@suluk/platform 0.2.1 → 0.3.1

package/package.json

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

@@ -26,7 +26,7 @@ export const CATALOG: Record<string, CatalogEntry> = Object.fromEntries(Object.e
  * 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"];
+export const BASE_DEPS = ["@suluk/platform", "@suluk/provision", "@suluk/core", "@suluk/env", "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). */

package/src/generate.ts

@@ -46,16 +46,19 @@ export async function generatePlatform(input: PlatformManifest | Platform, opts:
   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).
+  // .gitignore MERGES (append missing entries) — ensures `.env.keys` (the PRIVATE key) + `.env.temp` are ignored. `.env`
+  // itself is COMMITTED (its secret values encrypted by @suluk/env). .env.example + env.ts + env-check are always (re)written.
   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
+    [".env.example", plan.envExample, true], // a checked-in keys checklist (no values)
+    ["scripts/env-check.ts", plan.envCheck, true], // the encrypted-env preflight
+    ["src/env.ts", plan.envTs, true], // the @suluk/env declare-once (derived from the manifest's secrets)
+    ["scripts/sync-secrets.ts", plan.syncSecrets, true], // the deploy-time secret push (derived)
+    [".env", plan.envScaffold, false], // the COMMITTED encrypted-secrets file — SCAFFOLD IF ABSENT (never clobber secrets)
   ] as const) {
     if (always || (await read(file)) == null) {
       log(`▸ writing ${file}`);

package/src/plan.ts

@@ -27,10 +27,18 @@ export interface PlatformPlan {
   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`, …). */
+  /** the generated `.gitignore` — ignores `.env.keys` (the private key) + `.env.temp`, but NOT `.env` (committed ENCRYPTED). */
   gitignore: string;
-  /** the generated `scripts/env-check.ts` — the `.env.temp` lifecycle preflight (create when secrets missing, delete when ready). */
+  /** the generated `scripts/env-check.ts` — the encrypted-env preflight (keypair present? required secrets set + encrypted?). */
   envCheck: string;
+  /** the generated `src/env.ts` — the @suluk/env `defineEnv` declaration (declare-once: the app's secrets, surfaced). */
+  envTs: string;
+  /** the generated `scripts/sync-secrets.ts` — decrypt the cloudflare-surfaced secrets from the committed .env and push them
+   *  as `wrangler secret`s (the toolfactory-exact deploy path; the alternative is the entry's runtime `loadEnv`). */
+  syncSecrets: string;
+  /** the generated `.env` SCAFFOLD (committed) — a header + the setup steps, NO values. `generate` writes it only if absent
+   *  (never clobbering the operator's encrypted secrets). Secret VALUES are added encrypted via `suluk-env set`. */
+  envScaffold: string;
 }
 
 export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
@@ -61,9 +69,15 @@ export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
     wranglerToml: buildWranglerToml(manifest.name, services, env, manifest.vars ?? {}),
     gitignore: buildGitignore(),
     envCheck: buildEnvCheckScript(env),
+    envTs: buildEnvTs(env),
+    syncSecrets: buildSyncSecrets(),
+    envScaffold: buildEnvScaffold(env),
   };
 }
 
+/** the app's SECRET env vars (the ones committed ENCRYPTED in `.env` + decrypted at runtime). */
+const secretsOf = (env: EnvVar[]): EnvVar[] => env.filter((e) => e.secret);
+
 /** 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 {
@@ -72,7 +86,9 @@ function buildEnvExample(env: EnvVar[]): string {
   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.",
+    "# .env keys checklist (generated). The `.env` is COMMITTED with these values ENCRYPTED (@suluk/env, ML-KEM-768):",
+    "#   bunx suluk-env keygen                 # once — keypair (SULUK_PUBLIC_KEY → .env; private → .env.keys, gitignored)",
+    "#   bunx suluk-env set KEY=value          # per secret — encrypts it into .env",
     "# Non-secret config lives in platform.config.ts `vars` (→ wrangler.toml [vars]), NOT here.",
     "",
     "# Required — the app won't start without these:",
@@ -84,6 +100,76 @@ function buildEnvExample(env: EnvVar[]): string {
   ].join("\n");
 }
 
+/**
+ * `src/env.ts` — the @suluk/env `defineEnv` DECLARE-ONCE for the app's SECRETS (from the catalog's secret env metadata). Each
+ * secret is `surfaces: ["cloudflare"]` (a Worker-runtime secret); `sync-secrets` reads `forSurface("cloudflare")` to know what
+ * to push, and the values live ENCRYPTED in the committed `.env`. Non-secret config stays in the manifest `vars` → [vars].
+ */
+function buildEnvTs(env: EnvVar[]): string {
+  const secrets = secretsOf(env);
+  const spec = secrets
+    .map((e) => `  ${e.name}: { secret: true, ${e.required ? "required: true, " : ""}surfaces: ["cloudflare"]${e.hint ? `, description: ${JSON.stringify(e.hint)}` : ""} },`)
+    .join("\n");
+  return [
+    "// AUTO-GENERATED by @suluk/platform — the @suluk/env declare-once for this app's SECRETS. Values live ENCRYPTED in the",
+    "// committed .env (ML-KEM-768). Non-secret config is in platform.config.ts `vars` → wrangler.toml [vars].",
+    'import { defineEnv } from "@suluk/env";',
+    "",
+    "export const env = defineEnv({",
+    spec,
+    "});",
+    "",
+  ].join("\n");
+}
+
+/**
+ * `scripts/sync-secrets.ts` — the deploy-time path (toolfactory-exact): decrypt the cloudflare-surfaced secrets from the
+ * committed .env (the private key comes from `.env.keys` / `~/.suluk` / `SULUK_PRIVATE_KEY`) and push each as a `wrangler
+ * secret`. Idempotent. The alternative is the runtime `loadEnv` in `src/index.ts` (set SULUK_PRIVATE_KEY as a wrangler secret).
+ */
+function buildSyncSecrets(): string {
+  return `#!/usr/bin/env bun
+// AUTO-GENERATED by @suluk/platform. Push the committed, @suluk/env-encrypted secrets to the Worker as \`wrangler secret\`s.
+// Run at deploy: \`bun run sync-secrets\`. Needs the private key (.env.keys / ~/.suluk / SULUK_PRIVATE_KEY) + a CF-authed wrangler.
+import { loadEnvFile } from "@suluk/env/node";
+import { env } from "../src/env";
+
+const values = await loadEnvFile(); // decrypt every value in .env into a { KEY: value } record
+const names = env.forSurface("cloudflare").filter((k) => values[k] !== undefined && values[k] !== "");
+if (!names.length) {
+  console.log("no cloudflare-surfaced secrets are set in .env yet — run \`bunx suluk-env set KEY=value\` first.");
+  process.exit(0);
+}
+for (const name of names) {
+  const proc = Bun.spawn(["wrangler", "secret", "put", name], { stdin: "pipe", stdout: "inherit", stderr: "inherit" });
+  proc.stdin.write(values[name]);
+  await proc.stdin.end();
+  if ((await proc.exited) !== 0) { console.error(\`✗ failed to put \${name}\`); process.exit(1); }
+  console.log(\`✓ \${name}\`);
+}
+console.log(\`✓ synced \${names.length} secret(s) to the Worker.\`);
+`;
+}
+
+/**
+ * The `.env` SCAFFOLD — a header + setup steps, NO values (safe to commit). `generate` writes it ONLY IF ABSENT so it never
+ * clobbers the operator's encrypted secrets. Its presence also lets `src/index.ts`'s `import "../.env"` resolve on a fresh app.
+ */
+function buildEnvScaffold(env: EnvVar[]): string {
+  const required = secretsOf(env).filter((e) => e.required);
+  return [
+    "# This file is COMMITTED. Secret VALUES are stored ENCRYPTED (@suluk/env, post-quantum ML-KEM-768) — safe to push to git.",
+    "# Setup:",
+    "#   bunx suluk-env keygen              # keypair: SULUK_PUBLIC_KEY here (commit); private key → .env.keys (gitignored)",
+    "#   bunx suluk-env set BETTER_AUTH_SECRET=...   # encrypts + adds each secret" + (required.length ? ` (required: ${required.map((e) => e.name).join(", ")})` : ""),
+    "# Get the secrets into the Worker EITHER way:",
+    "#   • runtime:  `wrangler secret put SULUK_PRIVATE_KEY`  → src/index.ts decrypts this file on the first request",
+    "#   • deploy:   `bun run sync-secrets`                    → pushes each secret via `wrangler secret put`",
+    "# NEVER commit a plaintext secret — `suluk-env set` encrypts; `bunx suluk-env encrypt` seals any leftover plaintext.",
+    "",
+  ].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 {
@@ -147,60 +233,66 @@ export function mergeWranglerToml(generated: string, existing: string | null): s
 }
 
 function buildGitignore(): string {
-  return ["node_modules/", ".env", ".env.temp", ".dev.vars", ".wrangler/", "dist/", ""].join("\n");
+  // NOTE: `.env` is NOT ignored — it is COMMITTED with its secret values ENCRYPTED (@suluk/env). The PRIVATE key
+  // (`.env.keys`) is what must never be committed; that + `.env.temp`/`.dev.vars` are ignored.
+  return ["node_modules/", ".env.keys", ".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. */
+ *  minimal .gitignore can't leave `.env.keys`/`.env.temp` UNIGNORED and risk committing the private key). Dedup, preserve app
+ *  entries. ENCRYPTED-ENV TRANSITION: if the new baseline ignores `.env.keys` (the private key) but NOT `.env`, a plaintext-era
+ *  `.env` ignore is REMOVED — the .env is now COMMITTED with its values encrypted, so ignoring it is wrong (and safe to undo). */
 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 genLines = generated.split("\n").map(norm);
+  const encryptedModel = genLines.includes(".env.keys") && !genLines.includes(".env");
+  const existingClean = encryptedModel ? existing.split("\n").filter((l) => norm(l) !== ".env").join("\n") : existing;
+  const have = new Set(existingClean.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*$/, "");
+  if (!add.length) return existingClean.endsWith("\n") ? existingClean : existingClean + "\n";
+  const base = existingClean.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. */
+/** The encrypted-env preflight (run via `predev` / `bun run check`): is there a keypair, and is every REQUIRED secret set
+ *  (encrypted) in the committed `.env`? A plaintext secret sitting in `.env` is flagged (encrypt it before you commit). */
 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.
+ * AUTO-GENERATED by @suluk/platform — the ENCRYPTED-env preflight (wired as \`predev\` + \`bun run check\`). Secrets live in the
+ * committed .env, ENCRYPTED with @suluk/env. This checks: a keypair exists, the REQUIRED secrets are set, and none is sitting
+ * in plaintext (which must never be committed). Non-secret config is in platform.config.ts \`vars\` → wrangler.toml [vars].
  */
-import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 const REQUIRED = ${JSON.stringify(required)};
-const ENV = ".env", TEMP = ".env.temp", EXAMPLE = ".env.example";
+const ENV = ".env";
 
 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();
+    if (m && m[2].trim()) out[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
   }
   return out;
 };
 
 const have = existsSync(ENV) ? parse(ENV) : {};
+const isEncrypted = (v: string) => v.startsWith("encrypted:");
+const fail = (msg: string) => { console.error("✗ " + msg); process.exit(1); };
+
+if (!have.SULUK_PUBLIC_KEY) fail("no @suluk/env keypair — run \`bunx suluk-env keygen\` (creates SULUK_PUBLIC_KEY in .env + .env.keys).");
+
 const missing = REQUIRED.filter((k) => !have[k] && !process.env[k]);
+if (missing.length) fail("missing required secret(s): " + missing.join(", ") + "\\n  → set each: bunx suluk-env set KEY=value");
 
-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);
-}
+const plaintext = Object.keys(have).filter((k) => k !== "SULUK_PUBLIC_KEY" && have[k] && !isEncrypted(have[k]));
+if (plaintext.length) fail("PLAINTEXT secret(s) in .env (never commit these): " + plaintext.join(", ") + "\\n  → encrypt: bunx suluk-env encrypt");
 
-// 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);
+console.log("✓ .env ready — keypair present, required secrets set + encrypted.");
+process.exit(0);
 `;
 }
 
@@ -217,10 +309,13 @@ export function buildPackageJson(name: string, services: string[], catalog: Reco
     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)
+      check: "bun run scripts/env-check.ts", // the encrypted-env preflight (keypair present? required secrets set + encrypted?)
       predev: "bun run scripts/env-check.ts", // runs automatically before `dev`
       dev: "wrangler dev",
       deploy: "wrangler deploy",
+      "env:keygen": "suluk-env keygen", // create the @suluk/env keypair (SULUK_PUBLIC_KEY → .env; private → .env.keys)
+      "env:set": "suluk-env set", // encrypt + add a secret: `bun run env:set BETTER_AUTH_SECRET=...`
+      "sync-secrets": "bun run scripts/sync-secrets.ts", // decrypt cloudflare-surfaced secrets → `wrangler secret put` each
       typecheck: "tsc --noEmit -p .",
       test: "bun test",
     },
@@ -295,7 +390,12 @@ function buildComponentsJson(): string {
 }
 
 function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>, wiring?: Wiring, catalog: Record<string, Service> = CORE_SERVICES): string {
-  const imports = ['import { createApp } from "./app";'];
+  const imports = [
+    'import { createApp } from "./app";',
+    'import { loadEnv } from "@suluk/env";',
+    "// @ts-ignore — the committed, @suluk/env-encrypted .env, bundled as text (bun + wrangler text import).",
+    'import envText from "../.env" with { type: "text" };',
+  ];
   const middleware: string[] = [];
   const routes: string[] = [];
   const hooksByService = wiring?.hooksByService ?? {};
@@ -339,7 +439,20 @@ function buildEntry(services: string[], opts?: Record<string, Record<string, unk
   });
   for (const line of groupImports(safeWireImports)) imports.push(line);
   const body = ["const app = createApp();", ...middleware, ...routes];
-  return `// AUTO-GENERATED by @suluk/platform from platform.config.ts — the wired Hono entry. Edit freely.\n${imports.join("\n")}\n\n${body.join("\n")}\n\nexport default app;\n`;
+  // the @suluk/env bootstrap: the committed .env holds the app's secrets ENCRYPTED. If SULUK_PRIVATE_KEY is set (a wrangler
+  // secret), decrypt them into the request env on first use (the runtime path); otherwise this is a no-op and the secrets come
+  // from `wrangler secret put` (the `bun run sync-secrets` deploy path). Decrypt once per isolate (env is stable across requests).
+  const bootstrap = [
+    "let secrets: Record<string, string> | null = null;",
+    "export default {",
+    "  async fetch(request: Request, env: Record<string, unknown>, ctx: ExecutionContext): Promise<Response> {",
+    "    if (!secrets && typeof env.SULUK_PRIVATE_KEY === \"string\") secrets = await loadEnv({ content: envText, privateKey: env.SULUK_PRIVATE_KEY });",
+    "    const merged = secrets ? { ...secrets, ...env } : env;",
+    "    return app.fetch(request, merged as Parameters<typeof app.fetch>[1], ctx);",
+    "  },",
+    "};",
+  ];
+  return `// AUTO-GENERATED by @suluk/platform from platform.config.ts — the wired Hono entry. Edit freely.\n${imports.join("\n")}\n\n${body.join("\n")}\n\n${bootstrap.join("\n")}\n`;
 }
 
 function buildProvisionConfig(services: string[], catalog: Record<string, Service> = CORE_SERVICES): string {