@suluk/platform 0.1.7 → 0.1.9

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.7",
+  "version": "0.1.9",
   "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

@@ -11,41 +11,136 @@ export type Mount =
   | { kind: "route"; path: string; symbol: string; from: string } // e.g. `app.route("/credits", creditsRoutes())`
   | { kind: "dev" }; // dev/CI tooling (journeys, audit) — files only, no runtime mount, no provision fragment
 
+/** An env var a module needs at runtime — drives the generated `.env.example` + the env-check preflight. Bindings (D1/KV)
+ *  are NOT here (they live in wrangler.toml); only string env vars. */
+export interface EnvVar {
+  name: string;
+  /** the app WON'T work without it (the "minimum keys") — the env-check requires a non-empty value before it's happy. */
+  required?: boolean;
+  /** a credential (never commit) — shown commented in `.env.example` + flagged in the temp file. */
+  secret?: boolean;
+  /** a one-line hint shown as a comment in `.env.example`. */
+  hint?: string;
+}
+
 export interface CatalogEntry {
   /** how it mounts into the entry. */
   mount: Mount;
   /** the provision fragment export, if any (`InstanceSpec[]`). */
   provision?: { symbol: string; from: string };
+  /** the module's npm deps BEYOND the always-present base (see BASE_DEPS) — its @suluk/* logic packages + any extras
+   *  (zod, better-auth). `shadcn add` also installs these; declaring them here lets the generator emit a complete,
+   *  from-the-manifest package.json (so platform.config.ts is the only hand-authored surface). Kept in sync with the
+   *  registry item's `dependencies`. */
+  deps?: string[];
+  /** the runtime env vars this module reads — the generator unions them into `.env.example` + the env-check preflight. */
+  env?: EnvVar[];
 }
 
 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" } },
+  app: { mount: { kind: "base" }, env: [{ name: "TRUSTED_ORIGINS", hint: "comma-separated browser origins allowed on /api/* (CORS)" }] },
+  auth: {
+    mount: { kind: "middleware", symbol: "mountAuthRoutes", from: "./auth" },
+    provision: { symbol: "authProvision", from: "./src/provision/auth" },
+    deps: ["better-auth", "@better-auth/api-key", "@better-auth/passkey", "@suluk/better-auth"],
+    env: [
+      { name: "BETTER_AUTH_SECRET", required: true, secret: true, hint: "session-signing key — `openssl rand -base64 32`" },
+      { name: "BETTER_AUTH_URL", hint: "your deployed origin, e.g. https://api.example.com" },
+      { name: "GOOGLE_CLIENT_ID", secret: true, hint: "optional — enables Google sign-in" },
+      { name: "GOOGLE_CLIENT_SECRET", secret: true, hint: "optional — pairs with GOOGLE_CLIENT_ID" },
+    ],
+  },
   // the contract is a MIDDLEWARE mount: it installs the scope gate (enforceApiKeyScope) + GET /api/openapi.json. Place it
   // after `auth` in the manifest so the gate runs after identity/apiKeyAuth set keyId/scopes. Derived + stateless.
-  contract: { mount: { kind: "middleware", symbol: "mountContract", from: "./routes/contract" } },
+  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"],
+    env: [
+      { name: "STRIPE_SECRET_KEY", required: true, secret: true, hint: "your Stripe secret key" },
+      { name: "STRIPE_PUBLISHABLE_KEY", hint: "returned by GET /api/billing/payment-config" },
+    ],
+  },
+  cost: { mount: { kind: "route", path: "/api/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" }, deps: ["@suluk/cost"] },
+  erasure: { mount: { kind: "route", path: "/api/erasure", symbol: "erasureRoutes", from: "./routes/erasure" }, provision: { symbol: "erasureProvision", from: "./src/provision/erasure" }, deps: ["@suluk/better-auth"] },
+  email: {
+    mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" }, // stateless binding — no provision fragment (C052)
+    deps: ["@suluk/email"],
+    env: [
+      { name: "RESEND_API_KEY", secret: true, hint: "omit → the console provider (dev)" },
+      { name: "EMAIL_FROM", hint: "the from-address" },
+      { name: "BRAND_NAME", hint: "email template branding" },
+      { name: "BASE_URL", hint: "email link base" },
+      { name: "ENVIRONMENT", hint: '"production" → use Resend (else console)' },
+    ],
+  },
+  webhooks: {
+    mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" },
+    provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" },
+    deps: ["@suluk/payments"],
+    env: [{ name: "STRIPE_WEBHOOK_SECRET", required: true, secret: true, hint: "verifies inbound Stripe events (POST /api/webhooks/stripe)" }],
+  },
   // cross-cutting MIDDLEWARE (apply globally via app.use, emitted before any route) — not routed resources.
-  "rate-limit": { mount: { kind: "middleware", symbol: "mountRateLimit", from: "./services/rate-limit" } },
-  "rate-credit": { mount: { kind: "middleware", symbol: "mountRateCredit", from: "./services/rate-credit" } }, // credit-backed free-tier bucket (KV binding)
-  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",
+  wrangler: "^4.0.0",
+};
+
+/** 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";
+}
+
+/** The env vars the selected services need, de-duped by name (first declaration wins). Split with `.secret` into the
+ *  `.env` secrets (the .env.temp lifecycle) vs the non-secret CONFIG (defined in platform.config.ts `vars` → wrangler `[vars]`). */
+export function collectEnv(services: string[]): EnvVar[] {
+  const seen = new Set<string>();
+  const out: EnvVar[] = [];
+  for (const s of services) for (const e of CATALOG[s]?.env ?? []) if (!seen.has(e.name)) (seen.add(e.name), out.push(e));
+  return out;
+}
+
 /** 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, mergeWranglerToml, 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,51 @@ 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");
+  // wrangler.toml MERGES (preserve the operator's provisioned binding ids across a regen); .env.example + the env-check
+  // preflight always (re)written (a template + a script, no secrets); tsconfig/components.json/.gitignore left if present.
+  log("▸ writing wrangler.toml");
+  await opts.write("wrangler.toml", mergeWranglerToml(plan.wranglerToml, await read("wrangler.toml")));
+  written.push("wrangler.toml");
+  for (const [file, content, always] of [
+    ["tsconfig.json", plan.tsconfig, false],
+    ["components.json", plan.componentsJson, false],
+    [".gitignore", plan.gitignore, false],
+    [".env.example", plan.envExample, true], // a checked-in template (no values) — keep it current
+    ["scripts/env-check.ts", plan.envCheck, true], // the .env.temp lifecycle preflight
+  ] as const) {
+    if (always || (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, collectEnv, resolveVersion, BASE_DEPS, ECOSYSTEM_VERSIONS, DEV_DEPS, type CatalogEntry, type Mount, type EnvVar } from "./catalog";
 export { mergeProvision } from "./merge";
-export { planPlatform, type PlatformPlan } from "./plan";
+export { planPlatform, buildPackageJson, mergePackageJson, mergeWranglerToml, 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). */
@@ -17,6 +20,12 @@ export interface PlatformManifest {
    * `mountAuthRoutes(app, {...})`. Only JSON-safe values (no functions/env-refs — edit the generated entry for those).
    */
   opts?: Record<string, Record<string, unknown>>;
+  /**
+   * NON-SECRET config values (`BASE_URL`, `EMAIL_FROM`, `TRUSTED_ORIGINS`, `ENVIRONMENT`, `STRIPE_PUBLISHABLE_KEY`, …) —
+   * defined HERE, in the committed manifest, and generated into `wrangler.toml` `[vars]`. SECRETS never go here; they live
+   * in `.env` (see the generated `.env.example` + the env-check preflight). Keyed by the env var name.
+   */
+  vars?: Record<string, string>;
 }
 
 /** 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, collectEnv, BASE_DEPS, DEV_DEPS, resolveVersion, type EnvVar } from "./catalog";
 
 export interface PlatformPlan {
   services: string[];
@@ -14,20 +14,261 @@ 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;
+  /** the generated `.env.example` — the SECRET keys the selected services need (non-secrets live in the manifest `vars`). */
+  envExample: string;
+  /** the generated `wrangler.toml` — `[vars]` from the manifest's non-secret config + the D1/KV binding placeholders. */
+  wranglerToml: string;
+  /** the generated `.gitignore` (ignores `.env`, `.env.temp`, `.dev.vars`, …). */
+  gitignore: string;
+  /** the generated `scripts/env-check.ts` — the `.env.temp` lifecycle preflight (create when secrets missing, delete when ready). */
+  envCheck: string;
 }
 
 export function planPlatform(manifest: PlatformManifest): PlatformPlan {
   const services = orderServices(manifest.services);
   const unknown = services.filter((s) => !CATALOG[s]);
   if (unknown.length) throw new Error(`platform: unknown service(s) [${unknown.join(", ")}] — not in the catalog`);
+  const env = collectEnv(services);
   return {
     services,
     adds: services.map((s) => `${manifest.registry}/${s}`),
     entry: buildEntry(services, manifest.opts),
     provisionConfig: buildProvisionConfig(services),
+    packageJson: buildPackageJson(manifest.name, services),
+    tsconfig: buildTsconfig(),
+    componentsJson: buildComponentsJson(),
+    envExample: buildEnvExample(env),
+    wranglerToml: buildWranglerToml(manifest.name, services, env, manifest.vars ?? {}),
+    gitignore: buildGitignore(),
+    envCheck: buildEnvCheckScript(env),
   };
 }
 
+/** The SECRET env keys → `.env.example` (required uncommented `KEY=`, optional commented `# KEY=`), each with its hint.
+ *  Non-secret config is NOT here — it's in the manifest `vars` → wrangler `[vars]`. Safe to commit (no values). */
+function buildEnvExample(env: EnvVar[]): string {
+  const secrets = env.filter((e) => e.secret);
+  const line = (e: EnvVar, commented: boolean) => `${commented ? "# " : ""}${e.name}=${e.hint ? `        # ${e.hint}` : ""}`;
+  const required = secrets.filter((e) => e.required);
+  const optional = secrets.filter((e) => !e.required);
+  return [
+    "# .env — SECRET keys (generated from platform.config.ts). Copy the values in; never commit this file.",
+    "# Non-secret config lives in platform.config.ts `vars` (→ wrangler.toml [vars]), NOT here.",
+    "",
+    "# Required — the app won't start without these:",
+    ...required.map((e) => line(e, false)),
+    "",
+    "# Optional:",
+    ...optional.map((e) => line(e, true)),
+    "",
+  ].join("\n");
+}
+
+/** The `wrangler.toml` — `[vars]` from the manifest's non-secret config (unset ones commented with a hint) + the D1 binding
+ *  (always) + a KV binding when rate-credit is selected. `generate` merges it so provisioned binding ids survive a regen. */
+function buildWranglerToml(name: string, services: string[], env: EnvVar[], vars: Record<string, string>): string {
+  const nonSecret = env.filter((e) => !e.secret);
+  const varLines = nonSecret.map((e) =>
+    vars[e.name] !== undefined
+      ? `${e.name} = ${JSON.stringify(vars[e.name])}`
+      : `# ${e.name} = ""        # ${e.hint ?? "set in platform.config.ts `vars`"}`,
+  );
+  const kv: string[] = [];
+  if (services.includes("rate-credit")) kv.push('\n[[kv_namespaces]]\nbinding = "RATE_CREDIT_KV"\nid = ""                 # ← `wrangler kv namespace create RATE_CREDIT_KV`');
+  if (services.includes("rate-limit")) kv.push('\n[[kv_namespaces]]\nbinding = "RATE_LIMIT_KV"\nid = ""                 # optional durable rate-limit store');
+  return [
+    `# AUTO-GENERATED by @suluk/platform — [vars] come from platform.config.ts \`vars\`; the binding ids are yours (from`,
+    `# \`suluk-provision apply\` / \`wrangler kv namespace create\`) and are PRESERVED across a regenerate.`,
+    `name = ${JSON.stringify(name)}`,
+    `main = "src/index.ts"`,
+    `compatibility_date = "2026-07-01"`,
+    "",
+    "[vars]",
+    ...varLines,
+    "",
+    "[[d1_databases]]",
+    `binding = "DB"`,
+    `database_name = ${JSON.stringify(name)}`,
+    `database_id = ""        # ← the id \`suluk-provision apply\` lands`,
+    ...kv,
+    "",
+  ].join("\n");
+}
+
+/** Preserve the operator's provisioned binding ids (keyed by `binding = "NAME"`) across a wrangler.toml regenerate. */
+export function mergeWranglerToml(generated: string, existing: string | null): string {
+  if (!existing) return generated;
+  const ids = new Map<string, string>();
+  let cur: string | null = null;
+  for (const l of existing.split("\n")) {
+    const b = l.match(/^\s*binding\s*=\s*"([^"]+)"/);
+    if (b) {
+      cur = b[1];
+      continue;
+    }
+    const id = l.match(/^\s*(?:database_id|id)\s*=\s*"([^"]+)"/);
+    if (id && cur && id[1]) ids.set(cur, id[1]);
+  }
+  if (!ids.size) return generated;
+  cur = null;
+  return generated
+    .split("\n")
+    .map((l) => {
+      const b = l.match(/^\s*binding\s*=\s*"([^"]+)"/);
+      if (b) {
+        cur = b[1];
+        return l;
+      }
+      const m = l.match(/^(\s*(?:database_id|id)\s*=\s*)""(.*)$/);
+      if (m && cur && ids.has(cur)) return `${m[1]}${JSON.stringify(ids.get(cur))}${m[2]}`;
+      return l;
+    })
+    .join("\n");
+}
+
+function buildGitignore(): string {
+  return ["node_modules/", ".env", ".env.temp", ".dev.vars", ".wrangler/", "dist/", ""].join("\n");
+}
+
+/** The `.env.temp` lifecycle preflight (run via `predev` / `bun run check`): if every REQUIRED secret is present (in `.env`
+ *  or the process env), delete `.env.temp`; else write `.env.temp` from `.env.example` + report the missing keys + fail. */
+function buildEnvCheckScript(env: EnvVar[]): string {
+  const required = env.filter((e) => e.secret && e.required).map((e) => e.name);
+  return `#!/usr/bin/env bun
+/**
+ * AUTO-GENERATED by @suluk/platform — the .env lifecycle. Wired as \`predev\` (runs before \`dev\`) + \`bun run check\`.
+ * The MINIMUM secret keys this app needs come from platform.config.ts (the selected modules). Non-secret config is in
+ * the manifest \`vars\` → wrangler.toml [vars], not here.
+ */
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+
+const REQUIRED = ${JSON.stringify(required)};
+const ENV = ".env", TEMP = ".env.temp", EXAMPLE = ".env.example";
+
+const parse = (p: string): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const line of readFileSync(p, "utf8").split("\\n")) {
+    const m = line.match(/^\\s*([A-Z0-9_]+)\\s*=\\s*(.*)$/);
+    if (m && m[2].trim()) out[m[1]] = m[2].trim();
+  }
+  return out;
+};
+
+const have = existsSync(ENV) ? parse(ENV) : {};
+const missing = REQUIRED.filter((k) => !have[k] && !process.env[k]);
+
+if (missing.length === 0) {
+  if (existsSync(TEMP)) { rmSync(TEMP); console.log("✓ .env ready — removed .env.temp"); }
+  else console.log("✓ .env ready (all required secrets present).");
+  process.exit(0);
+}
+
+// not ready → drop a fill-me-in template so you can see exactly what's needed.
+if (existsSync(EXAMPLE)) writeFileSync(TEMP, readFileSync(EXAMPLE, "utf8"));
+console.error("✗ missing required secret(s): " + missing.join(", "));
+console.error("  → wrote .env.temp — fill the values in and save it as .env (or inject the secrets another way).");
+console.error("    .env.temp auto-deletes once .env has every required secret.");
+process.exit(1);
+`;
+}
+
+/** The framework baseline package.json — name from the manifest, the union of BASE + each service's deps (versions
+ *  resolved: @suluk/* → "latest", ecosystem → pinned), + the toolchain devDeps + the regenerate/typecheck scripts. */
+export function buildPackageJson(name: string, services: string[]): string {
+  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 the scaffold config + src/index.ts + provision.config.ts
+      check: "bun run scripts/env-check.ts", // the .env.temp lifecycle (fails if a required secret is missing)
+      predev: "bun run scripts/env-check.ts", // runs automatically before `dev`
+      dev: "wrangler dev",
+      deploy: "wrangler deploy",
+      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[] = [];

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, 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
@@ -151,18 +151,95 @@ 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 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() {