@bongos/core 1.17.0

package/README.md

@@ -0,0 +1,88 @@
+# Example
+
+A persistent, shared 16-bit pixel-art world — the e-commerce experience for [Off the Boats](https://example.com), powered by [Example](https://example.com).
+
+Project memory — architecture, scope, V1 limitations, future ideas, session log — lives in [`CLAUDE.md`](./CLAUDE.md). Read it before editing code.
+
+> **Reading this on GitHub?** [`builders.example.com`](https://builders.example.com) is the canonical place to read project docs — task refs (`#NNN`) render as working links there. GitHub is the code host: great for diffs and PRs, but a bare `#NNN` here links to a GitHub issue and 404s.
+
+## New builder? Start here
+
+### Before you start (prerequisites)
+
+You'll need three things on your machine first:
+
+- **Git** — the tool that copies the code down. Check with `git --version`; install from [git-scm.com](https://git-scm.com/downloads) if it's missing.
+- **Claude Code** — your pair-programmer for every session. Download the desktop app at [claude.com/download](https://claude.com/download) (Mac and Windows).
+- **A GitHub account with access to this repo** — the project is private, so an Archon must invite you first. Accept the emailed invitation before cloning. (The bootstrap script below also checks for Node ≥ 22 and Python ≥ 3.10, and prints the install command if either is missing — you don't need them installed *before* cloning.)
+
+### Step 0 — get the project onto your machine
+
+Clone the repo, then `cd` into it. Everything below runs from inside that folder:
+
+```sh
+git clone https://github.com/example-owner/example.git
+cd example
+```
+
+### Step 1 — bootstrap
+
+One command bootstraps a fresh clone end-to-end — toolchain checks, JS deps, local env file, and a GDS session via GitHub:
+
+```sh
+# macOS / Linux:
+./scripts/setup-builder.sh
+# Windows — or any OS (node is the one guaranteed runtime):
+node scripts/setup-builder.js
+```
+
+It checks Node ≥ 22 and Python ≥ 3.10 (prints the install command if either is missing), runs `npm ci`, copies `.env.local.example` to `.env.local` (optionally prompting for your Google AI Studio key — pass `--skip-keys` to leave it blank), and hands off to `node scripts/gds/setup.js` to authenticate against the GDS via the GitHub Device Flow. The script is idempotent: re-running on an already-set-up checkout reports "already done" rather than clobbering.
+
+When it finishes, open Claude Code and run `/builder-start` to see what tasks are claimable.
+
+## Secrets scanning
+
+We keep secrets (`.env` files, API keys, private keys) out of the repo with two layers:
+
+- **Pre-commit hook** ([`.husky/pre-commit`](./.husky/pre-commit)) — scans your *staged* changes before each commit and aborts if it finds a secret. Activate it **once per clone**:
+
+  ```sh
+  git config core.hooksPath .husky
+  ```
+
+  It always runs a built-in guard (blocks `.env`, `*.pem`, credential files, obvious key patterns). If [TruffleHog](https://github.com/trufflesecurity/trufflehog) is installed (`brew install trufflehog` on macOS; `scoop install trufflehog` / `choco install trufflehog` or the GitHub release on Windows) it also runs a deep scan; if not, it warns and lets the commit through — CI is the real gate.
+
+  > **Windows:** git runs the `.husky/pre-commit` hook through the Git-Bash `sh` bundled with Git for Windows, so the hook works if you installed Git for Windows (the usual case). If you don't have a `sh` available, the local hook silently no-ops — CI's full-history TruffleHog scan is then your only gate (and it always runs regardless of platform).
+
+- **CI scan** ([`.github/workflows/secrets-scan.yml`](./.github/workflows/secrets-scan.yml)) — every PR to `main` runs TruffleHog over the **full git history**. This must pass before merge.
+
+### If a commit is blocked, here's how to investigate
+
+1. **Read the output.** The hook prints the offending file(s) and why.
+2. **Is it a real secret?** Then it must never be committed. Remove it from the commit (`git restore --staged <file>`), move the value out of the repo — local secrets go in `.env.local` (gitignored; run `/builder-setup`), production secrets live on the droplet at `/etc/example/`. If it was *already committed in an earlier commit*, the history scan will keep failing until the history is scrubbed — flag this to Lars, since rewriting shared history needs care.
+3. **Is it a false positive?** (e.g. an example key in docs, a test fixture, a Stripe `pk_test_` publishable key.) Add a path regex — one per line — to [`.husky/secrets-allowlist.txt`](./.husky/secrets-allowlist.txt). Both the hook and CI read that allowlist. Keep entries narrow and only add them after confirming the match is genuinely not a secret.
+4. **Genuine emergency commit** (you're sure it's clean and need to move now): `git commit --no-verify` skips the local hook — but CI will still scan the PR, so this only defers the check, it doesn't bypass it.
+
+## If your CLI starts 401'ing
+
+GDS CLI calls (`node scripts/gds/start.js`, `claim.js`, `ship.js`, etc.) authenticate against `example.com` using a session token at `~/.config/otb/gds-session.json`. Migration 035 (V3.R38 / [#259](https://example.com/builders#/task/259)) put a 1-hour rolling TTL on every session — every authenticated request resets it, so an active session never silently expires. But after a long idle, a token revocation, or an auth-changing deploy (e.g. mig 035 itself when it landed), the local token can stop working.
+
+`apiCall` in `scripts/gds/cli-lib.js` detects HTTP 401 and exits with a clear recovery message rather than letting the failure cascade through downstream calls. When you see that message:
+
+1. **Re-auth via Device Flow:**
+
+   ```sh
+   node scripts/gds/setup.js --force
+   ```
+
+   This pre-flights `GET /api/gds/me` against your existing session before doing anything. If the token is valid, it tells you who you're authenticated as and exits. If the token is dead (401), it falls through to the Device Flow *automatically* — no second `--force` needed. Browser opens to `github.com/login/device`; paste the printed code, authorize as the right GitHub account, you're back.
+
+2. **If something feels off and you're not sure what,** run the doctor:
+
+   ```sh
+   node scripts/gds/doctor.js
+   ```
+
+   It checks session validity (`/me` returns 200, identity + rank), git plumbing (`core.hooksPath` resolves), repo state (on a branch, working-tree status), and environment files (`.env.local`, `~/.config/otb/env`). Green/red checklist, no arguments. Exits 0 if every check passes, 1 if any red.
+
+Mirrors the "if a commit is blocked" pattern above: actionable, single command, no guessing.

package/bin/bongos.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// bin/bongos.js — the Cloud Bongos CLI dispatcher.
+//
+// GDS-V4 · V4.R79 · task 1246 (Phase 1 of the `bongos` toolkit; epic 1245).
+//
+// A single `bongos <verb>` front door over the existing scripts/gds/* scripts —
+// the same actions the /builder-* slash-commands run inside Claude Code, now
+// usable from any terminal, VS Code, a Chromebook, or CI. This is deliberately a
+// THIN dispatcher: it spawns the target script with `process.execPath` (the one
+// guaranteed cross-platform runtime — no bash, #686) and forwards argv + exit
+// code. No auth/API logic lives here; the target scripts already share
+// scripts/gds/cli-lib.js.
+//
+// Phases 2-4 extend this same CLI with `shell`/`code` (VS Code Remote-SSH into
+// the dev box), a one-line installer + standalone binary, and instance-agnostic
+// `login`/`init`/`upgrade`.
+
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.join(__dirname, '..');
+const GDS_DIR = path.join(REPO_ROOT, 'scripts', 'gds');
+
+// Two runtimes, one dispatcher (V4.R81 / task 1248):
+//  • repo checkout / `npm i -g` → we run under `node`, and the sibling scripts
+//    are on disk beside us: spawn each under node (the original path).
+//  • compiled standalone binary (the `curl | sh` install — no Node, no repo) →
+//    process.execPath is the `bongos` binary itself, not node/bun, so there is
+//    nothing to spawn and no scripts on disk. The ON-RAMP verbs' scripts are
+//    bundled into the binary and run in-process (see BUNDLED_RUNNERS).
+// We distinguish by the basename of the running executable — a compiled binary
+// is named `bongos`, never `node`/`bun`.
+const EXEC_BASENAME = path.basename(process.execPath).toLowerCase();
+const COMPILED = !['node', 'node.exe', 'bun', 'bun.exe'].includes(EXEC_BASENAME);
+
+// The verbs whose scripts are bundled into the standalone binary: just enough to
+// get a user from a bare laptop onto a real environment. Each value is a LAZY
+// require — never evaluated in the spawn (repo/npm) path, so requiring bongos.js
+// has no side effects there; a bundler (bun/deno/sea) still sees the static paths
+// and embeds these modules + their deps. Work verbs (ship/claim/start/status/
+// recall/cost/release/module/package-core) and doctor are deliberately NOT here:
+// bundling their heavy, repo-coupled trees would bloat the binary, and they need
+// a repo to run anyway.
+const BUNDLED_RUNNERS = {
+  'login.js': () => require('../scripts/gds/login.js'),
+  'setup.js': () => require('../scripts/gds/setup.js'),
+  'reauth.js': () => require('../scripts/gds/reauth.js'),
+  'api.js': () => require('../scripts/gds/api.js'),
+  'shell.js': () => require('../scripts/gds/shell.js'),
+  'code.js': () => require('../scripts/gds/code.js'),
+  'init.js': () => require('../scripts/gds/init.js'),
+  'onboard.js': () => require('../scripts/gds/onboard.js'),
+};
+
+// The bongos CLI's OWN release version is config/bongos-cli.json's `version` (the
+// release the compiled binaries are cut from — what `bongos version` should
+// report). Fall back to the repo package.json, then a placeholder. Both are
+// static requires so a bundler embeds them into the standalone binary.
+let VERSION = '0.0.0';
+try { VERSION = require('../config/bongos-cli.json').version || VERSION; } catch { /* best-effort */ }
+if (VERSION === '0.0.0') { try { VERSION = require('../package.json').version || VERSION; } catch { /* best-effort */ } }
+
+// verb -> { script, prefixArgs?, group, summary }
+//   `script`     a file under scripts/gds/ (or api.js for actions with no
+//                dedicated builder script yet).
+//   `prefixArgs` inserted before the user's args — used to drive the generic
+//                api.js caller (e.g. waking your box is just POST /box/ensure).
+const VERBS = {
+  start:   { script: 'start.js',   group: 'work', summary: 'List tasks you can claim right now' },
+  claim:   { script: 'claim.js',   group: 'work', summary: 'Claim a task by id  (bongos claim 1246)' },
+  ship:    { script: 'ship.js',    group: 'work', summary: 'Grade, merge, and deploy your claimed task' },
+  release: { script: 'release.js', group: 'work', summary: 'Cancel a claim — task returns to ready (no credits)' },
+  status:  { script: 'status.js',  group: 'work', summary: 'Version / criterion progress  (bongos status C8)' },
+  recall:  { script: 'recall.js',  group: 'work', summary: 'Search the docs + project knowledge  (bongos recall "x")' },
+  cost:    { script: 'cost.js',    group: 'work', summary: 'Log a cost entry' },
+
+  login:   { script: 'login.js',  group: 'account', summary: 'Sign in to an instance  (bongos login <url> — browser click, no paste)' },
+  setup:   { script: 'setup.js',  group: 'account', summary: 'Full builder setup on this instance (art key, disciplines, consent)' },
+  reauth:  { script: 'reauth.js', group: 'account', summary: 'Refresh your session' },
+  doctor:  { script: 'doctor.js', group: 'account', summary: 'Check your local toolchain + session' },
+  box:     { script: 'api.js', prefixArgs: ['POST', '/api/gds/box/ensure'], group: 'account', summary: 'Turn on / wake your cloud dev box' },
+  shell:   { script: 'shell.js', group: 'account', summary: 'Open a terminal on your dev box  (--local for a local clone)' },
+  code:    { script: 'code.js',  group: 'account', summary: 'Open VS Code on your dev box over Remote-SSH  (--local for a local clone)' },
+
+  init:    { script: 'init.js', group: 'instance', summary: 'Scaffold a new instance (config + first version + kickoff tasks)' },
+  onboard: { script: 'onboard.js', group: 'instance', summary: 'Guided zero-to-live walkthrough: init → scaffold → provision → OAuth → verify → brand' },
+  module:  { script: 'module.js', group: 'instance', summary: 'Scaffold a new module  (bongos module new <key>)' },
+  upgrade: { script: 'upgrade.js', group: 'instance', summary: 'Pull the core to a new version (bump pin→install→migrate→materialize→restart); bare = module-compat pre-check' },
+  'package-core': { script: 'package-core.js', group: 'instance', summary: 'Package the core as a versioned, installable artifact (+ pin manifest)' },
+  exec:    { script: null, group: 'instance', summary: 'Run a core script inside the package  (bongos exec scripts/gds/<x>.js [args])' },
+};
+
+// `bongos exec <relpath> [args]` — resolve a script by its repo-relative path INSIDE the core
+// package and run it. This is what lets a materialized skill/hook reach a core CLI that has no
+// dedicated verb (ADR 0108 §3 / W3): once the core installs from node_modules, `node scripts/gds/x.js`
+// from the instance root can't find the script (it's in the package), but `bongos exec scripts/gds/x.js`
+// resolves it under the package root. Constrained to paths that stay within the package (no `..`
+// escape, no absolute paths) so it can only run core code.
+function resolveExecTarget(relpath) {
+  if (!relpath || path.isAbsolute(relpath)) return null;
+  const abs = path.resolve(REPO_ROOT, relpath);
+  const within = abs === REPO_ROOT || abs.startsWith(REPO_ROOT + path.sep);
+  return within ? abs : null;
+}
+
+const GROUPS = [
+  ['work', 'Work'],
+  ['account', 'Account & environment'],
+  ['instance', 'Instance setup'],
+];
+
+function helpText() {
+  const lines = [];
+  lines.push('bongos — the Cloud Bongos CLI');
+  lines.push('');
+  lines.push('Usage:  bongos <command> [args]');
+  for (const [key, label] of GROUPS) {
+    lines.push('');
+    lines.push(`${label}:`);
+    for (const [verb, def] of Object.entries(VERBS)) {
+      if (def.group !== key) continue;
+      lines.push(`  ${verb.padEnd(10)} ${def.summary}`);
+    }
+  }
+  lines.push('');
+  lines.push('  help        Show this help');
+  lines.push('  version     Show the bongos version');
+  lines.push('');
+  lines.push('Inside Claude Code the same actions are the /builder-* slash-commands.');
+  return lines.join('\n');
+}
+
+// Returns the process exit code (does not call process.exit, so it's testable).
+function main(argv) {
+  const args = argv.slice(2);
+  const verb = args[0];
+
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h') {
+    process.stdout.write(helpText() + '\n');
+    return 0;
+  }
+  if (verb === 'version' || verb === '--version' || verb === '-v') {
+    process.stdout.write(`bongos ${VERSION}\n`);
+    return 0;
+  }
+
+  const def = VERBS[verb];
+  if (!def) {
+    process.stderr.write(`bongos: unknown command "${verb}"\n\n` + helpText() + '\n');
+    return 2;
+  }
+
+  // `bongos exec <relpath> [args]` — run a core script by its package-relative path (see above).
+  if (verb === 'exec') {
+    if (COMPILED) {
+      process.stderr.write('bongos: "exec" needs the full package on disk, which the standalone binary does not carry.\n');
+      return 2;
+    }
+    const target = resolveExecTarget(args[1]);
+    if (!target) {
+      process.stderr.write('bongos: exec needs a package-relative script path, e.g. `bongos exec scripts/gds/api.js GET /api/gds/me` (no absolute paths, no `..`).\n');
+      return 2;
+    }
+    const res = spawnSync(process.execPath, [target, ...args.slice(2)], { stdio: 'inherit' });
+    if (res.error) { process.stderr.write(`bongos: exec failed: ${res.error.message}\n`); return 1; }
+    return res.status == null ? 1 : res.status;
+  }
+
+  const scriptPath = path.join(GDS_DIR, def.script);
+  const forwarded = [...(def.prefixArgs || []), ...args.slice(1)];
+
+  if (COMPILED) return runBundled(verb, def, forwarded);
+
+  const res = spawnSync(process.execPath, [scriptPath, ...forwarded], { stdio: 'inherit' });
+  if (res.error) {
+    process.stderr.write(`bongos: failed to run "${verb}": ${res.error.message}\n`);
+    return 1;
+  }
+  if (res.signal) {
+    process.stderr.write(`bongos: "${verb}" terminated by signal ${res.signal}\n`);
+    return 1;
+  }
+  return res.status == null ? 1 : res.status;
+}
+
+// Compiled-binary dispatch: run a bundled on-ramp script in-process. Returns a
+// numeric code ONLY for the "not on-ramp" refusal; on a real dispatch it returns
+// undefined so the entry wrapper does NOT process.exit — the bundled script's
+// main() is often async and exits (or drains the event loop) on its own.
+function runBundled(verb, def, forwarded) {
+  const runner = BUNDLED_RUNNERS[def.script];
+  if (!runner) {
+    process.stderr.write(
+      `bongos: "${verb}" needs the full project (git + a repo clone), which the standalone binary doesn't carry.\n\n` +
+        `Get onto a real environment first, then run it there:\n` +
+        `  bongos login <instance-url>   sign in to an instance\n` +
+        `  bongos code                   open VS Code on your cloud dev box (has everything)\n` +
+        `  bongos shell                  open a terminal on your cloud dev box\n` +
+        `  bongos init                   scaffold a new instance here\n\n` +
+        `The standalone binary covers the on-ramp: login, box, shell, code, init, reauth.\n`
+    );
+    return 2;
+  }
+  // Hand the bundled script the argv it expects (it reads process.argv.slice(2)),
+  // then require it — which runs its top-level main().
+  process.argv = [process.execPath, path.join(GDS_DIR, def.script), ...forwarded];
+  runner();
+  return undefined;
+}
+
+if (require.main === module) {
+  const code = main(process.argv);
+  // A numeric return means "exit now with this code" (help / version / a spawned
+  // verb / unknown / the compiled not-on-ramp refusal). A compiled in-process
+  // dispatch returns undefined: we leave the event loop alone so the async
+  // bundled command can finish and exit itself.
+  if (typeof code === 'number') process.exit(code);
+}
+
+module.exports = { VERBS, GROUPS, helpText, main, VERSION, GDS_DIR, COMPILED, BUNDLED_RUNNERS, resolveExecTarget };

package/clients/bongos-client/README.md

@@ -0,0 +1,48 @@
+# @cloudbongos/client
+
+A **generated**, zero-dependency typed client for the Bongos API — produced from
+`docs/api/openapi.json` by `scripts/gds/gen-api-client.js` (ADR 0118). Do not edit
+by hand; it regenerates when the spec changes, so it can never drift from the routes.
+
+- API version: **v1** (served at `/api/bongos/v1`)
+- 224 operations across 40 resource groups
+
+## Install
+
+```bash
+npm install @cloudbongos/client   # internal registry / workspace path
+```
+
+## Use
+
+```js
+import { createClient, ApiError } from '@cloudbongos/client';
+
+const api = createClient({
+  baseUrl: 'https://example.com/api/bongos/v1', // or omit for same-origin (browser)
+  token: <redacted>,             // Authorization: Bearer <token>
+});
+
+try {
+  const first = await api.me.getMe();               // GET /me
+  const item = await api.tasks.getTasksId({ id: 1988 });   // GET /tasks/{id}
+  const created = await api.tasks.postTasks({ body: { version_id: '…', title: '…' } }); // POST /tasks
+  const page = await api.tasks.getTasks({ query: { limit: 25, offset: 0 } }); // GET /tasks
+} catch (e) {
+  if (e instanceof ApiError) console.error(e.code, e.status, e.details); // the ADR-0116 envelope
+}
+```
+
+Every method takes one `args` object: path params by name (e.g. `{ id }`), plus
+optional `query`, `body`, and `headers`. A non-2xx response throws `ApiError`
+carrying the envelope's `code` / `message` / `details` and the HTTP `status`.
+
+## Authenticate + a runnable hello-world
+
+How to get a `token` (Device Flow for a headless program, or a portal-issued
+bearer) and a copy-paste-runnable proof are in the on-ramp guide:
+**`docs/api-onramp.md`**. The example lives next to this client:
+
+```bash
+node clients/bongos-client/examples/hello-world.mjs   # public read — no token needed
+```