Initial Commit

packages/api-stack/api/api-plugin-site/src/services/registry-augmentation.md

@@ -0,0 +1,58 @@
+# `services/registry-augmentation.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Augments the `ServiceRegistry` interface from `@suaveplan/api-plugin` so the three slots the site plugin owns — `siteService`, `domainResolver`, `domainResolverMiddleware` — resolve with full typing for any downstream consumer that imports the package root. Module augmentation is the canonical suaveplan pattern for cross-plugin typed services: it keeps `ctx.getService("siteService")` strongly typed without forcing every consumer to import a plugin-specific type and without leaking implementation details through the augmentation.
+
+The file also re-declares the host-side `app` and `db` slots (owned by `@suaveplan/api` and `@suaveplan/api-plugin-database` respectively) so the site plugin's `onInit` can resolve them with typing even when the consumer has not explicitly imported those upstream packages. TypeScript merges duplicate `declare module` blocks, so this is additive and safe.
+
+## Features
+
+- Declares `siteService: SiteService` on `ServiceRegistry`.
+- Declares `domainResolver: DomainResolverService` on `ServiceRegistry`.
+- Declares `domainResolverMiddleware: DomainResolverMiddleware` on `ServiceRegistry`.
+- Re-declares `app: OpenAPIHono` and `db: SurrealAdapter` for cumulative resolution.
+- Zero runtime cost — the entire module is a type-only `declare module` block.
+
+## Usage: Basic
+
+```ts
+import "@suaveplan/api-plugin-site"; // pulls in the augmentation transitively
+
+// In a downstream plugin onInit:
+const siteService = ctx.getService("siteService"); // typed: SiteService | undefined
+```
+
+## Usage: Advanced
+
+```ts
+import "@suaveplan/api-plugin-site/services/registry-augmentation";
+
+declare module "@suaveplan/api-plugin/service-registry" {
+    interface ServiceRegistry {
+        myAppCustomSlot: MyType;
+    }
+}
+
+const my = ctx.getService("myAppCustomSlot");
+```
+
+## API Reference
+
+No runtime exports. The file adds five slots to `ServiceRegistry`:
+
+- `siteService: SiteService`
+- `domainResolver: DomainResolverService`
+- `domainResolverMiddleware: DomainResolverMiddleware`
+- `app: OpenAPIHono`
+- `db: SurrealAdapter`
+
+## Implementation Notes
+
+- The augmentation is imported as a side-effect via the package barrel, so consumers automatically get the typed slots — no explicit `import "@suaveplan/api-plugin-site/services/registry-augmentation"` needed.
+- Re-declaring host slots is documented as safe in the suaveplan convention (see `@suaveplan/api-plugin-auth`'s registry-augmentation for prior art).
+- The `db` slot is typed as `SurrealAdapter` rather than `DatabaseAdapter` because the site service relies on typed CRUD (`create`, `update`) which only `SurrealAdapter` exposes. The service consumes a structural `SiteDb` port, but the `ServiceRegistry` slot is the live adapter type.

packages/api-stack/api/api-plugin-site/src/services/registry-augmentation.ts

@@ -0,0 +1,30 @@
+/**
+ * ServiceRegistry module augmentation — registers the three slots the
+ * site plugin owns on `@suaveplan/api-plugin/service-registry`'s
+ * `ServiceRegistry` interface so downstream plugins get fully-typed
+ * `ctx.getService("siteService")` lookups.
+ *
+ * Importing this module for its side effects (which the package root
+ * barrel does automatically) is sufficient.
+ *
+ * Host-side slots (`app`, `db`) are owned by `@suaveplan/api` /
+ * `@suaveplan/api-plugin-database`'s own augmentations. They are
+ * re-declared here as a cumulative augmentation so the site plugin's
+ * `onInit(ctx)` can resolve them with full typing even when the
+ * consumer has not explicitly imported the upstream plugin.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { SurrealAdapter } from "@suaveplan/surrealdb";
+import type { DomainResolverMiddleware } from "../middleware/domain-resolver.js";
+import type { DomainResolverService } from "../service/domain-resolver.js";
+import type { SiteService } from "../service/site.js";
+
+declare module "@suaveplan/api-plugin/service-registry" {
+    interface ServiceRegistry {
+        siteService: SiteService;
+        domainResolver: DomainResolverService;
+        domainResolverMiddleware: DomainResolverMiddleware;
+        app: OpenAPIHono;
+        db: SurrealAdapter;
+    }
+}