@cosmicdrift/kumiko-dev-server 0.329.0 → 0.330.0

package/src/scaffold-app.ts

@@ -1,1033 +0,0 @@
-// scaffoldApp — generate a runnable Kumiko app workspace from a name.
-//
-// Used by `kumiko new app <name>`. Produces the minimal app shape that
-// `KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts` runs successfully against:
-// run-config with 5 foundation features, bin/main.ts with auth-admin
-// stub, package.json with @cosmicdrift/* deps, tsconfig, .env.example,
-// README.
-//
-// .ts files are built via ts-morph (same tool [[scaffoldAppFeature]] uses
-// to auto-mount features). Means a single AST representation for both
-// generate + later modify — no template-string ↔ ts-morph divergence.
-// Static files (package.json, tsconfig, .env, README) stay text-based.
-
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-import {
-  collectTableMetas,
-  generateMigration,
-  writeSnapshotJson,
-} from "@cosmicdrift/kumiko-framework/db";
-import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
-import { IndentationText, Project, VariableDeclarationKind } from "ts-morph";
-import { isKebabSegment } from "./kebab";
-import {
-  createDemoTasksFeature,
-  renderDemoSeedFile,
-  renderDemoTasksFeatureFile,
-  renderDemoTasksI18n,
-  renderDemoTasksIndex,
-  renderDemoTasksWebIndex,
-} from "./scaffold-demo-tasks";
-import { scaffoldDeploy } from "./scaffold-deploy";
-
-// Single bundled-feature entry the scaffolder mounts into run-config.ts.
-// importPath is the from-spec ("@cosmicdrift/kumiko-bundled-features/files"),
-// exportName the named import, callExpression the form that lands in the
-// APP_FEATURES array literal — typically `${exportName}()` for factory-style
-// features and just `${exportName}` for object-style ones (e.g. billingFoundationFeature).
-export type ScaffoldFeatureEntry = {
-  readonly name: string;
-  readonly importPath: string;
-  readonly exportName: string;
-  readonly callExpression: string;
-  /** Runtime args for factory-style exports that need config the codegen text can't parse back out (e.g. `{ scopes: {} }`). Omit for zero-arg factories and object-style exports. */
-  readonly callArgs?: readonly unknown[];
-};
-
-// Structural twin of `ScaffoldTestSetup` from @cosmicdrift/kumiko-testing/scaffold —
-// dev-server cannot import that package (it depends on dev-server), callers pass it in.
-export type ScaffoldTestSetup = {
-  readonly files: Readonly<Record<string, string>>;
-  readonly scripts: Readonly<Record<string, string>>;
-  readonly devDependencies: Readonly<Record<string, string>>;
-  readonly rulesMarkdown: string;
-};
-
-export type ScaffoldTestSetupFactory = (input: {
-  readonly appName: string;
-  readonly frameworkVersion: string;
-}) => ScaffoldTestSetup;
-
-export type ScaffoldAppOptions = {
-  /** kebab-case app name (e.g. "my-shop"). Becomes package-name + folder. */
-  readonly name: string;
-  /** Absolute or cwd-relative target dir. Default: <cwd>/<name>. */
-  readonly destination?: string;
-  /** Base dir a relative `destination` (or the name-default) resolves
-   *  against. Defaults to process.cwd(). Callers with their own cwd-notion
-   *  (the CLI's ctx.cwd) MUST pass it so the scaffold lands where the
-   *  command's output claims it does. */
-  readonly cwd?: string;
-  /** npm-version-pin for @cosmicdrift/* deps. Default "*" for latest. */
-  readonly frameworkVersion?: string;
-  /** Bundled-features to mount in run-config.ts. Default: secrets + auth-foundation + sessions
-   *  (the historical foundation). create-kumiko-app passes the picker output
-   *  here so the generated APP_FEATURES reflects the user's selection. */
-  readonly features?: ReadonlyArray<ScaffoldFeatureEntry>;
-  /** Test wiring (bunfigs, scripts, example tests, e2e) — `renderTestSetup` from
-   *  @cosmicdrift/kumiko-testing/scaffold. Without it the app gets the legacy
-   *  bunfig pair and no example tests. */
-  readonly testSetup?: ScaffoldTestSetupFactory;
-};
-
-export type ScaffoldAppResult = {
-  readonly destination: string;
-  readonly files: readonly string[];
-  readonly appName: string;
-};
-
-export async function scaffoldApp(options: ScaffoldAppOptions): Promise<ScaffoldAppResult> {
-  if (!isKebabSegment(options.name)) {
-    throw new Error(`scaffoldApp: name must be kebab-case (a-z, 0-9, -); got "${options.name}"`);
-  }
-  const cwd = options.cwd ?? process.cwd();
-  const destination = resolve(cwd, options.destination ?? options.name);
-  if (existsSync(destination)) {
-    throw new Error(`scaffoldApp: ${destination} already exists — refusing to overwrite`);
-  }
-  const version = options.frameworkVersion ?? "*";
-  const testSetup = options.testSetup?.({ appName: options.name, frameworkVersion: version });
-
-  mkdirSync(join(destination, "bin"), { recursive: true });
-  mkdirSync(join(destination, "src"), { recursive: true });
-  mkdirSync(join(destination, "kumiko"), { recursive: true });
-
-  const files: string[] = [];
-
-  write(join(destination, "package.json"), renderPackageJson(options.name, version, testSetup));
-  files.push("package.json");
-
-  write(join(destination, "tsconfig.json"), renderTsconfig());
-  files.push("tsconfig.json");
-
-  write(join(destination, "biome.json"), renderBiomeJson());
-  files.push("biome.json");
-
-  if (testSetup === undefined) {
-    write(join(destination, "bunfig.toml"), renderBunfigToml());
-    files.push("bunfig.toml");
-
-    write(join(destination, "bunfig.ci.toml"), renderBunfigCiToml());
-    files.push("bunfig.ci.toml");
-  }
-
-  write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
-  files.push("src/run-config.ts");
-
-  mkdirSync(join(destination, "src", "features", "tasks", "web"), { recursive: true });
-  write(join(destination, "src", "features", "tasks", "feature.ts"), renderDemoTasksFeatureFile());
-  files.push("src/features/tasks/feature.ts");
-  write(join(destination, "src", "features", "tasks", "i18n.ts"), renderDemoTasksI18n());
-  files.push("src/features/tasks/i18n.ts");
-  write(join(destination, "src", "features", "tasks", "index.ts"), renderDemoTasksIndex());
-  files.push("src/features/tasks/index.ts");
-  write(
-    join(destination, "src", "features", "tasks", "web", "index.ts"),
-    renderDemoTasksWebIndex(),
-  );
-  files.push("src/features/tasks/web/index.ts");
-  write(join(destination, "src", "seed.ts"), renderDemoSeedFile());
-  files.push("src/seed.ts");
-
-  write(join(destination, "kumiko", "schema.ts"), renderKumikoSchema());
-  files.push("kumiko/schema.ts");
-
-  write(join(destination, "bin", "main.ts"), renderMain(options.name));
-  files.push("bin/main.ts");
-
-  write(join(destination, "bin", "dev.ts"), renderDev(options.name));
-  files.push("bin/dev.ts");
-
-  write(join(destination, "bin", "kumiko.ts"), renderBinKumiko());
-  files.push("bin/kumiko.ts");
-
-  write(join(destination, "src", "client.tsx"), renderClient(options.name));
-  files.push("src/client.tsx");
-
-  write(join(destination, "src", "styles.css"), renderStylesCss());
-  files.push("src/styles.css");
-
-  write(join(destination, ".env.example"), renderEnvExample(options.name));
-  files.push(".env.example");
-
-  write(join(destination, "docker-compose.yml"), renderDockerCompose());
-  files.push("docker-compose.yml");
-
-  await writeInitMigration(destination, options.features);
-  files.push("kumiko/migrations/0001_init.sql", "kumiko/migrations/.snapshot.json");
-
-  const deploy = scaffoldDeploy({ appName: options.name, destination });
-  for (const f of deploy.files) {
-    if (f.written) {
-      files.push(relative(destination, f.path));
-    }
-  }
-
-  if (testSetup !== undefined) {
-    for (const [rel, content] of Object.entries(testSetup.files)) {
-      mkdirSync(dirname(join(destination, rel)), { recursive: true });
-      write(join(destination, rel), content);
-      files.push(rel);
-    }
-  }
-
-  write(
-    join(destination, "README.md"),
-    `${renderReadme(options.name, options.features)}${testSetup === undefined ? "" : `\n${testSetup.rulesMarkdown}`}`,
-  );
-  files.push("README.md");
-
-  return { destination, files, appName: options.name };
-}
-
-// @wrapper-known semantic-alias
-function write(path: string, content: string): void {
-  writeFileSync(path, content);
-}
-
-function renderPackageJson(
-  name: string,
-  version: string,
-  testSetup: ScaffoldTestSetup | undefined,
-): string {
-  return `${JSON.stringify(
-    {
-      name,
-      version: "0.1.0",
-      private: true,
-      type: "module",
-      scripts: {
-        dev: "bun --watch bin/dev.ts",
-        build: "bun kumiko-build",
-        start: "bun run bin/main.ts",
-        boot: "KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts",
-        typecheck: "tsc --noEmit",
-        lint: "biome check .",
-        ...(testSetup?.scripts ?? { test: "bun --config=bunfig.ci.toml test --dots" }),
-        "schema:apply": "bun kumiko-schema apply",
-        "schema:generate": "bun kumiko-schema generate",
-      },
-      dependencies: {
-        "@cosmicdrift/kumiko-bundled-features": version,
-        "@cosmicdrift/kumiko-dev-server": version,
-        "@cosmicdrift/kumiko-framework": version,
-        "@cosmicdrift/kumiko-renderer-web": version,
-        "@cosmicdrift/kumiko-server-runtime": version,
-        react: "^19.2.6",
-        "react-dom": "^19.2.6",
-        zod: "^4.4.3",
-      },
-      devDependencies: sortedByName({
-        "@biomejs/biome": "^2.4.15",
-        "@tailwindcss/cli": "^4.3.0",
-        "@types/react": "^19.2.0",
-        "@types/react-dom": "^19.2.0",
-        "bun-types": "^1.4.0",
-        tailwindcss: "^4.3.0",
-        typescript: "^6.0.3",
-        ...testSetup?.devDependencies,
-      }),
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function sortedByName(record: Readonly<Record<string, string>>): Record<string, string> {
-  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : 1)));
-}
-
-function renderTsconfig(): string {
-  return `${JSON.stringify(
-    {
-      compilerOptions: {
-        strict: true,
-        noUncheckedIndexedAccess: true,
-        forceConsistentCasingInFileNames: true,
-        verbatimModuleSyntax: true,
-        target: "ESNext",
-        module: "ESNext",
-        moduleResolution: "bundler",
-        esModuleInterop: true,
-        skipLibCheck: true,
-        lib: ["ESNext", "DOM"],
-        types: ["bun-types"],
-        jsx: "react-jsx",
-        noEmit: true,
-      },
-      include: ["bin", "src", "kumiko", "e2e", "playwright.config.ts"],
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function renderBiomeJson(): string {
-  return `${JSON.stringify(
-    {
-      $schema: "https://biomejs.dev/schemas/2.4.15/schema.json",
-      vcs: {
-        enabled: true,
-        clientKind: "git",
-        useIgnoreFile: true,
-        defaultBranch: "main",
-      },
-      files: {
-        includes: [
-          "src/**",
-          "bin/**",
-          "kumiko/**",
-          "e2e/**",
-          "playwright.config.ts",
-          "!**/dist",
-          "!kumiko/migrations",
-        ],
-      },
-      formatter: {
-        enabled: true,
-        indentStyle: "space",
-        indentWidth: 2,
-        lineWidth: 100,
-        lineEnding: "lf",
-      },
-      css: {
-        parser: { cssModules: false, tailwindDirectives: true },
-      },
-      javascript: {
-        formatter: {
-          quoteStyle: "double",
-          jsxQuoteStyle: "double",
-          semicolons: "always",
-          trailingCommas: "all",
-          arrowParentheses: "always",
-        },
-      },
-      json: { formatter: { indentWidth: 2, lineWidth: 80 } },
-      linter: {
-        enabled: true,
-        rules: {
-          recommended: true,
-          correctness: { noUnusedVariables: "error", noUnusedImports: "error" },
-          suspicious: { noExplicitAny: "error", noDebugger: "error", noConsole: "warn" },
-          complexity: { useLiteralKeys: "off" },
-          style: { useConst: "error" },
-          nursery: { noFloatingPromises: "error" },
-        },
-      },
-      overrides: [
-        {
-          includes: ["**/*.test.ts", "**/*.spec.ts", "**/*.integration.ts", "**/*.e2e.ts"],
-          linter: {
-            rules: {
-              suspicious: { noConsole: "off" },
-              style: { noNonNullAssertion: "off" },
-            },
-          },
-        },
-      ],
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function renderBunfigToml(): string {
-  return `[install]
-linker = "hoisted"
-
-[test]
-pathIgnorePatterns = [
-  "**/e2e/**",
-  "**/*.spec.ts",
-  "**/dist/**",
-]
-`;
-}
-
-function renderBunfigCiToml(): string {
-  return `[install]
-linker = "hoisted"
-
-[test]
-pathIgnorePatterns = [
-  "**/e2e/**",
-  "**/*.spec.ts",
-  "**/dist/**",
-]
-`;
-}
-
-function newTsProject(): Project {
-  return new Project({
-    useInMemoryFileSystem: true,
-    compilerOptions: { target: 99, module: 99, strict: true },
-    manipulationSettings: { indentationText: IndentationText.TwoSpaces },
-  });
-}
-
-const FOUNDATION_FEATURES: ReadonlyArray<ScaffoldFeatureEntry> = [
-  {
-    name: "secrets",
-    importPath: "@cosmicdrift/kumiko-bundled-features/secrets",
-    exportName: "createSecretsFeature",
-    callExpression: "createSecretsFeature()",
-  },
-  // sessions' `sessionStore` extension requires auth-foundation to be mounted.
-  {
-    name: "auth-foundation",
-    importPath: "@cosmicdrift/kumiko-bundled-features/auth-foundation",
-    exportName: "authFoundationFeature",
-    callExpression: "authFoundationFeature",
-  },
-  {
-    name: "sessions",
-    importPath: "@cosmicdrift/kumiko-bundled-features/sessions",
-    exportName: "createSessionsFeature",
-    callExpression: "createSessionsFeature()",
-  },
-];
-
-// composeFeatures({ includeBundled: true }) auto-mountet diese 4 Foundation-
-// Features. Sie hier nochmal in APP_FEATURES zu schreiben löste den dedupe-
-// warn-Spam im scaffolded `bun dev` aus (PR #599 hat den createRegistry-
-// Crash gefangen, der Spam blieb bis hier). Filter wirkt defensiv: auch wenn
-// jemand scaffoldApp() direkt mit allen Bundled-Feature-Entries aufruft
-// rutschen die 4 nicht in run-config.ts.
-const COMPOSE_AUTO_MOUNTED_NAMES = new Set(["config", "user", "tenant", "auth-email-password"]);
-
-function renderRunConfig(features?: ReadonlyArray<ScaffoldFeatureEntry>): string {
-  const project = newTsProject();
-  const sf = project.createSourceFile("run-config.ts", "");
-
-  // Fallback decided BEFORE filtering: if the caller passed features (even
-  // if every one of them is an auto-mounted name), an all-filtered-out empty
-  // result is the correct outcome — falling back to FOUNDATION_FEATURES here
-  // would silently substitute a different feature set than the caller asked
-  // for.
-  const base = features?.length ? features : FOUNDATION_FEATURES;
-  const effective = base.filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
-  const grouped = new Map<string, string[]>();
-  for (const entry of effective) {
-    const existing = grouped.get(entry.importPath) ?? [];
-    if (!existing.includes(entry.exportName)) existing.push(entry.exportName);
-    grouped.set(entry.importPath, existing);
-  }
-  for (const [importPath, namedImports] of grouped) {
-    sf.addImportDeclaration({ moduleSpecifier: importPath, namedImports });
-  }
-  sf.addImportDeclaration({
-    moduleSpecifier: "./features/tasks",
-    namedImports: ["tasksFeature"],
-  });
-
-  const callExprs = [...effective.map((f) => f.callExpression), "tasksFeature"];
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    isExported: true,
-    declarations: [
-      {
-        name: "APP_FEATURES",
-        initializer: `[${callExprs.join(", ")}] as const`,
-      },
-    ],
-  });
-
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    isExported: true,
-    declarations: [{ name: "HAS_AUTH", initializer: "true" }],
-  });
-
-  sf.insertText(
-    0,
-    [
-      "// Single source of truth for your app's feature composition.",
-      "// config/user/tenant/auth-email-password are added automatically",
-      "// via composeFeatures(includeBundled:true) when runProdApp is called",
-      "// with `auth: {…}` (see bin/main.ts).",
-      "//",
-      "// Add new features:",
-      "//   - bunx @cosmicdrift/kumiko-cli add feature <name>  (DX-2, automatic)",
-      "//   - or: hand-edit + add the import below",
-      "",
-      "",
-    ].join("\n"),
-  );
-
-  return sf.getFullText();
-}
-
-function renderMain(appName: string): string {
-  const tenantId = deriveTenantId(appName);
-  const project = newTsProject();
-  const sf = project.createSourceFile("main.ts", "");
-
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-dev-server/env-schema",
-    namedImports: ["frameworkCoreEnvSchema"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-server-runtime",
-    namedImports: ["composeFeatures", "runProdApp"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-framework/engine",
-    isTypeOnly: true,
-    namedImports: ["TenantId"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-framework/env",
-    namedImports: ["composeEnvSchema"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-framework/crypto",
-    namedImports: ["requireKmsWiring", "resolveKmsWiring"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "../src/run-config",
-    namedImports: ["APP_FEATURES", "HAS_AUTH"],
-  });
-
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    declarations: [
-      {
-        name: "DEFAULT_TENANT_ID",
-        initializer: `"${tenantId}" as TenantId`,
-      },
-    ],
-  });
-
-  // The envSchema must cover the SAME features runProdApp mounts at boot.
-  // `auth: { admin: … }` below makes runProdApp auto-mix config/user/tenant/
-  // auth-email-password via composeFeatures(includeBundled:HAS_AUTH); compose the
-  // identical set here so the auth feature's JWT_SECRET (min-32) declaration
-  // is part of the boot-gate — otherwise a too-short JWT_SECRET slips through.
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    declarations: [
-      {
-        name: "bootFeatures",
-        initializer: "composeFeatures(APP_FEATURES, { includeBundled: HAS_AUTH })",
-      },
-    ],
-  });
-
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    declarations: [
-      {
-        name: "envSchema",
-        initializer: "composeEnvSchema({ core: frameworkCoreEnvSchema, features: bootFeatures })",
-      },
-    ],
-  });
-
-  // Subject-key KMS for the pii-annotated entities the --yes recommended set
-  // mounts (user, tenant-invitation, fileRef). Local/dev may omit the trio
-  // (plaintext + loud warning); NODE_ENV=production uses requireKmsWiring so
-  // a real deploy cannot silently store plaintext PII (fw#2317 / #2339).
-  // assertPiiBootInvariants already warns on the plaintext path — no duplicate console.warn.
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    declarations: [
-      {
-        name: "kmsOpts",
-        initializer: (writer) => {
-          writer.write("{").newLine();
-          writer.writeLine(`  logPrefix: "[${appName}]",`);
-          writer.writeLine(
-            `  plaintextReason: "no PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY set — see .env.example",`,
-          );
-          writer.write("} as const");
-        },
-      },
-    ],
-  });
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    declarations: [
-      {
-        name: "kmsWiring",
-        initializer: (writer) => {
-          writer.write(`process.env["NODE_ENV"] === "production"`);
-          writer.newLine();
-          writer.write("  ? requireKmsWiring(process.env, kmsOpts)");
-          writer.newLine();
-          writer.write("  : resolveKmsWiring(process.env, kmsOpts)");
-        },
-      },
-    ],
-  });
-
-  sf.addStatements((writer) => {
-    writer
-      .write("await runProdApp(")
-      .inlineBlock(() => {
-        writer.writeLine("features: APP_FEATURES,");
-        writer.writeLine("envSchema,");
-        writer.writeLine('staticDir: "./dist",');
-        writer.writeLine("...kmsWiring,");
-        writer.write("auth: ").inlineBlock(() => {
-          writer.write("admin: ").inlineBlock(() => {
-            writer.writeLine(`email: "admin@${appName}.local",`);
-            writer.writeLine(`password: "change-me-on-first-deploy",`);
-            writer.writeLine(`displayName: "Admin",`);
-            writer.write("memberships: [");
-            writer.indent(() => {
-              writer.inlineBlock(() => {
-                writer.writeLine("tenantId: DEFAULT_TENANT_ID,");
-                writer.writeLine(`tenantKey: "${appName}",`);
-                writer.writeLine(`tenantName: "${appName}",`);
-                writer.writeLine(`roles: ["TenantAdmin"],`);
-              });
-              writer.write(",");
-            });
-            writer.write("],");
-          });
-        });
-      })
-      .write(");");
-  });
-
-  sf.insertText(
-    0,
-    [
-      "// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after",
-      "// composeFeatures + validateBoot + createRegistry without DB/Redis-connect",
-      "// (see @cosmicdrift/kumiko-server-runtime runProdApp). The real dev boot",
-      "// runs via `bunx kumiko dev` (in-repo dev-tool) with a Docker stack — DX-1.0",
-      "// only covers the boot-mode path; `kumiko dev` lands in a later DX phase.",
-      "",
-      "",
-    ].join("\n"),
-  );
-
-  return sf.getFullText();
-}
-
-function renderDev(appName: string): string {
-  const tenantId = deriveTenantId(appName);
-  const project = newTsProject();
-  const sf = project.createSourceFile("dev.ts", "");
-
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-dev-server",
-    namedImports: ["runDevApp"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-framework/engine",
-    isTypeOnly: true,
-    namedImports: ["TenantId"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "../src/run-config",
-    namedImports: ["APP_FEATURES"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "../src/seed",
-    namedImports: ["seedDemoTasks"],
-  });
-
-  sf.addVariableStatement({
-    declarationKind: VariableDeclarationKind.Const,
-    declarations: [
-      {
-        name: "DEFAULT_TENANT_ID",
-        initializer: `"${tenantId}" as TenantId`,
-      },
-    ],
-  });
-
-  sf.addStatements((writer) => {
-    writer
-      .write("await runDevApp(")
-      .inlineBlock(() => {
-        writer.writeLine("features: APP_FEATURES,");
-        writer.writeLine("welcomeBanner: true,");
-        writer.writeLine(`clientEntry: "./src/client.tsx",`);
-        writer.writeLine("seeds: [seedDemoTasks],");
-        writer.write("auth: ").inlineBlock(() => {
-          writer.write("admin: ").inlineBlock(() => {
-            writer.writeLine(`email: "admin@${appName}.local",`);
-            writer.writeLine(`password: "changeme",`);
-            writer.writeLine(`displayName: "Admin",`);
-            // Dev-only: skip the email-verify login gate for the seeded
-            // admin. Prod's scaffold (renderMain) leaves this unset on
-            // purpose — the verify flow must run there.
-            writer.writeLine("emailVerified: true,");
-            writer.write("memberships: [");
-            writer.indent(() => {
-              writer.inlineBlock(() => {
-                writer.writeLine("tenantId: DEFAULT_TENANT_ID,");
-                writer.writeLine(`tenantKey: "${appName}",`);
-                writer.writeLine(`tenantName: "${appName}",`);
-                writer.writeLine(`roles: ["TenantAdmin"],`);
-              });
-              writer.write(",");
-            });
-            writer.write("],");
-          });
-        });
-      })
-      .write(");");
-  });
-
-  sf.insertText(
-    0,
-    [
-      "// Dev bootstrap. `bun --watch bin/dev.ts` (see package.json scripts.dev)",
-      "// starts a full-featured dev server with auto-reload on code changes.",
-      "// setupTestStack creates missing entity tables automatically — a new",
-      "// r.entity(...) in a feature becomes a CREATE TABLE on the next reboot,",
-      "// no manual `kumiko schema apply` needed (that's prod-only).",
-      "// Persistent DB via KUMIKO_DEV_DB_NAME (.env) so admin + data survive reboots.",
-      "",
-      "",
-    ].join("\n"),
-  );
-
-  return sf.getFullText();
-}
-
-function renderClient(appName: string): string {
-  return [
-    "// Browser entry. runDevApp's clientEntry option bundles this file to",
-    "// /client.js and the default HTML loads it. createKumikoApp fetches the",
-    "// AppSchema itself from the authenticated GET /api/schema and mounts",
-    "// the routes.",
-    "//",
-    "// AppShell wraps DefaultAppShell to supply `brand` — createKumikoApp's",
-    "// shell option only injects schema + children. Without `shell` the",
-    "// active screen renders with no layout wrapper (a bare banner after",
-    "// login instead of the app). emailPasswordClient() brings the login",
-    "// screen + session provider — without it /login stays empty.",
-    "//",
-    "// Add new client plugins (e.g. notificationsClient()) to clientFeatures",
-    "// here — symmetric to APP_FEATURES on the server side.",
-    "",
-    'import { emailPasswordClient } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";',
-    'import { tasksClient } from "./features/tasks/web";',
-    'import { type AppSchema, createKumikoApp, DefaultAppShell } from "@cosmicdrift/kumiko-renderer-web";',
-    'import type { ReactNode } from "react";',
-    "",
-    "function AppShell({ children, schema }: { children: ReactNode; schema: AppSchema }): ReactNode {",
-    "  return (",
-    // html-ok: appName is kebab-validated (a-z/0-9/-); this is generated .tsx source, not runtime HTML.
-    `    <DefaultAppShell brand={<span className="font-semibold tracking-tight">${appName}</span>} schema={schema}>`,
-    "      {children}",
-    "    </DefaultAppShell>",
-    "  );",
-    "}",
-    "",
-    "createKumikoApp({",
-    "  shell: AppShell,",
-    "  clientFeatures: [emailPasswordClient(), tasksClient],",
-    "});",
-    "",
-  ].join("\n");
-}
-
-function renderEnvExample(appName: string): string {
-  const devDb = `${appName.replace(/-/g, "_")}_dev`;
-  return `# bun dev (runDevApp → setupTestStack) needs TEST_DATABASE_URL.
-# Production (bun bin/main.ts → runProdApp) needs DATABASE_URL.
-# Both default to the same local Postgres — runDevApp creates its own
-# "<KUMIKO_DEV_DB_NAME>" database underneath.
-TEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/postgres
-DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/app
-REDIS_URL=redis://127.0.0.1:6379
-
-# JWT_SECRET: min 32 chars. Generate with: openssl rand -base64 32
-JWT_SECRET=change-me-min-32-chars-change-me-min-32
-
-# KUMIKO_SECRETS_MASTER_KEY_V1: base64-encoded 32 bytes (AES-256 KEK).
-# Generate with: openssl rand -base64 32
-KUMIKO_SECRETS_MASTER_KEY_V1=
-
-# Subject-keys KMS for PII fields (user, tenant-invitation, fileRef). All-or-none.
-# Unset → local boot with plaintext PII + warning; NODE_ENV=production requires
-# the trio (requireKmsWiring). Generate PLATFORM_KEK / KUMIKO_BLIND_INDEX_KEY
-# with: openssl rand -base64 32. SUBJECT_KEYS_DATABASE_URL must be a dedicated
-# subject-keys cluster (not the app DB) — see kms-adapter.md.
-PLATFORM_KEK=
-# Separate Postgres instance for subject keys — never DATABASE_URL (retention
-# must outlive app-DB backups for crypto-shredding).
-SUBJECT_KEYS_DATABASE_URL=
-KUMIKO_BLIND_INDEX_KEY=
-
-# Dev-only: persistent DB for \`bun dev\`. Without this var every reboot starts
-# a fresh kumiko_test_<random> DB → admin login + data gone on every edit.
-# With it the DB persists across reboots (schema pushes are idempotent).
-KUMIKO_DEV_DB_NAME=${devDb}
-`;
-}
-
-// Ports + credentials match the *_URL defaults in renderEnvExample, so
-// `docker compose up -d` just works with the generated .env. Named pg volume
-// so dev data survives `docker compose down` (pairs with KUMIKO_DEV_DB_NAME
-// persistence) — the loopback-binding rationale is in the generated file's
-// own comment (657/1), no need to duplicate it here.
-function renderDockerCompose(): string {
-  return `# Local Postgres + Redis for \`bun dev\`. Matches the *_URL defaults in .env.example.
-# Start: docker compose up -d   ·   Stop: docker compose down   ·   Reset: docker compose down -v
-# Ports bind to 127.0.0.1 only — weak dev credentials must not be exposed on the LAN.
-services:
-  postgres:
-    # Pinned to the project's own compose-file tag (663/1) — Alpine variant
-    # (~90MB vs ~400MB) and a reproducible patch version, bump on PG18 minors.
-    image: postgres:18.3-alpine
-    environment:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-    ports:
-      - "127.0.0.1:5432:5432"
-    volumes:
-      - kumiko-pg:/var/lib/postgresql
-  redis:
-    image: redis:7
-    ports:
-      - "127.0.0.1:6379:6379"
-volumes:
-  kumiko-pg:
-`;
-}
-
-function renderReadme(
-  appName: string,
-  features: ReadonlyArray<ScaffoldFeatureEntry> | undefined,
-): string {
-  const featureList =
-    features && features.length > 0
-      ? [...features.map((f) => `- \`${f.name}\``), "- `tasks` (demo — list + edit screens)"].join(
-          "\n",
-        )
-      : "- `secrets` (foundation)\n- `sessions` (foundation)\n- `tasks` (demo — list + edit screens)";
-  return `# ${appName}
-
-Scaffolded by \`kumiko new app\`. Includes a demo **tasks** feature with list +
-edit screens, sidebar nav, and seeded rows — \`bun dev\` shows a working admin UI
-after login. Add more features via \`bunx @cosmicdrift/kumiko-cli add feature <name>\`.
-
-## Mounted features
-
-${featureList}
-
-Edit \`src/run-config.ts\` to add bundled features. The demo lives in
-\`src/features/tasks/\`.
-
-## First run (browser)
-
-\`\`\`sh
-bun install
-cp .env.example .env
-# set JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1 in .env
-docker compose up -d   # local Postgres + Redis (skip if you already have them)
-bun dev
-\`\`\`
-
-The welcome banner prints the URL (default \`http://localhost:4173\`) and admin
-login. Sign in as \`admin@${appName}.local\` / \`changeme\`, then open **Tasks**
-in the sidebar — demo rows are pre-seeded.
-
-## Boot-only smoke (no DB needed)
-
-\`\`\`sh
-bun run boot
-\`\`\`
-
-Runs \`KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts\` — validates feature composition
-+ env schema, exits 0 without touching DB/Redis. Useful in CI.
-
-Without \`PLATFORM_KEK\` / \`SUBJECT_KEYS_DATABASE_URL\` / \`KUMIKO_BLIND_INDEX_KEY\`
-set (see \`.env.example\`), both \`bun run boot\` and \`bun run start\` boot with
-PII fields (user, tenant-invitation, fileRef) stored in plaintext and a loud
-warning — set all three before a real deploy.
-
-## Production build + schema
-
-\`\`\`sh
-bun run build          # kumiko-build → dist/ + dist-server/
-bun run schema:apply   # apply checked-in kumiko/migrations (needs DATABASE_URL)
-bun run start          # runProdApp against dist/
-\`\`\`
-
-After adding entities/features, regenerate migrations:
-
-\`\`\`sh
-bun run schema:generate <name>
-\`\`\`
-
-## Deploy
-
-\`deploy/Dockerfile\` + \`deploy/migrate-step.sh\` are scaffolded for container
-deploys. Build context = app repo root; migrations ship in \`kumiko/migrations/\`.
-
-## Architecture
-
-- \`src/run-config.ts\` — single source of truth: which features your app mounts (\`APP_FEATURES\`, \`HAS_AUTH\`).
-- \`src/features/tasks/\` — demo feature (entity + handlers + screens + nav).
-- \`src/seed.ts\` — dev seed for demo tasks (\`bun dev\` only).
-- \`kumiko/schema.ts\` — same feature set → \`ENTITY_METAS\` for \`kumiko schema\`.
-- \`bin/dev.ts\` — dev-server entry (\`bun dev\`).
-- \`bin/main.ts\` — production-bootstrap (\`bun run start\`).
-- \`bin/kumiko.ts\` — schema + consumer-ops CLI bundled into \`dist-server/kumiko.js\`.
-- \`docker-compose.yml\` — local Postgres + Redis for \`bun dev\`.
-
-For full docs see https://docs.kumiko.rocks.
-`;
-}
-
-function renderStylesCss(): string {
-  return [
-    '@import "@cosmicdrift/kumiko-renderer-web/styles.css";',
-    "",
-    '@source "./**/*.{ts,tsx}";',
-    "",
-  ].join("\n");
-}
-
-function renderKumikoSchema(): string {
-  return [
-    "// Live ENTITY_METAS source for `kumiko schema generate|apply|status`.",
-    "//",
-    "// Computes table-metas from the SAME composeFeatures(APP_FEATURES) the",
-    "// runtime sees (runProdApp/runDevApp) — migration and runtime cannot drift.",
-    "",
-    'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
-    'import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";',
-    'import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";',
-    'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
-    "",
-    "export const FEATURES: readonly FeatureDefinition[] = composeFeatures([...APP_FEATURES], {",
-    "  includeBundled: HAS_AUTH,",
-    "});",
-    "",
-    "export const ENTITY_METAS: readonly EntityTableMeta[] = collectTableMetas(FEATURES);",
-    "",
-  ].join("\n");
-}
-
-function renderBinKumiko(): string {
-  return [
-    "#!/usr/bin/env bun",
-    "",
-    "// Standalone kumiko CLI for the production bundle. The deploy migrate-step",
-    "// runs `bun /app/kumiko.js schema apply`; ops runs `bun /app/kumiko.js",
-    "// consumer status|restart <name>` to recover a dead event consumer without",
-    "// ad-hoc SQL. kumiko-build bundles this file to dist-server/kumiko.js.",
-    "",
-    'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
-    'import { runConsumerCli } from "@cosmicdrift/kumiko-framework/consumer-cli";',
-    'import { runSchemaCli } from "@cosmicdrift/kumiko-framework/schema-cli";',
-    'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
-    "",
-    "const [, , cmd, ...rest] = Bun.argv;",
-    "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
-    "const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };",
-    "",
-    'if (cmd === "schema") {',
-    "  const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
-    "  process.exit(await runSchemaCli(rest, process.env.INIT_CWD ?? process.cwd(), out, { features }));",
-    "}",
-    "",
-    'if (cmd === "consumer") {',
-    "  process.exit(await runConsumerCli(rest, out));",
-    "}",
-    "",
-    "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
-    'console.error("\\n  Unknown: kumiko " + (cmd ?? "") + " — only \'kumiko schema <sub>\' or \'kumiko consumer <sub>\' in the standalone bundle.\\n");',
-    "process.exit(1);",
-    "",
-  ].join("\n");
-}
-
-async function instantiateScaffoldFeatures(
-  features?: ReadonlyArray<ScaffoldFeatureEntry>,
-): Promise<readonly FeatureDefinition[]> {
-  const base = features?.length ? features : FOUNDATION_FEATURES;
-  const effective = base.filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
-  const instances: FeatureDefinition[] = [];
-  for (const entry of effective) {
-    const mod = (await import(entry.importPath)) as Record<string, unknown>;
-    const exp = mod[entry.exportName];
-    if (exp === undefined) {
-      throw new Error(
-        `scaffoldApp: ${entry.importPath} missing export ${entry.exportName} for ${entry.callExpression}`,
-      );
-    }
-    const looksCallable = entry.callExpression.endsWith(")");
-    if (looksCallable !== (typeof exp === "function")) {
-      throw new Error(
-        `scaffoldApp: ${entry.importPath} export ${entry.exportName} is ${
-          typeof exp === "function" ? "" : "not "
-        }callable but callExpression "${entry.callExpression}" says otherwise`,
-      );
-    }
-    if (typeof exp === "function") {
-      instances.push((exp as (...args: unknown[]) => FeatureDefinition)(...(entry.callArgs ?? [])));
-    } else {
-      instances.push(exp as FeatureDefinition);
-    }
-  }
-  instances.push(createDemoTasksFeature());
-  return instances;
-}
-
-async function writeInitMigration(
-  destination: string,
-  features?: ReadonlyArray<ScaffoldFeatureEntry>,
-): Promise<void> {
-  const instances = await instantiateScaffoldFeatures(features);
-  const composed = composeFeatures(instances, { includeBundled: true });
-  const metas = collectTableMetas(composed);
-  const result = generateMigration({
-    metas,
-    prevSnapshot: null,
-    name: "init",
-    sequenceNumber: 1,
-  });
-  const migrationsDir = join(destination, "kumiko", "migrations");
-  mkdirSync(migrationsDir, { recursive: true });
-  writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
-  writeSnapshotJson(join(migrationsDir, ".snapshot.json"), result.snapshot);
-}
-
-// Deterministic tenant-ID from app-name. Format: UUID-v4 with the
-// version-marker at the right spot. NOT cryptographically random —
-// just a stable per-app default the user can change later.
-function deriveTenantId(name: string): string {
-  let state = 2166136261;
-  for (const ch of name) {
-    state ^= ch.charCodeAt(0);
-    state = Math.imul(state, 16777619) >>> 0;
-  }
-  // @wrapper-known semantic-alias
-  const hex = (n: number, len: number): string => n.toString(16).padStart(len, "0").slice(0, len);
-  const a = hex(state, 8);
-  state ^= state << 13;
-  state >>>= 0;
-  const b = hex(state, 4);
-  state ^= state >>> 17;
-  state >>>= 0;
-  const c = `4${hex(state, 3)}`;
-  state ^= state << 5;
-  state >>>= 0;
-  const d4 = (0x8 | (state & 0x3)).toString(16);
-  const d = `${d4}${hex(state >>> 4, 3)}`;
-  state = Math.imul(state, 16777619) >>> 0;
-  const e = hex(state, 12);
-  return `${a}-${b}-${c}-${d}-${e}`;
-}