@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/api-alias-caller-scan.js

@@ -1,257 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/api-alias-caller-scan.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/api-alias-caller-scan.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-// api-alias-caller-scan.js — the detector behind the lowercase `/api/gds` CALLER ratchet
-// (task 1004064, from idea 1001030; the sibling of gds-literal-scan.js).
-//
-// WHY THIS EXISTS. Task 1003707 (criterion C3e of goal 1000073) moved 665 in-repo callers off the
-// permanent `/api/gds` alias onto the canonical `/api/bongos`. The ratchet that already guards the
-// rename, `legacy_gds_literals`, is CASE-SENSITIVE on the shouting acronym — deliberately, because
-// `GDS` is the word a newcomer trips over. So that metric read 1135 before the sweep and 1135
-// after it, and it was right to: the alias is spelled in lowercase.
-//
-// The consequence is the gap this file closes. The lowercase spelling is invisible to CI in BOTH
-// directions: the 665-caller sweep earned no credit, and — the half that matters — a caller written
-// against `/api/gds` tomorrow moves no number and reds no build. 1003707's own session log says it
-// plainly: "the 665 will quietly grow back". `tests/api_alias_exceptions.mjs` pins the callers that
-// were deliberately LEFT behind and why, but it polices the exceptions, not new offenders. That is
-// a ratchet's job.
-//
-// WHY A COUNT AND NOT ZERO. Every remaining occurrence has a reason, and most of them are reasons
-// that will never expire — the OAuth callbacks are registered in GitHub's and Discord's app
-// settings, the uptime poller is the one production caller proving the alias still answers, and
-// tests are what keep it exercised in CI. A zero-rule would demand deleting things that must not be
-// deleted. So this holds the line the same way its sibling does: the number may fall, never rise.
-//
-// WHAT IS NEVER COUNTED, and why each one. The exclusion list is not invented here — it is
-// 1003707's own worked-out list, transcribed from docs/session-logs/2026-09-16-task-1003707-api-gds-callers.md
-// so that a future move has to argue with a stated reason rather than with a leftover:
-//
-//   1. THE ALIAS CONTRACT (path-excluded). api-prefix.js and api-path-404.js ARE the alias; they
-//      cannot name it less often than they do.
-//   2. THE PINNED OAUTH CALLBACKS (path-excluded). routes/auth.js, provisioning.js and the scripts
-//      + skills that register the same callback for a new instance. These paths live in the GitHub
-//      and Discord app settings; a repo-only change silently breaks sign-in.
-//   3. THE LIVE PROOF (path-excluded). uptime-poller.js and smoke-gds.js exercise the alias on
-//      purpose — if nothing calls it, its eventual breakage is found by a user rather than by us.
-//      Note fitness-ratchets.js belongs here too: it is the GATE, and its builder-facing hint has
-//      to spell the alias out to tell anyone what they tripped over.
-//   4. THE RENAME GUARDRAILS (path-excluded). rename-history-check.js, rename-ledger-prose.js,
-//      gds-literal-scan.js, codemod-rename-src-gds.js, fitness-ratchets.js and THIS FILE name the
-//      old path because that is what they are for. Same principle as GDS_RULE_FILES next door: a
-//      gate that cannot state its own rule cannot explain itself.
-//   5. tests/ (path-excluded). Tests are what keeps the alias exercised in CI. Moving them off it
-//      would retire the alias by accident.
-//   6. THE FROZEN RECORD UNDER docs/ (path-excluded) — narrowed from a blanket `docs/` by task
-//      1004113, which is the scope call 1004064 deferred. docs/ is not one kind of thing: part of
-//      it is the RECORD of what we used to call the thing, and part of it is live instruction that
-//      still TEACHES a reader to call the alias. A blanket exclusion left the second unpoliced
-//      forever; a blind sweep would have destroyed the first.
-//      The line is not invented here — it is the one the repo already draws twice over. The
-//      subtrees excluded (docs/adr, docs/session-logs, docs/audits) are exactly the frozen-record
-//      path list in the sibling detector gds-literal-scan.js, and — measured, not assumed — all 134 per-file
-//      floors in config/rename-history-baseline.json fall inside them (adr 116, session-logs 15,
-//      audits 3) and NONE falls outside. Rewriting a file with a floor fails the build on purpose:
-//      an ADR rewritten to today's vocabulary destroys the evidence that the words changed.
-//      docs/governance joins them on the same reading: every file in it is a dated authority sweep
-//      or a payment PROOF — an audit filed under another name. docs/recipes/failed-ship-recovery-proof.md
-//      is the one file named individually, for the same reason: it is a transcript of a recovery
-//      that happened, and rewriting the calls it records would make it misreport them.
-//      Everything else under docs/ is now COUNTED, and 1004113 swept it.
-//   7. MIGRATIONS + THE FROZEN RECORD (path-excluded). Same rule as the sibling detector: an
-//      applied migration renamed is an applied migration re-run, and a rewritten ADR destroys the
-//      evidence that the words changed.
-//   8. A LINE THAT IS ABOUT THE ALIAS (line-excluded). Any line that ALSO names `/api/bongos`, or
-//      carries the words alias / legacy / permanent / forever, is commentary on the alias rather
-//      than a caller of it. This is the same rule 1003707's codemod used to decide what to leave,
-//      so the ratchet and the sweep agree by construction.
-//   9. CAPTURED FIXTURES (path-excluded). scripts/hall-preview/fixtures/*.json are snapshots of
-//      real API responses; rewriting one would make the fixture misreport what the server returned.
-//  10. A LINE NAMING AN AUTH URL (line-excluded, task 1004113). `/api/gds/auth/...` in prose is the
-//      SAME pinned callback reason 2 path-excludes in code, reached from the docs side: the
-//      Authorization callback URL registered in GitHub's app settings is `${publicOrigin}/api/gds/auth/web/callback`,
-//      and a recipe that teaches a builder to register anything else breaks sign-in for the
-//      instance they are standing up. Seven occurrences across four recipes turn on this, and they
-//      must not be swept to make a number fall. This is a LINE rule rather than a path rule
-//      because the files carrying them (ops-gotchas.md, local-dev.md, staging-environment.md)
-//      are otherwise ordinary live instruction that SHOULD be counted.
-//
-// Usage:
-//   node scripts/gds/api-alias-caller-scan.js            # count + the top offending files
-//   node scripts/gds/api-alias-caller-scan.js --files    # every file with its count
-//   node scripts/gds/api-alias-caller-scan.js --json
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { execFileSync } = require('node:child_process');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-
-// The alias, lowercase — the whole point of this detector, since its sibling is case-sensitive on
-// the shouting form and therefore blind to exactly this spelling.
-const ALIAS = '/api/gds';
-const ALIAS_RE = /\/api\/gds/g;
-
-// The canonical prefix. A line naming BOTH is commentary on the alias, not a caller of it.
-const CANONICAL = '/api/bongos';
-
-// Path exclusions, matched against the repo-relative path (forward slashes), at any depth.
-// Every entry maps to a numbered reason in the header above — keep them in step.
-const ALIAS_EXCLUDED_PATHS = [
-  // 1. the alias contract
-  /^src\/bongos\/api-prefix\.js$/,
-  /^src\/bongos\/api-path-404\.js$/,
-  // 2. the pinned OAuth callbacks + everything that registers them for a new instance
-  /^src\/bongos\/routes\/auth\.js$/,
-  /^modules\/provisioning\/provisioning\.js$/,
-  /^scripts\/gds\/(onboard|provision-net|dev|login)\.js$/,
-  /^modules\/lifecycle\/kickoff-checklist\.js$/,
-  /^modules\/public-landing\/public\/projects\.html$/,
-  /^\.claude\/skills\/new-project\/SKILL\.md$/,
-  // 3. the live proof that the alias still answers
-  /^src\/bongos\/uptime-poller\.js$/,
-  /^scripts\/gds\/smoke-gds\.js$/,
-  // 4. the rename guardrails — they name the old path on purpose
-  /^scripts\/gds\/(rename-history-check|rename-ledger-prose|gds-literal-scan|codemod-rename-src-gds|api-alias-caller-scan|fitness-ratchets)\.js$/,
-  /^config\/(fitness-baselines|rename-history-baseline)\.json$/,
-  // 5. tests keep the alias exercised in CI — the repo's own two spellings, `tests/` at the root
-  //    and a module's `tests/` or `test/` dir. Deliberately NOT a blanket `\.mjs$`: three .mjs
-  //    files are not tests (clients/bongos-client/index.mjs and its example, scripts/status-probe.mjs)
-  //    and the client is exactly the kind of caller this ratchet exists to police.
-  /(^|\/)tests?\//,
-  // 6. the FROZEN RECORD under docs/ — narrowed from a blanket `docs/` by task 1004113. These
-  //    three subtrees mirror the frozen-record path list in gds-literal-scan.js and are where all 134
-  //    rename-history floors live; docs/governance is dated audits + payment proofs under another
-  //    name, and the one named file is a transcript of a recovery that happened.
-  /(^|\/)docs\/adr\//,
-  /(^|\/)docs\/session-logs\//,
-  /(^|\/)docs\/audits\//,
-  /(^|\/)docs\/governance\//,
-  /^docs\/recipes\/failed-ship-recovery-proof\.md$/,
-  // 7. migrations + the frozen record
-  /(^|\/)migrations\//,
-  /(^|\/)limitations\//,
-  // 9. captured API-response fixtures
-  /(^|\/)fixtures\//,
-];
-
-// Vendored / generated / third-party trees — the same exclusion the sibling detector applies.
-const ALIAS_EXCLUDED_TREES = /(^|\/)(node_modules|public-docs)\/|\.min\.js$|(^|\/)vendor\//;
-
-// A line that is ABOUT the alias rather than a caller of it. Rule 8 above.
-const ALIAS_COMMENTARY_RE = /\balias\b|\blegacy\b|\bpermanent\b|\bforever\b/i;
-
-// A line naming an AUTH url under the alias. Rule 10 above: this is the pinned OAuth callback,
-// registered outside the repo, so it is a fact about GitHub's app settings rather than a caller
-// anyone may move. Kept as a line rule because the files it appears in are otherwise countable.
-// Two shapes: the URL itself, and prose ABOUT it — a heading such as "Authorized callback URL must
-// include the full /api/gds path" names the prefix without the /auth/ segment, and sweeping it left
-// the heading contradicting the body two lines below it. Caught in review on task 1004113; the rule
-// covers the heading rather than the heading being rewritten, because the heading is right.
-//
-// NARROWED after grade review on 1004113: the first cut of this was a bare `\bcallback\b`, which
-// excused ANY line carrying the word — "the webhook fires a callback to /api/gds/tasks" would have
-// gone silently uncounted, and a shrink-only ratchet whose exclusions can be triggered by a common
-// noun is not shrink-only. `callback URL` is the OAuth-registration phrase specifically, and the
-// negative cases below are tested, not just the positive ones.
-const ALIAS_PINNED_AUTH_RE = /\/api\/gds\/auth\/|\bcallback URL\b/i;
-
-function isExcludedPath(relPath) {
-  const p = relPath.replace(/\\/g, '/');
-  if (ALIAS_EXCLUDED_TREES.test(p)) return true;
-  return ALIAS_EXCLUDED_PATHS.some((re) => re.test(p));
-}
-
-// isCountedLine — a line naming the alias that is a CALLER rather than commentary. Exported so the
-// test and any future sweep share ONE decision (the gds-literal-scan precedent: a gate whose
-// detector drifts from its sweep is worse than no gate).
-function isCountedLine(line) {
-  if (!line.includes(ALIAS)) return false;
-  if (line.includes(CANONICAL)) return false;
-  if (ALIAS_COMMENTARY_RE.test(line)) return false;
-  if (ALIAS_PINNED_AUTH_RE.test(line)) return false;
-  return true;
-}
-
-// countInText — alias occurrences on counted lines only. A line can legitimately carry more than
-// one (two fetches, a usage banner), so occurrences are counted rather than lines: that is what
-// makes the number fall when a caller is actually moved.
-function countInText(text) {
-  let n = 0;
-  for (const line of String(text).split(/\r?\n/)) {
-    if (!isCountedLine(line)) continue;
-    n += (line.match(ALIAS_RE) || []).length;
-  }
-  return n;
-}
-
-function trackedFiles() {
-  const out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
-  return out.split('\n').map((s) => s.trim()).filter(Boolean);
-}
-
-// scanAliasCallers — { total, byFile, scanned } across every tracked, countable file.
-//
-// `scanned` is the NON-VACUITY channel, and it is the whole reason this function returns it. A
-// static scan breaks by finding nothing, and a green run looks identical to a working one: if
-// `git ls-files` returns nothing, or every path is excluded, this reports total 0 and a caller
-// that reads only `total` cannot tell a clean tree from a broken scanner. The ratchet and the test
-// both assert `scanned > 0`, so an enumeration that collapses fails LOUDLY instead of passing.
-//
-// `files` and `readFile` are injectable for tests, so the real aggregation — exclusions, the
-// commentary rule, per-file totals — is exercised without writing into the repo. The unit lane runs
-// test files in parallel; a test that edited a tracked file would break whichever suite happened to
-// be scanning the tree at that moment.
-function scanAliasCallers({ files = null, readFile = null } = {}) {
-  const read = readFile || ((relPath) => fs.readFileSync(path.join(ROOT, relPath), 'utf8'));
-  const byFile = {};
-  let total = 0;
-  let scanned = 0;
-  for (const relPath of files || trackedFiles()) {
-    if (isExcludedPath(relPath)) continue;
-    let text;
-    try {
-      text = read(relPath);
-    } catch {
-      continue;
-    }
-    if (text.includes(String.fromCharCode(0))) continue; // binary (a NUL byte)
-    scanned += 1;
-    const n = countInText(text);
-    if (n) {
-      byFile[relPath] = n;
-      total += n;
-    }
-  }
-  return { total, byFile, scanned };
-}
-
-function main() {
-  const { total, byFile, scanned } = scanAliasCallers();
-  const ranked = Object.entries(byFile).sort((a, b) => b[1] - a[1]);
-  if (process.argv.includes('--json')) {
-    process.stdout.write(`${JSON.stringify({ total, byFile, scanned }, null, 2)}\n`);
-    return;
-  }
-  const show = process.argv.includes('--files') ? ranked : ranked.slice(0, 20);
-  console.log(`in-repo /api/gds callers: ${total} across ${ranked.length} file(s) (${scanned} file(s) scanned)`);
-  console.log('(the alias contract, the pinned OAuth callbacks, the uptime poller + smoke, the rename guardrails,');
-  console.log(' tests/, the FROZEN RECORD under docs/ (adr, session-logs, audits, governance), migrations/ and');
-  console.log(' captured fixtures are excluded by construction; so is any line that also names /api/bongos, carries');
-  console.log(' the words alias / legacy / permanent / forever, or names a pinned /api/gds/auth/ callback URL.');
-  console.log(' The REST of docs/ is counted — live instruction that still teaches the alias should shrink.)');
-  console.log('');
-  for (const [f, n] of show) console.log(`  ${String(n).padStart(5)}  ${f}`);
-  if (show.length < ranked.length) console.log(`  … and ${ranked.length - show.length} more file(s) — pass --files for all`);
-}
-
-if (require.main === module) main();
-
-// Only what a consumer actually calls. The constants above stay module-private on purpose: an
-// export nobody imports reads as dead code to knip and costs a ratchet point for nothing, and the
-// rules are meant to be read here rather than re-implemented by a caller.
-module.exports = {
-  isExcludedPath,
-  isCountedLine,
-  countInText,
-  scanAliasCallers,
-};
+require('../bongos/forwarder.js').forward(module, 'api-alias-caller-scan.js');

package/scripts/gds/api-artifacts.js

@@ -0,0 +1,6 @@
+// scripts/gds/api-artifacts.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/api-artifacts.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'api-artifacts.js');

package/scripts/gds/api.js

@@ -1,86 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/api.js — cross-platform GDS API caller (#686).
-//
-// Replaces the bash `TOKEN=$(python3 -c ...)` + `curl ... | python3 -m json.tool`
-// (+ `jq`) pattern that skill command-blocks used — that pattern breaks on
-// Windows (no python3/curl/jq by default, and `$(...)` is bash-only). node is
-// the project's guaranteed runtime, and cli-lib.apiCall already resolves the
-// session token + API base, so there is no manual token extraction here.
-//
-// Usage:
-//   node scripts/gds/api.js GET  /api/bongos/inbox
-//   node scripts/gds/api.js POST /api/bongos/blockers/5/resolve --body '{"resolution_note":"fixed in #690"}'
-//   node scripts/gds/api.js POST /api/bongos/security/reports   --body-file report.json
-//   echo '{"verdict":"promote"}' | node scripts/gds/api.js PATCH /api/bongos/inbox/12 --body-file -
-//
-// The HTTP status goes to STDERR ("POST /path → 201"); the pretty-printed JSON
-// body goes to STDOUT, so `... | node -e ...` style piping stays clean. Exit 0
-// on a 2xx, 1 on any non-2xx or transport error, 2 on bad invocation.
-
-const fs = require('node:fs');
-const { cliClient, arg, stripBom, resolveQuiet, cliExit, repairMsysMangledPath } = require('./cli-lib');
-
-
-(async () => {
-  const method = (process.argv[2] || '').toUpperCase();
-  // task 1002809: Git Bash converts the leading-slash path arg into a Windows
-  // path under the Git install root before node sees it; undo that so builders
-  // don't need the MSYS_NO_PATHCONV=1 prefix.
-  const urlPath = repairMsysMangledPath(process.argv[3]);
-  if (!method || !urlPath || !urlPath.startsWith('/')) {
-    console.error("usage: node scripts/gds/api.js <METHOD> <path> [--body '<json>' | --body-file <file|->] [--quiet]");
-    process.exit(2);
-  }
-
-  // --quiet / GDS_QUIET: suppress the stderr status banner below. Default OFF —
-  // existing pipelines that scrape stderr for the status line are unaffected.
-  const quiet = resolveQuiet();
-
-  // Resolve an optional JSON request body. `--body-file -` reads stdin (the
-  // robust way to pass a body with awkward characters without shell quoting).
-  let body = null;
-  const bodyFile = arg('--body-file');
-  const bodyInline = arg('--body');
-  try {
-    let raw = null;
-    if (bodyFile != null) {
-      raw = stripBom(bodyFile === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(bodyFile, 'utf8'));
-    } else if (bodyInline != null) raw = bodyInline;
-    if (raw != null && raw.trim()) body = JSON.parse(raw);
-  } catch (e) {
-    console.error(`api: could not read/parse JSON body: ${e.message}`);
-    // task 1002809: inline --body is the usual culprit — shells (especially on
-    // Windows) strip or re-split the quotes before node sees them. Teach the
-    // durable pattern instead of leaving a bare parse error.
-    if (bodyFile == null && bodyInline != null) {
-      console.error('  Inline --body often loses its quoting through the shell. Durable pattern:');
-      console.error('  write the JSON to a file and pass --body-file <path>, or pipe it via --body-file -');
-    }
-    process.exit(2);
-  }
-
-  let res;
-  try {
-    // allowUnauthenticated so a 401 renders as a normal status row + exit 1
-    // (clear error) instead of the cli-lib global "run setup" short-circuit.
-    // Generic passthrough tool: the client's baseUrl is the versioned API prefix
-    // (/api/bongos/v1), so strip a legacy /api/gds|/api/bongos[/v1] prefix off the
-    // caller-supplied path and route the remainder through the escape hatch — no
-    // generated method exists for an arbitrary runtime path.
-    const api = await cliClient({ allowUnauthenticated: true });
-    const relPath = urlPath.replace(/^\/api\/(?:bongos\/v1|bongos|gds)/, '');
-    res = await api.request(method, relPath, body != null ? { body } : {});
-  } catch (e) {
-    console.error(`api: request failed: ${e.message}`);
-    return cliExit(1); // task 1002734: never process.exit() after a request
-  }
-  if (!quiet) console.error(`${method} ${urlPath} → ${res.status}`);
-  if (res.data !== undefined && res.data !== null) {
-    console.log(JSON.stringify(res.data, null, 2));
-  }
-  // task 1002734: process.exit() here aborted node 5/5 on Windows —
-  // "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c"
-  // — AFTER the JSON had already printed, so every caller that checks the exit code
-  // read a successful command as a failure. Set the code and let the loop drain.
-  cliExit(res.ok ? 0 : 1);
-})();
+// scripts/gds/api.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/api.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'api.js');

package/scripts/gds/api.ps1

@@ -1,26 +1,8 @@
-# scripts/gds/api.ps1 — PowerShell 5.1-safe wrapper around api.js.
-#
-# PS 5.1 wraps a native command's stderr into NativeCommandError records and sets
-# $? false even on a clean exit (api.js always prints its status banner to
-# stderr), so a plain `node scripts/gds/api.js ... 2>&1` looks like a failure when
-# it isn't. This wrapper discards stderr, strips a leading UTF-8 BOM, and writes
-# only the raw JSON to stdout so callers can `| ConvertFrom-Json` it directly.
-#
-# Usage: scripts/gds/api.ps1 <METHOD> <path> [--body '<json>' | --body-file <file>]
-
-$apiJs = Join-Path $PSScriptRoot 'api.js'
-$out = & node $apiJs @args 2>$null
-$exitCode = $LASTEXITCODE
-
-$text = $out -join "`n"
-if ($text.Length -gt 0 -and $text[0] -eq [char]0xFEFF) {
-    $text = $text.Substring(1)
-}
-
-if ($exitCode -ne 0) {
-    Write-Output "GDS-ERROR: scripts/gds/api.ps1 exited $exitCode"
-    exit $exitCode
-}
-
-Write-Output $text
-exit $exitCode
+# scripts/gds/api.ps1 -- @bongos-forwarder (task 1004848). Generated by
+# scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+# The real script is scripts/bongos/api.ps1. This forwarder keeps callers that still name
+# the old path working, and warns once so they get repointed. Task 1003706 removes it.
+if (-not $env:BONGOS_FORWARDER_WARNED) { Write-Warning '[bongos] scripts/gds/api.ps1 has moved to scripts/bongos/api.ps1. This old path still works for now, but update whatever called it. The forwarders in scripts/gds/ are removed in a later release.' }
+$env:BONGOS_FORWARDER_WARNED = '1'
+& (Join-Path $PSScriptRoot '..\bongos\api.ps1') @args
+exit $LASTEXITCODE