@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/dev-lib.js

@@ -0,0 +1,722 @@
+'use strict';
+// scripts/bongos/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 `example` (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/bongos/ -> the core package root (holds src/platform-server.js + scripts/migrate.sh).
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+
+// The one role the Windows Postgres installer creates (task 1002707).
+const WINDOWS_PG_USER = 'postgres';
+
+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(example) 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/platform). 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 = [],
+  mode = null,
+  platform = process.platform,
+} = {}) {
+  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');
+  // 'server' = a real host (systemd-supervised, no auto-login, outward health
+  // probe); 'local' = the ADR 0149 laptop path. Same six steps either way.
+  const runMode = mode || (argv.includes('--server') ? 'server' : 'local');
+
+  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;
+  // Windows (task 1002707): the Postgres installer creates exactly one role,
+  // `postgres`. Your Windows login name is never a role there, so defaulting to
+  // it would fail every connection with 'role "<you>" does not exist'.
+  if (!pgUser && platform === 'win32') pgUser = WINDOWS_PG_USER;
+  if (!pgUser) { try { pgUser = userInfo().username; } catch { pgUser = undefined; } }
+
+  const publicOrigin = facts.publicOrigin.replace(/\/+$/, '');
+
+  return {
+    instanceRoot,
+    coreRoot,
+    mode: runMode,
+    port,
+    host: deriveBindHost({ publicOrigin, mode: runMode, override: argFrom(argv, '--bind') || env.HOST }),
+    dbName,
+    pgHost: env.PGHOST || 'localhost',
+    pgUser,
+    pgPassword: env.PGPASSWORD || undefined,
+    publicOrigin,
+    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/bongos/healthz.
+async function health(params, deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  const base = `http://${probeHost(params)}:${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/bongos/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/bongos/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'] };
+}
+
+// ========================= WINDOWS (task 1002707) =========================
+// `bongos dev` is the local-hall path every project without an address is told to
+// run (ADR 0323 made bring-your-own-host the free default), so a Windows owner has
+// to be able to one-command it too. Four things differ on Windows, and each is a
+// pure decision here so tests/dev_windows.mjs proves it on any OS:
+//   1. npm is a .cmd shim, which a plain spawn cannot start;
+//   2. the bash for migrate.sh is Git Bash, and the `bash.exe` on PATH may be WSL's
+//      launcher, which cannot reach a Windows Postgres or node;
+//   3. the Postgres installer neither puts psql on PATH nor creates a role named
+//      after you: its one role is `postgres`, behind the password chosen at install;
+//   4. Postgres runs as a Windows service, not under Homebrew or systemd.
+// Docker (docs/recipes/self-host.md) stays the fallback when none of this fits.
+// Paths are built with path.win32 so the answers are Windows-shaped on any host.
+
+// Windows env names are case-insensitive (`Path`, `ProgramFiles`), but a copied or
+// injected env is a plain object. Read it the way Windows would.
+function envGet(env, name) {
+  if (!env) return undefined;
+  if (env[name] !== undefined) return env[name];
+  const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+  return key === undefined ? undefined : env[key];
+}
+
+// How to run `npm <args>`. On Windows `npm` is `npm.cmd`, and Node will not spawn a
+// .cmd without a shell: bare `npm` is ENOENT and `npm.cmd` is EINVAL since the
+// CVE-2024-27980 fix (docs/recipes/windows-builders.md). Prefer npm's own entry
+// point run by node (npm-cli.js ships beside node.exe), which needs no shell at
+// all; else fall back to the shim through cmd.exe, as ONE command string so Node
+// never concatenates an args array unescaped (DEP0190). The args are fixed verbs
+// ('ci' / 'install'), never user input. Mac/Linux keep the plain spawn.
+function npmInvocation(args = [], { platform = process.platform, execPath = process.execPath, exists = fs.existsSync } = {}) {
+  if (platform !== 'win32') return { cmd: 'npm', args: [...args], shell: false };
+  const npmCli = path.win32.join(path.win32.dirname(execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+  if (exists(npmCli)) return { cmd: execPath, args: [npmCli, ...args], shell: false };
+  return { cmd: ['npm', ...args].join(' '), args: [], shell: true };
+}
+
+// Is this bash.exe WSL's launcher? C:\Windows\System32\bash.exe (and the
+// WindowsApps alias) start a Linux distro that cannot see Windows' node, psql or
+// PATH, so migrate.sh would "run" there and fail naming nothing useful.
+function isWslBashLauncher(p) {
+  const s = String(p).replace(/\\/g, '/').toLowerCase();
+  return /\/windows\/(system32|sysnative)\/bash\.exe$/.test(s) || s.includes('/windowsapps/');
+}
+
+// Which bash runs migrate.sh. Mac/Linux: `bash` on PATH, as before. Windows: Git
+// Bash, the shell Windows builders already use and the one migrate.sh is written to
+// handle. Looked for cheapest-to-trust first: the Git Bash this terminal runs in
+// (EXEPATH), Git's install folders, beside the `git` on PATH, then any non-WSL bash
+// on PATH. Returns { ok, bin, source }, or { ok: false, wslOnly } when nothing
+// usable exists (wslOnly = the only bash seen was WSL's, which deserves a sentence).
+function resolveBash({ platform = process.platform, env = process.env, has = () => false, whereAll = () => [], exists = fs.existsSync } = {}) {
+  if (platform !== 'win32') return has('bash') ? { ok: true, bin: 'bash', source: 'PATH' } : { ok: false, wslOnly: false };
+  const w = path.win32;
+  const candidates = [];
+  const exe = envGet(env, 'EXEPATH'); // set by Git Bash: its install root or its bin folder
+  if (exe) candidates.push([w.join(exe, 'bash.exe'), 'Git Bash'], [w.join(exe, 'bin', 'bash.exe'), 'Git Bash']);
+  for (const base of [envGet(env, 'ProgramFiles'), envGet(env, 'ProgramW6432'), envGet(env, 'ProgramFiles(x86)')]) {
+    if (base) candidates.push([w.join(base, 'Git', 'bin', 'bash.exe'), 'Git for Windows']);
+  }
+  const local = envGet(env, 'LOCALAPPDATA');
+  if (local) candidates.push([w.join(local, 'Programs', 'Git', 'bin', 'bash.exe'), 'Git for Windows']);
+  // git.exe sits in <root>\cmd, <root>\bin or <root>\mingw64\bin; bash in <root>\bin.
+  for (const git of whereAll('git')) {
+    let dir = w.dirname(git);
+    for (let i = 0; i < 3; i++) { candidates.push([w.join(dir, 'bin', 'bash.exe'), 'Git for Windows']); dir = w.dirname(dir); }
+  }
+  let wslSeen = false;
+  for (const b of whereAll('bash')) {
+    if (isWslBashLauncher(b)) wslSeen = true;
+    else candidates.push([b, 'PATH']);
+  }
+  for (const [bin, source] of candidates) {
+    if (exists(bin)) return { ok: true, bin, source };
+  }
+  return { ok: false, wslOnly: wslSeen };
+}
+
+// migrate.sh's path as Git Bash must receive it. The script finds the core with
+// `dirname "$0"`, and bash's dirname splits on `/` only: handed C:\x\scripts\migrate.sh
+// it answers ".", so the script would look for migrations under whatever folder it
+// was started in. Forward slashes (C:/x/scripts/migrate.sh) keep that working.
+function bashScriptPath(p, platform = process.platform) {
+  return platform === 'win32' ? String(p).replace(/\\/g, '/') : p;
+}
+
+// The Postgres Windows installer (postgresql.org/download/windows) puts the server
+// and its client tools in %ProgramFiles%\PostgreSQL\<version>\bin but does NOT add
+// that folder to PATH, so `psql` looks missing on a machine where Postgres is
+// installed and running. Find those folders, newest first, so dev.js can put the
+// tools on PATH for this run instead of asking an owner to edit PATH by hand. Each
+// entry also names the installer's Windows service (postgresql-x64-<version>).
+function windowsPgInstalls({ env = process.env, readdir = (d) => fs.readdirSync(d), exists = fs.existsSync } = {}) {
+  const w = path.win32;
+  const seen = new Set();
+  const out = [];
+  for (const base of [envGet(env, 'ProgramFiles'), envGet(env, 'ProgramW6432'), envGet(env, 'ProgramFiles(x86)')]) {
+    if (!base) continue;
+    const root = w.join(base, 'PostgreSQL');
+    let entries;
+    try { entries = readdir(root); } catch { continue; }
+    for (const name of entries) {
+      const version = Number.parseFloat(String(name));
+      if (!Number.isFinite(version) || version <= 0) continue;
+      const bin = w.join(root, String(name), 'bin');
+      if (seen.has(bin.toLowerCase()) || !exists(w.join(bin, 'psql.exe'))) continue;
+      seen.add(bin.toLowerCase());
+      out.push({ version, bin, service: `postgresql-x64-${name}` });
+    }
+  }
+  return out.sort((a, b) => b.version - a.version);
+}
+
+// psql/createdb connection flags: -h/-U only when we have them (libpq fills the
+// rest). On Windows add -w (never prompt): the installer's `postgres` role is
+// password-only, and a console prompt is a trap there. psql would take a typed
+// password that migrations, the server and every later run never see. Failing fast
+// lets dev.js say which password to set (pgAuthHint). pg_isready has no -w flag, so
+// its caller passes { forReady: true }.
+function pgClientArgs(params, { platform = process.platform, forReady = false } = {}) {
+  const a = ['-h', params.pgHost];
+  if (params.pgUser) a.push('-U', params.pgUser);
+  if (platform === 'win32' && !forReady) a.push('-w');
+  return a;
+}
+
+// The shared "give it your Postgres password" lines (Windows installs only).
+const WINDOWS_PGPASSWORD_LINES = [
+  'Give bongos dev that password in the terminal you run it from, then re-run it:',
+  '  PowerShell:  $env:PGPASSWORD = "<that password>"; npx bongos dev',
+  '  Git Bash:    PGPASSWORD="<that password>" npx bongos dev',
+  'To keep it for next time:  setx PGPASSWORD "<that password>"  (then open a new terminal).',
+];
+
+// What to tell someone whose Postgres client tools are missing, per platform, so a
+// Windows owner gets Windows steps instead of a Homebrew line.
+function pgInstallHint(platform = process.platform) {
+  if (platform === 'darwin') return ['brew install postgresql@16 && brew services start postgresql@16'];
+  if (platform === 'win32') {
+    return [
+      'Download the Windows installer from https://www.postgresql.org/download/windows/ and run it.',
+      'Keep the default port (5432), and note the password it asks you to choose for the "postgres" user.',
+      ...WINDOWS_PGPASSWORD_LINES,
+      'Rather not install Postgres? The Docker path in docs/recipes/self-host.md runs everything in containers.',
+    ];
+  }
+  return ['(Debian/Ubuntu) sudo apt-get install -y postgresql   (or your distro’s package)'];
+}
+
+// How to start Postgres by hand when dev.js could not, per platform.
+function pgStartHint(platform = process.platform, { pgInstalls = [] } = {}) {
+  if (platform === 'darwin') return ['brew services start postgresql@16'];
+  if (platform === 'win32') {
+    const svc = (pgInstalls[0] && pgInstalls[0].service) || 'postgresql-x64-16';
+    return [
+      `Press Win+R, type services.msc, find "${svc}" in the list, and click Start.`,
+      `Or, in a PowerShell opened with "Run as administrator":  Start-Service ${svc}`,
+    ];
+  }
+  return ['sudo service postgresql start'];
+}
+
+// Windows only: a createdb/psql refused on authentication almost always means
+// PGPASSWORD is unset or wrong for the installer's `postgres` role. [] otherwise,
+// so Mac/Linux output is unchanged.
+function pgAuthHint(platform = process.platform, stderr = '') {
+  if (platform !== 'win32') return [];
+  if (!/password authentication failed|no password supplied|role .* does not exist/i.test(String(stderr))) return [];
+  return [
+    'Postgres on Windows has one user, "postgres", protected by the password you chose when you installed it.',
+    ...WINDOWS_PGPASSWORD_LINES,
+    'Using a different Postgres user? Set PGUSER to it the same way.',
+  ];
+}
+
+// No usable bash for migrations. Windows only (Mac and Linux ship bash); names Git
+// for Windows first and Docker as the fallback, and explains a WSL-only bash.
+function bashMissingHint(platform = process.platform, { wslOnly = false } = {}) {
+  if (platform !== 'win32') return [];
+  const lines = [];
+  if (wslOnly) lines.push('The only bash found belongs to WSL (C:\\Windows\\System32\\bash.exe). It runs Linux, so it cannot reach a Windows Postgres or Node.');
+  lines.push(
+    'Install Git for Windows from https://git-scm.com/download/win (it includes Git Bash, which runs the migrations),',
+    'then open a new terminal and re-run `npx bongos dev`.',
+    'Or skip the local tools entirely with the Docker path: docs/recipes/self-host.md.',
+  );
+  return lines;
+}
+
+// ===================== SERVER MODE (task 1002398, ADR 0162) =====================
+// The SAME boot path — deps -> Postgres -> createdb -> migrate -> env -> server ->
+// health — retargeted at a real host. Four decisions differ from local, and every
+// one of them is a pure function here so tests/dev_lib.mjs can prove it without a
+// host: where to bind, how to start Postgres, how the DB role gets bootstrapped
+// under peer auth, and what supervises the process.
+
+// `bongos serve stop` arrives as argv ['--server','stop'] once bin/bongos.js
+// prefixes the mode flag, and `--port 3006 status` puts a VALUE where the old
+// `argv[0]` scan looked for the subcommand. Resolve the subcommand by skipping
+// flags and the values they consume, so flag order never changes the verb.
+const VALUE_FLAGS = new Set(['--port', '--db', '--bind', '--user', '--env-file']);
+
+function parseSub(argv = [], fallback = 'up') {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') break;
+    if (a.startsWith('-')) { if (VALUE_FLAGS.has(a)) i++; continue; }
+    return a;
+  }
+  return fallback;
+}
+
+// Where the server binds. Local is always loopback. On a real host the right
+// answer is derivable from the origin the instance is CONFIGURED for, so an
+// operator never has to reason about it:
+//   https://…            -> a TLS-terminating proxy fronts us  -> 127.0.0.1
+//   http://localhost:…   -> a local-shaped origin on a host     -> 127.0.0.1
+//   http://<public>:…    -> nothing in front of us yet          -> 0.0.0.0
+// An explicit --bind (or HOST in the environment) still wins over all of it.
+function deriveBindHost({ publicOrigin, mode = 'local', override } = {}) {
+  if (override) return String(override);
+  if (mode !== 'server') return HOST;
+  let u;
+  try { u = new URL(String(publicOrigin)); } catch { return HOST; }
+  if (u.protocol === 'https:') return HOST;
+  if (u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '::1') return HOST;
+  return '0.0.0.0';
+}
+
+// The address to PROBE for health. Binding 0.0.0.0 still answers on loopback;
+// binding one specific address does not, so probe whatever we actually bound.
+function probeHost(params = {}) {
+  const h = params.host || HOST;
+  return (h === '0.0.0.0' || h === '::') ? HOST : h;
+}
+
+function serviceName(params) { return `bongos-${sanitizeDbName(params.dbName) || 'instance'}`; }
+function unitPath(params, { systemdDir = '/etc/systemd/system' } = {}) {
+  return path.posix.join(systemdDir, `${serviceName(params)}.service`);
+}
+// Secrets (PGPASSWORD, GitHub OAuth creds) belong in a root-owned 0600 file the
+// unit references, NEVER in Environment= lines — `systemctl show` and the journal
+// expose those to any user on the box.
+function envFilePath(params, { etcBase = '/etc/bongos' } = {}) {
+  return path.posix.join(etcBase, `${serviceName(params)}.env`);
+}
+
+// The unit's Environment= set: ONLY the keys the boot path resolves. Deliberately
+// not buildEnv() — that spreads the caller's whole environment, which under
+// systemd would bake a builder's shell (tokens included) into a root-owned file.
+function unitEnvironment(params) {
+  const pairs = [
+    ['PORT', String(params.port)],
+    ['HOST', params.host],
+    ['PGHOST', params.pgHost],
+    ['PGDATABASE', params.dbName],
+    ['NODE_ENV', 'production'],
+  ];
+  if (params.pgUser) pairs.push(['PGUSER', params.pgUser]);
+  if (params.gdsOnly) pairs.push(['MEDUSA_GDS_ONLY', '1']);
+  pairs.push([`${params.envPrefix}_INSTANCE_ROOT`, params.instanceRoot]);
+  return pairs;
+}
+
+// systemd accepts Environment="K=v with spaces"; quote every value so a path with
+// a space (or a quote) can't split the assignment.
+function quoteUnitValue(v) { return `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`; }
+
+function renderSystemdUnit(params, { nodePath = process.execPath, user, group, envFile } = {}) {
+  const env = unitEnvironment(params).map(([k, v]) => `Environment=${quoteUnitValue(`${k}=${v}`)}`);
+  const lines = [
+    '[Unit]',
+    `Description=Cloud Bongos instance ${params.dbName} (bongos serve)`,
+    'Wants=network-online.target',
+    // postgresql.service may not exist (managed/remote DB) — After= on an absent
+    // unit is a no-op, so this is safe either way and orders us correctly when it
+    // IS local. No Requires=: a remote-DB host must still boot.
+    'After=network-online.target postgresql.service',
+    '',
+    '[Service]',
+    'Type=simple',
+    `WorkingDirectory=${params.instanceRoot}`,
+    `ExecStart=${nodePath} ${serverEntry(params)}`,
+    ...env,
+    `EnvironmentFile=-${envFile || envFilePath(params)}`,
+    // Survive a crash AND a reboot — the whole point of moving off the pid file.
+    'Restart=always',
+    'RestartSec=3',
+    'NoNewPrivileges=yes',
+    'StandardOutput=journal',
+    'StandardError=journal',
+  ];
+  if (user) lines.push(`User=${user}`);
+  if (group) lines.push(`Group=${group}`);
+  lines.push('', '[Install]', 'WantedBy=multi-user.target', '');
+  return lines.join('\n');
+}
+
+// Can this host supervise with systemd, and do we need sudo to install the unit?
+function systemdPlan({ platform = process.platform, has = () => false, isRoot = false } = {}) {
+  if (platform !== 'linux') return { available: false, reason: `systemd is linux-only (this host is ${platform})` };
+  if (!has('systemctl')) return { available: false, reason: 'systemctl is not on PATH' };
+  if (isRoot) return { available: true, sudo: false };
+  if (!has('sudo')) return { available: false, reason: 'installing a unit needs root, and sudo is not on PATH' };
+  return { available: true, sudo: true };
+}
+
+// Prefix a step with non-interactive sudo when we are not already root. `sudo -n`
+// never prompts: on a host without passwordless sudo it fails fast with a clear
+// error instead of hanging a deploy on a hidden password prompt.
+function withSudo(step, { isRoot = false, sudo = true } = {}) {
+  if (isRoot || !sudo) return step;
+  return { ...step, cmd: 'sudo', args: ['-n', step.cmd, ...step.args] };
+}
+
+// Ordered candidates for "start Postgres", best-first for the platform. dev.js
+// tries each until pg_isready passes. Homebrew keeps its own branch there (the
+// formula name has to be discovered at runtime); everything else is decided here.
+// On Windows, Postgres is a Windows service per installed version (pgInstalls, from
+// windowsPgInstalls). `net start` needs an Administrator terminal; from an ordinary
+// one it fails fast with "Access is denied", and dev.js moves on to pgStartHint.
+function pgStartPlan({ platform = process.platform, has = () => false, env = process.env, isRoot = false, pgInstalls = [] } = {}) {
+  const out = [];
+  if (platform === 'darwin' && has('brew')) out.push({ cmd: 'brew', args: ['services', 'start'], needsFormula: true, label: 'Homebrew' });
+  if (platform === 'linux') {
+    if (has('systemctl')) out.push(withSudo({ cmd: 'systemctl', args: ['start', 'postgresql'], label: 'systemd' }, { isRoot }));
+    else if (has('service')) out.push(withSudo({ cmd: 'service', args: ['postgresql', 'start'], label: 'service' }, { isRoot }));
+  }
+  if (platform === 'win32') {
+    for (const inst of pgInstalls) out.push({ cmd: 'net', args: ['start', inst.service], label: `Windows service ${inst.service}` });
+  }
+  if (has('pg_ctl') && env.PGDATA) out.push({ cmd: 'pg_ctl', args: ['start', '-w', '-D', env.PGDATA], label: 'pg_ctl' });
+  return out;
+}
+
+// Postgres identifiers are case-folded unless quoted, and a role name reaches the
+// server as SQL text — quote it properly and refuse anything that isn't a plain
+// identifier rather than interpolating a surprise into a CREATE ROLE.
+const SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function quoteIdent(s) { return `"${String(s).replace(/"/g, '""')}"`; }
+
+// The fresh-Debian wall: `apt-get install postgresql` creates exactly ONE role,
+// `postgres`, reachable only by peer auth as the postgres OS user. A deploy user
+// running `createdb` gets 'role "deploy" does not exist' — which reads like a
+// broken install and is really just an unbootstrapped cluster. These two steps,
+// run as the postgres superuser, are the whole fix.
+function pgBootstrapPlan({ pgUser, dbName, isRoot = false, has = () => false } = {}) {
+  if (!pgUser || !SAFE_IDENT.test(pgUser)) return { ok: false, reason: `refusing to bootstrap an unsafe role name: ${pgUser || '(none)'}` };
+  if (!dbName || !SAFE_IDENT.test(dbName)) return { ok: false, reason: `refusing to bootstrap an unsafe database name: ${dbName || '(none)'}` };
+  // Reach the postgres superuser the way this host allows: `sudo -u postgres` for
+  // a normal deploy user (and for root when sudo exists), else `su postgres -c`
+  // when we are already root on a minimal image with no sudo installed.
+  let asPostgres;
+  if (has('sudo')) asPostgres = (cmd, args, label) => ({ cmd: 'sudo', args: ['-n', '-u', 'postgres', cmd, ...args], label });
+  else if (isRoot) asPostgres = (cmd, args, label) => ({ cmd: 'su', args: ['postgres', '-c', shellJoin([cmd, ...args])], label });
+  else return { ok: false, reason: 'bootstrapping the role needs the postgres superuser (root or sudo)' };
+
+  return {
+    ok: true,
+    steps: [
+      { ...asPostgres('psql', ['-v', 'ON_ERROR_STOP=1', '-tAc',
+        `SELECT 1 FROM pg_roles WHERE rolname='${pgUser}'`], 'check role'), id: 'check-role' },
+      { ...asPostgres('psql', ['-v', 'ON_ERROR_STOP=1', '-c',
+        `CREATE ROLE ${quoteIdent(pgUser)} LOGIN CREATEDB`], 'create role'), id: 'create-role' },
+      { ...asPostgres('createdb', ['-O', pgUser, dbName], 'create database'), id: 'create-db' },
+    ],
+  };
+}
+
+// Quote an argv into a single `su -c` string. Only ever fed argv this module
+// built from validated identifiers, but quote anyway — `su -c` is a shell.
+function shellJoin(argv) {
+  return argv.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${String(a).replace(/'/g, `'\\''`)}'`)).join(' ');
+}
+
+// Health as seen from OUTSIDE — does the origin the instance advertises actually
+// answer? On a server that also exercises DNS, the proxy, and TLS, which the
+// loopback probe cannot see. Advisory: DNS may legitimately not be wired yet.
+async function publicHealth(params, deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  const timeout = deps.healthTimeoutMs || 6000;
+  try {
+    const r = await fetchImpl(`${params.publicOrigin}/healthz`, { signal: AbortSignal.timeout(timeout) });
+    return { reachable: r.status < 500, status: r.status };
+  } catch (e) {
+    return { reachable: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+module.exports = {
+  HOST, DEFAULT_PORT, CORE_ROOT, WINDOWS_PG_USER,
+  readJsonSafe, loadBrandingFacts, parsePort, sanitizeDbName, deriveDbName,
+  resolveRunParams, buildEnv, authWillWork, depsInstallPlan,
+  // Windows (task 1002707). envGet stays private — a lookup helper, not a surface.
+  npmInvocation, isWslBashLauncher, resolveBash, bashScriptPath, windowsPgInstalls,
+  pgClientArgs, pgInstallHint, pgStartHint, pgAuthHint, bashMissingHint,
+  slug, pidPath, logPath, readPid, pidAlive, isRunning, serverEntry,
+  startDetached, stop, health, argFrom,
+  // server mode (task 1002398). withSudo/quoteIdent/shellJoin stay private —
+  // they are implementation details of the plans above, not a callable surface.
+  parseSub, deriveBindHost, probeHost, serviceName, unitPath, envFilePath,
+  unitEnvironment, renderSystemdUnit, systemdPlan, pgStartPlan,
+  pgBootstrapPlan, publicHealth,
+};