@cosmicdrift/kumiko-dev-server 0.322.0 → 0.323.0

package/bin/kumiko-build.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env bun
 // kumiko-build — Production-Build für Kumiko-Apps. Convention-driven:
 //
-//   src/client.tsx | src/styles.css | public/   →  Client-Bundle (dist/)
-//   bin/main.ts                                  →  Server-Bundle (dist-server/)
+//   package.json "kumiko.clientEntries"/"kumiko.clientEntry",
+//     or src/client.tsx | src/styles.css | public/   →  Client-Bundle (dist/)
+//   bin/main.ts                                       →  Server-Bundle (dist-server/)
 //
 // Beide werden gebaut wenn die jeweiligen Conventions getroffen sind, sonst
 // übersprungen. Ein Workspace mit nur bin/main.ts kriegt nur den Server-
@@ -20,11 +21,12 @@ import { join, resolve } from "node:path";
 import {
   buildProdBundle,
   buildServerBundle,
-  discoverClientEntries,
   discoverServerEntry,
   formatBuildResult,
   formatServerBuildResult,
+  readClientEntriesConfig,
   readExtraRuntimeExternals,
+  resolveClientEntries,
 } from "../src/build";
 import { formatScanWarning, runCodegen } from "../src/codegen";
 
@@ -35,23 +37,27 @@ const red = "\x1b[31m";
 const yellow = "\x1b[33m";
 const reset = "\x1b[0m";
 
-const hasClient =
-  discoverClientEntries(cwd).length > 0 ||
-  existsSync(join(cwd, "src/styles.css")) ||
-  existsSync(join(cwd, "public")) ||
-  existsSync(join(cwd, "index.html"));
-const hasServer = discoverServerEntry(cwd) !== undefined;
+try {
+  // Read once up front — resolveClientEntries can throw (mutual exclusion,
+  // malformed declaration, unmigrated legacy client-*.tsx files) and that
+  // must surface through the same ✗/exit(1) path as every other build error.
+  const declaredClientEntries = readClientEntriesConfig(cwd);
+  const hasClient =
+    resolveClientEntries(cwd, declaredClientEntries).length > 0 ||
+    existsSync(join(cwd, "src/styles.css")) ||
+    existsSync(join(cwd, "public")) ||
+    existsSync(join(cwd, "index.html"));
+  const hasServer = discoverServerEntry(cwd) !== undefined;
 
-if (!hasClient && !hasServer) {
-  // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
-  console.error(
-    `\n  ${yellow}!${reset} Nichts zu bauen in ${cwd}.\n` +
-      `    Convention: src/client.tsx oder bin/main.ts erwartet.\n`,
-  );
-  process.exit(1);
-}
+  if (!hasClient && !hasServer) {
+    // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
+    console.error(
+      `\n  ${yellow}!${reset} Nichts zu bauen in ${cwd}.\n` +
+        `    Convention: src/client.tsx oder bin/main.ts erwartet.\n`,
+    );
+    process.exit(1);
+  }
 
-try {
   // Codegen-Pass vor dem Build — sicherstellt dass `.kumiko/define.ts`
   // und `types.generated.d.ts` synchron mit den r.defineEvent-Aufrufen
   // sind. Ohne diesen Pass würde ein veraltetes Wrapper-File ein
@@ -67,7 +73,7 @@ try {
 
   if (hasClient) {
     const t0 = performance.now();
-    const result = await buildProdBundle({ cwd });
+    const result = await buildProdBundle({ cwd, ...declaredClientEntries });
     const ms = Math.round(performance.now() - t0);
     // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
     console.log(formatBuildResult(result, ms));

package/bin/kumiko-init-deploy.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+// biome-ignore-all lint/suspicious/noConsole: CLI script, console is the feature.
+// kumiko-init-deploy — Scaffold deploy/{Dockerfile,Dockerfile.dockerignore,
+// migrate-step.sh} from the canonical templates shipped with this package.
+//
+// Usage:
+//   bunx kumiko-init-deploy --app <name> [--port <n>] [--github-org <org>] [--out <dir>] [--force]
+//   bunx kumiko-init-deploy --check   # drift check, exit 1 if deploy/ is stale
+
+import { runInitDeployCli } from "../src/init-deploy-cli";
+
+// Only run when executed as a CLI, not when imported (e.g. from tests that
+// exercise runInitDeployCli directly).
+if (import.meta.main) {
+  const exitCode = await runInitDeployCli({
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    out: { log: console.log, err: console.error },
+  });
+  process.exit(exitCode);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.322.0",
+  "version": "0.323.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -54,15 +54,16 @@
   "bin": {
     "kumiko-build": "./bin/kumiko-build.ts",
     "kumiko-dev": "./bin/kumiko-dev.ts",
+    "kumiko-init-deploy": "./bin/kumiko-init-deploy.ts",
     "kumiko-schema": "./bin/kumiko-schema.ts",
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts",
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.322.0",
-    "@cosmicdrift/kumiko-framework": "0.322.0",
-    "@cosmicdrift/kumiko-headless": "0.322.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.322.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.323.0",
+    "@cosmicdrift/kumiko-framework": "0.323.0",
+    "@cosmicdrift/kumiko-headless": "0.323.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.323.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/init-deploy-cli.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runInitDeployCli } from "../init-deploy-cli";
+
+function makeOut() {
+  const logs: string[] = [];
+  const errs: string[] = [];
+  return {
+    out: { log: (m: string) => logs.push(m), err: (m: string) => errs.push(m) },
+    logs,
+    errs,
+  };
+}
+
+describe("runInitDeployCli", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "kumiko-init-deploy-cli-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("scaffolds with an explicit --app and reports exit 0", async () => {
+    const { out, logs } = makeOut();
+    const code = await runInitDeployCli({ argv: ["--app", "myapp"], cwd: tmp, out });
+    expect(code).toBe(0);
+    expect(logs.some((l) => l.includes("Deploy scaffolding generated"))).toBe(true);
+  });
+
+  it("defaults --app from package.json name, stripping the scope", async () => {
+    writeFileSync(join(tmp, "package.json"), JSON.stringify({ name: "@cosmicdrift/some-app" }));
+    const { out, logs } = makeOut();
+    const code = await runInitDeployCli({ argv: [], cwd: tmp, out });
+    expect(code).toBe(0);
+    expect(logs.some((l) => l.includes("some-app"))).toBe(true);
+  });
+
+  it("fails with a usage error when --app is missing and package.json has no name", async () => {
+    const { out, errs } = makeOut();
+    const code = await runInitDeployCli({ argv: [], cwd: tmp, out });
+    expect(code).toBe(1);
+    expect(errs.some((e) => e.includes("--app <name> is required"))).toBe(true);
+  });
+
+  it("--check and --force are mutually exclusive (exit 2)", async () => {
+    const { out, errs } = makeOut();
+    const code = await runInitDeployCli({
+      argv: ["--app", "myapp", "--check", "--force"],
+      cwd: tmp,
+      out,
+    });
+    expect(code).toBe(2);
+    expect(errs.some((e) => e.includes("mutually exclusive"))).toBe(true);
+  });
+
+  it("--check exits 0 when deploy/ is already in sync", async () => {
+    const first = await runInitDeployCli({
+      argv: ["--app", "myapp"],
+      cwd: tmp,
+      out: makeOut().out,
+    });
+    expect(first).toBe(0);
+    const { out, logs } = makeOut();
+    const code = await runInitDeployCli({ argv: ["--app", "myapp", "--check"], cwd: tmp, out });
+    expect(code).toBe(0);
+    expect(logs.some((l) => l.includes("in sync"))).toBe(true);
+  });
+
+  it("--check exits 1 and lists drifted files when deploy/ is missing or stale", async () => {
+    const { out: outMissing, errs: errsMissing } = makeOut();
+    const missingCode = await runInitDeployCli({
+      argv: ["--app", "myapp", "--check"],
+      cwd: tmp,
+      out: outMissing,
+    });
+    expect(missingCode).toBe(1);
+    expect(errsMissing.some((e) => e.includes("missing"))).toBe(true);
+
+    await runInitDeployCli({ argv: ["--app", "myapp"], cwd: tmp, out: makeOut().out });
+    writeFileSync(join(tmp, "deploy", "Dockerfile"), "# stale");
+    const { out: outStale, errs: errsStale } = makeOut();
+    const staleCode = await runInitDeployCli({
+      argv: ["--app", "myapp", "--check"],
+      cwd: tmp,
+      out: outStale,
+    });
+    expect(staleCode).toBe(1);
+    expect(errsStale.some((e) => e.includes("differs"))).toBe(true);
+    expect(errsStale.some((e) => e.includes("--force to regenerate"))).toBe(true);
+  });
+
+  it("rejects a non-kebab appName via the underlying scaffold validation", async () => {
+    const { out, errs } = makeOut();
+    const code = await runInitDeployCli({ argv: ["--app", "MyApp"], cwd: tmp, out });
+    expect(code).toBe(1);
+    expect(errs.some((e) => e.includes("kebab-case"))).toBe(true);
+  });
+
+  it("rejects an invalid package.json#kumiko.deploy config with exit 1", async () => {
+    writeFileSync(
+      join(tmp, "package.json"),
+      JSON.stringify({ name: "myapp", kumiko: { deploy: { stackNetwork: "foo" } } }),
+    );
+    const { out, errs } = makeOut();
+    const code = await runInitDeployCli({ argv: ["--app", "myapp"], cwd: tmp, out });
+    expect(code).toBe(1);
+    expect(errs.some((e) => e.includes("stackNetwork"))).toBe(true);
+  });
+});

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

@@ -2,7 +2,7 @@ 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 { render, scaffoldDeploy } from "../scaffold-deploy";
+import { checkDeployDrift, render, scaffoldDeploy } from "../scaffold-deploy";
 
 describe("scaffoldDeploy", () => {
   let tmp: string;
@@ -212,13 +212,13 @@ describe("scaffoldDeploy", () => {
       const result = scaffoldDeploy({ appName: "ghapp", destination: tmp });
       expect(result.detected.hasPrivateGhPackages).toBe(true);
       const df = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
-      expect(df).toContain("ARG GITHUB_TOKEN=");
-      expect(df).toContain("ARG GITHUB_TOKEN\n");
+      expect(df).toContain("ARG NPM_AUTH_TOKEN=");
+      expect(df).toContain("ARG NPM_AUTH_TOKEN\n");
       // biome-ignore lint/suspicious/noTemplateCurlyInString: shell variable expansion, not a JS template
-      expect(df).toContain("ENV GITHUB_TOKEN=${GITHUB_TOKEN}");
+      expect(df).toContain("ENV GITHUB_TOKEN=${NPM_AUTH_TOKEN}");
     });
 
-    it("skips GITHUB_TOKEN blocks when only public @cosmicdrift/* deps are present", () => {
+    it("skips NPM_AUTH_TOKEN blocks when only public @cosmicdrift/* deps are present", () => {
       writeFileSync(
         join(tmp, "package.json"),
         JSON.stringify({
@@ -232,21 +232,233 @@ describe("scaffoldDeploy", () => {
       const result = scaffoldDeploy({ appName: "publicapp", destination: tmp });
       expect(result.detected.hasPrivateGhPackages).toBe(false);
       const df = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
-      expect(df).not.toContain("ARG GITHUB_TOKEN");
+      expect(df).not.toContain("ARG NPM_AUTH_TOKEN");
       expect(df).not.toContain("ENV GITHUB_TOKEN");
     });
 
-    it("malformed package.json warns + defaults to no private deps (mis-detection is visible)", () => {
+    it("manifests app with bunfig.toml: NPM_AUTH_TOKEN wiring + manifests-first COPY", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({
+          name: "manifestapp",
+          dependencies: { "@cosmicdriftgamestudio/kumiko-ai-foundation": "^0.2.0" },
+        }),
+      );
+      writeFileSync(join(tmp, "bunfig.toml"), "[install.scopes]\n");
+      const result = scaffoldDeploy({ appName: "manifestapp", destination: tmp });
+      expect(result.detected.installFromFullTree).toBe(false);
+      expect(result.detected.registryConfigFiles).toEqual(["bunfig.toml"]);
+      const df = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+      expect(df).toContain("ARG NPM_AUTH_TOKEN=");
+      expect(df).toContain("ARG NPM_AUTH_TOKEN\n");
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: shell variable expansion, not a JS template
+      expect(df).toContain("ENV GITHUB_TOKEN=${NPM_AUTH_TOKEN}");
+      expect(df).toContain(
+        "COPY package.json bun.lock bunfig.toml ./\nRUN bun install --frozen-lockfile",
+      );
+      expect(df).toMatch(
+        /FROM .* AS runtime\n(?:#[^\n]*\n)*ARG BUILD_VERSION=dev\nARG BUILD_TIME=unknown/,
+      );
+    });
+
+    it(".npmrc-only app copies .npmrc before install", () => {
+      writeFileSync(join(tmp, "package.json"), JSON.stringify({ name: "npmrcapp" }));
+      writeFileSync(
+        join(tmp, ".npmrc"),
+        "@cosmicdriftgamestudio:registry=https://npm.pkg.github.com\n",
+      );
+      const result = scaffoldDeploy({ appName: "npmrcapp", destination: tmp });
+      expect(result.detected.registryConfigFiles).toEqual([".npmrc"]);
+      const df = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+      expect(df).toContain("COPY package.json bun.lock .npmrc ./");
+    });
+
+    it("a workspaces app renders COPY . . before install (full-tree)", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "wsapp", workspaces: ["packages/*"] }),
+      );
+      const result = scaffoldDeploy({ appName: "wsapp", destination: tmp });
+      expect(result.detected.installFromFullTree).toBe(true);
+      const df = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+      expect(df).toContain("COPY . .\nRUN bun install --frozen-lockfile\nRUN bun run build");
+      expect(df).not.toContain("COPY package.json bun.lock");
+    });
+
+    it("a file:/workspace:/link: dependency spec triggers full-tree install without a workspaces field", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "localdepapp", dependencies: { "@app/define": "file:./.kumiko" } }),
+      );
+      const result = scaffoldDeploy({ appName: "localdepapp", destination: tmp });
+      expect(result.detected.installFromFullTree).toBe(true);
+    });
+  });
+
+  describe("kumiko.deploy config", () => {
+    it("no kumiko.deploy → migrate-step uses appName as db user and the discover block", () => {
+      scaffoldDeploy({ appName: "plainapp", destination: tmp });
+      const migrate = readFileSync(join(tmp, "deploy", "migrate-step.sh"), "utf-8");
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: shell-substitution literal, not a JS template
+      expect(migrate).toContain("postgresql://plainapp:${DB_PASSWORD}@db:5432/plainapp");
+      expect(migrate).toContain("docker network ls");
+      expect(migrate).not.toContain("basename");
+    });
+
+    it('dbUser "kumiko" substitutes only the DB-URL user, db name stays appName', () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "dbuserapp", kumiko: { deploy: { dbUser: "kumiko" } } }),
+      );
+      scaffoldDeploy({ appName: "dbuserapp", destination: tmp });
+      const migrate = readFileSync(join(tmp, "deploy", "migrate-step.sh"), "utf-8");
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: shell-substitution literal, not a JS template
+      expect(migrate).toContain("postgresql://kumiko:${DB_PASSWORD}@db:5432/dbuserapp");
+    });
+
+    it('stackNetwork "directory" renders the exact-name block, not the discover block', () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "dirapp", kumiko: { deploy: { stackNetwork: "directory" } } }),
+      );
+      scaffoldDeploy({ appName: "dirapp", destination: tmp });
+      const migrate = readFileSync(join(tmp, "deploy", "migrate-step.sh"), "utf-8");
+      expect(migrate).toContain('STACK_NETWORK="$(basename "$PWD")_stack"');
+      expect(migrate).toContain("docker network inspect");
+      expect(migrate).not.toContain("docker network ls");
+    });
+
+    it.each(["a;rm -rf /", "$(id)", "a b", ""])(
+      "rejects invalid dbUser %j, naming the field",
+      (dbUser) => {
+        writeFileSync(
+          join(tmp, "package.json"),
+          JSON.stringify({ name: "invaliddbuser", kumiko: { deploy: { dbUser } } }),
+        );
+        expect(() => scaffoldDeploy({ appName: "invaliddbuser", destination: tmp })).toThrow(
+          /dbUser/,
+        );
+      },
+    );
+
+    it("rejects an invalid stackNetwork value", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "invalidnet", kumiko: { deploy: { stackNetwork: "foo" } } }),
+      );
+      expect(() => scaffoldDeploy({ appName: "invalidnet", destination: tmp })).toThrow(
+        /stackNetwork/,
+      );
+    });
+
+    it("rejects an unknown key under kumiko.deploy (strict)", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "unknownkey", kumiko: { deploy: { dbHost: "elsewhere" } } }),
+      );
+      expect(() => scaffoldDeploy({ appName: "unknownkey", destination: tmp })).toThrow(/dbHost/);
+    });
+  });
+
+  describe("checkDeployDrift", () => {
+    it("reports missing when no deploy files exist yet", () => {
+      const result = checkDeployDrift({ appName: "driftapp", destination: tmp });
+      expect(result.drifted).toHaveLength(3);
+      expect(result.drifted.every((d) => d.reason === "missing")).toBe(true);
+    });
+
+    it("reports differs when an on-disk file no longer matches the rendered content", () => {
+      scaffoldDeploy({ appName: "driftapp", destination: tmp });
+      writeFileSync(join(tmp, "deploy", "Dockerfile"), "# hand-edited, drifted");
+      const result = checkDeployDrift({ appName: "driftapp", destination: tmp });
+      expect(result.drifted).toEqual([
+        { path: join(tmp, "deploy", "Dockerfile"), reason: "differs" },
+      ]);
+    });
+
+    it("reports no drift right after a fresh scaffold", () => {
+      scaffoldDeploy({ appName: "driftapp", destination: tmp });
+      const result = checkDeployDrift({ appName: "driftapp", destination: tmp });
+      expect(result.drifted).toHaveLength(0);
+    });
+
+    it("reports no drift for a scaffold rendered with a kumiko.deploy config", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "driftconfigapp", kumiko: { deploy: { dbUser: "kumiko" } } }),
+      );
+      scaffoldDeploy({ appName: "driftconfigapp", destination: tmp });
+      const result = checkDeployDrift({ appName: "driftconfigapp", destination: tmp });
+      expect(result.drifted).toHaveLength(0);
+    });
+
+    it("reports differs on migrate-step.sh after package.json's dbUser changes", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "driftconfigapp", kumiko: { deploy: { dbUser: "kumiko" } } }),
+      );
+      scaffoldDeploy({ appName: "driftconfigapp", destination: tmp });
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({ name: "driftconfigapp", kumiko: { deploy: { dbUser: "otheruser" } } }),
+      );
+      const result = checkDeployDrift({ appName: "driftconfigapp", destination: tmp });
+      expect(result.drifted).toEqual([
+        { path: join(tmp, "deploy", "migrate-step.sh"), reason: "differs" },
+      ]);
+    });
+
+    it("reports differs when the file on disk uses defaults but package.json now says directory", () => {
+      scaffoldDeploy({ appName: "driftconfigapp", destination: tmp });
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({
+          name: "driftconfigapp",
+          kumiko: { deploy: { stackNetwork: "directory" } },
+        }),
+      );
+      const result = checkDeployDrift({ appName: "driftconfigapp", destination: tmp });
+      expect(result.drifted).toEqual([
+        { path: join(tmp, "deploy", "migrate-step.sh"), reason: "differs" },
+      ]);
+    });
+  });
+
+  describe("malformed package.json", () => {
+    it("warns + defaults to no private deps and manifests-first install (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(result.detected.installFromFullTree).toBe(false);
         expect(warn).toHaveBeenCalledTimes(1);
         expect(warn.mock.calls[0]?.[0]).toContain("is not valid JSON");
       } finally {
         warn.mockRestore();
       }
     });
+
+    it("keeps a valid kumiko.deploy config even when dependencies has an unexpected shape", () => {
+      const warn = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        writeFileSync(
+          join(tmp, "package.json"),
+          JSON.stringify({
+            name: "shapeissue",
+            dependencies: "not-an-object",
+            kumiko: { deploy: { dbUser: "kumiko" } },
+          }),
+        );
+        const result = scaffoldDeploy({ appName: "shapeissue", destination: tmp });
+        expect(result.detected.hasPrivateGhPackages).toBe(false);
+        expect(warn).toHaveBeenCalledTimes(1);
+        const migrate = readFileSync(join(tmp, "deploy", "migrate-step.sh"), "utf-8");
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: shell-substitution literal, not a JS template
+        expect(migrate).toContain("postgresql://kumiko:${DB_PASSWORD}@db:5432/shapeissue");
+      } finally {
+        warn.mockRestore();
+      }
+    });
   });
 });

package/src/build.ts

@@ -9,10 +9,12 @@ export {
   type BuildResult,
   buildProdBundle,
   type ClientEntry,
-  discoverClientEntries,
+  type ClientEntryDeclaration,
   discoverHtmlTemplate,
   formatBuildResult,
   injectAssetTags,
+  readClientEntriesConfig,
+  resolveClientEntries,
 } from "@cosmicdrift/kumiko-server-runtime/build-prod-bundle";
 
 export {

package/src/changes.json

@@ -1,4 +1,30 @@
 [
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "Deploy Dockerfile template: NPM_AUTH_TOKEN registry auth, manifest-first or full-tree install by detected layout, BUILD_VERSION/BUILD_TIME in the runtime stage, TZ=UTC; new kumiko-init-deploy bin with --force and a --check drift check",
+    "migration": "The scaffolded `deploy/Dockerfile` now declares `ARG NPM_AUTH_TOKEN`\n(global + re-declared in the build stage) instead of `ARG GITHUB_TOKEN`,\nand exports `ENV GITHUB_TOKEN=${NPM_AUTH_TOKEN}` in the build stage —\nbunfig.toml/.npmrc still read `$GITHUB_TOKEN`, only the build-arg name\npassed by CI changes. Apps that already generated `deploy/Dockerfile`\nfrom an older template keep working unchanged; re-run\n`kumiko-init-deploy --force` (or `kumiko init-deploy --force` from the\nmonorepo) to pick up the new wiring, the runtime stage's\n`ARG BUILD_VERSION=dev`/`ARG BUILD_TIME=unknown` re-declaration (without\nit the runtime `ENV BUILD_VERSION`/`ENV BUILD_TIME` stayed empty despite\na correct `--build-arg`), and `ENV TZ=UTC`.\n\nThe install step now copies manifests first (`package.json`, `bun.lock`,\nand whichever of `bunfig.toml`/`.npmrc` exist) before `bun install`,\nunless the app's `package.json` has a `workspaces` field or a\n`file:`/`workspace:`/`link:` dependency spec, in which case it still\ndoes `COPY . .` first (bun needs the whole tree to resolve the\nlockfile).\n\n`scaffoldDeploy`/`ScaffoldDeployOptions`/`ScaffoldDeployResult` keep\ntheir existing shape and behavior. New: `renderDeployFiles` (pure,\nno writes) and `checkDeployDrift` (read-only, reports missing/differing\nfiles) are exported alongside `scaffoldDeploy`, which now calls\n`renderDeployFiles` internally. `ScaffoldDeployDetected` gained\n`installFromFullTree` and `registryConfigFiles`.\n\nNew `kumiko-init-deploy` bin (and `runInitDeployCli` export) — same\nflags as `kumiko init-deploy` (`--app`, `--port`, `--github-org`,\n`--out`, `--force`), plus `--check` (drift check, exit 1 on any\nmissing/differing file, does not write) and defaulting `--app` from\n`package.json`'s `name` (scope stripped) when omitted. `--check` and\n`--force` are mutually exclusive (exit 2). The monorepo's\n`kumiko init-deploy` command now delegates to `runInitDeployCli`\ninstead of duplicating the CLI logic."
+  },
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "migrate-step.sh reads package.json#kumiko.deploy (dbUser, stackNetwork \"discover\" | \"directory\"); defaults unchanged, invalid values fail the render and the drift check",
+    "migration": "No action needed: without `kumiko.deploy` the scaffolded\n`deploy/migrate-step.sh` renders byte-identical to before. Apps whose\ndatabase user is not the app name set\n`\"kumiko\": { \"deploy\": { \"dbUser\": \"<user>\" } }`; apps that want the\nexact `<dirname>_stack` network instead of the `docker network ls`\nheuristic set `\"stackNetwork\": \"directory\"`. Both `kumiko-init-deploy\n--force` and `--check` read the same config, so the drift check needs\nno extra flags. `ScaffoldDeployDetected` gained `dbUser` and\n`stackNetwork`."
+  },
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "runDevApp wires auth-email-password's new invite-info query into invite.infoHandler",
+    "detail": "Same wiring as runProdApp, for the dev server.",
+    "migration": "No action needed: purely additive wiring, no option changes."
+  },
+  {
+    "version": "0.323.0",
+    "type": "breaking",
+    "title": "kumiko-build reads client entries from package.json \"kumiko.clientEntries\"/\"kumiko.clientEntry\" instead of inferring them from filenames",
+    "detail": "`kumiko-build` (and the `kumiko build` command) now call\n`readClientEntriesConfig(cwd)` and pass the result into\n`buildProdBundle`, instead of relying on `discoverClientEntries`'\nfilename-based multi-entry discovery. `@cosmicdrift/kumiko-dev-server/build`\nre-exports `resolveClientEntries`, `readClientEntriesConfig`, and\n`ClientEntryDeclaration` in place of `discoverClientEntries`.",
+    "migration": "See the `@cosmicdrift/kumiko-server-runtime` changelog entry above for\nthe required package.json changes — the dev-server change is the CLI\nwiring for the same underlying behavior."
+  },
   {
     "version": "0.321.0",
     "type": "improvement",

package/src/create-kumiko-server.ts

@@ -85,18 +85,20 @@ const logInfo = (msg: string): void => console.log(msg);
 // biome-ignore lint/suspicious/noConsole: dev-server error logging
 const logError = (...args: unknown[]): void => console.error(...args);
 
-/** Multi-Entry-Mode für Apps die mehrere getrennte Bundles ausliefern
- *  (z.B. publicstatus: `admin.<base>` lädt Admin-UI, sonst Public-Page).
+/** Multi-entry mode for apps that ship several separate bundles (e.g.
+ *  publicstatus: `admin.<base>` loads the admin UI, otherwise the public
+ *  page).
  *
- *  Spiegelt die Convention von kumiko-build (`src/client-<name>.tsx`) und
- *  serviert `/client-<name>.js` per HTTP. Multi-Entry ist mutually
- *  exclusive mit `clientEntry`. Wer Multi-Entry nutzt MUSS auch
- *  `hostDispatch` setzen — sonst weiß der Server nicht welches HTML
- *  er rausgeben soll. */
+ *  kumiko-build reads the same entry list from package.json
+ *  `kumiko.clientEntries` and serves `/client-<name>.js` per HTTP — the
+ *  dev server and the prod build stay in sync via that shared declaration,
+ *  not a filename convention. Mutually exclusive with `clientEntry`.
+ *  Multi-entry apps MUST also set `hostDispatch` — otherwise the server
+ *  has no way to know which HTML to serve. */
 export type DevClientEntry = {
-  /** Logical Name. Frei wählbar; Convention: gleicher Suffix wie
-   *  `src/client-<name>.tsx` damit der Build identische Asset-URLs
-   *  liefert (`/client-<name>.js`). */
+  /** Logical name. Should match the corresponding package.json
+   *  `kumiko.clientEntries[].name` so dev and prod produce identical
+   *  asset URLs (`/client-<name>.js`). */
   readonly name: string;
   /** Absoluter Pfad zur Browser-Entry-Datei. */
   readonly sourceFile: string;

package/src/index.ts

@@ -68,6 +68,8 @@ export type {
 } from "./few-shot-corpus";
 export { buildFewShotCorpus, pathToId } from "./few-shot-corpus";
 export { resolveFrameworkVersion } from "./framework-version";
+export type { CliOutput, RunInitDeployCliOptions } from "./init-deploy-cli";
+export { runInitDeployCli } from "./init-deploy-cli";
 export type { RunDevAppAuthOptions, RunDevAppOptions, SeedFn } from "./run-dev-app";
 export { runDevApp } from "./run-dev-app";
 export type {
@@ -82,11 +84,17 @@ export type {
 } from "./scaffold-app-feature";
 export { runConfigPathForApp, scaffoldAppFeature } from "./scaffold-app-feature";
 export type {
+  CheckDeployDriftResult,
+  DeployDriftEntry,
+  RenderDeployFilesOptions,
+  RenderDeployFilesResult,
+  RenderedDeployFile,
+  ScaffoldDeployDetected,
   ScaffoldDeployOptions,
   ScaffoldDeployResult,
   ScaffoldedFile,
 } from "./scaffold-deploy";
-export { scaffoldDeploy } from "./scaffold-deploy";
+export { checkDeployDrift, renderDeployFiles, scaffoldDeploy } from "./scaffold-deploy";
 export type { ScaffoldFeatureOptions, ScaffoldFeatureResult } from "./scaffold-feature";
 export { scaffoldFeature } from "./scaffold-feature";
 export {