@bongos/core 1.21.174 → 1.21.176

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

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+'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). smoke-gds.js exercises 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/bongos/api-alias-caller-scan.js            # count + the top offending files
+//   node scripts/bongos/api-alias-caller-scan.js --files    # every file with its count
+//   node scripts/bongos/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|bongos)\/(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
+  /^scripts\/(?:gds|bongos)\/smoke-gds\.js$/,
+  // 4. the rename guardrails — they name the old path on purpose
+  /^scripts\/(?:gds|bongos)\/(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)
+  //    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,
+};

package/scripts/bongos/api-artifacts.js

@@ -0,0 +1,91 @@
+'use strict';
+// scripts/bongos/api-artifacts.js — the generated API spec, reference and typed client,
+// built in memory from the live route files (task 1004866).
+//
+// These eight files used to be COMMITTED and regenerated + re-committed on every ship
+// ("chore(api-client): auto-regenerate typed client" ~175 times in four months), with a
+// merge driver just to resolve their conflicts. They are now gitignored: nothing in git
+// holds them, and every consumer builds them from the routes instead —
+//   • package-core.js generates them into every core tarball (provisioning vendors it,
+//     ADR 0292), and refuses to build if generation fails;
+//   • serve-internal.js / the ui-design kit generate them in-process when the file is absent;
+//   • the unit suite and fitness call buildApiArtifacts() / ensureApiArtifacts().
+//
+// docs/routes-permissions.md is ALSO written by gen-api-docs.js, but it is a constant
+// pointer stub that stays committed (it is not in this set).
+//
+// Usage:
+//   node scripts/bongos/api-artifacts.js            # write any missing/stale copy into the docs root
+//   node scripts/bongos/api-artifacts.js --list     # print the eight paths
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The eight generated, NOT-committed paths (relative to the docs root). .gitignore lists
+// exactly these; tests/api_artifacts.mjs pins the two lists together.
+const API_ARTIFACT_PATHS = Object.freeze([
+  'docs/api/openapi.json',
+  'docs/api-reference.md',
+  'clients/bongos-client/index.mjs',
+  'clients/bongos-client/index.cjs',
+  'clients/bongos-client/bongos-client.global.js',
+  'clients/bongos-client/index.d.ts',
+  'clients/bongos-client/package.json',
+  'clients/bongos-client/README.md',
+]);
+
+// Build all eight in memory from the route files. Throws (never returns a partial set)
+// when the spec is not valid OpenAPI 3.1 or any file comes out empty, so a caller that
+// packs or serves the result can fail loudly instead of shipping a hole.
+function buildApiArtifacts() {
+  const docs = require('./gen-api-docs.js');
+  const client = require('./gen-api-client.js');
+  const built = docs.build();
+  const problems = docs.validateOpenapi(built.spec);
+  if (problems.length) throw new Error(`generated spec is not valid OpenAPI 3.1: ${problems.join('; ')}`);
+  const out = {};
+  for (const f of built.files) if (API_ARTIFACT_PATHS.includes(f.rel)) out[f.rel] = f.content;
+  const c = client.build(built.spec);
+  for (const [name, content] of Object.entries(c.files)) out[`clients/bongos-client/${name}`] = content;
+  for (const rel of API_ARTIFACT_PATHS) {
+    if (typeof out[rel] !== 'string' || out[rel].length === 0) throw new Error(`generation produced no ${rel}`);
+  }
+  return out;
+}
+
+// Write every artifact that is missing or differs under `root` (default: the docs root
+// the generators use). Each write goes to a temp file and is renamed over the target, so
+// a reader never sees a half-written client. Returns the relative paths written.
+function ensureApiArtifacts({ root } = {}) {
+  const dest = root || require('../../src/instance-config').resolveDocsRoot();
+  const files = buildApiArtifacts();
+  const written = [];
+  for (const rel of API_ARTIFACT_PATHS) {
+    const abs = path.join(dest, rel);
+    let cur = null;
+    try { cur = fs.readFileSync(abs, 'utf8'); } catch { /* absent */ }
+    if (cur === files[rel]) continue;
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const tmp = `${abs}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, files[rel]);
+    fs.renameSync(tmp, abs);
+    written.push(rel);
+  }
+  return written;
+}
+
+module.exports = { API_ARTIFACT_PATHS, buildApiArtifacts, ensureApiArtifacts };
+
+if (require.main === module) {
+  if (process.argv.includes('--list')) {
+    for (const p of API_ARTIFACT_PATHS) console.log(p);
+  } else {
+    try {
+      const w = ensureApiArtifacts();
+      console.log(`api-artifacts: ${w.length ? `wrote ${w.join(', ')}` : 'all eight already current'}.`);
+    } catch (e) {
+      console.error(`api-artifacts: generation FAILED — ${e.message}`);
+      process.exit(1);
+    }
+  }
+}

package/scripts/bongos/api.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos/api.js GET  /api/bongos/inbox
+//   node scripts/bongos/api.js POST /api/bongos/blockers/5/resolve --body '{"resolution_note":"fixed in #690"}'
+//   node scripts/bongos/api.js POST /api/bongos/security/reports   --body-file report.json
+//   echo '{"verdict":"promote"}' | node scripts/bongos/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/bongos/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);
+})();

package/scripts/bongos/api.ps1

@@ -0,0 +1,26 @@
+# scripts/bongos/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/bongos/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/bongos/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/bongos/api.ps1 exited $exitCode"
+    exit $exitCode
+}
+
+Write-Output $text
+exit $exitCode