@bongos/core 1.18.3 → 1.18.19

package/scripts/gds/deploy-divergence.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// Compare what a live instance is SERVING against what is on main.
+//
+// Merging to main deploys nothing (ADR 0108/0137 — publishing is manual and
+// owner-gated). That is by design, but every layer around it still reports
+// success: /builder-ship prints success, the publish-reconciler flips
+// confirmed → shipped, and credits pay out on "land". Nothing compared live
+// against main, so between 2026-07-24 and 2026-08-03 a hundred and seventy-one
+// commits — including a whole governance permission system — sat on main while
+// cloudbongos.com served 1.18.17, and nobody noticed for ten days (blocker
+// 1000097 / task 1002521). This script is the missing comparison.
+//
+// Two independent gaps, both reported:
+//   1. UNRELEASED — commits on main since the last CORE_VERSION bump. No
+//      instance can take these at any pin, because no version carries them.
+//   2. UNDEPLOYED — the live instance's coreVersion is behind the CORE_VERSION
+//      on main. A release exists; this instance has not moved its pin to it.
+//
+// Usage:
+//   node scripts/gds/deploy-divergence.js                  # check the instance this checkout talks to
+//   node scripts/gds/deploy-divergence.js --url https://example.com
+//   node scripts/gds/deploy-divergence.js --quiet          # only print on divergence
+//   node scripts/gds/deploy-divergence.js --warn-only      # always exit 0 (for a non-blocking ship warning)
+//
+// Exit codes: 0 aligned (or --warn-only), 1 diverged, 2 could not determine.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const { API_BASE, arg, hasFlag } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MODULE_API = path.join(REPO_ROOT, 'src', 'module-api.js');
+
+// Read CORE_VERSION by regex rather than require() — this runs in checkouts
+// (and CI) where loading the doorway would pull config/branding that may not
+// resolve, and we only ever want the literal.
+function coreVersionAt(ref) {
+  let src;
+  try {
+    src = ref
+      ? execSync(`git show ${ref}:src/module-api.js`, { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 })
+      : fs.readFileSync(MODULE_API, 'utf8');
+  } catch {
+    return null;
+  }
+  const m = src.match(/^const CORE_VERSION = '([^']+)'/m);
+  return m ? m[1] : null;
+}
+
+function git(cmd, fallback = null) {
+  try {
+    return execSync(`git ${cmd}`, { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 }).trim();
+  } catch {
+    return fallback;
+  }
+}
+
+// The commit that last changed the CORE_VERSION literal, and how many commits
+// sit on top of it. Must be `-G` (any diff line matching the regex), NOT `-S`:
+// `-S` fires only when the number of occurrences changes, and a bump rewrites
+// the single existing line — so `-S` silently walks back to the commit that
+// first introduced the constant and reports every commit since as unreleased.
+// `--no-merges` is load-bearing, not a nicety: a bump lands on main VIA a merge,
+// so counting merges means the moment any release lands there is always ≥1
+// "unreleased" commit — the merge that landed the bump. This check exists
+// because a real gap hid for ten days behind layers that all reported success;
+// one that cries wolf after every single release earns exactly the same
+// scrolling-past it was added to prevent. Merge commits carry no content of
+// their own, so they are not unreleased work. (task 1002558)
+function unreleasedSince(mainRef) {
+  const bump = git(`log ${mainRef} -1 --format=%H -G"^const CORE_VERSION = " -- src/module-api.js`);
+  if (!bump) return null;
+  const count = git(`rev-list --count --no-merges ${bump}..${mainRef}`);
+  const withMerges = git(`rev-list --count ${bump}..${mainRef}`);
+  return {
+    bump,
+    bumpShort: bump.slice(0, 8),
+    bumpSubject: git(`log -1 --format=%s ${bump}`, ''),
+    bumpDate: git(`log -1 --format=%cs ${bump}`, ''),
+    count: count === null ? null : Number(count),
+    countWithMerges: withMerges === null ? null : Number(withMerges),
+  };
+}
+
+function cmpSemver(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+async function fetchLive(base) {
+  const url = `${String(base).replace(/\/+$/, '')}/version`;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), 15000);
+  try {
+    const res = await fetch(url, { signal: ctl.signal, headers: { accept: 'application/json' } });
+    if (!res.ok) return { url, error: `HTTP ${res.status}` };
+    const body = await res.json();
+    if (!body || !body.coreVersion) return { url, error: 'no coreVersion field in /version' };
+    return { url, coreVersion: body.coreVersion, commitShort: body.commitShort || null };
+  } catch (e) {
+    return { url, error: e.name === 'AbortError' ? 'timed out after 15s' : (e.message || String(e)) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function check({ base } = {}) {
+  const target = base || arg('--url') || API_BASE;
+  const local = coreVersionAt(null);
+  if (!local) return { ok: false, undetermined: true, reason: 'could not read CORE_VERSION from src/module-api.js', target };
+
+  // Prefer origin/main — the released trunk — but fall back to HEAD in a
+  // checkout with no remote (a box, a tarball) so the check still says
+  // something useful instead of bailing.
+  const mainRef = git('rev-parse --verify --quiet origin/main') ? 'origin/main' : 'HEAD';
+  const onMain = coreVersionAt(mainRef) || local;
+  const unreleased = unreleasedSince(mainRef);
+  const live = await fetchLive(target);
+
+  if (live.error) return { ok: false, undetermined: true, reason: `could not read ${live.url}: ${live.error}`, target, local, onMain, unreleased };
+
+  const behind = cmpSemver(live.coreVersion, onMain) < 0;
+  const ahead = cmpSemver(live.coreVersion, onMain) > 0;
+  const hasUnreleased = !!(unreleased && unreleased.count > 0);
+
+  return {
+    ok: !behind && !hasUnreleased,
+    target, local, onMain, mainRef, unreleased, live, behind, ahead, hasUnreleased,
+  };
+}
+
+function report(r, { quiet = false } = {}) {
+  const say = (...a) => console.log(...a);
+
+  if (r.undetermined) {
+    console.error(`deploy-divergence: undetermined — ${r.reason}`);
+    return;
+  }
+  if (r.ok && quiet) return;
+
+  const host = String(r.target).replace(/^https?:\/\//, '');
+  say('');
+  say(`  Deploy divergence · ${host}`);
+  say('  ──────────────────────────────────────────────────────────');
+  say(`  live (serving)      ${r.live.coreVersion}${r.live.commitShort ? `  (instance commit ${r.live.commitShort})` : ''}`);
+  say(`  ${r.mainRef.padEnd(18)}  ${r.onMain}`);
+  // Only worth a line when a bump is in flight in this tree but not yet landed.
+  if (r.local !== r.onMain) say(`  working tree        ${r.local}  (not yet on ${r.mainRef})`);
+  if (r.unreleased) {
+    say(`  last bump           ${r.unreleased.bumpShort} ${r.unreleased.bumpDate} — ${r.unreleased.bumpSubject}`);
+  }
+  say('');
+
+  if (r.ok) {
+    say('  ✓ aligned — live matches main, and main carries no unreleased commits.');
+    say('');
+    return;
+  }
+
+  if (r.hasUnreleased) {
+    // Say which number this is: work commits and with-merges differ a lot on a
+    // big window (93 vs 171 for 1.18.18), and an unlabelled figure invites the
+    // "~100 vs 171" disagreement that muddied blocker 1000097.
+    const u = r.unreleased;
+    const merges = u.countWithMerges != null && u.countWithMerges !== u.count
+      ? ` (${u.countWithMerges} counting merges)` : '';
+    say(`  ⚠ UNRELEASED — ${u.count} work commit${u.count === 1 ? '' : 's'}${merges} on ${r.mainRef} since the last CORE_VERSION bump.`);
+    say('    No instance can take these at ANY pin: no published version contains them.');
+    say(`    Fix: bump CORE_VERSION in src/module-api.js (+ a changelog line) and land it.`);
+  }
+  if (r.behind) {
+    say(`  ⚠ UNDEPLOYED — live is ${r.live.coreVersion}, main declares ${r.onMain}.`);
+    say('    A release exists that this instance has not moved its pin to.');
+    say('    Fix: package-core, then move the instance pin (see docs/recipes/upgrading-the-core.md).');
+  }
+  if (r.ahead) {
+    say(`  note: live (${r.live.coreVersion}) is AHEAD of ${r.mainRef} (${r.onMain}) — this checkout is stale; fetch.`);
+  }
+  say('');
+  say('  Merging to main deploys nothing by design. "shipped" means "merged" —');
+  say('  it does not mean users can see it.');
+  say('');
+}
+
+async function main() {
+  const quiet = hasFlag('--quiet');
+  const warnOnly = hasFlag('--warn-only');
+  const r = await check();
+  report(r, { quiet });
+  if (warnOnly) return process.exit(0);
+  if (r.undetermined) return process.exit(2);
+  return process.exit(r.ok ? 0 : 1);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error('deploy-divergence: failed —', e.message || e);
+    process.exit(2);
+  });
+}
+
+module.exports = { check, report, coreVersionAt, unreleasedSince, cmpSemver };

package/scripts/gds/dev-lib.js

@@ -0,0 +1,309 @@
+'use strict';
+// scripts/gds/dev-lib.js — pure + injectable core of `bongos dev`, the one-command
+// LOCAL launcher for a standalone instance repo (ADR 0149).
+//
+// WHY. A project scaffolded by the creation flow ships a repo whose
+// config/branding.json points at http://localhost:<port> — it is CONFIGURED to run
+// on the owner's own machine — but the platform shipped no command that actually
+// STARTS it. Standing it up by hand is a six-part assembly (install+start Postgres,
+// createdb, migrate, set PORT/PGDATABASE/PGHOST/OAuth env, launch the server) with
+// three silent mismatches: the server reads PORT from env and NOT from branding
+// (platform-server.js:44); the server DB name collapses to the OS user while
+// migrate.sh defaults to `amazonprimea` (pool.js:47 vs migrate.sh:52) unless
+// PGDATABASE is set for BOTH; and node-pg defaults to the Linux peer socket
+// /var/run/postgresql (pool.js:46), which does not exist under Homebrew Postgres on
+// a Mac. `bongos dev` collapses all of that into one idempotent command.
+//
+// Everything here is a PURE transform or an INJECTABLE helper (deps.fs / deps.spawn
+// / deps.kill / deps.fetchImpl / deps.env / deps.userInfo / deps.*Path), so
+// tests/dev_lib.mjs exercises every decision with NO real spawn, DB, or network.
+// The side-effecting orchestration (start Postgres, createdb, run migrate, hand off
+// to login) lives in dev.js.
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const ic = require('../../src/instance-config');
+
+// The server binds loopback (platform-server.js HOST default). We probe the IP
+// literal, never "localhost", to dodge any IPv6/hosts-file quirk while it binds
+// 127.0.0.1 — the same choice local-preview-lib.js made.
+const HOST = '127.0.0.1';
+const DEFAULT_PORT = 3000;
+
+// scripts/gds/ -> the core package root (holds src/platform-server.js + scripts/migrate.sh).
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+
+function readJsonSafe(p, f = fs) {
+  try { return JSON.parse(f.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+// Read the instance-identity fields the launcher needs, INSTANCE pack first
+// (config/branding.json — host content, resolveInstanceRoot) then the CORE neutral
+// starter (config/branding.neutral.json — ships with the package). Decoupled from
+// the full branding() resolver on purpose (mirrors pool.js:instanceDbName): a
+// branding validation error must never stop a local dev boot.
+function loadBrandingFacts({ instanceRoot, coreRoot = CORE_ROOT, f = fs } = {}) {
+  const inst = readJsonSafe(path.join(instanceRoot, 'config', 'branding.json'), f) || {};
+  const neutral = readJsonSafe(path.join(coreRoot, 'config', 'branding.neutral.json'), f) || {};
+  const pick = (k, subk) => {
+    const from = (o) => (subk ? (o[k] && o[k][subk]) : o[k]);
+    const v = from(inst);
+    return (v === undefined || v === null || v === '') ? from(neutral) : v;
+  };
+  return {
+    publicOrigin: pick('domains', 'publicOrigin') || `http://localhost:${DEFAULT_PORT}`,
+    firstAdmin: pick('firstAdmin') || '',
+    // db.database is null in the neutral starter and usually absent in a fresh
+    // instance pack — deriveDbName() falls back to the repo dir name.
+    brandingDbName: (inst.db && inst.db.database) || (neutral.db && neutral.db.database) || null,
+    envPrefix: pick('envPrefix') || ic.FALLBACK_ENV_PREFIX,
+    configDir: pick('configDir') || ic.FALLBACK_DIR,
+    gameEnabled: false, // overridden by resolveRunParams from config/modules.json
+  };
+}
+
+// Port the instance is configured for. The server reads process.env.PORT and
+// ignores branding, so `bongos dev` MUST set PORT to this or the server would come
+// up on 3000 while branding (and every printed link) says <port>.
+function parsePort(origin, fallback = DEFAULT_PORT) {
+  try {
+    const p = new URL(String(origin)).port;
+    const n = Number(p);
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : fallback;
+  } catch { return fallback; }
+}
+
+// Coerce an arbitrary string into a legal, safe Postgres database identifier:
+// lowercased, non [a-z0-9_] collapsed to '_', must begin with a letter or '_'
+// (a leading digit is illegal unquoted), max 63 bytes. Returns null if nothing
+// usable survives, so deriveDbName can fall through to its last-resort default.
+function sanitizeDbName(s) {
+  if (!s) return null;
+  let out = String(s).toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+  if (!out) return null;
+  if (/^[0-9]/.test(out)) out = `db_${out}`;
+  return out.slice(0, 63);
+}
+
+// The DB name BOTH migrate.sh and the server pool will use. Precedence:
+//   explicit --db / override  ->  branding db.database  ->  the repo dir name  ->
+//   'cloudbongos_dev'. Whatever we pick is exported as PGDATABASE for both sides,
+//   which is the fix for the pool.js(OS-user) vs migrate.sh(amazonprimea) split.
+function deriveDbName({ brandingDbName, instanceRoot, override } = {}) {
+  return (
+    sanitizeDbName(override) ||
+    sanitizeDbName(brandingDbName) ||
+    sanitizeDbName(instanceRoot && path.basename(instanceRoot)) ||
+    'cloudbongos_dev'
+  );
+}
+
+// Resolve every parameter a local run needs, from branding + modules + env + argv.
+// Pure: all IO comes through injected deps (f/env/userInfo/argv). PGHOST defaults to
+// TCP 'localhost' (NOT the Linux peer socket the pool defaults to) so a Homebrew Mac
+// Postgres is reachable; an explicit PGHOST/PGUSER in the environment still wins.
+function resolveRunParams({
+  instanceRoot,
+  coreRoot = CORE_ROOT,
+  f = fs,
+  env = process.env,
+  userInfo = os.userInfo,
+  argv = [],
+} = {}) {
+  const facts = loadBrandingFacts({ instanceRoot, coreRoot, f });
+  const modules = readJsonSafe(path.join(instanceRoot, 'config', 'modules.json'), f) || {};
+  const gameEnabled = !!(modules.modules && modules.modules.game);
+
+  const portOverride = argFrom(argv, '--port');
+  const dbOverride = argFrom(argv, '--db');
+
+  const port = portOverride ? parsePort(`http://x:${portOverride}`, parsePort(facts.publicOrigin)) : parsePort(facts.publicOrigin);
+  const dbName = deriveDbName({ brandingDbName: facts.brandingDbName, instanceRoot, override: dbOverride });
+
+  let pgUser = env.PGUSER;
+  if (!pgUser) { try { pgUser = userInfo().username; } catch { pgUser = undefined; } }
+
+  return {
+    instanceRoot,
+    coreRoot,
+    port,
+    host: HOST,
+    dbName,
+    pgHost: env.PGHOST || 'localhost',
+    pgUser,
+    pgPassword: env.PGPASSWORD || undefined,
+    publicOrigin: facts.publicOrigin.replace(/\/+$/, ''),
+    firstAdmin: facts.firstAdmin,
+    envPrefix: facts.envPrefix,
+    configDir: facts.configDir,
+    // A local dev instance never wants OTB's instance-seed migrations (they FK-crash
+    // a non-owning DB — migrate.sh:56). Game-less instances skip them via
+    // MEDUSA_GDS_ONLY=1; when the game module IS enabled we still skip instance
+    // seeds (default-off) but do not force GDS-only, so game schema still applies.
+    gdsOnly: !gameEnabled,
+  };
+}
+
+// The env a child process (migrate or server) runs with. Starts from baseEnv (so
+// the child inherits any GitHub OAuth creds already in the shell) and overlays the
+// resolved run parameters. role='server' adds PORT/HOST; both roles set the PG*
+// trio + the instance-root pointer + the seed policy.
+function buildEnv(params, { baseEnv = process.env, role = 'server' } = {}) {
+  const env = { ...baseEnv };
+  env.PGHOST = params.pgHost;
+  if (params.pgUser) env.PGUSER = params.pgUser;
+  if (params.pgPassword) env.PGPASSWORD = params.pgPassword;
+  env.PGDATABASE = params.dbName;
+  if (params.gdsOnly) env.MEDUSA_GDS_ONLY = '1';
+  // Point migrate + the server at the instance explicitly, so resolution never
+  // depends on a stray cwd (migrate.sh:26 gotcha).
+  env[`${params.envPrefix}_INSTANCE_ROOT`] = params.instanceRoot;
+  if (role === 'server') {
+    env.PORT = String(params.port);
+    env.HOST = params.host;
+  }
+  return env;
+}
+
+// Does the machine have GitHub OAuth creds this instance's server will read?
+// Mirrors auth.js:loadGithubCreds EXACTLY (env <PREFIX>_GITHUB_CLIENT_ID/SECRET
+// with legacy fallbacks, else ~/.config/<configDir>/gds-github.json | pms-github.json)
+// so `bongos dev` predicts sign-in correctly instead of guessing.
+function authWillWork({ resolveEnv = ic.resolveEnv, readConfigFileSync = ic.readConfigFileSync } = {}) {
+  if (resolveEnv('GITHUB_CLIENT_ID') && resolveEnv('GITHUB_CLIENT_SECRET')) return true;
+  for (const name of ['gds-github.json', 'pms-github.json']) {
+    try {
+      const raw = readConfigFileSync(name);
+      if (raw) {
+        const c = JSON.parse(raw);
+        if (c && c.client_id && c.client_secret) return true;
+      }
+    } catch { /* try next */ }
+  }
+  return false;
+}
+
+// --- managed background server (the local analogue of local-preview-lib) --------
+// Keyed per (dbName, port) so two instances on one machine never collide on pid/log.
+
+function slug(params) { return `${params.dbName}-${params.port}`.replace(/[^a-z0-9_.-]+/gi, '_'); }
+function pidPath(params, deps = {}) {
+  return deps.pidPath || path.join((deps.tmpdir || os.tmpdir)(), `bongos-dev-${slug(params)}.pid`);
+}
+function logPath(params, deps = {}) {
+  return deps.logPath || path.join((deps.tmpdir || os.tmpdir)(), `bongos-dev-${slug(params)}.log`);
+}
+
+function readPid(params, deps = {}) {
+  const f = deps.fs || fs;
+  try {
+    const pid = Number(String(f.readFileSync(pidPath(params, deps), 'utf8')).trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch { return null; }
+}
+
+// signal-0 existence probe: EPERM = alive but unsignalable, ESRCH = 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(params, deps = {}) { return pidAlive(readPid(params, deps), deps); }
+
+function serverEntry(params) { return path.join(params.coreRoot, 'src', 'platform-server.js'); }
+
+// Start the platform server DETACHED (background), idempotent. Returns
+// { ok, already, pid, url, log }. The parent polls health, prints the managed-server
+// notice + the `bongos dev stop` command, and exits — the server keeps running.
+function startDetached(params, deps = {}) {
+  const f = deps.fs || fs;
+  const spawnImpl = deps.spawn || spawn;
+  if (isRunning(params, deps)) {
+    return { ok: true, already: true, pid: readPid(params, deps), url: params.publicOrigin, log: logPath(params, deps) };
+  }
+  const lp = logPath(params, deps);
+  let out = 'ignore';
+  try { out = f.openSync(lp, 'w'); } catch { /* fall back to ignore */ }
+  const child = spawnImpl(deps.nodePath || process.execPath, [serverEntry(params)], {
+    cwd: params.instanceRoot,
+    env: buildEnv(params, { baseEnv: deps.env || process.env, role: 'server' }),
+    detached: true,
+    stdio: ['ignore', out, out],
+    windowsHide: true,
+  });
+  child.unref();
+  if (child.pid) f.writeFileSync(pidPath(params, deps), String(child.pid) + '\n');
+  return { ok: true, already: false, pid: child.pid, url: params.publicOrigin, log: lp };
+}
+
+function stop(params, deps = {}) {
+  const f = deps.fs || fs;
+  const kill = deps.kill || process.kill;
+  const pid = readPid(params, deps);
+  if (!pid || !pidAlive(pid, deps)) {
+    try { f.rmSync(pidPath(params, 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(params, deps), { force: true }); } catch { /* best-effort */ }
+  return { ok: true, wasRunning: true, pid };
+}
+
+// Probe the running server. Returns { up, authConfigured }. `up` = the plain
+// /healthz (needs no DB); authConfigured comes from /api/gds/healthz.
+async function health(params, deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  const base = `http://${HOST}:${params.port}`;
+  const timeout = deps.healthTimeoutMs || 4000;
+  let up = false;
+  try {
+    const r = await fetchImpl(`${base}/healthz`, { signal: AbortSignal.timeout(timeout) });
+    up = r.status < 500;
+  } catch { return { up: false, authConfigured: false }; }
+  let authConfigured = false;
+  try {
+    const r = await fetchImpl(`${base}/api/gds/healthz`, { signal: AbortSignal.timeout(timeout) });
+    const j = await r.json();
+    authConfigured = j && j.auth_configured === true;
+  } catch { /* leave false */ }
+  return { up, authConfigured };
+}
+
+// argv helper local to dev-lib (dev.js uses cli-lib's arg() for the real process
+// argv; this variant is pure so resolveRunParams stays unit-testable). Accepts
+// `--flag value` and `--flag=value`.
+function argFrom(args, name) {
+  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;
+}
+
+// depsInstallPlan (task 1002405) — decide whether `bongos dev` must install node
+// deps before it can do anything useful, and with which command. A freshly-cloned
+// instance has no node_modules, so migrate.sh (pg) and the server (pg/express)
+// would crash; install FIRST — this makes `bongos dev` a true one-command bring-up
+// even from a bare checkout (the case where a global/npx bongos, or `node
+// <core>/scripts/gds/dev.js`, is reachable but deps are not). Prefer `npm ci` when
+// a lockfile is present (reproducible + faster), else `npm install`. Pure:
+// injectable fs.
+function depsInstallPlan({ instanceRoot, f = fs } = {}) {
+  const present = f.existsSync(path.join(instanceRoot, 'node_modules'));
+  if (present) return { needed: false, cmd: null, args: [] };
+  const hasLock = f.existsSync(path.join(instanceRoot, 'package-lock.json'));
+  return hasLock
+    ? { needed: true, cmd: 'ci', args: ['ci'] }
+    : { needed: true, cmd: 'install', args: ['install'] };
+}
+
+module.exports = {
+  HOST, DEFAULT_PORT, CORE_ROOT,
+  readJsonSafe, loadBrandingFacts, parsePort, sanitizeDbName, deriveDbName,
+  resolveRunParams, buildEnv, authWillWork, depsInstallPlan,
+  slug, pidPath, logPath, readPid, pidAlive, isRunning, serverEntry,
+  startDetached, stop, health, argFrom,
+};