@suluk/platform 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/platform",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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,6 +11,18 @@ 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;
@@ -21,11 +33,23 @@ export interface CatalogEntry {
    *  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" }, deps: ["better-auth", "@better-auth/api-key", "@better-auth/passkey", "@suluk/better-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" }, deps: ["@suluk/hono", "zod"] },
@@ -34,11 +58,34 @@ export const CATALOG: Record<string, CatalogEntry> = {
   // feature routes mount under /api/* — where the caller-resolution + cors + rate-limit middleware live (toolfactory parity).
   credits: { mount: { kind: "route", path: "/api/credits", symbol: "creditsRoutes", from: "./routes/credits" }, provision: { symbol: "creditsProvision", from: "./src/provision/credits" }, deps: ["@suluk/credits"] },
   keys: { mount: { kind: "route", path: "/api/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" }, deps: ["@suluk/keys"] },
-  billing: { mount: { kind: "route", path: "/api/billing", symbol: "billingRoutes", from: "./routes/billing" }, provision: { symbol: "billingProvision", from: "./src/provision/billing" }, deps: ["@suluk/billing", "@suluk/payments", "@suluk/credits"] },
+  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" }, 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"] },
+  email: {
+    mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" }, // stateless binding — no provision fragment (C052)
+    deps: ["@suluk/email"],
+    env: [
+      { name: "RESEND_API_KEY", secret: true, hint: "omit → the console provider (dev)" },
+      { name: "EMAIL_FROM", hint: "the from-address" },
+      { name: "BRAND_NAME", hint: "email template branding" },
+      { name: "BASE_URL", hint: "email link base" },
+      { name: "ENVIRONMENT", hint: '"production" → use Resend (else console)' },
+    ],
+  },
+  webhooks: {
+    mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" },
+    provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" },
+    deps: ["@suluk/payments"],
+    env: [{ name: "STRIPE_WEBHOOK_SECRET", required: true, secret: true, hint: "verifies inbound Stripe events (POST /api/webhooks/stripe)" }],
+  },
   // cross-cutting MIDDLEWARE (apply globally via app.use, emitted before any route) — not routed resources.
   "rate-limit": { mount: { kind: "middleware", symbol: "mountRateLimit", from: "./services/rate-limit" }, deps: ["@suluk/hono"] },
   "rate-credit": { mount: { kind: "middleware", symbol: "mountRateCredit", from: "./services/rate-credit" } }, // credit-backed free-tier bucket (KV binding); base deps cover it
@@ -75,6 +122,7 @@ 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 →
@@ -84,6 +132,15 @@ export function resolveVersion(dep: string): string {
   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,7 +5,7 @@
  * testable. Stops short of `provision apply` — that's a live infra op the operator triggers.
  */
 import type { PlatformManifest } from "./manifest";
-import { planPlatform, mergePackageJson, type PlatformPlan } from "./plan";
+import { planPlatform, mergePackageJson, mergeWranglerToml, mergeGitignore, type PlatformPlan } from "./plan";
 
 export interface GenerateOptions {
   /** run a command — the CLI spawns `bunx shadcn add <ref>`; a test records. */
@@ -38,8 +38,23 @@ export async function generatePlatform(manifest: PlatformManifest, opts: Generat
   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) {
+  // 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");
+  // .gitignore MERGES (append missing entries) — critically ensures .env/.env.temp are ignored even if the app already had
+  // a minimal .gitignore, so secrets are never committed. .env.example + the env-check are always (re)written (no values).
+  log("▸ writing .gitignore");
+  await opts.write(".gitignore", mergeGitignore(plan.gitignore, await read(".gitignore")));
+  written.push(".gitignore");
+  for (const [file, content, always] of [
+    ["tsconfig.json", plan.tsconfig, false],
+    ["components.json", plan.componentsJson, 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);

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, resolveVersion, BASE_DEPS, ECOSYSTEM_VERSIONS, DEV_DEPS, 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, buildPackageJson, mergePackageJson, type PlatformPlan } from "./plan";
+export { planPlatform, buildPackageJson, mergePackageJson, mergeWranglerToml, mergeGitignore, type PlatformPlan } from "./plan";
 export { generatePlatform, type GenerateOptions, type GenerateResult } from "./generate";

package/src/manifest.ts

@@ -20,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, BASE_DEPS, DEV_DEPS, resolveVersion } from "./catalog";
+import { CATALOG, orderServices, collectEnv, BASE_DEPS, DEV_DEPS, resolveVersion, type EnvVar } from "./catalog";
 
 export interface PlatformPlan {
   services: string[];
@@ -21,12 +21,21 @@ export interface PlatformPlan {
   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}`),
@@ -35,9 +44,153 @@ export function planPlatform(manifest: PlatformManifest): PlatformPlan {
     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");
+}
+
+/** Merge the generated .gitignore into an existing one — APPEND any missing entries (never skip-if-present, so an app's
+ *  minimal .gitignore can't leave `.env`/`.env.temp` UNIGNORED and risk committing secrets). Dedup, preserve app entries. */
+export function mergeGitignore(generated: string, existing: string | null): string {
+  if (!existing) return generated;
+  const norm = (s: string) => s.trim().replace(/\/$/, "");
+  const have = new Set(existing.split("\n").map(norm).filter(Boolean));
+  const add = generated.split("\n").filter((l) => l.trim() && !have.has(norm(l)));
+  if (!add.length) return existing.endsWith("\n") ? existing : existing + "\n";
+  const base = existing.replace(/\n*$/, "");
+  return `${base}\n${add.join("\n")}\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 {
@@ -50,7 +203,11 @@ export function buildPackageJson(name: string, services: string[]): string {
     private: true,
     type: "module",
     scripts: {
-      generate: "suluk-platform", // re-pull modules + rewrite src/index.ts + provision.config.ts + this config
+      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",
     },

package/test/plan.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { definePlatform, planPlatform, mergeProvision, generatePlatform, buildPackageJson, mergePackageJson } from "../src/index";
+import { definePlatform, planPlatform, mergeProvision, generatePlatform, buildPackageJson, mergePackageJson, mergeWranglerToml, mergeGitignore } from "../src/index";
 import type { InstanceSpec } from "@suluk/provision";
 
 /** C051 — the platform generator: manifest → plan (adds + wired entry + merged provision), the provision merge, and the
@@ -161,12 +161,12 @@ describe("generatePlatform — the orchestration (with recorders)", () => {
     });
     expect(ran).toEqual(plannedAdds()); // exactly the planned adds, in order
     expect(ran.length).toBe(6); // app+auth+credits+keys+billing+logs
-    // 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"]);
+    // config is written BEFORE the shadcn adds; the glue after. env-example + env-check + wrangler + gitignore included.
+    expect(wrote).toEqual(["package.json", "wrangler.toml", ".gitignore", "tsconfig.json", "components.json", ".env.example", "scripts/env-check.ts", "src/index.ts", "provision.config.ts"]);
     expect(res.added.length).toBe(6);
   });
 
-  test("leaves an existing tsconfig/components.json untouched but always (re)writes package.json", async () => {
+  test("leaves an existing tsconfig/components.json untouched; always (re)writes package.json/.gitignore/.env.example", async () => {
     const wrote: string[] = [];
     await generatePlatform(manifest, {
       run: async () => {},
@@ -174,8 +174,48 @@ describe("generatePlatform — the orchestration (with recorders)", () => {
       read: async (p) => (p === "package.json" ? '{"name":"x","dependencies":{"my-lib":"^1.0.0"}}' : "existing"),
     });
     expect(wrote).toContain("package.json"); // merged + rewritten
+    expect(wrote).toContain(".gitignore"); // MERGED (never skip — must ensure .env is ignored)
+    expect(wrote).toContain(".env.example"); // template — always current
+    expect(wrote).toContain("scripts/env-check.ts");
     expect(wrote).not.toContain("tsconfig.json"); // present → left as-is
-    expect(wrote).not.toContain("components.json");
+  });
+
+  test("mergeGitignore appends missing entries so .env is always ignored", () => {
+    const merged = mergeGitignore("node_modules/\n.env\n.env.temp\n", "node_modules\n");
+    expect(merged).toContain(".env");
+    expect(merged).toContain(".env.temp");
+    expect(merged.match(/node_modules/g)?.length).toBe(1); // deduped (node_modules vs node_modules/)
+  });
+});
+
+describe("env — secrets in .env (temp lifecycle), non-secrets in the manifest vars", () => {
+  test(".env.example lists ONLY required + optional secrets, never non-secret config", () => {
+    const p = planPlatform(definePlatform({ name: "e", registry: "acme/reg", services: ["auth", "billing", "webhooks", "email"] }));
+    expect(p.envExample).toContain("BETTER_AUTH_SECRET="); // required secret, uncommented
+    expect(p.envExample).toContain("STRIPE_SECRET_KEY=");
+    expect(p.envExample).toContain("STRIPE_WEBHOOK_SECRET=");
+    expect(p.envExample).toContain("# RESEND_API_KEY="); // optional secret, commented
+    expect(p.envExample).not.toContain("BASE_URL"); // non-secret → the manifest vars, NOT .env
+    expect(p.envExample).not.toContain("TRUSTED_ORIGINS");
+  });
+
+  test("wrangler.toml [vars] come from the manifest vars; unset non-secrets are commented; D1 binding present", () => {
+    const p = planPlatform(definePlatform({ name: "myapp", registry: "acme/reg", services: ["auth", "email", "rate-credit"], vars: { BASE_URL: "https://x.dev", ENVIRONMENT: "production" } }));
+    expect(p.wranglerToml).toContain('BASE_URL = "https://x.dev"'); // set in the manifest
+    expect(p.wranglerToml).toContain('ENVIRONMENT = "production"');
+    expect(p.wranglerToml).toContain("# EMAIL_FROM ="); // unset → commented
+    expect(p.wranglerToml).toContain('binding = "DB"');
+    expect(p.wranglerToml).toContain('binding = "RATE_CREDIT_KV"'); // rate-credit selected
+    expect(p.wranglerToml).not.toContain("BETTER_AUTH_SECRET"); // secrets never in [vars]
+  });
+
+  test("the env-check script bakes in the required secrets; merge preserves provisioned binding ids", () => {
+    const p = planPlatform(definePlatform({ name: "e", registry: "acme/reg", services: ["auth", "billing"] }));
+    expect(p.envCheck).toContain('["BETTER_AUTH_SECRET","STRIPE_SECRET_KEY"]');
+    expect(p.envCheck).toContain(".env.temp");
+    // wrangler merge keeps the operator's database_id across a regen
+    const merged = mergeWranglerToml(p.wranglerToml, 'name="e"\n[[d1_databases]]\nbinding = "DB"\ndatabase_id = "abc-123"');
+    expect(merged).toContain('database_id = "abc-123"');
   });
 });