@bongos/core 1.17.0

package/scripts/gds/local-preview-lib.js

@@ -0,0 +1,159 @@
+// scripts/gds/local-preview-lib.js — core of the LOCAL sandbox launcher (task 1056).
+//
+// Gives a builder working on a LOCAL full clone (laptop) the same private game
+// preview a dev box gets at sandbox-<login>.amazonprimea.com (ADR 0044/0046/0052)
+// — but served at http://localhost:<port> on their OWN machine: no Cloudflare
+// tunnel, no public URL, $0. It runs the ADR 0052 game-only entry
+// (src/preview-server.js), which serves ONLY the playable game (no /api/gds, no
+// BuildersHall), degraded-DB exactly like the box sandbox.
+//
+// The preview is a long-running DETACHED background process (the laptop analogue
+// of the box's box-game-preview.service systemd unit). The edit loop mirrors the
+// box: edit -> restart -> refresh the browser tab.
+//
+// Everything is pure + injectable (deps.fs / deps.spawn / deps.kill /
+// deps.fetchImpl / deps.env / deps.*Path) so tests/local_preview.mjs can exercise
+// the logic with NO real spawn, NO network, NO filesystem writes.
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// 3100, NOT 3000 — a local builder may already run the FULL server.js on 3000
+// for API dev; the preview must never fight it for the port.
+const DEFAULT_PORT = 3100;
+const HOST = '127.0.0.1';
+
+// Box-only markers (ADR 0031/0044). ANY one ⇒ this is a provisioned dev box, NOT
+// a laptop. Deliberately broader than /etc/otb/box.env alone: a box whose box.env
+// was lost or is unreadable must still be recognized as a box, never mistaken for
+// a laptop — because the laptop path hands back a http://localhost preview URL,
+// which is unreachable from the builder's own browser when the server is on a
+// remote box (the task-1443 footgun: "the link is giving me localhost"). box.env
+// is the canonical marker; box-preview (the preview control command) and the
+// box-game-preview.service unit are written on every box and survive an
+// unreadable/empty box.env, so they're the resilient backstops.
+const BOX_ENV_PATH = '/etc/otb/box.env';
+const BOX_PREVIEW_WRAPPER = '/usr/local/bin/box-preview';
+const BOX_SERVICE_UNIT = '/etc/systemd/system/box-game-preview.service';
+// scripts/gds/ -> repo root. Absolute + cwd-independent so staging works no
+// matter where ship.js is invoked from.
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PREVIEW_ENTRY = path.join(REPO_ROOT, 'src', 'preview-server.js');
+
+function previewPort(deps = {}) {
+  const env = deps.env || process.env;
+  const n = Number(env.OTB_PREVIEW_PORT);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : DEFAULT_PORT;
+}
+function localUrl(deps = {}) { return `http://localhost:${previewPort(deps)}`; }
+// Health is checked on the loopback IP literal (not "localhost") to dodge any
+// IPv6/hosts-file quirk while the server binds 127.0.0.1.
+function healthUrl(deps = {}) { return `http://127.0.0.1:${previewPort(deps)}/healthz`; }
+function previewEntry(deps = {}) { return deps.previewEntry || PREVIEW_ENTRY; }
+function pidPath(deps = {}) { return deps.pidPath || path.join((deps.tmpdir || os.tmpdir)(), 'otb-local-preview.pid'); }
+function logPath(deps = {}) { return deps.logPath || path.join((deps.tmpdir || os.tmpdir)(), 'otb-local-preview.log'); }
+
+// Is the game-only entry present? A FULL clone carries it; a partial/sparse
+// clone (or a non-repo dir) does not — and then there is no local sandbox.
+function hasGameEntry(deps = {}) {
+  const f = deps.fs || fs;
+  return f.existsSync(previewEntry(deps));
+}
+
+// Is this a provisioned dev box (ADR 0031/0044), i.e. NOT a laptop? True if any
+// box-only marker is present. Pure + injectable (deps.fs + per-marker path
+// overrides) like everything else here, and honors the dep names sandbox-stage.js
+// already injects (deps.boxEnvPath / deps.previewWrapper) so a single call site
+// drives both. Used to keep the localhost local-preview path from EVER being
+// chosen on a box — see the BOX_* marker note above (task 1443).
+function onBox(deps = {}) {
+  const f = deps.fs || fs;
+  const markers = [
+    deps.boxEnvPath || BOX_ENV_PATH,
+    deps.previewWrapper || BOX_PREVIEW_WRAPPER,
+    deps.boxServiceUnit || BOX_SERVICE_UNIT,
+  ];
+  return markers.some((p) => { try { return f.existsSync(p); } catch { return false; } });
+}
+
+function readPid(deps = {}) {
+  const f = deps.fs || fs;
+  try {
+    const pid = Number(String(f.readFileSync(pidPath(deps), 'utf8')).trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch { return null; }
+}
+
+// signal-0 existence probe. EPERM means the pid exists but we can't signal it
+// (still alive); ESRCH means gone.
+function pidAlive(pid, deps = {}) {
+  if (!pid) return false;
+  const kill = deps.kill || process.kill;
+  try { kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+function isRunning(deps = {}) { return pidAlive(readPid(deps), deps); }
+
+// Start the preview detached. Idempotent: a no-op (already:true) if it's already
+// running, so re-running `start` / `npm run preview` is safe.
+function start(deps = {}) {
+  if (!hasGameEntry(deps)) {
+    return { ok: false, reason: `no game preview entry at ${previewEntry(deps)} — this clone doesn't carry the game (a full clone does)` };
+  }
+  if (isRunning(deps)) {
+    return { ok: true, already: true, pid: readPid(deps), url: localUrl(deps) };
+  }
+  const f = deps.fs || fs;
+  const spawnImpl = deps.spawn || spawn;
+  const port = previewPort(deps);
+  const lp = logPath(deps);
+  // Fresh log per run so `logs` shows the current process's output.
+  let out = 'ignore';
+  try { out = f.openSync(lp, 'w'); } catch { /* fall back to ignore */ }
+  const child = spawnImpl(deps.nodePath || process.execPath, [previewEntry(deps)], {
+    cwd: REPO_ROOT,
+    env: { ...(deps.env || process.env), PORT: String(port), HOST },
+    detached: true,
+    stdio: ['ignore', out, out],
+    windowsHide: true,
+  });
+  child.unref();
+  if (child.pid) f.writeFileSync(pidPath(deps), String(child.pid) + '\n');
+  return { ok: true, already: false, pid: child.pid, url: localUrl(deps), log: lp };
+}
+
+function stop(deps = {}) {
+  const f = deps.fs || fs;
+  const kill = deps.kill || process.kill;
+  const pid = readPid(deps);
+  if (!pid || !pidAlive(pid, deps)) {
+    try { f.rmSync(pidPath(deps), { force: true }); } catch { /* best-effort */ }
+    return { ok: true, wasRunning: false };
+  }
+  try { kill(pid); } catch (e) { return { ok: false, reason: e.message, pid }; }
+  try { f.rmSync(pidPath(deps), { force: true }); } catch { /* best-effort */ }
+  return { ok: true, wasRunning: true, pid };
+}
+
+function restart(deps = {}) {
+  stop(deps);
+  return start(deps);
+}
+
+async function health(deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  try {
+    const res = await fetchImpl(healthUrl(deps), { signal: AbortSignal.timeout(deps.healthTimeoutMs || 4000) });
+    return res.status < 500;
+  } catch { return false; }
+}
+
+module.exports = {
+  DEFAULT_PORT, HOST, REPO_ROOT,
+  BOX_ENV_PATH, BOX_PREVIEW_WRAPPER, BOX_SERVICE_UNIT,
+  previewPort, localUrl, healthUrl, previewEntry, pidPath, logPath,
+  hasGameEntry, onBox, readPid, pidAlive, isRunning,
+  start, stop, restart, health,
+};

package/scripts/gds/local-preview.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// scripts/gds/local-preview.js — the builder's control for the LOCAL game
+// preview (task 1056), the laptop analogue of `box-preview` (ADR 0044) on a dev
+// box. Runs the ADR 0052 game-only entry privately at http://localhost:<port>.
+//
+//   npm run preview                          # start it (then open the URL)
+//   node scripts/gds/local-preview.js status   is it up + the URL          (default)
+//   node scripts/gds/local-preview.js start
+//   node scripts/gds/local-preview.js restart  pick up your latest edits
+//   node scripts/gds/local-preview.js stop
+//   node scripts/gds/local-preview.js logs     dump the preview's output
+//   node scripts/gds/local-preview.js url
+//
+// Private to your machine: no Cloudflare tunnel, no public URL, no DB, nothing
+// shipped. Set OTB_PREVIEW_PORT to override the default 3100.
+
+const lib = require('./local-preview-lib');
+
+async function pollHealthy(ms = 20_000) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    if (await lib.health()) return true;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+const HINT = `Open ${lib.localUrl()} — your PRIVATE copy of the game (degraded DB, nothing shipped).`;
+
+// This launcher is the LAPTOP analogue of box-preview. On a dev box it's the
+// wrong tool: it binds http://localhost, which the builder's browser can't reach
+// when the server is on a remote box — the "the link is giving me localhost"
+// footgun (task 1443). Warn loudly and point at the box's HOSTED sandbox; warn,
+// don't hard-fail, so an operator who really wants a box-local loopback still can.
+function warnIfOnBox() {
+  if (!lib.onBox()) return;
+  console.error('⚠ You appear to be on a dev box. This LOCAL preview binds http://localhost —');
+  console.error('  your browser cannot reach the box\'s localhost. Your sandbox is the HOSTED url:');
+  console.error('  run  /builder-stage  (or  box-preview status )  to get https://sandbox-<login>.<host> and refresh that tab.');
+}
+
+(async () => {
+  const cmd = process.argv[2] || 'status';
+  if (cmd === 'start' || cmd === 'restart' || cmd === 'status' || cmd === 'url') warnIfOnBox();
+  switch (cmd) {
+    case 'start': {
+      const r = lib.start();
+      if (!r.ok) { console.error(`local-preview: ${r.reason}`); process.exit(1); }
+      if (r.already) {
+        console.log(`local preview already running (pid ${r.pid}) at ${r.url}`);
+      } else {
+        process.stdout.write(`starting local preview (pid ${r.pid})... `);
+        console.log((await pollHealthy()) ? `up at ${r.url}` : `started, not healthy yet — see 'node scripts/gds/local-preview.js logs'`);
+      }
+      console.log(HINT);
+      break;
+    }
+    case 'restart': {
+      const r = lib.restart();
+      if (!r.ok) { console.error(`local-preview: ${r.reason}`); process.exit(1); }
+      process.stdout.write('restarting local preview to pick up your edits... ');
+      console.log((await pollHealthy()) ? `up at ${r.url}  (refresh your browser tab)` : `restarted, not healthy yet — see logs`);
+      break;
+    }
+    case 'stop': {
+      const r = lib.stop();
+      console.log(r.wasRunning ? `stopped (pid ${r.pid})` : 'local preview was not running');
+      break;
+    }
+    case 'status': {
+      const running = lib.isRunning();
+      console.log(`local preview: ${running ? `running (pid ${lib.readPid()})` : 'stopped'}`);
+      console.log(`url:           ${lib.localUrl()}`);
+      if (running) console.log(`health:        ${(await lib.health()) ? 'OK' : 'not answering yet'}`);
+      else console.log(`(run 'npm run preview' to start it)`);
+      break;
+    }
+    case 'url':
+      console.log(lib.localUrl());
+      break;
+    case 'logs': {
+      const fs = require('node:fs');
+      try { process.stdout.write(fs.readFileSync(lib.logPath(), 'utf8')); }
+      catch { console.log(`(no preview log yet at ${lib.logPath()})`); }
+      break;
+    }
+    case '-h': case '--help': case 'help':
+      console.log('usage: node scripts/gds/local-preview.js [status|start|restart|stop|logs|url]');
+      console.log(`port: $OTB_PREVIEW_PORT or ${lib.DEFAULT_PORT}`);
+      break;
+    default:
+      console.error(`local-preview: unknown command '${cmd}' (try: status|start|restart|stop|logs|url)`);
+      process.exit(2);
+  }
+})().catch((e) => { console.error('local-preview error:', e.message); process.exit(1); });

package/scripts/gds/login.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// scripts/gds/login.js — `bongos login <instance-url>` (GDS-V4 · V4.R83 · task 1250).
+//
+// Instance-agnostic sign-in: point the CLI at ANY Cloud Bongos instance, and it
+// configures itself from that instance's manifest, runs the GitHub device flow
+// (browser click — no token paste, the UI-first rule), and stores a session
+// scoped to that instance (session.api_base → every later `bongos` command talks
+// to it).
+//
+// The stranger path: an instance is invite-only by default, so a brand-new person
+// isn't admitted yet. When the device flow comes back `not_approved`, this files
+// the PUBLIC access request (their GitHub username) and POLLS admission until an
+// Archon approves them with a 👍 in Discord — then finishes sign-in. (The device
+// flow's not_approved is terminal — the code is spent — so admission is polled
+// via GET /access-requests/status and a fresh device flow completes it.)
+//
+// `bongos init` (scaffold a new instance) and `bongos upgrade` (module pre-check)
+// are sibling verbs of the same CLI (see bin/bongos.js VERBS) — this login is the
+// front door; those are reachable alongside it.
+
+'use strict';
+
+const readline = require('node:readline');
+const { spawnSync } = require('node:child_process');
+const { saveSession } = require('./cli-lib');
+
+// --- pure helpers (unit-tested) ---------------------------------------------
+
+// Normalize whatever the user pastes into an origin: add https:// if no scheme,
+// drop trailing slashes, and tolerate a pasted /api/gds suffix.
+function normalizeInstanceBase(raw) {
+  let s = String(raw || '').trim();
+  if (!s) throw new Error('missing instance URL');
+  if (!/^https?:\/\//i.test(s)) s = `https://${s}`;
+  s = s.replace(/\/+$/, '');
+  s = s.replace(/\/api\/gds\/?$/i, '');
+  return s;
+}
+
+// Decide what an /access-requests/status poll means for the sign-in loop.
+function pollDecision(body) {
+  if (!body || typeof body !== 'object') return 'wait';
+  if (body.admitted === true) return 'admitted';
+  if (body.status === 'member' || body.status === 'invited') return 'admitted';
+  if (body.status === 'dismissed') return 'dismissed';
+  return 'wait';
+}
+
+// --- I/O helpers -------------------------------------------------------------
+
+async function fetchJson(url, opts = {}) {
+  const res = await fetch(url, {
+    headers: { 'Content-Type': 'application/json', 'User-Agent': 'bongos-cli/login' },
+    ...opts,
+  });
+  let data = null;
+  try {
+    const t = await res.text();
+    data = t ? JSON.parse(t) : null;
+  } catch {
+    data = null;
+  }
+  return { status: res.status, ok: res.ok, data };
+}
+
+function openBrowser(url) {
+  try {
+    if (process.platform === 'darwin') spawnSync('open', [url], { stdio: 'ignore' });
+    else if (process.platform === 'win32') spawnSync('cmd', ['/c', 'start', '', url], { stdio: 'ignore' });
+    else spawnSync('xdg-open', [url], { stdio: 'ignore' });
+  } catch {
+    /* best-effort — the code is printed regardless */
+  }
+}
+
+function prompt(q) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(q, (a) => { rl.close(); resolve(String(a || '').trim()); }));
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Run the GitHub device flow against `base`. Returns one of:
+//   { state: 'ok', token, builder } | { state: 'not_approved' } | { state: 'expired' }
+async function runDeviceFlow(base, { log }) {
+  const start = await fetchJson(`${base}/api/gds/auth/device/start`, { method: 'POST' });
+  if (start.status === 503 || (start.data && start.data.error === 'auth_not_configured')) {
+    throw new Error('that instance has no GitHub sign-in configured yet — ask its Archon to set it up.');
+  }
+  if (!start.ok || !start.data || !start.data.device_code) {
+    throw new Error(`could not start sign-in (HTTP ${start.status}).`);
+  }
+  const { device_code, user_code, verification_uri } = start.data;
+  let interval = Number(start.data.interval) || 5;
+  const expires = Number(start.data.expires_in) || 900;
+
+  log('');
+  log('  ┌────────────────────────────────────────────┐');
+  log(`  │  Open:  ${String(verification_uri).slice(0, 36).padEnd(36)}│`);
+  log(`  │  Code:  ${String(user_code).slice(0, 36).padEnd(36)}│`);
+  log('  └────────────────────────────────────────────┘');
+  log('');
+  openBrowser(verification_uri);
+  log('  Waiting for you to approve in the browser…');
+
+  const deadline = Date.now() + expires * 1000;
+  while (Date.now() < deadline) {
+    await sleep(interval * 1000);
+    const poll = await fetchJson(`${base}/api/gds/auth/device/poll`, {
+      method: 'POST',
+      body: JSON.stringify({ device_code }),
+    });
+    const st = poll.data && poll.data.state;
+    if (st === 'ok') return { state: 'ok', token: poll.data.token, builder: poll.data.builder };
+    if (st === 'not_approved' || (poll.status === 403 && st !== 'pending')) return { state: 'not_approved' };
+    if (st === 'denied') throw new Error('sign-in was denied in the browser.');
+    if (st === 'expired') return { state: 'expired' };
+    if (st === 'slow_down') interval += 5;
+    process.stdout.write('.');
+  }
+  return { state: 'expired' };
+}
+
+// --- main --------------------------------------------------------------------
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const urlArg = argv.find((a) => !a.startsWith('-'));
+  const log = console.log;
+
+  let base;
+  try {
+    base = normalizeInstanceBase(urlArg || (await prompt('Instance URL (e.g. https://amazonprimea.com): ')));
+  } catch {
+    console.error('✖ usage: bongos login <instance-url>');
+    process.exit(2);
+  }
+
+  // 1. Manifest — brand + admission posture, and a check that this really is a
+  //    Cloud Bongos instance before we start a device flow.
+  log(`▸ Connecting to ${base}…`);
+  const man = await fetchJson(`${base}/api/gds/instance`);
+  if (!man.ok || !man.data || man.data.schema !== 'instance-manifest/v1') {
+    console.error(`✖ ${base} does not look like a Cloud Bongos instance (no /api/gds/instance manifest).`);
+    process.exit(1);
+  }
+  const instanceName = man.data.name || base;
+  const admission = (man.data.admission && man.data.admission.policy) || 'invite-only';
+  log(`  Signing in to ${instanceName}${admission === 'invite-only' ? ' (invite-only)' : ''}`);
+
+  // 2. Device flow.
+  let flow = await runDeviceFlow(base, { log });
+
+  // 3. Stranger path: not admitted → file the request, poll until an Archon 👍s,
+  //    then finish sign-in with a fresh device flow (the first code is spent).
+  if (flow.state === 'not_approved') {
+    log('');
+    log(`  You're not admitted to ${instanceName} yet.`);
+    const ghLogin = (await prompt('  Your GitHub username: ')).replace(/^@/, '');
+    if (!ghLogin) {
+      console.error('✖ need your GitHub username to request access.');
+      process.exit(2);
+    }
+    const reqRes = await fetchJson(`${base}/api/gds/access-requests`, {
+      method: 'POST',
+      body: JSON.stringify({ github_login: ghLogin, note: 'via bongos login' }),
+    });
+    if (reqRes.status === 409 && reqRes.data && reqRes.data.error === 'already_member') {
+      log('  You already have an account — retrying sign-in…');
+    } else if (reqRes.ok || reqRes.status === 200 || reqRes.status === 201) {
+      log(`  ✓ Requested access to ${instanceName}. An Archon approves you with a 👍 in Discord (#member-approvals).`);
+    } else {
+      console.error(`✖ could not file an access request (HTTP ${reqRes.status}).`);
+      process.exit(1);
+    }
+    log('  Waiting for approval (safe to leave running)…');
+    const admitDeadline = Date.now() + 30 * 60 * 1000; // 30 min
+    for (;;) {
+      await sleep(5000);
+      const s = await fetchJson(`${base}/api/gds/access-requests/status?github_login=${encodeURIComponent(ghLogin)}`);
+      const decision = pollDecision(s.data);
+      if (decision === 'admitted') {
+        log('\n  ✓ Approved! Finishing sign-in — approve once more in your browser.');
+        break;
+      }
+      if (decision === 'dismissed') {
+        console.error('\n✖ your access request was declined.');
+        process.exit(1);
+      }
+      if (Date.now() > admitDeadline) {
+        console.error('\n✖ timed out waiting for approval — re-run `bongos login` once an Archon has approved you.');
+        process.exit(1);
+      }
+      process.stdout.write('.');
+    }
+    flow = await runDeviceFlow(base, { log });
+  }
+
+  if (flow.state !== 'ok') {
+    console.error(`✖ sign-in did not complete (${flow.state}). Re-run \`bongos login ${base}\`.`);
+    process.exit(1);
+  }
+
+  // 4. Per-instance session — api_base scopes every later `bongos` command to
+  //    this instance; the brand name rides along for display.
+  await saveSession({
+    token: flow.token,
+    builder: flow.builder,
+    api_base: base,
+    instance: { name: instanceName, origin: base },
+  });
+  const who = (flow.builder && (flow.builder.github_login || flow.builder.display_name)) || 'you';
+  log('');
+  log(`  ✓ Signed in to ${instanceName} as ${who}.`);
+  log('  Next:  bongos start  (see what you can claim)  ·  bongos code / bongos shell  (get on your dev box)');
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`✖ ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { normalizeInstanceBase, pollDecision, runDeviceFlow };