@opengsd/gsd-core 1.11.0 → 1.12.0

package/scripts/gen-hooks-cli-exit.cjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * gen-hooks-cli-exit.cjs — generates hooks/lib/cli-exit.js from a fresh
+ * compile of src/cli-exit.cts.
+ *
+ * ADR-3889 Phase 7 (#3911): shipped hooks must be able to terminate through
+ * `terminateNow` WITHOUT depending on any build artifact. hooks/ runs
+ * straight from a raw, unbuilt clone (a hook is required by name via
+ * `require('./lib/cli-exit.js')` relative to the hook's own __dirname), so
+ * the generated file is compiled to a THROWAWAY outDir rather than read from
+ * gsd-core/bin/lib/ — reading the tracked build output would let a stale
+ * build produce a false green. This mirrors scripts/gen-scripts-cli-exit.cjs
+ * exactly (same compile-to-temp strategy, same banner/check/write shape);
+ * kept as a SIBLING script rather than folded into that one because
+ * gen-scripts-cli-exit.cjs is hard-coded to a single output path/extension
+ * (`scripts/lib/cli-exit.cjs`) throughout its BANNER prose and REASON
+ * messaging — parameterizing it for a second, differently-extensioned
+ * target (`.js`, not `.cjs`, to match the hooks/lib/*.js convention) would
+ * tangle a script that is otherwise simple and single-purpose.
+ *
+ * Usage:
+ *   node scripts/gen-hooks-cli-exit.cjs            # same as --write
+ *   node scripts/gen-hooks-cli-exit.cjs --write     # write hooks/lib/cli-exit.js
+ *   node scripts/gen-hooks-cli-exit.cjs --check     # exit 1 if committed file is stale
+ *   node scripts/gen-hooks-cli-exit.cjs --out <path>   # override the output path (default: hooks/lib/cli-exit.js) — honoured by BOTH --write and --check
+ *
+ * `--out` restores parity with the sibling scripts/gen-exit-code-registry.cjs,
+ * which already supports `--out`/`--scripts-out`/`--hooks-out`/`--dts-out`/
+ * `--sh-out` overrides honoured by its own `--check`. This script hardcoding
+ * `OUTPUT_PATH` with no override was an inconsistency between two sibling
+ * generators, not an intentionally narrower surface — tests need to redirect
+ * `--check` at a disposable tmpdir copy instead of corrupting the real
+ * committed artifact in place.
+ */
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const OUTPUT_PATH = path.join(REPO_ROOT, 'hooks', 'lib', 'cli-exit.js');
+const COMPILE_TIMEOUT_MS = 60_000;
+
+/** Frozen reason codes so tests assert on structure, not prose. */
+const REASON = Object.freeze({
+  OK: 'ok_generated_sync',
+  DRIFTED: 'fail_generated_drifted',
+  BUILD_FAILED: 'fail_build_failed',
+  MISSING_EMIT: 'fail_missing_emit',
+  USAGE: 'fail_usage',
+});
+
+const USAGE_MESSAGE = [
+  'Usage: node scripts/gen-hooks-cli-exit.cjs [--write|--check] [--out <path>]',
+  '  (no flag)  same as --write',
+  '  --write    write hooks/lib/cli-exit.js',
+  '  --check    exit 1 if the committed file is stale',
+  '  --out      override the output artifact path (default: hooks/lib/cli-exit.js)',
+].join('\n');
+
+const BANNER = [
+  '// GENERATED FILE — DO NOT EDIT BY HAND.',
+  '// Source of truth: src/cli-exit.cts. Regenerate with:',
+  '//   node scripts/gen-hooks-cli-exit.cjs --write',
+  '// Byte-compared by `npm run lint:generated-sync` (#3911, ADR-3889 Phase 7).',
+  '//',
+  '// Why this copy exists: hooks/ runs straight from a raw, unbuilt clone — a',
+  '// shipped hook must be able to `require(\'./lib/cli-exit.js\')` relative to',
+  '// its own __dirname and terminate through `terminateNow` without depending',
+  '// on any build artifact. gsd-core/bin/lib/cli-exit.cjs is gitignored tsc',
+  '// output and doubles as the build sentinel, so it cannot be required from',
+  '// here. `.js`, not `.cjs`, to match the hooks/lib/*.js convention. Hence one',
+  '// source, three emitted locations (gsd-core/bin/lib, scripts/lib, hooks/lib).',
+  '',
+  '',
+].join('\n');
+
+/** Compile the whole project to a throwaway outDir so the work tree is untouched. */
+function compileToTemp() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-hooks-cli-exit-'));
+  try {
+    execFileSync(
+      process.execPath,
+      [
+        path.join(REPO_ROOT, 'node_modules', 'typescript', 'bin', 'tsc'),
+        '-p', path.join(REPO_ROOT, 'tsconfig.build.json'),
+        '--outDir', tmp,
+        // A throwaway outDir must not reuse the in-tree incremental state, or
+        // tsc skips emit for files it believes are already current.
+        '--incremental', 'false',
+        '--tsBuildInfoFile', 'null',
+      ],
+      { cwd: REPO_ROOT, encoding: 'utf8', stdio: 'pipe', timeout: COMPILE_TIMEOUT_MS },
+    );
+    return { ok: true, dir: tmp };
+  } catch (err) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    const detail = [err.stdout, err.stderr].filter(Boolean).join('\n').trim();
+    return { ok: false, detail };
+  }
+}
+
+/**
+ * Compile src/cli-exit.cts to a throwaway outDir and return the expected
+ * generated content (banner + compiled bytes, with the sibling registry
+ * require rewritten to the `.js` extension hooks/lib/ uses), or a failure
+ * descriptor.
+ *
+ * @returns {{ ok: true, content: string } | { ok: false, reason: string, detail?: string }}
+ */
+function buildExpectedContent() {
+  const build = compileToTemp();
+  if (!build.ok) {
+    return { ok: false, reason: REASON.BUILD_FAILED, detail: build.detail };
+  }
+  try {
+    const emitted = path.join(build.dir, 'cli-exit.cjs');
+    if (!fs.existsSync(emitted)) {
+      return { ok: false, reason: REASON.MISSING_EMIT, detail: `no emit produced at ${emitted} from src/cli-exit.cts` };
+    }
+    const compiled = fs.readFileSync(emitted, 'utf8');
+    // hooks/lib/ ships `.js`, not `.cjs` (matching the hooks/lib/*.js
+    // convention — see the module header), so the sibling registry require
+    // tsc emits for src/cli-exit.cts's `require('./exit-code-registry.cjs')`
+    // must be rewritten to resolve the `.js` copy scripts/gen-exit-code-
+    // registry.cjs emits alongside this file, not the `.cjs` one. A literal,
+    // anchored replace (never a regex) so this can only ever touch the exact
+    // string tsc is known to emit for that one import.
+    const REGISTRY_REQUIRE_CJS = 'require("./exit-code-registry.cjs")';
+    const REGISTRY_REQUIRE_JS = 'require("./exit-code-registry.js")';
+    if (!compiled.includes(REGISTRY_REQUIRE_CJS)) {
+      return {
+        ok: false,
+        reason: REASON.MISSING_EMIT,
+        detail: `expected compiled output to contain ${REGISTRY_REQUIRE_CJS} (the sibling registry require) — tsc's emit shape may have changed`,
+      };
+    }
+    const rewritten = compiled.split(REGISTRY_REQUIRE_CJS).join(REGISTRY_REQUIRE_JS);
+    return { ok: true, content: BANNER + rewritten };
+  } finally {
+    fs.rmSync(build.dir, { recursive: true, force: true });
+  }
+}
+
+function doWrite(outPath) {
+  const result = buildExpectedContent();
+  if (!result.ok) {
+    console.error(`FAIL gen-hooks-cli-exit: ${result.reason}`);
+    if (result.detail) console.error(result.detail);
+    return 1;
+  }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, result.content, 'utf8');
+  console.log(`ok gen-hooks-cli-exit: wrote ${path.relative(REPO_ROOT, outPath)}`);
+  return 0;
+}
+
+function doCheck(outPath) {
+  const result = buildExpectedContent();
+  if (!result.ok) {
+    console.error(`FAIL gen-hooks-cli-exit: ${result.reason}`);
+    if (result.detail) console.error(result.detail);
+    return 1;
+  }
+
+  if (!fs.existsSync(outPath)) {
+    console.error(`FAIL gen-hooks-cli-exit: ${REASON.MISSING_EMIT}`);
+    console.error(`  ${path.relative(REPO_ROOT, outPath)} does not exist. Run:`);
+    console.error('  node scripts/gen-hooks-cli-exit.cjs --write');
+    return 1;
+  }
+
+  const committed = fs.readFileSync(outPath, 'utf8');
+  if (committed !== result.content) {
+    console.error(`FAIL gen-hooks-cli-exit: ${REASON.DRIFTED}`);
+    console.error(
+      `  ${path.relative(REPO_ROOT, outPath)} (${committed.length} bytes) != ` +
+      `compile of src/cli-exit.cts (${result.content.length} bytes)`,
+    );
+    console.error('');
+    console.error('Regenerate with:');
+    console.error('  node scripts/gen-hooks-cli-exit.cjs --write');
+    return 1;
+  }
+
+  console.log(`ok gen-hooks-cli-exit: ${path.relative(REPO_ROOT, outPath)} matches src/cli-exit.cts`);
+  return 0;
+}
+
+/**
+ * @returns {{mode:'write'|'check', outPath:?string}}
+ */
+function parseArgs(argv) {
+  let mode = null;
+  let outPath = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--write' || arg === '--check') {
+      if (mode !== null) {
+        throw new Error(`conflicting mode flags: --${mode} and ${arg}`);
+      }
+      mode = arg === '--write' ? 'write' : 'check';
+    } else if (arg === '--out') {
+      const value = argv[++i];
+      if (value === undefined) throw new Error('--out requires a value');
+      outPath = value;
+    } else if (arg.startsWith('--out=')) {
+      outPath = arg.slice('--out='.length);
+    } else {
+      throw new Error(`unrecognized argument: ${arg}`);
+    }
+  }
+
+  return { mode: mode || 'write', outPath };
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    console.error(`FAIL gen-hooks-cli-exit: ${REASON.USAGE}`);
+    console.error(`  ${err.message}`);
+    console.error(USAGE_MESSAGE);
+    return 1;
+  }
+
+  const outPath = args.outPath || OUTPUT_PATH;
+
+  return args.mode === 'check' ? doCheck(outPath) : doWrite(outPath);
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { REASON, buildExpectedContent, OUTPUT_PATH, BANNER };

package/scripts/gen-install-tree-fixtures.cjs

@@ -21,7 +21,7 @@ const ROOT = path.resolve(__dirname, '..');
 // buildParityManifest) is the canonical single source of truth in
 // tests/helpers/install-shared.cjs (issue #2266/#2267) — this generator does
 // not keep its own inline copy of the walk/exclusion logic.
-const { runMinimalInstall, RUNTIME_META, buildInstallTree, BUILD_SCRIPT } = require(path.join(ROOT, 'tests', 'helpers', 'install-shared.cjs'));
+const { runMinimalInstall, RUNTIME_META, buildInstallTree, extraEmitRootsFor, BUILD_SCRIPT } = require(path.join(ROOT, 'tests', 'helpers', 'install-shared.cjs'));
 const FIXTURE_DIR = path.join(ROOT, 'tests', 'fixtures', 'install-tree');
 
 function cleanup(root) {
@@ -51,7 +51,7 @@ for (const runtime of targets) {
   const { configDir, root } = runMinimalInstall({ runtime, scope: 'global' });
   let actual;
   try {
-    actual = buildInstallTree(configDir, root);
+    actual = buildInstallTree(configDir, root, extraEmitRootsFor(runtime, 'global', root));
   } finally {
     cleanup(root);
   }

package/scripts/gen-loop-host-contract.cjs

@@ -446,8 +446,11 @@ const HOST_LOOP_FILES = STEP_WORKFLOWS.map((w) => 'gsd-core/workflows/' + w.file
  * @param {string} text  Content of a workflow file (or any text).
  * @returns {Set<string>}
  */
+/** The call-site shape both scanners key on — one regex, two consumers (#3606). */
+const CALL_SITE_RE = /loop render-hooks\s+([a-z:]+)/g;
+
 function scanWiredPoints(text) {
-  const re = /loop render-hooks\s+([a-z:]+)/g;
+  const re = CALL_SITE_RE;
   const result = new Set();
   let m;
   while ((m = re.exec(text)) !== null) {
@@ -456,6 +459,132 @@ function scanWiredPoints(text) {
   return result;
 }
 
+// ─── Hook-kind coverage (#3606) ──────────────────────────────────────────────
+
+const HOOK_KINDS = ['contribution', 'step', 'gate'];
+
+/**
+ * The kinds one call site's dispatch text actually covers (#3606).
+ *
+ * A point having a `loop render-hooks <point>` call site proves the hooks are
+ * RENDERED, not that they are DISPATCHED — a consumer that iterates only
+ * `kind == "gate"` (or narrows `kind == "step"` to one `ref.skill`) silently
+ * drops every other registered kind. Coverage rules for the text following a
+ * call site, up to the next call site or the region cap, judged LINE by line:
+ *
+ * - A deferral line (one carrying an `@`-included path to the generic
+ *   contract, e.g. `@gsd-core/references/loop-hook-dispatch.md`) that names a
+ *   kind (`kind == "step"`) covers that kind; a deferral line with no kind
+ *   discriminator ("apply each entry") covers every kind. A bare §-citation
+ *   of the reference (validation guidance only, no `@`) covers nothing —
+ *   plan-phase cites the gate-validation section while dispatching only gates.
+ * - Otherwise a kind is covered when some LINE dispatches it unconditionally:
+ *   a `kind == "<kind>"` discriminator with NO same-line narrowing to one
+ *   hook (`ref.skill ==`, `ref.agent ==`, `ref.command ==`). A narrowed line
+ *   special-cases ONE hook and proves nothing about the kind generally — the
+ *   exact hand-rolled-consumer shape the reference warns about.
+ *
+ * Quote style and spacing vary across the corpus (`kind == "step"`,
+ * `kind === 'gate'`), so the matcher is tolerant of both quote characters and
+ * of `==`/`===`.
+ *
+ * Pure: same input, same output; CRLF-safe (line splitting tolerates \r).
+ *
+ * @param {string} region  Dispatch text following one call site.
+ * @returns {Set<string>}
+ */
+function coveredKindsInRegion(region) {
+  const covered = new Set();
+  // Same-SEGMENT narrowing to ONE hook voids credit: `ref.skill ==`, `capId ==`,
+  // and `into ==` each special-case a subset, not the kind generally
+  // (plan-phase's `kind == "contribution" and capId == "security"` is the
+  // hand-rolled shape; `into == "planner"` covers only planner-targeted
+  // contributions). Segments, not lines: execute-phase legitimately writes
+  // "dispatch `kind == "step"` hooks per … . `ref.skill == "code-review"`:" —
+  // the deferral is one sentence, the specialization the next; narrowing in a
+  // DIFFERENT segment must not void the deferral's credit.
+  const narrowingRe = /(?:ref\.(?:skill|agent|command)|capId|into)\s*={2,3}/;
+  // Negated mentions describe an absence, not a dispatch ("Branch 1 — no active
+  // step hooks (`activeHooks` has no entry with `kind == "step"`)" — ship.md).
+  const negationRe = /\b(?:no|without|absent|lacks?|missing)\b[^.|]*kind\s*={2,3}/;
+  const deferralRe = /@\S*loop-hook-dispatch\.md/;
+  for (const line of region.split(/\r?\n/)) {
+    // Sentence segments: a `.`/`;` followed by whitespace ends a segment. A
+    // period NOT followed by whitespace (the `.md` inside a deferral path,
+    // `ref.skill`) is not a boundary.
+    for (const segment of line.split(/(?<=[.;])\s+/)) {
+      const kindDiscriminators = [];
+      for (const kind of HOOK_KINDS) {
+        if (new RegExp(`kind\\s*={2,3}\\s*["']${kind}["']`).test(segment)) kindDiscriminators.push(kind);
+      }
+      if (kindDiscriminators.length === 0) {
+        // A deferral with no kind discriminator ("apply each entry per …")
+        // still covers every kind.
+        if (deferralRe.test(segment)) for (const kind of HOOK_KINDS) covered.add(kind);
+        continue;
+      }
+      if (negationRe.test(segment)) continue;
+      if (deferralRe.test(segment)) {
+        // Deferral naming kinds ("dispatch `kind == "step"` hooks per …").
+        if (!narrowingRe.test(segment)) for (const kind of kindDiscriminators) covered.add(kind);
+        continue;
+      }
+      if (!narrowingRe.test(segment)) for (const kind of kindDiscriminators) covered.add(kind);
+    }
+  }
+  return covered;
+}
+
+/**
+ * Scan every `loop render-hooks <point>` call site in `text` and accumulate,
+ * per point, the union of hook kinds its dispatch regions cover (#3606).
+ *
+ * @param {string} text  Content of a workflow file (or any text).
+ * @returns {Map<string, Set<string>>}  point → covered kinds.
+ */
+function scanWiredKinds(text) {
+  const result = new Map();
+  const siteRe = CALL_SITE_RE;
+  const sites = [];
+  let m;
+  while ((m = siteRe.exec(text)) !== null) sites.push({ point: m[1], start: m.index });
+  const REGION_CAP = 6000;
+  for (let i = 0; i < sites.length; i++) {
+    const regionEnd = i + 1 < sites.length ? sites[i + 1].start : Math.min(text.length, sites[i].start + REGION_CAP);
+    const region = text.slice(sites[i].start, regionEnd);
+    const covered = coveredKindsInRegion(region);
+    if (!result.has(sites[i].point)) result.set(sites[i].point, new Set());
+    for (const kind of covered) result.get(sites[i].point).add(kind);
+  }
+  return result;
+}
+
+/**
+ * Read every host-loop workflow file and return, per point, the union of hook
+ * kinds its call sites' dispatch text covers (#3606).
+ *
+ * @param {string} [repoRoot]  Path to the repository root. Defaults to ROOT.
+ * @returns {Map<string, Set<string>>}
+ */
+function getWiredKinds(repoRoot) {
+  const resolvedRoot = repoRoot !== undefined ? repoRoot : ROOT;
+  const result = new Map();
+  for (const relPath of HOST_LOOP_FILES) {
+    const absPath = path.join(resolvedRoot, relPath);
+    let content;
+    try {
+      content = fs.readFileSync(absPath, 'utf8');
+    } catch (err) {
+      throw new Error('getWiredKinds: cannot read host-loop file ' + absPath + ': ' + err.message);
+    }
+    for (const [point, kinds] of scanWiredKinds(content)) {
+      if (!result.has(point)) result.set(point, new Set());
+      for (const kind of kinds) result.get(point).add(kind);
+    }
+  }
+  return result;
+}
+
 /**
  * Read every host-loop workflow file and return the union of all wired loop points
  * (i.e. points that have a `loop render-hooks <point>` call site).
@@ -497,6 +626,10 @@ module.exports = {
   ROLE_TO_AGENT,
   scanWiredPoints,
   getWiredLoopPoints,
+  coveredKindsInRegion,
+  scanWiredKinds,
+  getWiredKinds,
+  HOOK_KINDS,
 };
 
 // ─── CLI entry point ──────────────────────────────────────────────────────────

package/scripts/gen-scripts-cli-exit.cjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * gen-scripts-cli-exit.cjs — generates scripts/lib/cli-exit.cjs from a fresh
+ * compile of src/cli-exit.cts.
+ *
+ * ADR-3889 Phase 0 (#3904): scripts/lib/cli-exit.cjs used to be a hand-written
+ * fork of gsd-core/bin/lib/cli-exit.cjs (the compiled artifact of
+ * src/cli-exit.cts). The two drifted — only the .cts copy routed a
+ * non-ExitError throw through getJsonErrorMode() to emit a structured
+ * { ok:false, reason, message } envelope. This script makes scripts/lib/cli-exit.cjs
+ * a generated artifact of the SAME source, so the two surfaces cannot diverge
+ * again.
+ *
+ * scripts/ runs straight from the repo checkout and must work on an unbuilt
+ * clone (scripts/check-env.cjs requires this file before any build runs), so
+ * the generated file is compiled to a THROWAWAY outDir rather than read from
+ * gsd-core/bin/lib/ — reading the tracked build output would let a stale build
+ * produce a false green.
+ *
+ * Usage:
+ *   node scripts/gen-scripts-cli-exit.cjs            # same as --write
+ *   node scripts/gen-scripts-cli-exit.cjs --write     # write scripts/lib/cli-exit.cjs
+ *   node scripts/gen-scripts-cli-exit.cjs --check     # exit 1 if committed file is stale
+ */
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const OUTPUT_PATH = path.join(REPO_ROOT, 'scripts', 'lib', 'cli-exit.cjs');
+const COMPILE_TIMEOUT_MS = 60_000;
+
+/** Frozen reason codes so tests assert on structure, not prose. */
+const REASON = Object.freeze({
+  OK: 'ok_generated_sync',
+  DRIFTED: 'fail_generated_drifted',
+  BUILD_FAILED: 'fail_build_failed',
+  MISSING_EMIT: 'fail_missing_emit',
+  USAGE: 'fail_usage',
+});
+
+const USAGE_MESSAGE = [
+  'Usage: node scripts/gen-scripts-cli-exit.cjs [--write|--check]',
+  '  (no flag)  same as --write',
+  '  --write    write scripts/lib/cli-exit.cjs',
+  '  --check    exit 1 if the committed file is stale',
+].join('\n');
+
+const BANNER = [
+  '// GENERATED FILE — DO NOT EDIT BY HAND.',
+  '// Source of truth: src/cli-exit.cts. Regenerate with:',
+  '//   node scripts/gen-scripts-cli-exit.cjs --write',
+  '// Byte-compared by `npm run lint:generated-sync` (#3904, ADR-3889 Phase 0).',
+  '//',
+  '// Why this copy exists: scripts/ runs straight from the repo checkout and must',
+  '// work on an unbuilt clone — 64+ scripts require this file, including',
+  '// check-env.cjs, which runs before any build. gsd-core/bin/lib/cli-exit.cjs is',
+  '// gitignored tsc output and doubles as the build sentinel, so it cannot be',
+  '// required from here. Hence one source, two emitted locations.',
+  '',
+  '',
+].join('\n');
+
+/** Compile the whole project to a throwaway outDir so the work tree is untouched. */
+function compileToTemp() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-scripts-cli-exit-'));
+  try {
+    execFileSync(
+      process.execPath,
+      [
+        path.join(REPO_ROOT, 'node_modules', 'typescript', 'bin', 'tsc'),
+        '-p', path.join(REPO_ROOT, 'tsconfig.build.json'),
+        '--outDir', tmp,
+        // A throwaway outDir must not reuse the in-tree incremental state, or
+        // tsc skips emit for files it believes are already current.
+        '--incremental', 'false',
+        '--tsBuildInfoFile', 'null',
+      ],
+      { cwd: REPO_ROOT, encoding: 'utf8', stdio: 'pipe', timeout: COMPILE_TIMEOUT_MS },
+    );
+    return { ok: true, dir: tmp };
+  } catch (err) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    const detail = [err.stdout, err.stderr].filter(Boolean).join('\n').trim();
+    return { ok: false, detail };
+  }
+}
+
+/**
+ * Compile src/cli-exit.cts to a throwaway outDir and return the expected
+ * generated content (banner + compiled bytes), or a failure descriptor.
+ *
+ * @returns {{ ok: true, content: string } | { ok: false, reason: string, detail?: string }}
+ */
+function buildExpectedContent() {
+  const build = compileToTemp();
+  if (!build.ok) {
+    return { ok: false, reason: REASON.BUILD_FAILED, detail: build.detail };
+  }
+  try {
+    const emitted = path.join(build.dir, 'cli-exit.cjs');
+    if (!fs.existsSync(emitted)) {
+      return { ok: false, reason: REASON.MISSING_EMIT, detail: `no emit produced at ${emitted} from src/cli-exit.cts` };
+    }
+    const compiled = fs.readFileSync(emitted, 'utf8');
+    return { ok: true, content: BANNER + compiled };
+  } finally {
+    fs.rmSync(build.dir, { recursive: true, force: true });
+  }
+}
+
+function doWrite() {
+  const result = buildExpectedContent();
+  if (!result.ok) {
+    console.error(`FAIL gen-scripts-cli-exit: ${result.reason}`);
+    if (result.detail) console.error(result.detail);
+    return 1;
+  }
+  fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+  fs.writeFileSync(OUTPUT_PATH, result.content, 'utf8');
+  console.log(`ok gen-scripts-cli-exit: wrote ${path.relative(REPO_ROOT, OUTPUT_PATH)}`);
+  return 0;
+}
+
+function doCheck() {
+  const result = buildExpectedContent();
+  if (!result.ok) {
+    console.error(`FAIL gen-scripts-cli-exit: ${result.reason}`);
+    if (result.detail) console.error(result.detail);
+    return 1;
+  }
+
+  if (!fs.existsSync(OUTPUT_PATH)) {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.MISSING_EMIT}`);
+    console.error(`  ${path.relative(REPO_ROOT, OUTPUT_PATH)} does not exist. Run:`);
+    console.error('  node scripts/gen-scripts-cli-exit.cjs --write');
+    return 1;
+  }
+
+  const committed = fs.readFileSync(OUTPUT_PATH, 'utf8');
+  if (committed !== result.content) {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.DRIFTED}`);
+    console.error(
+      `  ${path.relative(REPO_ROOT, OUTPUT_PATH)} (${committed.length} bytes) != ` +
+      `compile of src/cli-exit.cts (${result.content.length} bytes)`,
+    );
+    console.error('');
+    console.error('Regenerate with:');
+    console.error('  node scripts/gen-scripts-cli-exit.cjs --write');
+    return 1;
+  }
+
+  console.log(`ok gen-scripts-cli-exit: ${path.relative(REPO_ROOT, OUTPUT_PATH)} matches src/cli-exit.cts`);
+  return 0;
+}
+
+function main() {
+  const flag = process.argv[2];
+  const extra = process.argv[3];
+
+  if (flag !== undefined && flag !== '--write' && flag !== '--check') {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.USAGE}`);
+    console.error(`  unrecognized argument: ${flag}`);
+    console.error(USAGE_MESSAGE);
+    return 1;
+  }
+
+  if (extra !== undefined) {
+    console.error(`FAIL gen-scripts-cli-exit: ${REASON.USAGE}`);
+    console.error(`  unexpected extra argument: ${extra}`);
+    console.error(USAGE_MESSAGE);
+    return 1;
+  }
+
+  if (flag === '--check') return doCheck();
+  return doWrite();
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { REASON, buildExpectedContent, OUTPUT_PATH, BANNER };