@suluk/platform 0.1.10 → 0.2.0

package/README.md

@@ -0,0 +1,77 @@
+# @suluk/platform
+
+Write **one manifest**; the generator plans the shadcn-registry adds, generates the wired Hono entry, merges each module's
+provision fragment, and emits the whole scaffold (package.json / tsconfig / wrangler.toml / .env.example / …). The
+higher-level surface over the [Suluk registry](https://github.com/MahmoodKhalil57/suluk) + `@suluk/provision`.
+
+There are two authoring surfaces. The **legacy** one (C051) is a single object and is supported forever. The **C053** one
+splits a platform into a reusable **system** and a swappable **brand**, adds typed opts, and lets services **compose**.
+
+## The C053 model
+
+### A service is a common interface
+
+`defineService<SO, BO>({ id, mount, provision?, deps?, env?, serviceOpts?, brandOpts?, reads?, compose? })` — the shape a
+community shadcn registry extends. The 19 core services are exported as typed consts (`authService`, `creditsService`, …).
+
+### System vs brand
+
+```ts
+import { defineSystem, defineBrand, definePlatform, authService, creditsService, emailService } from "@suluk/platform";
+import { analyticsService } from "@acme/suluk-analytics"; // a community service
+
+export const system = defineSystem({
+  registry: "MahmoodKhalil57/suluk",
+  services: [authService, creditsService, emailService, analyticsService],
+  globalServiceOpts: { ENVIRONMENT: "production", TRUSTED_ORIGINS: "https://app.example" },
+  serviceOpts: { auth: { mcp: { loginPage: "…", consentPage: "…", resource: "…", scopes: ["credits:read"] } } }, // typed by id
+  wire: [{ id: "signup-grant", from: "auth.onUserCreated", to: "credits.grantOnSignup", with: { amount: 100 } }],
+});
+
+export const brand = defineBrand({
+  name: "app",
+  globalBrandOpts: { BRAND_NAME: "App", BASE_URL: "https://app.example", EMAIL_FROM: "hi@app.example" },
+});
+
+export default definePlatform({ system, brand });
+```
+
+A **system** (services + serviceOpts + globalServiceOpts + wiring) is the reusable, publishable template. A **brand**
+(brandOpts + globalBrandOpts) is thin and swappable — two businesses run the same system with different brands; the generated
+entry *code* is identical, only `wrangler.toml [vars]` differ.
+
+### The 2×2 opts matrix
+
+|  | per-service | global |
+|---|---|---|
+| **service axis** (how it works) | `serviceOpts` → the entry (mount opts) | `globalServiceOpts` (a service `reads` the keys it needs) |
+| **brand axis** (identity) | `brandOpts` → `[vars]` | `globalBrandOpts` → `[vars]` |
+
+`serviceOpts` is typed per service id off the imported service objects (or `CoreServiceOptsMap` for a string id) — a wrong
+opt is a compile error.
+
+### Composition (`wire`)
+
+An edge binds a producer **port** to a consumer **capability**. It renders **into the producer's existing mount-opt field**
+(e.g. `auth.onUserCreated`), not a separate statement — so it reuses a real seam and the hook closure gets a real `env`.
+`resolveWiring` validates presence, port/capability existence, JSON-safe params, safe identifiers, and acyclicity; fan-out
+(several wires on one port) composes in declaration order. A community service participates by offering a capability (fills a
+core port) or exposing its own.
+
+## CLI
+
+```sh
+suluk-platform            # generate from ./platform.config.ts (legacy OR { system, brand })
+suluk-platform --config <path>
+suluk-platform migrate    # print the { system, brand } split of a legacy config (a starting point)
+```
+
+`migrate` is byte-faithful: `liftLegacy` → the same generated app as the legacy manifest.
+
+## Guarantees
+
+- **Byte-identity.** A legacy manifest — and any `{ system, brand }` with no wire — regenerates the exact bytes the C051
+  generator produced (pinned by a golden test over the real 18-service reference app).
+- **Fail closed.** A missing registry, a wrong-typed wire param, or a colliding wire import throws at generate time, not in
+  the shipped app.
+- **Own the wiring, npm the logic** (C052). A community extends services *and* composition without forking `@suluk` logic.

package/bin/platform.ts

@@ -3,24 +3,36 @@
  * The @suluk/platform CLI (C051) — load `platform.config.ts`, run `shadcn add` per service, write the wired entry +
  * provision.config. Then `bun install && suluk-provision apply`.
  *
- *   suluk-platform            generate from ./platform.config.ts
+ *   suluk-platform            generate from ./platform.config.ts (legacy manifest OR a { system, brand } platform)
  *   --config <path>           a different manifest
+ *   suluk-platform migrate    print the C053 { system, brand } split of a legacy platform.config.ts (a starting point)
  */
 import { resolve, dirname } from "node:path";
 import { writeFile, mkdir, readFile } from "node:fs/promises";
 import { generatePlatform } from "../src/generate";
-import type { PlatformManifest } from "../src/manifest";
+import { isPlatform, type PlatformManifest, type Platform } from "../src/manifest";
+import { liftLegacy } from "../src/resolve";
 
 const argv = process.argv.slice(2);
 const ci = argv.indexOf("--config");
 const configPath = ci >= 0 ? argv[ci + 1] : "platform.config.ts";
 
-const mod = (await import(resolve(process.cwd(), configPath))) as { default?: PlatformManifest };
+const mod = (await import(resolve(process.cwd(), configPath))) as { default?: PlatformManifest | Platform };
 if (!mod.default) {
   console.error(`✗ ${configPath} has no default export (a definePlatform(...) result)`);
   process.exit(2);
 }
 
+// `migrate` — show the { system, brand } split of a legacy manifest (does not rewrite the file; copy the output in).
+if (argv[0] === "migrate") {
+  const platform = isPlatform(mod.default) ? mod.default : liftLegacy(mod.default);
+  console.log("// C053 { system, brand } split — a starting point; move brand-specific values into defineBrand:\n");
+  console.log("export const system = defineSystem(" + JSON.stringify(platform.system, null, 2) + ");");
+  console.log("export const brand = defineBrand(" + JSON.stringify(platform.brand, null, 2) + ");");
+  console.log("export default definePlatform({ system, brand });");
+  process.exit(0);
+}
+
 const run = (cmd: string, args: string[]): Promise<void> =>
   new Promise((res, rej) => {
     const p = Bun.spawn([cmd, ...args], { stdout: "inherit", stderr: "inherit", cwd: process.cwd() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/platform",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "The platform generator (C051): write one `definePlatform` manifest → it plans the shadcn-registry adds, generates the wired Hono entry, and merges each module's provision fragment into a single provision.config. The manifest compiles to a shadcn-add list + a C047 provision.config; the generator runs the adds + `@suluk/provision`. Turns the Suluk backend registry into a one-command platform. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"
@@ -14,6 +14,7 @@
 "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
 "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
 "type": "module",
+"files": ["src", "bin", "README.md"],
 "main": "src/index.ts",
 "bin": {
 "suluk-platform": "bin/platform.ts"

package/src/catalog.ts

@@ -1,103 +1,26 @@
 /**
- * The catalog (C051) — the OSB "offerings": each service id → how to MOUNT its router into the Hono entry + where its
- * PROVISION fragment lives. This is the mapping the generator needs beyond `shadcn add` (which handles files/deps/order on
- * its own). Kept in sync with the registry's module set (C050). `app` is the base (no mount, no fragment).
+ * The catalog (C051) — each service id → how to MOUNT its router + where its PROVISION fragment lives. Since C053 this is a
+ * DERIVED VIEW of {@link CORE_SERVICES} (the common {@link Service} interface): `CATALOG[id] = toCatalogEntry(service)`, so
+ * the C051 generator reads the exact same shape it always did (the Phase-0 golden lock proves byte-identity) while the
+ * authoring surface is now the open Service model. Types + the core service set live in `service.ts`.
  */
+import { CORE_SERVICES, toCatalogEntry, type CatalogEntry, type EnvVar } from "./service";
 
-/** How a module contributes to the generated `src/index.ts`. */
-export type Mount =
-  | { kind: "base" } // the app skeleton — `createApp()`
-  | { kind: "middleware"; symbol: string; from: string } // e.g. `mountAuthRoutes(app)`
-  | { kind: "route"; path: string; symbol: string; from: string } // e.g. `app.route("/credits", creditsRoutes())`
-  | { kind: "dev" }; // dev/CI tooling (journeys, audit) — files only, no runtime mount, no provision fragment
+// re-export the shape types from their new home so `@suluk/platform`'s public surface + `plan.ts` are unchanged.
+export { CORE_SERVICES, toCatalogEntry, defineService } from "./service";
+export type { Mount, EnvVar, CatalogEntry, Service, Port, Capability, CompositionSurface, Schema } from "./service";
 
-/** An env var a module needs at runtime — drives the generated `.env.example` + the env-check preflight. Bindings (D1/KV)
- *  are NOT here (they live in wrangler.toml); only string env vars. */
-export interface EnvVar {
-  name: string;
-  /** the app WON'T work without it (the "minimum keys") — the env-check requires a non-empty value before it's happy. */
-  required?: boolean;
-  /** a credential (never commit) — shown commented in `.env.example` + flagged in the temp file. */
-  secret?: boolean;
-  /** a one-line hint shown as a comment in `.env.example`. */
-  hint?: string;
-}
+/** The offerings, derived from the core service set. `app` is the base (no mount symbol, no fragment). */
+export const CATALOG: Record<string, CatalogEntry> = Object.fromEntries(Object.entries(CORE_SERVICES).map(([id, s]) => [id, toCatalogEntry(s)]));
 
-export interface CatalogEntry {
-  /** how it mounts into the entry. */
-  mount: Mount;
-  /** the provision fragment export, if any (`InstanceSpec[]`). */
-  provision?: { symbol: string; from: string };
-  /** the module's npm deps BEYOND the always-present base (see BASE_DEPS) — its @suluk/* logic packages + any extras
-   *  (zod, better-auth). `shadcn add` also installs these; declaring them here lets the generator emit a complete,
-   *  from-the-manifest package.json (so platform.config.ts is the only hand-authored surface). Kept in sync with the
-   *  registry item's `dependencies`. */
-  deps?: string[];
-  /** the runtime env vars this module reads — the generator unions them into `.env.example` + the env-check preflight. */
-  env?: EnvVar[];
+// DRIFT GUARD: the derived view must expose exactly the core service ids (a dropped/renamed service would silently change
+// the generated app). Trivially true while CATALOG is derived, but asserted so a future hand-edit can't diverge unnoticed.
+{
+  const a = Object.keys(CORE_SERVICES).sort().join(",");
+  const b = Object.keys(CATALOG).sort().join(",");
+  if (a !== b) throw new Error(`platform: CATALOG drifted from CORE_SERVICES (${b} vs ${a})`);
 }
 
-export const CATALOG: Record<string, CatalogEntry> = {
-  app: { mount: { kind: "base" }, env: [{ name: "TRUSTED_ORIGINS", hint: "comma-separated browser origins allowed on /api/* (CORS)" }] },
-  auth: {
-    mount: { kind: "middleware", symbol: "mountAuthRoutes", from: "./auth" },
-    provision: { symbol: "authProvision", from: "./src/provision/auth" },
-    deps: ["better-auth", "@better-auth/api-key", "@better-auth/passkey", "@suluk/better-auth"],
-    env: [
-      { name: "BETTER_AUTH_SECRET", required: true, secret: true, hint: "session-signing key — `openssl rand -base64 32`" },
-      { name: "BETTER_AUTH_URL", hint: "your deployed origin, e.g. https://api.example.com" },
-      { name: "GOOGLE_CLIENT_ID", secret: true, hint: "optional — enables Google sign-in" },
-      { name: "GOOGLE_CLIENT_SECRET", secret: true, hint: "optional — pairs with GOOGLE_CLIENT_ID" },
-    ],
-  },
-  // the contract is a MIDDLEWARE mount: it installs the scope gate (enforceApiKeyScope) + GET /api/openapi.json. Place it
-  // after `auth` in the manifest so the gate runs after identity/apiKeyAuth set keyId/scopes. Derived + stateless.
-  contract: { mount: { kind: "middleware", symbol: "mountContract", from: "./routes/contract" }, deps: ["@suluk/hono", "zod"] },
-  // the API-as-MCP server + OAuth discovery + connections — a middleware mount (registers /api/mcp + /.well-known/*).
-  mcp: { mount: { kind: "middleware", symbol: "mountMcp", from: "./routes/mcp" }, provision: { symbol: "mcpProvision", from: "./src/provision/mcp" }, deps: ["@suluk/mcp", "better-auth"] },
-  // feature routes mount under /api/* — where the caller-resolution + cors + rate-limit middleware live (toolfactory parity).
-  credits: { mount: { kind: "route", path: "/api/credits", symbol: "creditsRoutes", from: "./routes/credits" }, provision: { symbol: "creditsProvision", from: "./src/provision/credits" }, deps: ["@suluk/credits"] },
-  keys: { mount: { kind: "route", path: "/api/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" }, deps: ["@suluk/keys"] },
-  billing: {
-    mount: { kind: "route", path: "/api/billing", symbol: "billingRoutes", from: "./routes/billing" },
-    provision: { symbol: "billingProvision", from: "./src/provision/billing" },
-    deps: ["@suluk/billing", "@suluk/payments", "@suluk/credits"],
-    env: [
-      { name: "STRIPE_SECRET_KEY", required: true, secret: true, hint: "your Stripe secret key" },
-      { name: "STRIPE_PUBLISHABLE_KEY", hint: "returned by GET /api/billing/payment-config" },
-    ],
-  },
-  cost: { mount: { kind: "route", path: "/api/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" }, deps: ["@suluk/cost"] },
-  erasure: { mount: { kind: "route", path: "/api/erasure", symbol: "erasureRoutes", from: "./routes/erasure" }, provision: { symbol: "erasureProvision", from: "./src/provision/erasure" }, deps: ["@suluk/better-auth"] },
-  email: {
-    mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" }, // stateless binding — no provision fragment (C052)
-    deps: ["@suluk/email"],
-    env: [
-      { name: "RESEND_API_KEY", secret: true, hint: "omit → the console provider (dev)" },
-      { name: "EMAIL_FROM", hint: "the from-address" },
-      { name: "BRAND_NAME", hint: "email template branding" },
-      { name: "BASE_URL", hint: "email link base" },
-      { name: "ENVIRONMENT", hint: '"production" → use Resend (else console)' },
-    ],
-  },
-  webhooks: {
-    mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" },
-    provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" },
-    deps: ["@suluk/payments"],
-    env: [{ name: "STRIPE_WEBHOOK_SECRET", required: true, secret: true, hint: "verifies inbound Stripe events (POST /api/webhooks/stripe)" }],
-  },
-  // cross-cutting MIDDLEWARE (apply globally via app.use, emitted before any route) — not routed resources.
-  "rate-limit": { mount: { kind: "middleware", symbol: "mountRateLimit", from: "./services/rate-limit" }, deps: ["@suluk/hono"] },
-  "rate-credit": { mount: { kind: "middleware", symbol: "mountRateCredit", from: "./services/rate-credit" } }, // credit-backed free-tier bucket (KV binding); base deps cover it
-  i18n: { mount: { kind: "middleware", symbol: "mountI18n", from: "./services/i18n" }, deps: ["@suluk/i18n"] },
-  reference: { mount: { kind: "route", path: "/api/reference", symbol: "referenceRoutes", from: "./routes/reference" }, deps: ["@suluk/reference"] }, // derived doc render — no provision
-  admin: { mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" }, deps: ["@suluk/credits"] }, // reads existing tables — no provision
-  logs: { mount: { kind: "route", path: "/api/logs", symbol: "logsRoutes", from: "./routes/logs" }, provision: { symbol: "logsProvision", from: "./src/provision/logs" } },
-  // dev/CI tooling — pulled in as files, no runtime mount, no provision fragment.
-  journeys: { mount: { kind: "dev" }, deps: ["@suluk/journeys"] },
-  audit: { mount: { kind: "dev" }, deps: ["@suluk/cockpit", "@suluk/harden"] },
-};
-
 /**
  * The always-present framework deps (every generated app: the Effect services + Hono entry + the merged provision.config
  * that imports mergeProvision from @suluk/platform + defineProvision from @suluk/provision). Union'd with each service's
@@ -134,10 +57,10 @@ export function resolveVersion(dep: string): string {
 
 /** The env vars the selected services need, de-duped by name (first declaration wins). Split with `.secret` into the
  *  `.env` secrets (the .env.temp lifecycle) vs the non-secret CONFIG (defined in platform.config.ts `vars` → wrangler `[vars]`). */
-export function collectEnv(services: string[]): EnvVar[] {
+export function collectEnv(services: string[], catalog: Record<string, { env?: EnvVar[] }> = CATALOG): EnvVar[] {
   const seen = new Set<string>();
   const out: EnvVar[] = [];
-  for (const s of services) for (const e of CATALOG[s]?.env ?? []) if (!seen.has(e.name)) (seen.add(e.name), out.push(e));
+  for (const s of services) for (const e of catalog[s]?.env ?? []) if (!seen.has(e.name)) (seen.add(e.name), out.push(e));
   return out;
 }
 

package/src/generate.ts

@@ -4,7 +4,8 @@
  * `run` + `write` are INJECTED (the CLI provides a real spawn + fs; a test provides recorders), so the orchestration is
  * testable. Stops short of `provision apply` — that's a live infra op the operator triggers.
  */
-import type { PlatformManifest } from "./manifest";
+import { type PlatformManifest, type Platform, isPlatform } from "./manifest";
+import { liftSystemBrand } from "./resolve";
 import { planPlatform, mergePackageJson, mergeWranglerToml, mergeGitignore, type PlatformPlan } from "./plan";
 
 export interface GenerateOptions {
@@ -25,9 +26,10 @@ export interface GenerateResult {
   written: string[];
 }
 
-export async function generatePlatform(manifest: PlatformManifest, opts: GenerateOptions): Promise<GenerateResult> {
+export async function generatePlatform(input: PlatformManifest | Platform, opts: GenerateOptions): Promise<GenerateResult> {
   const log = opts.log ?? (() => {});
   const read = opts.read ?? (async () => null);
+  const manifest = isPlatform(input) ? liftSystemBrand(input) : input;
   const plan = planPlatform(manifest);
   const written: string[] = [];
 

package/src/index.ts

@@ -4,7 +4,13 @@
  * provision.config. The higher-level surface over C047's provision.config + the C050 registry: `services: ["auth",
  * "credits", "billing"]` → a whole backend. The generated `provision.config.ts` imports `mergeProvision` from here.
  */
-export { definePlatform, type PlatformManifest } from "./manifest";
+export { definePlatform, defineSystem, defineBrand, isPlatform, type PlatformManifest, type SystemManifest, type BrandManifest, type Platform, type ServiceRef, type WireDecl } from "./manifest";
+export { resolveNodeOpts, liftSystemBrand, liftLegacy, serviceId } from "./resolve";
+export { resolveWiring, groupImports, assertJsonSafe, validateIdentifier, lit, type Wiring, type WireImport } from "./wire";
+// C053 — the open Service interface (the common shape community registries extend): defineService + the core service set.
+export { defineService, optsType, CORE_SERVICES, toCatalogEntry, type Service, type Port, type Capability, type CompositionSurface, type Schema, type McpOAuthOpts, type AuthServiceOpts } from "./service";
+// the core services as named, typed consts — import these into `defineSystem({ services: [...] })` for typed opts by id.
+export { appService, authService, contractService, mcpService, creditsService, keysService, billingService, costService, erasureService, emailService, webhooksService, rateLimitService, rateCreditService, i18nService, referenceService, adminService, logsService, journeysService, auditService } from "./service";
 export { CATALOG, orderServices, collectEnv, resolveVersion, BASE_DEPS, ECOSYSTEM_VERSIONS, DEV_DEPS, type CatalogEntry, type Mount, type EnvVar } from "./catalog";
 export { mergeProvision } from "./merge";
 export { planPlatform, buildPackageJson, mergePackageJson, mergeWranglerToml, mergeGitignore, type PlatformPlan } from "./plan";

package/src/manifest.ts

@@ -1,36 +1,119 @@
 /**
- * The platform manifest (C051) — the ONLY author-facing document. Name the registry + the services you want; the generator
- * compiles it to EVERYTHING: the shadcn-add list, the wired Hono entry, the merged provision.config, AND the scaffold config
- * (package.json with each module's deps — @suluk/* on "latest" so fixes flow via `bun update`, ecosystem pinned; plus
- * tsconfig.json + components.json). `platform.config.ts` is the single surface; regenerating keeps deps current + preserves
- * any deps/scripts you added. The higher-level surface over C047's provision.config: you say "auth, credits, billing" and
- * the catalog knows each one's component + provision fragment + npm deps.
+ * The platform manifest. TWO authoring surfaces:
+ *  - LEGACY {@link PlatformManifest} (C051) — `definePlatform({ name, registry, services, opts?, vars? })`. Kept FOREVER; the
+ *    C053 refactor keeps it a strict subset so an existing config regenerates byte-for-byte (the Phase-0 golden lock).
+ *  - C053 {@link SystemManifest} + {@link BrandManifest} — `definePlatform({ system, brand })`. A SYSTEM (services + their
+ *    serviceOpts + globalServiceOpts + composition) is the REUSABLE/PUBLISHABLE template; a BRAND (brandOpts + globalBrandOpts)
+ *    is thin + SWAPPABLE. `defineSystem` is GENERIC over the services TUPLE, so `serviceOpts` is typed per service id off the
+ *    imported service objects — no codegen. The new shape LOWERS into a legacy manifest (`liftSystemBrand`) and runs the same
+ *    generator.
  */
+import type { Service, Schema, CoreServiceOptsMap } from "./service";
+
+/** The C051 legacy manifest — still valid, still the byte-identity anchor. */
 export interface PlatformManifest {
   /** the app/repo name (used in the generated scaffold). */
   name: string;
   /** the shadcn registry, e.g. "MahmoodKhalil57/suluk". */
   registry: string;
-  /** the services to include, in mount order — resolved against the catalog. `app` + `auth` are implied if any is listed
-   *  but list them for clarity; the base + foundation always come first. */
+  /** the services to include, in mount order — resolved against the catalog. `app` + `auth` are implied if any is listed. */
   services: string[];
-  /**
-   * Per-service static OPTIONS passed to that service's mount in the generated entry (a plain JSON-serializable object).
-   * E.g. enable MCP OAuth: `opts: { auth: { mcp: { loginPage, consentPage, resource, scopes } } }` → the entry emits
-   * `mountAuthRoutes(app, {...})`. Only JSON-safe values (no functions/env-refs — edit the generated entry for those).
-   */
+  /** per-service static OPTIONS passed to that service's mount in the generated entry (JSON-serializable). */
   opts?: Record<string, Record<string, unknown>>;
-  /**
-   * NON-SECRET config values (`BASE_URL`, `EMAIL_FROM`, `TRUSTED_ORIGINS`, `ENVIRONMENT`, `STRIPE_PUBLISHABLE_KEY`, …) —
-   * defined HERE, in the committed manifest, and generated into `wrangler.toml` `[vars]`. SECRETS never go here; they live
-   * in `.env` (see the generated `.env.example` + the env-check preflight). Keyed by the env var name.
-   */
+  /** NON-SECRET config values → generated into `wrangler.toml` `[vars]`. SECRETS never go here (they live in `.env`). */
   vars?: Record<string, string>;
 }
 
-/** Validate + return the manifest (throws on an empty service list). */
-export function definePlatform(manifest: PlatformManifest): PlatformManifest {
-  if (!manifest.registry) throw new Error("platform: `registry` is required (e.g. \"MahmoodKhalil57/suluk\")");
-  if (!manifest.services?.length) throw new Error("platform: `services` must list at least one module");
-  return manifest;
+// ── C053: the open system/brand surface ──────────────────────────────────────────────────────────────────────────────
+
+/** A reference to a service: an imported {@link Service} object (fully typed) or a bare string id (resolved against the
+ *  catalog; opts typed as `unknown`). */
+export type ServiceRef = string | Service<any, any>;
+
+/** the service id of a ref (a Service object's literal `id`, or the string itself). */
+type IdOf<R> = R extends { id: infer Id extends string } ? Id : R extends string ? R : never;
+/** the serviceOpts value type a ref carries: from its `serviceOpts` marker (imported object); else the {@link
+ *  CoreServiceOptsMap} entry for a known core string id; else `unknown` for an unknown string; `{}` for a typed service
+ *  without opts. */
+type SoOf<R> = R extends { serviceOpts: Schema<infer SO> } ? SO : R extends keyof CoreServiceOptsMap ? CoreServiceOptsMap[R] : R extends string ? unknown : {};
+
+/**
+ * An inter-service composition EDGE (Phase 3). Declared here so a Phase-2 manifest's shape is forward-compatible; the
+ * resolver ignores `wire` until the Phase-3 engine lands. `from`/`to` are `"<service>.<port|capability>"`.
+ */
+export interface WireDecl {
+  id?: string;
+  from: string;
+  to: string;
+  with?: Record<string, unknown>;
+}
+
+/** A SYSTEM — the reusable, publishable template. Generic over the services tuple so `serviceOpts` is typed by service id. */
+export interface SystemManifest<T extends readonly ServiceRef[] = readonly ServiceRef[]> {
+  /** the single core registry, e.g. "MahmoodKhalil57/suluk". (Multi-registry alias map: `registries`, Phase 4.) */
+  registry?: string;
+  /** alias → registry map for multi-registry systems (Phase 4). `registries.core` is the default when `registry` is unset. */
+  registries?: Record<string, string>;
+  /** the services, in mount order — imported {@link Service} objects (typed) and/or string ids. */
+  services: T;
+  /** system-wide behaviour shared by services; a service receives the keys it names in `reads.globalService` (else inert). */
+  globalServiceOpts?: Record<string, unknown>;
+  /** per-service serviceOpts — TYPED by service id off the imported service objects. */
+  serviceOpts?: Partial<{ [K in T[number] as IdOf<K>]: SoOf<K> }>;
+  /** inter-service composition edges (Phase 3). */
+  wire?: WireDecl[];
+}
+
+/** A BRAND — thin, swappable per deployment. Carries the app identity + the brand-facing opts (→ `[vars]`). */
+export interface BrandManifest {
+  /** the deployment/app name (the wrangler + package name). Differs per brand of the same system. */
+  name: string;
+  /** brand identity shared by every service (BRAND_NAME, baseUrl, emailFrom, …) → `[vars]`. */
+  globalBrandOpts?: Record<string, unknown>;
+  /** per-service brand-facing opts → `[vars]`. */
+  brandOpts?: Record<string, Record<string, unknown>>;
+  /** brand-tunable EDGE params keyed by `wire.id` (Phase 3). */
+  wireBrandOpts?: Record<string, Record<string, unknown>>;
+}
+
+/** A bound platform = a system + a brand. */
+export interface Platform {
+  system: SystemManifest<any>;
+  brand: BrandManifest;
+}
+
+/** Author a SYSTEM. `const T` captures the services tuple so `serviceOpts` types resolve per service id. */
+export function defineSystem<const T extends readonly ServiceRef[]>(s: SystemManifest<T>): SystemManifest<T> {
+  if (!s.services?.length) throw new Error("defineSystem: `services` must list at least one service");
+  return s;
+}
+
+/** Author a BRAND. */
+export function defineBrand(b: BrandManifest): BrandManifest {
+  if (!b.name) throw new Error("defineBrand: `name` is required");
+  return b;
+}
+
+/**
+ * Validate + return a platform. Accepts BOTH the legacy {@link PlatformManifest} and the C053 `{ system, brand }` shape
+ * (discriminated on the `system` key). Overloaded so the return type matches the input surface.
+ */
+export function definePlatform(input: PlatformManifest): PlatformManifest;
+export function definePlatform(input: Platform): Platform;
+export function definePlatform(input: PlatformManifest | Platform): PlatformManifest | Platform {
+  if (isPlatform(input)) {
+    if (!input.system?.services?.length) throw new Error("platform: `system.services` must list at least one service");
+    if (!input.brand?.name) throw new Error("platform: `brand.name` is required");
+    // fail CLOSED on a missing registry (the legacy surface does), so every `adds` entry is `<registry>/<service>`.
+    if (!input.system.registry && !input.system.registries?.core) throw new Error('platform: `system.registry` (or `system.registries.core`) is required (e.g. "MahmoodKhalil57/suluk")');
+    return input;
+  }
+  if (!input.registry) throw new Error('platform: `registry` is required (e.g. "MahmoodKhalil57/suluk")');
+  if (!input.services?.length) throw new Error("platform: `services` must list at least one module");
+  return input;
+}
+
+/** Discriminate the C053 `{ system, brand }` shape from the legacy manifest. */
+export function isPlatform(input: PlatformManifest | Platform): input is Platform {
+  return typeof input === "object" && input !== null && "system" in input;
 }

package/src/plan.ts

@@ -3,8 +3,10 @@
  * generated `provision.config.ts` (importing + merging the fragments). No I/O; `generate` executes this. Testable to the
  * character.
  */
-import type { PlatformManifest } from "./manifest";
-import { CATALOG, orderServices, collectEnv, BASE_DEPS, DEV_DEPS, resolveVersion, type EnvVar } from "./catalog";
+import { type PlatformManifest, type Platform, isPlatform } from "./manifest";
+import { liftSystemBrand } from "./resolve";
+import { resolveWiring, groupImports, type Wiring } from "./wire";
+import { CATALOG, CORE_SERVICES, orderServices, collectEnv, BASE_DEPS, DEV_DEPS, resolveVersion, type EnvVar, type Service } from "./catalog";
 
 export interface PlatformPlan {
   services: string[];
@@ -31,17 +33,28 @@ export interface PlatformPlan {
   envCheck: string;
 }
 
-export function planPlatform(manifest: PlatformManifest): PlatformPlan {
+export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
+  // C053: a `{ system, brand }` platform lowers to the legacy manifest first, then the UNCHANGED lowering runs — so the
+  // legacy path is byte-for-byte identical and the new surface is sugar over it.
+  const manifest = isPlatform(input) ? liftSystemBrand(input) : input;
+  // the EFFECTIVE catalog = core services + any inline (community) Service objects a `{system,brand}` platform carries. It
+  // threads through EVERY emitter (mounts, provision, deps, env, wiring), so a community service contributes end-to-end. For
+  // the legacy path and an all-core `{system,brand}` it === CORE_SERVICES → the Phase-0 golden lock still holds byte-for-byte.
+  const catalog: Record<string, Service> = { ...CORE_SERVICES };
+  if (isPlatform(input)) for (const ref of input.system.services) if (typeof ref !== "string") catalog[ref.id] = ref;
   const services = orderServices(manifest.services);
-  const unknown = services.filter((s) => !CATALOG[s]);
+  const unknown = services.filter((s) => !catalog[s]);
   if (unknown.length) throw new Error(`platform: unknown service(s) [${unknown.join(", ")}] — not in the catalog`);
-  const env = collectEnv(services);
+  const env = collectEnv(services, catalog);
+  // resolve the wires (a `{system,brand}` platform may carry `wire`; a legacy manifest never does → no wiring → byte-identical).
+  const wiring = resolveWiring(services, isPlatform(input) ? input.system.wire ?? [] : [], catalog);
   return {
     services,
-    adds: services.map((s) => `${manifest.registry}/${s}`),
-    entry: buildEntry(services, manifest.opts),
-    provisionConfig: buildProvisionConfig(services),
-    packageJson: buildPackageJson(manifest.name, services),
+    // a service may override the registry it's pulled from (multi-registry); core services fall back to the system registry.
+    adds: services.map((s) => `${catalog[s].registry ?? manifest.registry}/${s}`),
+    entry: buildEntry(services, manifest.opts, wiring, catalog),
+    provisionConfig: buildProvisionConfig(services, catalog),
+    packageJson: buildPackageJson(manifest.name, services, catalog),
     tsconfig: buildTsconfig(),
     componentsJson: buildComponentsJson(),
     envExample: buildEnvExample(env),
@@ -193,9 +206,9 @@ process.exit(1);
 
 /** The framework baseline package.json — name from the manifest, the union of BASE + each service's deps (versions
  *  resolved: @suluk/* → "latest", ecosystem → pinned), + the toolchain devDeps + the regenerate/typecheck scripts. */
-export function buildPackageJson(name: string, services: string[]): string {
+export function buildPackageJson(name: string, services: string[], catalog: Record<string, Service> = CORE_SERVICES): string {
   const deps = new Set<string>(BASE_DEPS);
-  for (const s of services) for (const d of CATALOG[s]?.deps ?? []) deps.add(d);
+  for (const s of services) for (const d of catalog[s]?.deps ?? []) deps.add(d);
   const dependencies: Record<string, string> = {};
   for (const d of [...deps].sort()) dependencies[d] = resolveVersion(d);
   const pkg = {
@@ -281,33 +294,56 @@ function buildComponentsJson(): string {
   );
 }
 
-function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>): string {
+function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>, wiring?: Wiring, catalog: Record<string, Service> = CORE_SERVICES): string {
   const imports = ['import { createApp } from "./app";'];
   const middleware: string[] = [];
   const routes: string[] = [];
-  // per-service static options → a JSON literal passed to the mount (e.g. auth's mcp OAuth config). Empty ⇒ no 2nd arg.
+  const hooksByService = wiring?.hooksByService ?? {};
+  // every identifier bound at the top of the entry (base + each mount) → its module. A wire import that reuses a symbol from
+  // a DIFFERENT module would shadow/duplicate-declare it, so reject it (fail closed); a same-module re-import is deduped.
+  const bound = new Map<string, string>([["createApp", "./app"]]);
+  // a service's mount opts = its serviceOpts (JSON) + any wire-injected hook closures (raw code). With NO hooks, render is
+  // the EXACT legacy JSON.stringify path (byte-identical); with hooks, a mixed object literal (JSON values + code fields).
   const optOf = (s: string): string => {
-    const o = opts?.[s];
-    return o && Object.keys(o).length ? `, ${JSON.stringify(o)}` : "";
+    const so = opts?.[s];
+    const hooks = hooksByService[s];
+    if (!hooks || !Object.keys(hooks).length) {
+      return so && Object.keys(so).length ? `, ${JSON.stringify(so)}` : "";
+    }
+    const parts: string[] = [];
+    for (const [k, v] of Object.entries(so ?? {})) parts.push(`${JSON.stringify(k)}: ${JSON.stringify(v)}`);
+    for (const [k, code] of Object.entries(hooks)) parts.push(`${JSON.stringify(k)}: ${code}`);
+    return `, { ${parts.join(", ")} }`;
   };
   // TWO passes: ALL middleware mounts (app.use / handler) emit BEFORE any route mount, so a cross-cutting concern
   // (auth, rate-limit, i18n) applies to every route regardless of where it sits in the manifest.
   for (const s of services) {
-    const m = CATALOG[s].mount;
+    const m = catalog[s].mount;
     if (m.kind === "middleware") {
       imports.push(`import { ${m.symbol} } from "${m.from}";`);
+      bound.set(m.symbol, m.from);
       middleware.push(`${m.symbol}(app${optOf(s)});`);
     } else if (m.kind === "route") {
       imports.push(`import { ${m.symbol} } from "${m.from}";`);
+      bound.set(m.symbol, m.from);
       routes.push(`app.route("${m.path}", ${m.symbol}(${optOf(s).replace(/^, /, "")}));`);
     }
   }
+  // the wires' consumed capabilities need imports (e.g. Effect / Credits / CreditsLive / DbLive) — appended after the mounts,
+  // rejecting any that collides with a base/mount symbol from a different module (would break the generated entry).
+  const safeWireImports = (wiring?.imports ?? []).filter((imp) => {
+    const existing = bound.get(imp.symbol);
+    if (existing === undefined) return (bound.set(imp.symbol, imp.from), true);
+    if (existing !== imp.from) throw new Error(`wire: import symbol "${imp.symbol}" (from "${imp.from}") collides with an existing import from "${existing}" — rename the capability's export`);
+    return false; // same symbol + module already imported → dedup
+  });
+  for (const line of groupImports(safeWireImports)) imports.push(line);
   const body = ["const app = createApp();", ...middleware, ...routes];
   return `// AUTO-GENERATED by @suluk/platform from platform.config.ts — the wired Hono entry. Edit freely.\n${imports.join("\n")}\n\n${body.join("\n")}\n\nexport default app;\n`;
 }
 
-function buildProvisionConfig(services: string[]): string {
-  const frags = services.map((s) => CATALOG[s].provision).filter((p): p is NonNullable<typeof p> => !!p);
+function buildProvisionConfig(services: string[], catalog: Record<string, Service> = CORE_SERVICES): string {
+  const frags = services.map((s) => catalog[s].provision).filter((p): p is NonNullable<typeof p> => !!p);
   const imports = frags.map((f) => `import { ${f.symbol} } from "${f.from}";`);
   return [
     "// AUTO-GENERATED by @suluk/platform — the merged provision config. Run `suluk-provision apply`.",

package/src/resolve.ts

@@ -0,0 +1,111 @@
+/**
+ * C053 Phase 2 — resolve the four opts quadrants of a `{ system, brand }` platform and LOWER it into the legacy
+ * `PlatformManifest` the C051 generator already consumes. This is the byte-identity strategy: the new authoring surface is
+ * sugar that normalizes DOWN to `{ services, opts, vars }`, then the UNCHANGED `planPlatform` renders it — so a system/brand
+ * manifest equivalent to the legacy one produces the SAME bytes (the Phase-0 golden lock proves it), and the legacy path is
+ * untouched.
+ *
+ * The 2×2 (NODE opts):
+ *   - serviceOpts (per-service) + globalServiceOpts-keys-a-service `reads`  →  the ENTRY (a mount's opts object)  →  `opts`
+ *   - brandOpts (per-service) + globalBrandOpts + env-shaped globalServiceOpts →  wrangler `[vars]`/env             →  `vars`
+ * Composition (`wire`) is Phase 3 — ignored here.
+ */
+import type { PlatformManifest } from "./manifest";
+import type { Platform, SystemManifest, BrandManifest } from "./manifest";
+import { CORE_SERVICES } from "./service";
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const isScalar = (v: unknown): v is string | number | boolean => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+
+/** Deep-merge b over a (b wins), preserving a's key insertion order then b's new keys — so the emitted JSON is stable. */
+function deepMerge(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    const prev = out[k];
+    out[k] = isPlainObject(prev) && isPlainObject(v) ? deepMerge(prev, v) : v;
+  }
+  return out;
+}
+
+const pick = (o: Record<string, unknown>, keys: string[]): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const k of keys) if (k in o) out[k] = o[k];
+  return out;
+};
+
+/** A ServiceRef → its runtime id (a string ref is the id; a Service object contributes `.id`). */
+export function serviceId(ref: string | { id: string }): string {
+  return typeof ref === "string" ? ref : ref.id;
+}
+
+/**
+ * Resolve the node quadrants of `{ system, brand }` into the `{ services, opts, vars }` a legacy manifest carries:
+ *  - `opts[id]` (→ entry): the globalServiceOpts keys the service `reads`, deep-merged UNDER its per-service serviceOpts.
+ *    Empty results are omitted, so the map matches a hand-written legacy manifest (which only lists services that HAVE opts).
+ *  - `vars` (→ [vars]): every scalar value across globalServiceOpts + globalBrandOpts + per-service brandOpts. `buildWrangler`
+ *    only surfaces the ones that are declared service env vars, so extra keys are harmless.
+ */
+export function resolveNodeOpts(system: SystemManifest, brand: BrandManifest): { services: string[]; opts: Record<string, Record<string, unknown>>; vars: Record<string, string> } {
+  const services = system.services.map(serviceId);
+  const gso = (system.globalServiceOpts ?? {}) as Record<string, unknown>;
+
+  const opts: Record<string, Record<string, unknown>> = {};
+  for (const id of services) {
+    const reads = CORE_SERVICES[id]?.reads?.globalService ?? [];
+    const fromGlobal = pick(gso, reads);
+    const perService = (system.serviceOpts as Record<string, Record<string, unknown>> | undefined)?.[id] ?? {};
+    const eff = deepMerge(fromGlobal, perService);
+    if (Object.keys(eff).length) opts[id] = eff;
+  }
+
+  const vars: Record<string, string> = {};
+  const foldScalars = (o: Record<string, unknown> | undefined) => {
+    for (const [k, v] of Object.entries(o ?? {})) if (isScalar(v)) vars[k] = String(v);
+  };
+  foldScalars(gso);
+  foldScalars(brand.globalBrandOpts as Record<string, unknown> | undefined);
+  for (const perBrand of Object.values(brand.brandOpts ?? {})) foldScalars(perBrand as Record<string, unknown>);
+
+  return { services, opts, vars };
+}
+
+/** env-shaped globalServiceOpts (system behaviour delivered as a runtime env var) — the rest of `vars` is brand identity. */
+const SYSTEM_VAR_NAMES = new Set(["TRUSTED_ORIGINS", "ENVIRONMENT"]);
+
+/**
+ * The MIGRATE direction — a legacy {@link PlatformManifest} → the C053 `{ system, brand }` split (the inverse of
+ * {@link liftSystemBrand}). `opts` → per-service serviceOpts; `vars` split into globalServiceOpts (system-shaped) vs
+ * globalBrandOpts (identity). Round-trips byte-for-byte: `liftSystemBrand(liftLegacy(m))` generates the same app as `m`.
+ */
+export function liftLegacy(m: PlatformManifest): Platform {
+  const globalServiceOpts: Record<string, string> = {};
+  const globalBrandOpts: Record<string, string> = {};
+  for (const [k, v] of Object.entries(m.vars ?? {})) (SYSTEM_VAR_NAMES.has(k) ? globalServiceOpts : globalBrandOpts)[k] = v;
+  return {
+    system: {
+      registry: m.registry,
+      services: m.services,
+      ...(Object.keys(globalServiceOpts).length ? { globalServiceOpts } : {}),
+      ...(m.opts && Object.keys(m.opts).length ? { serviceOpts: m.opts } : {}),
+    },
+    brand: {
+      name: m.name,
+      ...(Object.keys(globalBrandOpts).length ? { globalBrandOpts } : {}),
+    },
+  };
+}
+
+/** Lower a `{ system, brand }` platform to the legacy {@link PlatformManifest} the C051 generator renders. */
+export function liftSystemBrand(p: Platform): PlatformManifest {
+  const { services, opts, vars } = resolveNodeOpts(p.system, p.brand);
+  const registry = p.system.registry ?? p.system.registries?.core;
+  // backstop (definePlatform also guards): never lower to an empty registry → malformed "/service" adds.
+  if (!registry) throw new Error('platform: `system.registry` (or `system.registries.core`) is required (e.g. "MahmoodKhalil57/suluk")');
+  return {
+    name: p.brand.name,
+    registry,
+    services,
+    ...(Object.keys(opts).length ? { opts } : {}),
+    ...(Object.keys(vars).length ? { vars } : {}),
+  };
+}

package/src/service.ts

@@ -0,0 +1,265 @@
+/**
+ * The common Service interface (C053) — "define what each core service is" so community shadcn registries can extend the
+ * platform with the SAME shape. A service = how it MOUNTS + its PROVISION fragment + npm DEPS + runtime ENV (all present
+ * since C051), PLUS (C053) the typed opts surfaces and the COMPOSITION surface (ports it EXPOSES / capabilities it OFFERS).
+ *
+ * PHASE 1 (this file) lands the interface + the 19 core services expressed through it (`CORE_SERVICES`); `catalog.ts`
+ * DERIVES the old `CATALOG` view from it (`toCatalogEntry`) so `planPlatform` is byte-for-byte unchanged. The typed opts
+ * schemas (`serviceOpts`/`brandOpts`) and the composition ENGINE are declared here but not yet consumed — Phase 2 wires the
+ * opts, Phase 3 the composition. Every phase runs against the Phase-0 golden lock.
+ */
+
+/** How a module contributes to the generated `src/index.ts`. (Unchanged from C051.) */
+export type Mount =
+  | { kind: "base" } // the app skeleton — `createApp()`
+  | { kind: "middleware"; symbol: string; from: string } // e.g. `mountAuthRoutes(app)`
+  | { kind: "route"; path: string; symbol: string; from: string } // e.g. `app.route("/api/credits", creditsRoutes())`
+  | { kind: "dev" }; // dev/CI tooling (journeys, audit) — files only, no runtime mount, no provision fragment
+
+/** An env var a module needs at runtime — drives the generated `.env.example` + the env-check preflight. (Unchanged.) */
+export interface EnvVar {
+  name: string;
+  /** the app WON'T work without it (the "minimum keys") — the env-check requires a non-empty value before it's happy. */
+  required?: boolean;
+  /** a credential (never commit) — shown commented in `.env.example` + flagged in the temp file. */
+  secret?: boolean;
+  /** a one-line hint shown as a comment in `.env.example`. */
+  hint?: string;
+}
+
+/** The old catalog record — now a DERIVED VIEW of a {@link Service} (see {@link toCatalogEntry}); kept so `planPlatform`
+ *  and the C051 helpers read the same shape they always did. */
+export interface CatalogEntry {
+  mount: Mount;
+  provision?: { symbol: string; from: string };
+  deps?: string[];
+  env?: EnvVar[];
+}
+
+/**
+ * Standard-Schema v1 shape (zod v4 implements it). Declared LOCALLY so the Service interface can carry the typed-opts slots
+ * with NO runtime validator dependency in Phase 1; Phase 2 replaces this with `@standard-schema/spec` and populates
+ * `serviceOpts`/`brandOpts` with real zod schemas (zod as a peerDependency). `Out` carries the inferred value type.
+ */
+export interface Schema<Out = unknown> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => { value: Out } | { issues: readonly unknown[] } | Promise<unknown>;
+  };
+}
+
+/**
+ * A typed PORT a service EXPOSES: a named hook others fill. `hookOptKey` is the mount-opt field a bound edge renders INTO
+ * (e.g. auth's `onUserCreated`), so an edge never emits a separate post-route statement — it composes into the producer's
+ * own mount call. `render` wraps the consumer expressions for this hook's real signature. (Consumed in Phase 3.)
+ */
+export interface Port<P = unknown> {
+  readonly kind: "port";
+  readonly param?: Schema<P>;
+  readonly hookOptKey: string;
+  readonly render: (consumerExprs: string[]) => string;
+}
+
+/**
+ * A typed CAPABILITY a service OFFERS to fill a port. `build` produces the consumer EXPRESSION rendered into the producer's
+ * hook closure — it may reference the closure's fixed params `userId` and `env` (the seam threads env), plus the symbols it
+ * declares in `imports` (all TRUSTED — from the service definition, never manifest free text). `with` is the wire's
+ * schema-validated params (JSON data only). (Consumed in Phase 3.)
+ */
+export interface Capability<A = unknown> {
+  readonly kind: "capability";
+  readonly param?: Schema<A>;
+  readonly symbol: string; // exported name in the service's owned code (import-checked)
+  readonly from: string;
+  readonly imports?: { symbol: string; from: string }[]; // what the built expr references → unioned into the entry imports
+  readonly build: (ctx: { with: Record<string, unknown> }) => string;
+}
+
+/** What a service brings to the composition graph: the ports it exposes + the capabilities it offers. */
+export interface CompositionSurface {
+  exposes?: Record<string, Port>;
+  offers?: Record<string, Capability>;
+}
+
+/**
+ * THE COMMON INTERFACE. `SO` = the service-opts value type, `BO` = the brand-opts value type (both Phase 2). A core service
+ * and a community service instantiate the exact same shape via {@link defineService}.
+ */
+export interface Service<SO = {}, BO = {}> {
+  readonly id: string; // "auth" | "acme.analytics"
+  readonly registry?: string; // owning registry (multi-registry, Phase 4); default = the manifest's core alias
+  readonly mount: Mount;
+  readonly provision?: { symbol: string; from: string };
+  readonly deps?: string[];
+  readonly env?: EnvVar[];
+  readonly serviceOpts?: Schema<SO>; // how THIS service works       → the ENTRY (mount 2nd arg)      [Phase 2]
+  readonly brandOpts?: Schema<BO>; // THIS service's brand-facing   → [vars]/env by default            [Phase 2]
+  readonly reads?: { globalService?: string[]; globalBrand?: string[] }; // which globals it consumes  [Phase 2]
+  readonly compose?: CompositionSurface; // ports it exposes + capabilities it offers                   [Phase 3]
+}
+
+/**
+ * Author a service. `const S` PRESERVES the literal `id` + the precise `serviceOpts`/`brandOpts` marker types, so the
+ * manifest (`defineSystem`) can key typed opts by service id off the imported service objects — no codegen. Validates the id.
+ */
+export function defineService<const S extends Service<any, any>>(s: S): S {
+  if (!s.id) throw new Error("defineService: `id` is required");
+  return s;
+}
+
+/**
+ * A TYPED opts marker for a service's `serviceOpts`/`brandOpts`. Phase 2 uses it purely for TYPES — the manifest author
+ * gets autocomplete + type-checking on that service's opts. It carries the value type `T` in the `Schema<T>` slot; Phase 3
+ * swaps it for a runtime-validating zod schema of the SAME type (a drop-in — the field type is `Schema<T>` either way).
+ */
+export function optsType<T>(): Schema<T> {
+  return { "~standard": { version: 1, vendor: "suluk", validate: (value) => ({ value: value as T }) } };
+}
+
+/** The MCP OAuth authorization-server config (auth's `serviceOpts.mcp`) — the frontend OAuth pages + resource + scope set. */
+export interface McpOAuthOpts {
+  loginPage: string;
+  consentPage: string;
+  resource: string;
+  scopes: string[];
+}
+/** auth's serviceOpts: optionally activate the MCP OAuth server (Better Auth `mcp()` plugin). */
+export interface AuthServiceOpts {
+  mcp?: McpOAuthOpts;
+}
+
+/**
+ * Core service id → its serviceOpts value type. Lets a STRING-referenced core service (e.g. `services: ["auth", …]`) get the
+ * SAME typed serviceOpts as the imported-object form (`services: [authService, …]`), instead of collapsing to `unknown`.
+ * Extend as core services gain typed opts.
+ */
+export interface CoreServiceOptsMap {
+  auth: AuthServiceOpts;
+}
+
+/** Project a Service onto the legacy {@link CatalogEntry} shape the C051 generator reads. Field-for-field — so a derived
+ *  CATALOG is behaviourally identical to the old hardcoded one (proven by the Phase-0 golden lock). */
+export function toCatalogEntry(s: Service): CatalogEntry {
+  return { mount: s.mount, provision: s.provision, deps: s.deps, env: s.env };
+}
+
+/**
+ * The 19 CORE services, expressed through the common interface (the dogfood). Ported field-for-field from the C051 CATALOG;
+ * `auth` and `credits` additionally declare their composition surface (the `auth.onUserCreated` port + the
+ * `credits.grantOnSignup` capability) — inert until the Phase-3 engine consumes them, and the render/build templates are
+ * PROVISIONAL (Phase 3 pins them against the real auth seam signature, see ADR C053 open question #1).
+ */
+// Each core service is exported as a NAMED, precisely-typed const so a `defineSystem` author can import it and get typed
+// serviceOpts keyed by id. Ported field-for-field from the C051 CATALOG (byte-identity via the Phase-0 golden lock).
+
+export const appService = defineService({ id: "app", mount: { kind: "base" }, env: [{ name: "TRUSTED_ORIGINS", hint: "comma-separated browser origins allowed on /api/* (CORS)" }] });
+
+export const authService = defineService({
+  id: "auth",
+  mount: { kind: "middleware", symbol: "mountAuthRoutes", from: "./auth" },
+  provision: { symbol: "authProvision", from: "./src/provision/auth" },
+  deps: ["better-auth", "@better-auth/api-key", "@better-auth/passkey", "@suluk/better-auth"],
+  env: [
+    { name: "BETTER_AUTH_SECRET", required: true, secret: true, hint: "session-signing key — `openssl rand -base64 32`" },
+    { name: "BETTER_AUTH_URL", hint: "your deployed origin, e.g. https://api.example.com" },
+    { name: "GOOGLE_CLIENT_ID", secret: true, hint: "optional — enables Google sign-in" },
+    { name: "GOOGLE_CLIENT_SECRET", secret: true, hint: "optional — pairs with GOOGLE_CLIENT_ID" },
+  ],
+  serviceOpts: optsType<AuthServiceOpts>(), // typed: `serviceOpts.auth.mcp` autocompletes + type-checks
+  compose: {
+    exposes: {
+      // the signup hook. The seam is PINNED to (userId, env) — registry/auth/auth.ts widened to pass the Worker env into the
+      // databaseHook callback (env is already in buildAuth's closure), so a consumer expr can build its Effect layers.
+      onUserCreated: { kind: "port", hookOptKey: "onUserCreated", render: (exprs) => `async (userId, env) => { ${exprs.join("; ")}; }` },
+    },
+  },
+});
+
+export const contractService = defineService({ id: "contract", mount: { kind: "middleware", symbol: "mountContract", from: "./routes/contract" }, deps: ["@suluk/hono", "zod"] });
+export const mcpService = defineService({ id: "mcp", mount: { kind: "middleware", symbol: "mountMcp", from: "./routes/mcp" }, provision: { symbol: "mcpProvision", from: "./src/provision/mcp" }, deps: ["@suluk/mcp", "better-auth"] });
+
+export const creditsService = defineService({
+  id: "credits",
+  mount: { kind: "route", path: "/api/credits", symbol: "creditsRoutes", from: "./routes/credits" },
+  provision: { symbol: "creditsProvision", from: "./src/provision/credits" },
+  deps: ["@suluk/credits"],
+  compose: {
+    offers: {
+      // grant N credits on signup, idempotent per user (the real Credits Effect service + grantOnce, over the request DB).
+      // References the closure's `userId` + `env`; provides CreditsLive + DbLive(env) and runs the program.
+      grantOnSignup: {
+        kind: "capability",
+        symbol: "Credits",
+        from: "./services/credits",
+        imports: [
+          { symbol: "Effect", from: "effect" },
+          { symbol: "Credits", from: "./services/credits" },
+          { symbol: "CreditsLive", from: "./services/credits" },
+          { symbol: "DbLive", from: "./app" },
+        ],
+        build: ({ with: w }) => {
+          // fail LOUDLY at generate time on a wrong-typed money param — never render an invalid literal into the app.
+          if (w.amount !== undefined && typeof w.amount !== "number") throw new Error(`credits.grantOnSignup: 'amount' must be a number (got ${typeof w.amount})`);
+          const amount = (w.amount as number | undefined) ?? 100;
+          return `await Effect.runPromise(Effect.flatMap(Credits, (s) => s.grant(userId, ${JSON.stringify(amount)}, "signup:" + userId, "signup grant")).pipe(Effect.provide(CreditsLive), Effect.provide(DbLive(env))))`;
+        },
+      },
+    },
+  },
+});
+
+export const keysService = defineService({ id: "keys", mount: { kind: "route", path: "/api/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" }, deps: ["@suluk/keys"] });
+
+export const billingService = defineService({
+  id: "billing",
+  mount: { kind: "route", path: "/api/billing", symbol: "billingRoutes", from: "./routes/billing" },
+  provision: { symbol: "billingProvision", from: "./src/provision/billing" },
+  deps: ["@suluk/billing", "@suluk/payments", "@suluk/credits"],
+  env: [
+    { name: "STRIPE_SECRET_KEY", required: true, secret: true, hint: "your Stripe secret key" },
+    { name: "STRIPE_PUBLISHABLE_KEY", hint: "returned by GET /api/billing/payment-config" },
+  ],
+});
+
+export const costService = defineService({ id: "cost", mount: { kind: "route", path: "/api/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" }, deps: ["@suluk/cost"] });
+export const erasureService = defineService({ id: "erasure", mount: { kind: "route", path: "/api/erasure", symbol: "erasureRoutes", from: "./routes/erasure" }, provision: { symbol: "erasureProvision", from: "./src/provision/erasure" }, deps: ["@suluk/better-auth"] });
+
+export const emailService = defineService({
+  id: "email",
+  mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" }, // stateless binding — no provision fragment (C052)
+  deps: ["@suluk/email"],
+  env: [
+    { name: "RESEND_API_KEY", secret: true, hint: "omit → the console provider (dev)" },
+    { name: "EMAIL_FROM", hint: "the from-address" },
+    { name: "BRAND_NAME", hint: "email template branding" },
+    { name: "BASE_URL", hint: "email link base" },
+    { name: "ENVIRONMENT", hint: '"production" → use Resend (else console)' },
+  ],
+});
+
+export const webhooksService = defineService({
+  id: "webhooks",
+  mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" },
+  provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" },
+  deps: ["@suluk/payments"],
+  env: [{ name: "STRIPE_WEBHOOK_SECRET", required: true, secret: true, hint: "verifies inbound Stripe events (POST /api/webhooks/stripe)" }],
+});
+
+export const rateLimitService = defineService({ id: "rate-limit", mount: { kind: "middleware", symbol: "mountRateLimit", from: "./services/rate-limit" }, deps: ["@suluk/hono"] });
+export const rateCreditService = defineService({ id: "rate-credit", mount: { kind: "middleware", symbol: "mountRateCredit", from: "./services/rate-credit" } }); // credit-backed free-tier bucket (KV binding)
+export const i18nService = defineService({ id: "i18n", mount: { kind: "middleware", symbol: "mountI18n", from: "./services/i18n" }, deps: ["@suluk/i18n"] });
+export const referenceService = defineService({ id: "reference", mount: { kind: "route", path: "/api/reference", symbol: "referenceRoutes", from: "./routes/reference" }, deps: ["@suluk/reference"] }); // derived — no provision
+export const adminService = defineService({ id: "admin", mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" }, deps: ["@suluk/credits"] }); // reads existing tables — no provision
+export const logsService = defineService({ id: "logs", mount: { kind: "route", path: "/api/logs", symbol: "logsRoutes", from: "./routes/logs" }, provision: { symbol: "logsProvision", from: "./src/provision/logs" } });
+export const journeysService = defineService({ id: "journeys", mount: { kind: "dev" }, deps: ["@suluk/journeys"] });
+export const auditService = defineService({ id: "audit", mount: { kind: "dev" }, deps: ["@suluk/cockpit", "@suluk/harden"] });
+
+/** The 19 core services, in the C051 catalog order. */
+const CORE_SERVICE_LIST: Service[] = [
+  appService, authService, contractService, mcpService, creditsService, keysService, billingService, costService, erasureService, emailService,
+  webhooksService, rateLimitService, rateCreditService, i18nService, referenceService, adminService, logsService, journeysService, auditService,
+];
+
+/** The core services keyed by id (key === `service.id`, guaranteed by construction). */
+export const CORE_SERVICES: Record<string, Service> = Object.fromEntries(CORE_SERVICE_LIST.map((s) => [s.id, s]));

package/test/plan.test.ts

@@ -1,254 +0,0 @@
-import { test, expect, describe } from "bun:test";
-import { definePlatform, planPlatform, mergeProvision, generatePlatform, buildPackageJson, mergePackageJson, mergeWranglerToml, mergeGitignore } from "../src/index";
-import type { InstanceSpec } from "@suluk/provision";
-
-/** C051 — the platform generator: manifest → plan (adds + wired entry + merged provision), the provision merge, and the
- *  generate orchestration (with recorders). */
-const manifest = definePlatform({ name: "autotoolfactory", registry: "acme/reg", services: ["auth", "credits", "keys", "billing", "logs"] });
-
-describe("planPlatform — manifest → shadcn adds + entry + provision.config", () => {
-  const plan = planPlatform(manifest);
-
-  test("orders app + auth first, then the rest; adds are registry refs", () => {
-    expect(plan.services).toEqual(["app", "auth", "credits", "keys", "billing", "logs"]);
-    expect(plan.adds).toEqual(["acme/reg/app", "acme/reg/auth", "acme/reg/credits", "acme/reg/keys", "acme/reg/billing", "acme/reg/logs"]);
-  });
-
-  test("the generated entry wires the base + auth middleware + each route", () => {
-    expect(plan.entry).toContain('import { createApp } from "./app";');
-    expect(plan.entry).toContain("const app = createApp();");
-    expect(plan.entry).toContain('import { mountAuthRoutes } from "./auth";');
-    expect(plan.entry).toContain("mountAuthRoutes(app);");
-    expect(plan.entry).toContain('import { creditsRoutes } from "./routes/credits";');
-    expect(plan.entry).toContain('app.route("/api/credits", creditsRoutes());');
-    expect(plan.entry).toContain('app.route("/api/billing", billingRoutes());');
-    expect(plan.entry).toContain("export default app;");
-  });
-
-  test("the generated provision.config imports each fragment + merges them", () => {
-    expect(plan.provisionConfig).toContain('import { defineProvision } from "@suluk/provision";');
-    expect(plan.provisionConfig).toContain('import { mergeProvision } from "@suluk/platform";');
-    expect(plan.provisionConfig).toContain('import { authProvision } from "./src/provision/auth";');
-    expect(plan.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision, keysProvision, billingProvision, logsProvision])");
-  });
-
-  test("an unknown service throws", () => {
-    expect(() => planPlatform({ name: "x", registry: "r", services: ["nope"] })).toThrow(/unknown service/);
-  });
-
-  test("per-service opts are passed to the mount (e.g. auth mcp OAuth config)", () => {
-    const p = planPlatform(definePlatform({ name: "o", registry: "acme/reg", services: ["auth", "credits"], opts: { auth: { mcp: { resource: "https://api.x", scopes: ["credits:read"] } } } }));
-    expect(p.entry).toContain('mountAuthRoutes(app, {"mcp":{"resource":"https://api.x","scopes":["credits:read"]}});');
-    // a service with no opts still gets the bare call.
-    expect(p.entry).toContain('app.route("/api/credits", creditsRoutes());');
-  });
-});
-
-describe("cost (route + provision) + dev modules (journeys/audit — files only)", () => {
-  const plan = planPlatform(definePlatform({ name: "full", registry: "acme/reg", services: ["auth", "credits", "cost", "logs", "journeys", "audit"] }));
-
-  test("cost mounts a /cost route and contributes a provision fragment", () => {
-    expect(plan.entry).toContain('import { costRoutes } from "./routes/cost";');
-    expect(plan.entry).toContain('app.route("/api/cost", costRoutes());');
-    expect(plan.provisionConfig).toContain('import { costProvision } from "./src/provision/cost";');
-    expect(plan.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision, costProvision, logsProvision])");
-  });
-
-  test("erasure mounts an /erasure route and contributes a provision fragment", () => {
-    const p = planPlatform(definePlatform({ name: "e", registry: "acme/reg", services: ["auth", "erasure"] }));
-    expect(p.entry).toContain('import { erasureRoutes } from "./routes/erasure";');
-    expect(p.entry).toContain('app.route("/api/erasure", erasureRoutes());');
-    expect(p.provisionConfig).toContain('import { erasureProvision } from "./src/provision/erasure";');
-    expect(p.provisionConfig).toContain("mergeProvision([authProvision, erasureProvision])");
-  });
-
-  test("email mounts an /email route but contributes NO provision fragment (stateless binding)", () => {
-    const p = planPlatform(definePlatform({ name: "m", registry: "acme/reg", services: ["auth", "email", "credits"] }));
-    expect(p.entry).toContain('import { emailRoutes } from "./routes/email";');
-    expect(p.entry).toContain('app.route("/api/email", emailRoutes());');
-    // email has no provision fragment, so the merge is just auth + credits.
-    expect(p.provisionConfig).not.toContain("emailProvision");
-    expect(p.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision])");
-  });
-
-  test("webhooks mounts a /webhooks route and contributes a provision fragment", () => {
-    const p = planPlatform(definePlatform({ name: "w", registry: "acme/reg", services: ["auth", "webhooks"] }));
-    expect(p.entry).toContain('import { webhooksRoutes } from "./routes/webhooks";');
-    expect(p.entry).toContain('app.route("/api/webhooks", webhooksRoutes());');
-    expect(p.provisionConfig).toContain("mergeProvision([authProvision, webhooksProvision])");
-  });
-
-  test("rate-limit + i18n are MIDDLEWARE mounts (app.use, no route, no provision) emitted BEFORE routes", () => {
-    const p = planPlatform(definePlatform({ name: "mw", registry: "acme/reg", services: ["auth", "credits", "rate-limit", "i18n"] }));
-    expect(p.entry).toContain("mountRateLimit(app);");
-    expect(p.entry).toContain("mountI18n(app);");
-    // no route, no provision for either.
-    expect(p.entry).not.toContain('app.route("/rate-limit"');
-    expect(p.provisionConfig).toContain("mergeProvision([authProvision, creditsProvision])");
-    // two-pass ordering: every middleware mount precedes every route mount, so global middleware applies to all routes.
-    const lastMw = Math.max(p.entry.indexOf("mountRateLimit(app);"), p.entry.indexOf("mountI18n(app);"), p.entry.indexOf("mountAuthRoutes(app);"));
-    expect(lastMw).toBeLessThan(p.entry.indexOf('app.route("/api/credits"'));
-  });
-
-  test("contract is a MIDDLEWARE mount (scope gate + /api/openapi.json), emitted before routes; feature routes under /api/*", () => {
-    const p = planPlatform(definePlatform({ name: "c", registry: "acme/reg", services: ["auth", "contract", "credits"] }));
-    expect(p.entry).toContain('import { mountContract } from "./routes/contract";');
-    expect(p.entry).toContain("mountContract(app);");
-    expect(p.entry).toContain('app.route("/api/credits", creditsRoutes());'); // toolfactory-parity /api/* prefix
-    // the gate (middleware) is emitted before any route.
-    expect(p.entry.indexOf("mountContract(app);")).toBeLessThan(p.entry.indexOf('app.route("/api/credits"'));
-    expect(p.provisionConfig).not.toContain("contractProvision");
-  });
-
-  test("reference + admin mount /api routes with NO provision (derived / reads existing tables)", () => {
-    const p = planPlatform(definePlatform({ name: "ra", registry: "acme/reg", services: ["auth", "contract", "reference", "admin", "credits"] }));
-    expect(p.entry).toContain('app.route("/api/reference", referenceRoutes());');
-    expect(p.entry).toContain('app.route("/api/admin", adminRoutes());');
-    expect(p.provisionConfig).not.toContain("referenceProvision");
-    expect(p.provisionConfig).not.toContain("adminProvision");
-  });
-
-  test("mcp is a middleware mount (server + discovery + connections) with a provision fragment", () => {
-    const p = planPlatform(definePlatform({ name: "m", registry: "acme/reg", services: ["auth", "contract", "mcp", "credits"] }));
-    expect(p.entry).toContain('import { mountMcp } from "./routes/mcp";');
-    expect(p.entry).toContain("mountMcp(app);");
-    expect(p.entry).not.toContain('app.route("/api/mcp"'); // it's a mount, not a route
-    expect(p.provisionConfig).toContain("mcpProvision");
-  });
-
-  test("rate-credit is a middleware mount (KV binding) with NO provision fragment", () => {
-    const p = planPlatform(definePlatform({ name: "rc", registry: "acme/reg", services: ["auth", "rate-credit", "credits"] }));
-    expect(p.entry).toContain("mountRateCredit(app);");
-    expect(p.provisionConfig).not.toContain("rateCreditProvision");
-  });
-
-  test("dev modules add shadcn refs but NO entry mount and NO provision fragment", () => {
-    expect(plan.adds).toContain("acme/reg/journeys");
-    expect(plan.adds).toContain("acme/reg/audit");
-    expect(plan.entry).not.toContain("journeys");
-    expect(plan.entry).not.toContain("audit");
-    expect(plan.provisionConfig).not.toContain("journeys");
-    expect(plan.provisionConfig).not.toContain("audit");
-  });
-});
-
-describe("mergeProvision — combine same-ref instances, union migrations in order", () => {
-  test("two `db` fragments merge into one with both migrations (fragment order preserved)", () => {
-    const auth: InstanceSpec[] = [{ ref: "db", service: "cloudflare-d1", name: "app-db", params: { migrations: [{ name: "0000_auth", sql: "A" }] }, bind: { database_id: "ID" }, protected: true }];
-    const credits: InstanceSpec[] = [{ ref: "db", service: "cloudflare-d1", name: "app-db", params: { migrations: [{ name: "0001_credits", sql: "C" }] }, bind: { database_id: "ID" }, protected: true }];
-    const merged = mergeProvision([auth, credits]);
-    expect(merged.length).toBe(1);
-    expect(merged[0].ref).toBe("db");
-    expect((merged[0].params!.migrations as { name: string }[]).map((m) => m.name)).toEqual(["0000_auth", "0001_credits"]);
-    expect(merged[0].protected).toBe(true);
-  });
-
-  test("distinct refs stay separate", () => {
-    const a: InstanceSpec[] = [{ ref: "db", service: "cloudflare-d1", name: "db", params: {} }];
-    const b: InstanceSpec[] = [{ ref: "kv", service: "cloudflare-kv", name: "cache", params: {} }];
-    expect(mergeProvision([a, b]).map((i) => i.ref).sort()).toEqual(["db", "kv"]);
-  });
-});
-
-describe("generatePlatform — the orchestration (with recorders)", () => {
-  test("writes the scaffold config FIRST, then a shadcn add per service, then the glue", async () => {
-    const ran: string[] = [];
-    const wrote: string[] = [];
-    const res = await generatePlatform(manifest, {
-      run: async (cmd, args) => void ran.push(`${cmd} ${args.join(" ")}`),
-      write: async (path) => void wrote.push(path),
-      read: async () => null, // a fresh app — no existing config
-    });
-    expect(ran).toEqual(plannedAdds()); // exactly the planned adds, in order
-    expect(ran.length).toBe(6); // app+auth+credits+keys+billing+logs
-    // config is written BEFORE the shadcn adds; the glue after. env-example + env-check + wrangler + gitignore included.
-    expect(wrote).toEqual(["package.json", "wrangler.toml", ".gitignore", "tsconfig.json", "components.json", ".env.example", "scripts/env-check.ts", "src/index.ts", "provision.config.ts"]);
-    expect(res.added.length).toBe(6);
-  });
-
-  test("leaves an existing tsconfig/components.json untouched; always (re)writes package.json/.gitignore/.env.example", async () => {
-    const wrote: string[] = [];
-    await generatePlatform(manifest, {
-      run: async () => {},
-      write: async (path) => void wrote.push(path),
-      read: async (p) => (p === "package.json" ? '{"name":"x","dependencies":{"my-lib":"^1.0.0"}}' : "existing"),
-    });
-    expect(wrote).toContain("package.json"); // merged + rewritten
-    expect(wrote).toContain(".gitignore"); // MERGED (never skip — must ensure .env is ignored)
-    expect(wrote).toContain(".env.example"); // template — always current
-    expect(wrote).toContain("scripts/env-check.ts");
-    expect(wrote).not.toContain("tsconfig.json"); // present → left as-is
-  });
-
-  test("mergeGitignore appends missing entries so .env is always ignored", () => {
-    const merged = mergeGitignore("node_modules/\n.env\n.env.temp\n", "node_modules\n");
-    expect(merged).toContain(".env");
-    expect(merged).toContain(".env.temp");
-    expect(merged.match(/node_modules/g)?.length).toBe(1); // deduped (node_modules vs node_modules/)
-  });
-});
-
-describe("env — secrets in .env (temp lifecycle), non-secrets in the manifest vars", () => {
-  test(".env.example lists ONLY required + optional secrets, never non-secret config", () => {
-    const p = planPlatform(definePlatform({ name: "e", registry: "acme/reg", services: ["auth", "billing", "webhooks", "email"] }));
-    expect(p.envExample).toContain("BETTER_AUTH_SECRET="); // required secret, uncommented
-    expect(p.envExample).toContain("STRIPE_SECRET_KEY=");
-    expect(p.envExample).toContain("STRIPE_WEBHOOK_SECRET=");
-    expect(p.envExample).toContain("# RESEND_API_KEY="); // optional secret, commented
-    expect(p.envExample).not.toContain("BASE_URL"); // non-secret → the manifest vars, NOT .env
-    expect(p.envExample).not.toContain("TRUSTED_ORIGINS");
-  });
-
-  test("wrangler.toml [vars] come from the manifest vars; unset non-secrets are commented; D1 binding present", () => {
-    const p = planPlatform(definePlatform({ name: "myapp", registry: "acme/reg", services: ["auth", "email", "rate-credit"], vars: { BASE_URL: "https://x.dev", ENVIRONMENT: "production" } }));
-    expect(p.wranglerToml).toContain('BASE_URL = "https://x.dev"'); // set in the manifest
-    expect(p.wranglerToml).toContain('ENVIRONMENT = "production"');
-    expect(p.wranglerToml).toContain("# EMAIL_FROM ="); // unset → commented
-    expect(p.wranglerToml).toContain('binding = "DB"');
-    expect(p.wranglerToml).toContain('binding = "RATE_CREDIT_KV"'); // rate-credit selected
-    expect(p.wranglerToml).not.toContain("BETTER_AUTH_SECRET"); // secrets never in [vars]
-  });
-
-  test("the env-check script bakes in the required secrets; merge preserves provisioned binding ids", () => {
-    const p = planPlatform(definePlatform({ name: "e", registry: "acme/reg", services: ["auth", "billing"] }));
-    expect(p.envCheck).toContain('["BETTER_AUTH_SECRET","STRIPE_SECRET_KEY"]');
-    expect(p.envCheck).toContain(".env.temp");
-    // wrangler merge keeps the operator's database_id across a regen
-    const merged = mergeWranglerToml(p.wranglerToml, 'name="e"\n[[d1_databases]]\nbinding = "DB"\ndatabase_id = "abc-123"');
-    expect(merged).toContain('database_id = "abc-123"');
-  });
-});
-
-describe("package.json generation — the manifest is the only surface", () => {
-  test("buildPackageJson unions base + service deps; @suluk/* → latest, ecosystem pinned", () => {
-    const plan = planPlatform(definePlatform({ name: "myapp", registry: "acme/reg", services: ["auth", "credits", "billing"] }));
-    const pkg = JSON.parse(plan.packageJson);
-    expect(pkg.name).toBe("myapp");
-    expect(pkg.dependencies["@suluk/credits"]).toBe("latest"); // fixes flow via bun update
-    expect(pkg.dependencies["@suluk/billing"]).toBe("latest");
-    expect(pkg.dependencies["hono"]).toBe("^4.0.0"); // ecosystem pinned
-    expect(pkg.dependencies["better-auth"]).toBe("^1.0.0"); // auth's dep
-    expect(pkg.devDependencies["typescript"]).toBeDefined();
-    expect(pkg.scripts.generate).toBe("suluk-platform");
-  });
-
-  test("mergePackageJson keeps app-added deps + scripts, baseline wins for framework deps", () => {
-    const baseline = buildPackageJson("myapp", ["auth", "credits"]);
-    const existing = JSON.stringify({ name: "myapp", dependencies: { "@suluk/credits": "^0.1.0", "my-product-lib": "^2.0.0" }, scripts: { deploy: "wrangler deploy" } });
-    const merged = JSON.parse(mergePackageJson(baseline, existing));
-    expect(merged.dependencies["my-product-lib"]).toBe("^2.0.0"); // app extra preserved
-    expect(merged.dependencies["@suluk/credits"]).toBe("latest"); // baseline wins → stays up to date
-    expect(merged.scripts.deploy).toBe("wrangler deploy"); // app script preserved
-    expect(merged.scripts.typecheck).toBe("tsc --noEmit -p ."); // framework script filled in
-  });
-
-  test("planPlatform emits tsconfig + components.json", () => {
-    const plan = planPlatform(manifest);
-    expect(JSON.parse(plan.tsconfig).exclude).toContain("src/**/*.test.ts");
-    expect(JSON.parse(plan.componentsJson).aliases.utils).toBe("src/lib/utils");
-  });
-});
-
-function plannedAdds() {
-  return planPlatform(manifest).adds.map((a) => `bunx shadcn@latest add ${a} --yes`);
-}

package/tsconfig.json

@@ -1 +0,0 @@
-{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test", "bin"] }