create-stitchkit 0.3.3 → 0.4.1

package/template/scripts/acceptance-local.ts

@@ -0,0 +1,144 @@
+/**
+ * The runtime gates, against a deployment this script owns.
+ *
+ * `runtime:smoke` and `e2e` check a RUNNING deployment, so a gate list has to
+ * bring one up. The wrong way to do that — and the way this replaced — is
+ * `pm2:prod`: it applies the declared migrations and reloads the developer's
+ * own PM2 daemon, so "run these before handing work off" quietly meant "deploy".
+ * A gate may not mutate a deployment; it may only create and destroy its own.
+ *
+ * So everything here is this run's and nothing else's: its own `PM2_HOME`, its
+ * own ephemeral ports, its own public-host allowlist, its own database, and a
+ * stop that names the roles the declaration declares rather than deleting
+ * whatever the daemon happened to hold.
+ *
+ * The database is the last thing this owned. It used to inherit `DATABASE_URL`,
+ * which made a GATE a writer: the repository example's smoke posts a refresh,
+ * and that upserts. It now runs against `ACCEPTANCE_DATABASE_URL` and refuses to
+ * start when that is unset or names the deployment's own database — and the
+ * deployment's URL is not in the child environment at all, so no role here can
+ * reach it even by asking.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { resolveAcceptanceDatabase } from './acceptance-database';
+import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
+import { assertBuildArtifacts, runDeclaredReleaseSteps } from './release-steps';
+import { deploymentEnvironment } from './tooling-env';
+
+const root = resolve(import.meta.dir, '..');
+
+function freePort(): number {
+  const listener = Bun.listen({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: { data: () => undefined },
+  });
+  const port = listener.port;
+  listener.stop(true);
+  return port;
+}
+
+async function run(command: string[], env: Record<string, string>): Promise<void> {
+  const child = Bun.spawn(command, {
+    cwd: root,
+    env,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  const exitCode = await child.exited;
+  if (exitCode !== 0) throw new Error(`${command.join(' ')} failed with exit code ${exitCode}`);
+}
+
+if (!Bun.which('pm2')) {
+  throw new Error(
+    'pm2 is required to run the local acceptance gate. Install it with `bun add --global pm2`, then rerun.',
+  );
+}
+
+assertBuildArtifacts();
+
+const home = await mkdtemp(join(tmpdir(), 'acceptance-local-'));
+const apiPort = freePort();
+const webPort = freePort();
+const apiOrigin = `http://127.0.0.1:${apiPort}`;
+const webOrigin = `http://127.0.0.1:${webPort}`;
+const base = deploymentEnvironment(root);
+// Before anything starts, and before the deployment's own URL is copied into
+// the child environment: a refusal here costs a message, a missing one costs
+// rows in someone's database.
+const acceptanceDatabaseUrl = resolveAcceptanceDatabase(base);
+const environment: Record<string, string> = {};
+for (const [name, value] of Object.entries(base)) {
+  if (value !== undefined) environment[name] = value;
+}
+delete environment.ACCEPTANCE_DATABASE_URL;
+Object.assign(environment, {
+  NODE_ENV: 'production',
+  // The one address every role, every migration and every gate here will see.
+  DATABASE_URL: acceptanceDatabaseUrl,
+  PM2_HOME: home,
+  API_PORT: String(apiPort),
+  WEB_PORT: String(webPort),
+  INTERNAL_API_URL: apiOrigin,
+  SMOKE_API_ORIGIN: apiOrigin,
+  SMOKE_WEB_ORIGIN: webOrigin,
+  PLAYWRIGHT_BASE_URL: webOrigin,
+  // The portability proof asks this deployment to answer as addresses other
+  // than the one it is dialled on. Those addresses belong to the CHECK, so
+  // they are supplied here rather than written into the project's own
+  // `.env.example`, where they would be policy a deployment carries for real.
+  PUBLIC_WEB_HOSTS: `127.0.0.1:${webPort},alpha.example,beta.example:8443`,
+});
+
+// Boxed, so a thrown `undefined` is still recorded as a failure.
+let failure: { error: unknown } | undefined;
+try {
+  // The declared migrations, against the acceptance database. A deployment is
+  // brought to its source before its roles start — that is a property of this
+  // deployment too, and skipping it here would mean the gates run against
+  // whatever schema the throwaway database happened to have.
+  await runDeclaredReleaseSteps(environment);
+  await run(['pm2', 'start', 'ecosystem.config.cjs', '--update-env'], environment);
+  await awaitRolesAnswering(declaredRoleReadiness(appDeclaration, environment));
+  await run(['bun', 'run', 'runtime:smoke'], environment);
+  await run(['bun', 'run', 'e2e'], environment);
+  console.log(
+    `Local acceptance passed: ${appDeclaration.roles.map((role) => role.name).join(' and ')} answered on ephemeral ports, and both runtime gates are green`,
+  );
+} catch (error) {
+  failure = { error };
+}
+
+// Only what this run started, named from the declaration. `pm2 delete all`
+// would delete every application in the daemon it is pointed at — and pointing
+// it at the wrong home is one forgotten variable away.
+const cleanupFailures: unknown[] = [];
+for (const step of [
+  () =>
+    run(
+      [
+        'pm2',
+        'delete',
+        ...appDeclaration.roles.map((role) => `${appDeclaration.identity.slug}-${role.name}`),
+      ],
+      environment,
+    ),
+  () => run(['pm2', 'kill'], environment),
+  () => rm(home, { recursive: true, force: true }),
+]) {
+  try {
+    await step();
+  } catch (error) {
+    cleanupFailures.push(error);
+  }
+}
+
+const failures = [...(failure ? [failure.error] : []), ...cleanupFailures];
+if (failures.length === 1) throw failures[0];
+if (failures.length > 1) {
+  throw new AggregateError(failures, 'Local acceptance failed, and so did its cleanup');
+}

package/template/scripts/build-inputs.test.ts

@@ -0,0 +1,69 @@
+import { expect, test } from 'bun:test';
+import { createHash } from 'node:crypto';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ProjectDeclaration } from 'stitchkit/declaration';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { assertDeclaredBuildInputs } from './build-inputs';
+
+function digestOf(text: string): string {
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+function withInput(path: string, digest: string): ProjectDeclaration {
+  const build = appDeclaration.build;
+  if (!build) throw new Error('the template declares a build');
+  return {
+    ...appDeclaration,
+    build: { ...build, inputs: [{ name: 'catalogue', path, digest }] },
+  };
+}
+
+test('this template declares no build inputs, and that is the answer', () => {
+  // Not "we forgot to say": the frontend cannot reach a data source at all
+  // (`check-authored` refuses the import), so the build is a function of the
+  // source alone. If a route ever needs data at build time, it declares it.
+  expect(appDeclaration.build?.inputs).toBeUndefined();
+  expect(() => assertDeclaredBuildInputs()).not.toThrow();
+});
+
+test('a declared input whose bytes changed is refused by name', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'starter-inputs-'));
+  try {
+    await writeFile(join(directory, 'catalogue.json'), '{"items":2}');
+    // The digest of what the author froze — not of what is on disk now. This is
+    // the whole failure mode: the filename still resolves, so nothing else in
+    // the build notices that two builds of one source now differ.
+    const stale = digestOf('{"items":1}');
+    expect(() =>
+      assertDeclaredBuildInputs(withInput('catalogue.json', stale), directory),
+    ).toThrow(/"catalogue".*no longer matches its digest/s);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test('a declared input that matches its digest passes', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'starter-inputs-'));
+  try {
+    const frozen = '{"items":2}';
+    await writeFile(join(directory, 'catalogue.json'), frozen);
+    expect(() =>
+      assertDeclaredBuildInputs(withInput('catalogue.json', digestOf(frozen)), directory),
+    ).not.toThrow();
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test('a declared input that is not there names itself', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'starter-inputs-'));
+  try {
+    expect(() =>
+      assertDeclaredBuildInputs(withInput('catalogue.json', digestOf('{}')), directory),
+    ).toThrow(/Declared build input "catalogue" is missing/);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

package/template/scripts/build-inputs.ts

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ProjectDeclaration } from 'stitchkit/declaration';
+import { appDeclaration } from '../packages/config/src/declaration';
+
+const root = resolve(import.meta.dir, '..');
+
+/**
+ * The third kind of input, checked before the build reads it.
+ *
+ * The boundary rule separates code from the values of a place. Data read while
+ * building is neither: it is not in the source and it is not a binding, so a
+ * build that reads it is a function of something nobody declared. That is the
+ * dependency that never announces itself — it works on the machine that happens
+ * to have the database, and the artifact quietly stops being a function of the
+ * source.
+ *
+ * Three answers are legitimate, per route rather than per project: render at
+ * runtime (the default, and what this template does), read a frozen export
+ * whose digest is declared here, or generate the bytes as a release step. This
+ * file owns the second one. It is deliberately a no-op for a project that
+ * declares no inputs — absent means "this build reads no DECLARED data", which
+ * is an answer rather than a gap. It is the author's statement, not a traced
+ * fact: nothing here sandboxes the build to see what it really opened.
+ */
+export function assertDeclaredBuildInputs(
+  declaration: ProjectDeclaration = appDeclaration,
+  from: string = root,
+): void {
+  for (const input of declaration.build?.inputs ?? []) {
+    const path = resolve(from, input.path);
+    let bytes: Buffer;
+    try {
+      bytes = readFileSync(path);
+    } catch {
+      throw new Error(
+        `Declared build input "${input.name}" is missing: ${input.path}. A build input is a frozen export inside the source — restore it, or stop declaring it and read the data at runtime.`,
+      );
+    }
+    const actual = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+    if (actual !== input.digest) {
+      throw new Error(
+        `Declared build input "${input.name}" (${input.path}) no longer matches its digest.\n  declared: ${input.digest}\n  actual:   ${actual}\nTwo builds of one source would produce different bytes. Re-freeze the export and update the digest in project.json, or drop the input and render the data at runtime.`,
+      );
+    }
+  }
+}
+
+if (import.meta.main) {
+  assertDeclaredBuildInputs();
+  const declared = appDeclaration.build?.inputs ?? [];
+  console.log(
+    declared.length === 0
+      ? 'This build reads no declared data.'
+      : `${declared.length} declared build input(s) match their digests.`,
+  );
+}

package/template/scripts/build-stamp.test.ts

@@ -0,0 +1,151 @@
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import {
+  assertArtifactMatchesSource,
+  BUILD_STAMP_PATH,
+  sourceDigest,
+  writeBuildStamp,
+} from './build-stamp';
+
+const created: string[] = [];
+afterAll(async () => {
+  for (const path of created) await rm(path, { recursive: true, force: true });
+});
+
+async function tree(files: Record<string, string>): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'build-stamp-'));
+  created.push(root);
+  for (const [relative, contents] of Object.entries(files)) {
+    const path = join(root, relative);
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, contents);
+  }
+  return root;
+}
+
+describe('a release starts this source, not a previous one', () => {
+  test('a stamped tree passes its own check', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    writeBuildStamp(root, []);
+    expect(() => assertArtifactMatchesSource(root, [])).not.toThrow();
+  });
+
+  test('an edited source file makes the artifact refuse to start', async () => {
+    // The failure this exists for: `pm2:prod` without a build applies THIS
+    // source's migrations and starts the previous source's `dist`. The schema
+    // moves ahead of the code, and rolling the code back does not undo it.
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/index.ts'), 'export const a = 2;\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a new source file counts, without anyone listing it', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/added.ts'), 'export const b = 2;\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a moved file changes the digest even with every byte unchanged', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    const before = sourceDigest(root, []);
+    await rm(join(root, 'src/index.ts'));
+    await writeFile(join(root, 'src/moved.ts'), 'export const a = 1;\n');
+    expect(sourceDigest(root, [])).not.toBe(before);
+  });
+
+  test('a binding is not an input — editing `.env` does not refuse the artifact', async () => {
+    // Deliberate, and the one exclusion that is a JUDGEMENT rather than a fact
+    // about outputs. This project forbids build-time environment reads —
+    // `check-authored` refuses direct environment access outside its declared
+    // boundaries, and the packed lane builds against a database that accepts
+    // nothing — so hashing
+    // `.env` would refuse a correct artifact every time a deployment edited its
+    // own environment.
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n', '.env': 'PORT=1\n' });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, '.env'), 'PORT=2\n');
+    expect(() => assertArtifactMatchesSource(root, [])).not.toThrow();
+  });
+
+  test('a Markdown file counts, because a project may import one', async () => {
+    // The digest used to skip every `.md`, every test file and every directory
+    // called `generated`. All three are true of THIS project today and none is
+    // true by construction: MDX is an import, and a checked-in directory may be
+    // called anything. A digest that answers "fresh" about a stale build is the
+    // failure the stamp exists to prevent.
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'content/post.md': 'before\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'content/post.md'), 'after\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a directory merely NAMED generated is source', async () => {
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'src/generated/checked-in.ts': 'export const kept = 1;\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/generated/checked-in.ts'), 'export const kept = 2;\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a test file counts too', async () => {
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'src/index.test.ts': 'test("x", () => {});\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/index.test.ts'), 'test("y", () => {});\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('what the DECLARATION calls output is skipped, by path and not by name', async () => {
+    // The one list a deployment tool already reads. `packages/db/src/generated`
+    // is skipped because `build.artifacts` says it is produced, not because of
+    // the word in it.
+    const artifacts = ['packages/db/src/generated', 'packages/frontend/.next'];
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'node_modules/pkg/index.js': 'module.exports = 1;\n',
+      'packages/db/src/generated/client.ts': 'export const generated = 1;\n',
+      'packages/frontend/.next/build-manifest.json': '{}\n',
+    });
+    writeBuildStamp(root, artifacts);
+    await writeFile(join(root, 'node_modules/pkg/index.js'), 'module.exports = 2;\n');
+    await writeFile(
+      join(root, 'packages/db/src/generated/client.ts'),
+      'export const generated = 2;\n',
+    );
+    await writeFile(join(root, 'packages/frontend/.next/build-manifest.json'), '{"c":1}\n');
+    expect(() => assertArtifactMatchesSource(root, artifacts)).not.toThrow();
+  });
+
+  test('an undeclared build output is NOT skipped', async () => {
+    // Falsification for the test above: without it, a helper that skipped every
+    // `.next` anywhere would pass it just as well.
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'packages/frontend/.next/build-manifest.json': '{}\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'packages/frontend/.next/build-manifest.json'), '{"c":1}\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('this project declares its outputs, so the default skips them', async () => {
+    expect(appDeclaration.build?.artifacts).toContain('packages/db/src/generated');
+  });
+
+  test('no stamp at all is refused, not assumed fresh', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(new RegExp(BUILD_STAMP_PATH));
+  });
+});

package/template/scripts/build-stamp.ts

@@ -0,0 +1,169 @@
+/**
+ * What the artifact was built FROM, so a release can tell whether it still is.
+ *
+ * `assertBuildArtifacts()` checked that the declared paths exist. Existence is
+ * not freshness: `pm2:prod` run without a build applies the migrations this
+ * source declares and then starts the `dist` and `.next` of an earlier one. The
+ * schema moves ahead of the code, which is the worst direction — rolling the
+ * code back does not roll the schema back with it.
+ *
+ * So the build leaves a stamp: one digest over the source it read. The release
+ * recomputes it and compares. A digest, not a timestamp, because a checkout
+ * rewrites every mtime and a formatter rewrites some for no change at all —
+ * both would make the gate cry wolf, and a gate nobody believes is worse than
+ * none.
+ *
+ * **Everything is source until something says otherwise, and the something is
+ * named.** The first version of this listed what to skip by *kind* — every
+ * `.md`, every test file, every directory called `generated` — which reads as
+ * "these cannot affect a build" and is only true of the project as it stands
+ * today. A project that imports MDX, or keeps checked-in source in a directory
+ * it happened to call `generated`, would change its content, keep its digest,
+ * and be told its old artifact was current. A digest that answers "fresh" about
+ * a stale build is worse than no digest.
+ *
+ * So the exclusions are now exactly three kinds, each named rather than guessed:
+ *
+ * - **The build's own OUTPUTS**, read from `build.artifacts` in the project
+ *   declaration. One source of truth: a project that adds an artifact is
+ *   covered by declaring it, and `packages/db/src/generated` is skipped because
+ *   the declaration calls it output — not because of its name.
+ * - **Not this project's source at all**: `node_modules`, `.git`. (`bun.lock`
+ *   is source and is hashed.)
+ * - **Runtime state**: `.env*`, logs, and the directories a test run writes.
+ *   `.env` is deliberate and not an oversight — a binding is not an input to
+ *   this build, which is the whole point of forbidding `NEXT_PUBLIC_*` env
+ *   reads and of building the packed lane against a database that accepts
+ *   nothing. Hashing it would refuse a correct artifact every time a deployment
+ *   edited its own environment: the same gate, crying wolf in the other
+ *   direction.
+ *
+ * The cost is that editing a README or a test now asks for a rebuild before a
+ * release. That is the safe direction: the gate can be wrong about "stale", and
+ * must never be wrong about "fresh".
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { z } from 'zod';
+import { appDeclaration } from '../packages/config/src/declaration';
+
+const root = resolve(import.meta.dir, '..');
+
+export const BUILD_STAMP_PATH = '.build-stamp.json';
+
+/** Not this project's source, and state a test run leaves behind. */
+const IGNORED_DIRECTORIES = new Set([
+  'node_modules',
+  '.git',
+  'coverage',
+  'test-results',
+  'playwright-report',
+]);
+
+function isIgnoredFile(name: string): boolean {
+  return (
+    name === BUILD_STAMP_PATH ||
+    // Written by `next typegen`, which `bun run check` runs — a generated file
+    // sitting at a package root rather than inside a declared artifact, and one
+    // that exists or not depending on whether anyone has run `check` yet.
+    name === 'next-env.d.ts' ||
+    // A binding, not an input. See the note above.
+    name.startsWith('.env') ||
+    name.endsWith('.log')
+  );
+}
+
+/** The declared outputs, as normalised relative paths. */
+function outputPaths(artifacts: readonly string[]): string[] {
+  return artifacts.map((artifact) => artifact.replaceAll('\\', '/').replace(/\/+$/, ''));
+}
+
+function sourceFiles(
+  from: string,
+  outputs: readonly string[],
+  directory: string = from,
+  found: string[] = [],
+): string[] {
+  for (const entry of readdirSync(directory).sort()) {
+    const path = join(directory, entry);
+    const relativePath = relative(from, path).replaceAll('\\', '/');
+    if (outputs.includes(relativePath)) continue;
+    if (statSync(path).isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry)) continue;
+      sourceFiles(from, outputs, path, found);
+    } else if (!isIgnoredFile(entry)) {
+      found.push(path);
+    }
+  }
+  return found;
+}
+
+/**
+ * One digest over every file a build of this project reads.
+ *
+ * `artifacts` defaults to what the declaration says the build produces, so the
+ * one list a deployment tool reads is the one this skips.
+ */
+export function sourceDigest(
+  from: string = root,
+  artifacts: readonly string[] = appDeclaration.build?.artifacts ?? [],
+): string {
+  const digest = createHash('sha256');
+  for (const path of sourceFiles(from, outputPaths(artifacts))) {
+    // The PATH goes in too: moving a file changes the build without changing
+    // any byte inside it.
+    digest.update(relative(from, path));
+    digest.update('\0');
+    digest.update(readFileSync(path));
+    digest.update('\0');
+  }
+  return `sha256:${digest.digest('hex')}`;
+}
+
+const BuildStampSchema = z.object({
+  schemaVersion: z.literal(1),
+  source: z.string().startsWith('sha256:'),
+});
+
+export function writeBuildStamp(
+  from: string = root,
+  artifacts: readonly string[] = appDeclaration.build?.artifacts ?? [],
+): string {
+  const source = sourceDigest(from, artifacts);
+  writeFileSync(
+    join(from, BUILD_STAMP_PATH),
+    `${JSON.stringify({ schemaVersion: 1, source }, null, 2)}\n`,
+  );
+  return source;
+}
+
+/**
+ * Refuse an artifact that is not this source's.
+ *
+ * A missing stamp is refused too, and deliberately: it means the artifact was
+ * produced by something other than this build, and "we cannot tell" is not a
+ * reason to start it.
+ */
+export function assertArtifactMatchesSource(
+  from: string = root,
+  artifacts: readonly string[] = appDeclaration.build?.artifacts ?? [],
+): void {
+  const path = join(from, BUILD_STAMP_PATH);
+  if (!existsSync(path)) {
+    throw new Error(
+      `No build stamp beside the artifacts (${BUILD_STAMP_PATH}). Run \`bun run build\` — a release will not start an artifact it cannot tie to this source.`,
+    );
+  }
+  const stamp = BuildStampSchema.parse(JSON.parse(readFileSync(path, 'utf8')));
+  const current = sourceDigest(from, artifacts);
+  if (stamp.source !== current) {
+    throw new Error(
+      `The built artifacts are not this source's: the stamp says ${stamp.source.slice(0, 19)}…, the tree hashes to ${current.slice(0, 19)}…. Run \`bun run build\` before releasing — otherwise the declared migrations of this source are applied to a deployment running the previous one.`,
+    );
+  }
+}
+
+if (import.meta.main) {
+  console.log(`Build stamped: ${writeBuildStamp()}`);
+}

package/template/scripts/check-authored.ts

@@ -7,12 +7,13 @@ const rootFiles = ['playwright.config.ts', 'ecosystem.config.cjs', 'ecosystem.de
 const processEnvMarker = ['process', 'env'].join('.');
 const replacedThemePackage = ['next', 'themes'].join('-');
 const generatedDirectories = new Set(['.git', '.next', 'dist', 'node_modules']);
+// The supervision files used to read the environment directly to build an argv
+// for the web role. They no longer do — a role reads its own bindings — so they
+// are no longer environment boundaries, and this list is smaller by two.
 const processEnvBoundaries = new Set([
   'packages/frontend/src/env.ts',
   'packages/config/src/server.ts',
   'scripts/tooling-env.ts',
-  'ecosystem.config.cjs',
-  'ecosystem.dev.config.cjs',
 ]);
 
 function lineAt(source: string, offset: number): number {
@@ -52,6 +53,21 @@ function inspect(path: string, source: string): string[] {
         failures.push(
           `${path}: server-only dependency ${dependency} crossed the browser boundary`,
         );
+        // Two separate reasons meet on this line, and the second one is the
+        // quiet one. Shipping a database client to the browser is the obvious
+        // failure; the other is that a route reaching a data source makes the
+        // BUILD depend on data — bytes that are neither code nor a binding, so
+        // the artifact stops being a function of the source and starts being a
+        // function of whichever machine had the database. Three answers are
+        // legitimate, chosen per route: render at runtime (what this template
+        // does), declare a frozen export as `build.inputs` in `project.json`
+        // and let `scripts/build-inputs.ts` pin its digest, or generate the
+        // bytes as a release step.
+        if (path.startsWith('packages/frontend/src/app/')) {
+          failures.push(
+            `${path}: a route reading data makes the build depend on it — render at runtime, declare the export in build.inputs, or generate it as a release step`,
+          );
+        }
       }
     }
   }