create-stitchkit 0.3.3 → 0.4.0

package/template/scripts/declaration.ts

@@ -0,0 +1,268 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { appDeclaration } from '../packages/config/src/declaration';
+import type {
+  ProjectDeclaration,
+  ProjectEnvVariable,
+  ProjectRole,
+} from '../packages/config/src/project-declaration.generated';
+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.
+ */
+const FORCE_BUDGET_MS = 5_000;
+const CLEANUP_MARGIN_MS = 5_000;
+
+/** 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_MARGIN_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_MARGIN_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/dev.ts

@@ -1,7 +1,8 @@
 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 { runDeclaredReleaseSteps } from './release-steps';
 import { inheritToolingEnvironment } from './tooling-env';
 
 const root = resolve(import.meta.dir, '..');
@@ -28,7 +29,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 +47,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 +86,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 +95,37 @@ 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}`);
+  console.log(`${appDeclaration.identity.name} development processes are running`);
+  for (const role of appDeclaration.roles) {
+    if (!role.listener) continue;
+    const port = environment[role.listener.portVariable];
+    const readiness = role.listener.readinessPath;
+    console.log(`${role.name}: http://${environment.BIND_HOST}:${port}${readiness}`);
+  }
 }

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,12 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { appIdentity } from '../packages/config/src/identity';
+import { appDeclaration } from '../packages/config/src/declaration';
 
 /**
  * Create `.env` from `.env.example` on first run, rendering the application
  * identity into the database name. `.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.
  */
@@ -14,7 +14,7 @@ export function ensureLocalEnvironment(root: string): void {
   const destination = resolve(root, '.env');
   if (existsSync(destination)) return;
   const example = readFileSync(resolve(root, '.env.example'), 'utf8');
-  const databaseName = appIdentity.slug.replaceAll('-', '_');
+  const databaseName = appDeclaration.identity.slug.replaceAll('-', '_');
   writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
 }
 

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();
+  });
+});

package/template/scripts/release-steps.ts

@@ -0,0 +1,108 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import type { ProjectDeclaration } from '../packages/config/src/project-declaration.generated';
+import { inheritToolingEnvironment } from './tooling-env';
+
+const root = resolve(import.meta.dir, '..');
+
+/**
+ * Bringing this deployment to this source — the steps the DECLARATION says
+ * must happen once, before any role starts.
+ *
+ * The declaration says what a migration *is* (engine, root, lockfile), not what
+ * command to run for it. That split is the point: an outside deployment tool
+ * reads the bytes and decides for itself — exact contents, admission verdict,
+ * whether a preflight is needed at all — while the project keeps the one command
+ * that applies them here. Neither side has to learn the other's vocabulary.
+ */
+const MIGRATION_COMMANDS: Record<string, string[]> = {
+  prisma: ['bun', 'run', 'db:deploy'],
+};
+
+/**
+ * The command that applies this project's declared migrations, or `undefined`
+ * when it declares none — absent means "there are none", not "we forgot to say".
+ *
+ * An engine with no command here is refused rather than skipped: silently not
+ * migrating is the failure that leaves a deployment running against the wrong
+ * schema.
+ */
+/**
+ * A declared command as an operator can retype it.
+ *
+ * `${command}` on a `{ executable, args }` object prints `[object Object]`, so
+ * the one diagnostic that exists to tell an operator what to run told them
+ * nothing. Quoting is deliberate: an argument with a space has to survive being
+ * read back.
+ */
+export function formatCommand(command: { executable: string; args: string[] }): string {
+  return [command.executable, ...command.args]
+    .map((part) => (/[\s"']/.test(part) ? JSON.stringify(part) : part))
+    .join(' ');
+}
+
+export function migrationCommandFor(
+  declaration: ProjectDeclaration = appDeclaration,
+): string[] | undefined {
+  const { migrations } = declaration.release;
+  if (!migrations) return undefined;
+
+  const command = MIGRATION_COMMANDS[migrations.engine];
+  if (!command) {
+    throw new Error(
+      `project.json declares migrations for "${migrations.engine}", which this project has no command for.`,
+    );
+  }
+  // Both declared paths are checked. The lockfile is what tells a reader the
+  // migrations belong to one lineage; declaring it and then not looking at it
+  // is how a declaration starts describing a tree that is not there.
+  const declaredPaths: Array<[string, string]> = [
+    ['root', migrations.root],
+    ['lockfile', migrations.lockfile],
+  ];
+  for (const [label, path] of declaredPaths) {
+    if (!existsSync(resolve(root, path))) {
+      throw new Error(`Declared migration ${label} ${path} does not exist.`);
+    }
+  }
+  return command;
+}
+
+/**
+ * Everything the declaration says building produces must exist before roles
+ * start.
+ *
+ * Derived from `build.artifacts` rather than from a list kept here, so an
+ * artifact added to the declaration is covered without a second edit — and the
+ * failure names the missing path instead of surfacing as a module-not-found
+ * inside a supervised process, where nobody reads it.
+ */
+export function assertBuildArtifacts(declaration: ProjectDeclaration = appDeclaration): void {
+  const build = declaration.build;
+  if (!build) return;
+  const missing = build.artifacts.filter((artifact) => !existsSync(resolve(root, artifact)));
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing build artifacts: ${missing.join(', ')} — run \`${formatCommand(build.command)}\` first.`,
+    );
+  }
+}
+
+export async function runDeclaredReleaseSteps(
+  environment?: Record<string, string>,
+): Promise<void> {
+  const command = migrationCommandFor();
+  if (!command) return;
+
+  const child = Bun.spawn(command, {
+    cwd: root,
+    env: environment ? inheritToolingEnvironment(environment) : undefined,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  if ((await child.exited) !== 0) {
+    throw new Error(`${command.join(' ')} failed`);
+  }
+}

package/template/scripts/release.ts

@@ -0,0 +1,30 @@
+import { resolve } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { assertBuildArtifacts, runDeclaredReleaseSteps } from './release-steps';
+
+/**
+ * Bring this deployment to this source, then hand the roles to the supervisor.
+ *
+ * The order is the declaration's, not this file's: build artifacts must exist,
+ * declared release steps run once, and only then do roles start. Nothing here
+ * repeats what `project.json` already says — the migration engine, the artifact
+ * paths and the roles all come from it, and the supervision file this ends with
+ * is generated from it too.
+ */
+const root = resolve(import.meta.dir, '..');
+
+assertBuildArtifacts();
+await runDeclaredReleaseSteps();
+
+const supervisor = Bun.spawn(['pm2', 'startOrReload', 'ecosystem.config.cjs', '--update-env'], {
+  cwd: root,
+  stdin: 'inherit',
+  stdout: 'inherit',
+  stderr: 'inherit',
+});
+const exitCode = await supervisor.exited;
+if (exitCode !== 0) process.exit(exitCode);
+
+for (const role of appDeclaration.roles) {
+  console.log(`${appDeclaration.identity.slug}-${role.name} is under supervision`);
+}

package/template/scripts/runtime-smoke.ts

@@ -3,10 +3,10 @@ import { createClient, createHttpClient } from 'stitchkit';
 import { z } from 'zod';
 import { runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
-import { assertPublicWebSurface } from './web-surface-smoke';
+import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-surface-smoke';
 
 const toolingEnv = loadToolingEnv();
-const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
+const apiOrigin = toolingEnv.SMOKE_API_ORIGIN;
 
 async function json(path: string): Promise<unknown> {
   const response = await fetch(`${apiOrigin}${path}`);
@@ -28,6 +28,9 @@ if (!Object.keys(openApi.paths).includes('/api/system/status')) {
 }
 
 await runSurfaceConformance({ apiOrigin });
-await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
+await assertPublicWebSurface(toolingEnv.SMOKE_WEB_ORIGIN);
+await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN);
 
-console.log('Runtime HTTP, typed client, OpenAPI, MCP and public web smoke passed');
+console.log(
+  'Runtime HTTP, typed client, OpenAPI, MCP, public web and placement-free artifact smoke passed',
+);