@cosmicdrift/kumiko-dev-server 0.24.0 → 0.25.0

package/bin/kumiko-schema-check.ts

@@ -25,6 +25,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { implicitAuthModeFeatureNames, resolveGeneratePath } from "../src/schema-check-core";
 
 type Args = {
   readonly runConfigPath: string;
@@ -34,7 +35,7 @@ type Args = {
 function parseArgs(argv: readonly string[]): Args {
   const cwd = process.cwd();
   let runConfigPath = resolve(cwd, "src/run-config.ts");
-  let generatePath = resolve(cwd, "drizzle/generate.ts");
+  let generatePath: string | undefined;
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
     const value = argv[i + 1];
@@ -46,7 +47,7 @@ function parseArgs(argv: readonly string[]): Args {
       i++;
     }
   }
-  return { runConfigPath, generatePath };
+  return { runConfigPath, generatePath: generatePath ?? resolveGeneratePath(cwd) };
 }
 
 function readRegistryFeatures(generateSrc: string): Set<string> {
@@ -74,20 +75,15 @@ async function readMountedFeatures(runConfigPath: string): Promise<Set<string>>
         `Convention: 'export const APP_FEATURES = [...] as const'.`,
     );
   }
-  // composeFeatures auto-prepends config + user + tenant + auth-email-
-  // password im auth-mode. Wenn HAS_AUTH=true (oder default), die 4
-  // implicit-mounted features auch in die Set tun damit der Diff nicht
-  // false-positive "auth-email-password is mounted but no registry-entry"
-  // produziert. Studio/use-all-bundled HAS_AUTH=true ist convention.
   const set = new Set<string>();
   for (const f of mod.APP_FEATURES) {
     set.add(f.name);
   }
+  // HAS_AUTH defaults to true (Studio/use-all-bundled convention). When set,
+  // include the implicit auth-mode features so the diff doesn't false-positive
+  // "auth-email-password is mounted but no registry-entry".
   if (mod.HAS_AUTH ?? true) {
-    set.add("config");
-    set.add("user");
-    set.add("tenant");
-    set.add("auth-email-password");
+    for (const name of implicitAuthModeFeatureNames()) set.add(name);
   }
   return set;
 }
@@ -156,4 +152,8 @@ async function main(): Promise<void> {
   }
 }
 
-await main();
+// Only run when executed as a CLI, not when imported (e.g. from tests that
+// exercise the exported pure helpers).
+if (import.meta.main) {
+  await main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/__tests__/env-schema.integration.test.ts

@@ -210,10 +210,17 @@ describe("runProdApp envSchema integration", () => {
     }
   });
 
-  it("KUMIKO_DRY_RUN_ENV=boot still aggregates env-errors before exit", async () => {
+  it("KUMIKO_DRY_RUN_ENV=boot does not skip env-validation (no success handle on invalid env)", async () => {
+    // Env-error aggregation itself is mode-independent (covered above). The
+    // boot-specific guarantee here: the boot dry-run — which returns a handle
+    // and exits early on VALID env (see the test above) — must NOT report
+    // success on INVALID env. It aborts with the aggregated errors and returns
+    // no handle, so a regression that made boot-mode bail out before validation
+    // would surface as a falsely-returned handle.
     let captured: KumikoBootError | undefined;
+    let handle: unknown;
     try {
-      await runProdApp({
+      handle = await runProdApp({
         features: [secretsFeature, authFeature],
         envSchema: composed,
         envSource: {
@@ -229,6 +236,7 @@ describe("runProdApp envSchema integration", () => {
     } catch (err) {
       expect(err).toBeInstanceOf(KumikoBootError);
     }
+    expect(handle).toBeUndefined();
     expect(captured).toBeDefined();
     expect(captured!.errors.length).toBeGreaterThanOrEqual(3);
   });

package/src/__tests__/env-schema.test.ts

@@ -32,6 +32,51 @@ describe("frameworkCoreEnvSchema", () => {
     }
   });
 
+  it("rejects a non-postgres DATABASE_URL even when it is a valid WHATWG URL", () => {
+    try {
+      parseEnv(frameworkCoreEnvSchema, {
+        DATABASE_URL: "https://example.com/db",
+        REDIS_URL: "redis://localhost:6379",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+      const db = (err as KumikoBootError).errors.find((e) => e.name === "DATABASE_URL");
+      expect(db?.kind).toBe("invalid");
+    }
+  });
+
+  it("accepts postgres:// and postgresql:// for DATABASE_URL", () => {
+    for (const url of ["postgres://localhost:5432/db", "postgresql://localhost:5432/db"]) {
+      const env = parseEnv(frameworkCoreEnvSchema, {
+        DATABASE_URL: url,
+        REDIS_URL: "redis://localhost:6379",
+      });
+      expect(env.DATABASE_URL).toBe(url);
+    }
+  });
+
+  it("rejects a non-redis REDIS_URL and accepts redis:// + rediss://", () => {
+    try {
+      parseEnv(frameworkCoreEnvSchema, {
+        DATABASE_URL: "postgres://localhost:5432/db",
+        REDIS_URL: "https://example.com/cache",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+      const redis = (err as KumikoBootError).errors.find((e) => e.name === "REDIS_URL");
+      expect(redis?.kind).toBe("invalid");
+    }
+    for (const url of ["redis://localhost:6379", "rediss://localhost:6379"]) {
+      const env = parseEnv(frameworkCoreEnvSchema, {
+        DATABASE_URL: "postgres://localhost:5432/db",
+        REDIS_URL: url,
+      });
+      expect(env.REDIS_URL).toBe(url);
+    }
+  });
+
   it("rejects an invalid PORT (non-numeric)", () => {
     try {
       parseEnv(frameworkCoreEnvSchema, {
@@ -70,6 +115,7 @@ describe("frameworkCoreEnvSchema", () => {
 
     try {
       parseEnv(schema, {}, { sources });
+      throw new Error("should have thrown");
     } catch (err) {
       const boot = err as KumikoBootError;
       const formatted = boot.format();

package/src/__tests__/kumiko-schema-check.test.ts

@@ -0,0 +1,57 @@
+// Unit-tests for the pure helpers behind the kumiko-schema-check bin.
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { composeFeatures } from "../compose-features";
+import { implicitAuthModeFeatureNames, resolveGeneratePath } from "../schema-check-core";
+
+describe("resolveGeneratePath", () => {
+  test("defaults to drizzle/generate.ts when neither candidate exists", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "schema-check-"));
+    try {
+      expect(resolveGeneratePath(cwd)).toBe(join(cwd, "drizzle/generate.ts"));
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  test("falls back to schema/generate.ts when drizzle/ is absent but schema/ exists", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "schema-check-"));
+    try {
+      mkdirSync(join(cwd, "schema"), { recursive: true });
+      writeFileSync(join(cwd, "schema/generate.ts"), "// stub", "utf-8");
+      expect(resolveGeneratePath(cwd)).toBe(join(cwd, "schema/generate.ts"));
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  test("prefers drizzle/generate.ts when both exist", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "schema-check-"));
+    try {
+      mkdirSync(join(cwd, "drizzle"), { recursive: true });
+      mkdirSync(join(cwd, "schema"), { recursive: true });
+      writeFileSync(join(cwd, "drizzle/generate.ts"), "// stub", "utf-8");
+      writeFileSync(join(cwd, "schema/generate.ts"), "// stub", "utf-8");
+      expect(resolveGeneratePath(cwd)).toBe(join(cwd, "drizzle/generate.ts"));
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("implicitAuthModeFeatureNames", () => {
+  test("matches composeFeatures' auth-mode prepend exactly (no hardcoded drift)", () => {
+    const fromCompose = composeFeatures([], { includeBundled: true }).map((f) => f.name);
+    expect(implicitAuthModeFeatureNames()).toEqual(fromCompose);
+    // Sanity: the current bundled-foundation set.
+    expect([...implicitAuthModeFeatureNames()].sort()).toEqual([
+      "auth-email-password",
+      "config",
+      "tenant",
+      "user",
+    ]);
+  });
+});

package/src/__tests__/run-prod-app-env-source.test.ts

@@ -0,0 +1,118 @@
+// Regression: the boot-path must read the injected `envSource`, not the real
+// process.env. Boot-mode (KUMIKO_DRY_RUN_ENV=boot) validates wiring + builds
+// the registry, then tears down the lazy DB/Redis clients before any socket
+// opens — so this runs without a real Postgres/Redis (same as the CI boot
+// smoke). Before the fix, requireEnv/readEnv read process.env directly, so the
+// required-var test would throw "required env var DATABASE_URL is missing" and
+// the PORT test would bind the default instead of the injected port.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { runProdApp } from "../run-prod-app";
+
+const probeEntity = createEntity({
+  fields: {
+    name: createTextField({ required: true }),
+    active: createBooleanField({ default: true }),
+  },
+  table: "env_source_probe",
+});
+
+const probeFeature = defineFeature("env-source-probe", (r) => {
+  r.entity("widget", probeEntity);
+  r.queryHandler({
+    name: "ping",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    handler: async () => ({ pong: true }),
+  });
+});
+
+// Cleared from process.env so the test fully controls config via envSource.
+// DATABASE_URL/REDIS_URL/JWT_SECRET are required (their read throws pre-fix);
+// PORT is non-throwing, cleared only so ambient PORT can't mask the second
+// test's "PORT comes from envSource" assertion.
+const CLEARED_VARS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET", "PORT"] as const;
+
+const DUMMY_ENV = {
+  KUMIKO_DRY_RUN_ENV: "boot",
+  DATABASE_URL: "postgres://smoke:smoke@127.0.0.1:1/smoke",
+  REDIS_URL: "redis://127.0.0.1:1",
+  JWT_SECRET: "smokesmokesmokesmokesmokesmokesmokesmoke",
+} as const;
+
+describe("runProdApp boot-mode env-source", () => {
+  const saved: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const k of CLEARED_VARS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+
+  afterEach(() => {
+    for (const k of CLEARED_VARS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  test("boots from injected envSource even when process.env lacks the required vars", async () => {
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    let handle: Awaited<ReturnType<typeof runProdApp>>;
+    try {
+      handle = await runProdApp({
+        features: [probeFeature],
+        autoListen: false,
+        migrations: false,
+        // REDIS_URL points at an unreachable port — boot-mode must NOT
+        // construct the (eager) Redis client, so this never tries to connect.
+        envSource: { ...DUMMY_ENV },
+      });
+    } finally {
+      console.log = originalLog;
+    }
+
+    // Boot-mode with an injected envSource returns an inert dry-run handle.
+    expect(handle).toBeDefined();
+    expect(typeof handle.stop).toBe("function");
+    // The registry was built + validated before any connection was opened.
+    expect(logs.some((line) => line.includes("boot validation OK"))).toBe(true);
+    await handle.stop();
+  });
+
+  test("resolves PORT from envSource, not process.env", async () => {
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    try {
+      const handle = await runProdApp({
+        features: [probeFeature],
+        autoListen: false,
+        migrations: false,
+        envSource: { ...DUMMY_ENV, PORT: "8123" },
+      });
+      await handle.stop();
+    } finally {
+      console.log = originalLog;
+    }
+
+    // The boot logs "booting Kumiko stack on port <port>" — pre-fix this read
+    // process.env["PORT"] (deleted here) and would log the 3000 default.
+    expect(logs.some((line) => line.includes("port 8123"))).toBe(true);
+    expect(logs.some((line) => line.includes("port 3000"))).toBe(false);
+  });
+});

package/src/__tests__/scaffold-app-feature.test.ts

@@ -1,7 +1,7 @@
 // scaffoldAppFeature unit-tests (DX-2).
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { scaffoldApp } from "../scaffold-app";
@@ -50,15 +50,13 @@ describe("scaffoldAppFeature", () => {
     expect(runConfig).toMatch(/\]\s*as const;/);
   });
 
-  test("idempotent: re-mount of existing feature is a no-op", () => {
+  test("mounting a second feature keeps the first feature's import exactly once", () => {
+    // Cross-feature non-duplication: adding billing must not touch the
+    // product-catalog import/entry. Same-feature re-mount idempotency is the
+    // next test — the dir-exists guard blocks a direct second scaffold of the
+    // same name, so this one cannot reach the short-circuit branches.
     scaffoldAppFeature({ name: "product-catalog", appRoot });
     const firstRunConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
-    // Now re-mount (second feature creates dir-already-exists error;
-    // we instead simulate "feature dir exists, only run-config dance").
-    // → Real DX-2 flow: scaffold fails on dir-exists; manual remount
-    //   would call mountInRunConfig directly. Test the mount-side
-    //   idempotency by triggering a second feature with a different
-    //   name and asserting the first import stays exactly once.
     scaffoldAppFeature({ name: "billing", appRoot });
     const secondRunConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
     expect(secondRunConfig).toContain("productCatalogFeature");
@@ -69,11 +67,88 @@ describe("scaffoldAppFeature", () => {
     expect(firstRunConfig.length).toBeLessThan(secondRunConfig.length);
   });
 
+  test("idempotent: re-scaffolding the same feature is a full no-op on run-config", () => {
+    scaffoldAppFeature({ name: "product-catalog", appRoot });
+    const runConfigPath = join(appRoot, "src/run-config.ts");
+    const afterFirst = readFileSync(runConfigPath, "utf-8");
+
+    // Drop only the feature dir so the dir-exists guard doesn't trip; the
+    // run-config import + APP_FEATURES entry both survive. The re-scaffold must
+    // hit the full short-circuit in mountInRunConfig (import present AND
+    // alreadyListed → changed=false → no save) and duplicate neither half —
+    // the branch the cross-feature test above never reaches.
+    rmSync(join(appRoot, "src/features/product-catalog"), { recursive: true, force: true });
+    const result = scaffoldAppFeature({ name: "product-catalog", appRoot });
+    expect(result.autoMounted).toBe(true);
+
+    const afterSecond = readFileSync(runConfigPath, "utf-8");
+    expect(afterSecond).toBe(afterFirst); // byte-identical: no save, no duplication
+    expect((afterSecond.match(/productCatalogFeature/g) ?? []).length).toBe(2);
+  });
+
+  test("self-heals a half-mounted run-config: import present but APP_FEATURES entry removed", () => {
+    scaffoldAppFeature({ name: "product-catalog", appRoot });
+    const runConfigPath = join(appRoot, "src/run-config.ts");
+
+    // Simulate a half-applied state: the feature dir is gone and the
+    // APP_FEATURES entry was hand-removed, but the import line still lingers.
+    rmSync(join(appRoot, "src/features/product-catalog"), { recursive: true, force: true });
+    const stripped = readFileSync(runConfigPath, "utf-8")
+      // Drop the APP_FEATURES array element (appended last, so `, productCatalogFeature`
+      // right before the closing `]`). The import `{ productCatalogFeature }` is
+      // followed by ` }`, not `]`/`,`, so the lookahead leaves it intact.
+      .replace(/,\s*productCatalogFeature(?=\s*\])/, "");
+    writeFileSync(runConfigPath, stripped, "utf-8");
+    // Guard the simulation itself: the import must remain, the array entry must
+    // be gone — exactly one mention left. Without this, a regex that failed to
+    // strip would leave the entry in place and the test would false-pass.
+    expect(stripped).toContain(
+      'import { productCatalogFeature } from "./features/product-catalog";',
+    );
+    expect((stripped.match(/productCatalogFeature/g) ?? []).length).toBe(1);
+
+    // Re-scaffold: dir is gone so it proceeds; mountInRunConfig sees the import
+    // already present and must still re-add the missing APP_FEATURES entry.
+    const result = scaffoldAppFeature({ name: "product-catalog", appRoot });
+    expect(result.autoMounted).toBe(true);
+
+    const healed = readFileSync(runConfigPath, "utf-8");
+    // Import stays exactly once; the array entry is back.
+    const occurrences = healed.match(/productCatalogFeature/g) ?? [];
+    expect(occurrences.length).toBe(2); // 1 import + 1 array-entry
+    expect(healed).toMatch(/\]\s*as const;/);
+  });
+
   test("rejects non-kebab-case", () => {
     expect(() => scaffoldAppFeature({ name: "ProductCatalog", appRoot })).toThrow(/kebab-case/);
     expect(() => scaffoldAppFeature({ name: "product_catalog", appRoot })).toThrow(/kebab-case/);
   });
 
+  test("rejects trailing- and double-hyphen names (kebabToCamel would break)", () => {
+    // `product-` → kebabToCamel leaves a trailing hyphen → `product-Feature`,
+    // an invalid identifier. The segment-strict regex must reject these.
+    expect(() => scaffoldAppFeature({ name: "product-", appRoot })).toThrow(/kebab-case/);
+    expect(() => scaffoldAppFeature({ name: "foo--bar", appRoot })).toThrow(/kebab-case/);
+  });
+
+  test("rolls back the scaffolded dir when run-config has no APP_FEATURES (re-run not blocked)", () => {
+    // run-config exists but is the wrong shape → mountInRunConfig throws. The
+    // feature files were already written; without rollback a re-run would hit
+    // the "already exists" guard and the user would be stuck.
+    const runConfigPath = join(appRoot, "src/run-config.ts");
+    writeFileSync(runConfigPath, "export const NOT_APP_FEATURES = [];\n", "utf-8");
+
+    expect(() => scaffoldAppFeature({ name: "orders", appRoot })).toThrow(/APP_FEATURES/);
+    // Rolled back: the half-written feature dir is gone.
+    expect(existsSync(join(appRoot, "src/features/orders"))).toBe(false);
+
+    // Re-run with a valid run-config now succeeds instead of "already exists".
+    writeFileSync(runConfigPath, "export const APP_FEATURES = [] as const;\n", "utf-8");
+    const result = scaffoldAppFeature({ name: "orders", appRoot });
+    expect(result.autoMounted).toBe(true);
+    expect(existsSync(join(appRoot, "src/features/orders/feature.ts"))).toBe(true);
+  });
+
   test("refuses to overwrite existing feature dir", () => {
     scaffoldAppFeature({ name: "billing", appRoot });
     expect(() => scaffoldAppFeature({ name: "billing", appRoot })).toThrow(/already exists/);

package/src/__tests__/scaffold-app.test.ts

@@ -63,6 +63,21 @@ describe("scaffoldApp", () => {
     expect(main).toMatch(/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/);
   });
 
+  test("bin/main.ts composes the auth-mode feature set into envSchema (JWT_SECRET boot-gate)", () => {
+    const dest = join(tmp, "my-shop");
+    scaffoldApp({ name: "my-shop", destination: dest });
+
+    const main = readFileSync(join(dest, "bin/main.ts"), "utf-8");
+    // envSchema must cover the same features runProdApp auto-mixes via
+    // auth-mode — otherwise auth-email-password's JWT_SECRET (min-32) is
+    // absent from the boot-gate and a too-short secret slips through.
+    expect(main).toContain("composeFeatures(APP_FEATURES, { includeBundled: true })");
+    expect(main).toContain(
+      "composeEnvSchema({ core: frameworkCoreEnvSchema, features: bootFeatures })",
+    );
+    expect(main).toContain("composeFeatures");
+  });
+
   test("src/run-config.ts mounts secrets + sessions as foundation", () => {
     const dest = join(tmp, "my-shop");
     scaffoldApp({ name: "my-shop", destination: dest });
@@ -79,6 +94,25 @@ describe("scaffoldApp", () => {
     expect(() => scaffoldApp({ name: "0shop", destination: tmp })).toThrow(/kebab-case/);
   });
 
+  test("rejects trailing- and double-hyphen names (invalid package segment)", () => {
+    expect(() => scaffoldApp({ name: "my-shop-", destination: tmp })).toThrow(/kebab-case/);
+    expect(() => scaffoldApp({ name: "my--shop", destination: tmp })).toThrow(/kebab-case/);
+  });
+
+  test("resolves a relative destination against the supplied cwd, not process.cwd()", () => {
+    // The CLI passes ctx.cwd; the scaffold must land under it so the
+    // displayed path matches the actual write location.
+    const result = scaffoldApp({ name: "shop", destination: "apps/shop", cwd: tmp });
+    expect(result.destination).toBe(join(tmp, "apps/shop"));
+    expect(existsSync(join(tmp, "apps/shop", "package.json"))).toBe(true);
+  });
+
+  test("resolves the name-default destination against the supplied cwd", () => {
+    const result = scaffoldApp({ name: "shop", cwd: tmp });
+    expect(result.destination).toBe(join(tmp, "shop"));
+    expect(existsSync(join(tmp, "shop", "package.json"))).toBe(true);
+  });
+
   test("refuses to overwrite existing destination", () => {
     const dest = join(tmp, "existing");
     scaffoldApp({ name: "existing", destination: dest });

package/src/__tests__/scaffold-deploy.test.ts

@@ -1,8 +1,8 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { scaffoldDeploy } from "../scaffold-deploy";
+import { render, scaffoldDeploy } from "../scaffold-deploy";
 
 describe("scaffoldDeploy", () => {
   let tmp: string;
@@ -41,6 +41,16 @@ describe("scaffoldDeploy", () => {
     expect(migrate).toContain("ghcr.io/acme/myapp:latest");
     // biome-ignore lint/suspicious/noTemplateCurlyInString: shell-substitution literal, not a JS template
     expect(migrate).toContain("postgresql://myapp:${DB_PASSWORD}@db:5432/myapp");
+    // The password-bearing URL is composed into the shell env and passed by
+    // NAME (`-e DATABASE_URL`, no `=`), so the expanded value never lands in
+    // `docker run`'s argv (would be visible in `ps auxe`).
+    expect(migrate).toContain("export DATABASE_URL=");
+    expect(migrate).toMatch(/-e DATABASE_URL\b(?!=)/);
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: shell-substitution literal, not a JS template
+    expect(migrate).not.toContain('-e DATABASE_URL="postgresql://myapp:${DB_PASSWORD}');
+    // grep's no-match exit must not abort the script before the friendly
+    // "No _stack network found" branch runs.
+    expect(migrate).toContain("| head -1 || true)");
     // Docker template syntax {{.Name}} must pass through verbatim — our
     // placeholder regex only matches lowercase-leading identifiers.
     expect(migrate).toContain('"{{.Name}}"');
@@ -148,6 +158,27 @@ describe("scaffoldDeploy", () => {
     );
   });
 
+  describe("render placeholder consumption", () => {
+    it("passes Docker/Go template syntax {{.X}} through verbatim", () => {
+      const out = render('docker network ls --format "{{.Name}}"', {}, {});
+      expect(out).toBe('docker network ls --format "{{.Name}}"');
+    });
+
+    it("substitutes known {{key}} placeholders", () => {
+      expect(render("hello {{who}}", { who: "world" }, {})).toBe("hello world");
+    });
+
+    it("throws on an orphan close-tag (no opener) instead of leaking it", () => {
+      expect(() => render("line\n{{/hasSeeds}}\nmore", {}, {})).toThrow(/unconsumed mustache/);
+    });
+
+    it("strips a matched block but does not leave its close-tag behind", () => {
+      const out = render("a\n{{#flag}}\nkept\n{{/flag}}\nb", {}, { flag: true });
+      expect(out).toContain("kept");
+      expect(out).not.toContain("{{/flag}}");
+    });
+  });
+
   describe("source-tree detection", () => {
     it("emits seeds-COPY block only when seeds/ exists", () => {
       // Without seeds/: block stripped
@@ -205,10 +236,17 @@ describe("scaffoldDeploy", () => {
       expect(df).not.toContain("ENV GITHUB_TOKEN");
     });
 
-    it("malformed package.json doesn't crash detection (defaults to no private deps)", () => {
-      writeFileSync(join(tmp, "package.json"), "{ this is not json");
-      const result = scaffoldDeploy({ appName: "broken", destination: tmp });
-      expect(result.detected.hasPrivateGhPackages).toBe(false);
+    it("malformed package.json warns + defaults to no private deps (mis-detection is visible)", () => {
+      const warn = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        writeFileSync(join(tmp, "package.json"), "{ this is not json");
+        const result = scaffoldDeploy({ appName: "broken", destination: tmp });
+        expect(result.detected.hasPrivateGhPackages).toBe(false);
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn.mock.calls[0]?.[0]).toContain("is not valid JSON");
+      } finally {
+        warn.mockRestore();
+      }
     });
   });
 });

package/src/codegen/__tests__/render-codegen.test.ts

@@ -39,6 +39,28 @@ describe("renderInlineSchemasFile", () => {
     expect(out).toContain("// inventory:event:product-archived — from src/feature.ts:92");
     expect(out).not.toContain(appRoot);
   });
+
+  test("falls back to the bare filename when a feature file is outside the app root", () => {
+    // A bundled-feature file lives in node_modules, outside the app root —
+    // relative() would emit `../../..`. The comment falls back to basename.
+    const appRoot = join(tmpdir(), "kumiko-codegen-app");
+    const featurePath = join(tmpdir(), "node_modules", "pkg", "dist", "feature.ts");
+    const events: ScannedEvent[] = [
+      {
+        qualifiedName: "bundled:event:thing-happened",
+        schemaSource: {
+          kind: "inline",
+          schemaSource: "z.object({ id: z.string() })",
+          generatedConstName: "_kg_bundled__thingHappened",
+        },
+        featureFilePath: featurePath,
+        source: { file: featurePath, line: 7 },
+      },
+    ];
+    const out = renderInlineSchemasFile(events, appRoot);
+    expect(out).toContain("// bundled:event:thing-happened — from feature.ts:7");
+    expect(out).not.toContain("..");
+  });
 });
 
 describe("renderDefineFile", () => {

package/src/codegen/render.ts

@@ -22,7 +22,7 @@
 // actual change, so mtime doesn't tick and the TS language server
 // doesn't reload every 100ms.
 
-import { relative } from "node:path";
+import { basename, relative } from "node:path";
 import type { ScannedEvent } from "./scan-events";
 import { rewriteImportPath } from "./scan-events";
 
@@ -143,7 +143,11 @@ export function renderInlineSchemasFile(
   });
   for (const ev of sorted) {
     if (ev.schemaSource.kind !== "inline") continue;
-    const sourcePath = relative(appRootAbs, ev.featureFilePath).split("\\").join("/");
+    const rel = relative(appRootAbs, ev.featureFilePath).split("\\").join("/");
+    // Feature files outside the app root (e.g. a bundled dependency) yield a
+    // `../../..`-walk that clutters the source comment; fall back to the bare
+    // filename. Comment-only — the generated schema is unaffected.
+    const sourcePath = rel.startsWith("..") ? basename(ev.featureFilePath) : rel;
     lines.push(
       `// ${ev.qualifiedName} — from ${sourcePath}:${ev.source.line}`,
       `export const ${ev.schemaSource.generatedConstName} = ${ev.schemaSource.schemaSource};`,

package/src/env-schema.ts

@@ -27,12 +27,16 @@ export const frameworkCoreEnvSchema = z.object({
     .describe("HTTP listen port. runProdApp defaults to 3000 when unset."),
 
   DATABASE_URL: z
-    .url("DATABASE_URL must be a valid postgres:// URL")
+    // `protocol` is matched against the URL scheme without the trailing
+    // colon — `postgres://`/`postgresql://` pass, `https://`/`ftp://` are
+    // rejected so the error message's promise actually holds at boot.
+    .url({ protocol: /^postgres(ql)?$/, error: "DATABASE_URL must be a valid postgres:// URL" })
     .describe("Primary Postgres connection string (write + read).")
     .meta({ kumiko: { pulumi: { secret: true } } }),
 
   REDIS_URL: z
-    .url("REDIS_URL must be a valid redis:// URL")
+    // `redis://` + the TLS variant `rediss://` pass; other schemes reject.
+    .url({ protocol: /^rediss?$/, error: "REDIS_URL must be a valid redis:// URL" })
     .describe("Redis connection string for SSE-broker + job-queues.")
     .meta({ kumiko: { pulumi: { secret: true } } }),
 
@@ -47,7 +51,7 @@ export const frameworkCoreEnvSchema = z.object({
     ),
 
   // `z.string().optional()` (not `z.literal("1")`) — the run-prod-app
-  // call-site (`process.env["KUMIKO_SKIP_ES_OPS"] !== "1"`) ignores any
+  // call-site (`envSource["KUMIKO_SKIP_ES_OPS"] !== "1"`) ignores any
   // value other than literal "1". A stricter schema would reject e.g.
   // "true" / "yes" that the runtime silently ignores, surfacing
   // boot-errors for inputs the framework doesn't actually care about.

package/src/run-prod-app.ts

@@ -110,8 +110,11 @@ export function buildBunServeOptions(
 
 // Strict env-var read. Throws with a clear hint when missing — better
 // than discovering a Postgres-connection-refused 30s into the boot.
-function requireEnv(name: string): string {
-  const value = process.env[name];
+// `src` defaults to process.env but is threaded from the caller's envSource
+// so the boot-path reads the SAME env-quelle that was validated above —
+// injected dummies in test-mode must not silently fall back to process.env.
+function requireEnv(name: string, src: Record<string, string | undefined> = process.env): string {
+  const value = src[name];
   if (value === undefined || value === "") {
     throw new Error(
       `runProdApp: required env var "${name}" is missing or empty. ` +
@@ -123,8 +126,11 @@ function requireEnv(name: string): string {
 
 // Optional env helper — returns undefined for missing, string for set.
 // Used for KUMIKO_INSTANCE_ID, JWT_ISSUER and other "nice to have" knobs.
-function readEnv(name: string): string | undefined {
-  const value = process.env[name];
+function readEnv(
+  name: string,
+  src: Record<string, string | undefined> = process.env,
+): string | undefined {
+  const value = src[name];
   return value === undefined || value === "" ? undefined : value;
 }
 
@@ -535,26 +541,21 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // 2. Env-vars: fail-fast. Better a 0s boot crash with a clear error
   //    than a 30s timeout chasing a Postgres connection that was never
   //    configured.
-  const databaseUrl = requireEnv("DATABASE_URL");
-  const redisUrl = requireEnv("REDIS_URL");
-  const jwtSecret = requireEnv("JWT_SECRET");
-  const jwtIssuer = readEnv("JWT_ISSUER");
-  const instanceId = readEnv("KUMIKO_INSTANCE_ID");
-  const port = options.port ?? Number.parseInt(process.env["PORT"] ?? "3000", 10);
+  const databaseUrl = requireEnv("DATABASE_URL", envSource);
+  const redisUrl = requireEnv("REDIS_URL", envSource);
+  const jwtSecret = requireEnv("JWT_SECRET", envSource);
+  const jwtIssuer = readEnv("JWT_ISSUER", envSource);
+  const instanceId = readEnv("KUMIKO_INSTANCE_ID", envSource);
+  const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
 
   // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
   console.log(`[runProdApp] booting Kumiko stack on port ${port}…`);
 
-  // 3. Connections — Postgres + Redis. The Redis client is shared by
-  //    idempotency, event-dedup, entity-cache, rate-limit; failing to
-  //    construct here surfaces the misconfig immediately.
-  const { db, close: closeDb } = createDbConnection(databaseUrl);
-  const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
-
-  // 4. Feature registry. Auth-mode auto-mixes config/user/tenant/auth-email-
+  // 3. Feature registry. Auth-mode auto-mixes config/user/tenant/auth-email-
   //    password via composeFeatures — same source-of-truth as runDevApp
   //    AND the per-app drizzle-Schema-Generator, so Migration und Runtime
-  //    sehen exakt dieselbe Liste.
+  //    sehen exakt dieselbe Liste. Built BEFORE any connection so boot-mode
+  //    can validate wiring and exit without opening a Postgres/Redis socket.
   const composeAuthOptions = buildComposeAuthOptions(options.auth);
   const features = composeFeatures(options.features, {
     includeBundled: !!options.auth,
@@ -564,22 +565,27 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   validateBoot(features);
   const registry = createRegistry(features);
 
-  // C1 boot-mode exit: validators ran, registry built, no DB/Redis
-  // operations executed yet (postgres.js + ioredis are lazy). Tear down
-  // the lazy clients so Bun doesn't keep them open, then exit / return.
+  // C1 boot-mode exit: validators ran + registry built; no DB/Redis client
+  // is constructed at all in this branch (the eager `new Redis(...)` below
+  // would otherwise open a TCP connect just to immediately disconnect it).
   if (runMode === "boot") {
     // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
     console.log(
       `[runProdApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`,
     );
-    await closeDb();
-    redis.disconnect();
     if (options.envSource === undefined) {
       process.exit(0);
     }
     return makeDryRunHandle();
   }
 
+  // 4. Connections — Postgres + Redis. The Redis client is shared by
+  //    idempotency, event-dedup, entity-cache, rate-limit; failing to
+  //    construct here surfaces the misconfig immediately. `new Redis(...)`
+  //    connects eagerly, so it must stay AFTER the boot-mode exit above.
+  const { db, close: closeDb } = createDbConnection(databaseUrl);
+  const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+
   // Sprint-8a Tier-Composition auto-wire: scan features for a
   // tenantTierResolver-extension. If found AND user didn't supply own
   // effectiveFeatures, build the resolver here (db + registry are
@@ -774,7 +780,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // if-missing"-Schicht; seed-migrations sind die "diff-and-update"-
   // Schicht für Drift den existing Seeds nicht erfassen können (z.B.
   // Membership-Roles-Change nach initialer Seed-Erstellung).
-  if (options.seedsDir !== undefined && process.env["KUMIKO_SKIP_ES_OPS"] !== "1") {
+  if (options.seedsDir !== undefined && envSource["KUMIKO_SKIP_ES_OPS"] !== "1") {
     await createEsOperationsTable(db);
     const seedDispatcher = createDispatcher(registry, {
       db,

package/src/scaffold-app-feature.ts

@@ -11,7 +11,7 @@
 // for the run-config side. Drizzle FEATURE_IMPORT_REGISTRY is NOT
 // touched here — DX-4 auto-discovery resolves that.
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { Project, SyntaxKind } from "ts-morph";
 
@@ -31,7 +31,10 @@ export type ScaffoldAppFeatureResult = {
   readonly autoMounted: boolean;
 };
 
-const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+// Segment-strict: rejects trailing/double hyphen (`product-`, `foo--bar`),
+// which kebabToCamel would otherwise turn into an invalid identifier
+// (`productFeature` vs the broken `product-Feature`).
+const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
 export function scaffoldAppFeature(options: ScaffoldAppFeatureOptions): ScaffoldAppFeatureResult {
   if (!KEBAB_RE.test(options.name)) {
@@ -56,9 +59,19 @@ export function scaffoldAppFeature(options: ScaffoldAppFeatureOptions): Scaffold
   files.push(`src/features/${options.name}/index.ts`);
 
   const runConfigPath = join(appRoot, "src", "run-config.ts");
-  const autoMounted = existsSync(runConfigPath)
-    ? mountInRunConfig(runConfigPath, options.name)
-    : false;
+  let autoMounted = false;
+  if (existsSync(runConfigPath)) {
+    try {
+      autoMounted = mountInRunConfig(runConfigPath, options.name);
+    } catch (err) {
+      // Roll back the freshly-written feature dir so a re-run isn't blocked
+      // by this function's own "already exists" guard. Without this, a
+      // shape-mismatch in run-config leaves feature.ts + index.ts on disk and
+      // the user is stuck having to hand-delete before retrying.
+      rmSync(featureDir, { recursive: true, force: true });
+      throw err;
+    }
+  }
 
   return {
     featureName: options.name,
@@ -98,8 +111,8 @@ function kebabToCamel(name: string): string {
 }
 
 // ts-morph: open run-config, prepend import, append APP_FEATURES entry.
-// Returns true on success, throws on shape-mismatch (caller swallows the
-// scaffolded files but warns).
+// Returns true on success, throws on shape-mismatch — the caller rolls back
+// the scaffolded feature dir and re-throws so a re-run isn't blocked.
 function mountInRunConfig(runConfigPath: string, name: string): boolean {
   const camel = kebabToCamel(name);
   const project = new Project({
@@ -108,20 +121,25 @@ function mountInRunConfig(runConfigPath: string, name: string): boolean {
   });
   const sf = project.addSourceFileAtPath(runConfigPath);
 
-  // Already mounted? short-circuit (idempotent re-runs).
-  const existingImport = sf.getImportDeclaration(`./features/${name}`);
-  if (existingImport) return true;
-
-  // 1. Prepend import after the last existing import.
-  const imports = sf.getImportDeclarations();
-  const insertIndex =
-    imports.length > 0 ? (imports[imports.length - 1]?.getChildIndex() ?? 0) + 1 : 0;
-  sf.insertImportDeclaration(insertIndex, {
-    moduleSpecifier: `./features/${name}`,
-    namedImports: [`${camel}Feature`],
-  });
+  // Import and APP_FEATURES entry are checked independently so a half-applied
+  // state self-heals: if the import exists but the entry was hand-removed (or
+  // vice versa), re-running adds only the missing half instead of short-
+  // circuiting on the import alone and leaving the feature unmounted.
+  let changed = false;
+
+  // 1. Prepend import after the last existing import — only if absent.
+  if (!sf.getImportDeclaration(`./features/${name}`)) {
+    const imports = sf.getImportDeclarations();
+    const insertIndex =
+      imports.length > 0 ? (imports[imports.length - 1]?.getChildIndex() ?? 0) + 1 : 0;
+    sf.insertImportDeclaration(insertIndex, {
+      moduleSpecifier: `./features/${name}`,
+      namedImports: [`${camel}Feature`],
+    });
+    changed = true;
+  }
 
-  // 2. Find `export const APP_FEATURES = [...]` and append the new entry.
+  // 2. Find `export const APP_FEATURES = [...]` and append the entry — only if absent.
   const appFeaturesDecl = sf.getVariableDeclaration("APP_FEATURES");
   if (!appFeaturesDecl) {
     throw new Error(
@@ -143,9 +161,13 @@ function mountInRunConfig(runConfigPath: string, name: string): boolean {
   if (!arr) {
     throw new Error(`mountInRunConfig: APP_FEATURES is not an array literal — cannot auto-mount.`);
   }
-  arr.addElement(`${camel}Feature`);
+  const alreadyListed = arr.getElements().some((el) => el.getText() === `${camel}Feature`);
+  if (!alreadyListed) {
+    arr.addElement(`${camel}Feature`);
+    changed = true;
+  }
 
-  sf.saveSync();
+  if (changed) sf.saveSync();
   return true;
 }
 

package/src/scaffold-app.ts

@@ -20,6 +20,11 @@ export type ScaffoldAppOptions = {
   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;
 };
@@ -30,13 +35,15 @@ export type ScaffoldAppResult = {
   readonly appName: string;
 };
 
-const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+// Segment-strict: rejects trailing/double hyphen so the name is a valid
+// package-name + folder (`my-shop`, not `my-` or `my--shop`).
+const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
 export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
   if (!KEBAB_RE.test(options.name)) {
     throw new Error(`scaffoldApp: name must be kebab-case (a-z, 0-9, -); got "${options.name}"`);
   }
-  const cwd = process.cwd();
+  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`);
@@ -178,7 +185,7 @@ function renderMain(appName: string): string {
 
   sf.addImportDeclaration({
     moduleSpecifier: "@cosmicdrift/kumiko-dev-server",
-    namedImports: ["frameworkCoreEnvSchema", "runProdApp"],
+    namedImports: ["composeFeatures", "frameworkCoreEnvSchema", "runProdApp"],
   });
   sf.addImportDeclaration({
     moduleSpecifier: "@cosmicdrift/kumiko-framework/engine",
@@ -204,12 +211,27 @@ function renderMain(appName: string): string {
     ],
   });
 
+  // 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:true); 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: true })",
+      },
+    ],
+  });
+
   sf.addVariableStatement({
     declarationKind: VariableDeclarationKind.Const,
     declarations: [
       {
         name: "envSchema",
-        initializer: "composeEnvSchema({ core: frameworkCoreEnvSchema, features: APP_FEATURES })",
+        initializer: "composeEnvSchema({ core: frameworkCoreEnvSchema, features: bootFeatures })",
       },
     ],
   });
@@ -249,7 +271,7 @@ function renderMain(appName: string): string {
       "// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after",
       "// composeFeatures + validateBoot + createRegistry without DB/Redis-connect",
       "// (siehe @cosmicdrift/kumiko-dev-server runProdApp). Echter Dev-Boot",
-      "// passiert via `bun kumiko dev` (in-repo dev-tool) mit Docker-stack — DX-1.0 deckt nur",
+      "// passiert via `bunx kumiko dev` (in-repo dev-tool) mit Docker-stack — DX-1.0 deckt nur",
       "// den boot-mode-Pfad ab; `kumiko dev` kommt in einer späteren DX-Phase.",
       "",
       "",

package/src/scaffold-deploy.ts

@@ -64,7 +64,9 @@ const TEMPLATE_FILES = [
   { template: "migrate-step.sh.template", output: "migrate-step.sh" },
 ] as const;
 
-const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+// Segment-strict: rejects trailing/double hyphen so the appName is a valid
+// image-tag + folder segment (`kumiko-studio`, not `kumiko-` / `kumiko--x`).
+const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
 export function scaffoldDeploy(options: ScaffoldDeployOptions): ScaffoldDeployResult {
   if (!KEBAB_RE.test(options.appName)) {
@@ -143,14 +145,26 @@ function detectOptionalSurfaces(sourceDir: string): ScaffoldDeployDetected {
       hasPrivateGhPackages = Object.keys(allDeps).some((d) =>
         d.startsWith("@cosmicdriftgamestudio/"),
       );
-    } catch {
-      // malformed package.json — assume no private packages, app-author can override via Dockerfile
+    } catch (err) {
+      // malformed package.json — assume no private packages, app-author can
+      // override via Dockerfile. Warn so a silent mis-detection (later YN0041
+      // on yarn install) is traceable to the scaffold step.
+      // biome-ignore lint/suspicious/noConsole: scaffold visibility for skipped private-package detection
+      console.warn(
+        `scaffoldDeploy: package.json at ${pkgJsonPath} is not valid JSON — private-GH-packages detection skipped (${err instanceof Error ? err.message : String(err)})`,
+      );
     }
   }
   return { hasSeeds, hasPrivateGhPackages };
 }
 
-function render(
+// Unconsumed-mustache guard. After step 1+2 the only legitimate `{{`
+// survivors are Docker/Go template tags (`{{.Name}}`, leading `.`). An
+// orphan close-tag (`{{/foo}}` without an opener) matches neither step and
+// would otherwise leak into the rendered file as a silent failure.
+const ORPHAN_MUSTACHE_RE = /\{\{(?!\.)[^}]*\}\}/;
+
+export function render(
   source: string,
   subs: Readonly<Record<string, string>>,
   flags: Readonly<Record<string, boolean>>,
@@ -182,5 +196,13 @@ function render(
     return value;
   });
 
+  const orphan = ORPHAN_MUSTACHE_RE.exec(result);
+  if (orphan) {
+    throw new Error(
+      `scaffoldDeploy.render: unconsumed mustache tag "${orphan[0]}" — ` +
+        `likely an orphan close-tag (e.g. a stray "{{/flag}}") in the template.`,
+    );
+  }
+
   return result;
 }

package/src/schema-check-core.ts

@@ -0,0 +1,26 @@
+// Pure helpers for the `kumiko-schema-check` bin. Kept in src/ (vs. the bin)
+// so they are part of the tsc project + unit-testable without importing the
+// auto-running CLI.
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { composeFeatures } from "./compose-features";
+
+// The generate-script lives under different roots across apps: publicstatus
+// uses `drizzle/generate.ts`, the framework's own sample-apps use
+// `schema/generate.ts`. Pick whichever exists so a no-arg `bunx
+// kumiko-schema-check` works in both layouts; default to `drizzle/` for the
+// error message when neither is present.
+export function resolveGeneratePath(cwd: string): string {
+  const drizzlePath = resolve(cwd, "drizzle/generate.ts");
+  const schemaPath = resolve(cwd, "schema/generate.ts");
+  if (!existsSync(drizzlePath) && existsSync(schemaPath)) return schemaPath;
+  return drizzlePath;
+}
+
+// The features composeFeatures auto-prepends in auth-mode (config + user +
+// tenant + auth-email-password). Derived from composeFeatures itself so this
+// can't drift from the real prepend-list in compose-features.ts.
+export function implicitAuthModeFeatureNames(): readonly string[] {
+  return composeFeatures([], { includeBundled: true }).map((f) => f.name);
+}

package/templates/deploy/migrate-step.sh.template

@@ -16,7 +16,10 @@
 
 set -euo pipefail
 
-STACK_NETWORK=$(docker network ls --format "{{.Name}}" | grep -E "_stack$" | head -1)
+# `|| true` keeps `set -e`/`pipefail` from aborting the script when `grep`
+# finds no match (exit 1) — the empty-check below owns that case and prints
+# the actionable hint instead of a bare pipefail abort.
+STACK_NETWORK=$(docker network ls --format "{{.Name}}" | grep -E "_stack$" | head -1 || true)
 if [ -z "$STACK_NETWORK" ]; then
   echo "No _stack network found — compose project not running?" >&2
   exit 1
@@ -32,8 +35,14 @@ set +a
 # DATABASE_URL assumes: db user = appName, db name = appName, host "db"
 # (compose-service-name), port 5432. Adjust to your stack if different.
 # Image tag pinned to :latest — swap to :${BUILD_SHA} for atomic deploys.
+#
+# Compose DATABASE_URL into the shell env and pass it to the container by
+# NAME (`-e DATABASE_URL`, no value) so the expanded password never appears
+# in `docker run`'s argv — otherwise it would be visible in `ps auxe` for
+# the duration of the migrate run.
+export DATABASE_URL="postgresql://{{appName}}:${DB_PASSWORD}@db:5432/{{appName}}"
 docker run --rm \
   --network "$STACK_NETWORK" \
-  -e DATABASE_URL="postgresql://{{appName}}:${DB_PASSWORD}@db:5432/{{appName}}" \
+  -e DATABASE_URL \
   ghcr.io/{{githubOrg}}/{{appName}}:latest \
   bun /app/kumiko.js schema apply