create-stitchkit 0.3.3 → 0.4.0

package/template/packages/frontend/src/lib/seo/request-origin.ts

@@ -0,0 +1,89 @@
+import { headers } from 'next/headers';
+import { env } from '@/env';
+
+/**
+ * The public origin this response is being served on.
+ *
+ * Derived from the REQUEST, never from the build. An absolute address read at
+ * build time is frozen into the artifact — `robots.txt` and `sitemap.xml` were
+ * prerendered with one origin inside their bytes, so a single build could not
+ * serve a second address. Reading the request instead makes one artifact
+ * correct at every address it is ever routed to.
+ *
+ * **The request is not trusted on its own.** `x-forwarded-host` is set by
+ * whoever is in front of this process, and a request that reaches the role
+ * directly can set it too. An unchecked value would put an attacker's host into
+ * canonical URLs, the sitemap and OG metadata — the artifact would be portable
+ * and also forgeable. So a forwarded host is honoured only when the deployment
+ * has said which hosts it serves, and `PUBLIC_WEB_ORIGIN` remains the way to
+ * state a single one.
+ *
+ * Both are read at RUNTIME (no `NEXT_PUBLIC_` prefix, so nothing is substituted
+ * at build time).
+ */
+export async function requestOrigin(): Promise<string> {
+  const configured = env.PUBLIC_WEB_ORIGIN;
+  if (configured) return new URL(configured).origin;
+
+  const incoming = await headers();
+  const host = firstValue(incoming.get('x-forwarded-host') ?? incoming.get('host'));
+  if (!host) {
+    throw new Error(
+      'Cannot determine the public origin: the request carried no Host header. Set PUBLIC_WEB_ORIGIN.',
+    );
+  }
+  if (!isAllowedHost(host)) {
+    throw new Error(
+      `Refusing to answer for host "${host}": it is not in PUBLIC_WEB_HOSTS. Set PUBLIC_WEB_ORIGIN for a single address, or PUBLIC_WEB_HOSTS for several.`,
+    );
+  }
+  return new URL(`${protocolOf(incoming.get('x-forwarded-proto'))}://${host}`).origin;
+}
+
+/**
+ * Which hosts this deployment serves.
+ *
+ * Empty means "only what `PUBLIC_WEB_ORIGIN` says", and since that short-circuits
+ * above, an empty list with no origin set is a deployment that has not been told
+ * where it lives — which is an error, not a licence to believe the caller.
+ *
+ * There is deliberately no wildcard: serving any host is the same as having no
+ * canonical origin, and every answer this module gives is a canonical origin.
+ */
+function isAllowedHost(host: string): boolean {
+  const allowed = env.PUBLIC_WEB_HOSTS?.split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry.length > 0);
+  if (!allowed || allowed.length === 0) return false;
+  // No wildcard. `*` read as "serve any host" — which is the same as having no
+  // canonical origin at all, and therefore no meaningful answer to give for a
+  // canonical URL, a sitemap or an OG card. A deployment that genuinely serves
+  // many addresses lists them; one that does not know which it serves has a
+  // configuration problem, not a licence to believe the caller.
+  return allowed.includes(host.toLowerCase());
+}
+
+/**
+ * The scheme this response is being served over.
+ *
+ * Only two are possible, and anything else is a misconfigured proxy or a
+ * forgery — both of which must be seen, not normalised. Mapping every unknown
+ * value to `http` meant `ftp`, `javascript` and a truncated header all produced
+ * a plausible-looking origin, and the answer went into canonical URLs.
+ *
+ * A missing header is not a failure: a deployment reached directly has no
+ * forwarding layer, and `http` is then the truth.
+ */
+function protocolOf(header: string | null): 'http' | 'https' {
+  const forwarded = firstValue(header)?.toLowerCase();
+  if (forwarded === undefined) return 'http';
+  if (forwarded === 'http' || forwarded === 'https') return forwarded;
+  throw new Error(
+    `Refusing to answer for forwarded protocol "${forwarded}": x-forwarded-proto must be http or https. Fix the proxy, or set PUBLIC_WEB_ORIGIN to state the public origin outright.`,
+  );
+}
+
+/** A forwarded header may carry the whole proxy chain — the first hop is ours. */
+function firstValue(header: string | null): string | undefined {
+  return header?.split(',')[0]?.trim() || undefined;
+}

package/template/packages/frontend/src/theme/config.ts

@@ -1,4 +1,4 @@
-import { appIdentity } from '@app/config/identity';
+import { appIdentity } from '@app/config/app-identity';
 import type { ThemeProviderProps } from '@wrksz/themes/next';
 
 export type AppTheme = 'light' | 'dark';

package/template/packages/frontend/tsconfig.json

@@ -5,15 +5,22 @@
     "jsx": "react-jsx",
     "incremental": true,
     "types": ["bun"],
-    "plugins": [{ "name": "next" }],
-    "paths": { "@/*": ["./src/*"] }
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
   },
   "include": [
     "next-env.d.ts",
     "next.config.ts",
     "src/**/*.ts",
     "src/**/*.tsx",
-    ".next/types/**/*.ts"
+    ".next/types/**/*.ts",
+    "scripts/**/*.ts"
   ],
   "exclude": ["node_modules"]
 }

package/template/playwright.config.ts

@@ -2,7 +2,7 @@ import { defineConfig, devices } from '@playwright/test';
 import { loadToolingEnv } from './scripts/tooling-env';
 
 const toolingEnv = loadToolingEnv();
-const baseURL = toolingEnv.PLAYWRIGHT_BASE_URL ?? toolingEnv.NEXT_PUBLIC_WEB_URL;
+const baseURL = toolingEnv.PLAYWRIGHT_BASE_URL ?? toolingEnv.SMOKE_WEB_ORIGIN;
 
 export default defineConfig({
   testDir: './e2e',

package/template/project.json

@@ -0,0 +1,169 @@
+{
+  "schemaVersion": 1,
+  "kind": "application",
+  "identity": {
+    "slug": "stitchkit-starter",
+    "name": "Stitchkit Starter",
+    "version": "0.1.0",
+    "description": {
+      "en": "Stitchkit Starter is a production application built with Stitchkit.",
+      "ru": "Stitchkit Starter — production-приложение на Stitchkit."
+    }
+  },
+  "roles": [
+    {
+      "name": "api",
+      "workingDirectory": "packages/backend",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": [
+            "--watch",
+            "src/index.ts"
+          ]
+        },
+        "production": {
+          "executable": "bun",
+          "args": [
+            "dist/index.js"
+          ]
+        }
+      },
+      "listener": {
+        "portVariable": "API_PORT",
+        "bindVariable": "BIND_HOST",
+        "readinessPath": "/health"
+      },
+      "drainFloorMs": 15000
+    },
+    {
+      "name": "web",
+      "workingDirectory": "packages/frontend",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": [
+            "scripts/serve.ts",
+            "development"
+          ]
+        },
+        "production": {
+          "executable": "bun",
+          "args": [
+            "scripts/serve.ts",
+            "production"
+          ]
+        }
+      },
+      "listener": {
+        "portVariable": "WEB_PORT",
+        "bindVariable": "BIND_HOST",
+        "readinessPath": "/"
+      },
+      "drainFloorMs": 5000
+    }
+  ],
+  "build": {
+    "command": {
+      "executable": "bun",
+      "args": [
+        "run",
+        "build"
+      ]
+    },
+    "artifacts": [
+      "packages/backend/dist",
+      "packages/frontend/.next",
+      "packages/db/src/generated"
+    ]
+  },
+  "requires": [
+    {
+      "name": "postgres",
+      "phases": [
+        "release",
+        "start"
+      ]
+    }
+  ],
+  "release": {
+    "migrations": {
+      "engine": "prisma",
+      "root": "packages/db/migrations",
+      "lockfile": "packages/db/migrations/migration_lock.toml"
+    }
+  },
+  "env": {
+    "variables": [
+      {
+        "name": "API_PORT",
+        "shape": "integer",
+        "required": true
+      },
+      {
+        "name": "BIND_HOST",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "CORS_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "DATABASE_URL",
+        "shape": "url",
+        "required": true
+      },
+      {
+        "name": "INTERNAL_API_URL",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "LOG_FORMAT",
+        "shape": "enum",
+        "required": false,
+        "members": [
+          "pretty",
+          "json"
+        ]
+      },
+      {
+        "name": "NODE_ENV",
+        "shape": "enum",
+        "required": false,
+        "members": [
+          "development",
+          "test",
+          "production"
+        ]
+      },
+      {
+        "name": "PUBLIC_API_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_REALTIME_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_WEB_HOSTS",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_WEB_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "WEB_PORT",
+        "shape": "integer",
+        "required": true
+      }
+    ]
+  }
+}

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 { appDeclaration } from '../packages/config/src/declaration';
+import type { ProjectDeclaration } from '../packages/config/src/project-declaration.generated';
+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,57 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } 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';
+
+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 data", which is an
+ * answer, not a gap.
+ */
+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/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`,
+          );
+        }
       }
     }
   }

package/template/scripts/declaration.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'dotenv';
+import { appDeclaration } from '../packages/config/src/declaration';
+import {
+  assertSupervisionAllowsShutdown,
+  LOCAL_SUPERVISION,
+  renderAppIdentity,
+  renderEcosystem,
+  renderEnvVariables,
+  terminationBudgetMs,
+} from './declaration';
+import { ensureLocalEnvironment } from './local-env';
+
+const root = resolve(import.meta.dir, '..');
+const read = (name: string) => readFileSync(resolve(root, name), 'utf8');
+
+describe('the declaration is the source of what is derived from it', () => {
+  test('the checked-in supervision files are exactly what the generator renders', () => {
+    // Byte-for-byte: nothing in these files is authored, so a difference is
+    // always a hand edit or a stale file — never a formatting opinion.
+    expect(read('ecosystem.config.cjs')).toBe(renderEcosystem(appDeclaration, 'production'));
+    expect(read('ecosystem.dev.config.cjs')).toBe(
+      renderEcosystem(appDeclaration, 'development'),
+    );
+    expect(read('packages/config/src/app-identity.generated.ts')).toBe(renderAppIdentity());
+  });
+
+  test('env.variables in the declaration matches the one environment schema', () => {
+    // Content, not bytes: roles are authored in this file and the formatter
+    // owns its shape — only the derived block has to agree.
+    expect(appDeclaration.env.variables).toEqual(renderEnvVariables());
+  });
+
+  test('every declared variable appears once, with a shape a reader can act on', () => {
+    const derived = renderEnvVariables();
+    expect(new Set(derived.map((entry) => entry.name)).size).toBe(derived.length);
+    expect(derived).toContainEqual({ name: 'DATABASE_URL', shape: 'url', required: true });
+    // A variable with a default is NOT required — the schema decides, not this list.
+    expect(derived).toContainEqual({ name: 'BIND_HOST', shape: 'string', required: false });
+    // An enum names its members: "one of an unnamed set" is useless to the
+    // reader this list exists for.
+    expect(derived).toContainEqual({
+      name: 'LOG_FORMAT',
+      shape: 'enum',
+      required: false,
+      members: ['pretty', 'json'],
+    });
+  });
+});
+
+describe('supervision may not be shorter than the code needs', () => {
+  test('the budget is the whole shutdown, not just the drain', () => {
+    for (const role of appDeclaration.roles) {
+      // Drain, then the force that follows it, then cleanup. Comparing against
+      // the drain alone is what let 15s + 5s meet a 20s kill timeout exactly.
+      expect(terminationBudgetMs(role)).toBeGreaterThan(role.drainFloorMs);
+    }
+  });
+
+  test('the local policy allows every role its full shutdown', () => {
+    expect(() =>
+      assertSupervisionAllowsShutdown(appDeclaration, LOCAL_SUPERVISION.killTimeoutMs),
+    ).not.toThrow();
+  });
+
+  test('a timeout that only covers the drain is refused', () => {
+    const floor = Math.max(...appDeclaration.roles.map((role) => role.drainFloorMs));
+    expect(() => assertSupervisionAllowsShutdown(appDeclaration, floor)).toThrow(
+      /killed mid-shutdown/,
+    );
+  });
+
+  test('a timeout one millisecond under the budget is refused', () => {
+    const budget = Math.max(...appDeclaration.roles.map(terminationBudgetMs));
+    expect(() => assertSupervisionAllowsShutdown(appDeclaration, budget - 1)).toThrow();
+    expect(() => assertSupervisionAllowsShutdown(appDeclaration, budget)).not.toThrow();
+  });
+
+  test('rendering a supervision file cannot bypass the rule', () => {
+    const impatient = {
+      ...appDeclaration,
+      roles: appDeclaration.roles.map((role) => ({ ...role, drainFloorMs: 10 ** 9 })),
+    };
+    expect(() => renderEcosystem(impatient, 'production')).toThrow(/mid-shutdown/);
+  });
+});
+
+describe('no repository file carries a value of the place', () => {
+  // The real property, checked the same way the frontend build is checked: no
+  // value that differs between two deployments may appear in a repository file.
+  // A kill timeout may — supervision policy is the place's, and for the manual
+  // path this repository IS the place, which is why it is one visible constant.
+  ensureLocalEnvironment(root);
+  const environment = parse(read('.env'));
+  const placementValues = Object.values(environment).filter(
+    (value) => /^\d+$/.test(value) || value.includes('://') || /\d+\.\d+\.\d+\.\d+/.test(value),
+  );
+
+  test('the fixture actually contains ports and addresses to look for', () => {
+    expect(placementValues.length).toBeGreaterThan(2);
+  });
+
+  const repositoryFiles = [
+    'ecosystem.config.cjs',
+    'ecosystem.dev.config.cjs',
+    'project.json',
+    'packages/config/src/app-identity.generated.ts',
+  ];
+  for (const name of repositoryFiles) {
+    test(`${name} names no port and no address`, () => {
+      const rendered = read(name);
+      for (const value of placementValues) expect(rendered).not.toInclude(value);
+    });
+  }
+
+  for (const name of ['ecosystem.config.cjs', 'ecosystem.dev.config.cjs']) {
+    test(`${name} says it is generated`, () => {
+      expect(read(name)).toStartWith('// GENERATED FILE — do not edit.');
+    });
+  }
+});
+
+describe('a role starts its own process, never a launcher', () => {
+  // Measured, not assumed: under PM2 a `bun run <script>` command made the API
+  // role receive the stop signal twice — once from the supervisor, once
+  // forwarded by the launcher — and the second press forced the shutdown, which
+  // turned a declared 15s drain into 1.3ms. Direct exec: `Shutdown clean`.
+  // The schema refuses the shape; this checks what actually reaches PM2.
+  const modes: Array<'production' | 'development'> = ['production', 'development'];
+
+  for (const mode of modes) {
+    test(`the ${mode} supervision file execs the role directly`, () => {
+      const rendered = renderEcosystem(appDeclaration, mode)
+        .split('\n')
+        .filter((line) => !line.trimStart().startsWith('//'))
+        .join('\n');
+      expect(rendered).not.toMatch(/args: \["run"/);
+      expect(rendered).not.toContain('--filter');
+      // And the deployment's environment is not overruled by a repository file.
+      expect(rendered).not.toContain('override');
+    });
+  }
+});
+
+describe('the drain floor has one home', () => {
+  test('the API role reads its grace period from the declaration', () => {
+    const source = read('packages/backend/src/index.ts');
+    // A literal here would be a second number able to disagree with the one a
+    // supervisor reads, which is exactly how a 30s floor met a 15s kill timeout.
+    expect(source).toContain('gracePeriodMs: apiRole.drainFloorMs');
+    expect(source).not.toMatch(/gracePeriodMs:\s*\d/);
+  });
+});
+
+describe('an argument survives the generator intact', () => {
+  test('a space and a quote reach the supervision file unmangled', () => {
+    // The reason commands are argv and the generator serialises rather than
+    // concatenates: `split(' ')` destroyed quoted arguments, and building
+    // `'${part}'` by hand emitted invalid JavaScript for an argument
+    // containing a quote.
+    const awkward = {
+      ...appDeclaration,
+      roles: appDeclaration.roles.map((role) => ({
+        ...role,
+        commands: {
+          ...role.commands,
+          production: { executable: 'bun', args: ['run me.ts', "it's fine"] },
+        },
+      })),
+    };
+
+    const rendered = renderEcosystem(awkward, 'production');
+    expect(rendered).toContain('["run me.ts","it\'s fine"]');
+
+    // And it is still valid JavaScript: the file is `require`d by PM2.
+    expect(
+      () =>
+        new Function(
+          `return (${rendered.slice(rendered.indexOf('args: [')).slice(6).split(']')[0]}])`,
+        ),
+    ).not.toThrow();
+  });
+});
+
+describe('the guidance a next agent reads names the keys that exist', () => {
+  // `AGENTS.md` is not documentation about the past — it is the instruction the
+  // next agent follows. It kept pointing at `env.required` for a whole release
+  // after the key became `env.variables`, which is worse than a stale comment:
+  // the agent goes looking for something that is not there.
+  const guidance = ['AGENTS.md', 'README.md'];
+
+  for (const file of guidance) {
+    test(`${file} names no key the declaration does not have`, () => {
+      const text = readFileSync(resolve(import.meta.dir, '..', file), 'utf8');
+      const referenced = [...text.matchAll(/`(env|build|release|roles|identity)\.(\w+)`/g)];
+      const unknown = referenced.filter(([, root, key]) => {
+        const branch: unknown = Reflect.get(appDeclaration, root ?? '');
+        if (typeof branch !== 'object' || branch === null) return true;
+        return !Object.hasOwn(branch, key ?? '');
+      });
+      expect(unknown.map(([match]) => match)).toEqual([]);
+    });
+  }
+});