@bongos/core 1.17.0

package/scripts/gds/cli-lib.js

@@ -0,0 +1,518 @@
+// Shared helpers for GDS CLI scripts (the things the builder-* slash commands invoke).
+// Renamed from PMS in V3.R01.
+//
+// - Reads / writes the session token at ~/.config/otb/gds-session.json
+//   (resolved via os.homedir(), so this works for any user on any machine).
+//   The legacy path ~/.config/otb/pms-session.json is still accepted on read,
+//   purely so any existing pre-rename session keeps working through the
+//   rollout — that's read-only back-compat, not a personalization.
+// - Provides apiCall(method, path, body) with the auth header
+// - Provides format helpers for terminal output (no deps; this isn't a TTY app,
+//   it's text the slash command consumes)
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const ic = require('../../src/instance-config');
+
+// Session token path — the WRITE target is the configured instance dir
+// (~/.config/<configDir>/gds-session.json; OTB → ~/.config/otb, unchanged). On
+// READ we try that file across every config read dir (configured + legacy otb),
+// then the legacy `pms-session.json` filename across the same dirs — so a
+// pre-rename session, or one written by a differently-namespaced instance, still
+// resolves (R61 / task 1200). os.homedir() keeps it per-user on any machine.
+const SESSION_PATH = ic.configPath('gds-session.json');
+const SESSION_READ_PATHS = [
+  ...ic.configReadPaths('gds-session.json'),
+  ...ic.configReadPaths('pms-session.json'),
+];
+// Default to live production. Override with <PREFIX>_API_BASE for local dev:
+//   CLOUDBONGOS_API_BASE=http://localhost:3000 node scripts/gds/start.js
+// Resolves the configured prefix first, then legacy GDS_/OTB_/PMS_API_BASE.
+const API_BASE = ic.resolveEnv('API_BASE') || 'https://amazonprimea.com';
+
+async function readSessionFile(p) {
+  try {
+    const raw = await fsp.readFile(p, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function loadSession() {
+  // Try each read path in priority order (configured dir's gds-session.json,
+  // legacy otb dir, then the legacy pms-session.json filename). We do NOT migrate
+  // the file on read — it gets written at SESSION_PATH next time the user re-auths
+  // or saveSession runs.
+  for (const p of SESSION_READ_PATHS) {
+    const s = await readSessionFile(p);
+    if (s) return s;
+  }
+  return null;
+}
+
+async function saveSession(session) {
+  const dir = path.dirname(SESSION_PATH);
+  await fsp.mkdir(dir, { recursive: true });
+  await fsp.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+
+function loadSessionSync() {
+  for (const p of SESSION_READ_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch (_) {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+// ---- argv helpers (C11) ---------------------------------------------------
+// One home for the flag parsing every GDS CLI rolled by hand. Two contracts:
+//   arg(name)     → the flag's VALUE ('--out x' or '--out=x'), else null
+//   hasFlag(name) → boolean presence ('--json', '--no-write')
+// Both default `args` to process.argv.slice(2). arg() accepts BOTH the space and
+// `=` forms (the superset — space-only callers gain `=` for free, harmlessly).
+// A presence flag wants hasFlag(), NOT arg() — they are opposite contracts
+// (repo-metrics.js learned this the hard way; do not collapse the two).
+function arg(name, args = process.argv.slice(2)) {
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  if (eq != null) return eq.slice(name.length + 1);
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+function hasFlag(name, args = process.argv.slice(2)) {
+  return args.includes(name);
+}
+
+// readSessionToken() — the { token, apiBase } a token-only raw fetch needs, read
+// synchronously from the session file. Distinct from API_BASE: apiBase here also
+// honors the PERSISTED session api_base (written by setup.js) AFTER the env
+// overrides — <PREFIX>_API_BASE (incl. legacy GDS_/PMS_) || session.api_base ||
+// default. Returns null when not signed in. Callers that must FAIL OPEN (e.g. the
+// sound player) use this + their own fetch rather than apiCall (which exits on 401).
+function readSessionToken() {
+  const j = loadSessionSync();
+  if (!j || !j.token) return null;
+  return {
+    token: j.token,
+    apiBase: ic.resolveEnv('API_BASE') || j.api_base || 'https://amazonprimea.com',
+  };
+}
+
+// Track whether we've already surfaced an auth-broken message this process so
+// repeated calls (e.g. a script that fires several apiCalls in a row) only
+// print the helpful guidance once before exiting.
+let _unauthExitInFlight = false;
+
+function printUnauthGuidanceAndExit() {
+  // Stable, single-screen guidance. Builders should see exactly this when
+  // their CLI session breaks — no raw API JSON, no stack trace.
+  console.error('');
+  console.error('✖ Your GDS CLI session is no longer valid.');
+  console.error('');
+  console.error('  Recover the fast (UI-first) way — run /builder-reauth, or:');
+  console.error('    node scripts/gds/reauth.js');
+  console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
+  console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
+  console.error('  Fallback (terminal Device Flow): node scripts/gds/setup.js --force');
+  console.error('');
+  console.error('  Possible causes:');
+  console.error('    - Your session token expired (24h idle TTL, auto-refreshes on each request)');
+  console.error('    - Your token was revoked by an Archon');
+  console.error('    - A recent deploy applied an auth-changing migration (see deploy banner)');
+  console.error('');
+  console.error('  Once re-authed, re-run whichever command you were trying.');
+  console.error('  For a full diagnosis, run: node scripts/gds/doctor.js');
+  console.error('');
+  process.exit(2);
+}
+
+// task 1050 (C): is this response the dev-box bootstrap-scoped 403? A box's baked
+// session (source='box', #919/ADR 0053) may only call the 4 on-box bootstrap
+// endpoints; everything else (claim/ship/me/…) returns 403 { error: 'box_scope' }.
+// Pure + exported so the detector is unit-tested.
+function isBoxScope(res) {
+  return !!res && res.status === 403 && !!res.data && res.data.error === 'box_scope';
+}
+
+let _boxScopeExitInFlight = false;
+
+// task 1050 (C): a box_scope 403 used to surface as a raw `failed to load
+// profile: { error: 'box_scope', … }` dump (the #1027 nightmare's first wall).
+// Turn it into the same UI-first guided recovery as a broken session: tell the
+// builder this is a bootstrap-only box session and walk them to re-auth. PRINT
+// only (no auto-open: the command runs ON the box, but the builder's browser is
+// on their own machine — they open the hall there).
+function printBoxScopeGuidanceAndExit() {
+  console.error('');
+  console.error('✖ This is a box-scoped session — it can only run dev-box bootstrap calls,');
+  console.error('  not claim / ship / grade / etc. (the box holds no full-authority token by');
+  console.error('  design — ADR 0053). Re-auth to a real CLI session, then re-run:');
+  console.error('');
+  console.error('    /builder-reauth      (or: node scripts/gds/reauth.js)');
+  console.error('');
+  console.error('  It opens your Settings page (https://amazonprimea.com/builders/settings) on');
+  console.error('  YOUR machine — under "CLI Access" click "Re-issue CLI token", copy the one-liner, paste it back.');
+  console.error('  No terminal Device Flow. Once re-authed, re-run whichever command you were');
+  console.error('  trying — if it had already done work, it resumes from where it stopped (task 941).');
+  console.error('');
+  process.exit(10); // 10 = "re-auth needed" (matches reauth.js's exit code)
+}
+
+/**
+ * Make an authenticated request to the GDS API.
+ *
+ * Default behavior on HTTP 401: print clear actionable guidance and exit(2).
+ * Callers can opt out by passing { allowUnauthenticated: true } when 401 is a
+ * legitimate response they want to handle (e.g. setup.js pre-flighting /me to
+ * decide whether to re-auth automatically).
+ */
+async function apiCall(method, urlPath, body = null, opts = {}) {
+  const { allowUnauthenticated = false, allowBoxScope = false } = opts;
+  const session = await loadSession();
+  // Instance-agnostic base (V4.R83 / task 1250): `bongos login <instance>` writes
+  // that instance's origin to session.api_base, so every later command targets it.
+  // Precedence mirrors readSessionToken: an explicit <PREFIX>_API_BASE env wins
+  // (local dev / staging override), then the logged-in instance, then prod. OTB
+  // sessions already store api_base='https://amazonprimea.com', so this is a no-op
+  // for the OTB instance and only bites once someone logs in to a different one.
+  const base = ic.resolveEnv('API_BASE') || (session && session.api_base) || 'https://amazonprimea.com';
+  const headers = {
+    'Content-Type': 'application/json',
+    'User-Agent': 'amazonprimea-gds-cli/1.0',
+  };
+  if (session && session.token) {
+    headers['Authorization'] = `Bearer ${session.token}`;
+  }
+  // The Anthropic-identity pin was removed (task 1039, idea 258): we no longer
+  // send X-Anthropic-User, because the server no longer cross-checks it. The
+  // reward is a uniform server-side valuation (ADR 0054), not per-Anthropic-
+  // account billing, so identity is not an auth boundary. anthropic_user_id is
+  // still kept in the session as cosmetic attribution; it is simply not
+  // transmitted as a header.
+  const res = await fetch(`${base}${urlPath}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : null,
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch (_) {
+    data = { raw: text };
+  }
+  if (res.status === 401 && !allowUnauthenticated && !_unauthExitInFlight) {
+    _unauthExitInFlight = true;
+    printUnauthGuidanceAndExit();
+  }
+  // task 1050 (C): a box-scoped session hitting a non-bootstrap endpoint gets a
+  // guided re-auth path instead of a raw box_scope dump. allowUnauthenticated
+  // opts out (e.g. a probe that wants to inspect the 403 itself).
+  if (isBoxScope({ status: res.status, data }) && !allowBoxScope && !allowUnauthenticated && !_boxScopeExitInFlight) {
+    _boxScopeExitInFlight = true;
+    printBoxScopeGuidanceAndExit();
+  }
+  return { status: res.status, ok: res.ok, data };
+}
+
+// task 1996 (R09): the ONE HTTP client. cliClient() returns the generated typed
+// client (clients/bongos-client — ADR 0118) configured for the CLI:
+//   • baseUrl  — the session-resolved instance origin + the versioned API prefix
+//                (/api/bongos/v1), so paths are the spec-relative /tasks/… form.
+//   • token    — the session bearer.
+//   • throwOnError:false — every call resolves to { status, ok, data } (never
+//     throws on HTTP status; network errors still reject), so the long-standing
+//     apiCall contract holds and status-inspecting callers port 1:1.
+//   • fetch    — a wrapper that keeps apiCall's behavior: the amazonprimea CLI
+//     User-Agent, plus the 401 and box_scope 403 auto-exit guidance.
+// Named methods (api.tasks.getTasksId({ id })) replace hand-built apiCall paths;
+// api.request(method, path, opts) is the escape hatch for non-spec routes.
+// The generated client is ESM; we import() it once and cache per (base, token,
+// opts) — CommonJS callers just `const api = await cliClient()`.
+let _clientModPromise = null;
+const _clientCache = new Map();
+async function cliClient(opts = {}) {
+  const { allowUnauthenticated = false, allowBoxScope = false } = opts;
+  const session = await loadSession();
+  const base = ic.resolveEnv('API_BASE') || (session && session.api_base) || 'https://amazonprimea.com';
+  const token = (session && session.token) || null;
+  const key = `${base}|${token || ''}|${allowUnauthenticated}|${allowBoxScope}`;
+  if (_clientCache.has(key)) return _clientCache.get(key);
+  if (!_clientModPromise) _clientModPromise = import('../../clients/bongos-client/index.mjs');
+  const { createClient } = await _clientModPromise;
+  const authedFetch = async (url, init) => {
+    init = init || {};
+    init.headers = Object.assign({ 'User-Agent': 'amazonprimea-gds-cli/1.0' }, init.headers);
+    const res = await fetch(url, init);
+    if (res.status === 401 && !allowUnauthenticated && !_unauthExitInFlight) {
+      _unauthExitInFlight = true;
+      printUnauthGuidanceAndExit();
+    }
+    if (res.status === 403 && !allowBoxScope && !allowUnauthenticated && !_boxScopeExitInFlight) {
+      const peek = await res.clone().json().catch(() => null);
+      if (isBoxScope({ status: 403, data: peek })) {
+        _boxScopeExitInFlight = true;
+        printBoxScopeGuidanceAndExit();
+      }
+    }
+    return res;
+  };
+  const client = createClient({ baseUrl: `${base}/api/bongos/v1`, token, fetch: authedFetch, throwOnError: false });
+  _clientCache.set(key, client);
+  return client;
+}
+
+async function requireSession() {
+  const s = await loadSession();
+  if (!s || !s.token) {
+    console.error(`No GDS session found at ${SESSION_PATH}.`);
+    console.error(`You're not signed in yet — pick the line that fits:`);
+    console.error(`  • First time on the project  → run /builder-setup   (one-time GitHub sign-in that also registers you)`);
+    console.error(`  • Signed in before / expired → run /builder-reauth  (fast UI re-issue of your CLI token)`);
+    process.exit(2);
+  }
+  return s;
+}
+
+// -------------------------------------------------------------------------
+// Output helpers (text, structured for the slash command to relay)
+// -------------------------------------------------------------------------
+
+function fmtMinutes(m) {
+  if (m == null) return '—';
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rem = m % 60;
+  return rem ? `${h}h${rem}m` : `${h}h`;
+}
+
+function fmtUsd(n) {
+  if (n == null) return '—';
+  return `$${Number(n).toFixed(2)}`;
+}
+
+function fmtTouches(arr) {
+  if (!arr || arr.length === 0) return '—';
+  if (arr.length <= 3) return arr.join(', ');
+  return `${arr.slice(0, 3).join(', ')} +${arr.length - 3}`;
+}
+
+// Estimate display: prefer the calibrated minutes (per-kind median × raw est).
+// When calibration differs meaningfully from the raw input we show both as
+// `~5m (raw 90m)` so the gap is visible. When raw == calibrated (small task,
+// no historical data, or differs by <20%) we collapse to a single number.
+// Migration 015 added est_minutes_calibrated to /tasks/claimable + getTask.
+function fmtEstimate(t) {
+  const raw = t.est_minutes;
+  const cal = t.est_minutes_calibrated;
+  if (cal == null) return fmtMinutes(raw);
+  if (raw == null || raw === cal) return fmtMinutes(cal);
+  const diff = Math.abs(cal - raw) / raw;
+  if (diff < 0.2) return fmtMinutes(cal);
+  return `~${fmtMinutes(cal)} (raw ${fmtMinutes(raw)})`;
+}
+
+function tableTask(t) {
+  // Version chip — eg `[V1]` / `[PMS-V2]`.
+  const versionChip = `[${t.version_id}]`;
+  return [
+    `#${t.id}`,
+    versionChip,
+    `P${t.priority ?? '?'}`,
+    fmtEstimate(t),
+    `${fmtUsd(t.est_cost_usd)}`,
+    `M${t.manual_degree ?? '?'}`,
+    `${t.credits_reward ?? 0}c`,
+    t.automation_tag ? `[${t.automation_tag}]` : '',
+    t.title,
+  ]
+    .filter(Boolean)
+    .join('  ');
+}
+
+// -------------------------------------------------------------------------
+// Free-text session-request parser
+// -------------------------------------------------------------------------
+//
+// Pure function. Returns { timeBudgetMin, mode, parallel } where each field
+// may be null if not detected. Returns null when *no* fields parsed (so the
+// CLI can fall through to the interactive prompt).
+//
+// Time:     \d+\s*(h|hr|hrs|hour|hours|min|m|minutes?)
+// Mode:     overnight|autonomous|async      → 'autonomous'
+//           active|focused                  → 'active'
+//           check[\s-]?in|intermittent      → 'check-in'
+// Parallel: parallel\s*\d+, \d+\s*sessions?, max\s*\d+
+
+// V3.R13 (#237): one-line "next: <stage>" nudge for newcomers.
+//
+// Given the /api/gds/me response, print a banner pointing at the next
+// uncleared onboarding stage. Silent when the builder has graduated or has
+// already cleared first_ship (the post-newcomer threshold) — gates lift
+// after the first ship, so the nudge is too. Also silent when the
+// onboarding payload is missing (older API, network glitch) — we'd rather
+// say nothing than print noise.
+//
+// Maps stage -> a concrete CLI/web action the builder can take RIGHT NOW.
+// Stage-internal hints (STAGE_HINTS in src/bongos/onboarding-state.js) are
+// the canonical description; the per-CLI commands are the action verbs.
+function nudgeActionForStage(stage) {
+  switch (stage) {
+    case 'auth_complete':
+      return 'Run node scripts/gds/setup.js to authenticate.';
+    case 'pick_disciplines':
+      return 'Choose the work that calls you — open the hall at https://amazonprimea.com/builders and pick engineer, artist, ideator, or any mix.';
+    case 'first_start':
+      return 'Run /builder-start to survey what you can claim.';
+    case 'first_claim':
+      return 'Pick a task from /builder-start and claim it with /builder-claim N.';
+    case 'ship_three':
+      return 'Carry three tasks through with /builder-ship — the third makes you a Thetes.';
+    default:
+      return null;
+  }
+}
+
+function printOnboardingNudge(meBody) {
+  if (!meBody || typeof meBody !== 'object') return;
+  const onboarding = meBody.onboarding;
+  if (!onboarding || typeof onboarding !== 'object') return;
+  if (onboarding.graduated) return;
+  const cleared = new Set(Array.isArray(onboarding.completed_stages) ? onboarding.completed_stages : []);
+  // Reached the ship-three milestone (= graduated to Thetes): no further nagging.
+  if (cleared.has('ship_three')) return;
+  const stage = onboarding.current_stage;
+  if (!stage || stage === 'graduated') return;
+  const action = nudgeActionForStage(stage);
+  if (!action) return;
+  // Use a recognizable prefix so the slash command and any UI surface can
+  // detect/strip the line if needed. Ascii-only — these scripts must work
+  // in low-fidelity terminals.
+  const stages = Array.isArray(onboarding.stages) ? onboarding.stages : [];
+  const stageMeta = stages.find((s) => s.id === stage);
+  const label = (stageMeta && stageMeta.label) || stage;
+  console.log(`Next: ${label} — ${action}`);
+}
+
+// V3.R84 (#302), criterion C3: the CLI-side budget "ping". Prints a prominent
+// soft-cap (warn) or hard-cap (over) line from the /me `cost` object. The CLI is
+// the builder's private surface, so this is where the budget warning reaches
+// them — not Discord (shared mirror). No-op when under budget or when the server
+// didn't return a cost status (older deploy / read error → fail-quiet).
+function printCostWarning(meBody) {
+  const cost = meBody && meBody.cost;
+  if (!cost || typeof cost !== 'object') return;
+  if (cost.level === 'over') {
+    console.log(`⚠ BUDGET EXCEEDED — $${cost.spend_mtd_usd} of $${cost.budget_mtd_usd} this month (${cost.pct_used}%). Cost-incurring actions (ship, art pipeline) are blocked until an Archon raises your budget.`);
+  } else if (cost.level === 'warn') {
+    console.log(`⚠ Budget at ${cost.pct_used}% — $${cost.spend_mtd_usd} of $${cost.budget_mtd_usd} this month. You'll be blocked from cost-incurring actions at 100%.`);
+  }
+}
+
+// task 1013 / ADR 0073: the CLI half of the consistent "the system needs an input
+// from you" signal. Given the /api/gds/me response, print a short line for each
+// `needs` item in the action_needed state — the builder's private surface is the
+// right place to tell them an input is missing (mirrors printCostWarning). Silent
+// when nothing needs action (covered / satisfied items don't nag) or when the
+// payload is absent (older API / network glitch). One line per item, with the
+// concrete place to fix it. The hall Standing card renders the same `needs` data.
+const HALL_BASE = 'https://amazonprimea.com/builders';
+function printNeedsNudge(meBody) {
+  if (!meBody || typeof meBody !== 'object') return;
+  const needs = meBody.needs;
+  if (!needs || !Array.isArray(needs.items)) return;
+  const action = needs.items.filter((n) => n && n.state === 'action_needed');
+  if (action.length === 0) return;
+  const noun = action.length === 1 ? 'thing needs' : 'things need';
+  console.log(`⚠ ${action.length} ${noun} your input:`);
+  for (const n of action) {
+    const where = n.action && n.action.href ? ` — ${HALL_BASE}${n.action.href}` : '';
+    console.log(`  • ${n.title}: ${n.message}${where}`);
+  }
+}
+
+function parseSessionRequest(text) {
+  if (!text || typeof text !== 'string') return null;
+  const s = text.toLowerCase();
+
+  let timeBudgetMin = null;
+  let mode = null;
+  let parallel = null;
+
+  // Parallel — try the most specific patterns first so a "3 sessions" form
+  // doesn't get clobbered by an earlier "\d+\s*h" match on the same digits.
+  let mParallel =
+    s.match(/parallel\s*[:=]?\s*(\d+)/) ||
+    s.match(/(\d+)\s*sessions?\b/) ||
+    s.match(/max\s*[:=]?\s*(\d+)/);
+  if (mParallel) parallel = Number(mParallel[1]);
+
+  // Time — accept hours and minutes in any combination ("6h", "90 min",
+  // "1 hour", "2hr30min"). Sum them. (?![a-z]) instead of \b so digit-suffix
+  // compounds like "2hr30min" still match the hour group.
+  const hourRe = /(\d+)\s*(hours|hour|hrs|hr|h)(?![a-z])/g;
+  const minRe = /(\d+)\s*(minutes|minute|min|m)(?![a-z])/g;
+  let total = 0;
+  let matched = false;
+  // Hours pass first.
+  let m;
+  while ((m = hourRe.exec(s)) !== null) {
+    total += Number(m[1]) * 60;
+    matched = true;
+  }
+  // Minutes pass — but only count "m" alone if it's not eaten by hour.
+  // Strip already-matched hour spans so "2hr30min" doesn't double-count.
+  let minSearch = s.replace(hourRe, ' ');
+  while ((m = minRe.exec(minSearch)) !== null) {
+    total += Number(m[1]);
+    matched = true;
+  }
+  if (matched) timeBudgetMin = total;
+
+  // Mode — most-specific wins. check-in patterns first because they overlap
+  // with nothing; then autonomous (overnight/async), then active.
+  if (/\bcheck[\s-]?in\b|\bintermittent\b/.test(s)) {
+    mode = 'check-in';
+  } else if (/\bovernight\b|\bautonomous\b|\basync\b/.test(s)) {
+    mode = 'autonomous';
+  } else if (/\bactive\b|\bfocused\b/.test(s)) {
+    mode = 'active';
+  }
+
+  if (timeBudgetMin == null && mode == null && parallel == null) return null;
+  return { timeBudgetMin, mode, parallel };
+}
+
+module.exports = {
+  API_BASE,
+  SESSION_PATH,
+  loadSession,
+  loadSessionSync,
+  saveSession,
+  arg,
+  hasFlag,
+  readSessionToken,
+  apiCall,
+  cliClient,
+  requireSession,
+  printUnauthGuidanceAndExit,
+  isBoxScope,
+  printBoxScopeGuidanceAndExit,
+  fmtMinutes,
+  fmtUsd,
+  fmtTouches,
+  fmtEstimate,
+  tableTask,
+  parseSessionRequest,
+  printOnboardingNudge,
+  printCostWarning,
+  printNeedsNudge,
+};

package/scripts/gds/code.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// scripts/gds/code.js — `bongos code` (GDS-V4 · V4.R80 · task 1247).
+//
+// Attaches VS Code to the builder's cloud dev box over Remote-SSH at /workspace,
+// so the laptop is a thin client and the box is the full environment. Wakes the
+// box (POST /box/ensure), ensures the local SSH key + host alias, best-effort
+// installs Claude's VS Code extension ON THE BOX (the cloud box isn't a
+// devcontainer, so the extension isn't pre-baked — VS Code installs it into the
+// remote server on connect), then opens the folder.
+//
+//   bongos code                  open VS Code Remote-SSH on the cloud box
+//   bongos code --local          open VS Code on the LOCAL clone (Metic+ only)
+//   bongos code --no-extension   skip the best-effort remote extension install
+
+'use strict';
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync, execFileSync } = require('node:child_process');
+const lib = require('./box-connect-lib');
+
+const WIN = process.platform === 'win32';
+
+function repoRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+  } catch (_) {
+    return process.cwd();
+  }
+}
+
+function runCode(args, { inherit = true } = {}) {
+  return spawnSync('code', args, { stdio: inherit ? 'inherit' : 'ignore', shell: WIN, windowsHide: true });
+}
+
+async function runLocal({ log }) {
+  const rank = await lib.fetchRank();
+  if (!lib.rankAtLeast(rank, 'metic')) {
+    console.error(
+      `✖ \`--local\` is a Metic+ convenience (your rank: ${rank || 'unknown'}). ` +
+        'The standard environment is the cloud box: run `bongos code` without `--local`.'
+    );
+    process.exit(1);
+  }
+  const root = repoRoot();
+  log(`▸ Opening VS Code on the local clone: ${root.replace(os.homedir(), '~')}`);
+  if (fs.existsSync(path.join(root, '.devcontainer', 'devcontainer.json'))) {
+    log('  (a .devcontainer is present — use "Reopen in Container" in VS Code for the full boxed environment.)');
+  }
+  const r = runCode([root]);
+  process.exit(r.status == null ? 1 : r.status);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const local = argv.includes('--local');
+  const noExtension = argv.includes('--no-extension');
+  const log = console.log;
+
+  if (!lib.binPresent('code')) {
+    console.error('✖ The VS Code `code` command was not found on your PATH.');
+    console.error('  Install VS Code (https://code.visualstudio.com), then run the command');
+    console.error('  palette action "Shell Command: Install \'code\' command in PATH", and re-run.');
+    process.exit(1);
+  }
+
+  if (local) return runLocal({ log });
+
+  console.log('▸ Connecting VS Code to your Amazonprimea dev box…');
+  const { box } = await lib.prepareConnection({ log });
+  const host = box.hostname;
+  const authority = lib.remoteAuthority(host);
+
+  if (!noExtension) {
+    log(`  Installing Claude's VS Code extension on the box (${lib.CLAUDE_VSCODE_EXTENSION})…`);
+    const ext = runCode(['--remote', authority, '--install-extension', lib.CLAUDE_VSCODE_EXTENSION]);
+    if (!ext || ext.error || (ext.status != null && ext.status !== 0)) {
+      log('  ! Could not auto-install the extension (non-fatal). VS Code will offer to install it once connected.');
+    }
+  }
+
+  console.log(`▸ Opening ${lib.WORKSPACE} on ${host} in VS Code…`);
+  const r = runCode(['--remote', authority, lib.WORKSPACE]);
+  if (r.error) {
+    console.error(`✖ Could not launch VS Code: ${r.error.message}`);
+    process.exit(1);
+  }
+  if (lib.isFirstLogin(host)) {
+    console.log(
+      '\nℹ First time on this box? If Claude in VS Code asks you to enroll this device (/login),\n' +
+        '  run `bongos shell` once to complete it in a terminal — then reload the VS Code window.'
+    );
+  }
+  process.exit(r.status == null ? 1 : r.status);
+}
+
+main().catch((err) => {
+  console.error(`✖ ${err.message}`);
+  process.exit(1);
+});