@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/dev.js

@@ -1,645 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/dev.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/dev.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-//
-// scripts/gds/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', 'gds', '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 };
+require('../bongos/forwarder.js').forward(module, 'dev.js');