@bongos/core 1.17.0

package/src/bongos/uptime-poller.js

@@ -0,0 +1,90 @@
+'use strict';
+
+// Uptime poller — runs inside the Node process, polls once per minute.
+// Writes results to uptime_checks. Prunes rows older than 90 days inline.
+//
+// Services checked:
+//   game_server — GET http://127.0.0.1:3000/healthz
+//   api         — GET http://127.0.0.1:3000/api/gds/healthz
+//   database    — direct Postgres query (SELECT 1)
+
+const http = require('node:http');
+const { pool } = require('./pool');
+
+const INTERVAL_MS = 60_000;
+const TIMEOUT_MS  = 8_000;
+const PRUNE_DAYS  = 90;
+
+const SERVICES = [
+  {
+    name: 'game_server',
+    check: () => httpGet('http://127.0.0.1:3000/healthz'),
+  },
+  {
+    name: 'api',
+    check: () => httpGet('http://127.0.0.1:3000/api/gds/healthz'),
+  },
+  {
+    name: 'database',
+    check: () => dbPing(),
+  },
+];
+
+function httpGet(url) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const req = http.get(url, { timeout: TIMEOUT_MS }, (res) => {
+      res.resume(); // drain
+      const latency = Date.now() - start;
+      const status = res.statusCode === 200 ? 'up'
+        : res.statusCode < 500 ? 'degraded'
+        : 'down';
+      resolve({ status, latency });
+    });
+    req.on('error', () => resolve({ status: 'down', latency: null }));
+    req.on('timeout', () => { req.destroy(); resolve({ status: 'down', latency: null }); });
+  });
+}
+
+async function dbPing() {
+  const start = Date.now();
+  try {
+    await pool.query('SELECT 1');
+    return { status: 'up', latency: Date.now() - start };
+  } catch (_) {
+    return { status: 'down', latency: null };
+  }
+}
+
+async function runChecks() {
+  for (const svc of SERVICES) {
+    try {
+      const { status, latency } = await svc.check();
+      await pool.query(
+        `INSERT INTO uptime_checks (service, status, latency_ms) VALUES ($1, $2, $3)`,
+        [svc.name, status, latency ?? null]
+      );
+    } catch (err) {
+      console.error(`[uptime] check failed for ${svc.name}:`, err.message);
+    }
+  }
+
+  // Prune old rows (fire-and-forget)
+  pool.query(
+    `DELETE FROM uptime_checks WHERE checked_at < now() - interval '${PRUNE_DAYS} days'`
+  ).catch((err) => console.error('[uptime] prune error:', err.message));
+}
+
+function start() {
+  // Stagger first check by 10s so the server finishes binding before we hit it
+  setTimeout(() => {
+    runChecks().catch((err) => console.error('[uptime] initial check error:', err.message));
+    setInterval(() => {
+      runChecks().catch((err) => console.error('[uptime] check error:', err.message));
+    }, INTERVAL_MS);
+  }, 10_000);
+
+  console.log('[uptime] poller started — checking every 60s');
+}
+
+module.exports = { start };

package/src/bongos-downloads.js

@@ -0,0 +1,70 @@
+// src/bongos-downloads.js — branded download redirects for the standalone
+// `bongos` CLI binary (task 1248, V4.R81).
+//
+// The compiled per-platform binaries can't ride the git-based deploy (private
+// repo, no LFS, GitHub's 100MB cap), so CI publishes them as release assets on a
+// PUBLIC releases repo (config/bongos-cli.json — the same off-repo pattern as the
+// Dev Box app, src/devbox-downloads.js, and the ADR 0029 status mirror). This
+// module turns that committed config into:
+//
+//   GET /downloads/bongos/latest.json   → { version, assets: { target: {file,url} } }
+//   GET /downloads/bongos/version       → { version, assets: { target: url } }
+//   GET /downloads/bongos/<target>      → 302 to the release asset
+//
+// so every URL a user sees or the installer fetches stays on the instance apex,
+// and a release bump is a one-file config change that rides the normal ship flow.
+// Pure (config in, urls out) so tests need no server.
+//
+// (A near-twin of src/devbox-downloads.js by design — same off-repo release
+// pattern, different artifact. Kept as its own module for a clear name + its own
+// config pointer; the two are independent instance features.)
+
+function buildBongosDownloads(cfg) {
+  if (!cfg || typeof cfg !== 'object') throw new Error('bongos-downloads: missing config');
+  const repo = String(cfg.releases_repo || '');
+  const version = String(cfg.version || '');
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) throw new Error(`bongos-downloads: bad releases_repo "${repo}"`);
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error(`bongos-downloads: bad version "${version}"`);
+
+  const assets = cfg.assets || {};
+  const aliases = cfg.aliases || {};
+
+  function assetUrl(file) {
+    // encodeURIComponent keeps a config typo from ever becoming a path traversal
+    // on the redirect target.
+    return `https://github.com/${repo}/releases/download/v${version}/${encodeURIComponent(file)}`;
+  }
+
+  // Resolve a request target ('mac-arm64', or an alias like 'mac') to a URL.
+  // null = unknown target → caller 404s. A stray `.exe` suffix is tolerated (the
+  // Windows asset carries one; mac/linux binaries have no extension).
+  function redirectFor(rawTarget) {
+    if (typeof rawTarget !== 'string' || rawTarget.length > 40) return null;
+    const target = rawTarget.toLowerCase().replace(/\.exe$/, '');
+    const key = Object.prototype.hasOwnProperty.call(aliases, target) ? aliases[target] : target;
+    const file = Object.prototype.hasOwnProperty.call(assets, key) ? assets[key] : null;
+    return file ? assetUrl(file) : null;
+  }
+
+  function latestJson() {
+    const out = { version, assets: {} };
+    for (const [target, file] of Object.entries(assets)) {
+      out.assets[target] = { file, url: assetUrl(file) };
+    }
+    return out;
+  }
+
+  // The flat {version, assets:{target:url}} form the installer + any update-check
+  // reads. No auth — same trust level as the redirects.
+  function versionJson() {
+    const out = { version, assets: {} };
+    for (const [target, file] of Object.entries(assets)) {
+      out.assets[target] = assetUrl(file);
+    }
+    return out;
+  }
+
+  return { redirectFor, latestJson, versionJson, version };
+}
+
+module.exports = { buildBongosDownloads };

package/src/branding.js

@@ -0,0 +1,182 @@
+// src/branding.js — the branding contract (ADR 0062 §3, task 1192 / V4.R53).
+//
+// The single source for every instance-identity string the platform renders:
+// product/world name, company, domains/origins, cookie + OAuth + dev-box
+// hosts, currency label, the track set, theme, and the project name injected
+// into LLM prompts. Generalizes devbox-app/src/brand.js to the whole platform.
+//
+// Resolution precedence (highest wins):
+//   env override  ->  instance config (config/branding.json)  ->  neutral
+//   starter (config/branding.neutral.json)
+// A fresh instance with NO config resolves to the PLAIN neutral identity —
+// never to a host's brand (fail-to-vanilla, never fail-to-OTB). ADR 0004's
+// "civ name = one config string" rule is satisfied here: code reads
+// branding.identity.worldName, never a string literal.
+//
+// Feature-module on/off flags are a SIBLING config owned by R54 (task 1193),
+// not part of the branding contract.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveCoreRoot, resolveInstanceRoot } = require('./instance-config');
+
+// ADR 0108 §1: the neutral starter ships WITH the core package; the instance
+// pack is host content. Both resolvers return the repo root today, so this is
+// byte-identical for the live instance.
+const NEUTRAL_PATH = path.join(resolveCoreRoot(), 'config', 'branding.neutral.json');
+const INSTANCE_PATH = path.join(resolveInstanceRoot(), 'config', 'branding.json');
+
+// Required after merge — resolution throws if any is missing/empty.
+const REQUIRED = [
+  ['identity', 'productName'],
+  ['identity', 'worldName'],
+  ['domains', 'publicOrigin'],
+  ['llmProjectName'],
+];
+
+// Env overrides: <ENVPREFIX>_<SUFFIX> -> config path. Only the
+// operationally-swapped fields (dev/staging) are env-overridable; everything
+// else comes from the committed pack.
+const ENV_OVERRIDES = [
+  ['PUBLIC_ORIGIN', ['domains', 'publicOrigin']],
+  ['BUILDERS_ORIGIN', ['domains', 'buildersOrigin']],
+  ['STATUS_ORIGIN', ['domains', 'statusOrigin']],
+  ['OAUTH_ORIGIN', ['domains', 'oauthOrigin']],
+  ['COOKIE_DOMAIN', ['domains', 'cookieDomain']],
+];
+
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+function deepMerge(base, over) {
+  if (!isObj(over)) return over === undefined ? base : over;
+  const out = isObj(base) ? { ...base } : {};
+  for (const k of Object.keys(over)) {
+    out[k] = isObj(over[k]) && isObj(out[k]) ? deepMerge(out[k], over[k]) : over[k];
+  }
+  return out;
+}
+
+function setPath(obj, p, val) {
+  let o = obj;
+  for (let i = 0; i < p.length - 1; i++) { o[p[i]] = isObj(o[p[i]]) ? o[p[i]] : {}; o = o[p[i]]; }
+  o[p[p.length - 1]] = val;
+}
+const getPath = (obj, p) => p.reduce((o, k) => (o == null ? o : o[k]), obj);
+
+function deepFreeze(o) {
+  if (isObj(o) || Array.isArray(o)) { Object.values(o).forEach(deepFreeze); Object.freeze(o); }
+  return o;
+}
+
+// Pure resolver — all inputs injected, so tests drive it with zero I/O.
+function resolveBranding({ neutral = {}, instance = {}, env = {} } = {}) {
+  // structuredClone so the merged result shares no nested references with the
+  // neutral/instance inputs — otherwise the deepFreeze below would also freeze
+  // the caller's input objects (deepMerge shallow-copies only the top level).
+  const resolved = structuredClone(deepMerge(neutral, instance));
+  const prefix = resolved.envPrefix || 'CLOUDBONGOS';
+  for (const [suffix, p] of ENV_OVERRIDES) {
+    const v = env[`${prefix}_${suffix}`];
+    if (v !== undefined && v !== '') setPath(resolved, p, v);
+  }
+  const missing = REQUIRED.filter((p) => {
+    const v = getPath(resolved, p);
+    return v === undefined || v === null || v === '';
+  });
+  if (missing.length) {
+    throw new Error(`branding: missing required field(s): ${missing.map((p) => p.join('.')).join(', ')}`);
+  }
+  return deepFreeze(resolved);
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+
+// Disk loader with the documented precedence. Instance config is OPTIONAL: a
+// vanilla instance ships only the neutral starter.
+//
+// Instance-pack selection (highest wins):
+//   explicit instancePath arg  ->  GDS_BRANDING_FILE env (a path)  ->  config/branding.json
+// The env knob lets ONE deployed checkout run two instances side by side — e.g.
+// OTB on the apex (server.js, the committed config/branding.json) and a vanilla
+// Cloud Bongos process pointed at its own pack (config/branding.cloudbongos.json)
+// — differentiated only by env, with no divergent clone to maintain. The loader
+// runs before the resolved envPrefix is known, so this is a FIXED env name (like
+// auth.js's GDS_PUBLIC_ORIGIN), not a <PREFIX>_ one. A relative path resolves
+// against the repo root.
+function loadBranding({ neutralPath = NEUTRAL_PATH, instancePath, env = process.env } = {}) {
+  const neutral = readJson(neutralPath);
+  if (!neutral) throw new Error(`branding: neutral starter not found at ${neutralPath}`);
+  let ip = instancePath;
+  if (ip === undefined) {
+    const override = env.GDS_BRANDING_FILE;
+    ip = override ? path.resolve(resolveInstanceRoot(), override) : INSTANCE_PATH;
+  }
+  const instance = readJson(ip) || {};
+  return resolveBranding({ neutral, instance, env });
+}
+
+// Resolved singleton for app code; lazy so require-time never crashes tooling
+// that doesn't touch branding.
+let _cached = null;
+const branding = () => (_cached ||= loadBranding());
+
+// The HTTP User-Agent the GDS sends on outbound API calls (GitHub, Discord),
+// derived from the instance branding pack so a non-OTB Cloud Bongos instance
+// identifies itself with ITS OWN name rather than a hardcoded "amazonprimea-gds"
+// (ADR 0062 §3/§5; the branding contract). Source order: the repo name (the
+// GitHub binding these calls actually target), else the env prefix, else a neutral
+// fallback. Falls back hard if branding fails so an outbound call never crashes.
+function userAgent() {
+  let base = 'cloud-bongos';
+  try {
+    const b = branding();
+    base = String(b.repo?.name || b.envPrefix || base).toLowerCase() || base;
+  } catch { /* fall through to the neutral default */ }
+  return `${base}-gds/1.0`;
+}
+
+// The CLIENT-SAFE projection of the resolved pack — the subset the browser is
+// allowed to see, served by GET /api/gds/public/branding and consumed by the
+// hall + status front-ends. Deliberately a small allow-list, NOT the whole pack:
+// origins, repo binding, db name, and env prefix are server-only and must never
+// reach the client. R56 (task 1195) seeded it with the configurable currency
+// label; R57 (task 1196) widens it to the LOOK + identity + rank labels so the
+// hall/status surfaces render from config instead of hard-coding OTB's Greek
+// strings. Note `theme.ui` (the WEB palette/fonts/favicon) is exposed, NOT
+// `theme.palette` (the server-only path to the game's pixel-art palette file).
+// Pure over the resolved pack so it is unit-testable without I/O.
+function clientBranding(b = branding()) {
+  const ui = b.theme?.ui || {};
+  return {
+    identity: {
+      productName: b.identity?.productName || '',
+      worldName: b.identity?.worldName || '',
+      company: { name: b.identity?.company?.name || '' },
+    },
+    currency: {
+      label: b.currency?.label || 'credits',
+      symbol: b.currency?.symbol || '',
+    },
+    theme: {
+      colors: ui.colors || {},
+      fonts: {
+        display: ui.fonts?.display || '',
+        body: ui.fonts?.body || '',
+        links: Array.isArray(ui.fonts?.links) ? ui.fonts.links : [],
+      },
+      favicon: ui.favicon || '',
+      backdrop: ui.backdrop || '',
+    },
+    copy: {
+      tagline: b.copy?.tagline || '',
+      hallName: b.copy?.hallName || 'Builders’ Hall',
+      notFound: b.copy?.notFound || 'Page not found.',
+    },
+    rankLabels: b.rankLabels || {},
+  };
+}
+
+module.exports = { resolveBranding, loadBranding, deepMerge, branding, clientBranding, userAgent, NEUTRAL_PATH, INSTANCE_PATH };

package/src/build-info.js

@@ -0,0 +1,77 @@
+// src/build-info.js — expose the running git commit so a deploy can be
+// commit-PINNED, not just liveness-checked (#858, ADR 0042 finding #2 residual).
+//
+// /healthz returns only "ok", so ship.js's ci-mode pollCiDeploy could confirm a
+// deploy RAN + the site was up, but not that prod is live on the EXACT commit it
+// just merged. This module resolves the deployed commit once (cached) and the
+// /version endpoint (server.js) serves it, so ship.js can assert
+// deployedCommit === mergeCommit before flipping a task to shipped.
+//
+// Resolution order (resolveCommit is pure + exported for the test):
+//   1. env OTB_GIT_SHA  — set by ~/deploy.sh at restart if/when it chooses to;
+//      authoritative + cheap, and survives a checkout with no usable .git.
+//   2. `git rev-parse HEAD` in the checkout — accurate after deploy.sh's
+//      `git reset --hard origin/main`.
+//   3. null — unknown (callers must degrade gracefully, never hard-fail).
+
+const { execSync } = require('node:child_process');
+
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+
+// Pure: pick the first valid-looking sha from (env, git). Exported so the test
+// asserts precedence + rejects garbage without touching child_process.
+function resolveCommit({ envSha, gitSha } = {}) {
+  const pick = (s) => {
+    const v = String(s == null ? '' : s).trim();
+    return SHA_RE.test(v) ? v : null;
+  };
+  return pick(envSha) || pick(gitSha) || null;
+}
+
+function readGitSha() {
+  try {
+    return execSync('git rev-parse HEAD', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// The deployed commit's date (ISO 8601), for the dev-box staleness comparison
+// (boxes.computeCodeStaleness, idea 332). A box reports its own HEAD commit date;
+// if it's > 2 days behind THIS, the box is flagged stale. Best-effort: after a
+// `git reset --hard origin/main` deploy, HEAD is the deployed commit, so its
+// committer date is the right reference. Null when git is unavailable (then the
+// "behind" check is skipped and only never-reported boxes flag).
+function readGitCommitDate() {
+  try {
+    return execSync('git show -s --format=%cI HEAD', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+let _cache = null;
+
+// Resolved once per process. The commit can't change without a restart (deploy
+// restarts the service), so caching is correct and keeps /version allocation-free.
+function buildInfo() {
+  if (_cache) return _cache;
+  const fromEnv = resolveCommit({ envSha: process.env.OTB_GIT_SHA });
+  const commit = fromEnv || resolveCommit({ gitSha: readGitSha() });
+  _cache = {
+    commit,
+    commitShort: commit ? commit.slice(0, 8) : null,
+    resolvedVia: fromEnv ? 'env' : commit ? 'git' : 'unknown',
+    commitDate: readGitCommitDate(),
+    startedAt: new Date().toISOString(),
+  };
+  return _cache;
+}
+
+module.exports = { resolveCommit, readGitSha, readGitCommitDate, buildInfo, SHA_RE };

package/src/devbox-downloads.js

@@ -0,0 +1,67 @@
+// src/devbox-downloads.js — branded download redirects for the Dev Box
+// desktop app (#904, ADR 0045).
+//
+// The installers (~100MB Electron artifacts) cannot ride the git-based deploy
+// (private repo, no LFS, GitHub's 100MB hard cap), so CI publishes them as
+// release assets on a PUBLIC releases repo (config/devbox-app.json — same
+// off-repo pattern as the ADR 0029 status mirror). This module turns that
+// committed config into:
+//
+//   GET /downloads/devbox/latest.json   → { version, assets: { target: url } }
+//   GET /downloads/devbox/<target>      → 302 to the release asset
+//
+// so every URL a builder ever sees or shares stays on amazonprimea.com, and a
+// release bump is a one-file config change that rides the normal ship flow.
+// Pure (config in, urls out) so tests need no server.
+
+function buildDevboxDownloads(cfg) {
+  if (!cfg || typeof cfg !== 'object') throw new Error('devbox-downloads: missing config');
+  const repo = String(cfg.releases_repo || '');
+  const version = String(cfg.version || '');
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) throw new Error(`devbox-downloads: bad releases_repo "${repo}"`);
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error(`devbox-downloads: bad version "${version}"`);
+
+  const assets = cfg.assets || {};
+  const aliases = cfg.aliases || {};
+
+  function assetUrl(file) {
+    // encodeURIComponent keeps a config typo from ever turning into a path
+    // traversal on the redirect target.
+    return `https://github.com/${repo}/releases/download/v${version}/${encodeURIComponent(file)}`;
+  }
+
+  // Resolve a request target ('mac-arm64', or an alias like 'mac') to a URL.
+  // null = unknown target → caller 404s.
+  function redirectFor(rawTarget) {
+    if (typeof rawTarget !== 'string' || rawTarget.length > 32) return null;
+    const target = rawTarget.toLowerCase().replace(/\.(dmg|exe)$/, '');
+    const key = Object.prototype.hasOwnProperty.call(aliases, target) ? aliases[target] : target;
+    const file = Object.prototype.hasOwnProperty.call(assets, key) ? assets[key] : null;
+    return file ? assetUrl(file) : null;
+  }
+
+  function latestJson() {
+    const out = { version, assets: {} };
+    for (const [target, file] of Object.entries(assets)) {
+      out.assets[target] = { file, url: assetUrl(file) };
+    }
+    return out;
+  }
+
+  // The lightweight update-check payload (#924): `{ version, assets: {target: url} }`
+  // — the flat, download-ready form the Dev Box app polls to decide "is there a
+  // newer release?" and the hall /settings courtesy line reads to show "latest
+  // version: X". Distinct from latestJson()'s {file,url} shape (which the
+  // downloads page renders). No auth — same trust level as the redirects.
+  function versionJson() {
+    const out = { version, assets: {} };
+    for (const [target, file] of Object.entries(assets)) {
+      out.assets[target] = assetUrl(file);
+    }
+    return out;
+  }
+
+  return { redirectFor, latestJson, versionJson, version };
+}
+
+module.exports = { buildDevboxDownloads };