@bongos/core 1.19.1032 → 1.19.1034

package/scripts/gds/dev-lib.js

@@ -35,6 +35,9 @@ 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; }
@@ -102,9 +105,10 @@ function deriveDbName({ brandingDbName, instanceRoot, override } = {}) {
 }
 
 // Resolve every parameter a local run needs, from branding + modules + env + argv.
-// Pure: all IO comes through injected deps (f/env/userInfo/argv). 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.
+// 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,
@@ -113,6 +117,7 @@ function resolveRunParams({
   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) || {};
@@ -128,6 +133,10 @@ function resolveRunParams({
   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(/\/+$/, '');
@@ -307,6 +316,195 @@ function depsInstallPlan({ instanceRoot, f = fs } = {}) {
     : { 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
@@ -436,13 +634,19 @@ function withSudo(step, { isRoot = false, sudo = true } = {}) {
 // 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.
-function pgStartPlan({ platform = process.platform, has = () => false, env = process.env, isRoot = false } = {}) {
+// 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;
 }
@@ -502,9 +706,12 @@ async function publicHealth(params, deps = {}) {
 }
 
 module.exports = {
-  HOST, DEFAULT_PORT, CORE_ROOT,
+  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 —

package/scripts/gds/dev.js

@@ -26,6 +26,9 @@
 //  * 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');
@@ -70,7 +73,8 @@ Usage:
 
 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)
+  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
@@ -84,33 +88,44 @@ What --server changes:
   • it checks the PUBLIC origin, not just loopback, and never opens a browser
   Extra flags: --bind <addr>, --user <unix-user> (who the service runs as).
 
-Needs Postgres + Node >= 22 installed. macOS/Linux (uses bash for migrations;
-on Windows use WSL or the Docker path in docs/recipes/self-host.md).
-Server walkthrough: docs/recipes/server-bring-up.md`);
+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 take -h/-U only when we have them; libpq fills the rest.
-function pgArgs(params) {
-  const a = ['-h', params.pgHost];
-  if (params.pgUser) a.push('-U', params.pgUser);
-  return a;
-}
+// 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), '-q']).status === 0;
+  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, 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.
+// (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() })) {
+  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,
@@ -177,13 +192,16 @@ function createDb(params) {
   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;
 }
 
-function migrate(params) {
-  const migrateSh = path.join(params.coreRoot, 'scripts', 'migrate.sh');
+// 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('bash', [migrateSh], { cwd: params.instanceRoot, env });
+  const r = run(bashBin, [migrateSh], { cwd: params.instanceRoot, env });
   if (r.status !== 0) {
     fail('migrations failed:');
     console.error(tail(r.stderr || r.stdout, 12));
@@ -469,54 +487,86 @@ async function cmdServeStart(params) {
   return 0;
 }
 
-async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
-  info(`Standing up ${path.basename(params.instanceRoot)} on ${params.publicOrigin}`);
-
-  // 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).
+// 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) {
-    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 1;
-    }
-    info(`installing dependencies (npm ${depsPlan.cmd}) — first run in this checkout, this can take a minute…`);
-    const r = run('npm', depsPlan.args, { cwd: params.instanceRoot, stdio: 'inherit' });
-    if (r.status !== 0) {
-      fail(`\`npm ${depsPlan.cmd}\` failed (exit ${r.status ?? '?'}). Fix the error above, then re-run \`bongos dev\`.`);
-      return 1;
-    }
-    ok('dependencies installed');
+  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: DB tooling + bash for migrations.
-  const missing = ['psql', 'createdb', 'pg_isready'].filter((b) => !has(b));
+// 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`:');
-    console.error(process.platform === 'darwin'
-      ? '    brew install postgresql@16 && brew services start postgresql@16'
-      : '    (Debian/Ubuntu) sudo apt-get install -y postgresql   (or your distro’s package)');
-    return 1;
+    for (const line of dev.pgInstallHint(process.platform)) console.error(`    ${line}`);
+    return { ok: false };
   }
-  if (!skipMigrate && !has('bash')) {
+  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).');
-    console.error('  On Windows, use WSL, or the Docker path in docs/recipes/self-host.md.');
-    return 1;
+    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\`:`);
-    console.error(process.platform === 'darwin' ? '    brew services start postgresql@16' : '    sudo service postgresql start');
+    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)) return 1;
+  else if (!migrate(params, pre.bashBin)) return 1;
 
   const authReady = dev.authWillWork();
   if (authReady) ok('sign-in configured');
@@ -590,4 +640,6 @@ if (require.main === module) {
   main().then((code) => process.exit(code || 0)).catch((e) => { fail(e && e.message ? e.message : String(e)); process.exit(1); });
 }
 
-module.exports = { usage, pgArgs };
+// 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 };

package/scripts/gds/doctor.js

@@ -30,6 +30,7 @@ const { execSync, spawnSync } = require('node:child_process');
 const { cliClient, SESSION_PATH, loadSession } = require('./cli-lib');
 const { classifyMergeDriverState, MERGE_DRIVER_NAME } = require('./install-git-hooks.js');
 const { preflightChecks } = require('./preflight');
+const { resolveEnv } = require('../../src/instance-config');
 
 // ANSI helpers (only if stdout is a TTY; otherwise emit plain text)
 const TTY = process.stdout.isTTY;
@@ -126,7 +127,7 @@ async function checkSession() {
 // this bit a real builder twice and was only diagnosed after a long manual dig.
 // This check makes it the FIRST thing doctor reports, with the one-line fix.
 //
-// Resolution mirrors the grader EXACTLY (OTB_CLAUDE_BIN / CLAUDE_BIN / 'claude',
+// Resolution mirrors the grader EXACTLY (<PREFIX>_CLAUDE_BIN / CLAUDE_BIN / 'claude',
 // shell:true on win32 so a `claude.cmd` shim resolves) so a green row here means
 // the grader's spawn will work too. Mac/Linux: shell:false, identical to today.
 function checkToolchain() {
@@ -152,7 +153,7 @@ function checkToolchain() {
   // can pass --version yet misbehave under the grader's stdio redirection
   // (SUBAGENT_NONZERO_EXIT). Learning #42.
   const claudeOk = results.some((r) => r.title === 'claude CLI' && r.level === 'ok');
-  if (claudeOk && process.platform === 'win32' && !process.env.OTB_CLAUDE_BIN && !process.env.CLAUDE_BIN) {
+  if (claudeOk && process.platform === 'win32' && !resolveEnv('CLAUDE_BIN') && !process.env.CLAUDE_BIN) {
     try {
       const where = spawnSync('where', ['claude'], { encoding: 'utf8', shell: true, timeout: 8000 });
       if (where.status === 0 && /WindowsApps/i.test(where.stdout || '')) {