@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/forwarder.js

@@ -0,0 +1,80 @@
+// scripts/bongos/forwarder.js — the runtime behind every scripts/gds/ forwarder (task 1004848).
+//
+// WHY. scripts/gds/ moved to scripts/bongos/ (criterion C3 of goal 1000073), but the old path
+// is named by callers this repo cannot update in the same commit: systemd units already
+// installed on a box, cron routines, hosted projects' hooks and skills that predate their next
+// core upgrade, a builder's shell history. Each file left in scripts/gds/ is a two-line
+// generated forwarder that hands itself to forward() below, so one copy of the behaviour
+// serves all of them and the forwarders stay trivially reviewable.
+//
+// TWO WAYS A FORWARDER IS REACHED, and both must keep working:
+//   1. RUN  (`node scripts/gds/x.js …`) — re-exec the real script with the same node flags,
+//      argv, cwd, env and stdio, and pass its exit status (or signal) back out. A re-exec,
+//      not an in-process require: the real scripts gate their CLI on
+//      `require.main === module`, which an in-process load would make false.
+//   2. REQUIRE (`require('…/scripts/gds/x.js')`) — export the real module itself, so the
+//      caller gets the identical object the new path returns (one module cache entry).
+//
+// It WARNS ONCE per process tree, on stderr, and only on a run: a run is a caller someone
+// should repoint; a require is code, and noise there would land in every test log. The
+// warning names the new path so the fix is one edit. Exit status uses process.exitCode, never
+// process.exit() — see the Windows abort note in scripts/bongos/CLAUDE.md.
+//
+// The forwarders are generated by scripts/bongos/codemod-rename-scripts-gds.js and removed
+// by task 1003706 (C3d) once a release has carried them.
+
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// Set in the child's env so a forwarder that reaches another forwarder warns once, not twice.
+const WARNED_ENV = 'BONGOS_FORWARDER_WARNED';
+
+// Plain ASCII with no shell metacharacters: the same sentence is baked into the .sh, .ps1 and
+// .cmd forwarders, and Windows PowerShell 5.1 reads a BOM-less script as the ANSI codepage.
+function warningText(rel) {
+  return `[bongos] scripts/gds/${rel} has moved to scripts/bongos/${rel}. `
+    + 'This old path still works for now, but update whatever called it. '
+    + 'The forwarders in scripts/gds/ are removed in a later release.';
+}
+
+// forward(mod, rel) — `mod` is the forwarder's own `module`; `rel` is its path under scripts/gds/.
+// Injectable seams (spawn, env, stderr, proc) exist for the test; a forwarder never passes them.
+function forward(mod, rel, {
+  spawn = spawnSync,
+  env = process.env,
+  stderr = process.stderr,
+  proc = process,
+  mainModule = require.main,
+} = {}) {
+  const target = path.join(__dirname, rel);
+  if (mainModule !== mod) {
+    mod.exports = require(target);
+    return { mode: 'require', target };
+  }
+  if (!env[WARNED_ENV]) stderr.write(`${warningText(rel)}\n`);
+  const r = spawn(proc.execPath, [...proc.execArgv, target, ...proc.argv.slice(2)], {
+    stdio: 'inherit',
+    env: { ...env, [WARNED_ENV]: '1' },
+  });
+  if (r.error) {
+    stderr.write(`[bongos] could not run ${target}: ${r.error.message}\n`);
+    proc.exitCode = 1;
+  } else if (r.signal) {
+    proc.kill(proc.pid, r.signal);
+  } else {
+    proc.exitCode = r.status == null ? 1 : r.status;
+  }
+  return { mode: 'run', target };
+}
+
+// currentScriptPath(rel) — a repo-relative path a doc or a record may still spell the old way,
+// mapped to the file that actually holds the code. The doc guards read a CLI's SOURCE to check
+// what a doc says about it; read through the old path, that source is a two-line forwarder, and
+// every documented flag would read as missing. Anything not under scripts/gds/ is returned as is.
+function currentScriptPath(rel) {
+  return String(rel).replace(/^scripts\/gds\//, 'scripts/bongos/');
+}
+
+module.exports = { forward, warningText, currentScriptPath, WARNED_ENV };

package/scripts/bongos/gate-review.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/gate-review.js — the automatic gate-surface gatekeeper (ADR 0058).
+//
+// WHY. In deploy mode 'ci' (config/deploy.json) PRs auto-merge on green checks and
+// main auto-deploys to prod. CODEOWNERS (owner review on gate surfaces) was the ONLY
+// human in that loop — and the bottleneck. The owner chose a RANK-BASED trust model
+// (2026-06-15): trust senior builders to auto-merge routine sensitive work, but keep a
+// HARD, rank-independent floor for the gate's own machinery + deploy switch.
+//
+// WHAT. This is a PURE, deterministic classifier over the PR diff-as-DATA. It runs in
+// CI (.github/workflows/gate-review.yml) from the TRUSTED BASE copy (the workflow
+// overlays scripts/+src/ from origin/main before running, so a PR cannot edit the
+// analyzer to pass itself). It emits one of three verdicts:
+//
+//   PASS         — no gate surface touched, OR only AUTO pure-removal surfaces
+//                  (un-mute a test, narrow the secret-scanner allowlist). Auto-merge.
+//   NEEDS_TRUST  — a sensitive-but-routine gate surface (migrations, deps, routes,
+//                  server, ship plumbing, boxes, auth-adjacent, doctrine docs). The
+//                  workflow auto-merges this IFF the author is Metic+ (rank trust) or
+//                  the owner approved; otherwise it escalates.
+//   ESCALATE     — the HARD FLOOR: the gate's own machinery, the deploy switch, branch
+//                  protection, CI workflows, the rank/permission enforcement, the
+//                  grader, the deploy-time audit, or the hooks the gate ships through.
+//                  Rank-trust does NOT apply — this ALWAYS pings the owner. Also any
+//                  pre-flight rejection (symlink / non-ASCII path / oversize / analyzer
+//                  error) → ESCALATE, fail-closed.
+//
+// The gate-surface SET is the authoritative src/bongos/permission-path-check.PROTECTED_GLOBS
+// (imported, NEVER hand-retyped — the red-team's #1 finding). The classifier only
+// decides, per touched surface, whether it is HARD-FLOOR, NEEDS_TRUST, or AUTO. Anything
+// matched-protected-but-unclassified defaults to ESCALATE (no allow-by-omission).
+//
+// The pure core (classifyChanges) takes diff data as arguments and is exhaustively
+// unit-tested (tests/gate_review.mjs) with the red-team evasion matrix. The CLI wrapper
+// (main) gathers the real diff via git and applies GATE_REPORT_ONLY / exit codes.
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+// Destructured AT the require, not off a held module object: knip's static pass
+// cannot follow `const x = require(...); const { y } = x;` and reports `y` as an
+// unused export, which reds the CI knip step (this file's own CLAUDE.md records
+// the same trap for src/instance-config.js).
+const { PROTECTED_GLOBS, compileGlobMatcher } = require('../../src/bongos/permission-path-check');
+
+// --- HARD FLOOR (rank-independent ESCALATE) -------------------------------------------
+// A subset of PROTECTED_GLOBS: the surfaces that, if a compromised/injected senior
+// session auto-merged them, would DISABLE the safety system itself or the deploy gate.
+// Kept as globs so the matcher is identical to permission-path-check (trailing '/' =
+// subtree). The owner can promote a NEEDS_TRUST surface here with a one-line edit (which
+// is itself a hard-floor change to this file → escalates — correct).
+const HARD_FLOOR_GLOBS = [
+  'scripts/bongos/gate-review.js', // self
+  'src/bongos/permission-path-check.js', // defines the protected set this gate reads
+  'src/bongos/route-rank-check.js', // the route-gate auditor
+  'src/bongos/auth.js', // requireRank / requireBuilder — the enforcement point
+  'modules/grading/grader.js',       // BV1.R73: grading carved to modules/grading/
+  'modules/grading/grader-workers/',
+  'modules/grading/grader-rubric.json',
+  'scripts/bongos/ci-grade.js', // CI grade-gate driver (task 1143 — red-team #3)
+  'scripts/bongos/grade-smoke.js', // grade-smoke driver
+  'scripts/bongos/conductor-dispatch.js', // mid-flight grader dispatch
+  'scripts/bongos/main-audit.js', // the authoritative deploy-time audit (the backstop)
+  'scripts/bongos/push-main.js', // the sanctioned main-push carrying the override
+  'scripts/bongos/run-unit-tests.js', // the test selector (AUTO pure-removal handled first)
+  'scripts/bongos/install-git-hooks.js',
+  'scripts/bongos/hooks/',
+  'scripts/migrate.sh',
+  'scripts/deploy/',
+  'config/deploy.json', // the laptop/ci/bypass deploy switch
+  'infra/', // branch-protection.json + deploy substrate
+  '.github/', // CI gates: gate-review.yml, deploy-prod.yml, secret scan, grade gate
+  'CODEOWNERS',
+  '.husky/', // pre-push/pre-commit gate delivery (secrets-allowlist.txt is AUTO, checked first)
+  '.claude/hooks/',
+  '.claude/settings.json',
+];
+
+// db.js is HARD-FLOOR only for the rank-tier brain (REQUIRES_RANK_TIER); every other
+// db.js change is NEEDS_TRUST (it is a huge, routinely-edited module — file-level
+// hard-flooring it would ping the owner for ordinary query work). This is the one
+// content-level rule; everything else is path-level.
+const DB_JS = 'src/bongos/db.js';
+const RANK_TIER_RE = /REQUIRES_RANK_TIER\s*=\s*\{[\s\S]*?\}/;
+
+// AUTO pure-removal surfaces — a NARROWING-only edit can only STRENGTHEN the gate, so
+// it may auto-pass for ANY author. Any non-narrowing edit falls through to its glob
+// classification (run-unit-tests.js → HARD FLOOR; secrets-allowlist.txt → .husky/ HARD FLOOR).
+const AUTO_NARROWING = {
+  'scripts/bongos/run-unit-tests.js': certifyRunUnitTestsNarrowing,
+  '.husky/secrets-allowlist.txt': certifyAllowlistNarrowing,
+};
+
+// task 1002874: compile through the authoritative module's FOLDING matcher, not
+// globToRegExp directly. Both of these used to build their own byte-exact regexes
+// from the raw globs and test raw candidates, so after protected-path matching
+// gained NFC + case-folding, an uppercased spelling of a gate surface still walked
+// past THIS classifier — the CI auto-merge gate — which is the bypass the fix
+// exists to close. isCanonicalPath below rejects non-NFC and non-ASCII, but it
+// does not case-fold, so it never covered this.
+const matchesHardFloor = compileGlobMatcher(HARD_FLOOR_GLOBS);
+
+// A path is "protected" per the authoritative module.
+const matchesProtected = compileGlobMatcher(PROTECTED_GLOBS);
+
+// Only [\x20-\x7e] path chars, NFC-stable, no leading/trailing whitespace. Defeats the
+// unicode-homoglyph + whitespace-alias evasions (red-team Holes 6/8).
+function isCanonicalPath(p) {
+  return typeof p === 'string' && p.length > 0 && /^[\x20-\x7e]+$/.test(p)
+    && p === p.normalize('NFC') && p === p.trim();
+}
+
+// AUTO certifier: run-unit-tests.js may auto-pass ONLY if its sole semantic change is
+// REMOVING entries from INTEGRATION/KNOWN_FAILING (un-muting tests) — never adding, and
+// the rest of the file byte-identical modulo those two set literals.
+function certifyRunUnitTestsNarrowing(base, head) {
+  if (base == null || head == null) return { pass: false, reason: 'added/removed wholesale — not a narrowing edit' };
+  const setOf = (t, name) => {
+    const m = new RegExp(`const ${name} = new Set\\(\\[([\\s\\S]*?)\\]\\)`).exec(t);
+    if (!m) return null;
+    return new Set([...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]));
+  };
+  const strip = (t) => t.replace(/const (INTEGRATION|KNOWN_FAILING) = new Set\(\[[\s\S]*?\]\)/g, 'SET');
+  if (strip(base) !== strip(head)) return { pass: false, reason: 'non-set code changed in run-unit-tests.js' };
+  for (const name of ['INTEGRATION', 'KNOWN_FAILING']) {
+    const b = setOf(base, name), h = setOf(head, name);
+    if (!b || !h) return { pass: false, reason: `cannot parse ${name} set — fail-closed` };
+    for (const x of h) if (!b.has(x)) return { pass: false, reason: `${name} ADDED '${x}' (muting a test)` };
+  }
+  return { pass: true };
+}
+
+// AUTO certifier: secrets-allowlist.txt may auto-pass ONLY if its head line set is a
+// subset of the base (removing/narrowing allowlist entries) — never adding a new exclude.
+function certifyAllowlistNarrowing(base, head) {
+  if (base == null || head == null) return { pass: false, reason: 'added/removed wholesale — not a narrowing edit' };
+  const norm = (t) => new Set(t.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
+  const b = norm(base), h = norm(head);
+  for (const line of h) if (!b.has(line)) return { pass: false, reason: `allowlist ADDED/BROADENED: ${line}` };
+  return { pass: true };
+}
+
+// ----------------------------------------------------------------------------------------
+// PURE CORE. Inputs are diff DATA (no git, no fs) so the whole policy is unit-tested:
+//   files:  [{ path, mode, deleted }]  — changed paths + git new-mode + delete flag
+//   blobAt: (which:'base'|'head', path) => string|null   — file content at base/head
+//   diffBytes: number                                    — total textual diff size
+// Returns { verdict:'pass'|'needs_trust'|'escalate', escalations:[{path,reason}],
+//           needsTrust:[{path,reason}], autoPassed:[path], surfaces:[path] }.
+// ----------------------------------------------------------------------------------------
+const MAX_DIFF_BYTES = Number(process.env.GATE_MAX_DIFF_BYTES || 2 * 1024 * 1024);
+
+function classifyChanges({ files, blobAt, diffBytes = 0 } = {}) {
+  const escalations = [];
+  const needsTrust = [];
+  const autoPassed = [];
+  const surfaces = [];
+
+  // --- Pre-flight, fail-closed (whole changed set) ---
+  for (const f of files || []) {
+    if (f.mode === '120000') escalations.push({ path: f.path, reason: 'symlink in diff — refused (alias evasion)' });
+    if (!isCanonicalPath(f.path)) escalations.push({ path: String(f.path), reason: 'non-ASCII/whitespace path — refused' });
+  }
+  if (diffBytes > MAX_DIFF_BYTES) {
+    escalations.push({ path: '<diff>', reason: `diff ${diffBytes}B exceeds ${MAX_DIFF_BYTES}B — too large to certify` });
+  }
+
+  for (const f of files || []) {
+    const p = f.path;
+    if (!isCanonicalPath(p)) continue; // already escalated above
+    // A gate surface = the authoritative PROTECTED_GLOBS, OR a hard-floor glob (some
+    // floor paths — gate-review.js itself, config/deploy.json, CODEOWNERS — are also
+    // added to PROTECTED_GLOBS, but OR-ing keeps the gatekeeper correct even if a
+    // future hard-floor entry isn't yet in the shared list), OR a tests/*.mjs file.
+    const isProtected = matchesProtected(p) || matchesHardFloor(p);
+    const isTest = /^tests\/.+\.mjs$/.test(p);
+    if (!isProtected && !isTest) continue; // not a gate surface
+
+    surfaces.push(p);
+
+    // tests/*.mjs: deleting or shrinking a test silently weakens the suite → NEEDS_TRUST
+    // (rank-trustable per the owner's model); adding/expanding is fine → PASS.
+    if (isTest && !isProtected) {
+      if (f.deleted) { needsTrust.push({ path: p, reason: 'test file DELETED — suite shrink' }); continue; }
+      const base = blobAt('base', p), head = blobAt('head', p);
+      if (base != null && head != null && head.length < base.length) {
+        needsTrust.push({ path: p, reason: 'test file SHRANK — possible muting' });
+      }
+      continue;
+    }
+
+    // AUTO pure-removal surfaces: certify a narrowing-only edit (any author).
+    if (Object.prototype.hasOwnProperty.call(AUTO_NARROWING, p)) {
+      const cert = AUTO_NARROWING[p](blobAt('base', p), blobAt('head', p));
+      if (cert.pass) { autoPassed.push(p); continue; }
+      // not a narrowing edit → fall through to HARD FLOOR (both AUTO files are floor globs)
+      escalations.push({ path: p, reason: `AUTO surface failed narrowing cert (${cert.reason}) — root-of-trust` });
+      continue;
+    }
+
+    // db.js: HARD FLOOR only when the rank-tier brain changed; else NEEDS_TRUST.
+    if (p === DB_JS) {
+      const base = blobAt('base', p), head = blobAt('head', p);
+      const region = (t) => { const m = t == null ? null : RANK_TIER_RE.exec(t); return m ? m[0] : (t == null ? '<absent>' : '<no-region>'); };
+      if (base == null || head == null) { needsTrust.push({ path: p, reason: 'db.js added/removed' }); continue; }
+      if (region(base) !== region(head)) {
+        escalations.push({ path: p, reason: 'db.js REQUIRES_RANK_TIER (rank brain) changed — root-of-trust' });
+      } else {
+        needsTrust.push({ path: p, reason: 'db.js change outside the rank-tier region' });
+      }
+      continue;
+    }
+
+    // HARD FLOOR globs → ESCALATE regardless of rank.
+    if (matchesHardFloor(p)) { escalations.push({ path: p, reason: 'gate machinery / deploy switch (hard floor) — owner review required' }); continue; }
+
+    // Any other protected surface → NEEDS_TRUST (rank-trustable).
+    needsTrust.push({ path: p, reason: 'sensitive gate surface — auto-merges for Metic+ (rank trust)' });
+  }
+
+  const verdict = escalations.length ? 'escalate' : (needsTrust.length ? 'needs_trust' : 'pass');
+  return { verdict, escalations, needsTrust, autoPassed, surfaces };
+}
+
+// Resolve the merge action from the verdict + the two trust signals (both injected by
+// the workflow, never read by the pure classifier). RANK trust (server-attested Metic+)
+// clears NEEDS_TRUST only; the HARD FLOOR (escalate) is cleared ONLY by an explicit
+// owner review — rank never bypasses it. An owner approval clears anything.
+//   pass        → 'pass'
+//   needs_trust → 'pass' iff (rank-trusted OR owner-approved)
+//   escalate    → 'pass' iff owner-approved
+function resolveAction({ verdict, trusted, ownerApproved }) {
+  if (verdict === 'pass') return 'pass';
+  if (verdict === 'escalate') return ownerApproved ? 'pass' : 'block';
+  return trusted || ownerApproved ? 'pass' : 'block';
+}
+
+// ----------------------------------------------------------------------------------------
+// CLI wrapper — gather the real diff and apply report-only / exit codes. Never returns 0
+// on an analyzer error (fail-closed). The rank/owner-approval resolution for NEEDS_TRUST
+// is provided by the workflow via GATE_AUTHOR_TRUSTED (set from the server-resolved rank /
+// owner approval); the pure core never reads rank.
+// ----------------------------------------------------------------------------------------
+function git(args) { return execFileSync('git', args, { encoding: 'utf8', maxBuffer: 128 * 1024 * 1024 }); }
+
+function gatherDiff(baseRef) {
+  const mb = git(['merge-base', baseRef, 'HEAD']).trim();
+  const raw = git(['diff', '--raw', `${mb}...HEAD`]).split('\n').filter(Boolean);
+  const files = [];
+  for (const line of raw) {
+    // ":100644 100644 sha sha M\tpath"  (status D = delete; mode 120000 = symlink)
+    const m = /^:(\d{6}) (\d{6}) \S+ \S+ (\S+)\t(.+)$/.exec(line);
+    if (!m) { files.push({ path: '<unparseable>', mode: '000000', deleted: false, parseError: true }); continue; }
+    const [, , newMode, status, rawPath] = m;
+    files.push({ path: rawPath, mode: newMode, deleted: status.startsWith('D') });
+  }
+  const diffBytes = Buffer.byteLength(git(['diff', `${mb}...HEAD`]), 'utf8');
+  const blobAt = (which, p) => {
+    const ref = which === 'base' ? mb : 'HEAD';
+    try { return git(['show', `${ref}:${p}`]); } catch { return null; }
+  };
+  return { files, blobAt, diffBytes };
+}
+
+async function main() {
+  const baseRef = process.env.GATE_BASE_REF || 'origin/main';
+  const reportOnly = process.env.GATE_REPORT_ONLY === '1';
+  const trusted = process.env.GATE_AUTHOR_TRUSTED === '1'; // set by the workflow from server-resolved rank / owner approval
+
+  let result;
+  try {
+    if ((process.env.GATE_FILES_JSON || '').trim()) {
+      // test/dry-run injection: {files, blobs:{ 'base:path':..., 'head:path':... }, diffBytes}
+      const inj = JSON.parse(process.env.GATE_FILES_JSON);
+      const blobAt = (which, p) => (inj.blobs && Object.prototype.hasOwnProperty.call(inj.blobs, `${which}:${p}`)) ? inj.blobs[`${which}:${p}`] : null;
+      result = classifyChanges({ files: inj.files, blobAt, diffBytes: inj.diffBytes || 0 });
+    } else {
+      const { files, blobAt, diffBytes } = gatherDiff(baseRef);
+      if (files.some((f) => f.parseError)) throw new Error('unparseable --raw diff line (fail-closed)');
+      result = classifyChanges({ files, blobAt, diffBytes });
+    }
+  } catch (e) {
+    console.error(`gate-review: analyzer error (fail-closed): ${e && e.stack ? e.stack : e}`);
+    process.exit(reportOnly ? 0 : 1);
+    return;
+  }
+
+  // Resolve the final action.
+  const ownerApproved = process.env.GATE_OWNER_APPROVED === '1';
+  const action = resolveAction({ verdict: result.verdict, trusted, ownerApproved });
+
+  const lines = [`## gate-review: ${result.verdict.toUpperCase()}${reportOnly ? ' (report-only)' : ''} → would ${action === 'pass' ? 'PASS' : 'BLOCK + ping owner'}`, ''];
+  if (result.surfaces.length) lines.push(`Gate surfaces touched: ${result.surfaces.length}`);
+  for (const e of result.escalations) lines.push(`- ESCALATE \`${e.path}\` — ${e.reason}`);
+  for (const n of result.needsTrust) lines.push(`- NEEDS-TRUST \`${n.path}\` — ${n.reason} → ${action === 'pass' ? 'PASS' : 'BLOCK (needs Metic+ attestation or owner approval)'}`);
+  for (const a of result.autoPassed) lines.push(`- AUTO-PASS \`${a}\` — pure narrowing (strengthens the gate)`);
+  if (!result.surfaces.length) lines.push('No gate surface touched — auto-merge.');
+
+  const out = lines.join('\n');
+  console.log(out);
+  if (process.env.GITHUB_STEP_SUMMARY) { try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, out + '\n'); } catch (_) { /* best-effort */ } }
+
+  if (action === 'block' && !reportOnly) {
+    await pingOwner(result).catch(() => {});
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+async function pingOwner(result) {
+  const url = process.env.DISCORD_GATE_APPROVALS_WEBHOOK;
+  const pr = process.env.GATE_PR_NUMBER;
+  if (!url || !pr) return;
+  const surfaces = [...new Set([...result.escalations, ...result.needsTrust].map((x) => x.path))].slice(0, 10).join(', ');
+  const body = { content: `gate-pr #${pr} — gate-surface change needs your review: ${surfaces}\nReview + approve the PR to land it.`, allowed_mentions: { parse: [] } };
+  await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+}
+
+module.exports = {
+  classifyChanges,
+  resolveAction,
+  certifyRunUnitTestsNarrowing,
+  certifyAllowlistNarrowing,
+  isCanonicalPath,
+  matchesHardFloor,
+  HARD_FLOOR_GLOBS,
+};
+
+if (require.main === module) main();