@bongos/core 1.19.1033 → 1.19.1035

package/scripts/gds/credential-presence.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+// scripts/gds/credential-presence.js — which credentials does this HOST hold? Names and
+// presence only, never a value (task 1002880, from idea 1000630).
+//
+// Run ON THE HOST, as the user that can read the instance's env files (usually via sudo):
+//   node scripts/gds/credential-presence.js                 # reads /etc/<configDir>/*.env
+//   node scripts/gds/credential-presence.js --etc /etc/example --json
+//
+// WHY. The owner was asked to create GitHub credentials at least three times, and each
+// time the credential already existed — nothing could answer "what does this instance
+// need, what is set, what is missing". docs/credentials.md is the written half (what each
+// credential is for, where it lives, who may hold it); this is the one-command half, run
+// where the values actually live. doctor.js cannot do it: it runs on a builder's laptop,
+// which never sees the host's env files, and that is by design.
+//
+// THE ONE RULE: A VALUE NEVER LEAVES THE FILE. The report says set / empty / missing and
+// the NAME of the variable that satisfied each row — never the value, never a prefix,
+// never a length. tests/credential_presence.mjs asserts no fragment of any value reaches
+// the output. If this is ever surfaced over HTTP it must be Archon-gated, and it still
+// returns names only.
+//
+// Deeper than presence: `node scripts/gds/publish-credential-check.js` (task 1002733)
+// probes whether the publish credential can actually read the Actions API. This file
+// does not call GitHub — presence is the question it answers, offline.
+//
+// Exit: 0 = every REQUIRED row is satisfied · 1 = a required row is missing ·
+// 2 = an env file this host should have could not be read (the answer is unknown).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveEnv, envPrefix, configDirName, configPath, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
+const { arg, hasFlag, cliExit } = require('./cli-lib');
+
+// ---- the inventory -------------------------------------------------------------------
+//
+// One row per credential this instance's HOST may hold. `names` are the env var(s) that
+// must ALL be non-empty for the row to count as set; `prefixed` names resolve through the
+// instance's own env prefix (and its legacy spellings) the way the server reads them.
+// Rows sharing a `group` are alternatives: the group is satisfied when any member is.
+// `file` is the env file the value lives in on a control-plane host:
+//   web.env    — the web tier (the cloudbongos.service EnvironmentFile)
+//   box.env    — the control-plane runners; deliberately unreadable by the web tier
+//                (InaccessiblePaths=, task 1004176 / ADR 0327 §5)
+//   spaces.env — the offsite-backup timer
+// `need`: required (the instance is broken without it) · recommended (a named feature
+// is off without it) · optional.
+//
+// Every name here is documented in docs/credentials.md; the test fails if either side
+// gains a name the other lacks. Non-host credentials (GitHub Actions secrets, a
+// builder's own machine) are in the doc only — no host sweep can see them.
+const CREDENTIALS = [
+  {
+    id: 'github-sign-in', group: 'sign-in', file: 'web.env', need: 'required',
+    names: ['GITHUB_CLIENT_ID', 'GITHUB_CLIENT_SECRET'], prefixed: true,
+    purpose: 'GitHub OAuth app that signs builders in (src/bongos/auth-config.js)',
+  },
+  {
+    id: 'hub-federation', group: 'sign-in', file: 'web.env', need: 'required',
+    names: ['HUB_ORIGIN', 'HUB_CLIENT_ID', 'HUB_CLIENT_SECRET', 'HUB_PUBLIC_KEY'], prefixed: true,
+    purpose: 'sign-in federated through the Cloud Bongos hub instead of an own GitHub app (ADR 0141 §4)',
+  },
+  {
+    id: 'publish-app', group: 'publish', file: 'web.env', need: 'required',
+    names: ['GITHUB_APP_ID', 'GITHUB_APP_PRIVATE_KEY'],
+    purpose: 'GitHub App the server publishes builder branches and PRs with (modules/lifecycle/github-push.js); preferred',
+  },
+  {
+    id: 'publish-pat', group: 'publish', file: 'web.env', need: 'required',
+    names: ['GITHUB_PUSH_TOKEN'],
+    purpose: 'fine-grained PAT fallback for the same publish path, kept for cutover',
+  },
+  {
+    id: 'repo-pin', file: 'web.env', need: 'required',
+    names: ['GITHUB_OWNER', 'GITHUB_REPO'], prefixed: true, notSecret: true,
+    purpose: "which GitHub repo this instance is — mandatory where the core runs from node_modules, which has no git remote to read (src/bongos/repo-info.js)",
+  },
+  {
+    id: 'secret-box-key', file: 'web.env', need: 'required',
+    names: ['BUILDER_SECRET_KEY'], keyFile: 'builder-secret.key',
+    purpose: "master key encrypting builders' stored AI keys and GitHub tokens (src/bongos/secret-box.js); the key file in the service user's config dir also counts",
+  },
+  {
+    id: 'database-password', file: 'web.env', need: 'optional',
+    names: ['PGPASSWORD'],
+    purpose: "the instance's own Postgres role (src/bongos/pool.js); absent means local peer auth",
+  },
+  {
+    id: 'database-url', file: 'web.env', need: 'optional',
+    names: ['DATABASE_URL'],
+    purpose: 'a full Postgres connection string, when the database is not local',
+  },
+  {
+    id: 'discord-bot', file: 'web.env', need: 'recommended',
+    names: ['DISCORD_BOT_TOKEN'],
+    purpose: 'the Discord bot (modules/discord); also readable from discord-bot.json in the config dir',
+  },
+  {
+    id: 'discord-oauth', file: 'web.env', need: 'optional',
+    names: ['DISCORD_CLIENT_ID', 'DISCORD_CLIENT_SECRET'],
+    purpose: 'linking a Discord account at sign-in (src/bongos/auth-discord.js)',
+  },
+  {
+    id: 'discord-ship-news', file: 'web.env', need: 'optional',
+    names: ['DISCORD_SHIP_NEWS_WEBHOOK'],
+    purpose: '#ship-news posts (scripts/discord/lib.js); discord-webhooks.json in the config dir also works',
+  },
+  {
+    id: 'prelaunch-password', file: 'web.env', need: 'optional',
+    names: ['PRELAUNCH_PASSWORD'], legacyNames: ['STEALTH_PASSWORD'],
+    purpose: 'the pre-launch site password (src/bongos/prelaunch-gate.js); STEALTH_PASSWORD is the deprecated alias',
+  },
+  {
+    id: 'metrics-token', file: 'web.env', need: 'optional',
+    names: ['METRICS_TOKEN'],
+    purpose: 'bearer token for a remote Prometheus scrape of /metrics (src/bongos/metrics.js)',
+  },
+  {
+    id: 'hub-signing-key', file: 'web.env', need: 'optional',
+    names: ['HUB_SIGNING_KEY'], prefixed: true,
+    purpose: 'the HUB only: signs the assertions federated instances verify (modules/platform-identity/hub-keys.js)',
+  },
+  {
+    id: 'digitalocean', file: 'box.env', need: 'recommended',
+    names: ['DO_API_TOKEN'],
+    purpose: 'creates and destroys project servers (scripts/gds/do-api.js, provisioning); control plane only',
+  },
+  {
+    id: 'cloudflare', file: 'box.env', need: 'recommended',
+    names: ['CLOUDFLARE_API_TOKEN'],
+    purpose: 'DNS records for project addresses (scripts/gds/provision-net.js); control plane only',
+  },
+  {
+    id: 'offsite-backup', file: 'spaces.env', need: 'optional',
+    names: ['SPACES_KEY', 'SPACES_SECRET', 'SPACES_BUCKET'],
+    // The same file also carries the region, the endpoint and the age RECIPIENT the dumps
+    // are encrypted to. None is a secret (a recipient is a public key), so none is swept.
+    purpose: 'the weekly offsite copy of the database dumps (scripts/gds/db-backup-offsite.sh)',
+  },
+];
+
+const ENV_FILES = ['web.env', 'box.env', 'spaces.env'];
+
+// ---- pure core ------------------------------------------------------------------------
+
+// parseEnvFile(text) → { NAME: value } for a systemd EnvironmentFile: KEY=VALUE lines,
+// `#` comments, blank lines, optional surrounding quotes. Values are held only long enough
+// to test for emptiness; nothing returned by the report functions below contains one.
+function parseEnvFile(text) {
+  const out = {};
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
+    let value = line.slice(eq + 1).trim();
+    if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value[value.length - 1] === value[0]) {
+      value = value.slice(1, -1);
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) out[key] = value;
+  }
+  return out;
+}
+
+// Every spelling a name answers to, in the order the server tries them.
+function spellingsOf(name, row, prefix) {
+  if (row.prefixed) return [...new Set([prefix, ...LEGACY_ENV_PREFIXES])].map((p) => `${p}_${name}`);
+  return [name, ...(row.legacyNames || [])];
+}
+
+// checkRow(row, env, { prefix, keyFileExists }) → { state, satisfiedBy, missing }
+// state: 'set' | 'empty' | 'missing'. satisfiedBy / missing are variable NAMES.
+function checkRow(row, env, { prefix = envPrefix(), keyFileExists = false } = {}) {
+  const satisfiedBy = [];
+  const missing = [];
+  let anyEmpty = false;
+  for (const name of row.names) {
+    const spellings = spellingsOf(name, row, prefix);
+    const value = row.prefixed ? resolveEnv(name, { env, prefix, warn: () => {} }) : spellings.map((s) => env[s]).find((v) => v);
+    if (value) {
+      satisfiedBy.push(spellings.find((s) => env[s] === value) || spellings[0]);
+    } else {
+      if (spellings.some((s) => s in env)) anyEmpty = true;
+      missing.push(spellings[0]);
+    }
+  }
+  if (missing.length && row.keyFile && keyFileExists) {
+    return { state: 'set', satisfiedBy: [`${row.keyFile} (key file)`], missing: [] };
+  }
+  const state = missing.length === 0 ? 'set' : anyEmpty ? 'empty' : 'missing';
+  return { state, satisfiedBy, missing };
+}
+
+// sweep({ files, prefix, keyFileExists }) → { rows, groups, unreadable, ok }
+// files: { 'web.env': { env } | { error } } — the parsed files, or why one could not be read.
+function sweep({ files, prefix = envPrefix(), keyFileExists = false, credentials = CREDENTIALS }) {
+  const unreadable = Object.entries(files).filter(([, f]) => f.error).map(([name, f]) => ({ file: name, error: f.error }));
+  const rows = credentials.map((row) => {
+    const f = files[row.file];
+    if (!f || f.error) return { ...pick(row), state: 'unknown', satisfiedBy: [], missing: [] };
+    return { ...pick(row), ...checkRow(row, f.env, { prefix, keyFileExists }) };
+  });
+  // A group is satisfied when any member is; its members are not individually required.
+  const groups = {};
+  for (const r of rows) {
+    if (!r.group) continue;
+    groups[r.group] = groups[r.group] || { satisfied: false, unknown: false, members: [] };
+    groups[r.group].members.push(r.id);
+    if (r.state === 'set') groups[r.group].satisfied = true;
+    if (r.state === 'unknown') groups[r.group].unknown = true;
+  }
+  const requiredMissing = rows.filter((r) => r.need === 'required' && r.state !== 'set' && r.state !== 'unknown'
+    && !(r.group && groups[r.group].satisfied));
+  const ok = requiredMissing.length === 0 && unreadable.length === 0;
+  return { rows, groups, unreadable, requiredMissing: requiredMissing.map((r) => r.id), ok };
+}
+
+function pick(row) {
+  return { id: row.id, file: row.file, need: row.need, group: row.group || null, purpose: row.purpose, notSecret: !!row.notSecret };
+}
+
+// format(result) → the human report. Built only from ids, names, states and the fixed
+// purpose text — never from a parsed value.
+function format(result, { etc } = {}) {
+  const mark = { set: '✓', empty: '!', missing: '✗', unknown: '?' };
+  const lines = [`Credential presence — names only, never values (${etc || 'env files'})`, ''];
+  for (const file of ENV_FILES) {
+    const rows = result.rows.filter((r) => r.file === file);
+    if (!rows.length) continue;
+    const bad = result.unreadable.find((u) => u.file === file);
+    lines.push(`  ${file}${bad ? `  — could not read: ${bad.error}` : ''}`);
+    for (const r of rows) {
+      const grp = r.group ? result.groups[r.group] : null;
+      const covered = grp && grp.satisfied && r.state !== 'set' ? ` (not needed: another ${r.group} option is set)` : '';
+      const detail = r.state === 'set' ? `via ${r.satisfiedBy.join(', ')}`
+        : r.state === 'unknown' ? 'file unreadable'
+        : `${r.state === 'empty' ? 'set but EMPTY' : 'not set'}: ${r.missing.join(', ')}`;
+      lines.push(`    ${mark[r.state]} ${r.id.padEnd(20)} ${r.need.padEnd(11)} ${detail}${covered}`);
+    }
+    lines.push('');
+  }
+  if (result.requiredMissing.length) lines.push(`REQUIRED and missing: ${result.requiredMissing.join(', ')} — see docs/credentials.md for what each is and where it comes from.`);
+  if (result.unreadable.length) lines.push('Some env files could not be read, so this answer is incomplete — rerun as a user that can read them (usually sudo).');
+  if (result.ok) lines.push('Every required credential is present.');
+  lines.push('Deeper check of the publish credential (can it read Actions?): node scripts/gds/publish-credential-check.js');
+  return lines.join('\n');
+}
+
+// readFiles(etc) → the `files` shape sweep() takes, read from <etc>/<name>.
+function readFiles(etc, { fsImpl = fs } = {}) {
+  const files = {};
+  for (const name of ENV_FILES) {
+    const p = path.join(etc, name);
+    try {
+      files[name] = { env: parseEnvFile(fsImpl.readFileSync(p, 'utf8')) };
+    } catch (e) {
+      // An absent spaces.env just means offsite backups were never set up; an absent
+      // web.env means this is not the host (or the wrong --etc).
+      files[name] = e.code === 'ENOENT' && name !== 'web.env' ? { env: {} } : { error: e.code || e.message };
+    }
+  }
+  return files;
+}
+
+module.exports = { CREDENTIALS, ENV_FILES, parseEnvFile, checkRow, sweep, format, readFiles };
+
+if (require.main === module) {
+  const etcArg = arg('--etc');
+  const etc = etcArg && etcArg !== true ? etcArg : path.join('/etc', configDirName());
+  const files = readFiles(etc);
+  const keyArg = arg('--secret-key-file');
+  const keyFile = keyArg && keyArg !== true ? keyArg : configPath('builder-secret.key');
+  let keyFileExists = false;
+  try { keyFileExists = fs.statSync(keyFile).isFile(); } catch (_) { /* absent */ }
+  const result = sweep({ files, keyFileExists });
+  if (hasFlag('--json')) console.log(JSON.stringify({ etc, ...result }, null, 2));
+  else console.log(format(result, { etc }));
+  cliExit(result.unreadable.length ? 2 : result.ok ? 0 : 1);
+}

package/scripts/gds/deploy-main-audit-gate.sh

@@ -42,9 +42,13 @@
 
 set -eu
 
+# The range rides main-audit.js's --range flag, never an env var (task 1001441): a
+# shell cannot compute the instance's branded env prefix (<PREFIX>_AUDIT_RANGE), and
+# argv needs none. AUDIT_RANGE below is this script's own variable, not exported.
+AUDIT_RANGE=""
 if [ -n "${OTB_DEPLOY_PREV_SHA:-}" ]; then
-  OTB_AUDIT_RANGE="${OTB_DEPLOY_PREV_SHA}..HEAD"; export OTB_AUDIT_RANGE
-  echo "main audit: range ${OTB_AUDIT_RANGE} (exact deploy delta)"
+  AUDIT_RANGE="${OTB_DEPLOY_PREV_SHA}..HEAD"
+  echo "main audit: range ${AUDIT_RANGE} (exact deploy delta)"
 else
   echo "main audit: OTB_DEPLOY_PREV_SHA not set — falling back to the wide window."
   echo "  (Recommended: capture OTB_DEPLOY_PREV_SHA=\$(git rev-parse HEAD) BEFORE the pull;"
@@ -64,7 +68,10 @@ if [ ! -f "$MAIN_AUDIT" ]; then
   exit 1
 fi
 
-if node "$MAIN_AUDIT" --verify-head --db ${STRICT}; then
+if [ -n "$AUDIT_RANGE" ]; then set -- --range "$AUDIT_RANGE"; else set --; fi
+# ${1+"$@"}, not "$@": an empty "$@" under set -u is an unbound-variable error in
+# older /bin/sh (bash 3.2, macOS).
+if node "$MAIN_AUDIT" --verify-head --db ${STRICT} ${1+"$@"}; then
   echo "OK main audit clean${STRICT:+ (strict)} — proceeding with deploy."
   exit 0
 fi
@@ -72,7 +79,7 @@ fi
 echo ""
 echo "X DEPLOY ABORTED (SEC #863): a below-Metic${STRICT:+ or unresolved} author modified a"
 echo "  permission-sensitive path in this deploy. Investigate and revert before deploying:"
-echo "      node $MAIN_AUDIT --range \"\${OTB_AUDIT_RANGE:-HEAD~200..HEAD}\" --revert"
+echo "      node $MAIN_AUDIT --range \"\${AUDIT_RANGE:-HEAD~200..HEAD}\" --revert"
 
 if [ -n "${OTB_DEPLOY_PREV_SHA:-}" ] && [ "${OTB_GATE_NO_RESTORE:-0}" != "1" ]; then
   if git rev-parse --verify --quiet "${OTB_DEPLOY_PREV_SHA}^{commit}" >/dev/null; then

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 —