@ultimat3/cli 1.0.0 → 1.2.0

package/src/prerender.ts

@@ -0,0 +1,71 @@
+// `x build --target static` — the `site/` surface, rendered once and written as files a CDN or an
+// object store can serve with no process behind it. Enumeration, hashing and the output path are
+// `@ultimat3/render`'s `renderStatic`; the document is the one `x dev` serves. This file decides
+// only which routes qualify and where the bytes land.
+
+import { join } from 'node:path';
+import type { RouteEntry } from '@ultimat3/render';
+import { renderStatic, routeEntries } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { appManifest } from './app-manifest';
+import { routeDocument } from './dev-render';
+
+/**
+ * `static` only. `isr` revalidates and `ssr`/`stream`/`spa` need a process, so writing any of them
+ * to disk would publish a page whose staleness nothing can correct — and the route already
+ * declared which of the five it is.
+ */
+export const isPrerenderable = (entry: RouteEntry): boolean => entry.config.render === 'static';
+
+export interface PrerenderOptions {
+  readonly root: string;
+  readonly out: string;
+  /** Origin the rendered `<head>` builds canonical and og:url from. */
+  readonly origin?: string;
+}
+
+export interface PrerenderedPage {
+  readonly path: string;
+  /** Relative to `out`, POSIX, as `renderStatic` computed it. */
+  readonly file: string;
+  readonly hash: string;
+  readonly bytes: number;
+}
+
+export interface PrerenderReport {
+  readonly out: string;
+  readonly buildId: string;
+  readonly pages: readonly PrerenderedPage[];
+  /** Routes that exist and are not static. Reported, so "only 2 pages" is never a mystery. */
+  readonly skipped: readonly string[];
+}
+
+export const DEFAULT_ORIGIN = 'https://localhost';
+
+export async function prerenderSite(options: PrerenderOptions): Promise<PrerenderReport> {
+  // The same load `x dev` and `x manifest` perform: importing the app's modules IS what fills the
+  // route registry, so there is no route table to prerender before this runs.
+  await loadApp(options.root);
+  const buildId = (await appManifest(options.root)).manifest.buildId;
+  const origin = options.origin ?? DEFAULT_ORIGIN;
+  const pages: PrerenderedPage[] = [];
+  const skipped: string[] = [];
+
+  for (const entry of routeEntries()) {
+    if (!isPrerenderable(entry)) {
+      skipped.push(entry.path);
+      continue;
+    }
+    const artifacts = await renderStatic(
+      entry,
+      ({ path, params }) => routeDocument(entry, { url: new URL(path, origin).href, params }),
+      { buildId },
+    );
+    for (const artifact of artifacts) {
+      const file = join(options.out, artifact.outputPath);
+      const bytes = await Bun.write(file, artifact.html);
+      pages.push({ path: artifact.path, file: artifact.outputPath, hash: artifact.hash, bytes });
+    }
+  }
+  return { out: options.out, buildId, pages, skipped };
+}

package/src/serve.ts

@@ -0,0 +1,200 @@
+// What a container starts. `apps/web/server.ts` is three lines that call `runRole`, so the boot a
+// production process performs is framework code with tests rather than app code the author has to
+// get right — and it is the SAME code `x dev` runs, minus the watcher, minus `/_x`, minus
+// `dev: true`. The only production-shaped decisions live here: which role, which port, and the
+// fact that a container must bind every interface.
+
+import { listActions, toRoute } from '@ultimat3/action';
+import type { Role } from '@ultimat3/core';
+import { isRole, logger, ROLES } from '@ultimat3/core';
+import { type MigrationReport, migrate } from '@ultimat3/db';
+import type { Route } from '@ultimat3/http';
+import { loadApp } from './app-load';
+import { appManifest } from './app-manifest';
+import { assetRoutes } from './dev-assets';
+import { startQueue } from './dev-queue';
+import { appRoutes } from './dev-render';
+import type { RunningRoles, WebBinding } from './dev-roles';
+import { startRoles } from './dev-roles';
+import type { RunningServices } from './dev-runtime';
+import { startServices } from './dev-runtime';
+import type { Env } from './dev-services';
+import { resolveServices } from './dev-services';
+import { PortInvalidError, RoleUnknownError } from './errors';
+import { holdUntilShutdown } from './hold';
+import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
+import { readMigrations } from './migrations';
+
+export const DEFAULT_PORT = 3000;
+
+/** Every interface. A container bound to loopback is unreachable through its own port mapping. */
+export const CONTAINER_BINDING: WebBinding = { dev: false, hostname: '0.0.0.0' };
+
+/**
+ * `ROLE` is the one knob one image exposes. Validated rather than defaulted: a typo that fell back
+ * to `web` would start a process that serves nothing the operator asked for and reports healthy.
+ */
+export function roleFromEnv(env: Env): Role {
+  const raw = env['ROLE'] ?? 'web';
+  if (!isRole(raw)) throw new RoleUnknownError({ role: raw, known: ROLES });
+  return raw;
+}
+
+/**
+ * `Number.parseInt` would read `80abc` as 80, so the whole string has to be a port — a
+ * partially-parsed port is a deploy that binds somewhere nobody asked for.
+ */
+function portValue(env: Env, name: string, fallback: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim().length === 0) return fallback;
+  const port = Number(raw.trim());
+  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+    throw new PortInvalidError({ value: raw, name });
+  return port;
+}
+
+/** Every PaaS injects `PORT` and routes traffic to exactly it. */
+export function portFromEnv(env: Env): number {
+  return portValue(env, 'PORT', DEFAULT_PORT);
+}
+
+/**
+ * The scrape port, deliberately its own env var and not `PORT + n`: an operator who moves the app
+ * port must not silently move the port their Prometheus is configured against, and the roles that
+ * set no `PORT` at all — `worker`, `scheduler`, `replicator` — still need this one.
+ */
+export function metricsPortFromEnv(env: Env): number {
+  return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
+}
+
+export interface ServeOptions {
+  readonly root: string;
+  readonly env: Env;
+  /** Overrides `ROLE`; `runRole` reads the environment when this is absent. */
+  readonly role?: Role;
+  /** Overrides `PORT`. 0 asks the kernel for an ephemeral one, which is what a test wants. */
+  readonly port?: number;
+  /** Overrides `METRICS_PORT`, on the same terms. */
+  readonly metricsPort?: number;
+}
+
+export interface ServedApp {
+  readonly kind: 'served';
+  readonly role: Role;
+  /** `http://…` for the web role; null for the roles that open no HTTP socket. */
+  readonly url: string | null;
+  readonly buildId: string;
+  readonly running: RunningRoles;
+  readonly runtime: RunningServices;
+  stop(): Promise<void>;
+}
+
+export interface MigratedApp {
+  readonly kind: 'migrated';
+  readonly role: 'migrate';
+  readonly report: MigrationReport;
+}
+
+export type StartedApp = ServedApp | MigratedApp;
+
+/**
+ * The release phase, as a role. `migrate` is not a server: it applies the app's own migrations
+ * through `@ultimat3/db`'s ledger — advisory lock, per-migration checksum, app-version fence — and
+ * exits, so a platform that runs one container to completion before the rest start (Heroku's
+ * release phase, a compose `service_completed_successfully`, a Kubernetes Job) has exactly one
+ * thing to run and no framework-specific flag to learn.
+ *
+ * It boots the queue, not the whole runtime: this role touches the database and nothing else, and
+ * `startQueue` is what installs `db()` for `migrate()` to find.
+ */
+export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
+  const queue = await startQueue(resolveServices(options.root, options.env));
+  try {
+    const migrations = await readMigrations(options.root);
+    const report = await migrate({
+      migrations,
+      ...(options.env['APP_VERSION'] === undefined
+        ? {}
+        : { appVersion: options.env['APP_VERSION'] }),
+    });
+    logger.info('ultimate migrate applied', {
+      applied: report.applied.length,
+      available: migrations.length,
+      appVersion: report.appVersion,
+    });
+    return { kind: 'migrated', role: 'migrate', report };
+  } finally {
+    await queue.stop();
+  }
+}
+
+/**
+ * Boot order is `x dev`'s, for the reason `x dev` gives: services, then the app's own modules
+ * (importing them IS the registration), then the role that serves what they registered. The route
+ * table is the same three contributions minus the dashboard — a `/_x` in production would expose
+ * the app's policy matrix, its outbox and its spans to the internet.
+ */
+export async function serveApp(options: ServeOptions): Promise<ServedApp> {
+  const role = options.role ?? roleFromEnv(options.env);
+  const runtime = await startServices(resolveServices(options.root, options.env), options.env);
+  // Importing the app's modules IS the registration: every route, action and job below is
+  // whatever this call put in the registries.
+  await loadApp(options.root);
+  // The build stamps `BUILD_ID` into the image; unstamped, the manifest's content hash is the same
+  // answer computed here, so `x-ultimate-build` is never absent and never a lie. Projected only
+  // when unstamped, because a stamped image already paid for it at build time and a replica's boot
+  // should not repeat it — the load above is the part every boot needs either way.
+  const stamped = options.env['BUILD_ID'];
+  const buildId =
+    stamped !== undefined && stamped.length > 0
+      ? stamped
+      : (await appManifest(options.root)).manifest.buildId;
+  const routes: readonly Route[] = [
+    ...listActions().map(toRoute),
+    ...assetRoutes({ root: options.root, storage: runtime.storage }),
+    ...appRoutes({ buildId }),
+  ];
+  const port = options.port ?? portFromEnv(options.env);
+  // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+  // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
+  // still wins — that is the deploy talking.
+  const metricsPort =
+    options.metricsPort ??
+    (port === 0 && options.env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(options.env));
+  const running = await startRoles({
+    roles: [role],
+    port,
+    metricsPort,
+    buildId,
+    runtime,
+    routes,
+    env: options.env,
+    http: CONTAINER_BINDING,
+  });
+  return {
+    kind: 'served',
+    role,
+    url: running.url,
+    buildId,
+    running,
+    runtime,
+    async stop() {
+      await running.stop();
+      await runtime.stop();
+    },
+  };
+}
+
+/**
+ * What `apps/web/server.ts` calls. Returns for `migrate` — the process is meant to exit — and
+ * holds for every other role until core's drain completes, so SIGTERM from a rolling restart takes
+ * the three-phase path (stop accepting, finish in-flight, close) instead of killing a query.
+ */
+export async function runRole(options: ServeOptions): Promise<StartedApp> {
+  const role = options.role ?? roleFromEnv(options.env);
+  if (role === 'migrate') return runMigrations({ ...options, role });
+  const app = await serveApp({ ...options, role });
+  logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
+  await holdUntilShutdown('serve', () => app.stop())();
+  return app;
+}

package/src/templates/index.ts

@@ -18,6 +18,7 @@ export { resourceFiles } from './resource';
 export type { RouteOptions, Surface } from './route';
 export { routeFiles } from './route';
 export { appFiles } from './scaffold-app';
+export { containerFiles } from './scaffold-container';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';

package/src/templates/scaffold-app.ts

@@ -280,6 +280,59 @@ export function AdminHome() {
 }
 `;
 
+// The two entry files a deploy needs. Both are deliberately thin: which role a container is, which
+// port it binds, how it drains and what a static build enumerates are the framework's answers, so
+// an upgrade moves them without a codemod in every app that ever shipped.
+
+const server =
+  (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
+// ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
+// applies the migrations and exits. PORT is bound on every interface, because a container bound to
+// localhost is unreachable through its own port mapping.
+
+import { join } from 'node:path';
+import { runRole } from '@ultimat3/cli';
+
+/**
+ * Where the app is. From this file normally — the image's WORKDIR is not the app root's business.
+ * A \`--compile\` binary is the exception: its \`import.meta.dir\` is Bun's virtual filesystem, which
+ * holds this module's bundled imports and none of the app's source, and the framework's registries
+ * are filled by scanning that source at boot. So a binary reads its root from the directory it is
+ * started in — it is a launcher for an app tree, not a self-contained copy of one.
+ */
+const root = import.meta.dir.startsWith('/$bunfs')
+  ? process.cwd()
+  : join(import.meta.dir, '..', '..');
+
+// Guarded, because the framework's module scan imports every file under apps/*/ to fill its
+// registries — an unguarded boot would start a server inside \`x verify\`.
+if (import.meta.main) {
+  await runRole({ root, env: Bun.env });
+}
+`;
+
+const prerender =
+  (): string => `// The static entry. \`x build --target static\` runs this with \`--out <dir>\` and it writes one HTML
+// file per \`render: 'static'\` route — a CDN or an object store then serves site/ with no process
+// behind it. Every other render mode needs a running app and is reported as skipped, never emitted.
+
+import { join } from 'node:path';
+import { prerenderSite } from '@ultimat3/cli';
+
+const root = join(import.meta.dir, '..', '..');
+const flag = Bun.argv.indexOf('--out');
+const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', 'static');
+// SITE_ORIGIN is what canonical and og:url are built from; the default is only ever a local build.
+const origin = Bun.env['SITE_ORIGIN'];
+
+if (import.meta.main) {
+  const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
+  await Bun.stdout.write(
+    \`\${JSON.stringify({ ok: true, out: report.out, pages: report.pages.length, skipped: report.skipped })}\\n\`,
+  );
+}
+`;
+
 const placeholder = (surface: string, app: NameSet): string => `# ${surface}
 
 Placeholder. The monorepo shape exists now so adding ${surface} later is a new directory, not a
@@ -297,6 +350,8 @@ export function appFiles(app: NameSet): readonly GeneratedFile[] {
   return [
     { path: 'apps/web/package.json', contents: webPackage(app) },
     { path: 'apps/web/tsconfig.json', contents: tsconfig() },
+    { path: 'apps/web/server.ts', contents: server() },
+    { path: 'apps/web/prerender.ts', contents: prerender() },
     { path: 'apps/web/site/icon.png', contents: icon() },
     { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
     { path: 'apps/web/site/page.module.scss', contents: siteStyle() },

package/src/templates/scaffold-container.ts

@@ -0,0 +1,264 @@
+// The container half of what `x new` writes: the image, what to ignore when building it, the
+// production topology, and the one page that explains how a platform runs the release phase.
+// Split from scaffold-docs.ts because these four are one subject and that file is another.
+//
+// Axiom 7 in file form. Nothing here names a cloud: `$PORT`, `0.0.0.0`, `/readyz` and a
+// run-to-completion migrate step are conventions every container platform shares — a Heroku
+// buildpack, a Render blueprint or a fly.toml would be the primitive that never ships.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const dockerfile = (
+  app: NameSet,
+): string => `# One image, every role. ROLE selects behaviour at start, so there is exactly one artifact to
+# promote — the image that passed staging is the image production runs.
+#
+#   x build --target docker --tag ${app.kebab}:$(git rev-parse --short HEAD)
+#   docker run --rm -e ROLE=migrate -e DATABASE_URL=... ${app.kebab}:...   # release phase
+#   docker run -e ROLE=web -e PORT=8080 -p 8080:8080 -e DATABASE_URL=... ${app.kebab}:...
+#
+# syntax=docker/dockerfile:1
+
+# ---------- deps: runtime dependencies only, cached on the workspace manifests ----------
+FROM oven/bun:1.3-alpine AS deps
+WORKDIR /app
+COPY package.json bun.lock ./
+# The workspace members' manifests are what \`bun install\` resolves against; their sources are not.
+COPY apps ./apps
+COPY packages ./packages
+RUN bun install --frozen-lockfile --production
+
+# ---------- runtime ----------
+# No build stage and no second gate: \`x verify\` is the gate and \`x build\` runs the static steps
+# before it ever calls \`docker build\`. Re-running typecheck and lint here would need the
+# devDependencies the \`--production\` install above deliberately leaves out — which is exactly how
+# a build stage came to run \`tsc\` and \`biome\` against a tree that had neither.
+FROM oven/bun:1.3-alpine AS runtime
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# The immutable content hash this image serves. Stamped by CI (\`--build-arg BUILD_ID=$(git rev-parse HEAD)\`);
+# without one the server computes the same hash from the manifest at boot. Never \`latest\`.
+ARG BUILD_ID=
+ENV NODE_ENV=production \\
+    ROLE=web \\
+    PORT=3000 \\
+    BUILD_ID=\${BUILD_ID}
+
+# Documentation only — the platform decides the real port and injects it as PORT. The server binds
+# whatever arrives, on 0.0.0.0, because a container bound to localhost is unreachable through its
+# own port mapping, its load balancer and every health probe alike.
+EXPOSE 3000
+
+# Every role serves /healthz and /readyz. /readyz flips to 503 on SIGTERM *before* the socket
+# closes, so a rolling restart drains in-flight work instead of dropping it.
+HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 CMD \\
+  bun --eval "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"
+
+# \`.x/\` is where any binding that is still embedded keeps its state — the local storage disk, and
+# PGlite if DATABASE_URL is unset. Owned by the runtime user, because /app is not: the alternative
+# is a non-root process failing at boot on a directory it is the only one that ever writes.
+RUN mkdir -p /app/.x && chown -R bun:bun /app/.x
+
+USER bun
+# apps/web/server.ts reads ROLE and PORT and nothing else. \`migrate\` applies the migrations and
+# exits; every other role serves until SIGTERM.
+ENTRYPOINT ["bun", "apps/web/server.ts"]
+`;
+
+/**
+ * BuildKit prefers `<dockerfile>.dockerignore` over the context root's, so this sits beside the
+ * Dockerfile. Without it `COPY . .` ships `node_modules` and `.x/` — a stale host `node_modules`
+ * would shadow the `--production` install the deps stage just made.
+ */
+const dockerignore = (): string => `node_modules
+**/node_modules
+**/.x
+**/dist
+**/*.tsbuildinfo
+.git
+.env
+.env.*.local
+coverage
+**/test-results
+**/playwright-report
+`;
+
+const composeProd = (
+  app: NameSet,
+): string => `# The production topology: one service per role, one image, differing only by ROLE and replicas.
+# What \`x deploy --method compose\` runs. migrate runs to completion before anything serves.
+#
+#   IMAGE=ghcr.io/you/${app.kebab}:1.2.3 x deploy --image ghcr.io/you/${app.kebab}:1.2.3
+name: ${app.kebab}
+
+x-image: &image
+  image: \${IMAGE:-${app.kebab}:dev}
+  env_file: [../.env.production]
+  restart: unless-stopped
+  stop_grace_period: 30s # SIGTERM → drain in-flight requests, jobs and sockets
+  depends_on:
+    db: { condition: service_healthy }
+
+services:
+  db:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+      POSTGRES_DB: ${app.kebab}
+    volumes: ['pgdata:/var/lib/postgresql/data']
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+    restart: unless-stopped
+
+  # The release phase. Applies pending migrations under an advisory lock and exits; every serving
+  # role waits for it to complete, so no replica ever serves against a schema it does not ship.
+  migrate:
+    <<: *image
+    environment: [ROLE=migrate]
+    restart: 'no'
+
+  web:
+    <<: *image
+    environment: [ROLE=web]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 2 } # stateless: scales on RPS
+    ports: ['3000:3000']
+
+  sync:
+    <<: *image
+    environment: [ROLE=sync]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # scales on concurrent websockets; no sticky sessions
+    ports: ['3001:3001']
+
+  worker:
+    <<: *image
+    environment: [ROLE=worker]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # scales on queue depth
+
+  scheduler:
+    <<: *image
+    environment: [ROLE=scheduler]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # fixed 1; leadership is a Postgres advisory lock
+
+volumes:
+  pgdata:
+`;
+
+const readme = (app: NameSet): string => `# docker
+
+One image, every role. \`ROLE\` selects behaviour at start, so there is one artifact to promote and
+nothing to rebuild between staging and production.
+
+| Role | Does | Listens |
+|---|---|---|
+| \`web\` | HTTP: pages, actions, assets | \`$PORT\` (default 3000) |
+| \`sync\` | websockets for live queries | \`$PORT + 1\` |
+| \`worker\` | the job queue | — |
+| \`scheduler\` | cron tasks; leadership is a Postgres advisory lock | — |
+| \`replicator\` | the logical replication slot, exactly one per database | — |
+| \`migrate\` | applies pending migrations and **exits** | — |
+
+Every serving role answers \`/healthz\` and \`/readyz\`. \`/readyz\` flips to 503 on \`SIGTERM\` before the
+socket closes, which is what makes a rolling restart drain instead of drop.
+
+## Build and run
+
+\`\`\`sh
+x build --target docker --tag ${app.kebab}:dev
+docker run --rm -e ROLE=migrate -e DATABASE_URL=postgres://... ${app.kebab}:dev
+docker run -p 3000:3000 -e DATABASE_URL=postgres://... ${app.kebab}:dev
+\`\`\`
+
+## One box, every role
+
+\`\`\`sh
+docker compose -f docker/docker-compose.prod.yml up -d      # db → migrate → the rest
+x deploy --image ${app.kebab}:dev --dry-run --json           # the same plan, printed
+\`\`\`
+
+## The other two build targets
+
+\`\`\`sh
+x build --target static --out dist/static   # one HTML file per \`render: 'static'\` route
+x build --target binary --out dist/app      # a single executable, no Bun install needed
+\`\`\`
+
+The binary bundles the framework, not the app: the registries are filled by scanning
+\`apps/*/{site,app,api,shared}\` at boot, so it is a launcher that must be **started from the app
+root**, with the source tree beside it. The image is the self-contained artifact.
+
+## A PaaS (Heroku, Render, Fly, Railway, Cloud Run, App Runner…)
+
+The framework ships **no** platform primitives — no buildpack, no \`app.json\`, no \`fly.toml\`, no
+adapter. It does not need to: every one of these platforms builds a Dockerfile and every one of
+them expects the same three things, which this image already does.
+
+| The platform does | The image does |
+|---|---|
+| injects \`PORT\` and routes traffic to it | \`apps/web/server.ts\` binds exactly \`$PORT\`, refusing a value that is not a port (\`X_PORT_INVALID\`) rather than defaulting past it |
+| requires the process to bind \`0.0.0.0\` | it binds every interface; loopback would be unreachable from outside the container |
+| polls a health path | \`/readyz\` for "may I have traffic", \`/healthz\` for "am I alive" |
+| sends \`SIGTERM\`, then \`SIGKILL\` after a grace period | drains in three phases: stop accepting, finish in-flight, close |
+
+Set \`DATABASE_URL\` and deploy the Dockerfile. That is the whole integration.
+
+### Release-phase migrations — the one way
+
+Run **the same image** with \`ROLE=migrate\` before the new release serves traffic. It applies every
+pending migration in \`packages/db/migrations\` under a Postgres advisory lock, records each in the
+\`x_migrations\` ledger with its checksum, and exits 0. Concurrent migrators serialise; a checksum
+that no longer matches an applied migration stops the release instead of corrupting it.
+
+| Platform | Where the command goes |
+|---|---|
+| Heroku | \`release: bun apps/web/server.ts\` in \`Procfile\`, with \`ROLE=migrate\` on the release dyno |
+| Render | \`preDeployCommand: ROLE=migrate bun apps/web/server.ts\` |
+| Fly.io | \`[deploy] release_command = "bun apps/web/server.ts"\` with \`ROLE=migrate\` |
+| Railway | a pre-deploy command running the same |
+| Kubernetes | an \`initContainer\` or a \`Job\` on the same image with \`ROLE=migrate\` |
+| Compose | the \`migrate\` service; every other role waits on \`service_completed_successfully\` |
+
+There is no \`x db migrate\` in that list on purpose: it is the developer's command and it needs the
+toolchain, while the release phase runs the shipped image and nothing else.
+
+## Environment
+
+| Key | Meaning | Unset means |
+|---|---|---|
+| \`ROLE\` | which process this is | \`web\` |
+| \`PORT\` | the port the web role binds | 3000 |
+| \`DATABASE_URL\` | Postgres | embedded PGlite — never in production |
+| \`BUILD_ID\` | the immutable build hash clients are served against | computed from the manifest at boot |
+| \`NATS_URL\` | multi-node realtime transport | in-process fanout, single node only |
+| \`S3_ENDPOINT\` | object storage | a local directory |
+
+## Kubernetes
+
+\`x deploy --method helm\` expects a chart at \`docker/helm\`. \`x new\` does not write one — a chart is
+a topology decision, not a scaffold default. Copy \`docker/helm\` from the framework repository, or
+stay on \`--method compose\`.
+`;
+
+/** The container files for a new app, in the order a reader meets them. */
+export function containerFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'docker/Dockerfile', contents: dockerfile(app) },
+    { path: 'docker/Dockerfile.dockerignore', contents: dockerignore() },
+    { path: 'docker/docker-compose.prod.yml', contents: composeProd(app) },
+    { path: 'docker/README.md', contents: readme(app) },
+  ];
+}

package/src/templates/scaffold-docs.ts

@@ -1,8 +1,10 @@
 // The human-authored half of what `x new` writes: the READMEs, the agent-facing convention files,
-// the bin/ shims and the docker directory. Separated from the config half so neither file has to
-// be scrolled to find the other — one file, one job applies to templates too.
+// the bin/ shims and the optional dev compose. Separated from the config half so neither file has
+// to be scrolled to find the other — one file, one job applies to templates too. The image, its
+// ignore file, the production topology and the deploy page are `scaffold-container.ts`.
 
 import type { GeneratedFile, NameSet } from './naming';
+import { containerFiles } from './scaffold-container';
 
 const agents = (app: NameSet): string => `# AGENTS.md
 
@@ -114,30 +116,6 @@ services:
     ports: ['9000:9000']
 `;
 
-const dockerfile = (
-  app: NameSet,
-): string => `# One image, all roles. ROLE selects behaviour at start; nothing else differs between processes.
-FROM oven/bun:1.3-alpine AS deps
-WORKDIR /src
-COPY package.json bun.lock ./
-COPY apps ./apps
-COPY packages ./packages
-RUN bun install --frozen-lockfile --production
-
-FROM oven/bun:1.3-alpine AS build
-WORKDIR /src
-COPY --from=deps /src/node_modules ./node_modules
-COPY . .
-RUN bunx x build --target binary --out /out/${app.kebab}
-
-FROM gcr.io/distroless/base-debian12 AS runtime
-COPY --from=build /out/${app.kebab} /app/${app.kebab}
-ENV ROLE=web PORT=3000
-EXPOSE 3000
-USER 65532:65532
-ENTRYPOINT ["/app/${app.kebab}"]
-`;
-
 /** Docs, shims and container files for a new app, in the order a reader meets them. */
 export function docsFiles(app: NameSet): readonly GeneratedFile[] {
   return [
@@ -147,8 +125,8 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'bin/setup', contents: binSetup() },
     { path: 'bin/dev', contents: binDev() },
     { path: 'bin/check', contents: binCheck() },
-    { path: 'docker/Dockerfile', contents: dockerfile(app) },
     { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
+    ...containerFiles(app),
   ];
 }