@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/lint-infra-exec.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+// lint-infra-exec.js — task 2137 (ADR 0108 configurable-root). The dry-run/lint that proves every
+// host systemd unit running a CORE script still resolves AFTER the R89 split.
+//
+// The units (cohost-*, provision-*, search-index-db) keep living in the instance repo
+// (infra/ is host topology) while scripts/bongos/ moves into node_modules/@bongos/core, so each
+// ExecStart runs through infra/core-node.sh, which resolves the script under the instance root OR
+// its node_modules/@bongos/core (both layouts). "Resolves in a consumer layout" is provable from
+// the package manifest: the referenced core script must be a PUBLISHABLE core file (isPublishable →
+// it ships inside @bongos/core → present at node_modules/@bongos/core/<rel> post-install). We also
+// assert it exists at the core root today (monolith resolution + a typo catch) and that NO unit
+// still uses the bare repo-relative `node scripts/…` form (which resolves nothing post-split).
+//
+// Usage: node scripts/bongos/lint-infra-exec.js   (exit 0 = every unit resolves; 1 = violation)
+
+const fs = require('fs');
+const path = require('path');
+const { isPublishable } = require('./publish-manifest');
+const { resolveInstanceRoot, resolveCoreRoot } = require('../../src/instance-config');
+
+const LAUNCHER = 'infra/core-node.sh';
+// Repointed form:  ExecStart=/usr/bin/env bash infra/core-node.sh <core-rel> [args]
+const LAUNCHER_EXEC = /^ExecStart=.*\binfra\/core-node\.sh\s+(\S+)/;
+// Old bare form:   ExecStart=<node> scripts/…  — must no longer appear on a core-script unit.
+const BARE_EXEC = /^ExecStart=\S*node\s+(scripts\/\S+)/;
+
+// Pure-ish (reads the fs): classify every infra/*.service ExecStart. Returns
+// { ok, checked:[{unit,rel}], violations:[{unit,rel,why}] }. Roots are injectable for tests.
+function lintInfraExec({ instanceRoot, coreRoot } = {}) {
+  const iRoot = instanceRoot || resolveInstanceRoot();
+  const cRoot = coreRoot || resolveCoreRoot();
+  const dir = path.join(iRoot, 'infra');
+  const checked = [];
+  const violations = [];
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.service')).sort() : [];
+  for (const f of files) {
+    for (const raw of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+      const L = raw.trim();
+      if (!L.startsWith('ExecStart=')) continue;
+      const viaLauncher = LAUNCHER_EXEC.exec(L);
+      if (viaLauncher) {
+        const rel = viaLauncher[1];
+        if (!isPublishable(rel)) {
+          violations.push({ unit: f, rel, why: 'not a publishable core file — ABSENT from node_modules/@bongos/core in a consumer layout' });
+        } else if (!fs.existsSync(path.join(cRoot, rel))) {
+          violations.push({ unit: f, rel, why: `does not exist at the core root (${cRoot})` });
+        } else {
+          checked.push({ unit: f, rel });
+        }
+        continue;
+      }
+      const bare = BARE_EXEC.exec(L);
+      if (bare && bare[1].startsWith('scripts/')) {
+        violations.push({ unit: f, rel: bare[1], why: `bare repo-relative ExecStart — route it through ${LAUNCHER}` });
+      }
+    }
+  }
+  return { ok: violations.length === 0, checked, violations };
+}
+
+if (require.main === module) {
+  const r = lintInfraExec();
+  for (const c of r.checked) console.log(`  ✓ ${c.unit.padEnd(38)} ${c.rel}  (publishable → resolves in a consumer layout)`);
+  for (const v of r.violations) console.error(`  ✗ ${v.unit.padEnd(38)} ${v.rel}  — ${v.why}`);
+  console.log(`\nlint-infra-exec: ${r.checked.length} core-script unit(s) resolve; ${r.violations.length} violation(s)`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+module.exports = { lintInfraExec };

package/scripts/bongos/lint-migrations.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/lint-migrations.js — core-migration FORWARD-SAFETY guard (task 1002223 / audit H10,
+// finding F6).
+//
+// `bongos upgrade` auto-rollback reverts the CODE pin but DELIBERATELY NOT the database
+// (upgrade.js: "the DB is deliberately NOT rolled back … core migrations are additive + forward-
+// safe"). That safety rested on a convention nothing checked. A core migration is FORWARD-SAFE when
+// the PREVIOUS code version still runs against the post-migration schema — so a code-only rollback
+// never strands old code on a schema it can't read. This lints core migrations for operations that
+// BREAK that property and fails unless the migration explicitly acknowledges the exception with a
+//   -- forward-unsafe: <reason>
+// pragma (a deliberate, documented decision — e.g. a historical migration, or one paired with a
+// two-step deploy).
+//
+// SAFE (never flagged): CREATE TABLE/INDEX/…, ADD COLUMN, INSERT/UPDATE, and DROP-then-CREATE of an
+// INDEX / TRIGGER / VIEW / FUNCTION / POLICY (the recreate-in-place idempotency pattern) — none of
+// these remove state the old code depends on.
+// UNSAFE (flagged): DROP TABLE, DROP COLUMN, RENAME COLUMN, ALTER TABLE … RENAME TO, ALTER COLUMN …
+// TYPE, SET NOT NULL — each removes / renames / retypes existing state old code reads.
+//
+// Usage:
+//   node scripts/bongos/lint-migrations.js                 # STRICT: exit 1 on any unacknowledged unsafe migration
+//   node scripts/bongos/lint-migrations.js --warn          # report only, always exit 0 (migrate.sh uses this)
+//   node scripts/bongos/lint-migrations.js --dir <path>    # scan a specific migrations dir (default: <repo>/migrations)
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// The acknowledgement pragma. Lives in a SQL comment; matched on the raw file text.
+const ACK_RE = /^\s*--\s*forward-unsafe\s*:\s*(.+)$/im;
+
+// Genuinely forward-unsafe statement shapes. Ordered; a file matching ANY is unsafe.
+const UNSAFE = [
+  ['drop-table', /\bdrop\s+table\b/i],
+  ['drop-column', /\bdrop\s+column\b/i],
+  ['rename-column', /\brename\s+column\b/i],
+  ['rename-table', /\balter\s+table\s+[^\s;]+\s+rename\s+to\b/i],
+  ['alter-column-type', /\balter\s+column\b[^;]*\btype\b/i],
+  ['set-not-null', /\bset\s+not\s+null\b/i],
+];
+
+// Strip block + line comments so a pattern that appears only in prose/comments never counts as an
+// operation. (The ACK pragma is detected separately, on the raw text, since it IS a comment.)
+function stripSqlComments(sql) {
+  return String(sql).replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/--[^\n]*/g, ' ');
+}
+
+// Classify one migration's SQL: { unsafe: [names], acknowledged: bool, ackReason }.
+function scanMigrationSql(sql) {
+  const code = stripSqlComments(sql);
+  const unsafe = [];
+  for (const [name, re] of UNSAFE) if (re.test(code)) unsafe.push(name);
+  const ack = String(sql).match(ACK_RE);
+  return { unsafe, acknowledged: !!ack, ackReason: ack ? ack[1].trim() : null };
+}
+
+// Scan a migrations directory. Returns { violations, acknowledged } — each entry { file, unsafe, ackReason }.
+// `violations` = unsafe WITHOUT the pragma (fail-closed); `acknowledged` = unsafe WITH it (documented).
+function scanMigrationsDir(dir, fsImpl = fs) {
+  let files;
+  try { files = fsImpl.readdirSync(dir).filter((f) => f.endsWith('.sql')); }
+  catch { return { violations: [], acknowledged: [], scanned: 0 }; }
+  const violations = [];
+  const acknowledged = [];
+  for (const f of files.sort()) {
+    const r = scanMigrationSql(fsImpl.readFileSync(path.join(dir, f), 'utf8'));
+    if (r.unsafe.length === 0) continue;
+    (r.acknowledged ? acknowledged : violations).push({ file: f, unsafe: r.unsafe, ackReason: r.ackReason });
+  }
+  return { violations, acknowledged, scanned: files.length };
+}
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : fallback;
+}
+
+function main() {
+  const warnOnly = process.argv.includes('--warn');
+  const dir = path.resolve(arg('--dir', path.join(REPO_ROOT, 'migrations')));
+  const { violations, acknowledged, scanned } = scanMigrationsDir(dir);
+
+  for (const a of acknowledged) {
+    console.error(`[migrations] forward-unsafe (acknowledged): ${a.file} [${a.unsafe.join(', ')}] — ${a.ackReason}`);
+  }
+  if (violations.length === 0) {
+    console.error(`[migrations] forward-safety: OK — ${scanned} core migration(s) scanned, ${acknowledged.length} acknowledged exception(s), 0 unacknowledged.`);
+    return 0;
+  }
+  console.error(`[migrations] forward-safety: ${warnOnly ? 'WARNING' : 'FAILED'} — ${violations.length} core migration(s) contain a forward-UNSAFE operation with no acknowledgement:`);
+  for (const v of violations) console.error(`   ${v.file} [${v.unsafe.join(', ')}]`);
+  console.error('   A code-only `bongos upgrade` rollback does NOT revert the DB, so old code would run on this schema.');
+  console.error('   If intentional, add a top-of-file SQL comment:  -- forward-unsafe: <why it is safe here / the two-step plan>');
+  return warnOnly ? 0 : 1;
+}
+
+module.exports = { scanMigrationSql, scanMigrationsDir, stripSqlComments, UNSAFE, ACK_RE };
+
+if (require.main === module) process.exit(main());

package/scripts/bongos/lint-workflow-exec.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+// lint-workflow-exec.js — task 2136 (ADR 0108 configurable-root). The dry-run/lint that proves
+// every .github/workflows/*.yml invocation of a CORE script still resolves AFTER the R89 split.
+//
+// Workflows keep living in the instance repo (.github/ is host topology) while scripts/bongos/* +
+// scripts/migrate.sh move into @bongos/core, so each core invocation runs through the both-layouts
+// resolver: infra/core-node.sh for node targets, infra/core-path.sh for bash targets. "Resolves in
+// a consumer layout" is provable from the package manifest: the referenced core script must be a
+// PUBLISHABLE core file (ships in @bongos/core → present at node_modules/@bongos/core post-install)
+// AND exist at the core root today. A BARE `node scripts/bongos/x.js` / `bash scripts/migrate.sh` (not
+// routed through the resolver) is a violation — it resolves nothing from the instance root
+// post-split. Host scripts (scripts/art/*) stay at the instance root, so they are NOT flagged.
+//
+// Usage: node scripts/bongos/lint-workflow-exec.js   (exit 0 = all routed + resolve; 1 = violation)
+
+const fs = require('fs');
+const path = require('path');
+const { isPublishable } = require('./publish-manifest');
+const { resolveInstanceRoot, resolveCoreRoot } = require('../../src/instance-config');
+
+// Routed:  `… core-node.sh <rel>` / `… core-path.sh <rel>` (rel = a scripts/… core path).
+const ROUTED = /core-(?:node|path)\.sh\s+(scripts\/[^\s"')]+)/g;
+// Bare core invocation the resolver should have wrapped. Core scripts = scripts/bongos/*.{js,sh} +
+// scripts/migrate.sh; host scripts/art/* deliberately excluded (they stay at the instance root).
+const BARE = /(?:^|[^/\w])(?:node|bash)\s+(scripts\/(?:(?:gds|bongos)\/[^\s"']+\.(?:js|sh)|migrate\.sh))/;
+
+function lintWorkflowExec({ instanceRoot, coreRoot } = {}) {
+  const iRoot = instanceRoot || resolveInstanceRoot();
+  const cRoot = coreRoot || resolveCoreRoot();
+  const dir = path.join(iRoot, '.github', 'workflows');
+  const checked = [];
+  const violations = [];
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)).sort() : [];
+  for (const f of files) {
+    for (const raw of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+      const line = raw.replace(/\s+$/, '');
+      if (line.trim().startsWith('#')) continue; // a YAML/shell comment — reference, not an invocation
+      let m;
+      ROUTED.lastIndex = 0;
+      while ((m = ROUTED.exec(line)) !== null) {
+        const rel = m[1];
+        if (!isPublishable(rel)) violations.push({ file: f, rel, why: 'routed but NOT a publishable core file — absent from @bongos/core in a consumer layout' });
+        else if (!fs.existsSync(path.join(cRoot, rel))) violations.push({ file: f, rel, why: `routed but does not exist at the core root (${rel})` });
+        else checked.push({ file: f, rel });
+      }
+      if (/core-(?:node|path)\.sh/.test(line)) continue; // routed line — the arg was handled above
+      const bare = BARE.exec(line);
+      if (bare) violations.push({ file: f, rel: bare[1], why: 'bare core invocation — route it through infra/core-node.sh (node) or infra/core-path.sh (bash)' });
+    }
+  }
+  return { ok: violations.length === 0, checked, violations };
+}
+
+if (require.main === module) {
+  const r = lintWorkflowExec();
+  for (const c of r.checked) console.log(`  ✓ ${c.file.padEnd(26)} ${c.rel}  (publishable → resolves in a consumer layout)`);
+  for (const v of r.violations) console.error(`  ✗ ${v.file.padEnd(26)} ${v.rel}  — ${v.why}`);
+  console.log(`\nlint-workflow-exec: ${r.checked.length} routed core invocation(s) resolve; ${r.violations.length} violation(s)`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+module.exports = { lintWorkflowExec };

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

@@ -0,0 +1,128 @@
+// scripts/bongos/local-preview-lib.js — core of the LOCAL sandbox launcher (task 1056).
+//
+// Gives a builder working on a LOCAL full clone a private game preview (ADR
+// 0044/0046/0052) served at http://localhost:<port> on their OWN machine: no
+// public URL, $0. It runs the ADR 0052 game-only entry (src/preview-server.js),
+// which serves ONLY the playable game (no /api/bongos, no BuildersHall),
+// degraded-DB.
+//
+// The preview is a long-running DETACHED background process. The edit loop is:
+// 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';
+
+// scripts/bongos/ -> 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));
+}
+
+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,
+  previewPort, localUrl, healthUrl, previewEntry, pidPath, logPath,
+  hasGameEntry, readPid, pidAlive, isRunning,
+  start, stop, restart, health,
+};

package/scripts/bongos/local-preview.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// scripts/bongos/local-preview.js — the builder's control for the LOCAL game
+// preview (task 1056, ADR 0044). Runs the ADR 0052 game-only entry privately at
+// http://localhost:<port>.
+//
+//   npm run preview                          # start it (then open the URL)
+//   node scripts/bongos/local-preview.js status   is it up + the URL          (default)
+//   node scripts/bongos/local-preview.js start
+//   node scripts/bongos/local-preview.js restart  pick up your latest edits
+//   node scripts/bongos/local-preview.js stop
+//   node scripts/bongos/local-preview.js logs     dump the preview's output
+//   node scripts/bongos/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).`;
+
+(async () => {
+  const cmd = process.argv[2] || 'status';
+  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/bongos/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/bongos/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); });