@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/dev.js

@@ -0,0 +1,645 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/dev.js — `bongos dev`: stand up THIS instance locally, in one command.
+//
+// The gap it closes (ADR 0149): a project the creation flow scaffolds ships a repo
+// configured for http://localhost:<port> but no way to START it locally. `bongos
+// onboard` provisions a CLOUD server (domain + DO/Cloudflare); Docker serves a
+// vanilla brand on :3000. Running THIS repo's brand on its OWN port meant a manual
+// six-part Postgres+migrate+env+server assembly with three silent mismatches. This
+// command does the whole thing, idempotently, and hands off to sign-in.
+//
+//   bongos dev            up: Postgres -> createdb -> migrate -> server -> login
+//   bongos dev stop       stop the background server this launched
+//   bongos dev status     is it up? what URL? is sign-in configured?
+//
+// Flags: --foreground (run attached; Ctrl-C stops), --no-login (don't auto sign in),
+//        --skip-migrate, --port <n>, --db <name>.
+//
+// Design notes:
+//  * The server runs DETACHED but MANAGED (pid/log keyed per instance) — the fix for
+//    the orphaned-background-server confusion (a stale server on :3005 answering a
+//    new project's login). `bongos dev status`/`stop` make it visible + killable, and
+//    a re-run is a no-op if it's already up. --foreground is there for those who want
+//    Ctrl-C lifecycle.
+//  * PORT is forced to branding's port (the server ignores branding — platform-server.js:44).
+//  * PGDATABASE is set for BOTH migrate.sh and the server (fixes the pool.js/migrate.sh
+//    default split); PGHOST defaults to TCP localhost (not the Linux peer socket).
+//  * Windows (task 1002707) runs the same steps: npm via its own entry point, the
+//    migrations in Git Bash, the Postgres installer's bin folder and `postgres` role.
+//    Every Windows decision is a pure function in dev-lib.js's WINDOWS section.
+
+const cp = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const dev = require('./dev-lib');
+const { arg, hasFlag, loadSessionSync } = require('./cli-lib');
+
+// ---- small terminal helpers (ascii-first; a builder's private surface) ---------
+const ok = (m) => console.log(`  ✓ ${m}`);
+const info = (m) => console.log(`▸ ${m}`);
+const warn = (m) => console.log(`  ⚠ ${m}`);
+const fail = (m) => console.error(`✖ ${m}`);
+const blank = () => console.log('');
+
+function run(cmd, args, opts = {}) {
+  const r = cp.spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '', error: r.error };
+}
+function has(bin) {
+  // `command -v` via the binary's own --version is unreliable across tools; probe PATH directly.
+  const which = process.platform === 'win32' ? 'where' : 'which';
+  return run(which, [bin]).status === 0;
+}
+function tail(s, n = 6) {
+  return String(s || '').trimEnd().split('\n').slice(-n).join('\n');
+}
+// Portable synchronous pause (no subprocess, no foreground-sleep dependency).
+function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function usage() {
+  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. Install dependencies if this checkout has none
+  2. Make sure Postgres is running (Homebrew on a Mac, systemd/service on a host,
+     the Postgres Windows service on Windows)
+  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. Runs on macOS, Linux and Windows.
+On Windows the migrations run in Git Bash (it comes with Git for Windows), and
+bongos dev connects to Postgres as "postgres" with the password you chose when
+installing it (set PGPASSWORD). Fallback anywhere: the Docker path in docs/recipes/self-host.md.
+Walkthroughs: docs/recipes/local-dev.md, docs/recipes/server-bring-up.md`);
+}
+
+// psql/createdb connection flags (dev-lib.pgClientArgs decides; -w on Windows so a
+// password prompt can never hang a run).
+function pgArgs(params, opts) { return dev.pgClientArgs(params, opts); }
+
+function pgReady(params) {
+  return run('pg_isready', [...pgArgs(params, { forReady: true }), '-q']).status === 0;
+}
+
+// Every path `where` prints for a binary (Windows lists all matches, in PATH order).
+function whereAll(bin) {
+  if (process.platform !== 'win32') return [];
+  return run('where', [bin]).stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+}
+
+// The Postgres installs the Windows installer left under Program Files ([] elsewhere).
+function pgInstalls() {
+  return process.platform === 'win32' ? dev.windowsPgInstalls() : [];
+}
+
+// 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, the installer's service on
+// Windows, 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…');
+  for (const step of dev.pgStartPlan({ has, isRoot: isRoot(), pgInstalls: pgInstalls() })) {
+    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) — 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);
+  }
+  return pgReady(params);
+}
+
+function dbExists(params) {
+  const r = run('psql', [...pgArgs(params), '-d', 'postgres', '-tAc',
+    `SELECT 1 FROM pg_database WHERE datname='${params.dbName}'`]);
+  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}`);
+  for (const line of dev.pgAuthHint(process.platform, r.stderr)) console.error(`  ${line}`);
+  return false;
+}
+
+// Run migrate.sh under `bashBin` (resolved by preflight: plain `bash` on Mac/Linux,
+// Git Bash's bash.exe on Windows).
+function migrate(params, bashBin = 'bash') {
+  const migrateSh = dev.bashScriptPath(path.join(params.coreRoot, 'scripts', 'migrate.sh'));
+  const env = dev.buildEnv(params, { role: 'migrate' });
+  const r = run(bashBin, [migrateSh], { cwd: params.instanceRoot, env });
+  if (r.status !== 0) {
+    fail('migrations failed:');
+    console.error(tail(r.stderr || r.stdout, 12));
+    return false;
+  }
+  const applied = (r.stdout.match(/^apply /gm) || []).length;
+  ok(applied ? `schema migrated (${applied} migration${applied === 1 ? '' : 's'} applied)` : 'schema up to date');
+  return true;
+}
+
+// Guidance for the ONE step that can require the user: a GitHub OAuth App. Only
+// printed when no creds are resolvable — most machines that already ran another
+// instance carry usable creds and skip this entirely.
+function printOAuthGuidance(params) {
+  const cb = `${params.publicOrigin}/api/gds/auth/web/callback`;
+  const credsPath = path.join(require('node:os').homedir(), '.config', params.configDir, 'gds-github.json');
+  blank();
+  warn('Sign-in is not configured yet (no GitHub OAuth credentials found).');
+  console.log('  The server will run, but `bongos login` needs a GitHub OAuth App first:');
+  console.log('    1. github.com → Settings → Developer settings → OAuth Apps → New OAuth App');
+  console.log(`       Homepage URL:              ${params.publicOrigin}`);
+  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`.');
+}
+
+function signedInToThisInstance(params) {
+  try {
+    const s = loadSessionSync();
+    if (!s || !s.token || !s.api_base) return false;
+    return new URL(s.api_base).host === new URL(params.publicOrigin).host;
+  } catch { return false; }
+}
+
+async function waitHealthy(params, ms = 20000) {
+  const start = Date.now();
+  while (Date.now() - start < ms) {
+    const h = await dev.health(params);
+    if (h.up) return h;
+    await sleep(1000);
+  }
+  return dev.health(params);
+}
+
+function loginNow(params) {
+  const loginJs = path.join(params.coreRoot, 'scripts', 'bongos', 'login.js');
+  info(`Signing in to ${params.publicOrigin}${params.firstAdmin ? ` (sign in as ${params.firstAdmin})` : ''}…`);
+  const r = cp.spawnSync(process.execPath, [loginJs, params.publicOrigin], { stdio: 'inherit' });
+  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)`);
+  return 0;
+}
+
+async function cmdStatus(params) {
+  const server = params.mode === 'server';
+  console.log(`instance:  ${path.basename(params.instanceRoot)}  (${params.publicOrigin})`);
+  console.log(`database:  ${params.dbName}  on ${params.pgHost}`);
+  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`)'}`);
+  console.log(`logs:      ${dev.logPath(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;
+}
+
+// Step 0: dependencies. A freshly-cloned instance has no node_modules, so
+// migrate.sh (pg) and the server (pg/express) would crash. Install FIRST, so
+// `bongos dev` is a true one-command bring-up even from a bare checkout (task
+// 1002405 — pairs with the root START-HERE that names `npm install` for the
+// truly-bare case where not even the `bongos` bin exists yet). How npm is started
+// is dev-lib.npmInvocation's call: on Windows a plain spawn of `npm` fails.
+function installDeps(params) {
+  const depsPlan = dev.depsInstallPlan({ instanceRoot: params.instanceRoot });
+  if (!depsPlan.needed) return true;
+  if (!has('npm')) {
+    fail('node_modules is missing and `npm` is not on PATH — install Node (it bundles npm), then re-run `bongos dev`.');
+    return false;
+  }
+  info(`installing dependencies (npm ${depsPlan.cmd}) — first run in this checkout, this can take a minute…`);
+  const npm = dev.npmInvocation(depsPlan.args);
+  const r = run(npm.cmd, npm.args, { cwd: params.instanceRoot, stdio: 'inherit', shell: npm.shell });
+  if (r.status !== 0) {
+    fail(`\`npm ${depsPlan.cmd}\` failed (exit ${r.status ?? '?'}). Fix the error above, then re-run \`bongos dev\`.`);
+    return false;
+  }
+  ok('dependencies installed');
+  return true;
+}
+
+// Windows: the Postgres installer leaves psql & co. OFF PATH. Put the newest
+// installed bin folder on PATH for this run (children inherit it), so an installed
+// Postgres is found without anyone editing PATH. Returns the install used, or null.
+function addWindowsPgToPath() {
+  if (process.platform !== 'win32') return null;
+  const inst = pgInstalls()[0];
+  if (!inst) return null;
+  process.env.PATH = `${inst.bin}${path.win32.delimiter}${process.env.PATH || ''}`;
+  return inst;
+}
+
+// Preflight: Postgres client tools + a bash for migrations. Returns
+// { ok: true, bashBin } or { ok: false } after printing what to do, per platform.
+function preflight({ skipMigrate = false } = {}) {
+  const PG_TOOLS = ['psql', 'createdb', 'pg_isready'];
+  let missing = PG_TOOLS.filter((b) => !has(b));
+  if (missing.length) {
+    const inst = addWindowsPgToPath();
+    if (inst) {
+      missing = PG_TOOLS.filter((b) => !has(b));
+      if (!missing.length) ok(`using the Postgres tools in ${inst.bin}`);
+    }
+  }
+  if (missing.length) {
+    fail(`Postgres client tools missing: ${missing.join(', ')}`);
+    console.error('  Install Postgres, then re-run `bongos dev`:');
+    for (const line of dev.pgInstallHint(process.platform)) console.error(`    ${line}`);
+    return { ok: false };
+  }
+  if (skipMigrate) return { ok: true, bashBin: null };
+  const bash = dev.resolveBash({ has, whereAll });
+  if (!bash.ok) {
+    fail('`bash` is required to run migrations (used by scripts/migrate.sh).');
+    for (const line of dev.bashMissingHint(process.platform, { wslOnly: bash.wslOnly })) console.error(`  ${line}`);
+    return { ok: false };
+  }
+  if (process.platform === 'win32') ok(`migrations will run in ${bash.bin}`);
+  return { ok: true, bashBin: bash.bin };
+}
+
+async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
+  info(`Standing up ${path.basename(params.instanceRoot)} on ${params.publicOrigin}`);
+
+  if (!installDeps(params)) return 1;
+  const pre = preflight({ skipMigrate });
+  if (!pre.ok) return 1;
+
+  if (!ensurePostgres(params)) {
+    fail('Postgres is installed but not reachable, and I could not start it.');
+    console.error(`  Start it yourself, then re-run \`bongos dev\`:`);
+    for (const line of dev.pgStartHint(process.platform, { pgInstalls: pgInstalls() })) console.error(`    ${line}`);
+    return 1;
+  }
+  if (!createDb(params)) return 1;
+  if (skipMigrate) warn('skipping migrations (--skip-migrate)');
+  else if (!migrate(params, pre.bashBin)) return 1;
+
+  const authReady = dev.authWillWork();
+  if (authReady) ok('sign-in configured');
+
+  // Foreground mode: run the server attached; Ctrl-C stops it. Print the login hint
+  // up front (the server owns the terminal once it starts).
+  if (foreground) {
+    blank();
+    info(`Starting ${params.dbName} on ${params.publicOrigin}  (Ctrl-C to stop)`);
+    if (authReady && !signedInToThisInstance(params)) {
+      console.log('  Once it says "listening", open a SECOND terminal and run:');
+      console.log(`     bongos login ${params.publicOrigin}${params.firstAdmin ? `   (sign in as ${params.firstAdmin})` : ''}`);
+    } else if (!authReady) printOAuthGuidance(params);
+    blank();
+    const env = dev.buildEnv(params, { role: 'server' });
+    const r = cp.spawnSync(process.execPath, [dev.serverEntry(params)], { cwd: params.instanceRoot, env, stdio: 'inherit' });
+    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})`);
+  const h = await waitHealthy(params);
+  if (!h.up) {
+    fail('the server did not become healthy in time. Recent log:');
+    try { console.error(tail(fs.readFileSync(started.log, 'utf8'), 12)); } catch { /* no log */ }
+    dev.stop(params); // don't leave a broken detached server behind
+    return 1;
+  }
+  if (!started.already) ok(`server running on ${params.publicOrigin} (pid ${started.pid})`);
+  blank();
+  console.log(`  → ${params.publicOrigin}`);
+  console.log(`     status:  bongos dev status      logs: ${started.log}`);
+  console.log(`     stop:    bongos dev stop`);
+  blank();
+
+  if (!authReady) { printOAuthGuidance(params); return 0; }
+  if (noLogin) { console.log('  Sign in when ready:  bongos login ' + params.publicOrigin); return 0; }
+  if (signedInToThisInstance(params)) { ok('already signed in to this instance'); return 0; }
+  const signedIn = loginNow(params);
+  blank();
+  if (signedIn) ok('all set — you’re signed in. Try:  bongos start');
+  else console.log('  Sign-in didn’t finish — re-run:  bongos login ' + params.publicOrigin);
+  return 0;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (hasFlag('--help') || hasFlag('-h') || argv[0] === 'help') { usage(); return 0; }
+
+  const params = dev.resolveRunParams({ instanceRoot: process.cwd(), argv });
+  // 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);
+  if (sub !== 'up') { fail(`unknown subcommand "${sub}"`); usage(); return 2; }
+
+  return cmdUp(params, {
+    foreground: hasFlag('--foreground'),
+    noLogin: hasFlag('--no-login'),
+    skipMigrate: hasFlag('--skip-migrate'),
+  });
+}
+
+if (require.main === module) {
+  main().then((code) => process.exit(code || 0)).catch((e) => { fail(e && e.message ? e.message : String(e)); process.exit(1); });
+}
+
+// installDeps / preflight / migrate / createDb are exported for tests/dev_windows.mjs,
+// which drives the win32 branches with process.platform and spawnSync stubbed.
+module.exports = { usage, pgArgs, installDeps, preflight, migrate, createDb };