@cosmicdrift/kumiko-dev-server 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @cosmicdrift/kumiko-dev-server
 
+## 0.9.0
+
+### Minor Changes
+
+- 51e22f5: Add deploy-template scaffolding (Sprint 9.6).
+
+  **New API:**
+
+  - `scaffoldDeploy({ appName, port?, githubOrg?, destination?, force? })` exported from `@cosmicdrift/kumiko-dev-server`. Generates `deploy/Dockerfile`, `deploy/Dockerfile.dockerignore`, and `deploy/migrate-step.sh` from canonical templates shipped with the package. Substitutes `{{appName}}`, `{{port}}`, `{{githubOrg}}` placeholders.
+  - New CLI command: `kumiko init-deploy --app <name> [--port <n>] [--github-org <org>] [--out <dir>] [--force]`.
+
+  The templates are extracted from publicstatus's production-tested `deploy/Dockerfile` (node-alpine build stage → bun-alpine runtime, drizzle migrations baked in, healthcheck wired). Refuses to overwrite existing files unless `--force` is passed so a tuned per-app Dockerfile isn't clobbered.
+
+  **Templates are a starting point, not a contract.** Apps should review and adjust:
+
+  - **Image tag** is hardcoded `:latest` in `migrate-step.sh.template`. Swap to `:${BUILD_SHA}` for atomic deploys.
+  - **DB defaults** in `migrate-step.sh.template` assume `db user = db name = appName`, host `db`, port `5432`. Adjust to your stack.
+  - **`COPY /app/seeds`** assumes the app uses ES-Operations seed migrations. Comment out if your app has no `seeds/` directory (otherwise `docker build` fails).
+  - **`docker build`-smoke-test:** the templates run untested against a non-publicstatus app-tree. Verify locally before pushing to CI.
+
+  **Deferred to Sprint 9.7+:** `.github/workflows/build-image.yml.suggested`, `pulumi/secrets-bootstrap.sh`, `pulumi/extraEnv.snippet.ts`.
+
+  **Plan-Doc drift (for 9.9 update):** Plan-Doc-Tabelle nennt `start.sh` (in-container migrate-then-run); diese Implementation liefert `migrate-step.sh` (host-side deploy-pipeline). Beide Konzepte sind gültig — Plan-Doc-Update sollte das klarstellen.
+
+- 37fe758: `scaffoldDeploy()` inspects the app source-tree and emits Dockerfile blocks conditionally (Sprint 9.6 follow-up).
+
+  **Why this exists:** Sprint 9.6's first Dockerfile.template hardcoded `COPY --from=build /app/seeds ./seeds` with a "comment out if you don't use it" note in the changeset. Apps without a `seeds/` directory (e.g. studio.kumiko.so) crashed in Docker-build with `failed to compute cache key: "/app/seeds": not found`. Root-cause was a framework issue (template too rigid), not a per-app symptom — the framework should detect what the app actually has.
+
+  **Detection:**
+
+  - `hasSeeds` — `exists(sourceDir/seeds)`. Drives the ES-Ops `COPY ./seeds` block in the runtime stage.
+  - `hasPrivateGhPackages` — scan `package.json` `dependencies` + `devDependencies` for any `@cosmicdriftgamestudio/*` entry. Drives the `ARG GITHUB_TOKEN` blocks (multi-stage with explicit re-declaration inside the build-stage) and the `ENV GITHUB_TOKEN=${GITHUB_TOKEN}` re-export before `yarn install --immutable`.
+
+  **Template syntax:** mustache-style block conditionals `{{#flag}}…{{/flag}}` (multi-line via `[\s\S]`, surrounding line stripped on falsy). Plain `{{key}}` placeholder substitution is unchanged.
+
+  **New API:**
+
+  - `ScaffoldDeployOptions.sourceDir?: string` — defaults to `destination`. Lets the caller scaffold into one dir while detecting optional surfaces in another (rare).
+  - `ScaffoldDeployResult.detected: { hasSeeds, hasPrivateGhPackages }` — surfaced so the CLI can report what was emitted.
+
+  **6 new tests:** seeds detection (with + without), GH-Packages detection (private + public-only + malformed package.json).
+
+  Sprint 9.6's "starting point not contract" disclaimer in the original changeset is now obsolete for these two surfaces — apps no longer need to manually comment out lines.
+
+### Patch Changes
+
+- Updated dependencies [51e22f5]
+  - @cosmicdrift/kumiko-framework@0.9.0
+  - @cosmicdrift/kumiko-bundled-features@0.9.0
+
+## 0.8.1
+
+### Patch Changes
+
+- Updated dependencies [4b5f91e]
+  - @cosmicdrift/kumiko-framework@0.8.1
+  - @cosmicdrift/kumiko-bundled-features@0.8.1
+
 ## 0.8.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.8.0",
+  "version": "0.9.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>",
@@ -48,8 +48,8 @@
     "kumiko-dev": "./bin/kumiko-dev.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.8.0",
-    "@cosmicdrift/kumiko-framework": "0.8.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.9.0",
+    "@cosmicdrift/kumiko-framework": "0.9.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -57,6 +57,7 @@
   },
   "files": [
     "src",
+    "templates",
     "README.md",
     "LICENSE"
   ]

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

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { scaffoldDeploy } from "../scaffold-deploy";
+
+describe("scaffoldDeploy", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "kumiko-deploy-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("generates Dockerfile, Dockerfile.dockerignore, migrate-step.sh", () => {
+    const result = scaffoldDeploy({ appName: "myapp", destination: tmp });
+    expect(result.destination).toBe(join(tmp, "deploy"));
+    expect(result.files).toHaveLength(3);
+    expect(result.files.every((f) => f.written)).toBe(true);
+    expect(existsSync(join(tmp, "deploy", "Dockerfile"))).toBe(true);
+    expect(existsSync(join(tmp, "deploy", "Dockerfile.dockerignore"))).toBe(true);
+    expect(existsSync(join(tmp, "deploy", "migrate-step.sh"))).toBe(true);
+  });
+
+  it("substitutes {{appName}} + {{port}} + {{githubOrg}}", () => {
+    scaffoldDeploy({
+      appName: "myapp",
+      port: 4242,
+      githubOrg: "acme",
+      destination: tmp,
+    });
+    const dockerfile = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+    expect(dockerfile).toContain("Production-Image for myapp");
+    expect(dockerfile).toContain("ENV PORT=4242");
+    expect(dockerfile).toContain("EXPOSE 4242");
+
+    const migrate = readFileSync(join(tmp, "deploy", "migrate-step.sh"), "utf-8");
+    expect(migrate).toContain("myapp pre-deploy migrate step");
+    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");
+    // Docker template syntax {{.Name}} must pass through verbatim — our
+    // placeholder regex only matches lowercase-leading identifiers.
+    expect(migrate).toContain('"{{.Name}}"');
+  });
+
+  it("uses defaults when port + githubOrg are omitted", () => {
+    scaffoldDeploy({ appName: "minimal", destination: tmp });
+    const dockerfile = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+    expect(dockerfile).toContain("ENV PORT=3000");
+    expect(dockerfile).toContain("EXPOSE 3000");
+
+    const migrate = readFileSync(join(tmp, "deploy", "migrate-step.sh"), "utf-8");
+    expect(migrate).toContain("ghcr.io/cosmicdriftgamestudio/minimal:latest");
+  });
+
+  it("skips existing files by default", () => {
+    const existing = join(tmp, "deploy");
+    scaffoldDeploy({ appName: "first", destination: tmp });
+    writeFileSync(join(existing, "Dockerfile"), "# user-tuned, do not touch");
+    const second = scaffoldDeploy({ appName: "first", destination: tmp });
+    const dockerfile = second.files.find((f) => f.path.endsWith("/Dockerfile"));
+    expect(dockerfile?.written).toBe(false);
+    expect(dockerfile?.reason).toBe("exists");
+    expect(readFileSync(join(existing, "Dockerfile"), "utf-8")).toBe("# user-tuned, do not touch");
+  });
+
+  it("overwrites existing files with --force and tags reason='force'", () => {
+    scaffoldDeploy({ appName: "first", destination: tmp });
+    writeFileSync(join(tmp, "deploy", "Dockerfile"), "# old content");
+    const second = scaffoldDeploy({ appName: "first", destination: tmp, force: true });
+    const dockerfile = second.files.find((f) => f.path.endsWith("/Dockerfile"));
+    expect(dockerfile?.written).toBe(true);
+    expect(dockerfile?.reason).toBe("force");
+    expect(readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8")).toContain(
+      "Production-Image for first",
+    );
+  });
+
+  it("force=true on a fresh directory leaves reason undefined (no clobber happened)", () => {
+    // Regression guard: a clean first-time write with force=true must NOT
+    // be tagged as `reason: "force"` — that label is reserved for actual
+    // overwrites of pre-existing files. Fixed in self-review after the
+    // initial implementation set `reason: "force"` unconditionally
+    // post-write.
+    const result = scaffoldDeploy({ appName: "fresh", destination: tmp, force: true });
+    for (const f of result.files) {
+      expect(f.written).toBe(true);
+      expect(f.reason).toBeUndefined();
+    }
+  });
+
+  it("rejects appName that isn't kebab-case", () => {
+    expect(() => scaffoldDeploy({ appName: "MyApp", destination: tmp })).toThrow(/kebab-case/);
+    expect(() => scaffoldDeploy({ appName: "my_app", destination: tmp })).toThrow(/kebab-case/);
+    expect(() => scaffoldDeploy({ appName: "1app", destination: tmp })).toThrow(/kebab-case/);
+  });
+
+  it("rejects out-of-range port", () => {
+    expect(() => scaffoldDeploy({ appName: "x", port: 0, destination: tmp })).toThrow(/1\.\.65535/);
+    expect(() => scaffoldDeploy({ appName: "x", port: 70000, destination: tmp })).toThrow(
+      /1\.\.65535/,
+    );
+  });
+
+  describe("source-tree detection", () => {
+    it("emits seeds-COPY block only when seeds/ exists", () => {
+      // Without seeds/: block stripped
+      const without = scaffoldDeploy({ appName: "noseeds", destination: tmp });
+      expect(without.detected.hasSeeds).toBe(false);
+      const dfNo = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+      expect(dfNo).not.toContain("COPY --from=build --chown=app:app /app/seeds ./seeds");
+      expect(dfNo).not.toContain("ES-Operations seed migrations");
+    });
+
+    it("emits seeds-COPY block when seeds/ exists", () => {
+      mkdirSync(join(tmp, "seeds"), { recursive: true });
+      writeFileSync(join(tmp, "seeds", ".keep"), "");
+      const result = scaffoldDeploy({ appName: "withseeds", destination: tmp });
+      expect(result.detected.hasSeeds).toBe(true);
+      const df = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+      expect(df).toContain("COPY --from=build --chown=app:app /app/seeds ./seeds");
+      expect(df).toContain("ES-Operations seed migrations");
+    });
+
+    it("emits GITHUB_TOKEN blocks when @cosmicdriftgamestudio/* dep is present", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({
+          name: "ghapp",
+          dependencies: {
+            "@cosmicdriftgamestudio/kumiko-ai-foundation": "^0.2.0",
+          },
+        }),
+      );
+      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("ENV GITHUB_TOKEN=${GITHUB_TOKEN}");
+    });
+
+    it("skips GITHUB_TOKEN blocks when only public @cosmicdrift/* deps are present", () => {
+      writeFileSync(
+        join(tmp, "package.json"),
+        JSON.stringify({
+          name: "publicapp",
+          dependencies: {
+            "@cosmicdrift/kumiko-framework": "^0.8.0",
+            "@cosmicdrift/kumiko-bundled-features": "^0.8.0",
+          },
+        }),
+      );
+      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("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);
+    });
+  });
+});

package/src/codegen/__tests__/watch.test.ts

@@ -52,7 +52,10 @@ async function waitFor(
   predicate: () => boolean,
   opts: { timeout?: number; interval?: number; label?: string } = {},
 ): Promise<void> {
-  const timeout = opts.timeout ?? 2000;
+  // Default 5000ms — fchokidar-FS-watch events take >2s under CI load on
+  // the cdgs-runner (Memory feedback_watch_test_flaky, observed 3× in
+  // a row on PR #80). 5s gives headroom without slowing the happy-path.
+  const timeout = opts.timeout ?? 5000;
   const interval = opts.interval ?? 25;
   const deadline = Date.now() + timeout;
   while (!predicate()) {
@@ -122,7 +125,7 @@ export default defineFeature("orders", (r) => {
     // polling adapts to the actual schedule instead of guessing a fixed
     // sleep.
     await waitFor(() => results.length >= 2, {
-      timeout: 2000,
+      timeout: 5000,
       label: "second codegen result",
     });
 
@@ -174,7 +177,7 @@ export default defineFeature("orders", (r) => {
     // soon as the new result lands, confirming the watcher is alive.
     writeFile(appRoot, "src/feature.ts", FEATURE_TEMPLATE("ignore-css", "after"));
     await waitFor(() => results.length > afterNonTs, {
-      timeout: 2000,
+      timeout: 5000,
       label: "ts-change result after non-ts noise",
     });
 

package/src/index.ts

@@ -54,5 +54,11 @@ export type {
   SignupSetup,
 } from "./run-prod-app";
 export { runProdApp } from "./run-prod-app";
+export type {
+  ScaffoldDeployOptions,
+  ScaffoldDeployResult,
+  ScaffoldedFile,
+} from "./scaffold-deploy";
+export { scaffoldDeploy } from "./scaffold-deploy";
 export type { ScaffoldFeatureOptions, ScaffoldFeatureResult } from "./scaffold-feature";
 export { scaffoldFeature } from "./scaffold-feature";

package/src/scaffold-deploy.ts

@@ -0,0 +1,186 @@
+// `kumiko init-deploy` scaffolding helper.
+//
+// Generates `deploy/Dockerfile`, `deploy/Dockerfile.dockerignore`, and
+// `deploy/migrate-step.sh` in the target app from canonical templates
+// shipped with @cosmicdrift/kumiko-dev-server. Substitutes `{{appName}}`,
+// `{{port}}`, `{{githubOrg}}` placeholders. Refuses to overwrite existing
+// files unless `force: true` — keeps an app's already-tuned Dockerfile
+// from being clobbered.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ScaffoldDeployOptions = {
+  /** App name, kebab-case (e.g. "publicstatus", "kumiko-studio"). */
+  readonly appName: string;
+  /** Container port the app listens on. Default 3000. */
+  readonly port?: number;
+  /** GitHub org for the published image-tag. Default "cosmicdriftgamestudio". */
+  readonly githubOrg?: string;
+  /** Destination directory (absolute or relative to cwd). The `deploy/`
+   *  subdir is created inside this. Default: process.cwd(). */
+  readonly destination?: string;
+  /** Source-tree root for optional-dir detection (seeds/, …). Defaults to
+   *  `destination`. Lets the caller scaffold into one dir while detecting
+   *  optional surfaces in another (rare — mostly destination = sourceDir). */
+  readonly sourceDir?: string;
+  /** Overwrite existing files instead of skipping them. */
+  readonly force?: boolean;
+};
+
+/** Detected optional-dirs in the app's source-tree. Drives which COPY
+ *  blocks the Dockerfile-template emits. */
+export type ScaffoldDeployDetected = {
+  /** ES-Operations seed-migrations (`seeds/`). Required for apps that
+   *  use the es-ops feature. */
+  readonly hasSeeds: boolean;
+  /** Private @cosmicdriftgamestudio/* GH-Packages → Dockerfile needs to
+   *  pass GITHUB_TOKEN as build-arg + re-export inside the build-stage. */
+  readonly hasPrivateGhPackages: boolean;
+};
+
+export type ScaffoldedFile = {
+  readonly path: string;
+  readonly written: boolean;
+  readonly reason?: "exists" | "force";
+};
+
+export type ScaffoldDeployResult = {
+  readonly destination: string;
+  readonly files: readonly ScaffoldedFile[];
+  /** What scaffoldDeploy detected in the source-tree and used to gate
+   *  conditional Dockerfile blocks. Surfaced so the CLI can report it
+   *  ("hasSeeds=true → /app/seeds COPY emitted"). */
+  readonly detected: ScaffoldDeployDetected;
+};
+
+const TEMPLATE_FILES = [
+  { template: "Dockerfile.template", output: "Dockerfile" },
+  {
+    template: "Dockerfile.dockerignore.template",
+    output: "Dockerfile.dockerignore",
+  },
+  { template: "migrate-step.sh.template", output: "migrate-step.sh" },
+] as const;
+
+const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+
+export function scaffoldDeploy(options: ScaffoldDeployOptions): ScaffoldDeployResult {
+  if (!KEBAB_RE.test(options.appName)) {
+    throw new Error(
+      `scaffoldDeploy: appName must be kebab-case (a-z, 0-9, -); got "${options.appName}"`,
+    );
+  }
+  const port = options.port ?? 3000;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`scaffoldDeploy: port must be 1..65535, got ${port}`);
+  }
+  const githubOrg = options.githubOrg ?? "cosmicdriftgamestudio";
+  const destinationRoot = options.destination ?? process.cwd();
+  const deployDir = join(destinationRoot, "deploy");
+  mkdirSync(deployDir, { recursive: true });
+
+  const templatesDir = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "deploy");
+
+  // Detect optional surfaces in the source-tree so the Dockerfile only
+  // emits COPYs for dirs that actually exist. Without this, apps without
+  // a `seeds/` directory (e.g. studio) crash in Docker-build with
+  // `failed to compute cache key: "/app/seeds": not found`.
+  //
+  // `hasPrivateGhPackages`: scan package.json for any
+  // `@cosmicdriftgamestudio/*` dep — those need GITHUB_TOKEN as a build-
+  // arg passed through into the build-stage (multi-stage ARG inheritance
+  // requires re-declaration inside the stage).
+  const sourceDir = options.sourceDir ?? destinationRoot;
+  const detected = detectOptionalSurfaces(sourceDir);
+
+  const subs: Readonly<Record<string, string>> = {
+    appName: options.appName,
+    port: String(port),
+    githubOrg,
+  };
+
+  const flags: Readonly<Record<string, boolean>> = {
+    hasSeeds: detected.hasSeeds,
+    hasPrivateGhPackages: detected.hasPrivateGhPackages,
+  };
+
+  const files: ScaffoldedFile[] = [];
+  for (const { template, output } of TEMPLATE_FILES) {
+    const outputPath = join(deployDir, output);
+    const preExisted = existsSync(outputPath);
+    if (preExisted && !options.force) {
+      files.push({ path: outputPath, written: false, reason: "exists" });
+      continue;
+    }
+    const rendered = render(readFileSync(join(templatesDir, template), "utf-8"), subs, flags);
+    writeFileSync(outputPath, rendered);
+    // `reason: "force"` only when we actually clobbered a pre-existing
+    // file — distinct from a clean first-time write. The existsSync above
+    // is captured BEFORE the write so the flag reflects pre-state.
+    files.push({
+      path: outputPath,
+      written: true,
+      ...(preExisted && options.force ? { reason: "force" as const } : {}),
+    });
+  }
+
+  return { destination: deployDir, files, detected };
+}
+
+function detectOptionalSurfaces(sourceDir: string): ScaffoldDeployDetected {
+  const hasSeeds = existsSync(join(sourceDir, "seeds"));
+  let hasPrivateGhPackages = false;
+  const pkgJsonPath = join(sourceDir, "package.json");
+  if (existsSync(pkgJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8")) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      hasPrivateGhPackages = Object.keys(allDeps).some((d) =>
+        d.startsWith("@cosmicdriftgamestudio/"),
+      );
+    } catch {
+      // malformed package.json — assume no private packages, app-author can override via Dockerfile
+    }
+  }
+  return { hasSeeds, hasPrivateGhPackages };
+}
+
+function render(
+  source: string,
+  subs: Readonly<Record<string, string>>,
+  flags: Readonly<Record<string, boolean>>,
+): string {
+  // Step 1: handle mustache-style block conditionals `{{#flag}}...{{/flag}}`
+  // (multiline-aware via [\s\S]). When flag is truthy → keep inner content;
+  // when falsy → strip the entire block (including the surrounding line so
+  // we don't leave blank lines in the rendered Dockerfile).
+  let result = source.replace(
+    /^[ \t]*\{\{#([a-z][a-zA-Z0-9]*)\}\}\n([\s\S]*?)\n[ \t]*\{\{\/\1\}\}[ \t]*\n?/gm,
+    (_full, key: string, inner: string) => {
+      const flag = flags[key];
+      if (flag === undefined) {
+        throw new Error(`scaffoldDeploy.render: unknown block-flag "{{#${key}}}"`);
+      }
+      return flag ? `${inner}\n` : "";
+    },
+  );
+
+  // Step 2: handle plain `{{key}}` substitutions. Pattern is intentionally
+  // narrow: lowercase-leading identifier followed by alphanumerics. That
+  // excludes Docker/Go template syntax like `{{.Name}}` (leading `.`)
+  // which appears verbatim in the migrate-step.sh shell snippet.
+  result = result.replace(/\{\{([a-z][a-zA-Z0-9]*)\}\}/g, (full, key: string) => {
+    const value = subs[key];
+    if (value === undefined) {
+      throw new Error(`scaffoldDeploy.render: unknown placeholder "${full}"`);
+    }
+    return value;
+  });
+
+  return result;
+}

package/templates/deploy/Dockerfile.dockerignore.template

@@ -0,0 +1,42 @@
+# Per-Dockerfile .dockerignore — Buildkit reads this when the
+# Dockerfile lives next to it (`deploy/Dockerfile` + `deploy/Dockerfile.dockerignore`).
+#
+# Keeps the build context lean: source-only excludes (tests, env files,
+# VCS metadata) plus the workspace-internal artefacts that the build
+# stage regenerates from scratch.
+
+# VCS + editor
+.git
+.github
+.gitignore
+.vscode
+.idea
+
+# Local env + secrets — must NEVER leak into a layer
+.env
+.env.local
+.env.*.local
+**/.env
+*.pem
+*.key
+
+# Tests + coverage (not in production image)
+**/__tests__
+**/*.test.ts
+**/*.integration.ts
+coverage
+**/*.tsbuildinfo
+
+# Docs (not in image)
+docs
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+
+# Workspace-internal — `dist/` is build output; runtime stage copies
+# fresh dist/ from the build stage. Local dist/ (from a dev build)
+# stays out.
+node_modules
+.yarn
+**/node_modules
+**/dist

package/templates/deploy/Dockerfile.template

@@ -0,0 +1,130 @@
+# syntax=docker/dockerfile:1.7
+#
+# Production-Image for {{appName}}.
+#
+# Server-Bundle variant — the runtime image doesn't know about the
+# monorepo any more, only:
+#
+#   dist/                  ← Client build (kumiko-build)
+#   dist-server/           ← Server bundle (bun build) + minimal package.json
+#   drizzle/               ← Migrations
+#   drizzle.config.ts      ← drizzle-kit config (for `bunx drizzle-kit migrate`)
+#
+# Size: ~250 MB incl. drizzle-kit for the pre-deploy migrate step.
+# Build context: repository root (monorepo is used in the build stage).
+
+ARG BUN_VERSION=1.2.20
+# Build identity — passed in by the CI workflow via --build-arg. Defaults
+# for local container builds.
+ARG BUILD_VERSION=dev
+ARG BUILD_TIME=unknown
+{{#hasPrivateGhPackages}}
+# Private @cosmicdriftgamestudio/* GH-Packages dep detected — yarn-4
+# reads the token via `npmAuthToken: "${GITHUB_TOKEN:-…}"` in .yarnrc.yml.
+# Without this build-arg, yarn install aborts with YN0041 anonymous-auth.
+ARG GITHUB_TOKEN=
+{{/hasPrivateGhPackages}}
+
+# ----- build: produces dist/ + dist-server/ ---------------------------------
+# Build base is node-alpine (not bun-alpine) because the repo uses yarn 4 as
+# its package manager — `link:./.kumiko` (@app/define codegen output) is
+# yarn-4's symlink protocol, which bun interprets differently. Node ships
+# corepack (yarn 4 via packageManager field); we pull bun via npm for
+# `bun run build`. Runtime stage stays pure bun.
+FROM node:20-alpine AS build
+{{#hasPrivateGhPackages}}
+# Multi-stage ARG inheritance: globals declared before FROM need an
+# `ARG <name>` line in every stage that uses them. Without this,
+# ${GITHUB_TOKEN} below resolves to empty and yarn install hits YN0041.
+ARG GITHUB_TOKEN
+{{/hasPrivateGhPackages}}
+WORKDIR /app
+
+RUN corepack enable && npm install -g bun@${BUN_VERSION}
+
+# Standalone-repo layout: @cosmicdrift/* pulled from NPM, no workspace:*
+# refs. Manifests first for Docker layer cache (yarn install only
+# invalidates on dep change).
+COPY package.json yarn.lock .yarnrc.yml ./
+
+# YARN_ENABLE_INLINE_BUILDS=true: postinstall stdout/stderr inline in the
+# install output. Without this, yarn 4 hides logs in /tmp/xfs-*/build.log
+# (invisible in the Docker layer output) and the CI operator guesses why
+# the install failed.
+#
+# `link:./.kumiko` (@app/define in package.json): yarn 4 creates a
+# dangling symlink; install does NOT fail. `bun run build` below calls
+# `runCodegen` from @cosmicdrift/kumiko-dev-server (see
+# bin/kumiko-build.ts), which writes .kumiko/define.ts and turns the
+# symlink real before the bundle is built.
+ENV YARN_ENABLE_INLINE_BUILDS=true
+{{#hasPrivateGhPackages}}
+# Re-export GITHUB_TOKEN as env so yarn-4's `${GITHUB_TOKEN:-…}` expansion
+# in .yarnrc.yml finds it during the install step.
+ENV GITHUB_TOKEN=${GITHUB_TOKEN}
+{{/hasPrivateGhPackages}}
+RUN yarn install --immutable
+
+COPY . .
+RUN bun run build
+
+# ----- runtime: bun-alpine, knows only the bundle artefact ------------------
+FROM oven/bun:${BUN_VERSION}-alpine AS runtime
+WORKDIR /app
+
+RUN addgroup -S app && adduser -S app -G app
+
+# Server bundle + its minimal package.json. `bun install --production`
+# only pulls the actual externals.
+COPY --from=build --chown=app:app /app/dist-server ./
+RUN bun install --production
+
+# Client build (static assets) — served by runProdApp.staticDir.
+COPY --from=build --chown=app:app /app/dist ./dist
+
+# Drizzle artefacts for migrate apply: drizzle-kit reads drizzle.config.ts
+# (bundled — inlined kumikoDrizzleConfig, no dev-server pkg needed) and
+# applies the SQL migrations from drizzle/migrations/. schema.ts is NOT
+# loaded (apply is SQL-only; generate reads schema).
+COPY --from=build --chown=app:app /app/dist-server/drizzle.config.ts ./drizzle.config.ts
+COPY --from=build --chown=app:app /app/drizzle ./drizzle
+
+{{#hasSeeds}}
+# ES-Operations seed migrations — runtime-loaded via dynamic import. Bun
+# does NOT bundle these into dist-server/server.js (await import on a
+# dynamic path), so the seeds/ tree is copied raw. Bun's runtime
+# transpiles the TS files on the fly.
+#
+# This block is emitted because scaffoldDeploy detected a `seeds/`
+# directory at the source root. Apps without it skip the block entirely.
+COPY --from=build --chown=app:app /app/seeds ./seeds
+{{/hasSeeds}}
+
+USER app
+
+ENV NODE_ENV=production
+ENV PORT={{port}}
+# kumiko.ts migrate path resolves drizzle-kit relative to KUMIKO_REPO_ROOT
+# (default is parent-of-import.meta.dir, which in a bundle points to the
+# wrong directory). /app is the app root + node_modules parent here.
+ENV KUMIKO_REPO_ROOT=/app
+# kumiko.ts expects INIT_CWD as the app workspace (drizzle.config.ts +
+# drizzle/ live per app). In the bundle container, /app is that workspace.
+ENV INIT_CWD=/app
+# kumiko.ts would otherwise load drizzle/migration-hooks.ts as an
+# unbundled .ts — that fails because dev-server and framework imports
+# can't be resolved from the runtime node_modules. Override to the
+# bundled equivalent in /app/migration-hooks.js.
+ENV KUMIKO_MIGRATION_HOOKS=/app/migration-hooks.js
+# Build identity in the runtime env so /api/version returns it.
+# Built: SHA of the commit at image build time + ISO timestamp.
+ENV BUILD_VERSION=$BUILD_VERSION
+ENV BUILD_TIME=$BUILD_TIME
+
+EXPOSE {{port}}
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD wget --quiet --spider "http://127.0.0.1:${PORT}/health" || exit 1
+
+# exec → bun is PID 1 → SIGTERM reaches it directly → graceful shutdown.
+CMD ["sh", "-c", "exec bun run server.js"]

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# {{appName}} pre-deploy migrate step.
+#
+# Called by the deploy workflow between `compose up -d db redis` and
+# `compose up -d app` via SSH (see `.github/workflows/deploy.yml` or
+# equivalent). Lives on the server under `/srv/{{appName}}/migrate-step.sh`,
+# called via `bash migrate-step.sh`.
+#
+# Task: apply drizzle-kit migrations + auto-rebuild for projection-schema
+# changes BEFORE the app container starts — runProdApp's boot gate would
+# otherwise abort with SchemaDriftError.
+#
+# Network discovery: the _stack network is named `<dirname>_stack`
+# (compose convention). We discover it via `docker network ls` instead
+# of hard-coding.
+
+set -euo pipefail
+
+STACK_NETWORK=$(docker network ls --format "{{.Name}}" | grep -E "_stack$" | head -1)
+if [ -z "$STACK_NETWORK" ]; then
+  echo "No _stack network found — compose project not running?" >&2
+  exit 1
+fi
+
+# Import .env as bash env. `set -a` marks subsequent variable assignments
+# as auto-export. Bash's built-in parser respects quotes/escapes like
+# compose does, without depending on compose-profile features.
+set -a
+. ./.env
+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.
+docker run --rm \
+  --network "$STACK_NETWORK" \
+  -e DATABASE_URL="postgresql://{{appName}}:${DB_PASSWORD}@db:5432/{{appName}}" \
+  ghcr.io/{{githubOrg}}/{{appName}}:latest \
+  bun /app/kumiko.js migrate apply