@bongos/core 1.19.101 → 1.19.103

package/scripts/gds/dev.js

@@ -57,22 +57,36 @@ function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 function usage() {
-  console.log(`bongos dev — run THIS instance locally, in one command.
+  console.log(`bongos dev — run THIS instance, in one command.
 
 Usage:
   bongos dev [--foreground] [--no-login] [--skip-migrate] [--port <n>] [--db <name>]
   bongos dev stop        Stop the local server this launched
   bongos dev status      Show whether it's running, its URL, and sign-in state
 
+  bongos serve           Same boot path, on a REAL HOST (= bongos dev --server)
+  bongos serve stop      Stop + disable the service
+  bongos serve status    Service state, health, and whether the public origin answers
+
 What it does (idempotent — safe to re-run):
-  1. Make sure Postgres is running (starts it via Homebrew if it isn't)
-  2. Create this instance's database if it doesn't exist
-  3. Build/refresh its tables (migrations)
-  4. Start the server on the port in config/branding.json
-  5. Sign you in to this instance (unless --no-login)
+  1. Install dependencies if this checkout has none
+  2. Make sure Postgres is running (Homebrew on a Mac, systemd/service on a host)
+  3. Create this instance's database if it doesn't exist
+  4. Build/refresh its tables (migrations)
+  5. Start the server on the port in config/branding.json
+  6. Sign you in (local only — a host prints the command instead)
+
+What --server changes:
+  • supervision — a systemd unit (enabled at boot, restarts on failure) instead of
+    a pid file, falling back to the background process where systemd is absent
+  • bind address — 127.0.0.1 behind a TLS proxy (https origin), else 0.0.0.0
+  • it bootstraps the Postgres login role on a fresh cluster (peer auth)
+  • it checks the PUBLIC origin, not just loopback, and never opens a browser
+  Extra flags: --bind <addr>, --user <unix-user> (who the service runs as).
 
 Needs Postgres + Node >= 22 installed. macOS/Linux (uses bash for migrations;
-on Windows use WSL or the Docker path in docs/recipes/self-host.md).`);
+on Windows use WSL or the Docker path in docs/recipes/self-host.md).
+Server walkthrough: docs/recipes/server-bring-up.md`);
 }
 
 // psql/createdb take -h/-U only when we have them; libpq fills the rest.
@@ -86,21 +100,31 @@ function pgReady(params) {
   return run('pg_isready', [...pgArgs(params), '-q']).status === 0;
 }
 
-// Best-effort: start a Homebrew-managed Postgres, then poll until it accepts
-// connections. Returns true if ready, false if we couldn't bring it up.
+// Am I root? (Only meaningful on POSIX; Windows has no getuid.)
+function isRoot() { return typeof process.getuid === 'function' && process.getuid() === 0; }
+
+// Best-effort: start whatever service manager owns Postgres on this platform
+// (Homebrew on a Mac, systemd/service on a Linux host, pg_ctl with PGDATA
+// anywhere), then poll until it accepts connections. The candidate list + sudo
+// prefixing are decided by dev-lib.pgStartPlan; this just executes them in order.
 function ensurePostgres(params) {
   if (pgReady(params)) { ok('Postgres is running'); return true; }
   info('Postgres is not running — trying to start it…');
-  if (has('brew')) {
-    const formulae = run('brew', ['list', '--formula']).stdout
-      .split(/\s+/).filter((x) => /^postgresql(@\d+)?$/.test(x))
-      .sort().reverse();
-    const target = formulae[0] || 'postgresql@16';
-    run('brew', ['services', 'start', target], { stdio: 'ignore' });
-  } else if (has('pg_ctl') && process.env.PGDATA) {
-    run('pg_ctl', ['start', '-w', '-D', process.env.PGDATA], { stdio: 'ignore' });
+  for (const step of dev.pgStartPlan({ has, isRoot: isRoot() })) {
+    let args = step.args;
+    if (step.needsFormula) {
+      // Homebrew's formula name has to be discovered at runtime (postgresql@16,
+      // @17, …) — the only start candidate that isn't statically known.
+      const formulae = run('brew', ['list', '--formula']).stdout
+        .split(/\s+/).filter((x) => /^postgresql(@\d+)?$/.test(x))
+        .sort().reverse();
+      args = [...step.args, formulae[0] || 'postgresql@16'];
+    }
+    run(step.cmd, args, { stdio: 'ignore' });
+    if (pgReady(params)) { ok(`Postgres started (${step.label})`); return true; }
   }
-  // Poll for readiness (~15s). pg_isready is cheap; pause between probes.
+  // Poll for readiness (~15s) — a service manager returns before the cluster is
+  // actually accepting connections. pg_isready is cheap; pause between probes.
   for (let i = 0; i < 15; i++) {
     if (pgReady(params)) { ok('Postgres started'); return true; }
     sleepSync(1000);
@@ -114,12 +138,44 @@ function dbExists(params) {
   return r.status === 0 && r.stdout.trim() === '1';
 }
 
+// A fresh `apt-get install postgresql` cluster has exactly one role — `postgres`,
+// peer-auth only — so a deploy user's createdb fails with 'role "deploy" does not
+// exist'. That reads like a broken install and is really an unbootstrapped
+// cluster. Create the login role (and the DB it owns) as the postgres superuser.
+function bootstrapRole(params) {
+  const plan = dev.pgBootstrapPlan({ pgUser: params.pgUser, dbName: params.dbName, isRoot: isRoot(), has });
+  if (!plan.ok) { warn(plan.reason); return false; }
+  info(`bootstrapping the Postgres role "${params.pgUser}" (first run on this host)…`);
+  const byId = Object.fromEntries(plan.steps.map((s) => [s.id, s]));
+
+  const check = byId['check-role'];
+  const already = run(check.cmd, check.args).stdout.trim() === '1';
+  if (!already) {
+    const mk = byId['create-role'];
+    const r = run(mk.cmd, mk.args);
+    if (r.status !== 0) { fail(`could not create the Postgres role "${params.pgUser}": ${tail(r.stderr, 2)}`); return false; }
+    ok(`created Postgres role "${params.pgUser}"`);
+  }
+  const mkdb = byId['create-db'];
+  const r = run(mkdb.cmd, mkdb.args);
+  if (r.status === 0 || /already exists/i.test(r.stderr)) { ok(`database "${params.dbName}" ready`); return true; }
+  fail(`could not create database "${params.dbName}" as the postgres superuser: ${tail(r.stderr, 2)}`);
+  return false;
+}
+
+// Does this createdb failure mean "the cluster was never bootstrapped for me"
+// (fixable, see bootstrapRole) rather than a genuine error?
+function needsRoleBootstrap(stderr) {
+  return /role .* does not exist|Peer authentication failed|password authentication failed|no password supplied/i.test(String(stderr || ''));
+}
+
 function createDb(params) {
   if (dbExists(params)) { ok(`database "${params.dbName}" exists`); return true; }
   const r = run('createdb', [...pgArgs(params), params.dbName]);
   if (r.status === 0) { ok(`created database "${params.dbName}"`); return true; }
   // A race or prior partial run may have created it; treat "already exists" as fine.
   if (/already exists/i.test(r.stderr)) { ok(`database "${params.dbName}" exists`); return true; }
+  if (needsRoleBootstrap(r.stderr) && process.platform === 'linux') return bootstrapRole(params);
   fail(`could not create database "${params.dbName}": ${tail(r.stderr, 2) || r.error}`);
   return false;
 }
@@ -152,6 +208,15 @@ function printOAuthGuidance(params) {
   console.log(`       Authorization callback URL: ${cb}`);
   console.log('       Then tick "Enable Device Flow" and Save (a separate save).');
   console.log('    2. Copy the Client ID; generate a client secret.');
+  if (params.mode === 'server') {
+    // On a host the server runs as a service user with its own (often empty) home,
+    // so the env file the unit already reads is the reliable place for creds.
+    console.log(`    3. Put both in ${dev.envFilePath(params)} (0600, root-owned):`);
+    console.log(`         ${params.envPrefix}_GITHUB_CLIENT_ID=…`);
+    console.log(`         ${params.envPrefix}_GITHUB_CLIENT_SECRET=…`);
+    console.log(`    4. systemctl restart ${dev.serviceName(params)}`);
+    return;
+  }
   console.log(`    3. Save both into ${credsPath} as:`);
   console.log('       { "client_id": "…", "client_secret": "…" }');
   console.log('    4. Re-run `bongos dev`.');
@@ -182,9 +247,124 @@ function loginNow(params) {
   return r.status === 0;
 }
 
+// ---- server mode: systemd supervision (task 1002398) ---------------------------
+// On a laptop a detached pid-file process is the right amount of machinery. On a
+// real host it is not: it dies on reboot, it has no restart policy, and its logs
+// are a file in /tmp. So server mode installs a systemd unit and lets the host's
+// own supervisor own the process — the pid-file path stays as the fallback for a
+// host without systemd (a container, a BSD, a non-root operator).
+
+function sudoWorks() { return run('sudo', ['-n', 'true']).status === 0; }
+
+// Write a root-owned file, directly when we are root and via `sudo tee` when not.
+function writeRootFile(target, contents, useSudo, mode = null) {
+  const dir = path.posix.dirname(target);
+  if (!useSudo) {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(target, contents, mode ? { mode } : undefined);
+      return { ok: true };
+    } catch (e) { return { ok: false, err: e.message }; }
+  }
+  const mk = run('sudo', ['-n', 'mkdir', '-p', dir]);
+  if (mk.status !== 0) return { ok: false, err: tail(mk.stderr, 2) };
+  const w = run('sudo', ['-n', 'tee', target], { input: contents, stdio: ['pipe', 'ignore', 'pipe'] });
+  if (w.status !== 0) return { ok: false, err: tail(w.stderr, 2) };
+  if (mode) run('sudo', ['-n', 'chmod', mode.toString(8).padStart(4, '0'), target]);
+  return { ok: true };
+}
+
+function rootFileExists(target, useSudo) {
+  if (!useSudo) return fs.existsSync(target);
+  return run('sudo', ['-n', 'test', '-f', target]).status === 0;
+}
+
+// The secrets sidecar the unit reads. Created ONCE, 0600, never overwritten — a
+// re-run must not clobber credentials an operator pasted in. Values stay out of
+// Environment= lines on purpose: `systemctl show` leaks those to every user.
+function ensureEnvFile(params, useSudo) {
+  const target = dev.envFilePath(params);
+  if (rootFileExists(target, useSudo)) return { path: target, created: false };
+  const body = [
+    `# ${dev.serviceName(params)} — secrets for this instance. Root-owned, 0600.`,
+    '# Referenced by the systemd unit as EnvironmentFile=- (optional: absent is fine).',
+    '# Fill in what applies, then: systemctl restart ' + dev.serviceName(params),
+    '',
+    '# Postgres password, if the role is not trusted/peer-authenticated:',
+    '#PGPASSWORD=',
+    '',
+    '# GitHub OAuth app for sign-in (see `bongos serve` output):',
+    `#${params.envPrefix}_GITHUB_CLIENT_ID=`,
+    `#${params.envPrefix}_GITHUB_CLIENT_SECRET=`,
+    '',
+  ].join('\n');
+  const w = writeRootFile(target, body, useSudo, 0o600);
+  return { path: target, created: w.ok, err: w.err };
+}
+
+const sc = (useSudo, args) => (useSudo ? run('sudo', ['-n', 'systemctl', ...args]) : run('systemctl', args));
+
+// Install (or refresh) the unit and bring the service up. Idempotent: rewriting
+// an identical unit is a no-op, and `restart` covers both "not yet running" and
+// "running the previous unit".
+function installUnit(params, plan) {
+  const service = dev.serviceName(params);
+  const target = dev.unitPath(params);
+  const envFile = ensureEnvFile(params, plan.sudo);
+  if (envFile.created) ok(`wrote ${envFile.path} (0600 — put secrets here)`);
+  else if (envFile.err) warn(`could not create ${envFile.path}: ${envFile.err}`);
+
+  const unit = dev.renderSystemdUnit(params, {
+    nodePath: process.execPath,
+    user: arg('--user') || (isRoot() ? null : currentUser()),
+    envFile: envFile.path,
+  });
+  const w = writeRootFile(target, unit, plan.sudo);
+  if (!w.ok) { fail(`could not write ${target}: ${w.err}`); return { ok: false }; }
+  ok(`installed ${target}`);
+
+  if (sc(plan.sudo, ['daemon-reload']).status !== 0) { fail('systemctl daemon-reload failed'); return { ok: false }; }
+  // enable = survive reboot; restart = pick up this unit whether or not it ran.
+  sc(plan.sudo, ['enable', service]);
+  const r = sc(plan.sudo, ['restart', service]);
+  if (r.status !== 0) {
+    fail(`systemctl restart ${service} failed:`);
+    console.error(tail(r.stderr, 6));
+    console.error(`  journalctl -u ${service} -n 50 --no-pager`);
+    return { ok: false };
+  }
+  return { ok: true, service, unitPath: target, envFile: envFile.path };
+}
+
+function currentUser() {
+  try { return require('node:os').userInfo().username; } catch { return null; }
+}
+
+// `systemctl is-active` exits non-zero when inactive, so read stdout, not status.
+function unitActive(params, useSudo) {
+  return sc(useSudo, ['is-active', dev.serviceName(params)]).stdout.trim() === 'active';
+}
+
 // ---- subcommands ---------------------------------------------------------------
 
 function cmdStop(params) {
+  // Server mode: if a unit owns this instance, stopping the pid-file process
+  // would be a no-op (or worse, systemd would restart it) — stop the unit, and
+  // disable it so "stopped" survives a reboot. `bongos serve` re-enables it.
+  if (params.mode === 'server') {
+    const plan = dev.systemdPlan({ has, isRoot: isRoot() });
+    if (plan.available) {
+      const useSudo = plan.sudo && sudoWorks();
+      const service = dev.serviceName(params);
+      if (rootFileExists(dev.unitPath(params), useSudo)) {
+        const r = sc(useSudo, ['stop', service]);
+        sc(useSudo, ['disable', service]);
+        if (r.status === 0) { ok(`stopped + disabled ${service}`); return 0; }
+        fail(`could not stop ${service}: ${tail(r.stderr, 2)}`);
+        return 1;
+      }
+    }
+  }
   const res = dev.stop(params);
   if (res.wasRunning) ok(`stopped the local ${params.dbName} server (pid ${res.pid})`);
   else console.log(`  (no running ${params.dbName} server to stop)`);
@@ -192,10 +372,31 @@ function cmdStop(params) {
 }
 
 async function cmdStatus(params) {
-  const running = dev.isRunning(params);
+  const server = params.mode === 'server';
   console.log(`instance:  ${path.basename(params.instanceRoot)}  (${params.publicOrigin})`);
   console.log(`database:  ${params.dbName}  on ${params.pgHost}`);
-  if (!running) { console.log('server:    not running  — start it with `bongos dev`'); return 0; }
+  console.log(`bind:      ${params.host}:${params.port}`);
+
+  if (server) {
+    const plan = dev.systemdPlan({ has, isRoot: isRoot() });
+    const useSudo = plan.available && plan.sudo && sudoWorks();
+    if (plan.available && rootFileExists(dev.unitPath(params), useSudo)) {
+      const active = unitActive(params, useSudo);
+      console.log(`service:   ${dev.serviceName(params)} — ${active ? 'active' : 'inactive'}  (${dev.unitPath(params)})`);
+      const h = await dev.health(params);
+      console.log(`health:    ${h.up ? 'OK' : 'unreachable on the bind address'}`);
+      console.log(`sign-in:   ${h.authConfigured ? 'configured' : 'NOT configured (see `bongos serve`)'}`);
+      const pub = await dev.publicHealth(params);
+      console.log(`public:    ${pub.reachable ? `reachable (${params.publicOrigin})` : `NOT reachable — ${pub.error || `HTTP ${pub.status}`}`}`);
+      console.log(`logs:      journalctl -u ${dev.serviceName(params)} -f`);
+      return 0;
+    }
+    console.log('service:   no systemd unit installed — start it with `bongos serve`');
+    // fall through: a fallback pid-managed server may still be up.
+  }
+
+  const running = dev.isRunning(params);
+  if (!running) { console.log(`server:    not running  — start it with \`bongos ${server ? 'serve' : 'dev'}\``); return 0; }
   const h = await dev.health(params);
   console.log(`server:    running (pid ${dev.readPid(params)}), health ${h.up ? 'OK' : 'starting/unreachable'}`);
   console.log(`sign-in:   ${h.authConfigured ? 'configured' : 'NOT configured (see `bongos dev`)'}`);
@@ -203,6 +404,71 @@ async function cmdStatus(params) {
   return 0;
 }
 
+// The tail of a server-mode `up`: supervise, wait for health, report the outward
+// view. Never auto-signs-in (a host has no browser) — it prints the command.
+async function cmdServeStart(params) {
+  const plan = dev.systemdPlan({ has, isRoot: isRoot() });
+  let managed = null;
+
+  if (plan.available) {
+    const useSudo = plan.sudo && sudoWorks();
+    if (plan.sudo && !useSudo) {
+      warn('sudo needs a password here, so I cannot install a systemd unit non-interactively.');
+      console.log('  Either run `sudo bongos serve`, or grant passwordless sudo, and I will supervise with systemd.');
+    } else {
+      managed = installUnit(params, { ...plan, sudo: useSudo });
+      if (!managed.ok) return 1;
+      ok(`${managed.service} started (enabled at boot, restarts on failure)`);
+    }
+  } else {
+    warn(`no systemd here (${plan.reason}) — falling back to a managed background process.`);
+    console.log('  It will NOT survive a reboot. Add it to this host’s own supervisor for production.');
+  }
+
+  if (!managed) {
+    const started = dev.startDetached(params);
+    if (started.already) ok(`server already running (pid ${started.pid})`);
+    else ok(`server running (pid ${started.pid}), logs: ${started.log}`);
+  }
+
+  const h = await waitHealthy(params);
+  if (!h.up) {
+    fail(`the server did not become healthy on ${params.host}:${params.port}. Recent log:`);
+    if (managed) console.error(run('journalctl', ['-u', managed.service, '-n', '20', '--no-pager']).stdout || `  journalctl -u ${managed.service} -n 50 --no-pager`);
+    else { try { console.error(tail(fs.readFileSync(dev.logPath(params), 'utf8'), 12)); } catch { /* no log */ } }
+    return 1;
+  }
+  ok(`healthy on ${params.host}:${params.port}`);
+
+  // The loopback probe proves the app. This proves the PATH TO IT — DNS, the
+  // proxy, TLS — which is the part that actually differs on a real host.
+  const pub = await dev.publicHealth(params);
+  blank();
+  if (pub.reachable) {
+    ok(`${params.publicOrigin} is answering`);
+  } else {
+    warn(`${params.publicOrigin} is not answering yet (${pub.error || `HTTP ${pub.status}`}).`);
+    console.log('  The app is up on this host — what is missing is in front of it:');
+    if (params.host === '127.0.0.1') console.log(`    • a reverse proxy forwarding ${params.publicOrigin} → 127.0.0.1:${params.port} (TLS terminates there)`);
+    else console.log(`    • DNS for ${new URL(params.publicOrigin).hostname} pointing at this host, and port ${params.port} open in the firewall`);
+    console.log('    • see docs/recipes/server-bring-up.md');
+  }
+
+  blank();
+  console.log(`  → ${params.publicOrigin}`);
+  if (managed) {
+    console.log(`     status:  bongos serve status      logs: journalctl -u ${managed.service} -f`);
+    console.log(`     stop:    bongos serve stop        secrets: ${managed.envFile}`);
+  } else {
+    console.log(`     status:  bongos serve status      stop: bongos serve stop`);
+  }
+  blank();
+
+  if (!dev.authWillWork()) { printOAuthGuidance(params); return 0; }
+  console.log(`  Sign in from your own machine:  bongos login ${params.publicOrigin}`);
+  return 0;
+}
+
 async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
   info(`Standing up ${path.basename(params.instanceRoot)} on ${params.publicOrigin}`);
 
@@ -270,6 +536,9 @@ async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
     return r.status == null ? 1 : r.status;
   }
 
+  // Server mode: hand the process to the host's own supervisor.
+  if (params.mode === 'server') return cmdServeStart(params);
+
   // Default: managed background server.
   const started = dev.startDetached(params);
   if (started.already) ok(`server already running (pid ${started.pid})`);
@@ -302,7 +571,9 @@ async function main() {
   if (hasFlag('--help') || hasFlag('-h') || argv[0] === 'help') { usage(); return 0; }
 
   const params = dev.resolveRunParams({ instanceRoot: process.cwd(), argv });
-  const sub = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'up';
+  // Flag-order-independent: `bongos serve stop` reaches us as ['--server','stop'],
+  // and `--port 3006 status` puts a flag VALUE where a naive argv[0] scan looked.
+  const sub = dev.parseSub(argv);
 
   if (sub === 'stop') return cmdStop(params);
   if (sub === 'status') return cmdStatus(params);

package/src/module-api.js

@@ -629,8 +629,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.99 with no explicit bump. run 31751275973. (task 1002620)
 //   1.19.101 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.100 with no explicit bump. run 31752022322. (task 1002620)
+//   1.19.102 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.101 with no explicit bump. run 31753496152. (task 1002620)
+//   1.19.103 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.102 with no explicit bump. run 31754659965. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.101'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.103'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/bongos_cli.mjs

@@ -47,8 +47,10 @@ test('VERBS: selfHelp is only claimed by scripts that really print their own usa
   // Verified by reading each script (they all branch on --help/-h to a usage()
   // printer). If a verb is added here, verify its script first — a wrong
   // selfHelp:true recreates the blocking-interview bug for that verb.
+  // `serve` is dev.js with --server pinned on, so it inherits dev's own usage()
+  // printer — verified: `bongos serve --help` prints the card and exits 0.
   const selfHelp = Object.entries(cli.VERBS).filter(([, d]) => d.selfHelp).map(([v]) => v).sort();
-  assert.deepEqual(selfHelp, ['dev', 'module', 'status', 'task', 'upgrade']);
+  assert.deepEqual(selfHelp, ['dev', 'module', 'serve', 'status', 'task', 'upgrade']);
 });
 
 // ---- spawned: the dispatcher answers --help without touching the script ----

package/tests/dev_lib.mjs

@@ -20,12 +20,18 @@ async function ta(name, fn) {
   catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
 }
 
+// The lib builds paths with path.join, so on Windows they come back with `\`
+// while these fixtures are written POSIX-style. Compare on a normalized form —
+// otherwise every fixture silently "misses" and the lib reads its neutral
+// fallback, which looks like a logic failure and is really a separator mismatch.
+const norm = (p) => String(p).replace(/\\/g, '/');
+
 // A fake fs.readFileSync that maps by path suffix; unknown paths throw ENOENT.
 function fakeFs(map) {
   return {
     readFileSync(p) {
       for (const [suffix, body] of Object.entries(map)) {
-        if (String(p).endsWith(suffix)) return body;
+        if (norm(p).endsWith(suffix)) return body;
       }
       const e = new Error('ENOENT'); e.code = 'ENOENT'; throw e;
     },
@@ -184,7 +190,7 @@ t('startDetached: spawns the server entry with the server env, detached', () =>
   const r = lib.startDetached(params, deps);
   assert.equal(r.already, false);
   assert.equal(r.pid, 555);
-  assert.equal(spawnCall.args[0], '/core/src/platform-server.js');
+  assert.equal(norm(spawnCall.args[0]), '/core/src/platform-server.js');
   assert.equal(spawnCall.opts.cwd, '/x/test4');
   assert.equal(spawnCall.opts.detached, true);
   assert.equal(spawnCall.opts.env.PORT, '3006');
@@ -249,5 +255,189 @@ t('depsInstallPlan: no node_modules + no lockfile → npm install', () => {
   assert.deepEqual(plan.args, ['install']);
 });
 
+// ---------- server mode (task 1002398) ----------
+// A fake `has(bin)`: the named binaries are on PATH, nothing else is.
+const hasOnly = (...bins) => (b) => bins.includes(b);
+
+t('parseSub: flag order never changes the verb', () => {
+  assert.equal(lib.parseSub([]), 'up');
+  assert.equal(lib.parseSub(['--server']), 'up');
+  assert.equal(lib.parseSub(['--server', 'stop']), 'stop');       // what `bongos serve stop` sends
+  assert.equal(lib.parseSub(['status', '--server']), 'status');
+  assert.equal(lib.parseSub(['--port', '3006', 'status']), 'status'); // 3006 is a VALUE, not the verb
+  assert.equal(lib.parseSub(['--db', 'stop', 'status']), 'status');   // a db literally named "stop"
+  assert.equal(lib.parseSub(['--foreground']), 'up');             // boolean flag consumes nothing
+});
+
+t('deriveBindHost: local is always loopback; server derives from the origin', () => {
+  assert.equal(lib.deriveBindHost({ publicOrigin: 'https://example.com', mode: 'local' }), '127.0.0.1');
+  // https => something terminates TLS in front of us => stay off the public NIC.
+  assert.equal(lib.deriveBindHost({ publicOrigin: 'https://example.com', mode: 'server' }), '127.0.0.1');
+  // plain http on a public name => nothing is in front yet => serve it ourselves.
+  assert.equal(lib.deriveBindHost({ publicOrigin: 'http://example.com:3006', mode: 'server' }), '0.0.0.0');
+  assert.equal(lib.deriveBindHost({ publicOrigin: 'http://localhost:3006', mode: 'server' }), '127.0.0.1');
+  assert.equal(lib.deriveBindHost({ publicOrigin: 'garbage', mode: 'server' }), '127.0.0.1');
+  assert.equal(lib.deriveBindHost({ publicOrigin: 'http://example.com', mode: 'server', override: '10.0.0.4' }), '10.0.0.4');
+});
+
+t('probeHost: probe what we bound (0.0.0.0 still answers on loopback)', () => {
+  assert.equal(lib.probeHost({ host: '0.0.0.0' }), '127.0.0.1');
+  assert.equal(lib.probeHost({ host: '10.0.0.4' }), '10.0.0.4');
+  assert.equal(lib.probeHost({}), '127.0.0.1');
+});
+
+t('resolveRunParams: --server flips mode and the bind address', () => {
+  const f = fakeFs({
+    'config/branding.json': JSON.stringify({ domains: { publicOrigin: 'http://box.example.com:3006' } }),
+    'config/branding.neutral.json': NEUTRAL,
+    'config/modules.json': JSON.stringify({ modules: {} }),
+  });
+  const base = { instanceRoot: '/srv/app', coreRoot: '/core', f, env: {}, userInfo: () => ({ username: 'deploy' }) };
+  const local = lib.resolveRunParams({ ...base, argv: [] });
+  assert.equal(local.mode, 'local');
+  assert.equal(local.host, '127.0.0.1');
+  const server = lib.resolveRunParams({ ...base, argv: ['--server'] });
+  assert.equal(server.mode, 'server');
+  assert.equal(server.host, '0.0.0.0');
+  assert.equal(server.port, 3006);
+});
+
+t('resolveRunParams: an https origin keeps the server on loopback (proxy in front)', () => {
+  const f = fakeFs({
+    'config/branding.json': JSON.stringify({ domains: { publicOrigin: 'https://app.example.com' } }),
+    'config/branding.neutral.json': NEUTRAL,
+    'config/modules.json': JSON.stringify({ modules: {} }),
+  });
+  const p = lib.resolveRunParams({ instanceRoot: '/srv/app', coreRoot: '/core', f, env: {}, userInfo: () => ({ username: 'deploy' }), argv: ['--server'] });
+  assert.equal(p.host, '127.0.0.1');
+  assert.equal(p.port, 3000);                      // no explicit port => the proxy's upstream
+  assert.equal(p.publicOrigin, 'https://app.example.com');
+});
+
+// ---------- systemd unit ----------
+const UNIT_PARAMS = {
+  instanceRoot: '/srv/app', coreRoot: '/core', dbName: 'app', port: 3006, host: '127.0.0.1',
+  pgHost: 'localhost', pgUser: 'deploy', gdsOnly: true, envPrefix: 'CLOUDBONGOS',
+  publicOrigin: 'https://app.example.com', mode: 'server',
+};
+
+t('serviceName / unitPath / envFilePath are keyed per instance', () => {
+  assert.equal(lib.serviceName(UNIT_PARAMS), 'bongos-app');
+  assert.equal(lib.unitPath(UNIT_PARAMS), '/etc/systemd/system/bongos-app.service');
+  assert.equal(lib.envFilePath(UNIT_PARAMS), '/etc/bongos/bongos-app.env');
+  assert.notEqual(lib.serviceName({ dbName: 'other' }), lib.serviceName(UNIT_PARAMS));
+});
+
+t('unitEnvironment: only resolved keys — never the caller’s environment', () => {
+  const keys = lib.unitEnvironment(UNIT_PARAMS).map(([k]) => k);
+  assert.deepEqual(keys.sort(), ['CLOUDBONGOS_INSTANCE_ROOT', 'HOST', 'MEDUSA_GDS_ONLY', 'NODE_ENV', 'PGDATABASE', 'PGHOST', 'PGUSER', 'PORT']);
+  const env = Object.fromEntries(lib.unitEnvironment(UNIT_PARAMS));
+  assert.equal(env.PORT, '3006');
+  assert.equal(env.NODE_ENV, 'production');
+  assert.equal(env.CLOUDBONGOS_INSTANCE_ROOT, '/srv/app');
+});
+
+t('unitEnvironment: no secret ever lands in an Environment= line', () => {
+  const withSecret = { ...UNIT_PARAMS, pgPassword: 'hunter2' };
+  const rendered = lib.renderSystemdUnit(withSecret, { nodePath: '/usr/bin/node', user: 'deploy' });
+  assert.ok(!rendered.includes('hunter2'), 'PGPASSWORD must go to the 0600 EnvironmentFile, not the unit');
+  assert.match(rendered, /EnvironmentFile=-\/etc\/bongos\/bongos-app\.env/);
+});
+
+t('renderSystemdUnit: boot-survival + restart policy + the right ExecStart', () => {
+  // The unit is only ever GENERATED on the host that runs it (linux), so
+  // serverEntry's separators are native there; normalize for a Windows test box.
+  const u = norm(lib.renderSystemdUnit(UNIT_PARAMS, { nodePath: '/usr/bin/node', user: 'deploy' }));
+  assert.match(u, /ExecStart=\/usr\/bin\/node \/core\/src\/platform-server\.js/);
+  assert.match(u, /WorkingDirectory=\/srv\/app/);
+  assert.match(u, /^Restart=always$/m);
+  assert.match(u, /^WantedBy=multi-user\.target$/m);   // = survives reboot
+  assert.match(u, /^User=deploy$/m);
+  assert.match(u, /Environment="PORT=3006"/);
+  assert.match(u, /After=network-online\.target postgresql\.service/);
+});
+
+t('renderSystemdUnit: values are quoted, so a path with a space cannot split the line', () => {
+  const u = lib.renderSystemdUnit({ ...UNIT_PARAMS, instanceRoot: '/srv/my app' }, { nodePath: '/usr/bin/node' });
+  assert.match(u, /Environment="CLOUDBONGOS_INSTANCE_ROOT=\/srv\/my app"/);
+  assert.ok(!/^User=/m.test(u), 'no User= line when no user was given (runs as root)');
+});
+
+t('systemdPlan: available only on linux with systemctl; sudo unless root', () => {
+  assert.equal(lib.systemdPlan({ platform: 'darwin', has: hasOnly('systemctl') }).available, false);
+  assert.equal(lib.systemdPlan({ platform: 'linux', has: hasOnly() }).available, false);
+  assert.deepEqual(lib.systemdPlan({ platform: 'linux', has: hasOnly('systemctl'), isRoot: true }), { available: true, sudo: false });
+  assert.deepEqual(lib.systemdPlan({ platform: 'linux', has: hasOnly('systemctl', 'sudo') }), { available: true, sudo: true });
+  // systemctl present but no way to become root -> unavailable, with a reason.
+  const p = lib.systemdPlan({ platform: 'linux', has: hasOnly('systemctl') });
+  assert.equal(p.available, false);
+  assert.match(p.reason, /sudo/);
+});
+
+// ---------- Postgres bring-up ----------
+t('pgStartPlan: platform-correct candidates, sudo-prefixed when not root', () => {
+  const mac = lib.pgStartPlan({ platform: 'darwin', has: hasOnly('brew'), env: {} });
+  assert.equal(mac[0].cmd, 'brew');
+  assert.equal(mac[0].needsFormula, true);
+
+  const linux = lib.pgStartPlan({ platform: 'linux', has: hasOnly('systemctl', 'sudo'), env: {} });
+  assert.deepEqual(linux[0].args, ['-n', 'systemctl', 'start', 'postgresql']);
+  assert.equal(linux[0].cmd, 'sudo');
+
+  const asRoot = lib.pgStartPlan({ platform: 'linux', has: hasOnly('systemctl'), env: {}, isRoot: true });
+  assert.equal(asRoot[0].cmd, 'systemctl');
+
+  // No systemd: fall back to SysV, then to pg_ctl when PGDATA names a cluster.
+  const sysv = lib.pgStartPlan({ platform: 'linux', has: hasOnly('service'), env: {}, isRoot: true });
+  assert.equal(sysv[0].cmd, 'service');
+  const ctl = lib.pgStartPlan({ platform: 'linux', has: hasOnly('pg_ctl'), env: { PGDATA: '/var/lib/pg' }, isRoot: true });
+  assert.deepEqual(ctl[0].args, ['start', '-w', '-D', '/var/lib/pg']);
+  assert.deepEqual(lib.pgStartPlan({ platform: 'linux', has: hasOnly('pg_ctl'), env: {} }), []); // pg_ctl needs PGDATA
+});
+
+t('pgBootstrapPlan: creates the login role + its db as the postgres superuser', () => {
+  const plan = lib.pgBootstrapPlan({ pgUser: 'deploy', dbName: 'app', has: hasOnly('sudo') });
+  assert.equal(plan.ok, true);
+  const byId = Object.fromEntries(plan.steps.map((s) => [s.id, s]));
+  assert.deepEqual(byId['check-role'].args.slice(0, 4), ['-n', '-u', 'postgres', 'psql']);
+  assert.ok(byId['create-role'].args.join(' ').includes('CREATE ROLE "deploy" LOGIN CREATEDB'));
+  assert.deepEqual(byId['create-db'].args, ['-n', '-u', 'postgres', 'createdb', '-O', 'deploy', 'app']);
+});
+
+t('pgBootstrapPlan: root on a sudo-less image uses `su postgres -c`', () => {
+  const plan = lib.pgBootstrapPlan({ pgUser: 'deploy', dbName: 'app', isRoot: true, has: hasOnly() });
+  assert.equal(plan.ok, true);
+  assert.equal(plan.steps[0].cmd, 'su');
+  assert.equal(plan.steps[0].args[0], 'postgres');
+  assert.equal(plan.steps[0].args[1], '-c');
+});
+
+t('pgBootstrapPlan: refuses injection-shaped identifiers and a rootless host', () => {
+  assert.equal(lib.pgBootstrapPlan({ pgUser: 'a"; DROP DATABASE x; --', dbName: 'app', has: hasOnly('sudo') }).ok, false);
+  assert.equal(lib.pgBootstrapPlan({ pgUser: 'deploy', dbName: 'bad-name', has: hasOnly('sudo') }).ok, false);
+  assert.equal(lib.pgBootstrapPlan({ pgUser: '', dbName: 'app', has: hasOnly('sudo') }).ok, false);
+  const noRoot = lib.pgBootstrapPlan({ pgUser: 'deploy', dbName: 'app', isRoot: false, has: hasOnly() });
+  assert.equal(noRoot.ok, false);
+  assert.match(noRoot.reason, /root or sudo/);
+});
+
+// ---------- outward health ----------
+await ta('publicHealth: proves the path THROUGH the proxy, not just loopback', async () => {
+  const params = { publicOrigin: 'https://app.example.com' };
+  const up = await lib.publicHealth(params, { fetchImpl: async (u) => { assert.equal(u, 'https://app.example.com/healthz'); return { status: 200 }; } });
+  assert.equal(up.reachable, true);
+  const down = await lib.publicHealth(params, { fetchImpl: async () => { throw new Error('ENOTFOUND'); } });
+  assert.equal(down.reachable, false);
+  assert.match(down.error, /ENOTFOUND/);
+  const bad = await lib.publicHealth(params, { fetchImpl: async () => ({ status: 502 }) });
+  assert.equal(bad.reachable, false);   // proxy up, app not wired through it
+});
+
+await ta('health: probes the address we actually bound', async () => {
+  let seen = null;
+  await lib.health({ port: 3006, host: '0.0.0.0' }, { fetchImpl: async (u) => { seen = u; return { status: 200, json: async () => ({}) }; } });
+  assert.match(seen, /^http:\/\/127\.0\.0\.1:3006\//);
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed > 0 ? 1 : 0);