@opengsd/gsd-core 1.10.0 → 1.12.0

package/scripts/gen-health-docs.cjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generates the `<error_codes>` and `<repair_actions>` tables in
+ * `gsd-core/workflows/health.md` from `src/health-diagnostic.cts`'s `RULES`
+ * table (Phase 11 follow-up, #3309 "Proposed behavior": "health.md's tables
+ * are generated rather than hand-maintained, closing the 16-vs-30+
+ * documentation gap structurally").
+ *
+ * Sources:
+ *   - The 31 real rules in the compiled `RULES` array
+ *     (`gsd-core/bin/lib/health-diagnostic.cjs`, built from
+ *     `src/health-diagnostic.cts` + `src/health-diagnostic-rules/*.cts`),
+ *     each carrying a static `description`/`repairable` (see
+ *     `src/health-diagnostic-types.cts`'s `Rule` interface).
+ *   - `PRECHECK_CODES` below — E001, E010, I010 — the three diagnostics
+ *     `cmdValidateHealth` (`src/verify.cts`) emits as pre-checks OUTSIDE the
+ *     rule table entirely (ADR-3180 §8.2 rule 4, "no precedence system" —
+ *     see `.gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md`,
+ *     "Two guards that stay OUTSIDE the rule table entirely"). These will
+ *     never appear in `RULES`, so they are a small, static, clearly-labeled
+ *     list merged in here instead.
+ *   - `REMEDY_ACTION_METADATA` below — the Effect/Risk prose for each of the
+ *     6 real repair actions (`REMEDY_ACTION`, excluding `ADVISE`, which never
+ *     acts). Static because the compiled module carries no Effect/Risk text
+ *     of its own — only the action identifier.
+ *
+ * Deliberately EXCLUDED from the generated `<error_codes>` table: `W025`
+ * (the `workflow.use_worktrees`/`dispatch.isolation` check, #2486). It is a
+ * workflow-layer diagnostic emitted directly by this same file's own
+ * `run_health_check` step (a bash block in `health.md` itself), never by
+ * `cmdValidateHealth`/`RULES` — it has no `Rule` entry and is not one of the
+ * three pre-checks above. It stays fully documented in prose at its own step
+ * (`<step name="run_health_check">`), which is the authoritative, more
+ * detailed source `<error_codes>` used to merely summarize; dropping the
+ * redundant table row is not a loss of information, and folding it back in
+ * here would require this generator to parse bash, which it does not do.
+ * Same reasoning for `I002` (stale Windows task-directory cleanup,
+ * `<stale_task_cleanup>` step) — it was never part of the `<error_codes>`
+ * tagged region even before this generator existed.
+ *
+ * Usage:
+ *   node scripts/gen-health-docs.cjs              # print both tables to stdout
+ *   node scripts/gen-health-docs.cjs --write       # rewrite the tagged regions in health.md
+ *   node scripts/gen-health-docs.cjs --check       # exit 1 if either region is stale
+ *   node scripts/gen-health-docs.cjs --write --target <path>  # test-only: target a fixture file
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const HEALTH_MD_REL = 'gsd-core/workflows/health.md';
+const HEALTH_MD_PATH = path.join(ROOT, HEALTH_MD_REL);
+const COMPILED_MODULE_REL = 'gsd-core/bin/lib/health-diagnostic.cjs';
+const COMPILED_MODULE_PATH = path.join(ROOT, COMPILED_MODULE_REL);
+
+const ERROR_CODES_START = '<error_codes>';
+const ERROR_CODES_END = '</error_codes>';
+const REPAIR_ACTIONS_START = '<repair_actions>';
+const REPAIR_ACTIONS_END = '</repair_actions>';
+
+/**
+ * The 3 pre-check diagnostics `cmdValidateHealth` emits OUTSIDE the rule
+ * table (see module header). All three are non-repairable safety rails, not
+ * `.planning/` findings a remedy could act on.
+ */
+const PRECHECK_CODES = [
+  {
+    code: 'E001',
+    severity: 'error',
+    description: '.planning/ directory not found',
+    repairable: false,
+  },
+  {
+    code: 'E010',
+    severity: 'error',
+    description: "CWD resolves to the user's home directory — health check would target the wrong .planning/",
+    repairable: false,
+  },
+  {
+    code: 'I010',
+    severity: 'info',
+    description: 'Resolved CWD reported alongside the E010 home-directory guard',
+    repairable: false,
+  },
+];
+
+/**
+ * Effect/Risk prose per real `REMEDY_ACTION` (everything except `ADVISE`,
+ * which never acts and has no row in `<repair_actions>`). Text for the 5
+ * actions the hand-written table already documented is reused VERBATIM;
+ * `addAiIntegrationPhaseKey` is new — #3309 itself notes it was "live in
+ * code, missing from docs" (mirrors `addNyquistKey`, its structural sibling:
+ * same shape, one config key each).
+ */
+const REMEDY_ACTION_METADATA = new Map([
+  ['createConfig', { effect: 'Create config.json with defaults', risk: 'None' }],
+  ['resetConfig', { effect: 'Delete + recreate config.json', risk: 'Loses custom settings' }],
+  [
+    'regenerateState',
+    {
+      effect: 'Create STATE.md from ROADMAP structure when it is missing',
+      risk: 'Loses session history',
+    },
+  ],
+  [
+    'addNyquistKey',
+    { effect: 'Add workflow.nyquist_validation: true to config.json', risk: 'None — matches existing default' },
+  ],
+  [
+    'addAiIntegrationPhaseKey',
+    { effect: 'Add workflow.ai_integration_phase: true to config.json', risk: 'None — matches existing default' },
+  ],
+  [
+    'backfillMilestones',
+    {
+      effect: 'Synthesize missing MILESTONES.md entries from `.planning/milestones/vX.Y-ROADMAP.md` snapshots',
+      risk: 'None — additive only; triggered by `--backfill` flag',
+    },
+  ],
+]);
+
+/** Order the Effect/Risk table renders in — matches `REMEDY_ACTION`'s own declaration order. */
+const REMEDY_ACTION_ORDER = [
+  'createConfig',
+  'resetConfig',
+  'regenerateState',
+  'addNyquistKey',
+  'addAiIntegrationPhaseKey',
+  'backfillMilestones',
+];
+
+/**
+ * Per-code override for the "Repairable" cell's display text, for codes
+ * whose remedy is conditional on a flag the plain `Yes`/`No` can't express
+ * (mirrors the hand-written table's pre-existing `W018` row: `Yes (--backfill)`).
+ */
+const REPAIRABLE_DISPLAY_OVERRIDE = new Map([['W018', 'Yes (`--backfill`)']]);
+
+const STATIC_NOT_REPAIRABLE_BULLETS = [
+  'PROJECT.md, ROADMAP.md content',
+  'Phase directory renaming',
+  'Orphaned plan cleanup',
+];
+
+const FOOTNOTE_PARAGRAPH =
+  'Note: this table is **generated** — do not hand-edit it. It is produced by ' +
+  '`node scripts/gen-health-docs.cjs --write` from `src/health-diagnostic.cts`\'s `RULES` table ' +
+  '(31 rules as of #3309, each carrying a static `description`/`repairable` on its `Rule` entry — ' +
+  'see `src/health-diagnostic-types.cts`) plus the 3 pre-checks that stay outside the rule table by ' +
+  'design (`E001`, `E010`, `I010` — safety rails in `cmdValidateHealth`, `src/verify.cts`, never ' +
+  '`.planning/` findings). `scripts/lint-health-diagnostic-rule-table.cjs` already enforces the 1:1 ' +
+  'code invariant this table depends on (no duplicate codes; severity is always a `Rule` property, ' +
+  'never set per emit call) — before assigning a new code, add a `Rule` entry under ' +
+  '`src/health-diagnostic-rules/` (its `code` is simply the next free number the lint guard has not ' +
+  'yet seen) and run `node scripts/gen-health-docs.cjs --write` to regenerate this table; ' +
+  '`npm run lint:generated-sync` fails if it drifts. `W025` (the `workflow.use_worktrees`/' +
+  '`dispatch.isolation` check, #2486) is a workflow-layer diagnostic emitted directly by this file\'s ' +
+  'own `run_health_check` step, not by `cmdValidateHealth` — it stays documented in that step, not in ' +
+  'this generated table.';
+
+/**
+ * Load the compiled health-diagnostic module. Throws a clear ExitError (not
+ * a raw MODULE_NOT_FOUND) if `npm run build:lib` has not run — mirrors
+ * `scripts/lint-health-diagnostic-rule-table.cjs`'s `loadCompiledModule`.
+ */
+function loadCompiledModule(compiledPath = COMPILED_MODULE_PATH) {
+  if (!fs.existsSync(compiledPath)) {
+    throw new ExitError(
+      2,
+      `gen-health-docs: compiled artifact not found at ${COMPILED_MODULE_REL}.\n` +
+        'Run `npm run build:lib` first.',
+    );
+  }
+  return require(compiledPath);
+}
+
+/**
+ * Sort order for the `<error_codes>` table: E-codes, then W-codes
+ * numerically, then I-codes — matching the hand-written table's pre-existing
+ * order. NOT insertion order from `RULES` (which is grouped by
+ * subject-area file, not sorted by code).
+ */
+const PREFIX_RANK = { E: 0, W: 1, I: 2 };
+
+function parseCode(code) {
+  const m = code.match(/^([A-Z]+)(\d+)$/);
+  if (!m) throw new Error(`gen-health-docs: unparseable diagnostic code "${code}"`);
+  return { prefix: m[1], number: Number(m[2]) };
+}
+
+function compareCodes(a, b) {
+  const pa = parseCode(a.code);
+  const pb = parseCode(b.code);
+  const rankA = PREFIX_RANK[pa.prefix] ?? 99;
+  const rankB = PREFIX_RANK[pb.prefix] ?? 99;
+  if (rankA !== rankB) return rankA - rankB;
+  return pa.number - pb.number;
+}
+
+/**
+ * Combine the 31 real rules + the 3 static pre-checks into one sorted row
+ * list for the `<error_codes>` table.
+ *
+ * @param {Array<{code: string, severity: string, description: string, repairable: boolean}>} rules
+ */
+function buildErrorCodeRows(rules) {
+  const seen = new Set();
+  const rows = [];
+  for (const entry of [...rules, ...PRECHECK_CODES]) {
+    if (seen.has(entry.code)) {
+      throw new Error(`gen-health-docs: duplicate diagnostic code "${entry.code}" across RULES + PRECHECK_CODES`);
+    }
+    seen.add(entry.code);
+    rows.push(entry);
+  }
+  rows.sort(compareCodes);
+  return rows;
+}
+
+/** Escape a cell's markdown-table-hostile characters (mirrors gen-adr-index.cjs's `cellText`). */
+function cellText(text) {
+  return String(text)
+    .replace(/\\/g, '\\\\')
+    .replace(/\|/g, '\\|')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\r?\n/g, ' ')
+    .trim();
+}
+
+function repairableCell(row) {
+  if (REPAIRABLE_DISPLAY_OVERRIDE.has(row.code)) return REPAIRABLE_DISPLAY_OVERRIDE.get(row.code);
+  return row.repairable ? 'Yes' : 'No';
+}
+
+function renderErrorCodesRegion(rules) {
+  const rows = buildErrorCodeRows(rules);
+  const lines = ['', '| Code | Severity | Description | Repairable |', '|------|----------|-------------|------------|'];
+  for (const row of rows) {
+    lines.push(`| ${row.code} | ${row.severity} | ${cellText(row.description)} | ${repairableCell(row)} |`);
+  }
+  lines.push('', FOOTNOTE_PARAGRAPH, '');
+  return lines.join('\n');
+}
+
+function renderRepairActionsRegion() {
+  const lines = ['', '| Action | Effect | Risk |', '|--------|--------|------|'];
+  for (const action of REMEDY_ACTION_ORDER) {
+    const meta = REMEDY_ACTION_METADATA.get(action);
+    if (!meta) {
+      throw new Error(
+        `gen-health-docs: no Effect/Risk metadata registered for repair action "${action}" — add an entry to REMEDY_ACTION_METADATA.`,
+      );
+    }
+    lines.push(`| ${action} | ${meta.effect} | ${meta.risk} |`);
+  }
+  lines.push('', '**Not repairable (too risky):**');
+  for (const bullet of STATIC_NOT_REPAIRABLE_BULLETS) lines.push(`- ${bullet}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Splice `newInner` between `${startTag}`/`${endTag}` inside `text`. Throws
+ * if either tag is missing, or if the tags appear more than once (this
+ * generator only ever targets the FIRST occurrence pair, and a duplicate
+ * tag anywhere in the file would silently corrupt the splice).
+ */
+function spliceRegion(text, startTag, endTag, newInner) {
+  const startIdx = text.indexOf(startTag);
+  const endIdx = text.indexOf(endTag);
+  if (startIdx === -1 || endIdx === -1) {
+    throw new ExitError(
+      1,
+      `gen-health-docs: ${HEALTH_MD_REL} is missing the ${startTag}/${endTag} tags.`,
+    );
+  }
+  if (text.indexOf(startTag, startIdx + 1) !== -1 || text.indexOf(endTag, endIdx + 1) !== -1) {
+    throw new ExitError(1, `gen-health-docs: ${HEALTH_MD_REL} has more than one ${startTag}/${endTag} pair.`);
+  }
+  const before = text.slice(0, startIdx + startTag.length);
+  const after = text.slice(endIdx);
+  return `${before}${newInner}\n${after}`;
+}
+
+/**
+ * Regenerate `health.md`'s full text from `rules` (the compiled `RULES`
+ * array) and the current on-disk `health.md` content.
+ */
+function regenerateHealthMd(rules, currentText) {
+  let out = spliceRegion(currentText, ERROR_CODES_START, ERROR_CODES_END, renderErrorCodesRegion(rules));
+  out = spliceRegion(out, REPAIR_ACTIONS_START, REPAIR_ACTIONS_END, renderRepairActionsRegion());
+  return out;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {{write: boolean, check: boolean, targetPath: string|null}}
+ */
+function parseArgs(argv) {
+  const opts = { write: false, check: false, targetPath: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--write') opts.write = true;
+    else if (arg === '--check') opts.check = true;
+    else if (arg === '--target') {
+      const value = argv[i + 1];
+      if (value === undefined) throw new ExitError(1, '--target requires a path argument.');
+      opts.targetPath = value;
+      i++;
+    } else {
+      throw new ExitError(1, `unknown flag: ${arg}\nRecognized flags: --write, --check, --target <path>.`);
+    }
+  }
+  return opts;
+}
+
+function main() {
+  const { write, check, targetPath } = parseArgs(process.argv.slice(2));
+  const { RULES } = loadCompiledModule();
+
+  // `--target` overrides the real committed health.md path, exclusively for
+  // test isolation (mirrors gen-section-manifest.cjs's `--manifest-path`
+  // override) — no production caller ever passes it.
+  const resolvedPath = targetPath ? path.resolve(targetPath) : HEALTH_MD_PATH;
+  const displayPath = targetPath ? targetPath : HEALTH_MD_REL;
+
+  const currentText = fs.existsSync(resolvedPath) ? fs.readFileSync(resolvedPath, 'utf8') : null;
+  if (currentText === null) {
+    throw new ExitError(1, `gen-health-docs: ${displayPath} not found.`);
+  }
+
+  const expected = regenerateHealthMd(RULES, currentText);
+
+  if (write) {
+    fs.writeFileSync(resolvedPath, expected, 'utf8');
+    process.stdout.write(
+      `Wrote ${displayPath} — ${RULES.length + PRECHECK_CODES.length} error/warning/info code(s), ` +
+        `${REMEDY_ACTION_ORDER.length} repair action(s).\n`,
+    );
+    return 0;
+  }
+
+  if (check) {
+    if (expected !== currentText) {
+      process.stderr.write(
+        `${displayPath} is stale — its <error_codes>/<repair_actions> tables do not match ` +
+          "src/health-diagnostic.cts's RULES table.\nRun:\n  node scripts/gen-health-docs.cjs --write\n\n",
+      );
+      throw new ExitError(1);
+    }
+    process.stdout.write(
+      `${displayPath} is up to date (${RULES.length + PRECHECK_CODES.length} codes, ${REMEDY_ACTION_ORDER.length} repair actions).\n`,
+    );
+    return 0;
+  }
+
+  process.stdout.write(renderErrorCodesRegion(RULES) + '\n\n' + renderRepairActionsRegion() + '\n');
+  return 0;
+}
+
+// Guarded: requiring this module (the test suite imports the pure render
+// functions directly) must not also run the generator as a side effect.
+if (require.main === module) runMain(main);
+
+module.exports = {
+  loadCompiledModule,
+  buildErrorCodeRows,
+  renderErrorCodesRegion,
+  renderRepairActionsRegion,
+  regenerateHealthMd,
+  spliceRegion,
+  compareCodes,
+  parseCode,
+  PRECHECK_CODES,
+  REMEDY_ACTION_METADATA,
+  REMEDY_ACTION_ORDER,
+  REPAIRABLE_DISPLAY_OVERRIDE,
+  HEALTH_MD_PATH,
+  COMPILED_MODULE_PATH,
+  ERROR_CODES_START,
+  ERROR_CODES_END,
+  REPAIR_ACTIONS_START,
+  REPAIR_ACTIONS_END,
+};

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