@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/dev-lib.js

@@ -1,722 +1,6 @@
+// scripts/gds/dev-lib.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/dev-lib.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-lib.js — pure + injectable core of `bongos dev`, the one-command
-// LOCAL launcher for a standalone instance repo (ADR 0149).
-//
-// WHY. A project scaffolded by the creation flow ships a repo whose
-// config/branding.json points at http://localhost:<port> — it is CONFIGURED to run
-// on the owner's own machine — but the platform shipped no command that actually
-// STARTS it. Standing it up by hand is a six-part assembly (install+start Postgres,
-// createdb, migrate, set PORT/PGDATABASE/PGHOST/OAuth env, launch the server) with
-// three silent mismatches: the server reads PORT from env and NOT from branding
-// (platform-server.js:44); the server DB name collapses to the OS user while
-// migrate.sh defaults to `example` (pool.js:47 vs migrate.sh:52) unless
-// PGDATABASE is set for BOTH; and node-pg defaults to the Linux peer socket
-// /var/run/postgresql (pool.js:46), which does not exist under Homebrew Postgres on
-// a Mac. `bongos dev` collapses all of that into one idempotent command.
-//
-// Everything here is a PURE transform or an INJECTABLE helper (deps.fs / deps.spawn
-// / deps.kill / deps.fetchImpl / deps.env / deps.userInfo / deps.*Path), so
-// tests/dev_lib.mjs exercises every decision with NO real spawn, DB, or network.
-// The side-effecting orchestration (start Postgres, createdb, run migrate, hand off
-// to login) lives in dev.js.
-
-const { spawn } = require('node:child_process');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const ic = require('../../src/instance-config');
-
-// The server binds loopback (platform-server.js HOST default). We probe the IP
-// literal, never "localhost", to dodge any IPv6/hosts-file quirk while it binds
-// 127.0.0.1 — the same choice local-preview-lib.js made.
-const HOST = '127.0.0.1';
-const DEFAULT_PORT = 3000;
-
-// scripts/gds/ -> the core package root (holds src/platform-server.js + scripts/migrate.sh).
-const CORE_ROOT = path.resolve(__dirname, '..', '..');
-
-// The one role the Windows Postgres installer creates (task 1002707).
-const WINDOWS_PG_USER = 'postgres';
-
-function readJsonSafe(p, f = fs) {
-  try { return JSON.parse(f.readFileSync(p, 'utf8')); }
-  catch { return null; }
-}
-
-// Read the instance-identity fields the launcher needs, INSTANCE pack first
-// (config/branding.json — host content, resolveInstanceRoot) then the CORE neutral
-// starter (config/branding.neutral.json — ships with the package). Decoupled from
-// the full branding() resolver on purpose (mirrors pool.js:instanceDbName): a
-// branding validation error must never stop a local dev boot.
-function loadBrandingFacts({ instanceRoot, coreRoot = CORE_ROOT, f = fs } = {}) {
-  const inst = readJsonSafe(path.join(instanceRoot, 'config', 'branding.json'), f) || {};
-  const neutral = readJsonSafe(path.join(coreRoot, 'config', 'branding.neutral.json'), f) || {};
-  const pick = (k, subk) => {
-    const from = (o) => (subk ? (o[k] && o[k][subk]) : o[k]);
-    const v = from(inst);
-    return (v === undefined || v === null || v === '') ? from(neutral) : v;
-  };
-  return {
-    publicOrigin: pick('domains', 'publicOrigin') || `http://localhost:${DEFAULT_PORT}`,
-    firstAdmin: pick('firstAdmin') || '',
-    // db.database is null in the neutral starter and usually absent in a fresh
-    // instance pack — deriveDbName() falls back to the repo dir name.
-    brandingDbName: (inst.db && inst.db.database) || (neutral.db && neutral.db.database) || null,
-    envPrefix: pick('envPrefix') || ic.FALLBACK_ENV_PREFIX,
-    configDir: pick('configDir') || ic.FALLBACK_DIR,
-    gameEnabled: false, // overridden by resolveRunParams from config/modules.json
-  };
-}
-
-// Port the instance is configured for. The server reads process.env.PORT and
-// ignores branding, so `bongos dev` MUST set PORT to this or the server would come
-// up on 3000 while branding (and every printed link) says <port>.
-function parsePort(origin, fallback = DEFAULT_PORT) {
-  try {
-    const p = new URL(String(origin)).port;
-    const n = Number(p);
-    return Number.isInteger(n) && n > 0 && n < 65536 ? n : fallback;
-  } catch { return fallback; }
-}
-
-// Coerce an arbitrary string into a legal, safe Postgres database identifier:
-// lowercased, non [a-z0-9_] collapsed to '_', must begin with a letter or '_'
-// (a leading digit is illegal unquoted), max 63 bytes. Returns null if nothing
-// usable survives, so deriveDbName can fall through to its last-resort default.
-function sanitizeDbName(s) {
-  if (!s) return null;
-  let out = String(s).toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
-  if (!out) return null;
-  if (/^[0-9]/.test(out)) out = `db_${out}`;
-  return out.slice(0, 63);
-}
-
-// The DB name BOTH migrate.sh and the server pool will use. Precedence:
-//   explicit --db / override  ->  branding db.database  ->  the repo dir name  ->
-//   'cloudbongos_dev'. Whatever we pick is exported as PGDATABASE for both sides,
-//   which is the fix for the pool.js(OS-user) vs migrate.sh(example) split.
-function deriveDbName({ brandingDbName, instanceRoot, override } = {}) {
-  return (
-    sanitizeDbName(override) ||
-    sanitizeDbName(brandingDbName) ||
-    sanitizeDbName(instanceRoot && path.basename(instanceRoot)) ||
-    'cloudbongos_dev'
-  );
-}
-
-// Resolve every parameter a local run needs, from branding + modules + env + argv.
-// Pure: all IO comes through injected deps (f/env/userInfo/argv/platform). PGHOST
-// defaults to TCP 'localhost' (NOT the Linux peer socket the pool defaults to) so a
-// Homebrew Mac Postgres is reachable; an explicit PGHOST/PGUSER in the environment
-// still wins.
-function resolveRunParams({
-  instanceRoot,
-  coreRoot = CORE_ROOT,
-  f = fs,
-  env = process.env,
-  userInfo = os.userInfo,
-  argv = [],
-  mode = null,
-  platform = process.platform,
-} = {}) {
-  const facts = loadBrandingFacts({ instanceRoot, coreRoot, f });
-  const modules = readJsonSafe(path.join(instanceRoot, 'config', 'modules.json'), f) || {};
-  const gameEnabled = !!(modules.modules && modules.modules.game);
-
-  const portOverride = argFrom(argv, '--port');
-  const dbOverride = argFrom(argv, '--db');
-  // 'server' = a real host (systemd-supervised, no auto-login, outward health
-  // probe); 'local' = the ADR 0149 laptop path. Same six steps either way.
-  const runMode = mode || (argv.includes('--server') ? 'server' : 'local');
-
-  const port = portOverride ? parsePort(`http://x:${portOverride}`, parsePort(facts.publicOrigin)) : parsePort(facts.publicOrigin);
-  const dbName = deriveDbName({ brandingDbName: facts.brandingDbName, instanceRoot, override: dbOverride });
-
-  let pgUser = env.PGUSER;
-  // Windows (task 1002707): the Postgres installer creates exactly one role,
-  // `postgres`. Your Windows login name is never a role there, so defaulting to
-  // it would fail every connection with 'role "<you>" does not exist'.
-  if (!pgUser && platform === 'win32') pgUser = WINDOWS_PG_USER;
-  if (!pgUser) { try { pgUser = userInfo().username; } catch { pgUser = undefined; } }
-
-  const publicOrigin = facts.publicOrigin.replace(/\/+$/, '');
-
-  return {
-    instanceRoot,
-    coreRoot,
-    mode: runMode,
-    port,
-    host: deriveBindHost({ publicOrigin, mode: runMode, override: argFrom(argv, '--bind') || env.HOST }),
-    dbName,
-    pgHost: env.PGHOST || 'localhost',
-    pgUser,
-    pgPassword: env.PGPASSWORD || undefined,
-    publicOrigin,
-    firstAdmin: facts.firstAdmin,
-    envPrefix: facts.envPrefix,
-    configDir: facts.configDir,
-    // A local dev instance never wants OTB's instance-seed migrations (they FK-crash
-    // a non-owning DB — migrate.sh:56). Game-less instances skip them via
-    // MEDUSA_GDS_ONLY=1; when the game module IS enabled we still skip instance
-    // seeds (default-off) but do not force GDS-only, so game schema still applies.
-    gdsOnly: !gameEnabled,
-  };
-}
-
-// The env a child process (migrate or server) runs with. Starts from baseEnv (so
-// the child inherits any GitHub OAuth creds already in the shell) and overlays the
-// resolved run parameters. role='server' adds PORT/HOST; both roles set the PG*
-// trio + the instance-root pointer + the seed policy.
-function buildEnv(params, { baseEnv = process.env, role = 'server' } = {}) {
-  const env = { ...baseEnv };
-  env.PGHOST = params.pgHost;
-  if (params.pgUser) env.PGUSER = params.pgUser;
-  if (params.pgPassword) env.PGPASSWORD = params.pgPassword;
-  env.PGDATABASE = params.dbName;
-  if (params.gdsOnly) env.MEDUSA_GDS_ONLY = '1';
-  // Point migrate + the server at the instance explicitly, so resolution never
-  // depends on a stray cwd (migrate.sh:26 gotcha).
-  env[`${params.envPrefix}_INSTANCE_ROOT`] = params.instanceRoot;
-  if (role === 'server') {
-    env.PORT = String(params.port);
-    env.HOST = params.host;
-  }
-  return env;
-}
-
-// Does the machine have GitHub OAuth creds this instance's server will read?
-// Mirrors auth.js:loadGithubCreds EXACTLY (env <PREFIX>_GITHUB_CLIENT_ID/SECRET
-// with legacy fallbacks, else ~/.config/<configDir>/gds-github.json | pms-github.json)
-// so `bongos dev` predicts sign-in correctly instead of guessing.
-function authWillWork({ resolveEnv = ic.resolveEnv, readConfigFileSync = ic.readConfigFileSync } = {}) {
-  if (resolveEnv('GITHUB_CLIENT_ID') && resolveEnv('GITHUB_CLIENT_SECRET')) return true;
-  for (const name of ['gds-github.json', 'pms-github.json']) {
-    try {
-      const raw = readConfigFileSync(name);
-      if (raw) {
-        const c = JSON.parse(raw);
-        if (c && c.client_id && c.client_secret) return true;
-      }
-    } catch { /* try next */ }
-  }
-  return false;
-}
-
-// --- managed background server (the local analogue of local-preview-lib) --------
-// Keyed per (dbName, port) so two instances on one machine never collide on pid/log.
-
-function slug(params) { return `${params.dbName}-${params.port}`.replace(/[^a-z0-9_.-]+/gi, '_'); }
-function pidPath(params, deps = {}) {
-  return deps.pidPath || path.join((deps.tmpdir || os.tmpdir)(), `bongos-dev-${slug(params)}.pid`);
-}
-function logPath(params, deps = {}) {
-  return deps.logPath || path.join((deps.tmpdir || os.tmpdir)(), `bongos-dev-${slug(params)}.log`);
-}
-
-function readPid(params, deps = {}) {
-  const f = deps.fs || fs;
-  try {
-    const pid = Number(String(f.readFileSync(pidPath(params, deps), 'utf8')).trim());
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch { return null; }
-}
-
-// signal-0 existence probe: EPERM = alive but unsignalable, ESRCH = gone.
-function pidAlive(pid, deps = {}) {
-  if (!pid) return false;
-  const kill = deps.kill || process.kill;
-  try { kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
-}
-
-function isRunning(params, deps = {}) { return pidAlive(readPid(params, deps), deps); }
-
-function serverEntry(params) { return path.join(params.coreRoot, 'src', 'platform-server.js'); }
-
-// Start the platform server DETACHED (background), idempotent. Returns
-// { ok, already, pid, url, log }. The parent polls health, prints the managed-server
-// notice + the `bongos dev stop` command, and exits — the server keeps running.
-function startDetached(params, deps = {}) {
-  const f = deps.fs || fs;
-  const spawnImpl = deps.spawn || spawn;
-  if (isRunning(params, deps)) {
-    return { ok: true, already: true, pid: readPid(params, deps), url: params.publicOrigin, log: logPath(params, deps) };
-  }
-  const lp = logPath(params, deps);
-  let out = 'ignore';
-  try { out = f.openSync(lp, 'w'); } catch { /* fall back to ignore */ }
-  const child = spawnImpl(deps.nodePath || process.execPath, [serverEntry(params)], {
-    cwd: params.instanceRoot,
-    env: buildEnv(params, { baseEnv: deps.env || process.env, role: 'server' }),
-    detached: true,
-    stdio: ['ignore', out, out],
-    windowsHide: true,
-  });
-  child.unref();
-  if (child.pid) f.writeFileSync(pidPath(params, deps), String(child.pid) + '\n');
-  return { ok: true, already: false, pid: child.pid, url: params.publicOrigin, log: lp };
-}
-
-function stop(params, deps = {}) {
-  const f = deps.fs || fs;
-  const kill = deps.kill || process.kill;
-  const pid = readPid(params, deps);
-  if (!pid || !pidAlive(pid, deps)) {
-    try { f.rmSync(pidPath(params, deps), { force: true }); } catch { /* best-effort */ }
-    return { ok: true, wasRunning: false };
-  }
-  try { kill(pid); } catch (e) { return { ok: false, reason: e.message, pid }; }
-  try { f.rmSync(pidPath(params, deps), { force: true }); } catch { /* best-effort */ }
-  return { ok: true, wasRunning: true, pid };
-}
-
-// Probe the running server. Returns { up, authConfigured }. `up` = the plain
-// /healthz (needs no DB); authConfigured comes from /api/bongos/healthz.
-async function health(params, deps = {}) {
-  const fetchImpl = deps.fetchImpl || fetch;
-  const base = `http://${probeHost(params)}:${params.port}`;
-  const timeout = deps.healthTimeoutMs || 4000;
-  let up = false;
-  try {
-    const r = await fetchImpl(`${base}/healthz`, { signal: AbortSignal.timeout(timeout) });
-    up = r.status < 500;
-  } catch { return { up: false, authConfigured: false }; }
-  let authConfigured = false;
-  try {
-    const r = await fetchImpl(`${base}/api/bongos/healthz`, { signal: AbortSignal.timeout(timeout) });
-    const j = await r.json();
-    authConfigured = j && j.auth_configured === true;
-  } catch { /* leave false */ }
-  return { up, authConfigured };
-}
-
-// argv helper local to dev-lib (dev.js uses cli-lib's arg() for the real process
-// argv; this variant is pure so resolveRunParams stays unit-testable). Accepts
-// `--flag value` and `--flag=value`.
-function argFrom(args, name) {
-  const eq = args.find((a) => a.startsWith(`${name}=`));
-  if (eq != null) return eq.slice(name.length + 1);
-  const i = args.indexOf(name);
-  return i >= 0 ? args[i + 1] : null;
-}
-
-// depsInstallPlan (task 1002405) — decide whether `bongos dev` must install node
-// deps before it can do anything useful, and with which command. A freshly-cloned
-// instance has no node_modules, so migrate.sh (pg) and the server (pg/express)
-// would crash; install FIRST — this makes `bongos dev` a true one-command bring-up
-// even from a bare checkout (the case where a global/npx bongos, or `node
-// <core>/scripts/gds/dev.js`, is reachable but deps are not). Prefer `npm ci` when
-// a lockfile is present (reproducible + faster), else `npm install`. Pure:
-// injectable fs.
-function depsInstallPlan({ instanceRoot, f = fs } = {}) {
-  const present = f.existsSync(path.join(instanceRoot, 'node_modules'));
-  if (present) return { needed: false, cmd: null, args: [] };
-  const hasLock = f.existsSync(path.join(instanceRoot, 'package-lock.json'));
-  return hasLock
-    ? { needed: true, cmd: 'ci', args: ['ci'] }
-    : { needed: true, cmd: 'install', args: ['install'] };
-}
-
-// ========================= WINDOWS (task 1002707) =========================
-// `bongos dev` is the local-hall path every project without an address is told to
-// run (ADR 0323 made bring-your-own-host the free default), so a Windows owner has
-// to be able to one-command it too. Four things differ on Windows, and each is a
-// pure decision here so tests/dev_windows.mjs proves it on any OS:
-//   1. npm is a .cmd shim, which a plain spawn cannot start;
-//   2. the bash for migrate.sh is Git Bash, and the `bash.exe` on PATH may be WSL's
-//      launcher, which cannot reach a Windows Postgres or node;
-//   3. the Postgres installer neither puts psql on PATH nor creates a role named
-//      after you: its one role is `postgres`, behind the password chosen at install;
-//   4. Postgres runs as a Windows service, not under Homebrew or systemd.
-// Docker (docs/recipes/self-host.md) stays the fallback when none of this fits.
-// Paths are built with path.win32 so the answers are Windows-shaped on any host.
-
-// Windows env names are case-insensitive (`Path`, `ProgramFiles`), but a copied or
-// injected env is a plain object. Read it the way Windows would.
-function envGet(env, name) {
-  if (!env) return undefined;
-  if (env[name] !== undefined) return env[name];
-  const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
-  return key === undefined ? undefined : env[key];
-}
-
-// How to run `npm <args>`. On Windows `npm` is `npm.cmd`, and Node will not spawn a
-// .cmd without a shell: bare `npm` is ENOENT and `npm.cmd` is EINVAL since the
-// CVE-2024-27980 fix (docs/recipes/windows-builders.md). Prefer npm's own entry
-// point run by node (npm-cli.js ships beside node.exe), which needs no shell at
-// all; else fall back to the shim through cmd.exe, as ONE command string so Node
-// never concatenates an args array unescaped (DEP0190). The args are fixed verbs
-// ('ci' / 'install'), never user input. Mac/Linux keep the plain spawn.
-function npmInvocation(args = [], { platform = process.platform, execPath = process.execPath, exists = fs.existsSync } = {}) {
-  if (platform !== 'win32') return { cmd: 'npm', args: [...args], shell: false };
-  const npmCli = path.win32.join(path.win32.dirname(execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
-  if (exists(npmCli)) return { cmd: execPath, args: [npmCli, ...args], shell: false };
-  return { cmd: ['npm', ...args].join(' '), args: [], shell: true };
-}
-
-// Is this bash.exe WSL's launcher? C:\Windows\System32\bash.exe (and the
-// WindowsApps alias) start a Linux distro that cannot see Windows' node, psql or
-// PATH, so migrate.sh would "run" there and fail naming nothing useful.
-function isWslBashLauncher(p) {
-  const s = String(p).replace(/\\/g, '/').toLowerCase();
-  return /\/windows\/(system32|sysnative)\/bash\.exe$/.test(s) || s.includes('/windowsapps/');
-}
-
-// Which bash runs migrate.sh. Mac/Linux: `bash` on PATH, as before. Windows: Git
-// Bash, the shell Windows builders already use and the one migrate.sh is written to
-// handle. Looked for cheapest-to-trust first: the Git Bash this terminal runs in
-// (EXEPATH), Git's install folders, beside the `git` on PATH, then any non-WSL bash
-// on PATH. Returns { ok, bin, source }, or { ok: false, wslOnly } when nothing
-// usable exists (wslOnly = the only bash seen was WSL's, which deserves a sentence).
-function resolveBash({ platform = process.platform, env = process.env, has = () => false, whereAll = () => [], exists = fs.existsSync } = {}) {
-  if (platform !== 'win32') return has('bash') ? { ok: true, bin: 'bash', source: 'PATH' } : { ok: false, wslOnly: false };
-  const w = path.win32;
-  const candidates = [];
-  const exe = envGet(env, 'EXEPATH'); // set by Git Bash: its install root or its bin folder
-  if (exe) candidates.push([w.join(exe, 'bash.exe'), 'Git Bash'], [w.join(exe, 'bin', 'bash.exe'), 'Git Bash']);
-  for (const base of [envGet(env, 'ProgramFiles'), envGet(env, 'ProgramW6432'), envGet(env, 'ProgramFiles(x86)')]) {
-    if (base) candidates.push([w.join(base, 'Git', 'bin', 'bash.exe'), 'Git for Windows']);
-  }
-  const local = envGet(env, 'LOCALAPPDATA');
-  if (local) candidates.push([w.join(local, 'Programs', 'Git', 'bin', 'bash.exe'), 'Git for Windows']);
-  // git.exe sits in <root>\cmd, <root>\bin or <root>\mingw64\bin; bash in <root>\bin.
-  for (const git of whereAll('git')) {
-    let dir = w.dirname(git);
-    for (let i = 0; i < 3; i++) { candidates.push([w.join(dir, 'bin', 'bash.exe'), 'Git for Windows']); dir = w.dirname(dir); }
-  }
-  let wslSeen = false;
-  for (const b of whereAll('bash')) {
-    if (isWslBashLauncher(b)) wslSeen = true;
-    else candidates.push([b, 'PATH']);
-  }
-  for (const [bin, source] of candidates) {
-    if (exists(bin)) return { ok: true, bin, source };
-  }
-  return { ok: false, wslOnly: wslSeen };
-}
-
-// migrate.sh's path as Git Bash must receive it. The script finds the core with
-// `dirname "$0"`, and bash's dirname splits on `/` only: handed C:\x\scripts\migrate.sh
-// it answers ".", so the script would look for migrations under whatever folder it
-// was started in. Forward slashes (C:/x/scripts/migrate.sh) keep that working.
-function bashScriptPath(p, platform = process.platform) {
-  return platform === 'win32' ? String(p).replace(/\\/g, '/') : p;
-}
-
-// The Postgres Windows installer (postgresql.org/download/windows) puts the server
-// and its client tools in %ProgramFiles%\PostgreSQL\<version>\bin but does NOT add
-// that folder to PATH, so `psql` looks missing on a machine where Postgres is
-// installed and running. Find those folders, newest first, so dev.js can put the
-// tools on PATH for this run instead of asking an owner to edit PATH by hand. Each
-// entry also names the installer's Windows service (postgresql-x64-<version>).
-function windowsPgInstalls({ env = process.env, readdir = (d) => fs.readdirSync(d), exists = fs.existsSync } = {}) {
-  const w = path.win32;
-  const seen = new Set();
-  const out = [];
-  for (const base of [envGet(env, 'ProgramFiles'), envGet(env, 'ProgramW6432'), envGet(env, 'ProgramFiles(x86)')]) {
-    if (!base) continue;
-    const root = w.join(base, 'PostgreSQL');
-    let entries;
-    try { entries = readdir(root); } catch { continue; }
-    for (const name of entries) {
-      const version = Number.parseFloat(String(name));
-      if (!Number.isFinite(version) || version <= 0) continue;
-      const bin = w.join(root, String(name), 'bin');
-      if (seen.has(bin.toLowerCase()) || !exists(w.join(bin, 'psql.exe'))) continue;
-      seen.add(bin.toLowerCase());
-      out.push({ version, bin, service: `postgresql-x64-${name}` });
-    }
-  }
-  return out.sort((a, b) => b.version - a.version);
-}
-
-// psql/createdb connection flags: -h/-U only when we have them (libpq fills the
-// rest). On Windows add -w (never prompt): the installer's `postgres` role is
-// password-only, and a console prompt is a trap there. psql would take a typed
-// password that migrations, the server and every later run never see. Failing fast
-// lets dev.js say which password to set (pgAuthHint). pg_isready has no -w flag, so
-// its caller passes { forReady: true }.
-function pgClientArgs(params, { platform = process.platform, forReady = false } = {}) {
-  const a = ['-h', params.pgHost];
-  if (params.pgUser) a.push('-U', params.pgUser);
-  if (platform === 'win32' && !forReady) a.push('-w');
-  return a;
-}
-
-// The shared "give it your Postgres password" lines (Windows installs only).
-const WINDOWS_PGPASSWORD_LINES = [
-  'Give bongos dev that password in the terminal you run it from, then re-run it:',
-  '  PowerShell:  $env:PGPASSWORD = "<that password>"; npx bongos dev',
-  '  Git Bash:    PGPASSWORD="<that password>" npx bongos dev',
-  'To keep it for next time:  setx PGPASSWORD "<that password>"  (then open a new terminal).',
-];
-
-// What to tell someone whose Postgres client tools are missing, per platform, so a
-// Windows owner gets Windows steps instead of a Homebrew line.
-function pgInstallHint(platform = process.platform) {
-  if (platform === 'darwin') return ['brew install postgresql@16 && brew services start postgresql@16'];
-  if (platform === 'win32') {
-    return [
-      'Download the Windows installer from https://www.postgresql.org/download/windows/ and run it.',
-      'Keep the default port (5432), and note the password it asks you to choose for the "postgres" user.',
-      ...WINDOWS_PGPASSWORD_LINES,
-      'Rather not install Postgres? The Docker path in docs/recipes/self-host.md runs everything in containers.',
-    ];
-  }
-  return ['(Debian/Ubuntu) sudo apt-get install -y postgresql   (or your distro’s package)'];
-}
-
-// How to start Postgres by hand when dev.js could not, per platform.
-function pgStartHint(platform = process.platform, { pgInstalls = [] } = {}) {
-  if (platform === 'darwin') return ['brew services start postgresql@16'];
-  if (platform === 'win32') {
-    const svc = (pgInstalls[0] && pgInstalls[0].service) || 'postgresql-x64-16';
-    return [
-      `Press Win+R, type services.msc, find "${svc}" in the list, and click Start.`,
-      `Or, in a PowerShell opened with "Run as administrator":  Start-Service ${svc}`,
-    ];
-  }
-  return ['sudo service postgresql start'];
-}
-
-// Windows only: a createdb/psql refused on authentication almost always means
-// PGPASSWORD is unset or wrong for the installer's `postgres` role. [] otherwise,
-// so Mac/Linux output is unchanged.
-function pgAuthHint(platform = process.platform, stderr = '') {
-  if (platform !== 'win32') return [];
-  if (!/password authentication failed|no password supplied|role .* does not exist/i.test(String(stderr))) return [];
-  return [
-    'Postgres on Windows has one user, "postgres", protected by the password you chose when you installed it.',
-    ...WINDOWS_PGPASSWORD_LINES,
-    'Using a different Postgres user? Set PGUSER to it the same way.',
-  ];
-}
-
-// No usable bash for migrations. Windows only (Mac and Linux ship bash); names Git
-// for Windows first and Docker as the fallback, and explains a WSL-only bash.
-function bashMissingHint(platform = process.platform, { wslOnly = false } = {}) {
-  if (platform !== 'win32') return [];
-  const lines = [];
-  if (wslOnly) lines.push('The only bash found belongs to WSL (C:\\Windows\\System32\\bash.exe). It runs Linux, so it cannot reach a Windows Postgres or Node.');
-  lines.push(
-    'Install Git for Windows from https://git-scm.com/download/win (it includes Git Bash, which runs the migrations),',
-    'then open a new terminal and re-run `npx bongos dev`.',
-    'Or skip the local tools entirely with the Docker path: docs/recipes/self-host.md.',
-  );
-  return lines;
-}
-
-// ===================== SERVER MODE (task 1002398, ADR 0162) =====================
-// The SAME boot path — deps -> Postgres -> createdb -> migrate -> env -> server ->
-// health — retargeted at a real host. Four decisions differ from local, and every
-// one of them is a pure function here so tests/dev_lib.mjs can prove it without a
-// host: where to bind, how to start Postgres, how the DB role gets bootstrapped
-// under peer auth, and what supervises the process.
-
-// `bongos serve stop` arrives as argv ['--server','stop'] once bin/bongos.js
-// prefixes the mode flag, and `--port 3006 status` puts a VALUE where the old
-// `argv[0]` scan looked for the subcommand. Resolve the subcommand by skipping
-// flags and the values they consume, so flag order never changes the verb.
-const VALUE_FLAGS = new Set(['--port', '--db', '--bind', '--user', '--env-file']);
-
-function parseSub(argv = [], fallback = 'up') {
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--') break;
-    if (a.startsWith('-')) { if (VALUE_FLAGS.has(a)) i++; continue; }
-    return a;
-  }
-  return fallback;
-}
-
-// Where the server binds. Local is always loopback. On a real host the right
-// answer is derivable from the origin the instance is CONFIGURED for, so an
-// operator never has to reason about it:
-//   https://…            -> a TLS-terminating proxy fronts us  -> 127.0.0.1
-//   http://localhost:…   -> a local-shaped origin on a host     -> 127.0.0.1
-//   http://<public>:…    -> nothing in front of us yet          -> 0.0.0.0
-// An explicit --bind (or HOST in the environment) still wins over all of it.
-function deriveBindHost({ publicOrigin, mode = 'local', override } = {}) {
-  if (override) return String(override);
-  if (mode !== 'server') return HOST;
-  let u;
-  try { u = new URL(String(publicOrigin)); } catch { return HOST; }
-  if (u.protocol === 'https:') return HOST;
-  if (u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '::1') return HOST;
-  return '0.0.0.0';
-}
-
-// The address to PROBE for health. Binding 0.0.0.0 still answers on loopback;
-// binding one specific address does not, so probe whatever we actually bound.
-function probeHost(params = {}) {
-  const h = params.host || HOST;
-  return (h === '0.0.0.0' || h === '::') ? HOST : h;
-}
-
-function serviceName(params) { return `bongos-${sanitizeDbName(params.dbName) || 'instance'}`; }
-function unitPath(params, { systemdDir = '/etc/systemd/system' } = {}) {
-  return path.posix.join(systemdDir, `${serviceName(params)}.service`);
-}
-// Secrets (PGPASSWORD, GitHub OAuth creds) belong in a root-owned 0600 file the
-// unit references, NEVER in Environment= lines — `systemctl show` and the journal
-// expose those to any user on the box.
-function envFilePath(params, { etcBase = '/etc/bongos' } = {}) {
-  return path.posix.join(etcBase, `${serviceName(params)}.env`);
-}
-
-// The unit's Environment= set: ONLY the keys the boot path resolves. Deliberately
-// not buildEnv() — that spreads the caller's whole environment, which under
-// systemd would bake a builder's shell (tokens included) into a root-owned file.
-function unitEnvironment(params) {
-  const pairs = [
-    ['PORT', String(params.port)],
-    ['HOST', params.host],
-    ['PGHOST', params.pgHost],
-    ['PGDATABASE', params.dbName],
-    ['NODE_ENV', 'production'],
-  ];
-  if (params.pgUser) pairs.push(['PGUSER', params.pgUser]);
-  if (params.gdsOnly) pairs.push(['MEDUSA_GDS_ONLY', '1']);
-  pairs.push([`${params.envPrefix}_INSTANCE_ROOT`, params.instanceRoot]);
-  return pairs;
-}
-
-// systemd accepts Environment="K=v with spaces"; quote every value so a path with
-// a space (or a quote) can't split the assignment.
-function quoteUnitValue(v) { return `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`; }
-
-function renderSystemdUnit(params, { nodePath = process.execPath, user, group, envFile } = {}) {
-  const env = unitEnvironment(params).map(([k, v]) => `Environment=${quoteUnitValue(`${k}=${v}`)}`);
-  const lines = [
-    '[Unit]',
-    `Description=Cloud Bongos instance ${params.dbName} (bongos serve)`,
-    'Wants=network-online.target',
-    // postgresql.service may not exist (managed/remote DB) — After= on an absent
-    // unit is a no-op, so this is safe either way and orders us correctly when it
-    // IS local. No Requires=: a remote-DB host must still boot.
-    'After=network-online.target postgresql.service',
-    '',
-    '[Service]',
-    'Type=simple',
-    `WorkingDirectory=${params.instanceRoot}`,
-    `ExecStart=${nodePath} ${serverEntry(params)}`,
-    ...env,
-    `EnvironmentFile=-${envFile || envFilePath(params)}`,
-    // Survive a crash AND a reboot — the whole point of moving off the pid file.
-    'Restart=always',
-    'RestartSec=3',
-    'NoNewPrivileges=yes',
-    'StandardOutput=journal',
-    'StandardError=journal',
-  ];
-  if (user) lines.push(`User=${user}`);
-  if (group) lines.push(`Group=${group}`);
-  lines.push('', '[Install]', 'WantedBy=multi-user.target', '');
-  return lines.join('\n');
-}
-
-// Can this host supervise with systemd, and do we need sudo to install the unit?
-function systemdPlan({ platform = process.platform, has = () => false, isRoot = false } = {}) {
-  if (platform !== 'linux') return { available: false, reason: `systemd is linux-only (this host is ${platform})` };
-  if (!has('systemctl')) return { available: false, reason: 'systemctl is not on PATH' };
-  if (isRoot) return { available: true, sudo: false };
-  if (!has('sudo')) return { available: false, reason: 'installing a unit needs root, and sudo is not on PATH' };
-  return { available: true, sudo: true };
-}
-
-// Prefix a step with non-interactive sudo when we are not already root. `sudo -n`
-// never prompts: on a host without passwordless sudo it fails fast with a clear
-// error instead of hanging a deploy on a hidden password prompt.
-function withSudo(step, { isRoot = false, sudo = true } = {}) {
-  if (isRoot || !sudo) return step;
-  return { ...step, cmd: 'sudo', args: ['-n', step.cmd, ...step.args] };
-}
-
-// Ordered candidates for "start Postgres", best-first for the platform. dev.js
-// tries each until pg_isready passes. Homebrew keeps its own branch there (the
-// formula name has to be discovered at runtime); everything else is decided here.
-// On Windows, Postgres is a Windows service per installed version (pgInstalls, from
-// windowsPgInstalls). `net start` needs an Administrator terminal; from an ordinary
-// one it fails fast with "Access is denied", and dev.js moves on to pgStartHint.
-function pgStartPlan({ platform = process.platform, has = () => false, env = process.env, isRoot = false, pgInstalls = [] } = {}) {
-  const out = [];
-  if (platform === 'darwin' && has('brew')) out.push({ cmd: 'brew', args: ['services', 'start'], needsFormula: true, label: 'Homebrew' });
-  if (platform === 'linux') {
-    if (has('systemctl')) out.push(withSudo({ cmd: 'systemctl', args: ['start', 'postgresql'], label: 'systemd' }, { isRoot }));
-    else if (has('service')) out.push(withSudo({ cmd: 'service', args: ['postgresql', 'start'], label: 'service' }, { isRoot }));
-  }
-  if (platform === 'win32') {
-    for (const inst of pgInstalls) out.push({ cmd: 'net', args: ['start', inst.service], label: `Windows service ${inst.service}` });
-  }
-  if (has('pg_ctl') && env.PGDATA) out.push({ cmd: 'pg_ctl', args: ['start', '-w', '-D', env.PGDATA], label: 'pg_ctl' });
-  return out;
-}
-
-// Postgres identifiers are case-folded unless quoted, and a role name reaches the
-// server as SQL text — quote it properly and refuse anything that isn't a plain
-// identifier rather than interpolating a surprise into a CREATE ROLE.
-const SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
-function quoteIdent(s) { return `"${String(s).replace(/"/g, '""')}"`; }
-
-// The fresh-Debian wall: `apt-get install postgresql` creates exactly ONE role,
-// `postgres`, reachable only by peer auth as the postgres OS user. A deploy user
-// running `createdb` gets 'role "deploy" does not exist' — which reads like a
-// broken install and is really just an unbootstrapped cluster. These two steps,
-// run as the postgres superuser, are the whole fix.
-function pgBootstrapPlan({ pgUser, dbName, isRoot = false, has = () => false } = {}) {
-  if (!pgUser || !SAFE_IDENT.test(pgUser)) return { ok: false, reason: `refusing to bootstrap an unsafe role name: ${pgUser || '(none)'}` };
-  if (!dbName || !SAFE_IDENT.test(dbName)) return { ok: false, reason: `refusing to bootstrap an unsafe database name: ${dbName || '(none)'}` };
-  // Reach the postgres superuser the way this host allows: `sudo -u postgres` for
-  // a normal deploy user (and for root when sudo exists), else `su postgres -c`
-  // when we are already root on a minimal image with no sudo installed.
-  let asPostgres;
-  if (has('sudo')) asPostgres = (cmd, args, label) => ({ cmd: 'sudo', args: ['-n', '-u', 'postgres', cmd, ...args], label });
-  else if (isRoot) asPostgres = (cmd, args, label) => ({ cmd: 'su', args: ['postgres', '-c', shellJoin([cmd, ...args])], label });
-  else return { ok: false, reason: 'bootstrapping the role needs the postgres superuser (root or sudo)' };
-
-  return {
-    ok: true,
-    steps: [
-      { ...asPostgres('psql', ['-v', 'ON_ERROR_STOP=1', '-tAc',
-        `SELECT 1 FROM pg_roles WHERE rolname='${pgUser}'`], 'check role'), id: 'check-role' },
-      { ...asPostgres('psql', ['-v', 'ON_ERROR_STOP=1', '-c',
-        `CREATE ROLE ${quoteIdent(pgUser)} LOGIN CREATEDB`], 'create role'), id: 'create-role' },
-      { ...asPostgres('createdb', ['-O', pgUser, dbName], 'create database'), id: 'create-db' },
-    ],
-  };
-}
-
-// Quote an argv into a single `su -c` string. Only ever fed argv this module
-// built from validated identifiers, but quote anyway — `su -c` is a shell.
-function shellJoin(argv) {
-  return argv.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${String(a).replace(/'/g, `'\\''`)}'`)).join(' ');
-}
-
-// Health as seen from OUTSIDE — does the origin the instance advertises actually
-// answer? On a server that also exercises DNS, the proxy, and TLS, which the
-// loopback probe cannot see. Advisory: DNS may legitimately not be wired yet.
-async function publicHealth(params, deps = {}) {
-  const fetchImpl = deps.fetchImpl || fetch;
-  const timeout = deps.healthTimeoutMs || 6000;
-  try {
-    const r = await fetchImpl(`${params.publicOrigin}/healthz`, { signal: AbortSignal.timeout(timeout) });
-    return { reachable: r.status < 500, status: r.status };
-  } catch (e) {
-    return { reachable: false, error: e && e.message ? e.message : String(e) };
-  }
-}
-
-module.exports = {
-  HOST, DEFAULT_PORT, CORE_ROOT, WINDOWS_PG_USER,
-  readJsonSafe, loadBrandingFacts, parsePort, sanitizeDbName, deriveDbName,
-  resolveRunParams, buildEnv, authWillWork, depsInstallPlan,
-  // Windows (task 1002707). envGet stays private — a lookup helper, not a surface.
-  npmInvocation, isWslBashLauncher, resolveBash, bashScriptPath, windowsPgInstalls,
-  pgClientArgs, pgInstallHint, pgStartHint, pgAuthHint, bashMissingHint,
-  slug, pidPath, logPath, readPid, pidAlive, isRunning, serverEntry,
-  startDetached, stop, health, argFrom,
-  // server mode (task 1002398). withSudo/quoteIdent/shellJoin stay private —
-  // they are implementation details of the plans above, not a callable surface.
-  parseSub, deriveBindHost, probeHost, serviceName, unitPath, envFilePath,
-  unitEnvironment, renderSystemdUnit, systemdPlan, pgStartPlan,
-  pgBootstrapPlan, publicHealth,
-};
+require('../bongos/forwarder.js').forward(module, 'dev-lib.js');