@suluk/platform 0.5.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/platform",
-  "version": "0.5.2",
+  "version": "0.7.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"

package/src/generate.ts

@@ -85,12 +85,23 @@ export async function generatePlatform(input: PlatformManifest | Platform, opts:
   log("▸ writing provision.config.ts");
   await opts.write("provision.config.ts", plan.provisionConfig);
   written.push("src/index.ts", "provision.config.ts");
-  // the bun MOCK-PROVIDER dev server — only when the manifest sets `local: true` (else undefined → not written).
+  // the composed contract surface (one fragment per module) — only when the `contract` service is installed.
+  if (plan.contractOps) {
+    log("▸ writing src/contract.ops.ts");
+    await opts.write("src/contract.ops.ts", plan.contractOps);
+    written.push("src/contract.ops.ts");
+  }
+  // the bun MOCK-PROVIDER dev server + the state-purge helper — only when the manifest sets `local: true`.
   if (plan.devEntry) {
     log("▸ writing src/dev.ts");
     await opts.write("src/dev.ts", plan.devEntry);
     written.push("src/dev.ts");
   }
+  if (plan.purgeScript) {
+    log("▸ writing scripts/purge-state.ts");
+    await opts.write("scripts/purge-state.ts", plan.purgeScript);
+    written.push("scripts/purge-state.ts");
+  }
 
   log(`✓ generated ${name}: ${plan.services.length} services. Next: bun install && suluk-provision apply`);
   return { plan, added, written };

package/src/manifest.ts

@@ -22,6 +22,11 @@ export interface PlatformManifest {
   opts?: Record<string, Record<string, unknown>>;
   /** NON-SECRET config values → generated into `wrangler.toml` `[vars]`. SECRETS never go here (they live in `.env`). */
   vars?: Record<string, string>;
+  /** C058 (INTERNAL, dev-only) — the LOCAL-runtime derived URL vars (BASE_URL/BETTER_AUTH_URL/TRUSTED_ORIGINS/EMAIL_FROM),
+   *  computed by `deriveHosts` from `LOCAL_BASE_URL`. Spread into `src/dev.ts`'s env; NEVER emitted to `[vars]`. */
+  localVars?: Record<string, string>;
+  /** C058 (INTERNAL, dev-only) — the raw local host (e.g. `localhost:8787`), so `src/dev.ts` can re-splice the actual PORT. */
+  __localHost?: string;
   /** emit the MOCK-PROVIDER dev runtime: a `src/dev.ts` that runs the app under bun with a bun:sqlite DB + JSON-file KV +
    *  mocked providers when their keys are absent (mock-until-keyed), and the `dev` script pointed at it. Default false →
    *  the scaffold is byte-for-byte the C051 golden. */

package/src/plan.ts

@@ -4,7 +4,7 @@
  * character.
  */
 import { type PlatformManifest, type Platform, isPlatform } from "./manifest";
-import { liftSystemBrand } from "./resolve";
+import { liftSystemBrand, deriveHosts } 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";
 
@@ -16,6 +16,9 @@ export interface PlatformPlan {
   entry: string;
   /** the generated `provision.config.ts` content. */
   provisionConfig: string;
+  /** the generated `src/contract.ops.ts` — the COMPOSED contract surface (one `RouteContract[]` fragment per module). Present
+   *  ONLY when the `contract` service is installed; the base `src/contract.ts` consumes its `ALL_OPS`. */
+  contractOps?: string;
   /** the generated `package.json` content (the FRAMEWORK baseline — `generate` merges it with any existing so app-added
    *  deps/scripts survive). @suluk/* on "latest" so fixes flow via `bun update`; ecosystem deps on pinned ranges. */
   packageJson: string;
@@ -52,12 +55,23 @@ export interface PlatformPlan {
   /** the generated `src/dev.ts` — the bun MOCK-PROVIDER dev server (bun:sqlite DB + JSON KV + mocked providers when keys
    *  absent). Present ONLY when the manifest sets `local: true`; undefined otherwise (so the golden path is unchanged). */
   devEntry?: string;
+  /** the generated `scripts/purge-state.ts` — clears dev/live state (recommended on a mock↔real swap or a provision
+   *  migration). Present ONLY when `local: true`. */
+  purgeScript?: string;
 }
 
 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;
+  const normalized = isPlatform(input) ? liftSystemBrand(input) : input;
+  // C058: the single-source URL derivation, on a PRIVATE copy so planPlatform never mutates the caller's manifest (the
+  // legacy full-URL manifest is a no-op — byte-identical). vars/opts are cloned; localVars/__localHost land on `manifest`.
+  const manifest: PlatformManifest = {
+    ...normalized,
+    ...(normalized.vars ? { vars: { ...normalized.vars } } : {}),
+    ...(normalized.opts ? { opts: structuredClone(normalized.opts) } : {}),
+  };
+  deriveHosts(manifest);
   // 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.
@@ -77,6 +91,7 @@ export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
     adds: services.map((s) => `${catalog[s].registry ?? manifest.registry}/${s}`),
     entry: buildEntry(services, manifest.opts, wiring, catalog, local),
     provisionConfig: buildProvisionConfig(services, catalog),
+    ...(services.includes("contract") ? { contractOps: buildContractOps(services, catalog) } : {}),
     packageJson: buildPackageJson(manifest.name, services, catalog, local),
     tsconfig: buildTsconfig(local),
     componentsJson: buildComponentsJson(),
@@ -91,7 +106,7 @@ export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
     provisionScript: buildProvisionScript(env),
     mintTokens: buildMintTokens(env),
     envScaffold: buildEnvScaffold(env),
-    ...(local ? { devEntry: buildDevEntry(services) } : {}),
+    ...(local ? { devEntry: buildDevEntry(services, manifest.localVars, manifest.__localHost), purgeScript: buildPurgeScript(services) } : {}),
   };
 }
 
@@ -524,6 +539,8 @@ process.exit(0);
 export function buildPackageJson(name: string, services: string[], catalog: Record<string, Service> = CORE_SERVICES, local = false): string {
   const deps = new Set<string>(BASE_DEPS);
   for (const s of services) for (const d of catalog[s]?.deps ?? []) deps.add(d);
+  // local mode's src/dev.ts imports @suluk/cloudflare (/local + /live facades + CloudflareClient) at runtime (dedup-safe).
+  if (local) deps.add("@suluk/cloudflare");
   const dependencies: Record<string, string> = {};
   for (const d of [...deps].sort()) dependencies[d] = resolveVersion(d);
   const pkg = {
@@ -536,7 +553,7 @@ export function buildPackageJson(name: string, services: string[], catalog: Reco
       // local mode: `dev` runs the bun mock-provider server (no keys needed → no env-check predev); `dev:cf` keeps wrangler.
       ...(local ? {} : { predev: "bun run scripts/env-check.ts" }), // (non-local) runs automatically before `dev`
       dev: local ? "bun run --hot src/dev.ts" : "wrangler dev",
-      ...(local ? { "dev:cf": "wrangler dev" } : {}),
+      ...(local ? { "dev:cf": "wrangler dev", purge: "bun run scripts/purge-state.ts" } : {}),
       deploy: "wrangler deploy",
       "env:keygen": "suluk-env keygen", // create the @suluk/env keypair (SULUK_PUBLIC_KEY → .env; private → .env.keys)
       "link-key": "bun run scripts/link-key.ts", // register the private key in ~/.suluk/settings.json (the central store)
@@ -592,9 +609,9 @@ function buildTsconfig(local = false): string {
       {
         compilerOptions: { module: "ESNext", target: "ESNext", moduleResolution: "bundler", types: ["node", "@cloudflare/workers-types"], skipLibCheck: true, strict: true, noEmit: true },
         include: ["src", "provision.config.ts", "platform.config.ts"],
-        // src/dev.ts is a bun-only runtime file (bun:sqlite + Bun globals), NOT Worker code — exclude it from the Worker
-        // typecheck (it pulls @suluk/cloudflare/local, which the workers-types config can't type); it's boot-tested instead.
-        exclude: ["src/**/*.test.ts", ...(local ? ["src/dev.ts"] : [])], // the bun:test journeys harness runs under `bun test`, not the Worker build
+        // src/dev.ts + scripts/purge-state.ts are bun-only (bun:sqlite + Bun globals + @suluk/cloudflare/local), NOT Worker
+        // code — exclude them from the Worker typecheck (the workers-types config can't type them); they're boot-tested instead.
+        exclude: ["src/**/*.test.ts", ...(local ? ["src/dev.ts", "scripts/purge-state.ts"] : [])], // the bun:test journeys harness runs under `bun test`, not the Worker build
       },
       null,
       2,
@@ -694,52 +711,86 @@ function buildEntry(services: string[], opts?: Record<string, Record<string, unk
  * no wrangler. Mock-until-keyed: it decrypts the committed `.env` if the app has been provisioned (real HTTP providers), else
  * every provider falls to its module's mock. The deployed Worker (`src/index.ts`) imports NONE of this — bun:sqlite stays out.
  */
-function buildDevEntry(services: string[]): string {
+function buildDevEntry(services: string[], localVars?: Record<string, string>, localHost?: string): string {
   const usesKv = services.includes("rate-credit");
   const usesEmail = services.includes("email");
+  // C058: the local-runtime URL vars (derived from LOCAL_BASE_URL) + the default PORT (from the local host, so BASE_URL's
+  // port matches what we serve on). `rebase` re-points any localhost URL at the actual PORT if the operator overrides it.
+  const localPort = (localHost ?? "").match(/:(\d+)$/)?.[1] ?? "8787";
+  const localVarsSetup = localVars && Object.keys(localVars).length
+    ? `\n// C058 — the LOCAL-runtime URL vars (BASE_URL/BETTER_AUTH_URL/TRUSTED_ORIGINS derived from LOCAL_BASE_URL), re-pointed at the actual PORT.\nconst LOCAL_VARS = ${JSON.stringify(localVars)};\nconst urls = Object.fromEntries(Object.entries(LOCAL_VARS).map(([k, v]) => [k, v.replace(/(localhost:)\\d+/g, \`$1\${PORT}\`)]));`
+    : "";
+  const localVarsBind = localVarsSetup ? "\n  ...urls," : "";
   const usesBilling = services.includes("billing");
   const localImports = ["d1FromSqlite", ...(usesKv ? ["jsonFileKvStore"] : []), ...(usesEmail ? ["jsonFileMailbox"] : []), "applyLocalSchema"];
+  const liveImports = ["d1FromHttp", ...(usesKv ? ["httpKvStore"] : [])];
   const billingImport = usesBilling ? '\nimport { mockStripeFetch } from "@suluk/billing";' : "";
-  const kvBind = usesKv ? "\n  RATE_CREDIT_KV: jsonFileKvStore(KV_PATH)," : "";
   const mailboxBind = usesEmail ? "\n  SULUK_MAILBOX_SINK: mailbox," : "";
-  // mock-until-keyed: only inject the Stripe fake when there is no real key (a provisioned app hits real Stripe).
+  // mock-until-keyed: only inject the Stripe fake when there is no real key (a provisioned app hits real Stripe). ORTHOGONAL
+  // to the state layer — a mock Stripe works against LIVE D1/KV too.
   const stripeInject = usesBilling
     ? '\nif (!env.STRIPE_SECRET_KEY) { env.STRIPE_SECRET_KEY = "sk_mock_local"; env.STRIPE_FETCH = mockStripeFetch(); }'
     : "";
   const mailboxRoute = usesEmail
     ? '\n// a dev-only inbox view of the emails the mock provider captured (never mounted on the deployed Worker).\napp.get("/api/email/dev/mailbox", async (c) => c.json(await mailbox.list()));\n'
     : "";
-  return `// AUTO-GENERATED by @suluk/platform — the bun MOCK-PROVIDER dev server. Runs the wired app under bun with a
-// bun:sqlite DB + JSON-file KV, so \`bun run dev\` works with ZERO Cloudflare account and no wrangler. A provider goes REAL
-// the moment its key is present (mock-until-keyed): add real keys to .env.temp + \`bun run provision\` and this file uses
-// them. NOTE: src/index.ts (the deployed Worker) imports NONE of these mocks — bun:sqlite never enters the Worker bundle.
+  const kvIdParse = usesKv ? '\nconst kvId = wrangler.match(/\\[\\[kv_namespaces\\]\\][\\s\\S]*?\\bid\\s*=\\s*"([^"]+)"/)?.[1];' : "";
+  const liveAttachCond = usesKv ? "cfToken && cfAccount && d1Id && kvId" : "cfToken && cfAccount && d1Id";
+  const kvDecl = usesKv ? "\nlet RATE_CREDIT_KV: unknown;" : "";
+  const liveKvAssign = usesKv ? "\n  RATE_CREDIT_KV = httpKvStore(new CloudflareClient({ apiToken: (S.CLOUDFLARE_KV_TOKEN ?? cfToken) as string, accountId: cfAccount! }), kvId!);" : "";
+  const mockKvAssign = usesKv ? "\n  RATE_CREDIT_KV = jsonFileKvStore(KV_PATH);" : "";
+  const kvEnvBind = usesKv ? "\n  RATE_CREDIT_KV," : "";
+  return `// AUTO-GENERATED by @suluk/platform — the bun dev server. Runs the wired app under bun so \`bun run dev\` works with
+// ZERO Cloudflare account and no wrangler. SINGLE ENVIRONMENT, MOCK-UNTIL-KEYED, per-layer + per-provider:
+//  • STATE (D1+KV): once PROVISIONED (CF token + account + binding ids) it attaches to the SAME LIVE services as the Worker
+//    over the Cloudflare HTTP API; a fresh app uses a local bun:sqlite + JSON-file mock. Both-or-neither (never split state).
+//  • PROVIDERS (Google/Stripe/Resend): each real when ITS key is present, else its module's mock — INDEPENDENT of the state
+//    layer, so a mock login/payment/email works against LIVE D1/KV too. RECOMMEND \`bun run purge\` when you swap a mock for a
+//    real key (or vice-versa) or migrate the provision — the old state's shape may not match.
+// NOTE: src/index.ts (the deployed Worker) imports NONE of this — bun:sqlite/mocks never enter the Worker bundle.
 import { app } from "./index";
 import { Database } from "bun:sqlite";
-import { ${localImports.join(", ")} } from "@suluk/cloudflare/local";${billingImport}
+import { ${localImports.join(", ")} } from "@suluk/cloudflare/local";
+import { ${liveImports.join(", ")} } from "@suluk/cloudflare/live";
+import { CloudflareClient } from "@suluk/cloudflare";${billingImport}
 import { loadEnvFile } from "@suluk/env/node";
 
 const DB_PATH = process.env.SULUK_DB_PATH ?? ".suluk/dev.sqlite";${usesKv ? '\nconst KV_PATH = process.env.SULUK_KV_PATH ?? ".suluk/dev-kv.json";' : ""}${usesEmail ? '\nconst MAILBOX_PATH = process.env.SULUK_MAILBOX_PATH ?? ".suluk/dev-mailbox.json";' : ""}
-const PORT = Number(process.env.PORT ?? 8787);
-
-const sqlite = new Database(DB_PATH, { create: true });
-const tables = await applyLocalSchema(sqlite); // discover src/db/*.ts + create the tables from the drizzle schema
-console.log(\`[suluk dev] sqlite \${DB_PATH} — \${tables.length} tables\`);
+const PORT = Number(process.env.PORT ?? ${localPort});${localVarsSetup}
 ${usesEmail ? "const mailbox = jsonFileMailbox(MAILBOX_PATH); // a local inbox the mock email provider saves to\n" : ""}
 // Real secrets (if this app has been provisioned): decrypt the committed .env with the local private key. Fresh app / no
 // key → {} → every provider mocks. Best-effort: a decryption failure never blocks the mock path.
 let secrets: Record<string, string> = {};
 try { secrets = await loadEnvFile(); } catch {}
+const S = { ...process.env, ...secrets } as Record<string, string | undefined>; // resolved config (env + decrypted secrets)
+
+// STATE layer: attach LIVE (same D1${usesKv ? "+KV" : ""} as the Worker, over the CF HTTP API) once the minted token + account + the
+// provisioned binding id(s) are present; else the local mock. Both-or-neither.
+const cfToken = S.CLOUDFLARE_D1_TOKEN ?? S.CLOUDFLARE_API_TOKEN;
+const cfAccount = S.CLOUDFLARE_ACCOUNT_ID;
+const wrangler = await Bun.file("wrangler.toml").text().catch(() => "");
+const d1Id = wrangler.match(/database_id\\s*=\\s*"([^"]+)"/)?.[1];${kvIdParse}
+const liveAttach = !!(${liveAttachCond});
+
+let DB: unknown;${kvDecl}
+if (liveAttach) {
+  const cf = new CloudflareClient({ apiToken: cfToken!, accountId: cfAccount! });
+  DB = d1FromHttp(cf, d1Id!);${liveKvAssign}
+  console.log(\`[suluk dev] LIVE-ATTACHED — same D1${usesKv ? "+KV" : ""} as the Worker (\${d1Id}); local changes hit production state.\`);
+} else {
+  const sqlite = new Database(DB_PATH, { create: true });
+  const tables = await applyLocalSchema(sqlite); // discover src/db/*.ts + create the tables from the drizzle schema
+  DB = d1FromSqlite(sqlite);${mockKvAssign}
+  console.log(\`[suluk dev] mock state — sqlite \${DB_PATH} (\${tables.length} tables)\`);
+}
 
-// The request env: process.env < decrypted secrets < the mock bindings. DB/KV are always local (a bun process can't bind a
-// remote D1/KV); the HTTP providers (Google/Stripe/Resend) use their real key when present, else their module's mock.
 const env: Record<string, unknown> = {
-  ...process.env,
-  ...secrets,
-  DB: d1FromSqlite(sqlite),${kvBind}${mailboxBind}
+  ...S,${localVarsBind}
+  DB,${kvEnvBind}${mailboxBind}
 };
 
 const mocked = ["GOOGLE_CLIENT_ID", "STRIPE_SECRET_KEY", "RESEND_API_KEY"].filter((k) => !env[k]);
-if (mocked.length) console.log(\`[suluk dev] mocked (no key): \${mocked.join(", ")}\`);${stripeInject}
+if (mocked.length) console.log(\`[suluk dev] mocked providers (no key): \${mocked.join(", ")}\${liveAttach ? " — against LIVE state; run \\\`bun run purge\\\` after swapping a mock for real keys" : ""}\`);${stripeInject}
 ${mailboxRoute}
 const ctx = { waitUntil() {}, passThroughOnException() {} } as unknown as ExecutionContext;
 Bun.serve({ port: PORT, idleTimeout: 120, fetch: (req) => app.fetch(req, env as Parameters<typeof app.fetch>[1], ctx) });
@@ -747,6 +798,77 @@ console.log(\`[suluk dev] → http://localhost:\${PORT}  (mock-until-keyed; prov
 `;
 }
 
+/**
+ * `scripts/purge-state.ts` (emitted only when `local: true`) — reset STATE. The single environment is mock-until-keyed, so
+ * when you swap a mock provider for real keys (or vice-versa), or migrate the provision (a new service ⇒ new tables / KV /
+ * R2), the OLD state's shape may not match — this clears it. Always purges the LOCAL mock state (`.suluk/*`, recreated on
+ * next `bun run dev`); with `--yes` it ALSO drops the LIVE D1 tables + clears the live KV (then re-run `bun run provision`).
+ */
+function buildPurgeScript(services: string[]): string {
+  const usesKv = services.includes("rate-credit");
+  const kvIdParse = usesKv ? '\nconst kvId = wrangler.match(/\\[\\[kv_namespaces\\]\\][\\s\\S]*?\\bid\\s*=\\s*"([^"]+)"/)?.[1];' : "";
+  const kvPurge = usesKv
+    ? `\n    if (kvId) {
+      const kvCf = new CloudflareClient({ apiToken: (S.CLOUDFLARE_KV_TOKEN ?? token) as string, accountId: account });
+      const keys = await kvList(kvCf, kvId);
+      for (const k of keys) await kvDelete(kvCf, kvId, k);
+      console.log(\`  cleared \${keys.length} live KV keys\`);
+    }`
+    : "";
+  const localFiles = ['.suluk/dev.sqlite', '.suluk/dev.sqlite-wal', '.suluk/dev.sqlite-shm', ...(usesKv ? ['.suluk/dev-kv.json'] : []), ...(services.includes("email") ? ['.suluk/dev-mailbox.json'] : [])];
+  return `// AUTO-GENERATED by @suluk/platform — purge STATE. RECOMMENDED whenever you swap a mock provider for real keys (or
+// vice-versa) or migrate the provision (a new service ⇒ new tables/KV/R2): the single environment is mock-until-keyed, so
+// the old state's shape may not match the new one. Always clears LOCAL mock state; \`--yes\` also purges LIVE D1 + KV.
+import { rmSync } from "node:fs";
+import { discoverTableNames } from "@suluk/cloudflare/local";
+import { loadEnvFile } from "@suluk/env/node";
+import { CloudflareClient, queryD1${usesKv ? ", kvList, kvDelete" : ""} } from "@suluk/cloudflare";
+
+const yes = process.argv.includes("--yes");
+
+// 1) LOCAL mock state — dev-only files; recreated on the next \`bun run dev\`. Always safe.
+for (const f of ${JSON.stringify(localFiles)}) { try { rmSync(f, { force: true }); } catch {} }
+console.log("✓ purged local mock state (.suluk/*)");
+
+// 2) LIVE state (if provisioned): DROP the app's D1 tables${usesKv ? " + clear the KV namespace" : ""}. DESTRUCTIVE — needs \`--yes\`.
+let S: Record<string, string | undefined> = { ...process.env };
+try { S = { ...process.env, ...(await loadEnvFile()) }; } catch {}
+const token = S.CLOUDFLARE_D1_TOKEN ?? S.CLOUDFLARE_API_TOKEN;
+const account = S.CLOUDFLARE_ACCOUNT_ID;
+const wrangler = await Bun.file("wrangler.toml").text().catch(() => "");
+const d1Id = wrangler.match(/database_id\\s*=\\s*"([^"]+)"/)?.[1];${kvIdParse}
+
+if (token && account && d1Id) {
+  if (!yes) {
+    console.log(\`\\n⚠ LIVE state detected (D1 \${d1Id}${usesKv ? '\${kvId ? " + KV " + kvId : ""}' : ""}). Re-run \\\`bun run purge -- --yes\\\` to DROP all app tables${usesKv ? " + clear KV" : ""}, then \\\`bun run provision\\\` to recreate the schema.\`);
+  } else {
+    const cf = new CloudflareClient({ apiToken: token, accountId: account });
+    for (const t of await discoverTableNames()) { await queryD1(cf, d1Id, \`DROP TABLE IF EXISTS "\${t}"\`); console.log(\`  dropped \${t}\`); }${kvPurge}
+    console.log("✓ purged LIVE state — run \`bun run provision\` to recreate the schema. (R2 objects, if any, purge via the CF dashboard.)");
+  }
+}
+`;
+}
+
+/**
+ * `src/contract.ops.ts` — the COMPOSED contract surface: one `RouteContract[]` fragment per installed module (each module
+ * OWNS its ops next to its routes), spread into `ALL_OPS`. Mirrors {@link buildProvisionConfig}. The base `src/contract.ts`
+ * consumes `ALL_OPS` (adding the system op + the derivations), so adding/changing a module's routes only touches THAT
+ * module's fragment — the central contract can never drift from the routes again.
+ */
+function buildContractOps(services: string[], catalog: Record<string, Service> = CORE_SERVICES): string {
+  const frags = services.map((s) => catalog[s].contract).filter((c): c is NonNullable<typeof c> => !!c);
+  const imports = frags.map((f) => `import { ${f.symbol} } from "${f.from}";`);
+  return [
+    "// AUTO-GENERATED by @suluk/platform — the composed contract surface (one fragment per installed module).",
+    'import type { DocumentedRoute } from "@suluk/hono";',
+    ...imports,
+    "",
+    `export const ALL_OPS: readonly DocumentedRoute[] = [${frags.map((f) => `...${f.symbol}`).join(", ")}];`,
+    "",
+  ].join("\n");
+}
+
 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}";`);

package/src/resolve.ts

@@ -13,6 +13,7 @@
 import type { PlatformManifest } from "./manifest";
 import type { Platform, SystemManifest, BrandManifest } from "./manifest";
 import { CORE_SERVICES } from "./service";
+import { deriveUrls } from "./urls";
 
 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";
@@ -72,6 +73,46 @@ export function resolveNodeOpts(system: SystemManifest, brand: BrandManifest): {
 /** 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"]);
 
+/**
+ * C058 — the single-source URL derivation, applied to a normalized {@link PlatformManifest} (BOTH authoring surfaces
+ * converge here). If the manifest declares `LIVE_BASE_URL` (a bare host) AND has NOT hand-authored `BETTER_AUTH_URL`
+ * (back-compat/golden-lock gate), derive every URL var: the WORKER `[vars]` from the LIVE host, the bun-dev env
+ * (`manifest.localVars`) from the LOCAL host, and — when `opts.auth.mcpScopes` is present — the mcp OAuth trio from LIVE.
+ * The two bare hosts + `EMAIL_DOMAIN`/`EXTRA_TRUSTED_ORIGINS` are DELETED from `vars` (pure inputs, never `[vars]`).
+ * Mutates the manifest in place; a no-op when the gate is off (a legacy full-URL manifest regenerates byte-for-byte).
+ */
+export function deriveHosts(manifest: PlatformManifest): void {
+  const vars = manifest.vars;
+  if (!vars) return;
+  const liveHost = vars.LIVE_BASE_URL;
+  if (!liveHost || vars.BETTER_AUTH_URL) return; // gate: opt-in via LIVE_BASE_URL + never override a hand-authored URL
+
+  const localHost = vars.LOCAL_BASE_URL ?? liveHost;
+  const scopes = (manifest.opts?.auth?.mcpScopes as string[] | undefined) ?? undefined;
+  const opts = { scopes, emailDomain: vars.EMAIL_DOMAIN, extraOrigins: (vars.EXTRA_TRUSTED_ORIGINS ?? "").split(",").map((s) => s.trim()).filter(Boolean) };
+
+  const live = deriveUrls(liveHost, liveHost, opts); // the deployed Worker: BASE_URL === the live URL
+  vars.BETTER_AUTH_URL = live.BETTER_AUTH_URL;
+  vars.BASE_URL = live.BASE_URL;
+  vars.TRUSTED_ORIGINS = live.TRUSTED_ORIGINS;
+  vars.EMAIL_FROM = live.EMAIL_FROM;
+  // mcp OAuth is opt-in via `mcpScopes` (an app without it stays non-MCP). Derive the URL trio; drop the raw scope input.
+  if (scopes?.length) {
+    manifest.opts = { ...(manifest.opts ?? {}), auth: { ...(manifest.opts?.auth ?? {}), mcp: live.mcp } };
+    delete (manifest.opts.auth as Record<string, unknown>).mcpScopes;
+  }
+
+  const local = deriveUrls(localHost, liveHost, opts); // the local bun-dev runtime: BASE_URL === the local URL
+  manifest.localVars = { BASE_URL: local.BASE_URL, BETTER_AUTH_URL: local.BETTER_AUTH_URL, TRUSTED_ORIGINS: local.TRUSTED_ORIGINS, EMAIL_FROM: local.EMAIL_FROM };
+  manifest.__localHost = localHost;
+
+  // the bare hosts + override knobs are derivation INPUTS — never emit them as `[vars]`.
+  delete vars.LIVE_BASE_URL;
+  delete vars.LOCAL_BASE_URL;
+  delete vars.EMAIL_DOMAIN;
+  delete vars.EXTRA_TRUSTED_ORIGINS;
+}
+
 /**
  * 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

package/src/service.ts

@@ -50,6 +50,8 @@ export interface EnvVar {
 export interface CatalogEntry {
   mount: Mount;
   provision?: { symbol: string; from: string };
+  /** the module's CONTRACT fragment — its `RouteContract[]` (ops), composed into `src/contract.ops.ts` (mirrors `provision`). */
+  contract?: { symbol: string; from: string };
   deps?: string[];
   env?: EnvVar[];
 }
@@ -109,6 +111,8 @@ export interface Service<SO = {}, BO = {}> {
   readonly registry?: string; // owning registry (multi-registry, Phase 4); default = the manifest's core alias
   readonly mount: Mount;
   readonly provision?: { symbol: string; from: string };
+  /** the module's CONTRACT fragment — its `RouteContract[]` (ops), composed into `src/contract.ops.ts` (mirrors `provision`). */
+  readonly contract?: { 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]
@@ -144,6 +148,10 @@ export interface McpOAuthOpts {
 }
 /** auth's serviceOpts: optionally activate the MCP OAuth server (Better Auth `mcp()` plugin). */
 export interface AuthServiceOpts {
+  /** C058: activate the MCP OAuth server by declaring its SCOPE SET — the loginPage/consentPage/resource URLs are DERIVED
+   *  from `LIVE_BASE_URL` (no host boilerplate). This is the single-source authoring path. */
+  mcpScopes?: string[];
+  /** LEGACY: the full MCP OAuth URL block. Prefer `mcpScopes` (URLs derived). Kept for back-compat with hand-authored URLs. */
   mcp?: McpOAuthOpts;
 }
 
@@ -159,7 +167,7 @@ export interface CoreServiceOptsMap {
 /** 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 };
+  return { mount: s.mount, provision: s.provision, contract: s.contract, deps: s.deps, env: s.env };
 }
 
 /**
@@ -210,12 +218,13 @@ export const authService = defineService({
 });
 
 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 mcpService = defineService({ id: "mcp", mount: { kind: "middleware", symbol: "mountMcp", from: "./routes/mcp" }, provision: { symbol: "mcpProvision", from: "./src/provision/mcp" }, contract: { symbol: "mcpOps", from: "./contract/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" },
+  contract: { symbol: "creditsOps", from: "./contract/credits" },
   deps: ["@suluk/credits"],
   compose: {
     offers: {
@@ -242,12 +251,13 @@ export const creditsService = defineService({
   },
 });
 
-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 keysService = defineService({ id: "keys", mount: { kind: "route", path: "/api/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" }, contract: { symbol: "keysOps", from: "./contract/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" },
+  contract: { symbol: "billingOps", from: "./contract/billing" },
   deps: ["@suluk/billing", "@suluk/payments", "@suluk/credits"],
   env: [
     { name: "STRIPE_SECRET_KEY", required: true, secret: true, hint: "your Stripe secret key" },
@@ -255,12 +265,13 @@ export const billingService = defineService({
   ],
 });
 
-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 costService = defineService({ id: "cost", mount: { kind: "route", path: "/api/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" }, contract: { symbol: "costOps", from: "./contract/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" }, contract: { symbol: "erasureOps", from: "./contract/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)
+  mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" }, // stateless binding — no provision fragment (C052) // stateless binding — no provision fragment (C052)
+  contract: { symbol: "emailOps", from: "./contract/email" },
   deps: ["@suluk/email"],
   env: [
     { name: "RESEND_API_KEY", secret: true, hint: "omit → the console provider (dev)" },
@@ -275,6 +286,7 @@ export const webhooksService = defineService({
   id: "webhooks",
   mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" },
   provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" },
+  contract: { symbol: "webhooksOps", from: "./contract/webhooks" },
   deps: ["@suluk/payments"],
   env: [{ name: "STRIPE_WEBHOOK_SECRET", required: true, secret: true, hint: "verifies inbound Stripe events (POST /api/webhooks/stripe)" }],
 });
@@ -282,9 +294,9 @@ export const webhooksService = defineService({
 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"], env: [{ name: "SUPERADMIN_EMAILS", secret: true, hint: "comma/space-separated admin emails → the admin scope (secret-surfaced so they stay out of git plaintext)" }] }); // 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 referenceService = defineService({ id: "reference", mount: { kind: "route", path: "/api/reference", symbol: "referenceRoutes", from: "./routes/reference" }, contract: { symbol: "referenceOps", from: "./contract/reference" }, deps: ["@suluk/reference"] }); // derived — no provision
+export const adminService = defineService({ id: "admin", mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" }, contract: { symbol: "adminOps", from: "./contract/admin" }, deps: ["@suluk/credits"], env: [{ name: "SUPERADMIN_EMAILS", secret: true, hint: "comma/space-separated admin emails → the admin scope (secret-surfaced so they stay out of git plaintext)" }] }); // 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" }, contract: { symbol: "logsOps", from: "./contract/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"] });
 

package/src/urls.ts

@@ -0,0 +1,79 @@
+/**
+ * C058 — the single-source URL derivation (PURE, generator-internal, build-time ONLY). The manifest declares TWO bare
+ * hosts once — `LIVE_BASE_URL` (the production host) + `LOCAL_BASE_URL` (the local-runtime host) — WITHOUT protocol; every
+ * other URL is DERIVED here and BAKED by `resolve.ts` into the Worker `[vars]` (from the live host) and the bun-dev env
+ * (from the local host). Registry consumers stay dumb env-readers (they never import this), so the golden path is unchanged
+ * and there is no URL authored twice. Never runs at app runtime.
+ */
+
+/** strip protocol + trailing slash(es) + any path, leaving `host[:port]`. */
+const strip = (h: string): string => h.replace(/^https?:\/\//, "").replace(/\/+$/, "").split("/")[0];
+/** the bare hostname (no port). */
+const hostname = (h: string): string => strip(h).split(":")[0];
+/** the port, or "" when none. */
+const port = (h: string): string => { const m = strip(h).match(/:(\d+)$/); return m ? m[1] : ""; };
+
+/** LOCAL is decided by HOSTNAME ONLY — never by port presence (so `example.com:8443` is NOT misclassified as local). */
+export function isLocal(h: string): boolean {
+  const n = hostname(h);
+  return n === "localhost" || n === "127.0.0.1" || n === "0.0.0.0" || n === "::1" || n.endsWith(".local");
+}
+
+/** Protocol rule: a local hostname → http, a real domain → https. Default ports (:80 http, :443 https) are STRIPPED so a
+ *  derived origin exact-matches the browser `Origin` header. */
+export function withProtocol(h: string): string {
+  const bare = strip(h);
+  const proto = isLocal(h) ? "http" : "https";
+  const p = port(h);
+  const dropDefault = (proto === "https" && p === "443") || (proto === "http" && p === "80");
+  return `${proto}://${dropDefault ? hostname(h) : bare}`;
+}
+
+/** the apex-ish host: the bare hostname minus a leading `www.` (NOT an eTLD+1 resolver — `api.example.com` stays as-is). */
+export function apex(h: string): string {
+  return hostname(h).replace(/^www\./, "");
+}
+
+/** true when the live host is a SUBDOMAIN (e.g. `api.example.com`) — a hint that `noreply@<host>` may not be a verified
+ *  sending domain, so an `EMAIL_DOMAIN` override is advisable. */
+export function isSubdomain(h: string): boolean {
+  return apex(h).split(".").length > 2;
+}
+
+export interface DerivedUrls {
+  BETTER_AUTH_URL: string;
+  BASE_URL: string;
+  TRUSTED_ORIGINS: string;
+  EMAIL_FROM: string;
+  /** the mcp OAuth trio + scopes — ALWAYS anchored to the LIVE host (a public authorization-server identity). */
+  mcp: { loginPage: string; consentPage: string; resource: string; scopes: string[] };
+}
+
+export interface DeriveOptions {
+  scopes?: string[];
+  /** override the email sending domain (else the live apex). */
+  emailDomain?: string;
+  /** extra CORS origins to append (e.g. a separate SPA host or `*.pages.dev` previews). */
+  extraOrigins?: string[];
+}
+
+/**
+ * Derive every URL var for ONE runtime. `runtimeHost` = the host `BASE_URL`/`BETTER_AUTH_URL`/`TRUSTED_ORIGINS` resolve to
+ * for THIS runtime (the live host on the Worker; the local host in bun-dev). `liveHost` = the production host, which ALWAYS
+ * drives `EMAIL_FROM` + the mcp OAuth identity (baked into shared code = physically one value).
+ */
+export function deriveUrls(runtimeHost: string, liveHost: string, o: DeriveOptions = {}): DerivedUrls {
+  const base = withProtocol(runtimeHost);
+  const live = withProtocol(liveHost);
+  const liveApex = apex(liveHost);
+  // origin allowlist: this runtime's own origin + the live apex + live www (so a pre-redirect www hit isn't CORS-rejected)
+  // + any operator EXTRA_TRUSTED_ORIGINS. A Set dedupes (on the Worker, base === the live apex origin).
+  const origins = new Set<string>([base, withProtocol(liveApex), withProtocol(`www.${liveApex}`), ...(o.extraOrigins ?? [])]);
+  return {
+    BETTER_AUTH_URL: base,
+    BASE_URL: base,
+    TRUSTED_ORIGINS: [...origins].join(","),
+    EMAIL_FROM: `noreply@${o.emailDomain ?? liveApex}`,
+    mcp: { loginPage: `${live}/oauth/sign-in`, consentPage: `${live}/oauth/consent`, resource: `${live}/api/mcp`, scopes: o.scopes ?? [] },
+  };
+}