@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/client-baseurl-guard.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// scripts/bongos/client-baseurl-guard.js — a web page must not send its API calls to
+// the site root (task 1003263).
+//
+// THE BUG THIS EXISTS TO STOP. The generated client (clients/bongos-client) exposes
+// two call styles, and mixing them is silent and fatal:
+//
+//   NAMESPACED   api.inbox.getInboxTemplate({})   → path template '/inbox/template',
+//                                                   API-RELATIVE, needs the API base
+//   ESCAPE HATCH api.request('GET', `${API}/me`)  → caller supplies the FULL path
+//
+// createClient documents `baseUrl: ''` as "paths are already absolute" and passes
+// them through unchanged. So a page that sets baseUrl:'' AND calls a namespaced
+// method requests '/inbox/template' — the SITE ROOT, where nothing is mounted — and
+// 404s on every call. The router mounts at '/api/bongos/v1' (api-prefix.js
+// VERSIONED_API_PREFIX), which is exactly the client's own default.
+//
+// WHY A FITNESS CHECK AND NOT A TEST. Three pages shipped this defect — ideas.js and
+// idea.js were dead in production from the day they shipped, and collab.js was caught
+// in review one commit before it would have been. Every page test stubs the client
+// method directly, so URL construction is never exercised; tests/idea_hall_composer.mjs
+// even asserted with a regex against the source text, which passes happily on a broken
+// URL. 54 green tests over pages that 404 on every call. The defect is invisible to the
+// test style this repo uses for hall pages, so it needs a guard at a different altitude.
+//
+// STATIC AND CONSERVATIVE. It flags only the unambiguous combination — an explicit
+// empty baseUrl in a createClient call, in a file that also makes a namespaced call.
+// A page using the escape hatch with baseUrl:'' is CORRECT and stays silent (work.js,
+// copy-desk.js, goal-inbox.js and most of the hall do exactly that).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'a web page sends its API calls to the API, not the site root (task 1003263)';
+
+// createClient({ ... baseUrl: '' ... }) — an EXPLICIT empty base. Omitting baseUrl is
+// the correct fix and must not match; only the literal empty string is the defect.
+const EMPTY_BASEURL = /createClient\(\s*\{[^}]*baseUrl\s*:\s*(''|""|`\s*`)/;
+
+// api.<namespace>.<method>( — the generated namespaced style. `api.request(` is the
+// escape hatch and is deliberately NOT matched: with it, baseUrl:'' is correct.
+const NAMESPACED_CALL = /\bapi\s*\.\s*(?!request\b)[A-Za-z_$][\w$]*\s*\.\s*[A-Za-z_$][\w$]*\s*\(/;
+
+// Every tracked browser-served script. Server code never calls createClient this way.
+function trackedPageScripts() {
+  try {
+    const out = execFileSync('git', ['ls-files', 'modules/*/public/*.js', 'public/*.js'],
+      { cwd: REPO_ROOT, encoding: 'utf8' });
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function scanPages(files, read) {
+  const violations = [];
+  let scanned = 0;
+  let usingClient = 0;
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) continue;
+    scanned += 1;
+    if (!/createClient\(/.test(src)) continue;
+    usingClient += 1;
+    if (!EMPTY_BASEURL.test(src)) continue;
+    if (!NAMESPACED_CALL.test(src)) continue; // escape-hatch page — baseUrl:'' is right
+    const m = NAMESPACED_CALL.exec(src);
+    violations.push(
+      `${rel} sets baseUrl:'' AND calls the generated client (${m[0].replace(/\s+/g, '')}…). `
+      + "Those paths are API-relative, so baseUrl:'' sends them to the site root and every "
+      + 'call 404s. Drop the baseUrl override, or switch every call to '
+      + "api.request('METHOD', `${API}/…`) with a full path.",
+    );
+  }
+  return { violations, scanned, usingClient };
+}
+
+function checkClientBaseUrl({ files, read } = {}) {
+  const list = files || trackedPageScripts();
+  if (!list.length) {
+    return {
+      name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked page scripts; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of browser-served scripts for a root-bound API client.',
+    };
+  }
+  const reader = read || ((rel) => {
+    try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+  });
+  const { violations, scanned, usingClient } = scanPages(list, reader);
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} browser-served script(s) scanned, ${usingClient} building a client: none may combine `
+      + "baseUrl:'' with a generated namespaced call (api.<ns>.<method>()) — that pairing 404s every request. "
+      + "baseUrl:'' with api.request() and a full path is the correct escape-hatch style and is not flagged.",
+  };
+}
+
+function main() {
+  const r = checkClientBaseUrl();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkClientBaseUrl, scanPages, trackedPageScripts, EMPTY_BASEURL, NAMESPACED_CALL };

package/scripts/bongos/codemod-rename-scripts-gds.js

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+// scripts/bongos/codemod-rename-scripts-gds.js — move scripts/gds/ to scripts/bongos/, rewrite
+// every in-repo reference, and leave a working forwarder at each old path (task 1004848, C3 of
+// goal 1000073).
+//
+// WHY. The builder CLI directory still carried the retired acronym, and ~1,600 tracked files name
+// it. Hand-editing that many files is how a rename goes wrong quietly, so this is the same shape
+// as task 2004's codemod-rename-src-gds.js: one committed, reviewable, deterministic pass. It is
+// the third attempt — tasks 1003705 and 1003965 both did this work on branches that were never
+// pushed and were lost — so it is written to be RE-RUN on top of a newer main: a script someone
+// adds under scripts/gds/ after this lands is picked up by the next run, not left behind.
+//
+// THE THREE PASSES, each idempotent on its own:
+//
+//   1. MOVE. Every tracked file under scripts/gds/ that is NOT a generated forwarder is
+//      `git mv`ed to the same relative path under scripts/bongos/. Skipping forwarders is the
+//      first of the four fixes the lost branch had: without it a second run "moves" the
+//      forwarders over the real scripts and silently replaces ~350 real files with two-line
+//      stubs. A file present at BOTH paths as real code is a conflict, and the run stops.
+//
+//   2. REWRITE. Every tracked text file outside the exclusions below has its references
+//      rewritten. The shapes, each with a trailing guard so `scripts/gdsx` is never touched:
+//        scripts/gds/…            -> scripts/bongos/…          (the slash form, any context)
+//        'scripts', 'gds'         -> 'scripts', 'bongos'       (path.join segments)
+//        scripts\/gds  (regex)    -> scripts\/(?:gds|bongos)   (WIDENED, not renamed: these are
+//                                    detectors — skill-preflight signals, path rules, the skill
+//                                    invocation matcher — and a hosted project's older skills
+//                                    and hooks still say scripts/gds until its next upgrade, so
+//                                    a detector that only knew the new name would stop seeing
+//                                    them. That is the "skills machine-detector" fix.)
+//        scripts\gds / scripts\\gds -> the same with bongos    (Windows paths in .ps1/.cmd/docs)
+//        scripts[/\\]gds (regex)   -> scripts[/\\](?:gds|bongos)  (either separator; widened like ESC)
+//        ../gds/ and ./gds/       -> ../bongos/ and ./bongos/  (relative, ONLY from a file that
+//                                    sits in a sibling dir of scripts/ or directly in scripts/)
+//      A LINE carrying `@bongos-forwarder` or `rename-keep` is never rewritten. The first marks
+//      a line ABOUT the forwarders (a protected-surface entry, a forwarder's own header); the
+//      second marks a line that matches RECORDED data — a shipped task's touches[] still says
+//      scripts/gds/ (the Bongos Shipper badge counts those), so that matcher must keep the old
+//      prefix beside the new one.
+//
+//   3. FORWARDERS. Every executable file under scripts/bongos/ (.js .cjs .mjs .sh .ps1 .cmd)
+//      gets a generated forwarder at the old path (the shim generator — the second fix), and a
+//      forwarder whose target is gone is removed. JS forwarders delegate to forwarder.js; the
+//      shell, PowerShell and cmd ones are self-contained. Data files (.json, .md, units) get no
+//      forwarder: nothing outside the repo executes them by the old path.
+//
+// NOT TOUCHED, on purpose (see EXCLUDE / FROZEN_PATHS):
+//   - the frozen record (docs/adr, docs/session-logs, docs/audits, limitations) and every
+//     migrations/ tree — history says scripts/gds because it was scripts/gds;
+//     rename-history-check.js pins it;
+//   - scripts/gds/ itself (the forwarders are generated, never rewritten);
+//   - files that deliberately name BOTH spellings or the old one: this codemod, forwarder.js,
+//     the forwarder test, modules/lifecycle/executed-closure.js (lists both on purpose),
+//     rename-ledger-prose.js (masks `scripts/gds` as a protected identifier in ledger prose),
+//     the task-2004 codemod (a historical tool), and .bongos-core.json (the manifest of a
+//     core build cut from an older commit — its paths describe THAT build).
+//
+// Usage:
+//   node scripts/bongos/codemod-rename-scripts-gds.js           # apply
+//   node scripts/bongos/codemod-rename-scripts-gds.js --check   # report only; exit 1 if anything would change
+//
+// Idempotent: a second run moves, rewrites and writes nothing.
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { warningText, WARNED_ENV } = require('./forwarder.js');
+
+const OLD_DIR = 'scripts/gds';
+const NEW_DIR = 'scripts/bongos';
+const MARKER = '@bongos-forwarder';
+const TASK = 'task 1004848';
+const KEEP_LINE = /@bongos-forwarder|rename-keep/;
+
+const EXCLUDE = new Set([
+  'scripts/bongos/codemod-rename-scripts-gds.js',
+  'scripts/bongos/forwarder.js',
+  'tests/scripts_gds_forwarders.mjs',
+  'modules/lifecycle/executed-closure.js',
+  'scripts/bongos/rename-ledger-prose.js',
+  'scripts/bongos/codemod-rename-src-gds.js',
+  '.bongos-core.json',
+]);
+
+const FROZEN_PATHS = [
+  /(^|\/)docs\/adr\//,
+  /(^|\/)docs\/session-logs\//,
+  /(^|\/)docs\/audits\//,
+  /(^|\/)limitations\//,
+  /(^|\/)migrations\//,
+];
+
+// Files with no forwarder even though they are executable: the two this task adds (nothing
+// outside the repo has ever called them by the old path).
+const NO_FORWARDER = new Set(['codemod-rename-scripts-gds.js', 'forwarder.js']);
+const FORWARDED_EXT = new Set(['.js', '.cjs', '.mjs', '.sh', '.ps1', '.cmd']);
+// Shell files that are SOURCED, never executed: their forwarder sources the real file instead of
+// exec'ing it, or the caller's shell would never see the functions it defines.
+const SOURCED = new Set(['lib.sh']);
+
+// ---------- pass 2: the rewrite (pure) ----------
+
+const SLASH = /scripts\/gds(?![A-Za-z0-9_-])/g;
+const SEG = /(['"`])scripts\1(\s*,\s*)(['"`])gds\3/g;
+const ESC = /scripts\\\/gds(?![A-Za-z0-9_-])/g;
+const WIN2 = /scripts\\\\gds(?![A-Za-z0-9_-])/g;
+const WIN1 = /scripts\\gds(?![A-Za-z0-9_-])/g;
+// Either separator, as a regex character class: `scripts[/\\]gds`. Widened like ESC.
+const CLASS = /scripts\[\/\\\\\]gds(?![A-Za-z0-9_-])/g;
+const REL_UP = /(['"`]\.\.\/)gds(?=\/|['"`])/g;
+const REL_DOT = /(['"`]\.\/)gds(?=\/|['"`])/g;
+
+// `../gds` means scripts/gds only from a file one level inside a SIBLING of scripts/gds;
+// `./gds` only from a file directly in scripts/. Anywhere else they mean something else.
+const inScriptsSibling = (rel) => /^scripts\/(?!gds\/|bongos\/)[^/]+\/[^/]+$/.test(rel);
+const inScriptsTop = (rel) => /^scripts\/[^/]+$/.test(rel);
+
+function isFrozen(rel) {
+  return FROZEN_PATHS.some((re) => re.test(rel));
+}
+
+function isRewritable(rel) {
+  if (EXCLUDE.has(rel)) return false;
+  if (rel === OLD_DIR || rel.startsWith(`${OLD_DIR}/`)) return false;
+  return !isFrozen(rel);
+}
+
+function count(re, s) {
+  return (s.match(re) || []).length;
+}
+
+// rewriteLine — one line, every shape. Returns { line, n }.
+function rewriteLine(rel, line) {
+  if (KEEP_LINE.test(line)) return { line, n: 0 };
+  let n = count(SLASH, line) + count(SEG, line) + count(ESC, line) + count(WIN2, line) + count(WIN1, line)
+    + count(CLASS, line);
+  let out = line
+    .replace(CLASS, 'scripts[/\\\\](?:gds|bongos)')
+    .replace(ESC, 'scripts\\/(?:gds|bongos)')
+    .replace(WIN2, 'scripts\\\\bongos')
+    .replace(WIN1, 'scripts\\bongos')
+    .replace(SLASH, 'scripts/bongos')
+    .replace(SEG, (_m, q1, sep, q2) => `${q1}scripts${q1}${sep}${q2}bongos${q2}`);
+  if (inScriptsSibling(rel)) {
+    n += count(REL_UP, out);
+    out = out.replace(REL_UP, '$1bongos');
+  }
+  if (inScriptsTop(rel)) {
+    n += count(REL_DOT, out);
+    out = out.replace(REL_DOT, '$1bongos');
+  }
+  return { line: out, n };
+}
+
+// rewriteText — a whole file. Line-wise so the marker exemption is per line; the SEG form can
+// span a newline inside a path.join, so a multi-line SEG is handled on the joined text after.
+function rewriteText(rel, text) {
+  let n = 0;
+  const lines = text.split('\n').map((l) => {
+    const r = rewriteLine(rel, l);
+    n += r.n;
+    return r.line;
+  });
+  let out = lines.join('\n');
+  const multi = out.match(SEG);
+  if (multi) {
+    n += multi.length;
+    out = out.replace(SEG, (_m, q1, sep, q2) => `${q1}scripts${q1}${sep}${q2}bongos${q2}`);
+  }
+  return { text: out, n };
+}
+
+// ---------- pass 3: forwarders (pure) ----------
+
+function isForwarder(text) {
+  return String(text).includes(MARKER);
+}
+
+function header(rel, c) {
+  return [
+    `${c} scripts/gds/${rel} — ${MARKER} (${TASK}). Generated by`,
+    `${c} scripts/bongos/codemod-rename-scripts-gds.js; do not edit.`,
+    `${c} The real script is scripts/bongos/${rel}. This forwarder keeps callers that still name`,
+    `${c} the old path working, and warns once so they get repointed. Task 1003706 removes it.`,
+  ];
+}
+
+function shellInterpreter(targetText) {
+  const first = String(targetText).split('\n', 1)[0];
+  if (/^#!.*\bsh\s*$/.test(first) && !/bash/.test(first)) return { shebang: first, interp: 'sh' };
+  if (/^#!/.test(first)) return { shebang: first, interp: 'bash' };
+  return { shebang: '#!/usr/bin/env bash', interp: 'bash' };
+}
+
+// forwarderFor(rel, targetText) — the forwarder's full text, or null when the file gets none.
+// `rel` is interpolated straight into shell, PowerShell and cmd text. That is safe because every
+// `rel` comes from `git ls-files` of this repo's own tree — committer-controlled, the same trust as
+// writing the script itself. Never point this at a path list from anywhere less trusted.
+function forwarderFor(rel, targetText) {
+  const base = path.posix.basename(rel);
+  const ext = path.posix.extname(rel);
+  if (NO_FORWARDER.has(rel) || !FORWARDED_EXT.has(ext)) return null;
+  const depth = rel.split('/').length - 1;
+  const up = '../'.repeat(depth + 1);
+  const toTarget = `${up}bongos/${rel}`;
+  const warn = warningText(rel);
+
+  if (ext === '.js' || ext === '.cjs' || ext === '.mjs') {
+    if (ext === '.mjs') return null; // none exist; an ESM forwarder would need its own shape
+    const first = String(targetText).split('\n', 1)[0];
+    const lines = [];
+    if (first.startsWith('#!')) lines.push(first);
+    lines.push(...header(rel, '//'));
+    lines.push("'use strict';");
+    lines.push(`require('${up}bongos/forwarder.js').forward(module, '${rel}');`);
+    return `${lines.join('\n')}\n`;
+  }
+  if (ext === '.sh') {
+    const { shebang, interp } = shellInterpreter(targetText);
+    const lines = [shebang, ...header(rel, '#')];
+    lines.push(`if [ -z "\${${WARNED_ENV}:-}" ]; then echo "${warn}" >&2; fi`);
+    lines.push(`export ${WARNED_ENV}=1`);
+    if (SOURCED.has(base)) {
+      lines.push(`. "$(dirname "\${BASH_SOURCE[0]}")/${toTarget}"`);
+    } else {
+      lines.push(`exec ${interp} "$(dirname "$0")/${toTarget}" "$@"`);
+    }
+    return `${lines.join('\n')}\n`;
+  }
+  if (ext === '.ps1') {
+    // CRLF and pure ASCII, like every .ps1 here (.gitattributes): PowerShell 5.1 reads a
+    // BOM-less script in the ANSI codepage.
+    const lines = header(rel, '#').map((l) => l.replace('—', '--'));
+    lines.push(`if (-not $env:${WARNED_ENV}) { Write-Warning '${warn}' }`);
+    lines.push(`$env:${WARNED_ENV} = '1'`);
+    lines.push(`& (Join-Path $PSScriptRoot '${toTarget.replace(/\//g, '\\')}') @args`);
+    lines.push('exit $LASTEXITCODE');
+    return `${lines.join('\r\n')}\r\n`;
+  }
+  // .cmd — CRLF, like the file it stands in for.
+  const lines = ['@echo off', ...header(rel, 'rem').map((l) => l.replace('—', '--'))];
+  lines.push(`if not defined ${WARNED_ENV} echo ${warn} 1>&2`);
+  lines.push(`set ${WARNED_ENV}=1`);
+  lines.push(`call "%~dp0${toTarget.replace(/\//g, '\\')}" %*`);
+  lines.push('exit /b %ERRORLEVEL%');
+  return `${lines.join('\r\n')}\r\n`;
+}
+
+const README = `# scripts/gds/ — forwarders only (${MARKER})
+
+Generated by \`scripts/bongos/codemod-rename-scripts-gds.js\` (${TASK}); do not edit.
+
+The builder CLI moved to [\`scripts/bongos/\`](../bongos/). Every executable file here is a
+forwarder that runs the real script at the same path under \`scripts/bongos/\` and warns once, so
+callers this repo cannot update in the same change — systemd units on a box, cron routines, a
+hosted project's hooks and skills before its next core upgrade — keep working. Point new code at
+\`scripts/bongos/\`. Task 1003706 removes this directory once a release has carried it.
+`;
+
+// ---------- the run ----------
+
+function git(args, root, opts = {}) {
+  return execFileSync('git', args, { cwd: root, maxBuffer: 256 * 1024 * 1024, encoding: 'utf8', ...opts });
+}
+
+function lsFiles(root, ...paths) {
+  return git(['ls-files', '-z', '--', ...paths], root).split('\0').filter(Boolean);
+}
+
+function isBinary(buf) {
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+function movePass(root, { check }) {
+  const moved = [];
+  for (const rel of lsFiles(root, OLD_DIR)) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs)) continue;
+    if (isForwarder(fs.readFileSync(abs, 'utf8'))) continue;
+    const dest = NEW_DIR + rel.slice(OLD_DIR.length);
+    const destAbs = path.join(root, dest);
+    if (fs.existsSync(destAbs) && !isForwarder(fs.readFileSync(destAbs, 'utf8'))) {
+      throw new Error(`conflict: ${rel} and ${dest} are both real files — merge them by hand, then re-run`);
+    }
+    moved.push(rel);
+    if (check) continue;
+    fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+    git(['mv', rel, dest], root);
+  }
+  return moved;
+}
+
+function rewritePass(root, { check }) {
+  const changed = [];
+  for (const rel of lsFiles(root)) {
+    if (!isRewritable(rel)) continue;
+    const abs = path.join(root, rel);
+    let buf;
+    try { buf = fs.readFileSync(abs); } catch { continue; }
+    if (isBinary(buf)) continue;
+    const before = buf.toString('utf8');
+    if (!/gds/.test(before)) continue;
+    const { text, n } = rewriteText(rel, before);
+    if (text === before) continue;
+    changed.push({ rel, n });
+    if (!check) fs.writeFileSync(abs, text);
+  }
+  return changed;
+}
+
+function forwarderPass(root, { check }) {
+  const written = [];
+  const removed = [];
+  const live = git(['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', NEW_DIR], root)
+    .split('\0').filter(Boolean);
+  const wanted = new Map();
+  for (const relNew of live) {
+    const abs = path.join(root, relNew);
+    if (!fs.existsSync(abs)) continue;
+    const rel = relNew.slice(NEW_DIR.length + 1);
+    const content = forwarderFor(rel, fs.readFileSync(abs, 'utf8'));
+    if (content != null) wanted.set(rel, { content, mode: fs.statSync(abs).mode });
+  }
+  wanted.set('README.md', { content: README, mode: 0o644 });
+
+  for (const [rel, { content, mode }] of wanted) {
+    const abs = path.join(root, OLD_DIR, rel);
+    const cur = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+    const exec = (mode & 0o111) !== 0;
+    const modeOk = cur == null || ((fs.statSync(abs).mode & 0o111) !== 0) === exec;
+    if (cur === content && modeOk) continue;
+    written.push(`${OLD_DIR}/${rel}`);
+    if (check) continue;
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    fs.chmodSync(abs, exec ? 0o755 : 0o644);
+  }
+  for (const relOld of lsFiles(root, OLD_DIR)) {
+    const rel = relOld.slice(OLD_DIR.length + 1);
+    const abs = path.join(root, relOld);
+    if (wanted.has(rel) || !fs.existsSync(abs) || !isForwarder(fs.readFileSync(abs, 'utf8'))) continue;
+    removed.push(relOld);
+    if (!check) git(['rm', '-q', '--', relOld], root);
+  }
+  if (!check && written.length) git(['add', '--', ...written], root);
+  return { written, removed };
+}
+
+function main(argv = process.argv.slice(2)) {
+  const check = argv.includes('--check');
+  const root = git(['rev-parse', '--show-toplevel'], process.cwd()).trim();
+  const moved = movePass(root, { check });
+  const changed = rewritePass(root, { check });
+  const { written, removed } = forwarderPass(root, { check });
+  const refs = changed.reduce((s, c) => s + c.n, 0);
+  const verb = check ? 'would' : 'did';
+  console.log(`codemod (${verb}): move ${moved.length} file(s) to ${NEW_DIR}/; rewrite ${refs} reference(s) across ${changed.length} file(s); write ${written.length} forwarder(s); remove ${removed.length} stale forwarder(s).`);
+  if (argv.includes('--verbose')) {
+    for (const c of changed.sort((a, b) => b.n - a.n)) console.log(`  ${String(c.n).padStart(4)}  ${c.rel}`);
+  }
+  const dirty = moved.length + changed.length + written.length + removed.length;
+  if (check && dirty) process.exitCode = 1;
+  return { moved, changed, written, removed };
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  EXCLUDE,
+  MARKER,
+  forwarderFor,
+  isForwarder,
+  isRewritable,
+  rewriteLine,
+  rewriteText,
+};

package/scripts/bongos/codemod-rename-src-gds.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// scripts/gds/codemod-rename-src-gds.js
+//
+// One-shot, auditable codemod for task 2004 (BV1.R124): rename the core source
+// directory src/gds/ -> src/bongos/ and rewrite EVERY in-repo reference to it.
+// Committed so the approach is reproducible and reviewable (task done-when).
+//
+// Deterministic by construction:
+//   1. `git mv src/gds src/bongos`  (idempotent -- skipped if already moved).
+//   2. Over every TRACKED text file, rewrite the literal path token `src/gds`
+//      -> `src/bongos`, guarded by a TRAILING boundary so look-alike tokens are
+//      never clobbered:
+//         src/gds/...     -> src/bongos/...     (directory refs)
+//         "src/gds"       -> "src/bongos"       (bare, at a boundary)
+//         src/gds-client  -> src/gds-client     (UNCHANGED: a look-alike file name)
+//         src/gdsx        -> src/gdsx           (UNCHANGED here: prefix-edge fixture)
+//
+//   Regex: /src\/gds(?![A-Za-z0-9_-])/g  -- trailing guard only. No LEADING guard:
+//   `scripts/gds` contains no `src/gds` substring, and the two real leading-glue
+//   sites (`keyed-to-src/gds` in an audit, `\tsrc/gds/auth.js` in a mirror-export
+//   fixture) are genuine directory refs we DO want rewritten.
+//
+// Excluded from the sweep (see EXCLUDE):
+//   - this script (its own source contains the search literal),
+//   - tests/path_match.mjs + tests/touches_overlap.mjs -- they assert the
+//     "src/gdsx must NOT match src/gds/" boundary edge; a mechanical half-rewrite
+//     (which leaves `src/gdsx` but changes `src/gds/`) would silently gut the
+//     test. Those two are hand-edited to src/bongos / src/bongosx so the edge
+//     stays meaningful.
+//
+// git ls-files is the file source, so gitignored generated docs
+// (docs/repo-map.md, docs/session-log-index.md) are excluded -- they regenerate.
+// Binary files are skipped via a NUL-byte sniff.
+//
+// Idempotent: a second run moves nothing and rewrites nothing (0 replacements).
+
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = execSync('git rev-parse --show-toplevel').toString().trim();
+
+// (a) The slash form: `src/gds`, `src/gds/routes`, `"src/gds"` ... Trailing guard
+// only (see header) so `src/gds-client` and `src/gdsx` are left alone.
+const NEEDLE = /src\/gds(?![A-Za-z0-9_-])/g;
+const REPLACEMENT = 'src/bongos';
+
+// (b) The SPLIT-SEGMENT form: `path.join(root, 'src', 'gds', ...)` -- the segments
+// are separate string args, so there is no literal `src/gds` substring for (a) to
+// catch. Anchored on a PRECEDING quoted `'src'` segment so it rewrites only the
+// `'gds'` that follows `'src'` -- NEVER `'scripts', 'gds'` (scripts/gds is not
+// renamed). \s between segments tolerates a newline-split path.join. The `gds`
+// quote must close immediately, so `'gdsx'` / `'gds-client'` never match.
+const SEG = /(['"])src\1(\s*,\s*)(['"])gds\3/g;
+const segReplace = (s) => s.replace(SEG, (_m, q1, sep, q2) => `${q1}src${q1}${sep}${q2}bongos${q2}`);
+
+// (c) RELATIVE requires into the moved dir. A file DIRECTLY under src/ addresses
+// its former sibling as `require('./gds/x')` -- no `src/` prefix, so (a) misses it,
+// and after the move it dangles. `./gds` resolves to src/gds ONLY from a src-top-
+// level file; a `./gds` in scripts/* means scripts/gds (NOT renamed) and a deeper
+// src/**/* file resolves elsewhere -- so this pass is gated to `src/<file>` and
+// never fires elsewhere. (Verified: the only matches are src/module-api.js +
+// src/platform-server.js; no `../gds` relative forms exist.) `(?=\/|['"])` keeps
+// `./gds-client` / `./gdsx` safe.
+const isSrcTopLevel = (rel) => /^src\/[^/]+\.(?:js|mjs|cjs)$/.test(rel);
+const REL = /(\.\/)gds(?=\/|['"])/g;
+
+// (d) REGEX-ESCAPED slash form: `src\/gds` (backslash-slash) as written inside a
+// RegExp literal -- e.g. route-rank-check.js's ROUTE_FILE_RE and the tests that
+// match against it. `\/` is not the plain `/` (a) scans for, so (a) misses it.
+const ESC = /src\\\/gds(?![A-Za-z0-9_-])/g;
+
+// (e) WINDOWS double-backslash form: `src\\gds` in JS source (one backslash on
+// disk-per-escape, two chars) -- Windows-path fixtures the matchers normalize
+// (permission_path / publish_manifest). Trailing guard keeps `src\\gdsx` safe.
+const WIN = /src\\\\gds(?![A-Za-z0-9_-])/g;
+
+const EXCLUDE = new Set([
+  'scripts/gds/codemod-rename-src-gds.js',
+  'tests/path_match.mjs',
+  'tests/touches_overlap.mjs',
+]);
+
+function gitMv() {
+  const oldDir = path.join(REPO_ROOT, 'src', 'gds');
+  const newDir = path.join(REPO_ROOT, 'src', 'bongos');
+  if (fs.existsSync(newDir)) {
+    console.log('git mv: src/bongos already exists -- skipping move (idempotent).');
+    return;
+  }
+  if (!fs.existsSync(oldDir)) {
+    console.log('git mv: neither src/gds nor src/bongos present -- nothing to move.');
+    return;
+  }
+  execSync('git mv src/gds src/bongos', { cwd: REPO_ROOT, stdio: 'inherit' });
+  console.log('git mv: src/gds -> src/bongos');
+}
+
+function isBinary(buf) {
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+function main() {
+  gitMv();
+
+  const tracked = execSync('git ls-files', { cwd: REPO_ROOT, maxBuffer: 128 * 1024 * 1024 })
+    .toString().split('\n').filter(Boolean);
+
+  let filesChanged = 0;
+  let totalReplacements = 0;
+  const changed = [];
+
+  for (const rel of tracked) {
+    if (EXCLUDE.has(rel)) continue;
+    const abs = path.join(REPO_ROOT, rel);
+    let buf;
+    try { buf = fs.readFileSync(abs); } catch { continue; } // e.g. deleted-in-index
+    if (isBinary(buf)) continue;
+    const before = buf.toString('utf8');
+    const slashN = (before.match(NEEDLE) || []).length;
+    const segN = (before.match(SEG) || []).length;
+    const escN = (before.match(ESC) || []).length;
+    const winN = (before.match(WIN) || []).length;
+    const relN = isSrcTopLevel(rel) ? (before.match(REL) || []).length : 0;
+    if (slashN === 0 && segN === 0 && escN === 0 && winN === 0 && relN === 0) continue;
+    let after = segReplace(before.replace(NEEDLE, REPLACEMENT));
+    after = after.replace(ESC, 'src\\/bongos').replace(WIN, 'src\\\\bongos');
+    if (relN > 0) after = after.replace(REL, '$1bongos');
+    if (after === before) continue;
+    fs.writeFileSync(abs, after);
+    filesChanged++;
+    const n = slashN + segN + escN + winN + relN;
+    totalReplacements += n;
+    changed.push({ rel, n });
+  }
+
+  changed.sort((a, b) => b.n - a.n);
+  console.log(`\ncodemod: rewrote ${totalReplacements} reference(s) across ${filesChanged} file(s).`);
+  for (const c of changed) console.log(`  ${String(c.n).padStart(4)}  ${c.rel}`);
+  console.log('\nExcluded (hand-edited or self): ' + [...EXCLUDE].join(', '));
+}
+
+main();