@suluk/platform 0.1.6 → 0.1.8

package/bin/platform.ts

@@ -7,7 +7,7 @@
  *   --config <path>           a different manifest
  */
 import { resolve, dirname } from "node:path";
-import { writeFile, mkdir } from "node:fs/promises";
+import { writeFile, mkdir, readFile } from "node:fs/promises";
 import { generatePlatform } from "../src/generate";
 import type { PlatformManifest } from "../src/manifest";
 
@@ -33,4 +33,13 @@ const write = async (path: string, content: string): Promise<void> => {
   await writeFile(abs, content);
 };
 
-await generatePlatform(mod.default, { run, write, log: (m) => console.log(m) });
+// read a file for the merge (null when absent), so a regenerate keeps package.json deps current without dropping app extras.
+const read = async (path: string): Promise<string | null> => {
+  try {
+    return await readFile(resolve(process.cwd(), path), "utf8");
+  } catch {
+    return null;
+  }
+};
+
+await generatePlatform(mod.default, { run, write, read, log: (m) => console.log(m) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/platform",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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/catalog.ts

@@ -16,35 +16,74 @@ export interface CatalogEntry {
   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[];
 }
 
 export const CATALOG: Record<string, CatalogEntry> = {
   app: { mount: { kind: "base" } },
-  auth: { mount: { kind: "middleware", symbol: "mountAuthRoutes", from: "./auth" }, provision: { symbol: "authProvision", from: "./src/provision/auth" } },
+  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"] },
   // 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" } },
+  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" } },
+  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" } },
-  keys: { mount: { kind: "route", path: "/api/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" } },
-  billing: { mount: { kind: "route", path: "/api/billing", symbol: "billingRoutes", from: "./routes/billing" }, provision: { symbol: "billingProvision", from: "./src/provision/billing" } },
-  cost: { mount: { kind: "route", path: "/api/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" } },
-  erasure: { mount: { kind: "route", path: "/api/erasure", symbol: "erasureRoutes", from: "./routes/erasure" }, provision: { symbol: "erasureProvision", from: "./src/provision/erasure" } },
-  email: { mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" } }, // stateless binding — no provision fragment (C052)
-  webhooks: { mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" }, provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" } },
+  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"] },
+  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" }, deps: ["@suluk/email"] }, // stateless binding — no provision fragment (C052)
+  webhooks: { mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" }, provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" }, deps: ["@suluk/payments"] },
   // 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" } },
-  i18n: { mount: { kind: "middleware", symbol: "mountI18n", from: "./services/i18n" } },
-  reference: { mount: { kind: "route", path: "/api/reference", symbol: "referenceRoutes", from: "./routes/reference" } }, // derived doc render — no provision
-  admin: { mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" } }, // reads existing tables — no provision
+  "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" } },
-  audit: { mount: { kind: "dev" } },
+  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
+ * `deps` to build package.json.
+ */
+export const BASE_DEPS = ["@suluk/platform", "@suluk/provision", "@suluk/core", "effect", "hono", "drizzle-orm"];
+
+/** Pinned ranges for the NON-@suluk ecosystem deps — the single place they're kept current for every generated app.
+ *  @suluk/* are NOT here: they resolve to "latest" so a package fix flows to the app via `bun update` (the C052 payoff). */
+export const ECOSYSTEM_VERSIONS: Record<string, string> = {
+  "better-auth": "^1.0.0",
+  "@better-auth/api-key": "^1.0.0",
+  "@better-auth/passkey": "^1.0.0",
+  "drizzle-orm": "^0.45.2",
+  effect: "^3.0.0",
+  hono: "^4.0.0",
+  zod: "^4.0.0",
+};
+
+/** The generated app's devDeps (the Workers + TS toolchain). */
+export const DEV_DEPS: Record<string, string> = {
+  "@cloudflare/workers-types": "^4.20260701.1",
+  "@types/node": "^26.0.1",
+  typescript: "^6.0.3",
+};
+
+/** Resolve a dep to its version: an @suluk/* package → "latest" (fixes flow via `bun update`); a known ecosystem dep →
+ *  its pinned range; anything else → "latest" (a best-effort default). */
+export function resolveVersion(dep: string): string {
+  if (dep.startsWith("@suluk/")) return "latest";
+  return ECOSYSTEM_VERSIONS[dep] ?? "latest";
+}
+
 /** app + auth always come first (the base + the user/apikey tables others reference); the rest keep manifest order. */
 export function orderServices(services: string[]): string[] {
   const want = new Set(services);

package/src/generate.ts

@@ -5,13 +5,17 @@
  * testable. Stops short of `provision apply` — that's a live infra op the operator triggers.
  */
 import type { PlatformManifest } from "./manifest";
-import { planPlatform, type PlatformPlan } from "./plan";
+import { planPlatform, mergePackageJson, type PlatformPlan } from "./plan";
 
 export interface GenerateOptions {
   /** run a command — the CLI spawns `bunx shadcn add <ref>`; a test records. */
   run: (cmd: string, args: string[]) => Promise<void>;
   /** write a file (path relative to the target cwd). */
   write: (path: string, content: string) => Promise<void>;
+  /** read a file (null when absent) — used to MERGE the generated package.json with the app's existing one (so app-added
+   *  deps/scripts survive a regenerate) and to leave an existing tsconfig/components.json untouched. Optional: without it,
+   *  the config files are written as the fresh baseline. */
+  read?: (path: string) => Promise<string | null>;
   log?: (msg: string) => void;
 }
 
@@ -23,17 +27,40 @@ export interface GenerateResult {
 
 export async function generatePlatform(manifest: PlatformManifest, opts: GenerateOptions): Promise<GenerateResult> {
   const log = opts.log ?? (() => {});
+  const read = opts.read ?? (async () => null);
   const plan = planPlatform(manifest);
+  const written: string[] = [];
+
+  // 1) the scaffold CONFIG first — so `shadcn add` has a package.json to install into + a components.json to resolve
+  //    targets against. package.json MERGES with any existing (app deps/scripts survive; @suluk/* stay "latest"). An
+  //    existing tsconfig/components.json is left as-is (an app may have customized them).
+  const existingPkg = await read("package.json");
+  log("▸ writing package.json");
+  await opts.write("package.json", mergePackageJson(plan.packageJson, existingPkg));
+  written.push("package.json");
+  for (const [file, content] of [["tsconfig.json", plan.tsconfig], ["components.json", plan.componentsJson]] as const) {
+    if ((await read(file)) == null) {
+      log(`▸ writing ${file}`);
+      await opts.write(file, content);
+      written.push(file);
+    }
+  }
+
+  // 2) the module code — shadcn add pulls each module's files + resolves registryDependencies (deps already in package.json).
   const added: string[] = [];
   for (const add of plan.adds) {
     log(`▸ shadcn add ${add}`);
     await opts.run("bunx", ["shadcn@latest", "add", add, "--yes"]);
     added.push(add);
   }
+
+  // 3) the generated glue.
   log("▸ writing src/index.ts");
   await opts.write("src/index.ts", plan.entry);
   log("▸ writing provision.config.ts");
   await opts.write("provision.config.ts", plan.provisionConfig);
+  written.push("src/index.ts", "provision.config.ts");
+
   log(`✓ generated ${manifest.name}: ${plan.services.length} services. Next: bun install && suluk-provision apply`);
-  return { plan, added, written: ["src/index.ts", "provision.config.ts"] };
+  return { plan, added, written };
 }

package/src/index.ts

@@ -5,7 +5,7 @@
  * "credits", "billing"]` → a whole backend. The generated `provision.config.ts` imports `mergeProvision` from here.
  */
 export { definePlatform, type PlatformManifest } from "./manifest";
-export { CATALOG, orderServices, type CatalogEntry, type Mount } from "./catalog";
+export { CATALOG, orderServices, resolveVersion, BASE_DEPS, ECOSYSTEM_VERSIONS, DEV_DEPS, type CatalogEntry, type Mount } from "./catalog";
 export { mergeProvision } from "./merge";
-export { planPlatform, type PlatformPlan } from "./plan";
+export { planPlatform, buildPackageJson, mergePackageJson, type PlatformPlan } from "./plan";
 export { generatePlatform, type GenerateOptions, type GenerateResult } from "./generate";

package/src/manifest.ts

@@ -1,7 +1,10 @@
 /**
- * The platform manifest (C051) — the one author-facing document. Name the registry + the services you want; the generator
- * compiles it to a shadcn-add list + a wired Hono entry + a merged provision.config. The higher-level surface over C047's
- * provision.config: you say "auth, credits, billing" and the catalog knows each one's component + provision fragment.
+ * 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.
  */
 export interface PlatformManifest {
   /** the app/repo name (used in the generated scaffold). */
@@ -11,6 +14,12 @@ export interface PlatformManifest {
   /** 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. */
   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).
+   */
+  opts?: Record<string, Record<string, unknown>>;
 }
 
 /** Validate + return the manifest (throws on an empty service list). */

package/src/plan.ts

@@ -4,7 +4,7 @@
  * character.
  */
 import type { PlatformManifest } from "./manifest";
-import { CATALOG, orderServices } from "./catalog";
+import { CATALOG, orderServices, BASE_DEPS, DEV_DEPS, resolveVersion } from "./catalog";
 
 export interface PlatformPlan {
   services: string[];
@@ -14,6 +14,13 @@ export interface PlatformPlan {
   entry: string;
   /** the generated `provision.config.ts` content. */
   provisionConfig: 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;
+  /** the generated `tsconfig.json` content (the Workers + TS config; test files excluded from the build). */
+  tsconfig: string;
+  /** the generated `components.json` content (so `shadcn add` resolves the file targets). */
+  componentsJson: string;
 }
 
 export function planPlatform(manifest: PlatformManifest): PlatformPlan {
@@ -23,25 +30,119 @@ export function planPlatform(manifest: PlatformManifest): PlatformPlan {
   return {
     services,
     adds: services.map((s) => `${manifest.registry}/${s}`),
-    entry: buildEntry(services),
+    entry: buildEntry(services, manifest.opts),
     provisionConfig: buildProvisionConfig(services),
+    packageJson: buildPackageJson(manifest.name, services),
+    tsconfig: buildTsconfig(),
+    componentsJson: buildComponentsJson(),
   };
 }
 
-function buildEntry(services: string[]): string {
+/** 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 {
+  const deps = new Set<string>(BASE_DEPS);
+  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 = {
+    name,
+    private: true,
+    type: "module",
+    scripts: {
+      generate: "suluk-platform", // re-pull modules + rewrite src/index.ts + provision.config.ts + this config
+      typecheck: "tsc --noEmit -p .",
+      test: "bun test",
+    },
+    dependencies,
+    devDependencies: { ...DEV_DEPS },
+  };
+  return JSON.stringify(pkg, null, 2) + "\n";
+}
+
+/**
+ * Merge the generated framework baseline package.json with the app's EXISTING one (if any). The baseline WINS for the
+ * framework + module deps (so `@suluk/*` stay `"latest"` and the ecosystem stays on its pinned range — deps stay current
+ * across a regenerate), while any deps / scripts / top-level fields the app added are PRESERVED. No existing ⇒ the baseline
+ * verbatim. Keys are sorted for stable output. Pure + testable.
+ */
+export function mergePackageJson(baselineJson: string, existingJson: string | null): string {
+  if (!existingJson) return baselineJson;
+  const baseline = JSON.parse(baselineJson) as Record<string, unknown>;
+  let existing: Record<string, unknown>;
+  try {
+    existing = JSON.parse(existingJson) as Record<string, unknown>;
+  } catch {
+    return baselineJson; // an unparseable existing file → the baseline (don't silently keep broken JSON)
+  }
+  const obj = (v: unknown): Record<string, string> => (v && typeof v === "object" ? (v as Record<string, string>) : {});
+  const sortedMerge = (a: Record<string, string>, b: Record<string, string>): Record<string, string> => {
+    const out: Record<string, string> = {};
+    for (const k of Object.keys({ ...a, ...b }).sort()) out[k] = (b as Record<string, string>)[k] ?? a[k];
+    return out;
+  };
+  const merged = {
+    ...existing, // app-added top-level fields (engines, wrangler, …) survive
+    ...baseline, // baseline sets name/private/type
+    // app extras preserved; the baseline (framework + modules) WINS for overlaps → @suluk/* stay "latest".
+    dependencies: sortedMerge(obj(existing.dependencies), obj(baseline.dependencies)),
+    devDependencies: sortedMerge(obj(existing.devDependencies), obj(baseline.devDependencies)),
+    // app scripts win (custom commands survive); the framework's generate/typecheck/test fill any gaps.
+    scripts: { ...obj(baseline.scripts), ...obj(existing.scripts) },
+  };
+  return JSON.stringify(merged, null, 2) + "\n";
+}
+
+function buildTsconfig(): string {
+  return (
+    JSON.stringify(
+      {
+        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"],
+        exclude: ["src/**/*.test.ts"], // the bun:test journeys harness runs under `bun test`, not the Worker build
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}
+
+function buildComponentsJson(): string {
+  return (
+    JSON.stringify(
+      {
+        $schema: "https://ui.shadcn.com/schema.json",
+        style: "default",
+        rsc: false,
+        tsx: true,
+        tailwind: { config: "", css: "", baseColor: "neutral", cssVariables: false },
+        aliases: { components: "src/components", utils: "src/lib/utils" },
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}
+
+function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>): 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 optOf = (s: string): string => {
+    const o = opts?.[s];
+    return o && Object.keys(o).length ? `, ${JSON.stringify(o)}` : "";
+  };
   // 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;
     if (m.kind === "middleware") {
       imports.push(`import { ${m.symbol} } from "${m.from}";`);
-      middleware.push(`${m.symbol}(app);`);
+      middleware.push(`${m.symbol}(app${optOf(s)});`);
     } else if (m.kind === "route") {
       imports.push(`import { ${m.symbol} } from "${m.from}";`);
-      routes.push(`app.route("${m.path}", ${m.symbol}());`);
+      routes.push(`app.route("${m.path}", ${m.symbol}(${optOf(s).replace(/^, /, "")}));`);
     }
   }
   const body = ["const app = createApp();", ...middleware, ...routes];

package/test/plan.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { definePlatform, planPlatform, mergeProvision, generatePlatform } from "../src/index";
+import { definePlatform, planPlatform, mergeProvision, generatePlatform, buildPackageJson, mergePackageJson } 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
@@ -35,6 +35,13 @@ describe("planPlatform — manifest → shadcn adds + entry + provision.config",
   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)", () => {
@@ -109,6 +116,12 @@ describe("cost (route + provision) + dev modules (journeys/audit — files only)
     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");
@@ -138,18 +151,62 @@ describe("mergeProvision — combine same-ref instances, union migrations in ord
 });
 
 describe("generatePlatform — the orchestration (with recorders)", () => {
-  test("runs a shadcn add per service, then writes the entry + provision.config", async () => {
+  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
-    expect(wrote).toEqual(["src/index.ts", "provision.config.ts"]);
+    // config (package.json/tsconfig/components.json) is written BEFORE the shadcn adds; the glue after.
+    expect(wrote).toEqual(["package.json", "tsconfig.json", "components.json", "src/index.ts", "provision.config.ts"]);
     expect(res.added.length).toBe(6);
   });
+
+  test("leaves an existing tsconfig/components.json untouched but always (re)writes package.json", 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).not.toContain("tsconfig.json"); // present → left as-is
+    expect(wrote).not.toContain("components.json");
+  });
+});
+
+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() {