@cosmicdrift/kumiko-dev-server 0.322.0 → 0.324.0

package/src/init-deploy-cli.ts

@@ -0,0 +1,148 @@
+// `kumiko-init-deploy` CLI — the shared implementation behind both the
+// standalone `kumiko-init-deploy` bin (published, app-facing) and the
+// monorepo's `bin/commands/init-deploy.ts` (delegates here, no duplicated
+// logic).
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import {
+  getFlag,
+  getNumberFlag,
+  getStringFlag,
+  parseArgs,
+} from "@cosmicdrift/kumiko-framework/arg-parser";
+import * as z from "zod";
+import { checkDeployDrift, type ScaffoldedFile, scaffoldDeploy } from "./scaffold-deploy";
+
+export type CliOutput = {
+  readonly log: (msg: string) => void;
+  readonly err: (msg: string) => void;
+};
+
+export type RunInitDeployCliOptions = {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly out: CliOutput;
+};
+
+const USAGE =
+  "Usage: kumiko-init-deploy --app <name> [--port <n>] [--github-org <org>] [--out <dir>] [--force | --check]";
+
+const packageNameSchema = z.object({ name: z.string().optional() });
+
+/** package.json `name` without its `@scope/` prefix, if present and valid. */
+function defaultAppName(cwd: string): string | undefined {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return undefined;
+  try {
+    const pkg = packageNameSchema.parse(JSON.parse(readFileSync(pkgPath, "utf-8")));
+    if (!pkg.name) return undefined;
+    const slash = pkg.name.indexOf("/");
+    return pkg.name.startsWith("@") && slash !== -1 ? pkg.name.slice(slash + 1) : pkg.name;
+  } catch {
+    return undefined;
+  }
+}
+
+type DeployTarget = {
+  readonly appName: string;
+  readonly port: number | undefined;
+  readonly githubOrg: string | undefined;
+  readonly destination: string;
+};
+
+function targetOptions({ appName, port, githubOrg, destination }: DeployTarget) {
+  return {
+    appName,
+    ...(port !== undefined && { port }),
+    ...(githubOrg !== undefined && { githubOrg }),
+    destination,
+  };
+}
+
+function reportDrift(target: DeployTarget, out: CliOutput): number {
+  const result = checkDeployDrift(targetOptions(target));
+  if (result.drifted.length === 0) {
+    out.log("  ✓ deploy/ is in sync with the current templates.");
+    return 0;
+  }
+  out.err("");
+  out.err(`  ✗ ${result.drifted.length} drifted file(s):`);
+  for (const d of result.drifted) {
+    out.err(`    ${relative(target.destination, d.path)} — ${d.reason}`);
+  }
+  out.err("");
+  out.err("  run kumiko-init-deploy --force to regenerate.");
+  out.err("");
+  return 1;
+}
+
+function fileMarker(file: ScaffoldedFile): string {
+  if (!file.written) return "SKIPPED    ";
+  return file.reason === "force" ? "OVERWRITTEN" : "WRITTEN    ";
+}
+
+function reportScaffold(target: DeployTarget, force: boolean, out: CliOutput): number {
+  const result = scaffoldDeploy({ ...targetOptions(target), force });
+  out.log("");
+  out.log(`  ✓ Deploy scaffolding generated — ${target.appName}`);
+  for (const f of result.files) {
+    out.log(`    ${fileMarker(f)} ${relative(target.destination, f.path)}`);
+  }
+  if (result.files.some((f) => !f.written)) {
+    out.log("");
+    out.log(
+      "  Some files were skipped because they already exist. Re-run with --force to overwrite.",
+    );
+  }
+  out.log("");
+  out.log("  Next steps:");
+  out.log("    1. Review deploy/Dockerfile — adjust if your app needs extra COPY/ENV steps.");
+  out.log("    2. Wire your image-build workflow to build deploy/Dockerfile and push it.");
+  out.log("    3. Configure the runtime env-vars for your platform.");
+  out.log("");
+  return 0;
+}
+
+export async function runInitDeployCli({
+  argv,
+  cwd,
+  out,
+}: RunInitDeployCliOptions): Promise<number> {
+  const args = parseArgs(argv);
+  const force = getFlag(args, "force");
+  const check = getFlag(args, "check");
+  if (force && check) {
+    out.err("");
+    out.err("  --check and --force are mutually exclusive.");
+    out.err(`  ${USAGE}`);
+    out.err("");
+    return 2;
+  }
+
+  const appName = getStringFlag(args, "app") ?? defaultAppName(cwd);
+  if (!appName) {
+    out.err("");
+    out.err('  --app <name> is required (no package.json "name" found to default from).');
+    out.err(`  ${USAGE}`);
+    out.err("");
+    return 1;
+  }
+
+  const target: DeployTarget = {
+    appName,
+    port: getNumberFlag(args, "port"),
+    githubOrg: getStringFlag(args, "github-org"),
+    destination: getStringFlag(args, "out") ?? cwd,
+  };
+
+  try {
+    return check ? reportDrift(target, out) : reportScaffold(target, force, out);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    out.err("");
+    out.err(`  ${msg}`);
+    out.err("");
+    return 1;
+  }
+}

package/src/run-dev-app.ts

@@ -12,7 +12,11 @@
 // alternativer Membership-Query, eigener LoginRateLimiter): geht direkt
 // auf `createKumikoServer` aus @cosmicdrift/kumiko-dev-server.
 
-import { AuthErrors, AuthHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import {
+  AuthErrors,
+  AuthHandlers,
+  AuthQueries,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
 import {
   type SeedAdminOptions,
   seedAdminGuarded,
@@ -187,17 +191,16 @@ export type RunDevAppOptions = {
   readonly features: readonly FeatureDefinition[];
   /** Opt-in boot-validator warnings — see ValidateBootOptions. */
   readonly validateBootOptions?: ValidateBootOptions;
-  /** Pfad zum Browser-Entry-Modul. Bun.build bündelt es zu /client.js.
-   *  Mutually exclusive mit `clientEntries`. */
+  /** Browser entry module, bundled to /client.js. Mutually exclusive with
+   *  `clientEntries`. */
   readonly clientEntry?: string;
-  /** Multi-Entry-Mode: pro Entry ein eigenes Bundle (`/client-<name>.js`)
-   *  + ein eigenes HTML-Template. `hostDispatch` wählt zur Request-Zeit
-   *  welcher Entry kommt. Symmetric zur kumiko-build-Convention
-   *  `src/client-<name>.tsx`. Mutually exclusive mit `clientEntry`. */
+  /** Multi-entry mode: one bundle (`/client-<name>.js`) and one HTML template
+   *  per entry; `hostDispatch` picks the entry per request. kumiko-build reads
+   *  the same list from package.json `kumiko.clientEntries`. Mutually exclusive
+   *  with `clientEntry`. */
   readonly clientEntries?: CreateKumikoServerOptions["clientEntries"];
-  /** Multi-Entry-Mode: Routing per Request. Wird für Multi-Entry mit
-   *  geforderten — sonst weiß der Server nicht welche HTML er liefern
-   *  soll. */
+  /** Multi-entry mode: per-request routing. Required with `clientEntries`,
+   *  otherwise the server cannot tell which HTML to serve. */
   readonly hostDispatch?: CreateKumikoServerOptions["hostDispatch"];
   /** Per-request head-metadata resolver — same option, same signature as
    *  `runProdApp`'s `resolvePageHead`, so `bun dev` and every e2e that boots
@@ -578,6 +581,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
             acceptHandler: AuthHandlers.inviteAccept,
             acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
             signupCompleteHandler: AuthHandlers.inviteSignupComplete,
+            infoHandler: AuthQueries.inviteInfo,
           },
         }),
       },

package/src/scaffold-app-feature.ts

@@ -162,7 +162,12 @@ import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/eng
 
 export const ${camel}ItemEntity = createEntity({
   fields: {
-    title: createTextField({ required: true, sortable: true }),
+    title: createTextField({
+      required: true,
+      sortable: true,
+      personal: false,
+      reason: "is_business_data",
+    }),
   },
 });
 `;

package/src/scaffold-deploy.ts

@@ -3,16 +3,21 @@
 // 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.
+// `{{port}}`, `{{githubOrg}}`, `{{installManifests}}` placeholders and the
+// `hasSeeds`/`hasPrivateGhPackages`/`installFromFullTree`/
+// `installFromManifests` block flags detected from the app's source-tree.
+// `renderDeployFiles` is the pure computation (no writes); `scaffoldDeploy`
+// writes it to disk (refuses to overwrite existing files unless
+// `force: true`); `checkDeployDrift` compares it against what's on disk
+// without writing.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import * as z from "zod";
 import { isKebabSegment } from "./kebab";
 
-export type ScaffoldDeployOptions = {
+export type RenderDeployFilesOptions = {
   /** App name, kebab-case (e.g. "publicstatus", "kumiko-studio"). */
   readonly appName: string;
   /** Container port the app listens on. Default 3000. */
@@ -26,19 +31,43 @@ export type ScaffoldDeployOptions = {
    *  `destination`. Lets the caller scaffold into one dir while detecting
    *  optional surfaces in another (rare — mostly destination = sourceDir). */
   readonly sourceDir?: string;
+};
+
+export type ScaffoldDeployOptions = RenderDeployFilesOptions & {
   /** 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. */
+const REGISTRY_CONFIG_FILES = ["bunfig.toml", ".npmrc"] as const;
+export type RegistryConfigFile = (typeof REGISTRY_CONFIG_FILES)[number];
+
+/** Detected optional-dirs/layout traits 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. */
+   *  pass NPM_AUTH_TOKEN as build-arg + re-export it as $GITHUB_TOKEN inside
+   *  the build-stage (bunfig.toml/.npmrc read $GITHUB_TOKEN). */
   readonly hasPrivateGhPackages: boolean;
+  /** A `workspaces` root, or a `file:`/`workspace:`/`link:` dependency spec
+   *  — bun needs the whole build context on disk to resolve the lockfile,
+   *  so the Dockerfile does `COPY . .` before `bun install` instead of
+   *  copying manifests first for layer-cache. */
+  readonly installFromFullTree: boolean;
+  /** Which of bunfig.toml/.npmrc exist at the source root — copied ahead of
+   *  `bun install` in the manifests-first install variant. */
+  readonly registryConfigFiles: readonly RegistryConfigFile[];
+  /** DB user for migrate-step.sh's DATABASE_URL — from
+   *  `package.json#kumiko.deploy.dbUser`, default = appName. The db name
+   *  always stays appName regardless of this value. */
+  readonly dbUser: string;
+  /** How migrate-step.sh locates the compose `_stack` network — from
+   *  `package.json#kumiko.deploy.stackNetwork`. "discover" (default):
+   *  today's `docker network ls` heuristic. "directory": the exact name
+   *  `$(basename "$PWD")_stack`, checked via `docker network inspect`. */
+  readonly stackNetwork: "discover" | "directory";
 };
 
 export type ScaffoldedFile = {
@@ -56,6 +85,30 @@ export type ScaffoldDeployResult = {
   readonly detected: ScaffoldDeployDetected;
 };
 
+export type RenderedDeployFile = {
+  /** Template-relative output filename (e.g. "Dockerfile"). */
+  readonly output: string;
+  /** Absolute path this would be written to. */
+  readonly path: string;
+  readonly content: string;
+};
+
+export type RenderDeployFilesResult = {
+  readonly deployDir: string;
+  readonly files: readonly RenderedDeployFile[];
+  readonly detected: ScaffoldDeployDetected;
+};
+
+export type DeployDriftEntry = {
+  readonly path: string;
+  readonly reason: "missing" | "differs";
+};
+
+export type CheckDeployDriftResult = {
+  readonly drifted: readonly DeployDriftEntry[];
+  readonly detected: ScaffoldDeployDetected;
+};
+
 const TEMPLATE_FILES = [
   { template: "Dockerfile.template", output: "Dockerfile" },
   {
@@ -65,61 +118,81 @@ const TEMPLATE_FILES = [
   { template: "migrate-step.sh.template", output: "migrate-step.sh" },
 ] as const;
 
-export function scaffoldDeploy(options: ScaffoldDeployOptions): ScaffoldDeployResult {
+function templatesDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "deploy");
+}
+
+/** Pure: computes the rendered deploy files for `options` without touching
+ *  disk beyond reading the app's source-tree (package.json, seeds/,
+ *  registry-config files) and the shipped templates. */
+export function renderDeployFiles(options: RenderDeployFilesOptions): RenderDeployFilesResult {
   if (!isKebabSegment(options.appName)) {
     throw new Error(
-      `scaffoldDeploy: appName must be kebab-case (a-z, 0-9, -); got "${options.appName}"`,
+      `renderDeployFiles: 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}`);
+    throw new Error(`renderDeployFiles: 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 detected = detectOptionalSurfaces(sourceDir, options.appName);
+
+  const installManifests = ["package.json", "bun.lock", ...detected.registryConfigFiles].join(" ");
 
   const subs: Readonly<Record<string, string>> = {
     appName: options.appName,
     port: String(port),
     githubOrg,
+    installManifests,
+    dbUser: detected.dbUser,
   };
 
   const flags: Readonly<Record<string, boolean>> = {
     hasSeeds: detected.hasSeeds,
     hasPrivateGhPackages: detected.hasPrivateGhPackages,
+    installFromFullTree: detected.installFromFullTree,
+    installFromManifests: !detected.installFromFullTree,
+    stackNetworkDiscover: detected.stackNetwork === "discover",
+    stackNetworkDirectory: detected.stackNetwork === "directory",
+    customDbUser: detected.dbUser !== options.appName,
   };
 
+  const dir = templatesDir();
+  const files: RenderedDeployFile[] = TEMPLATE_FILES.map(({ template, output }) => ({
+    output,
+    path: join(deployDir, output),
+    content: render(readFileSync(join(dir, template), "utf-8"), subs, flags),
+  }));
+
+  return { deployDir, files, detected };
+}
+
+export function scaffoldDeploy(options: ScaffoldDeployOptions): ScaffoldDeployResult {
+  const { deployDir, files: rendered, detected } = renderDeployFiles(options);
+  mkdirSync(deployDir, { recursive: true });
+
   const files: ScaffoldedFile[] = [];
-  for (const { template, output } of TEMPLATE_FILES) {
-    const outputPath = join(deployDir, output);
-    const preExisted = existsSync(outputPath);
+  for (const { path, content } of rendered) {
+    const preExisted = existsSync(path);
     if (preExisted && !options.force) {
-      files.push({ path: outputPath, written: false, reason: "exists" });
+      files.push({ path, written: false, reason: "exists" });
       continue;
     }
-    const rendered = render(readFileSync(join(templatesDir, template), "utf-8"), subs, flags);
-    writeFileSync(outputPath, rendered);
+    writeFileSync(path, content);
     // `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,
+      path,
       written: true,
       ...(preExisted && options.force ? { reason: "force" as const } : {}),
     });
@@ -128,31 +201,146 @@ export function scaffoldDeploy(options: ScaffoldDeployOptions): ScaffoldDeployRe
   return { destination: deployDir, files, detected };
 }
 
-function detectOptionalSurfaces(sourceDir: string): ScaffoldDeployDetected {
+/** Read-only: compares the rendered deploy files against what's on disk
+ *  without writing anything. */
+export function checkDeployDrift(options: RenderDeployFilesOptions): CheckDeployDriftResult {
+  const { files: rendered, detected } = renderDeployFiles(options);
+  const drifted: DeployDriftEntry[] = [];
+  for (const { path, content } of rendered) {
+    if (!existsSync(path)) {
+      drifted.push({ path, reason: "missing" });
+      continue;
+    }
+    if (readFileSync(path, "utf-8") !== content) {
+      drifted.push({ path, reason: "differs" });
+    }
+  }
+  return { drifted, detected };
+}
+
+const packageJsonSchema = z.object({
+  dependencies: z.record(z.string(), z.string()).optional(),
+  devDependencies: z.record(z.string(), z.string()).optional(),
+  workspaces: z
+    .union([z.array(z.string()), z.object({ packages: z.array(z.string()).optional() })])
+    .optional(),
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Reads `raw.kumiko.deploy` without going through `packageJsonSchema` — an
+ *  unrelated shape problem elsewhere in package.json (e.g. a malformed
+ *  `dependencies`) must not silently drop a valid deploy config; only
+ *  actually-malformed JSON (JSON.parse throwing) should fall back. */
+function extractDeployConfigRaw(raw: unknown): unknown {
+  if (!isRecord(raw)) return undefined;
+  const kumiko = raw["kumiko"];
+  if (!isRecord(kumiko)) return undefined;
+  return kumiko["deploy"];
+}
+
+const LOCAL_DEP_SPEC_RE = /^(file:|workspace:|link:)/;
+
+// The user part of DATABASE_URL — deliberately stricter than a full Postgres
+// role-name grammar (no quoting support) since it is interpolated into a
+// shell string, not passed through a driver's escaping.
+const DB_USER_RE = /^[a-zA-Z0-9_][a-zA-Z0-9_-]{0,62}$/;
+
+const kumikoDeployConfigSchema = z
+  .object({
+    dbUser: z.string().regex(DB_USER_RE).optional(),
+    stackNetwork: z.enum(["discover", "directory"]).optional(),
+  })
+  .strict();
+
+type KumikoDeployConfig = z.infer<typeof kumikoDeployConfigSchema>;
+
+/** `package.json#kumiko.deploy` must be well-formed — silently falling back
+ *  to defaults on an invalid `dbUser`/`stackNetwork` would render a migrate
+ *  step that talks to the wrong DB user or the wrong stack network, breaking
+ *  prod migrations without anyone noticing. Unlike detectOptionalSurfaces'
+ *  malformed-JSON fallback, this throws (fail loud) and names the field. */
+function parseDeployConfig(raw: unknown): KumikoDeployConfig {
+  if (raw === undefined) return {};
+  const result = kumikoDeployConfigSchema.safeParse(raw);
+  if (result.success) return result.data;
+  const issue = result.error.issues[0];
+  const location =
+    issue === undefined
+      ? "kumiko.deploy"
+      : issue.code === "unrecognized_keys"
+        ? ["kumiko", "deploy", ...issue.keys].join(".")
+        : ["kumiko", "deploy", ...issue.path.map(String)].join(".");
+  throw new Error(
+    `scaffoldDeploy: invalid package.json#${location} — ${issue?.message ?? "validation failed"}`,
+  );
+}
+
+function resolveDeployConfig(
+  deployConfigRaw: unknown,
+  appName: string,
+): Pick<ScaffoldDeployDetected, "dbUser" | "stackNetwork"> {
+  const config = parseDeployConfig(deployConfigRaw);
+  const dbUser = config.dbUser ?? appName;
+  // The default (appName) already passed isKebabSegment's charset check but
+  // not DB_USER_RE's length cap — validate the effective value so an
+  // over-long appName fails loud here instead of producing a DB user
+  // Postgres itself would reject at migrate-time.
+  if (!DB_USER_RE.test(dbUser)) {
+    throw new Error(
+      `scaffoldDeploy: invalid package.json#kumiko.deploy.dbUser — effective value "${dbUser}" (defaulted from appName) does not match ${DB_USER_RE}`,
+    );
+  }
+  return { dbUser, stackNetwork: config.stackNetwork ?? "discover" };
+}
+
+function detectOptionalSurfaces(sourceDir: string, appName: string): ScaffoldDeployDetected {
   const hasSeeds = existsSync(join(sourceDir, "seeds"));
   let hasPrivateGhPackages = false;
+  let installFromFullTree = false;
+  let deployConfigRaw: unknown;
   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 raw: unknown = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+      // Read ahead of packageJsonSchema.parse: an unrelated shape problem in
+      // `dependencies`/`workspaces` must not silently discard a valid deploy
+      // config along with it (that's caught by the outer catch below).
+      deployConfigRaw = extractDeployConfigRaw(raw);
+      const pkg = packageJsonSchema.parse(raw);
       const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
       hasPrivateGhPackages = Object.keys(allDeps).some((d) =>
         d.startsWith("@cosmicdriftgamestudio/"),
       );
+      installFromFullTree =
+        pkg.workspaces !== undefined ||
+        Object.values(allDeps).some((v) => LOCAL_DEP_SPEC_RE.test(v));
     } 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.
+      // malformed JSON (or unexpected dependencies/workspaces shape) —
+      // assume no private packages and a plain manifests-first install;
+      // app-author can override via Dockerfile. Warn so a silent
+      // mis-detection (later YN0041 on yarn install, or a broken lockfile
+      // resolve) is traceable to the scaffold step. If JSON.parse itself
+      // failed, deployConfigRaw also stays undefined → deploy params fall
+      // back to defaults (an invalid deploy config must THROW, but
+      // unreadable JSON can't distinguish "no deploy config" from "invalid
+      // deploy config" — it already surfaces via this warning).
       // 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)})`,
+        `scaffoldDeploy: package.json at ${pkgJsonPath} is not valid JSON — private-GH-packages/install-layout detection skipped (${err instanceof Error ? err.message : String(err)})`,
       );
     }
   }
-  return { hasSeeds, hasPrivateGhPackages };
+  const registryConfigFiles = REGISTRY_CONFIG_FILES.filter((f) => existsSync(join(sourceDir, f)));
+  return {
+    hasSeeds,
+    hasPrivateGhPackages,
+    installFromFullTree,
+    registryConfigFiles,
+    ...resolveDeployConfig(deployConfigRaw, appName),
+  };
 }
 
 // Unconsumed-mustache guard. After step 1+2 the only legitimate `{{`

package/templates/deploy/Dockerfile.template

@@ -1,4 +1,4 @@
-# syntax=docker/dockerfile:1.7
+# syntax=docker/dockerfile:1.27
 #
 # Production-Image for {{appName}}.
 #
@@ -13,10 +13,11 @@
 
 ARG BUN_VERSION=1.4.0
 {{#hasPrivateGhPackages}}
-# Private GH-Packages: der CI-Workflow injects GITHUB_TOKEN via --build-arg.
-# Docker's multi-stage ARG scoping braucht die Re-declaration in jeder Stage
-# die sie nutzt; das top-level ARG macht sie per `docker build` setzbar.
-ARG GITHUB_TOKEN=
+# Registry auth for @cosmicdriftgamestudio: CI passes the token as
+# NPM_AUTH_TOKEN via --build-arg. Multi-stage ARG scoping needs the
+# re-declaration inside the stage that uses it; this top-level ARG only
+# makes it settable via `docker build`.
+ARG NPM_AUTH_TOKEN=
 {{/hasPrivateGhPackages}}
 # Build identity — passed in by the CI workflow via --build-arg. Defaults
 # for local container builds.
@@ -27,24 +28,34 @@ ARG BUILD_TIME=unknown
 FROM oven/bun:${BUN_VERSION}-alpine AS build
 WORKDIR /app
 {{#hasPrivateGhPackages}}
-# GITHUB_TOKEN für @cosmicdriftgamestudio/*-Scope beim bun install.
-ARG GITHUB_TOKEN
-ENV GITHUB_TOKEN=${GITHUB_TOKEN}
-RUN bun config set --scope @cosmicdriftgamestudio token "${GITHUB_TOKEN}"
+# bunfig.toml/.npmrc resolve the @cosmicdriftgamestudio scope via $GITHUB_TOKEN.
+ARG NPM_AUTH_TOKEN
+ENV GITHUB_TOKEN=${NPM_AUTH_TOKEN}
 {{/hasPrivateGhPackages}}
 
-# Standalone-repo layout: @cosmicdrift/* pulled from NPM, no workspace:*
-# refs. Manifests first for Docker layer cache (bun install only
-# invalidates on dep change).
-COPY package.json bun.lock ./
-
+{{#installFromFullTree}}
+# file:/workspace:/link: deps (or a workspaces root) need the whole tree on
+# disk for bun to resolve the lockfile — a partial COPY makes bun treat it
+# as empty and rewrite it.
+COPY . .
+RUN bun install --frozen-lockfile
+RUN bun run build
+{{/installFromFullTree}}
+{{#installFromManifests}}
+# Manifests first for Docker layer cache — bun install only invalidates on
+# dependency change, not on every source edit.
+COPY {{installManifests}} ./
 RUN bun install --frozen-lockfile
-
 COPY . .
 RUN bun run build
+{{/installFromManifests}}
 
 # ----- runtime: bun-alpine, knows only the bundle artefact ------------------
 FROM oven/bun:${BUN_VERSION}-alpine AS runtime
+# Global ARGs are invisible inside a stage until re-declared — without this,
+# ENV BUILD_VERSION/BUILD_TIME below stay empty despite a correct --build-arg.
+ARG BUILD_VERSION=dev
+ARG BUILD_TIME=unknown
 WORKDIR /app
 
 RUN addgroup -S app && adduser -S app -G app
@@ -63,11 +74,10 @@ COPY --from=build --chown=app:app /app/dist ./dist
 # (only generate reads it; apply is checksum-tracked SQL only).
 COPY --from=build --chown=app:app /app/kumiko/migrations ./kumiko/migrations
 
-# Container entrypoint — `infra/pulumi/bun-server.ts` overrides the container
-# command to inject DATABASE_URL from the init-container's /shared/database-url
-# then execs `./start.sh`. We generate it inline so app-source-roots stay
-# clean (no per-app start.sh duplication). Apps that don't go through
-# createBunServer's command-override still boot via the CMD at the bottom
+# Container entrypoint — the platform may override the container command to
+# inject runtime secrets, then execs `./start.sh`. We generate it inline so
+# app-source-roots stay clean (no per-app start.sh duplication). Apps that
+# don't go through a command-override still boot via the CMD at the bottom
 # (`exec bun run server.js`) — start.sh is dead-code in that case.
 RUN printf '#!/bin/sh\nset -e\nexec bun run server.js\n' > ./start.sh && chmod +x ./start.sh
 
@@ -85,6 +95,8 @@ COPY --from=build --chown=app:app /app/seeds ./seeds
 USER app
 
 ENV NODE_ENV=production
+# The framework assumes UTC.
+ENV TZ=UTC
 ENV PORT={{port}}
 # The bundled kumiko.js CLI resolves its repo-relative paths via
 # KUMIKO_REPO_ROOT (default: parent-of-import.meta.dir, which inside the