@suluk/platform 0.4.2 → 0.5.1

package/package.json

@@ -1,35 +1,39 @@
 {
   "name": "@suluk/platform",
-  "version": "0.4.2",
+  "version": "0.5.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"
-},
-"license": "Apache-2.0",
-"repository": {
-"type": "git",
-"url": "git+https://github.com/MahmoodKhalil57/suluk.git",
-"directory": "tooling/ts/packages/platform"
-},
-"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
-"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
-"type": "module",
-"files": ["src", "bin", "README.md"],
-"main": "src/index.ts",
-"bin": {
-"suluk-platform": "bin/platform.ts"
-},
-"exports": {
-".": "./src/index.ts"
-},
-"dependencies": {
-"@suluk/provision": "^0.1.0"
-},
-"devDependencies": {
-"@types/bun": "latest"
-},
-"scripts": {
-"test": "bun test",
-"typecheck": "tsc --noEmit -p ."
-}
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+    "directory": "tooling/ts/packages/platform"
+  },
+  "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+  "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+  "type": "module",
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "main": "src/index.ts",
+  "bin": {
+    "suluk-platform": "bin/platform.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@suluk/provision": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }

package/src/generate.ts

@@ -85,6 +85,12 @@ export async function generatePlatform(input: PlatformManifest | Platform, opts:
   log("▸ writing provision.config.ts");
   await opts.write("provision.config.ts", plan.provisionConfig);
   written.push("src/index.ts", "provision.config.ts");
+  // the bun MOCK-PROVIDER dev server — only when the manifest sets `local: true` (else undefined → not written).
+  if (plan.devEntry) {
+    log("▸ writing src/dev.ts");
+    await opts.write("src/dev.ts", plan.devEntry);
+    written.push("src/dev.ts");
+  }
 
   log(`✓ generated ${name}: ${plan.services.length} services. Next: bun install && suluk-provision apply`);
   return { plan, added, written };

package/src/manifest.ts

@@ -22,6 +22,10 @@ export interface PlatformManifest {
   opts?: Record<string, Record<string, unknown>>;
   /** NON-SECRET config values → generated into `wrangler.toml` `[vars]`. SECRETS never go here (they live in `.env`). */
   vars?: Record<string, string>;
+  /** emit the MOCK-PROVIDER dev runtime: a `src/dev.ts` that runs the app under bun with a bun:sqlite DB + JSON-file KV +
+   *  mocked providers when their keys are absent (mock-until-keyed), and the `dev` script pointed at it. Default false →
+   *  the scaffold is byte-for-byte the C051 golden. */
+  local?: boolean;
 }
 
 // ── C053: the open system/brand surface ──────────────────────────────────────────────────────────────────────────────
@@ -62,6 +66,9 @@ export interface SystemManifest<T extends readonly ServiceRef[] = readonly Servi
   serviceOpts?: Partial<{ [K in T[number] as IdOf<K>]: SoOf<K> }>;
   /** inter-service composition edges (Phase 3). */
   wire?: WireDecl[];
+  /** emit the MOCK-PROVIDER dev runtime (a `src/dev.ts` bun server with a bun:sqlite DB + JSON KV + mocked providers when
+   *  keys are absent). A SYSTEM-level property (the app structure), swappable per brand only if a brand overrides it. */
+  local?: boolean;
 }
 
 /** A BRAND — thin, swappable per deployment. Carries the app identity + the brand-facing opts (→ `[vars]`). */

package/src/plan.ts

@@ -49,6 +49,9 @@ export interface PlatformPlan {
   /** 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;
+  /** the generated `src/dev.ts` — the bun MOCK-PROVIDER dev server (bun:sqlite DB + JSON KV + mocked providers when keys
+   *  absent). Present ONLY when the manifest sets `local: true`; undefined otherwise (so the golden path is unchanged). */
+  devEntry?: string;
 }
 
 export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
@@ -66,18 +69,20 @@ export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
   const env = collectEnv(services, catalog);
   // resolve the wires (a `{system,brand}` platform may carry `wire`; a legacy manifest never does → no wiring → byte-identical).
   const wiring = resolveWiring(services, isPlatform(input) ? input.system.wire ?? [] : [], catalog);
+  // the MOCK-PROVIDER dev runtime is OPT-IN (`local: true`); off → every output below is byte-for-byte the C051 golden.
+  const local = manifest.local === true;
   return {
     services,
     // a service may override the registry it's pulled from (multi-registry); core services fall back to the system registry.
     adds: services.map((s) => `${catalog[s].registry ?? manifest.registry}/${s}`),
-    entry: buildEntry(services, manifest.opts, wiring, catalog),
+    entry: buildEntry(services, manifest.opts, wiring, catalog, local),
     provisionConfig: buildProvisionConfig(services, catalog),
-    packageJson: buildPackageJson(manifest.name, services, catalog),
+    packageJson: buildPackageJson(manifest.name, services, catalog, local),
     tsconfig: buildTsconfig(),
     componentsJson: buildComponentsJson(),
     envExample: buildEnvExample(env),
     wranglerToml: buildWranglerToml(manifest.name, services, env, manifest.vars ?? {}),
-    gitignore: buildGitignore(),
+    gitignore: buildGitignore(local),
     envCheck: buildEnvCheckScript(env),
     envTs: buildEnvTs(env),
     syncSecrets: buildSyncSecrets(),
@@ -86,6 +91,7 @@ export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
     provisionScript: buildProvisionScript(env),
     mintTokens: buildMintTokens(env),
     envScaffold: buildEnvScaffold(env),
+    ...(local ? { devEntry: buildDevEntry(services) } : {}),
   };
 }
 
@@ -445,10 +451,11 @@ export function mergeWranglerToml(generated: string, existing: string | null): s
     .join("\n");
 }
 
-function buildGitignore(): string {
+function buildGitignore(local = false): string {
   // 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");
+  // local mode also ignores `.suluk/` (the bun-dev sqlite DB + JSON KV — local dev data, never committed).
+  return ["node_modules/", ".env.keys", ".env.temp", ".dev.vars", ".wrangler/", "dist/", ...(local ? [".suluk/"] : []), ""].join("\n");
 }
 
 /** Merge the generated .gitignore into an existing one — APPEND any missing entries (never skip-if-present, so an app's
@@ -514,7 +521,7 @@ process.exit(0);
 
 /** 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[], catalog: Record<string, Service> = CORE_SERVICES): string {
+export function buildPackageJson(name: string, services: string[], catalog: Record<string, Service> = CORE_SERVICES, local = false): 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> = {};
@@ -526,8 +533,10 @@ export function buildPackageJson(name: string, services: string[], catalog: Reco
     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 encrypted-env preflight (keypair present? required secrets set + encrypted?)
-      predev: "bun run scripts/env-check.ts", // runs automatically before `dev`
-      dev: "wrangler dev",
+      // local mode: `dev` runs the bun mock-provider server (no keys needed → no env-check predev); `dev:cf` keeps wrangler.
+      ...(local ? {} : { predev: "bun run scripts/env-check.ts" }), // (non-local) runs automatically before `dev`
+      dev: local ? "bun run --hot src/dev.ts" : "wrangler dev",
+      ...(local ? { "dev:cf": "wrangler dev" } : {}),
       deploy: "wrangler deploy",
       "env:keygen": "suluk-env keygen", // create the @suluk/env keypair (SULUK_PUBLIC_KEY → .env; private → .env.keys)
       "link-key": "bun run scripts/link-key.ts", // register the private key in ~/.suluk/settings.json (the central store)
@@ -608,7 +617,7 @@ function buildComponentsJson(): string {
   );
 }
 
-function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>, wiring?: Wiring, catalog: Record<string, Service> = CORE_SERVICES): string {
+function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>, wiring?: Wiring, catalog: Record<string, Service> = CORE_SERVICES, local = false): string {
   const imports = [
     'import { createApp } from "./app";',
     'import { loadEnv } from "@suluk/env";',
@@ -657,7 +666,10 @@ function buildEntry(services: string[], opts?: Record<string, Record<string, unk
     return false; // same symbol + module already imported → dedup
   });
   for (const line of groupImports(safeWireImports)) imports.push(line);
-  const body = ["const app = createApp();", ...middleware, ...routes];
+  // local mode also EXPORTS the wired app so `src/dev.ts` can serve it under bun with mock bindings (the Worker `fetch`
+  // export is unchanged). Off → `const app` (byte-identical to the golden). The mock modules are imported ONLY by dev.ts,
+  // so `wrangler deploy` (bundling from `src/index.ts`) never pulls bun:sqlite into the Worker.
+  const body = [`${local ? "export const app" : "const app"} = createApp();`, ...middleware, ...routes];
   // 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).
@@ -674,6 +686,65 @@ function buildEntry(services: string[], opts?: Record<string, Record<string, unk
   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`;
 }
 
+/**
+ * `src/dev.ts` — the bun MOCK-PROVIDER dev server (emitted only when `local: true`). Runs the SAME wired app (imported from
+ * `src/index.ts`) under bun with a bun:sqlite `DB` facade + a JSON-file KV, so `bun run dev` needs no Cloudflare account and
+ * no wrangler. Mock-until-keyed: it decrypts the committed `.env` if the app has been provisioned (real HTTP providers), else
+ * every provider falls to its module's mock. The deployed Worker (`src/index.ts`) imports NONE of this — bun:sqlite stays out.
+ */
+function buildDevEntry(services: string[]): string {
+  const usesKv = services.includes("rate-credit");
+  const usesEmail = services.includes("email");
+  const usesBilling = services.includes("billing");
+  const localImports = ["d1FromSqlite", ...(usesKv ? ["jsonFileKvStore"] : []), ...(usesEmail ? ["jsonFileMailbox"] : []), "applyLocalSchema"];
+  const billingImport = usesBilling ? '\nimport { mockStripeFetch } from "@suluk/billing";' : "";
+  const kvBind = usesKv ? "\n  RATE_CREDIT_KV: jsonFileKvStore(KV_PATH)," : "";
+  const mailboxBind = usesEmail ? "\n  SULUK_MAILBOX_SINK: mailbox," : "";
+  // mock-until-keyed: only inject the Stripe fake when there is no real key (a provisioned app hits real Stripe).
+  const stripeInject = usesBilling
+    ? '\nif (!env.STRIPE_SECRET_KEY) { env.STRIPE_SECRET_KEY = "sk_mock_local"; env.STRIPE_FETCH = mockStripeFetch(); }'
+    : "";
+  const mailboxRoute = usesEmail
+    ? '\n// a dev-only inbox view of the emails the mock provider captured (never mounted on the deployed Worker).\napp.get("/api/email/dev/mailbox", async (c) => c.json(await mailbox.list()));\n'
+    : "";
+  return `// AUTO-GENERATED by @suluk/platform — the bun MOCK-PROVIDER dev server. Runs the wired app under bun with a
+// bun:sqlite DB + JSON-file KV, so \`bun run dev\` works with ZERO Cloudflare account and no wrangler. A provider goes REAL
+// the moment its key is present (mock-until-keyed): add real keys to .env.temp + \`bun run provision\` and this file uses
+// them. NOTE: src/index.ts (the deployed Worker) imports NONE of these mocks — bun:sqlite never enters the Worker bundle.
+import { app } from "./index";
+import { Database } from "bun:sqlite";
+import { ${localImports.join(", ")} } from "@suluk/cloudflare/local";${billingImport}
+import { loadEnvFile } from "@suluk/env/node";
+
+const DB_PATH = process.env.SULUK_DB_PATH ?? ".suluk/dev.sqlite";${usesKv ? '\nconst KV_PATH = process.env.SULUK_KV_PATH ?? ".suluk/dev-kv.json";' : ""}${usesEmail ? '\nconst MAILBOX_PATH = process.env.SULUK_MAILBOX_PATH ?? ".suluk/dev-mailbox.json";' : ""}
+const PORT = Number(process.env.PORT ?? 8787);
+
+const sqlite = new Database(DB_PATH, { create: true });
+const tables = await applyLocalSchema(sqlite); // discover src/db/*.ts + create the tables from the drizzle schema
+console.log(\`[suluk dev] sqlite \${DB_PATH} — \${tables.length} tables\`);
+${usesEmail ? "const mailbox = jsonFileMailbox(MAILBOX_PATH); // a local inbox the mock email provider saves to\n" : ""}
+// Real secrets (if this app has been provisioned): decrypt the committed .env with the local private key. Fresh app / no
+// key → {} → every provider mocks. Best-effort: a decryption failure never blocks the mock path.
+let secrets: Record<string, string> = {};
+try { secrets = await loadEnvFile(); } catch {}
+
+// The request env: process.env < decrypted secrets < the mock bindings. DB/KV are always local (a bun process can't bind a
+// remote D1/KV); the HTTP providers (Google/Stripe/Resend) use their real key when present, else their module's mock.
+const env: Record<string, unknown> = {
+  ...process.env,
+  ...secrets,
+  DB: d1FromSqlite(sqlite),${kvBind}${mailboxBind}
+};
+
+const mocked = ["GOOGLE_CLIENT_ID", "STRIPE_SECRET_KEY", "RESEND_API_KEY"].filter((k) => !env[k]);
+if (mocked.length) console.log(\`[suluk dev] mocked (no key): \${mocked.join(", ")}\`);${stripeInject}
+${mailboxRoute}
+const ctx = { waitUntil() {}, passThroughOnException() {} } as unknown as ExecutionContext;
+Bun.serve({ port: PORT, idleTimeout: 120, fetch: (req) => app.fetch(req, env as Parameters<typeof app.fetch>[1], ctx) });
+console.log(\`[suluk dev] → http://localhost:\${PORT}  (mock-until-keyed; provision to go live)\`);
+`;
+}
+
 function buildProvisionConfig(services: string[], catalog: Record<string, Service> = CORE_SERVICES): string {
   const frags = services.map((s) => catalog[s].provision).filter((p): p is NonNullable<typeof p> => !!p);
   const imports = frags.map((f) => `import { ${f.symbol} } from "${f.from}";`);

package/src/resolve.ts

@@ -87,6 +87,7 @@ export function liftLegacy(m: PlatformManifest): Platform {
       services: m.services,
       ...(Object.keys(globalServiceOpts).length ? { globalServiceOpts } : {}),
       ...(m.opts && Object.keys(m.opts).length ? { serviceOpts: m.opts } : {}),
+      ...(m.local ? { local: true } : {}),
     },
     brand: {
       name: m.name,
@@ -107,5 +108,6 @@ export function liftSystemBrand(p: Platform): PlatformManifest {
     services,
     ...(Object.keys(opts).length ? { opts } : {}),
     ...(Object.keys(vars).length ? { vars } : {}),
+    ...(p.system.local ? { local: true } : {}),
   };
 }