@bongos/core 1.21.175 → 1.21.177

package/tests/api_artifacts.mjs

@@ -0,0 +1,214 @@
+// tests/api_artifacts.mjs
+//
+// task 1004866 — the generated API spec, reference and typed client are NOT committed.
+// They used to be, and every ship regenerated and re-committed them (~175 "auto-regenerate
+// typed client" commits in four months), with a merge driver just for their conflicts.
+// Now they are gitignored and every consumer builds them from the route files:
+//   • package-core.js generates them into every core tarball (provisioning vendors it),
+//     and refuses to build if generation fails;
+//   • serve-internal.js generates /docs/openapi.json and /lib/bongos-client.js in-process
+//     when the files are absent (tests/docs_openapi_route.mjs, tests/client_bundle_route.mjs);
+//   • tests build them in memory (scripts/bongos/api-artifacts.js).
+//
+// This file pins the pieces that make that hold together:
+//   1. the eight paths are gitignored and untracked, and .gitignore lists exactly them;
+//   2. buildApiArtifacts() yields all eight from the routes, valid and non-empty;
+//   3. ensureApiArtifacts() writes a fresh root, then is a no-op;
+//   4. ship no longer regenerates or commits them;
+//   5. package-core's generation step really runs the generators of the tree it packs and
+//      FAILS CLOSED (a generator error or a missing output aborts the build).
+//
+// Run:  node --test tests/api_artifacts.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { API_ARTIFACT_PATHS, buildApiArtifacts, ensureApiArtifacts } = require('../scripts/bongos/api-artifacts.js');
+
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+
+// ---- 1. not committed -------------------------------------------------------
+
+test('.gitignore lists exactly the eight generated paths', () => {
+  const lines = read('.gitignore').split('\n').map((l) => l.trim());
+  for (const rel of API_ARTIFACT_PATHS) {
+    assert.ok(lines.includes(`/${rel}`), `.gitignore must list /${rel}`);
+  }
+  const listed = lines.filter((l) => /^\/(docs\/api\/|docs\/api-reference\.md|clients\/bongos-client\/)/.test(l));
+  assert.deepEqual(listed.map((l) => l.slice(1)).sort(), [...API_ARTIFACT_PATHS].sort(),
+    'the .gitignore block and API_ARTIFACT_PATHS must be the same set');
+  assert.ok(!lines.filter((l) => !l.startsWith('#')).some((l) => l.includes('bongos-client/examples') || l === '/clients/bongos-client/' || l === '/clients/'), 'the hand-written client example stays committed');
+});
+
+test('git ignores every one of them, and none is tracked', (t) => {
+  const probe = spawnSync('git', ['-C', ROOT, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
+  if (probe.status !== 0) { t.skip('not a git checkout'); return; }
+  const ignored = spawnSync('git', ['-C', ROOT, 'check-ignore', '--no-index', ...API_ARTIFACT_PATHS], { encoding: 'utf8' });
+  assert.deepEqual(ignored.stdout.trim().split('\n').sort(), [...API_ARTIFACT_PATHS].sort());
+  const tracked = spawnSync('git', ['-C', ROOT, 'ls-files', '--', ...API_ARTIFACT_PATHS], { encoding: 'utf8' });
+  assert.equal(tracked.stdout.trim(), '', `still tracked: ${tracked.stdout.trim()}`);
+  const example = spawnSync('git', ['-C', ROOT, 'ls-files', '--', 'clients/bongos-client/examples/hello-world.mjs'], { encoding: 'utf8' });
+  assert.equal(example.stdout.trim(), 'clients/bongos-client/examples/hello-world.mjs', 'the hand-written example stays tracked');
+});
+
+// ---- 2/3. built from the routes ---------------------------------------------
+
+test('buildApiArtifacts yields all eight, non-empty, with a valid spec and a loadable client', () => {
+  const a = buildApiArtifacts();
+  assert.deepEqual(Object.keys(a).sort(), [...API_ARTIFACT_PATHS].sort());
+  const spec = JSON.parse(a['docs/api/openapi.json']);
+  assert.equal(spec.openapi, '3.1.0');
+  assert.ok(Object.keys(spec.paths).length > 100, 'the spec documents the real route surface');
+  assert.match(a['docs/api-reference.md'], /GENERATED by scripts\/bongos\/gen-api-docs\.js/);
+  const g = {};
+  new Function('globalThis', 'self', a['clients/bongos-client/bongos-client.global.js']).call(g, g, g);
+  assert.equal(typeof g.BongosClient.createClient, 'function');
+  assert.equal(JSON.parse(a['clients/bongos-client/package.json']).private, true);
+});
+
+test('ensureApiArtifacts writes a fresh root, then has nothing to do', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'api-artifacts-'));
+  try {
+    const first = ensureApiArtifacts({ root });
+    assert.deepEqual([...first].sort(), [...API_ARTIFACT_PATHS].sort(), 'every file written on a fresh root');
+    const a = buildApiArtifacts();
+    for (const rel of API_ARTIFACT_PATHS) assert.equal(fs.readFileSync(path.join(root, rel), 'utf8'), a[rel]);
+    assert.deepEqual(ensureApiArtifacts({ root }), [], 'a current root is left alone');
+    fs.writeFileSync(path.join(root, 'docs/api-reference.md'), 'stale\n');
+    assert.deepEqual(ensureApiArtifacts({ root }), ['docs/api-reference.md'], 'a stale file is rewritten');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ---- 4. ship no longer commits them -----------------------------------------
+
+test('ship regenerates and commits only the committed stub, never an ignored artifact', () => {
+  const regen = require('../scripts/bongos/ship-regen.js');
+  assert.equal(regen.regenerateApiClient, undefined, 'the typed-client regen+commit step is gone');
+  assert.equal(regen.API_DOCS_COMMITTED, 'docs/routes-permissions.md');
+  const src = read('scripts/bongos/ship-regen.js');
+  // `git add <ignored path>` aborts the whole add, so naming one would also drop the stub.
+  for (const rel of API_ARTIFACT_PATHS) {
+    assert.ok(!new RegExp(`git (add|status)[^\\n]*${rel.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}`).test(src),
+      `ship-regen must not git add/status ${rel}`);
+  }
+  assert.doesNotMatch(src, /git add clients\/bongos-client|API_CLIENT_PATHSPEC/);
+  const merge = read('scripts/bongos/ship-merge.js');
+  assert.doesNotMatch(merge, /regenerateApiClient/, 'ship-merge must not call the removed client regen');
+});
+
+// ---- 5. package-core generates them, fail-closed ----------------------------
+
+const PC = require('../scripts/bongos/package-core.js');
+
+test('package-core generation runs the packed tree\'s generators and returns all eight', () => {
+  const calls = [];
+  const run = (cmd, args, opts) => {
+    calls.push({ script: path.relative(opts.cwd, args[0]).split(path.sep).join('/'), cwd: opts.cwd, env: opts.env });
+    // Stand in for the generators: write what they would write, into the tree they run in.
+    const a = buildApiArtifacts();
+    const mine = calls.length === 1 ? API_ARTIFACT_PATHS.filter((p) => p.startsWith('docs/')) : API_ARTIFACT_PATHS.filter((p) => p.startsWith('clients/'));
+    for (const rel of mine) { fs.mkdirSync(path.dirname(path.join(opts.cwd, rel)), { recursive: true }); fs.writeFileSync(path.join(opts.cwd, rel), a[rel]); }
+    return { status: 0 };
+  };
+  const out = PC.generateApiArtifacts([{ path: 'src/x.js', buf: Buffer.from('1') }], { run, env: { FOO: '1', BONGOS_INSTANCE_ROOT: '/elsewhere' } });
+  assert.deepEqual(calls.map((c) => c.script), ['scripts/bongos/gen-api-docs.js', 'scripts/bongos/gen-api-client.js'],
+    'docs first, then the client FROM that spec — both out of the packed tree');
+  assert.ok(!fs.existsSync(calls[0].cwd), 'the throwaway tree is removed afterwards');
+  assert.equal(calls[0].env.BONGOS_INSTANCE_ROOT, undefined, 'an instance-root pointer must not redirect the output');
+  assert.equal(calls[0].env.FOO, '1');
+  assert.deepEqual(out.map((o) => o.path), [...API_ARTIFACT_PATHS]);
+  assert.ok(out.every((o) => o.buf.length > 0));
+});
+
+test('package-core generation FAILS CLOSED on a generator error or a missing output', () => {
+  assert.throws(
+    () => PC.generateApiArtifacts([], { run: () => ({ status: 1, stderr: 'spec is NOT valid OpenAPI 3.1' }) }),
+    /gen-api-docs\.js failed \(exit 1\).*NOT valid/,
+  );
+  assert.throws(
+    () => PC.generateApiArtifacts([], { run: () => ({ error: new Error('ENOENT') }) }),
+    /gen-api-docs\.js failed \(ENOENT\)/,
+  );
+  // Both generators "succeed" but write nothing: a hole must not be packed silently.
+  assert.throws(() => PC.generateApiArtifacts([], { run: () => ({ status: 0 }) }), /generation left no docs\/api\/openapi\.json/);
+});
+
+test('package-core main refuses to build when generation fails, before anything is staged', () => {
+  const src = read('scripts/bongos/package-core.js');
+  const main = src.slice(src.indexOf('function main()'));
+  const gen = main.indexOf('generateApiArtifacts(sources)');
+  assert.ok(gen > 0, 'main() generates the API artifacts');
+  assert.ok(gen < main.indexOf('for (const e of publishable)'), 'before the per-file processing loop that stages the tarball');
+  assert.match(main, /generating the API spec \+ client FAILED[\s\S]{0,200}process\.exit\(1\)/, 'and exits non-zero on failure');
+  assert.match(main, /!API_GENERATED\.has\(e\.path\)/, 'an on-hand (possibly stale) copy is never packed in place of the generated one');
+});
+
+test('the generated files pass the SAME redaction + leak gates as every packed file', () => {
+  // They join `publishable`; the one per-file loop over `publishable` runs processCoreFile
+  // (doc redaction + the fail-closed no-leak gate) and stages the result; the post-build
+  // scanArtifactForLeaks runs over that same `staged` list. Pin each link of that chain.
+  const src = read('scripts/bongos/package-core.js');
+  const main = src.slice(src.indexOf('function main()'));
+  const push = main.indexOf("publishable.push({ path: g.path, type: 'blob', mode: '100644', buf: g.buf })");
+  const loop = main.indexOf('for (const e of publishable) {');
+  assert.ok(push > 0 && loop > push, 'generated entries are added to publishable before the per-file loop');
+  const body = main.slice(loop, main.indexOf('\n  }\n', loop));
+  assert.match(body, /readBlob\(e\)/, 'the loop reads each entry through readBlob, which returns a generated buf');
+  assert.match(body, /processCoreFile\(\{ pathRel: e\.path, raw,/, 'every entry goes through processCoreFile (redaction + leak gate)');
+  assert.match(body, /staged\.push\(/, 'and is staged from that processed buffer');
+  assert.match(main, /const scanFiles = staged\.map\(/, 'the post-build leak scan covers every staged file');
+  assert.match(src, /const readBlob = \(e\) => \(e\.buf \? e\.buf :/, 'readBlob hands back a generated entry\'s bytes');
+  // ...and a generated doc really is redacted/gated like a committed one.
+  const r = PC.processCoreFile({ pathRel: 'docs/api-reference.md', raw: Buffer.from('# API\n'), rules: [], sensitiveLiterals: [], envSecrets: [], knownDocNames: new Set() });
+  assert.equal(r.kind, 'doc', 'api-reference.md is classified as a doc, so it is redacted + leak-gated');
+});
+
+test('the real generators run from the packed source files alone (no node_modules, no docs)', () => {
+  // The provisioning-critical proof: write only src/, modules/, scripts/bongos/ and
+  // package.json — what a tarball build packs — and run the real generators there.
+  const sources = [];
+  const walk = (rel) => {
+    for (const d of fs.readdirSync(path.join(ROOT, rel), { withFileTypes: true })) {
+      const r = `${rel}/${d.name}`;
+      if (d.isDirectory()) { if (d.name !== 'node_modules') walk(r); } else if (d.isFile() && /\.(js|json|cjs|mjs)$/.test(d.name)) sources.push({ path: r, buf: fs.readFileSync(path.join(ROOT, r)) });
+    }
+  };
+  for (const dir of ['src', 'modules', 'scripts/bongos']) walk(dir);
+  sources.push({ path: 'package.json', buf: fs.readFileSync(path.join(ROOT, 'package.json')) });
+  const out = PC.generateApiArtifacts(sources);
+  const a = buildApiArtifacts();
+  for (const o of out) assert.equal(o.buf.toString('utf8'), a[o.path], `${o.path} from the packed tree must equal the in-memory build`);
+});
+
+// ---- 6. the CLI's own client on a fresh clone -------------------------------
+
+test('the CLI generates its typed client when a fresh clone has none, and only then', () => {
+  const { ensureCliClientFile } = require('../scripts/bongos/cli-lib.js');
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-client-'));
+  try {
+    assert.equal(ensureCliClientFile({ root }), true, 'missing → generated');
+    assert.equal(fs.readFileSync(path.join(root, 'clients/bongos-client/index.mjs'), 'utf8'),
+      buildApiArtifacts()['clients/bongos-client/index.mjs']);
+    let called = 0;
+    assert.equal(ensureCliClientFile({ root, ensure: () => { called++; } }), false, 'present → left alone');
+    assert.equal(called, 0, 'an installed (possibly read-only) core is never rewritten');
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-client-'));
+    const err = console.error; console.error = () => {};
+    try {
+      assert.equal(ensureCliClientFile({ root: empty, ensure: () => { throw new Error('boom'); } }), false,
+        'a generation failure is reported, not thrown — the import then names the missing file');
+    } finally { console.error = err; fs.rmSync(empty, { recursive: true, force: true }); }
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/tests/api_cli_flags.mjs

@@ -1,7 +1,7 @@
 // tests/api_cli_flags.mjs
 //
-// Unit test for two PURE helpers exported from scripts/gds/cli-lib.js in support
-// of scripts/gds/api.js's CLI flags (task 1002475):
+// Unit test for two PURE helpers exported from scripts/bongos/cli-lib.js in support
+// of scripts/bongos/api.js's CLI flags (task 1002475):
 //   - stripBom(s)      → drop a leading UTF-8 BOM (U+FEFF); pass clean input through
 //   - resolveQuiet(args, env) → true when --quiet or GDS_QUIET should suppress
 //     api.js's stderr status banner
@@ -14,7 +14,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const cli = require('../scripts/gds/cli-lib.js');
+const cli = require('../scripts/bongos/cli-lib.js');
 
 let passed = 0;
 let failed = 0;

package/tests/api_client.mjs

@@ -3,7 +3,9 @@
 // Guard for the generated typed client (task 1995, R08 / ADR 0118). Verifies the
 // GENERATOR's output behaves: grouped methods, path-param substitution, query +
 // body wiring, Bearer auth, and the ApiError envelope on non-2xx. DB-free — a fake
-// fetch captures the request. Also asserts the committed client is FRESH.
+// fetch captures the request. The client is gitignored (task 1004866), so this tests a
+// client generated FRESH from the routes into a temp dir — never a stale on-disk copy —
+// and proves the CLI writes it on a fresh clone (no docs/api/openapi.json present).
 //
 // Run:  node tests/api_client.mjs
 
@@ -14,12 +16,23 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { createClient, ApiError, API_VERSION, DEFAULT_BASE_URL } from '../clients/bongos-client/index.mjs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const { sameContent } = require(path.join(ROOT, 'scripts', 'gds', 'gen-freshness.js'));
+const { API_ARTIFACT_PATHS, buildApiArtifacts } = require(path.join(ROOT, 'scripts', 'bongos', 'api-artifacts.js'));
+
+// Generate the eight artifacts from the routes into a throwaway root and load the client
+// from there (task 1004866).
+const ARTIFACTS = buildApiArtifacts();
+const GEN_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'api-client-test-'));
+for (const rel of API_ARTIFACT_PATHS) {
+  fs.mkdirSync(path.dirname(path.join(GEN_ROOT, rel)), { recursive: true });
+  fs.writeFileSync(path.join(GEN_ROOT, rel), ARTIFACTS[rel]);
+}
+process.on('exit', () => { try { fs.rmSync(GEN_ROOT, { recursive: true, force: true }); } catch { /* best effort */ } });
+const CLIENT_DIR = path.join(GEN_ROOT, 'clients', 'bongos-client');
+const { createClient, ApiError, API_VERSION, DEFAULT_BASE_URL } = await import(pathToFileURL(path.join(CLIENT_DIR, 'index.mjs')).href);
 
 function fakeFetch(recorder, response = { ok: true, status: 200, body: { ok: true } }) {
   return async (url, init) => {
@@ -117,7 +130,7 @@ test('every method the README example names actually exists on the client', () =
   // Guards against the generator's usage block drifting from the operationId-derived
   // namer (it once showed getTask/createTask, which are never emitted).
   const api = createClient({ baseUrl: 'https://x.test', fetch: async () => {} });
-  const md = fs.readFileSync(path.join(ROOT, 'clients/bongos-client/README.md'), 'utf8');
+  const md = fs.readFileSync(path.join(CLIENT_DIR, 'README.md'), 'utf8');
   const re = /api\.([A-Za-z0-9]+)\.([A-Za-z0-9]+)\(/g;
   let m, count = 0;
   while ((m = re.exec(md))) {
@@ -137,22 +150,19 @@ test('baseUrl:"" is honored (absolute-path passthrough for the hall fetch wrappe
   assert.deepEqual(res, { status: 200, ok: true, data: { x: 1 } });
 });
 
-// The CI-gate twin of `gen-api-client.js --check`, and it carried the SAME defect
-// (task 1003844): a byte-wise assert.equal against a CRLF working copy failed on
-// every Windows checkout, forever — index.d.ts and README.md have no eol pin, so
-// core.autocrlf hands them back CRLF while the generator renders LF. Compare with
-// sameContent for the same reason gen-freshness.js exists; a real content change
-// still fails, which tests/gen_freshness.mjs pins.
-test('committed client is fresh (regenerate with gen-api-client.js if this fails)', () => {
-  const gen = require('../scripts/gds/gen-api-client.js');
-  const { files } = gen.build();
+// task 1004866: the client is not committed, so there is no "committed copy is fresh"
+// check. What must hold instead: the generator's own build() and the api-artifacts set
+// agree file for file, so whatever consumer builds the client gets the same bytes.
+test('the api-artifacts set carries exactly what gen-api-client builds', () => {
+  const gen = require('../scripts/bongos/gen-api-client.js');
+  const { files } = gen.build(require('../scripts/bongos/gen-api-docs.js').build().spec);
   for (const [name, content] of Object.entries(files)) {
-    const onDisk = fs.readFileSync(path.join(ROOT, 'clients/bongos-client', name), 'utf8');
-    assert.ok(
-      sameContent(onDisk, content),
-      `clients/bongos-client/${name} is STALE — run node scripts/gds/gen-api-client.js`,
-    );
+    assert.equal(ARTIFACTS[`clients/bongos-client/${name}`], content, `${name} differs between the two builds`);
   }
+  assert.deepEqual(
+    API_ARTIFACT_PATHS.filter((p) => p.startsWith('clients/bongos-client/')).map((p) => p.slice('clients/bongos-client/'.length)).sort(),
+    Object.keys(files).sort(),
+    'API_ARTIFACT_PATHS must list every file gen-api-client writes — an unlisted one would be committed again');
 });
 
 // The .d.ts carries FIELD-LEVEL request types generated from the enriched spec
@@ -161,7 +171,7 @@ test('committed client is fresh (regenerate with gen-api-client.js if this fails
 // `<OperationId>Response` interface when its res.json({…}) shape is statically
 // provable, and the `ApiResponse` (any) alias only for routes where it isn't.
 test('generated .d.ts emits field-level request types (task 2050)', () => {
-  const dts = fs.readFileSync(path.join(ROOT, 'clients/bongos-client/index.d.ts'), 'utf8');
+  const dts = fs.readFileSync(path.join(CLIENT_DIR, 'index.d.ts'), 'utf8');
   // shared base types generated from components.schemas
   assert.match(dts, /export type StringifiableId = number \| string;/, 'StringifiableId union emitted');
   assert.match(dts, /export interface ErrorEnvelope \{ error: ApiErrorObject \}/, 'ErrorEnvelope references ApiErrorObject');
@@ -180,7 +190,7 @@ test('generated .d.ts emits field-level request types (task 2050)', () => {
 // safe), the ADR-0119 pageMeta() `page` block → the shared PageInfo, and a route
 // whose shape can't be proven degrades to the `ApiResponse` alias (never mistyped).
 test('generated .d.ts types success responses (task 2061)', () => {
-  const dts = fs.readFileSync(path.join(ROOT, 'clients/bongos-client/index.d.ts'), 'utf8');
+  const dts = fs.readFileSync(path.join(CLIENT_DIR, 'index.d.ts'), 'utf8');
   // the shared pagination block, wired into paginated list responses
   assert.match(dts, /export interface PageInfo \{ limit: number; offset: number; total\?: number \}/, 'PageInfo emitted');
   assert.match(dts, /export interface Get\w*Response \{ [^}]*page: PageInfo\b/, 'a list response wires page: PageInfo');
@@ -211,7 +221,7 @@ test('generated .d.ts types success responses (task 2061)', () => {
 // 1996 / R09). CommonJS callers (require) and classic <script> web pages consume them, so
 // guard that they load and shape requests IDENTICALLY to the ESM build.
 test('CJS build behaves identically to the ESM build', async () => {
-  const cjs = require('../clients/bongos-client/index.cjs');
+  const cjs = require(path.join(CLIENT_DIR, 'index.cjs'));
   assert.equal(typeof cjs.createClient, 'function');
   assert.equal(typeof cjs, 'function', 'module.exports is createClient itself');
   assert.equal(cjs.API_VERSION, API_VERSION);
@@ -227,7 +237,7 @@ test('CJS build behaves identically to the ESM build', async () => {
 });
 
 test('browser-global build exposes window.BongosClient and shapes requests identically', async () => {
-  const src = fs.readFileSync(path.join(ROOT, 'clients/bongos-client/bongos-client.global.js'), 'utf8');
+  const src = fs.readFileSync(path.join(CLIENT_DIR, 'bongos-client.global.js'), 'utf8');
   const g = {};
   // The IIFE resolves its target as globalThis ?? self ?? this — call with `g` as
   // all three so it attaches BongosClient to our sandbox rather than the real global.
@@ -243,47 +253,39 @@ test('browser-global build exposes window.BongosClient and shapes requests ident
   assert.equal(rec.init.body, JSON.stringify({ a: 1 }));
 });
 
-// --- the --check gate itself (task 1003844) ---------------------------------
+// --- the CLI on a FRESH clone (task 1004866) ---------------------------------
 //
-// The assertions above compare the client this checkout HAS, so they can only ever
-// see the eol convention this checkout happens to use. The bug lived in the other
-// direction: a Windows clone whose committed client is already correct was told it
-// was STALE, forever. So drive the real CLI against a throwaway docs root where we
-// control the line endings, and pin BOTH halves — the eol-only case must pass, and
-// a genuine edit must still fail, which is what stops an over-broad "fix" (the same
-// pairing tests/gen_freshness.mjs makes for the helper).
+// A fresh clone has no docs/api/openapi.json (it is gitignored). The CLI must still write
+// the whole client — building the spec from the routes in memory — and --check must prove
+// generation succeeds without writing anything.
 function runGen(root, args = []) {
-  return spawnSync(process.execPath, [path.join(ROOT, 'scripts/gds/gen-api-client.js'), ...args], {
+  return spawnSync(process.execPath, [path.join(ROOT, 'scripts/bongos/gen-api-client.js'), ...args], {
     encoding: 'utf8',
     env: { ...process.env, BONGOS_INSTANCE_ROOT: root },
   });
 }
 
-test('--check reads a CRLF working copy as fresh, and a real edit as stale (task 1003844)', () => {
+test('the CLI writes the full client on a fresh clone with no spec on disk', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gen-api-client-'));
   try {
-    fs.mkdirSync(path.join(root, 'docs', 'api'), { recursive: true });
-    fs.copyFileSync(path.join(ROOT, 'docs/api/openapi.json'), path.join(root, 'docs/api/openapi.json'));
-
+    assert.equal(fs.existsSync(path.join(root, 'docs/api/openapi.json')), false);
     const wrote = runGen(root);
-    assert.equal(wrote.status, 0, `generator failed: ${wrote.stderr}`);
-
-    // What a core.autocrlf=true checkout hands back for the two files with no eol
-    // pin. Nothing about the CONTENT changed, so --check must stay quiet.
-    for (const name of ['index.d.ts', 'README.md']) {
-      const f = path.join(root, 'clients/bongos-client', name);
-      fs.writeFileSync(f, fs.readFileSync(f, 'utf8').replace(/\n/g, '\r\n'));
+    assert.equal(wrote.status, 0, `generator failed with no spec on disk: ${wrote.stderr}`);
+    for (const rel of API_ARTIFACT_PATHS.filter((p) => p.startsWith('clients/'))) {
+      assert.equal(fs.readFileSync(path.join(root, rel), 'utf8'), ARTIFACTS[rel], `${rel} must equal the routes build`);
     }
-    const fresh = runGen(root, ['--check']);
-    assert.equal(fresh.status, 0, `CRLF must not read as STALE — this is the bug: ${fresh.stderr}`);
-    assert.match(fresh.stdout, /is fresh/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
 
-    // ...and the gate is still a gate.
-    const target = path.join(root, 'clients/bongos-client/index.mjs');
-    fs.writeFileSync(target, `${fs.readFileSync(target, 'utf8')}\nexport const SMUGGLED = 1;\n`);
-    const stale = runGen(root, ['--check']);
-    assert.equal(stale.status, 2, 'a real content change must still exit 2');
-    assert.match(stale.stderr, /STALE/);
+test('--check proves generation from the routes and writes nothing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gen-api-client-'));
+  try {
+    const r = runGen(root, ['--check']);
+    assert.equal(r.status, 0, `--check failed: ${r.stderr}`);
+    assert.match(r.stdout, /generation OK \(\d+ operations from the routes\)/);
+    assert.equal(fs.existsSync(path.join(root, 'clients')), false, '--check must not write the client');
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
@@ -307,7 +309,7 @@ test('--check reads a CRLF working copy as fresh, and a real edit as stale (task
 // is the part this repo actually controls.
 test('the generated client manifest is private, so it cannot be republished', () => {
   const pkg = JSON.parse(fs.readFileSync(
-    path.join(ROOT, 'clients', 'bongos-client', 'package.json'), 'utf8'));
+    path.join(CLIENT_DIR, 'package.json'), 'utf8'));
   assert.equal(pkg.private, true,
     'clients/bongos-client/package.json lost `private: true` — npm publish in that directory '
     + 'would recreate @bongos/client, the package the owner removed from the registry.');
@@ -320,7 +322,7 @@ test('the generated client manifest is private, so it cannot be republished', ()
 
 test('the GENERATOR emits it, not just the committed file', () => {
   // Fixing only the output is a fix that the next regeneration undoes.
-  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'gen-api-client.js'), 'utf8');
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'bongos', 'gen-api-client.js'), 'utf8');
   assert.match(src, /private:\s*true/,
     'gen-api-client.js no longer emits `private: true` — the next regeneration would '
     + 'make clients/bongos-client publishable again.');

package/tests/api_docs.mjs

@@ -1,7 +1,7 @@
 // tests/api_docs.mjs
 //
 // Task 1918 (BONGOS-V1) — the generated OpenAPI 3.1 contract + the pure helpers of
-// scripts/gds/gen-api-docs.js. DB-free: the generator only reads the route source.
+// scripts/bongos/gen-api-docs.js. DB-free: the generator only reads the route source.
 //
 // Pins:
 //   1. build() produces a STRUCTURALLY VALID OpenAPI 3.1 doc (built-in validator).
@@ -9,18 +9,21 @@
 //      the docs can't silently document more/fewer routes than the server mounts.
 //   3. the pure extractors (pathParams, commentBlockAbove, topLevelKeys, captureBalanced)
 //      behave, incl. the inline-comment case that once leaked a nested `min` key.
-//   4. the committed docs/api/openapi.json is FRESH (matches a fresh build).
+//   4. `gen-api-docs --check` proves generation, never compares the gitignored spec
+//      (task 1004866) — it passes on a fresh clone with no spec on disk.
 //
 // Run:  node tests/api_docs.mjs
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
-const gen = require('../scripts/gds/gen-api-docs.js');
+const gen = require('../scripts/bongos/gen-api-docs.js');
 const { checkRouteRanks } = require('../src/bongos/route-rank-check.js');
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -99,7 +102,8 @@ t('routeForDisplay: the reader sees /inbox/:id, never the regex', () => {
 });
 
 t('the published spec contains no leaked param constraint', () => {
-  const spec = JSON.parse(fs.readFileSync(path.join(ROOT, 'docs', 'api', 'openapi.json'), 'utf8'));
+  // The spec is gitignored (task 1004866); what ships is what build() produces.
+  const spec = gen.build().spec;
   const leaked = Object.keys(spec.paths || {}).filter((p) => p.includes('(') || p.includes('\\'));
   assert.deepEqual(leaked, [], `path templates must carry no regex: ${leaked.join(', ')}`);
 });
@@ -144,11 +148,28 @@ t('api-prefix: /api/bongos/v1 versioned, /api/bongos + /api/gds PERMANENT aliase
   assert.equal(spec.servers[1].url, API_PREFIX, 'unversioned alias is the second server');
 });
 
-// ---- 5. committed spec is fresh --------------------------------------------
-t('committed docs/api/openapi.json matches a fresh build (run gen-api-docs.js if this fails)', () => {
-  const onDisk = fs.readFileSync(path.join(ROOT, 'docs/api/openapi.json'), 'utf8');
-  const fresh = JSON.stringify(spec, null, 2) + '\n';
-  assert.equal(onDisk, fresh, 'docs/api/openapi.json is STALE — run `node scripts/gds/gen-api-docs.js`');
+// ---- 5. --check on a fresh clone (task 1004866) -----------------------------
+// docs/api/openapi.json + docs/api-reference.md are gitignored, so --check must pass with
+// neither on disk (it used to call a missing file STALE) and must write nothing; only the
+// committed pointer stub is compared.
+t('--check passes on a fresh clone with no spec on disk, and writes nothing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gen-api-docs-'));
+  try {
+    fs.mkdirSync(path.join(root, 'docs'), { recursive: true });
+    const stub = gen.build().files.find((f) => f.rel === 'docs/routes-permissions.md');
+    fs.writeFileSync(path.join(root, 'docs/routes-permissions.md'), stub.content);
+    const run = (args) => spawnSync(process.execPath, [path.join(ROOT, 'scripts/bongos/gen-api-docs.js'), ...args],
+      { encoding: 'utf8', env: { ...process.env, BONGOS_INSTANCE_ROOT: root } });
+    const r = run(['--check']);
+    assert.equal(r.status, 0, `--check failed on a fresh clone: ${r.stderr}`);
+    assert.match(r.stdout, /generation OK/);
+    assert.equal(fs.existsSync(path.join(root, 'docs/api/openapi.json')), false, '--check must not write the spec');
+    // ...and the committed stub is still a gate.
+    fs.writeFileSync(path.join(root, 'docs/routes-permissions.md'), 'hand edit\n');
+    assert.equal(run(['--check']).status, 2, 'a drifted committed stub must still exit 2');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
 });
 
 // ---- 6. FIELD-LEVEL enrichment (task 2050 / ADR 0118) ----------------------

package/tests/api_error_envelope_buildcheck.mjs

@@ -10,7 +10,7 @@ import { strict as assert } from 'node:assert';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
-const F = require('../scripts/gds/fitness.js');
+const F = require('../scripts/bongos/fitness.js');
 
 test('detector flags hand-rolled flat errors', () => {
   assert.equal(F.countFlatErrors(`res.status(404).json({ error: 'task_not_found' })`), 1);

package/tests/api_msys_path_repair.mjs

@@ -23,7 +23,7 @@ import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
-const { repairMsysMangledPath } = require('../scripts/gds/cli-lib.js');
+const { repairMsysMangledPath } = require('../scripts/bongos/cli-lib.js');
 
 let passed = 0;
 let failed = 0;
@@ -93,7 +93,7 @@ test('empty/undefined input passes through', () => {
 // correct is worthless if api.js stops applying it to its positional path arg —
 // that exact mutation survived every behavioural test here.
 test('api.js applies the repair to process.argv[3] (static)', () => {
-  const src = fs.readFileSync(fileURLToPath(new URL('../scripts/gds/api.js', import.meta.url)), 'utf8');
+  const src = fs.readFileSync(fileURLToPath(new URL('../scripts/bongos/api.js', import.meta.url)), 'utf8');
   if (!/repairMsysMangledPath\(\s*process\.argv\[3\]\s*\)/.test(src)) {
     throw new Error('api.js no longer wraps process.argv[3] in repairMsysMangledPath(...)');
   }

package/tests/architect.mjs

@@ -11,7 +11,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const architect = require('../scripts/gds/architect-audit.js');
+const architect = require('../scripts/bongos/architect-audit.js');
 
 let passed = 0;
 let failed = 0;

package/tests/art_stage.mjs

@@ -1,6 +1,6 @@
 // tests/art_stage.mjs
 //
-// Hermetic unit coverage for scripts/gds/art-stage.js (#1067) — rebuild the atlas
+// Hermetic unit coverage for scripts/bongos/art-stage.js (#1067) — rebuild the atlas
 // + surface it on the builder's sandbox in one step. All deps (execFileSync, fs,
 // fetchImpl, resolvePreviewContext, log) are injected; NO real pipeline run, NO
 // network, NO systemd, NO real /workspace.
@@ -15,7 +15,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const art = requireHostModule(require, '../scripts/gds/art-stage.js');
+const art = requireHostModule(require, '../scripts/bongos/art-stage.js');
 
 let passed = 0, failed = 0;
 function t(name, fn) { try { fn(); passed++; console.log(`  PASS  ${name}`); } catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); } }

package/tests/artifact_audit.mjs

@@ -26,7 +26,7 @@ const {
   auditArtifacts, declaresArtifact, taskIdsIn,
   AUDITED_STATUSES, ASSURANCE_GATE_DATE, fetchAuditedTasks,
   fileBlocker, blockerSourceRef,
-} = require('../scripts/gds/artifact-audit.js');
+} = require('../scripts/bongos/artifact-audit.js');
 
 let passed = 0, failed = 0;
 const t = async (n, f) => {
@@ -38,7 +38,7 @@ const NONE = { messageIds: new Set(), contentIds: new Set() };
 
 // The three, in the shape they had on the day they were found.
 const SEEDS = [
-  { id: '1003158', status: 'shipped', shipped_at: '2026-08-25T00:00:00Z', title: 'auto-upgrade loud', touches: ['scripts/gds/deploy-divergence.js'] },
+  { id: '1003158', status: 'shipped', shipped_at: '2026-08-25T00:00:00Z', title: 'auto-upgrade loud', touches: ['scripts/bongos/deploy-divergence.js'] },
   { id: '1002459', status: 'confirmed', shipped_at: '2026-09-04T00:00:00Z', title: 'blocker detail hydration', touches: ['modules/ideas/blockers.js'] },
   { id: '1002792', status: 'completed', shipped_at: '2026-08-27T00:00:00Z', title: 'PATCH /tasks/:id title', touches: ['modules/lifecycle/routes/tasks.js'] },
 ];

package/tests/atlas.mjs

@@ -15,7 +15,7 @@ import { onDiskModuleKeys } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const atlas = require(path.join(ROOT, 'scripts', 'gds', 'gen-atlas.js'));
+const atlas = require(path.join(ROOT, 'scripts', 'bongos', 'gen-atlas.js'));
 
 // Must stay in lockstep with modules/hall-ui/public/atlas.js (nodeFill/sizeFor/ringFor,
 // EDGE_STYLE, TOKENS, CENTER kinds). If the renderer learns a new kind, add it

package/tests/audit_deps.mjs

@@ -6,7 +6,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const { findMissingDeps, classify } = require('../scripts/gds/audit-deps.js');
+const { findMissingDeps, classify } = require('../scripts/bongos/audit-deps.js');
 
 let passed = 0, failed = 0;
 const t = (n, f) => { try { f(); passed++; console.log(`  PASS  ${n}`); } catch (e) { failed++; console.log(`  FAIL  ${n}\n        ${e.message}`); } };

package/tests/audit_gate.mjs

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const gate = require(path.join(ROOT, 'scripts', 'gds', 'audit-gate.js'));
+const gate = require(path.join(ROOT, 'scripts', 'bongos', 'audit-gate.js'));
 
 const AUDIT_FIXTURE = {
   vulnerabilities: {