create-stitchkit 0.3.3 → 0.4.1

package/template/scripts/declaration.ts

@@ -0,0 +1,271 @@
+import { resolve } from 'node:path';
+import type {
+  ProjectDeclaration,
+  ProjectEnvVariable,
+  ProjectRole,
+} from 'stitchkit/declaration';
+import { z } from 'zod';
+import { appDeclaration } from '../packages/config/src/declaration';
+import * as shutdownBudgets from '../packages/config/src/shutdown';
+import { applicationVariables } from '../packages/config/src/variables';
+
+/**
+ * Everything derived from the project declaration.
+ *
+ * Two things used to be written by hand and had already drifted: the list of
+ * environment variables (three overlapping copies) and the two PM2 files (nine
+ * diverging lines, one of which killed the backend mid-drain every time). Both
+ * are now DERIVED — from `variables.ts` and from `project.json` — and the gate
+ * refuses a checked-in file that does not match what this module renders.
+ *
+ * Note what stays on which side. Roles, commands, readiness and the drain floor
+ * come from the declaration, because they are true of the code. Restart policy
+ * and the kill timeout are the place's, and for the manual path this file IS
+ * the place — so the policy is one visible constant below, and the rule that
+ * binds it to the code is checked rather than trusted.
+ */
+const root = resolve(import.meta.dir, '..');
+
+interface SupervisionPolicy {
+  restart: boolean;
+  /** Must cover every role's FULL termination budget — `assertSupervisionAllowsShutdown`. */
+  killTimeoutMs: number;
+}
+
+/**
+ * Local supervision policy: the place's side of the manual path.
+ *
+ * This is placement policy living in a repository, and it is here because the
+ * manual path has nowhere else to put it. It is not evidence that the
+ * declaration is placement-free — the declaration is the file next to it.
+ */
+export const LOCAL_SUPERVISION: SupervisionPolicy = {
+  restart: true,
+  killTimeoutMs: 30_000,
+};
+
+/**
+ * What a role spends after its drain floor before the process can exit.
+ *
+ * The server forces for `forceTimeoutMs` (5s by default) once the grace period
+ * ends, and `onComplete` then closes MCP and the database. A supervisor sized to
+ * the drain floor alone kills the role in the middle of that tail — which is why
+ * the earlier check, comparing against the floor only, reported that supervision
+ * "allows the full shutdown" while 15s + 5s met a 20s kill timeout exactly.
+ */
+// Imported, not restated: the role enforces these, and a number in two places
+// is two numbers that can disagree — which is exactly how a 15s drain met a
+// 20s kill timeout.
+const { FORCE_BUDGET_MS, CLEANUP_BUDGET_MS } = shutdownBudgets;
+
+/** The shortest time a supervisor may allow this role and still see it finish. */
+export function terminationBudgetMs(role: ProjectRole): number {
+  return role.drainFloorMs + FORCE_BUDGET_MS + CLEANUP_BUDGET_MS;
+}
+
+/**
+ * JSON Schema types this projection can carry into the declaration.
+ *
+ * `number` used to be mapped to `integer`, which quietly told a deployment that
+ * a fractional value was an integer — the declaration and the Zod contract it
+ * is derived FROM would then disagree, which is the one failure the derivation
+ * exists to prevent. A type with no faithful shape is refused instead: the
+ * declaration format gains the shape, or the project stops declaring that type.
+ */
+const SHAPE_BY_JSON_TYPE: Record<string, ProjectEnvVariable['shape']> = {
+  integer: 'integer',
+  boolean: 'boolean',
+};
+
+const JsonSchemaSchema = z.object({
+  properties: z.record(
+    z.string(),
+    z.object({
+      type: z.string().optional(),
+      format: z.string().optional(),
+      enum: z.array(z.unknown()).optional(),
+    }),
+  ),
+  required: z.array(z.string()).optional(),
+});
+
+/**
+ * The variables a deployment must supply, derived from the one Zod declaration.
+ *
+ * `required` follows the schema exactly: a variable with a default or an
+ * `.optional()` is not required, and nothing here restates that judgement. An
+ * enum carries its members, because "one of an unnamed set" tells a reader
+ * without a TypeScript runtime nothing — and that reader is the whole point.
+ */
+export function renderEnvVariables(
+  variables: Record<string, z.ZodType> = applicationVariables,
+): ProjectEnvVariable[] {
+  const json = JsonSchemaSchema.parse(
+    z.toJSONSchema(z.object(variables), { io: 'input', unrepresentable: 'any' }),
+  );
+  const required = new Set(json.required ?? []);
+  return Object.entries(json.properties)
+    .map(([name, property]) => describeVariable(name, property, required.has(name)))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function describeVariable(
+  name: string,
+  property: { type?: string; format?: string; enum?: unknown[] },
+  required: boolean,
+): ProjectEnvVariable {
+  if (property.enum) {
+    // Members are refused rather than stringified. `String(member)` turned
+    // numbers and booleans into text that no longer matched the value the Zod
+    // schema accepts, so a deployment reading the declaration would supply
+    // something the application then rejects — the declaration would be derived
+    // and still wrong.
+    const members = property.enum.filter((member) => typeof member === 'string');
+    if (members.length !== property.enum.length) {
+      throw new Error(
+        `Environment variable ${name} declares a non-string enum member. The declaration format carries enum members as strings; declare it as a string enum, or extend the format first.`,
+      );
+    }
+    return { name, shape: 'enum', required, members };
+  }
+  if (property.format === 'uri') return { name, shape: 'url', required };
+  if (property.type === undefined || property.type === 'string') {
+    return { name, shape: 'string', required };
+  }
+  const shape = SHAPE_BY_JSON_TYPE[property.type];
+  if (!shape) {
+    // Fail closed rather than describe the variable with the wrong shape: a
+    // reader acting on `string` when the value is something else is worse off
+    // than a reader told this project cannot describe it.
+    throw new Error(
+      `Cannot describe ${name}: no declaration shape for JSON Schema type "${property.type}".`,
+    );
+  }
+  return { name, shape, required };
+}
+
+/** The declaration as it must appear on disk: authored fields plus derived ones. */
+export function renderProjectJson(): string {
+  const declaration: ProjectDeclaration = {
+    ...appDeclaration,
+    env: { variables: renderEnvVariables() },
+  };
+  return `${JSON.stringify(declaration, undefined, 2)}\n`;
+}
+
+/**
+ * The rule the drain floor exists for: a supervisor must allow at least as long
+ * as the role needs to finish — the drain, the force that follows it, and the
+ * cleanup after that. Shorter, and the process is killed mid-shutdown, which is
+ * what a 15s kill timeout against a 30s floor did here, every time, for as long
+ * as the two numbers lived in two hand-written files.
+ */
+export function assertSupervisionAllowsShutdown(
+  declaration: ProjectDeclaration,
+  killTimeoutMs: number,
+): void {
+  for (const role of declaration.roles) {
+    const budget = terminationBudgetMs(role);
+    if (budget > killTimeoutMs) {
+      throw new Error(
+        `Role "${role.name}" needs up to ${budget}ms to finish shutting down (${role.drainFloorMs}ms drain + ${FORCE_BUDGET_MS}ms force + ${CLEANUP_BUDGET_MS}ms cleanup) but supervision allows ${killTimeoutMs}ms — it would be killed mid-shutdown.`,
+      );
+    }
+  }
+}
+
+const BANNER = `// GENERATED FILE — do not edit.
+//
+// Rendered from \`project.json\` by \`scripts/declaration.ts\`; run
+// \`bun run gen:declaration\` after changing a role. Roles, commands and the
+// drain floor come from the declaration because they are true of the code;
+// restart policy and the kill timeout are this machine's, and the generator
+// refuses a timeout shorter than any role's full shutdown budget.
+`;
+
+/** One PM2 file per run mode, rendered from the roles. */
+export function renderEcosystem(
+  declaration: ProjectDeclaration,
+  mode: 'development' | 'production',
+): string {
+  assertSupervisionAllowsShutdown(declaration, LOCAL_SUPERVISION.killTimeoutMs);
+  const suffix = mode === 'development' ? '-dev' : '';
+  const apps = declaration.roles.map((role) => renderApp(role, mode, suffix)).join('\n');
+  return `${BANNER}const path = require('node:path');
+const { config } = require('dotenv');
+const declaration = require('./project.json');
+
+// NOT \`override\`: an environment a deployment injected into this process must
+// win over a file in the repository. The file fills gaps; it does not overrule
+// the place.
+config({ path: path.join(__dirname, '.env'), quiet: true });
+
+module.exports = {
+  apps: [
+${apps}
+  ],
+};
+`;
+}
+
+function renderApp(
+  role: ProjectRole,
+  mode: 'development' | 'production',
+  suffix: string,
+): string {
+  const command = role.commands[mode];
+  if (!command) throw new Error(`Role "${role.name}" declares no ${mode} command.`);
+  const binding = role.listener ? `\`${role.listener.portVariable}\`` : 'its variables';
+  return `    {
+      name: \`\${declaration.identity.slug}-${role.name}${suffix}\`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, ${JSON.stringify(role.workingDirectory ?? '.')}),
+      script: ${JSON.stringify(command.executable)},
+      // No argv invented here: the deployment injects ${binding} and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ${JSON.stringify(command.args)},
+      interpreter: 'none',
+      autorestart: ${LOCAL_SUPERVISION.restart},
+      // >= this role's full shutdown budget of ${terminationBudgetMs(role)}ms.
+      kill_timeout: ${LOCAL_SUPERVISION.killTimeoutMs},
+      env: { NODE_ENV: '${mode}' },
+    },`;
+}
+
+const IDENTITY_BANNER = `// GENERATED FILE — do not edit.
+//
+// Rendered from \`project.json\` by \`scripts/declaration.ts\`.
+//
+// Identity ONLY, inlined rather than imported, because this is the part of the
+// declaration a browser may know. Importing the whole declaration from a client
+// component would put role commands, working directories, build artifact paths,
+// the migration lockfile and every environment variable name into the browser
+// bundle — the same mistake as publishing internal topology from a status
+// endpoint, made from the other side.
+`;
+
+/** Identity alone, safe for the client graph. */
+export function renderAppIdentity(): string {
+  return `${IDENTITY_BANNER}
+export const appIdentity = ${JSON.stringify(appDeclaration.identity, undefined, 2)};
+`;
+}
+
+export const GENERATED_FILES = {
+  'project.json': renderProjectJson,
+  'packages/config/src/app-identity.generated.ts': renderAppIdentity,
+  'ecosystem.config.cjs': () => renderEcosystem(appDeclaration, 'production'),
+  'ecosystem.dev.config.cjs': () => renderEcosystem(appDeclaration, 'development'),
+};
+
+if (import.meta.main) {
+  for (const [name, render] of Object.entries(GENERATED_FILES)) {
+    await Bun.write(resolve(root, name), render());
+    console.log(`Wrote ${name}`);
+  }
+}

package/template/scripts/deployment-preflight.ts

@@ -0,0 +1,41 @@
+/**
+ * The deployment a runtime smoke dials has to be there.
+ *
+ * `runtime:smoke` checks a RUNNING deployment — that is what makes it a runtime
+ * smoke rather than a build check. Without this the first `fetch` inside some
+ * assertion fails with a bare `ECONNRESET`, which reads like a broken check
+ * instead of an absent deployment and says nothing about what to do next. The
+ * packed lane never saw it because the lane starts the roles itself; everyone
+ * following the README's gate list saw it first.
+ */
+export async function assertDeploymentIsAnswering(
+  origins: Readonly<Record<string, string>>,
+): Promise<void> {
+  const closed: string[] = [];
+  for (const [role, origin] of Object.entries(origins)) {
+    if (!(await answers(origin))) closed.push(`${role} (${origin})`);
+  }
+  if (closed.length === 0) return;
+  throw new Error(
+    [
+      `Nothing is listening for ${closed.join(' and ')}.`,
+      '`runtime:smoke` checks a deployment that is already running, and the one it is about is',
+      'the artifact `bun run build` produced: start it with `bun run pm2:prod`, then rerun.',
+      '(`bun run dev` serves it too, from a development build.)',
+      'If the deployment is somewhere else, point SMOKE_API_ORIGIN and SMOKE_WEB_ORIGIN at it.',
+    ].join(' '),
+  );
+}
+
+/**
+ * Answering, not healthy: the checks that follow are what judge health. A role
+ * that returns 404 for `/` has still proved the thing this asks about.
+ */
+async function answers(origin: string): Promise<boolean> {
+  try {
+    await fetch(new URL(origin), { method: 'HEAD', signal: AbortSignal.timeout(10_000) });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/template/scripts/dev.ts

@@ -1,7 +1,9 @@
 import { resolve } from 'node:path';
 import { z } from 'zod';
-import { appIdentity } from '../packages/config/src/identity';
+import { appDeclaration } from '../packages/config/src/declaration';
 import { ensureLocalEnvironment } from './local-env';
+import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
+import { runDeclaredReleaseSteps } from './release-steps';
 import { inheritToolingEnvironment } from './tooling-env';
 
 const root = resolve(import.meta.dir, '..');
@@ -28,7 +30,11 @@ export async function runDevelopment(environment?: Record<string, string>): Prom
     );
   }
   await assertPortsAvailable(environmentForRun);
-  await run(['bun', 'run', 'db:setup'], environmentForRun);
+  // The generated client is a BUILD artifact; applying migrations is a RELEASE
+  // step the declaration owns. Development runs the same release step as
+  // production, so the two paths cannot drift on what 'up to date' means.
+  await run(['bun', 'run', 'db:generate'], environmentForRun);
+  await runDeclaredReleaseSteps(environmentForRun);
   await run(
     ['pm2', 'startOrReload', 'ecosystem.dev.config.cjs', '--update-env'],
     environmentForRun,
@@ -42,10 +48,17 @@ export async function runDevelopment(environment?: Record<string, string>): Prom
  */
 async function assertPortsAvailable(environment: Record<string, string>): Promise<void> {
   const registered = await registeredPm2Names();
-  const managed = [`${appIdentity.slug}-backend-dev`, `${appIdentity.slug}-frontend-dev`];
+  const managed = appDeclaration.roles.map(
+    (role) => `${appDeclaration.identity.slug}-${role.name}-dev`,
+  );
   if (managed.some((name) => registered.has(name))) return;
-  assertPortFree(Number(environment.API_PORT), 'API_PORT');
-  assertPortFree(Number(environment.WEB_PORT), 'WEB_PORT');
+  // Which ports to probe comes from the declaration, not from a second list
+  // of variable names here: a new role is covered by declaring it.
+  for (const role of appDeclaration.roles) {
+    if (!role.listener) continue;
+    const variable = role.listener.portVariable;
+    assertPortFree(Number(environment[variable]), variable);
+  }
 }
 
 async function registeredPm2Names(): Promise<Set<string>> {
@@ -74,7 +87,7 @@ function assertPortFree(port: number, variable: string): void {
     listener.stop(true);
   } catch {
     throw new Error(
-      `Port ${port} (${variable}) is already in use by another process. Pick a free port in .env and update the URLs that embed it.`,
+      `Port ${port} (${variable}) is already in use by another process. Pick a free port in .env and update the SMOKE_* origins that embed it.`,
     );
   }
 }
@@ -83,28 +96,38 @@ function assertToolAvailable(command: string, instruction: string): void {
   if (!Bun.which(command)) throw new Error(`${command} is required. ${instruction}`);
 }
 
+/**
+ * The validated environment the development processes run with.
+ *
+ * Every variable the DECLARATION names, and no hand-written list beside it: a
+ * list here went stale the moment a variable was added, and a role declaring a
+ * port whose name was missing got `Number(undefined)` — reported as
+ * `Port NaN (WORKER_PORT) is already in use`, which is a false diagnosis of a
+ * real mistake.
+ */
 export async function developmentEnvironment(
   overrides: Record<string, string> = {},
 ): Promise<Record<string, string>> {
   const { env } = await import('../packages/config/src/server');
-  return {
-    DATABASE_URL: env.DATABASE_URL,
-    BIND_HOST: env.BIND_HOST,
-    API_PORT: String(env.API_PORT),
-    WEB_PORT: String(env.WEB_PORT),
-    CORS_ORIGIN: env.CORS_ORIGIN,
-    NEXT_PUBLIC_API_URL: env.NEXT_PUBLIC_API_URL,
-    NEXT_PUBLIC_WEB_URL: env.NEXT_PUBLIC_WEB_URL,
-    INTERNAL_API_URL: env.INTERNAL_API_URL,
-    ...overrides,
-  };
+  const validated: Record<string, unknown> = env;
+  const declared: Record<string, string> = {};
+  for (const variable of appDeclaration.env.variables) {
+    const value = validated[variable.name];
+    if (value !== undefined) declared[variable.name] = String(value);
+  }
+  return { ...declared, ...overrides };
 }
 
 if (import.meta.main) {
   await runDevelopment();
 
   const environment = await developmentEnvironment();
-  console.log(`${appIdentity.name} development processes are running`);
-  console.log(`Web: ${environment.NEXT_PUBLIC_WEB_URL}/en`);
-  console.log(`API: ${environment.NEXT_PUBLIC_API_URL}`);
+  const roles = declaredRoleReadiness(appDeclaration, environment);
+  // Reported only once it is TRUE. The supervisor returns at the spawn, and a
+  // development build needs seconds after that before it listens — so the line
+  // below used to be printed at a moment when nothing answered, and the next
+  // command in the gate list got a connection reset.
+  await awaitRolesAnswering(roles);
+  console.log(`${appDeclaration.identity.name} development processes are running`);
+  for (const role of roles) console.log(`${role.name}: ${role.url}`);
 }

package/template/scripts/local-env.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { appIdentity } from '../packages/config/src/identity';
+import { appDeclaration } from '../packages/config/src/declaration';
 import { ensureLocalEnvironment } from './local-env';
 
 describe('ensureLocalEnvironment', () => {
@@ -19,7 +19,7 @@ describe('ensureLocalEnvironment', () => {
       // substitution is proven end-to-end by the starter lane on a renamed
       // scaffold; here we prove the file is created from the example with the
       // identity-derived database name in place.
-      const databaseName = appIdentity.slug.replaceAll('-', '_');
+      const databaseName = appDeclaration.identity.slug.replaceAll('-', '_');
       expect(created).toContain(`5432/${databaseName}`);
 
       // Idempotency — a developer's local credentials survive every dev run.

package/template/scripts/local-env.ts

@@ -1,12 +1,18 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { appIdentity } from '../packages/config/src/identity';
+import { appIdentity } from '../packages/config/src/app-identity.generated';
 
 /**
  * Create `.env` from `.env.example` on first run, rendering the application
- * identity into the database name. `.env.example` is the ONLY environment
+ * identity into the database name.
+ *
+ * Identity, not the whole declaration: this needs one slug, and the identity
+ * module carries no dependencies. That matters here more than elsewhere —
+ * a project scaffolded with `--no-install` renders its `.env` before anything
+ * is installed, and a script that reaches for the framework's schema to read a
+ * name cannot run in that window. `.env.example` is the ONLY environment
  * source the repository ships — the scaffolder never writes `.env`, so a
- * rename in `app.config.json` changes the database of the next created
+ * rename in `project.json` changes the database of the next created
  * environment too. Synchronous on purpose: `playwright.config.ts` and other
  * synchronous entry points must be able to self-heal before validating.
  */

package/template/scripts/readiness.ts

@@ -0,0 +1,92 @@
+import type { ProjectDeclaration } from 'stitchkit/declaration';
+
+/** Where a declared role answers once it is ready. */
+export interface RoleReadiness {
+  name: string;
+  url: string;
+}
+
+/**
+ * The readiness address of every role that listens — from the DECLARATION.
+ *
+ * Which variable holds the port and which holds the bind address are the
+ * role's own statement, so a new role is covered by declaring it rather than by
+ * a second list here that would go stale.
+ */
+export function declaredRoleReadiness(
+  declaration: ProjectDeclaration,
+  environment: Record<string, string | undefined>,
+): RoleReadiness[] {
+  return declaration.roles.flatMap((role) => {
+    const listener = role.listener;
+    if (!listener) return [];
+    const port = environment[listener.portVariable];
+    // Not skipped: a role that declares a listener and has no port is a
+    // deployment that cannot have started it, and quietly waiting for nothing
+    // is the failure this module exists to remove.
+    if (!port) {
+      throw new Error(
+        `Role "${role.name}" declares a listener on ${listener.portVariable}, and this environment does not set it.`,
+      );
+    }
+    // `0.0.0.0` is what a role BINDS, never an address to dial: it means every
+    // interface, and loopback is the one this machine can always reach.
+    const bind = environment[listener.bindVariable];
+    const host = !bind || bind === '0.0.0.0' || bind === '::' ? '127.0.0.1' : bind;
+    return [
+      { name: role.name, url: `http://${authority(host, port)}${listener.readinessPath}` },
+    ];
+  });
+}
+
+/**
+ * An IPv6 literal is bracketed; everything else is written as it stands.
+ *
+ * `http://::1:3211/health` is not an address with a port — it is not a URL at
+ * all, and `fetch` refuses it. A role bound to a specific IPv6 address is a
+ * legitimate deployment, and it used to make the readiness wait fail on the
+ * spelling rather than on the role.
+ */
+function authority(host: string, port: string): string {
+  const literal = host.includes(':') && !host.startsWith('[');
+  return `${literal ? `[${host}]` : host}:${port}`;
+}
+
+/**
+ * Wait until every role answers — because starting is not running.
+ *
+ * A supervisor returns as soon as it has SPAWNED a process, and a role needs
+ * seconds after that before it listens. Printing "running" at the moment of the
+ * spawn is a claim nobody checked: the next command in the gate list dialled
+ * the declared port and got a connection reset, which reads as a broken check
+ * rather than an application still booting.
+ */
+export async function awaitRolesAnswering(
+  roles: readonly RoleReadiness[],
+  { timeoutMs = 120_000 }: { timeoutMs?: number } = {},
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  const pending = [...roles];
+  while (pending.length > 0) {
+    const role = pending[0];
+    if (!role) break;
+    if (await answers(role.url)) {
+      pending.shift();
+      continue;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `${role.name} did not answer at ${role.url} within ${Math.round(timeoutMs / 1000)}s. It is under the supervisor but not serving — read its output with \`pm2 logs\`.`,
+      );
+    }
+    await Bun.sleep(250);
+  }
+}
+
+async function answers(url: string): Promise<boolean> {
+  try {
+    return (await fetch(url, { signal: AbortSignal.timeout(5_000) })).ok;
+  } catch {
+    return false;
+  }
+}

package/template/scripts/release-steps.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from 'bun:test';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { assertBuildArtifacts, formatCommand, migrationCommandFor } from './release-steps';
+
+describe('release steps come from the declaration', () => {
+  test('the declared engine resolves to this project one command', () => {
+    expect(migrationCommandFor()).toEqual(['bun', 'run', 'db:deploy']);
+  });
+
+  test('no declared migrations means no migration step, not a skipped one', () => {
+    expect(migrationCommandFor({ ...appDeclaration, release: {} })).toBeUndefined();
+  });
+
+  test('an engine this project cannot apply is refused, never skipped', () => {
+    // Silently not migrating is the failure that leaves a machine running
+    // against the wrong schema — it has to be loud.
+    const foreign = {
+      ...appDeclaration,
+      release: {
+        migrations: { engine: 'flyway', root: 'packages/db/migrations', lockfile: 'x' },
+      },
+    };
+    expect(() => migrationCommandFor(foreign)).toThrow(/has no command for/);
+  });
+
+  test('a declared migration root that does not exist is refused', () => {
+    const missing = {
+      ...appDeclaration,
+      release: {
+        migrations: { engine: 'prisma', root: 'packages/db/nowhere', lockfile: 'x' },
+      },
+    };
+    expect(() => migrationCommandFor(missing)).toThrow(/does not exist/);
+  });
+});
+
+describe('build artifacts are checked before roles start', () => {
+  test('a missing artifact is named, together with the command that makes it', () => {
+    const unbuilt = {
+      ...appDeclaration,
+      build: {
+        command: { executable: 'bun', args: ['run', 'build'] },
+        artifacts: ['packages/backend/nowhere'],
+      },
+    };
+    // The test used to stop at the artifact name, which is why nobody noticed
+    // that the second half of the sentence had become `[object Object]` when
+    // commands turned into `{ executable, args }`. A diagnostic exists to be
+    // retyped, so the assertion reads it the way an operator would.
+    expect(() => assertBuildArtifacts(unbuilt)).toThrow(
+      /Missing build artifacts: packages\/backend\/nowhere — run `bun run build` first\./,
+    );
+  });
+
+  test('a command with a space survives the diagnostic intact', () => {
+    expect(formatCommand({ executable: 'bun', args: ['run', 'build --out dir name'] })).toBe(
+      'bun run "build --out dir name"',
+    );
+  });
+
+  test('the diagnostic never prints an object', () => {
+    const declared = appDeclaration.build;
+    if (!declared) throw new Error('the template declares a build');
+    expect(formatCommand(declared.command)).not.toContain('[object');
+    expect(formatCommand(declared.command)).toBe('bun run build');
+  });
+
+  test('the check covers every declared artifact, not a list kept beside it', () => {
+    const declared = appDeclaration.build?.artifacts ?? [];
+    expect(declared.length).toBeGreaterThan(1);
+    for (const artifact of declared) {
+      expect(() =>
+        assertBuildArtifacts({
+          ...appDeclaration,
+          build: {
+            command: { executable: 'bun', args: ['run', 'build'] },
+            artifacts: [`${artifact}-absent`],
+          },
+        }),
+      ).toThrow(new RegExp(`${artifact.replaceAll('/', '\\/')}-absent`));
+    }
+  });
+
+  test('a project that builds nothing passes', () => {
+    expect(() => assertBuildArtifacts({ ...appDeclaration, build: undefined })).not.toThrow();
+  });
+});