@suluk/platform 0.1.9 → 0.2.0

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,247 +0,0 @@
-import { test, expect, describe } from "bun:test";
-import { definePlatform, planPlatform, mergeProvision, generatePlatform, buildPackageJson, mergePackageJson, mergeWranglerToml } 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", "tsconfig.json", "components.json", ".gitignore", ".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/.gitignore untouched; always rewrites package.json/.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(".env.example"); // template — always current
-    expect(wrote).toContain("scripts/env-check.ts");
-    expect(wrote).not.toContain("tsconfig.json"); // present → left as-is
-    expect(wrote).not.toContain(".gitignore");
-  });
-});
-
-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"] }