@bongos/core 1.19.1032 → 1.19.1034

package/tests/db_backup_offsite.mjs

@@ -0,0 +1,81 @@
+// tests/db_backup_offsite.mjs — the weekly offsite copy sizes what it ships the same way
+// on every platform (task 1004170).
+//
+// THE BUG. db-backup-offsite.sh read both of its sizes — the local dump it picks and the
+// ciphertext it uploads — with GNU-only `stat -c '%s'`, which BSD/macOS stat refuses
+// outright. Every run on a Mac died before it encrypted anything, and CI's Linux never
+// saw it, because nothing ran the script at all. The empty-ciphertext guard rides on the
+// second of those sizes, so it is pinned here too.
+//
+// The script runs for real under macOS-shaped `stat` and `wc` (tests/helpers.mjs), with
+// stub `age` and `python3` first on PATH: nothing is encrypted, no bucket is touched and
+// no network is used.
+//
+// Run:  node --test tests/db_backup_offsite.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { macShapedTools } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'gds', 'db-backup-offsite.sh');
+const skip = process.platform === 'win32' ? 'needs a POSIX bash + coreutils (runs in CI)' : false;
+// The script's env-var prefix, built rather than written — the same reason as in
+// tests/db_backup_nightly.mjs: the legacy-literal ratchet counts the spelled-out form.
+const ENV = 'gds_'.toUpperCase();
+
+const DUMP_NAME = 'smallproj-2026-09-20T000000Z.sql.gz';
+const DUMP = '--\n-- PostgreSQL database dump complete\n--\n';
+const CIPHER = 'age-encryption.org/v1\n-> X25519 stub\n';
+
+// `cipher` is what the stub age writes to its -o file. The stub python3 answers the
+// boto3 probe and, for the upload program, records the object key it was handed.
+function runOffsite({ cipher = CIPHER } = {}) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'db-offsite-'));
+  const bin = path.join(tmp, 'bin');
+  const dir = path.join(tmp, 'backups');
+  const uploads = path.join(tmp, 'uploads.log');
+  fs.mkdirSync(bin);
+  fs.mkdirSync(dir);
+  macShapedTools(bin);
+  fs.writeFileSync(path.join(dir, DUMP_NAME), DUMP);
+  fs.writeFileSync(path.join(tmp, 'cipher'), cipher);
+  fs.writeFileSync(path.join(bin, 'age'),
+    `#!/bin/bash\nwhile [ $# -gt 0 ]; do [ "$1" = -o ] && out="$2"; shift; done\ncp "${path.join(tmp, 'cipher')}" "$out"\n`, { mode: 0o755 });
+  fs.writeFileSync(path.join(bin, 'python3'),
+    `#!/bin/bash\n[ "$1" = -c ] && exit 0\ncat > /dev/null\necho "$${ENV}OFFSITE_KEY" >> "${uploads}"\n`, { mode: 0o755 });
+  const r = spawnSync('bash', [SCRIPT], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PATH: `${bin}:${process.env.PATH}`,
+      [`${ENV}BACKUP_DB`]: 'smallproj',
+      [`${ENV}BACKUP_DIR`]: dir,
+      [`${ENV}SPACES_ENV`]: path.join(tmp, 'no-such-spaces.env'),
+      [`${ENV}OFFSITE_AGE_RECIPIENT`]: 'age1stubrecipient',
+      SPACES_KEY: 'k', SPACES_SECRET: 's', SPACES_BUCKET: 'b', SPACES_REGION: 'r', SPACES_ENDPOINT: 'https://example.invalid',
+    },
+  });
+  const sent = fs.existsSync(uploads) ? fs.readFileSync(uploads, 'utf8').split('\n').filter(Boolean) : [];
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, sent };
+}
+
+test('it sizes the dump and its ciphertext on macOS as on Linux, then ships it (task 1004170)', { skip }, () => {
+  const r = runOffsite();
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, new RegExp(`\\(${Buffer.byteLength(DUMP)} bytes → ${Buffer.byteLength(CIPHER)} encrypted\\)`),
+    'both sizes are the real byte counts, unpadded');
+  assert.deepEqual(r.sent, [`gds-offsite/${DUMP_NAME}.age`]);
+});
+
+test('an empty ciphertext is refused, never uploaded as a backup', { skip }, () => {
+  const r = runOffsite({ cipher: '' });
+  assert.equal(r.status, 2, r.stderr);
+  assert.match(r.stderr, /encryption produced an empty file/);
+  assert.deepEqual(r.sent, [], 'nothing reached the bucket');
+});

package/tests/deploy_audit_gate.mjs

@@ -89,13 +89,16 @@ test('the range handed to the auditor is the exact deploy delta, not a window',
   try {
     const gdsDir = path.join(repo.dir, 'node_modules', '@bongos', 'core', 'scripts', 'gds');
     fs.mkdirSync(gdsDir, { recursive: true });
+    // The range rides --range, not an env var (task 1001441): a shell cannot compute
+    // the instance's branded env prefix, and argv needs none.
     fs.writeFileSync(path.join(gdsDir, 'main-audit.js'),
-      'require("fs").writeFileSync("range.txt", process.env.OTB_AUDIT_RANGE || "UNSET");\n');
+      'const a = process.argv; const i = a.indexOf("--range");\n'
+      + 'require("fs").writeFileSync("range.txt", i >= 0 ? a[i + 1] : "UNSET");\n');
     const r = runGate(repo, { OTB_DEPLOY_PREV_SHA: repo.prev });
     assert.equal(r.code, 0, r.out);
     assert.equal(
       fs.readFileSync(path.join(repo.dir, 'range.txt'), 'utf8'), `${repo.prev}..HEAD`,
-      'the auditor must receive <previously-deployed>..HEAD',
+      'the auditor must receive --range <previously-deployed>..HEAD',
     );
   } finally { fs.rmSync(repo.dir, { recursive: true, force: true }); }
 });

package/tests/deploy_page_projects.mjs

@@ -37,7 +37,7 @@ const FLEET = [
   { id: '35', slug: 'unreadable-one', status: 'active', hosting_shape: 'cloud-host' },
 ];
 
-function boot({ controlPlane = preview('1', 'cloudbongos'), controlPlaneStatus = 200, fleet = FLEET, fleetStatus = 200, instanceOver = null, moveTries = 4, postStatus = 200, scope = null } = {}) {
+function boot({ controlPlane = preview('1', 'cloudbongos'), controlPlaneStatus = 200, fleet = FLEET, fleetStatus = 200, instanceOver = null, moveTries = 4, postStatus = 200, scope = null, href = null } = {}) {
   const els = new Map();
   const posts = [];
   const gets = [];
@@ -94,7 +94,7 @@ function boot({ controlPlane = preview('1', 'cloudbongos'), controlPlaneStatus =
     OTB: { escapeHtml: (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c])), toast(m) { toasts.push(String(m)); } },
     // `search` is what decides which project the page is about. A stub without it is the
     // shape the page has to survive, and the default here keeps that path exercised.
-    location: { assign() {}, search: scope ? `?project=${encodeURIComponent(scope)}` : '' },
+    location: { assign() {}, search: scope ? `?project=${encodeURIComponent(scope)}` : '', ...(href ? { href } : {}) },
   };
   // The page's poll interval, driven rather than slept through. Injecting the REAL
   // setTimeout made every case whose preview never converges sit out the page's full
@@ -583,3 +583,64 @@ test('a queue that is REFUSED leaves no in-flight state to wait on', async () =>
   assert.ok(b.toasts.some((t) => /currently running/i.test(t)), 'and the refusal is reported');
   assert.match(b.panel(), /id="dp-confirm-32"/, 'the button comes back so it can be retried');
 });
+
+// ---- landed, but GitHub was not updated (task 1004065) ----------------------------
+//
+// The hub pushes a hosted project's pin to its GitHub repo after the upgrade. When it
+// cannot, the move is still DONE (the site runs the new core) but the page must not
+// read "and the box confirmed it" as though everything was saved — the box and the
+// repo have split, and changes pushed to GitHub can stop reaching the live site.
+
+const landedWith = (warning) => () => ({
+  served_version: '1.19.871', recommended_version: '1.19.871', behind: false, open_intent: null,
+  last_move: { target_version: '1.19.871', state: 'done', at: new Date(Date.now() - 60 * 1000).toISOString(), error: null, warning },
+});
+
+test('a move that landed but did NOT reach GitHub says so, instead of a clean confirmation', async () => {
+  const b = boot({ scope: 'mercury', instanceOver: landedWith({ code: 'no_access', text: 'The hub had no permission to write to the project’s GitHub repository.' }) });
+  await b.settle();
+  const html = b.panel();
+  assert.match(html, /Now running core 1\.19\.871/, 'the upgrade itself is still stated — it worked');
+  assert.match(html, /GitHub was not updated/i, 'and the half that did not happen is the headline beside it');
+  assert.match(html, /no permission to write/, 'with the runner’s reason in plain words');
+  assert.match(html, /dp-settled--warn/, 'a warning mark — not the success mark, not the failure one');
+  assert.doesNotMatch(html, /dp-settled--ok/);
+  assert.doesNotMatch(html, /dp-settled--failed/);
+  assert.doesNotMatch(html, /did not land/i, 'it DID land');
+});
+
+test('when the fix is reconnecting GitHub, the page links straight to it and comes back here', async () => {
+  for (const code of ['no_access', 'refused']) {
+    const b = boot({ scope: 'mercury', instanceOver: landedWith({ code, text: 'x' }) });
+    await b.settle();
+    const html = b.panel();
+    assert.match(html, /href="\/api\/bongos\/auth\/web\/start\?repos=1&amp;return=%2Fdeploy%3Fproject%3Dmercury"/,
+      `${code}: the repo-access sign-in, returning to this project's deploy page — got ${html}`);
+    assert.match(html, /within the hour/i, `${code}: and it says the access is short-lived, rather than promising a fix`);
+  }
+});
+
+test('when reconnecting cannot help, no reconnect link is offered', async () => {
+  for (const code of ['behind', 'no_repo', 'failed', 'no_branch']) {
+    const b = boot({ scope: 'mercury', instanceOver: landedWith({ code, text: 'x' }) });
+    await b.settle();
+    assert.doesNotMatch(b.panel(), /auth\/web\/start/, `${code}: a sign-in does not fix this`);
+  }
+});
+
+test('a clean move still reads as the plain confirmation', async () => {
+  const b = boot({ scope: 'mercury', instanceOver: landedWith(null) });
+  await b.settle();
+  const html = b.panel();
+  assert.match(html, /dp-settled--ok/);
+  assert.doesNotMatch(html, /GitHub was not updated/i);
+});
+
+test('the reconnect link returns to the page\u2019s full https address when there is one', async () => {
+  // A relative return resolves against the sign-in callback's host, which is not the
+  // hall's. The absolute address is admitted by the same allowlist and lands back here.
+  const here = 'https://builders.example.com/deploy?project=mercury';
+  const b = boot({ scope: 'mercury', href: here, instanceOver: landedWith({ code: 'no_access', text: 'x' }) });
+  await b.settle();
+  assert.ok(b.panel().includes(`return=${encodeURIComponent(here)}`), b.panel());
+});

package/tests/dev_lib.mjs

@@ -86,7 +86,8 @@ t('resolveRunParams: port from branding, db from repo dir, TCP localhost, gdsOnl
     'config/branding.neutral.json': NEUTRAL,
     'config/modules.json': JSON.stringify({ modules: { game: false } }),
   });
-  const p = lib.resolveRunParams({ instanceRoot: '/Users/x/test4', coreRoot: '/core', f, env: {}, userInfo: () => ({ username: 'lars' }), argv: [] });
+  // platform pinned: on Windows the default role is `postgres` (tests/dev_windows.mjs).
+  const p = lib.resolveRunParams({ instanceRoot: '/Users/x/test4', coreRoot: '/core', f, env: {}, userInfo: () => ({ username: 'lars' }), argv: [], platform: 'darwin' });
   assert.equal(p.port, 3006);
   assert.equal(p.dbName, 'test4');
   assert.equal(p.pgHost, 'localhost');   // NOT the /var/run/postgresql linux socket

package/tests/dev_windows.mjs

@@ -0,0 +1,324 @@
+// tests/dev_windows.mjs — `bongos dev` on Windows (task 1002707), proven on any OS.
+//
+// Two layers:
+//   1. dev-lib's WINDOWS decisions, called with platform:'win32' and injected
+//      env / fs / where, so every Windows path is exercised on a Mac or Linux CI box.
+//   2. dev.js's wiring of those decisions (npm install, preflight, migrate, createdb),
+//      driven with process.platform STUBBED to 'win32' and child_process.spawnSync +
+//      fs.existsSync/readdirSync STUBBED. Nothing real is spawned, installed or read.
+//
+// Each case fails on the pre-fix code: a plain `npm` spawn with no shell, a WSL
+// bash.exe accepted for migrations, a backslash migrate.sh path, the Windows login
+// name as the Postgres role, and Homebrew/apt-get help printed to a Windows owner.
+//
+// Run:  node tests/dev_windows.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cp = require('node:child_process');
+const fs = require('node:fs');
+const lib = require('../scripts/gds/dev-lib.js');
+const devCli = require('../scripts/gds/dev.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+const PF = 'C:\\Program Files';
+const GIT_BASH = 'C:\\Program Files\\Git\\bin\\bash.exe';
+const WSL_BASH = 'C:\\Windows\\System32\\bash.exe';
+const PG16_BIN = 'C:\\Program Files\\PostgreSQL\\16\\bin';
+const lower = (s) => String(s).toLowerCase();
+// A fake existsSync over an exact (case-insensitive, Windows-style) path set.
+const existsIn = (...paths) => (p) => paths.map(lower).includes(lower(p));
+
+// ======================= 1. dev-lib, platform:'win32' =======================
+
+t('npmInvocation: Windows runs npm-cli.js through node, no shell', () => {
+  const inv = lib.npmInvocation(['ci'], {
+    platform: 'win32', execPath: 'C:\\Program Files\\nodejs\\node.exe',
+    exists: existsIn('C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js'),
+  });
+  assert.equal(inv.cmd, 'C:\\Program Files\\nodejs\\node.exe');
+  assert.deepEqual(inv.args, ['C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js', 'ci']);
+  assert.equal(inv.shell, false);
+});
+
+t('npmInvocation: Windows without npm-cli.js falls back to the .cmd shim through a shell, as one string', () => {
+  const inv = lib.npmInvocation(['install'], { platform: 'win32', execPath: 'C:\\n\\node.exe', exists: () => false });
+  assert.equal(inv.shell, true);
+  assert.equal(inv.cmd, 'npm install');
+  assert.deepEqual(inv.args, []); // no args array beside shell:true (DEP0190)
+});
+
+t('npmInvocation: Mac/Linux keep the plain spawn', () => {
+  for (const platform of ['darwin', 'linux']) {
+    assert.deepEqual(lib.npmInvocation(['ci'], { platform, exists: () => true }), { cmd: 'npm', args: ['ci'], shell: false });
+  }
+});
+
+t('isWslBashLauncher: System32 / Sysnative / WindowsApps bash are WSL, Git Bash is not', () => {
+  assert.equal(lib.isWslBashLauncher(WSL_BASH), true);
+  assert.equal(lib.isWslBashLauncher('C:\\WINDOWS\\Sysnative\\bash.exe'), true);
+  assert.equal(lib.isWslBashLauncher('C:\\Users\\a\\AppData\\Local\\Microsoft\\WindowsApps\\bash.exe'), true);
+  assert.equal(lib.isWslBashLauncher(GIT_BASH), false);
+  assert.equal(lib.isWslBashLauncher('C:\\Program Files\\Git\\usr\\bin\\bash.exe'), false);
+});
+
+t('resolveBash: Windows finds Git Bash in Program Files and never picks WSL’s bash', () => {
+  const r = lib.resolveBash({
+    platform: 'win32', env: { ProgramFiles: PF },
+    whereAll: (b) => (b === 'bash' ? [WSL_BASH] : []),
+    exists: existsIn(GIT_BASH, WSL_BASH),
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.bin, GIT_BASH);
+});
+
+t('resolveBash: Windows prefers the Git Bash this terminal runs in (EXEPATH)', () => {
+  const own = 'D:\\tools\\Git\\bin\\bash.exe';
+  const r = lib.resolveBash({ platform: 'win32', env: { EXEPATH: 'D:\\tools\\Git\\bin', ProgramFiles: PF }, exists: existsIn(own, GIT_BASH) });
+  assert.equal(r.bin, own);
+});
+
+t('resolveBash: Windows finds Git Bash beside the git on PATH (custom install folder)', () => {
+  const custom = 'E:\\Apps\\Git\\bin\\bash.exe';
+  const r = lib.resolveBash({
+    platform: 'win32', env: {},
+    whereAll: (b) => (b === 'git' ? ['E:\\Apps\\Git\\cmd\\git.exe'] : []),
+    exists: existsIn(custom),
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.bin, custom);
+});
+
+t('resolveBash: Windows env names are read case-insensitively (PROGRAMFILES)', () => {
+  const r = lib.resolveBash({ platform: 'win32', env: { PROGRAMFILES: PF }, exists: existsIn(GIT_BASH) });
+  assert.equal(r.bin, GIT_BASH);
+});
+
+t('resolveBash: a WSL-only machine is refused and says so', () => {
+  const r = lib.resolveBash({ platform: 'win32', env: { ProgramFiles: PF }, whereAll: (b) => (b === 'bash' ? [WSL_BASH] : []), exists: existsIn(WSL_BASH) });
+  assert.equal(r.ok, false);
+  assert.equal(r.wslOnly, true);
+});
+
+t('resolveBash: Mac/Linux still use `bash` from PATH', () => {
+  assert.deepEqual(lib.resolveBash({ platform: 'linux', has: (b) => b === 'bash' }), { ok: true, bin: 'bash', source: 'PATH' });
+  assert.equal(lib.resolveBash({ platform: 'darwin', has: () => false }).ok, false);
+});
+
+t('bashScriptPath: Windows gets forward slashes (bash dirname splits on / only)', () => {
+  assert.equal(lib.bashScriptPath('C:\\x\\core\\scripts\\migrate.sh', 'win32'), 'C:/x/core/scripts/migrate.sh');
+  assert.equal(lib.bashScriptPath('/x/core/scripts/migrate.sh', 'linux'), '/x/core/scripts/migrate.sh');
+});
+
+t('windowsPgInstalls: finds installer folders newest-first, deduped, psql.exe required', () => {
+  const dirs = { [lower(`${PF}\\PostgreSQL`)]: ['15', '16', 'data-backup', '17'] };
+  const installs = lib.windowsPgInstalls({
+    env: { ProgramFiles: PF, ProgramW6432: PF }, // the same folder twice on 64-bit Windows
+    readdir: (d) => { const v = dirs[lower(d)]; if (!v) throw new Error('ENOENT'); return v; },
+    exists: existsIn(`${PF}\\PostgreSQL\\15\\bin\\psql.exe`, `${PF}\\PostgreSQL\\16\\bin\\psql.exe`), // 17 has no psql.exe
+  });
+  assert.deepEqual(installs.map((i) => i.bin), [PG16_BIN, `${PF}\\PostgreSQL\\15\\bin`]);
+  assert.equal(installs[0].service, 'postgresql-x64-16');
+});
+
+t('pgStartPlan: Windows tries each installed version’s Windows service', () => {
+  const plan = lib.pgStartPlan({ platform: 'win32', env: {}, pgInstalls: [{ service: 'postgresql-x64-16' }, { service: 'postgresql-x64-15' }] });
+  assert.deepEqual(plan.map((s) => [s.cmd, ...s.args]), [['net', 'start', 'postgresql-x64-16'], ['net', 'start', 'postgresql-x64-15']]);
+  assert.deepEqual(lib.pgStartPlan({ platform: 'win32', env: {} }), []);
+});
+
+t('pgClientArgs: Windows adds -w (never prompt) except for pg_isready', () => {
+  const params = { pgHost: 'localhost', pgUser: 'postgres' };
+  assert.deepEqual(lib.pgClientArgs(params, { platform: 'win32' }), ['-h', 'localhost', '-U', 'postgres', '-w']);
+  assert.deepEqual(lib.pgClientArgs(params, { platform: 'win32', forReady: true }), ['-h', 'localhost', '-U', 'postgres']);
+  assert.deepEqual(lib.pgClientArgs(params, { platform: 'darwin' }), ['-h', 'localhost', '-U', 'postgres']);
+});
+
+t('resolveRunParams: Windows defaults the Postgres role to `postgres`; PGUSER still wins', () => {
+  const f = { readFileSync: () => { throw new Error('ENOENT'); } };
+  const base = { instanceRoot: 'C:\\Users\\Lars\\proj', coreRoot: 'C:\\core', f, userInfo: () => ({ username: 'Lars' }), argv: [] };
+  assert.equal(lib.resolveRunParams({ ...base, env: {}, platform: 'win32' }).pgUser, 'postgres');
+  assert.equal(lib.resolveRunParams({ ...base, env: { PGUSER: 'me' }, platform: 'win32' }).pgUser, 'me');
+  assert.equal(lib.resolveRunParams({ ...base, env: {}, platform: 'darwin' }).pgUser, 'Lars');
+});
+
+t('pgInstallHint / pgStartHint: Windows steps for Windows, unchanged elsewhere', () => {
+  const win = lib.pgInstallHint('win32').join('\n');
+  assert.match(win, /postgresql\.org\/download\/windows/);
+  assert.match(win, /PGPASSWORD/);
+  assert.match(win, /self-host\.md/);           // Docker named as the fallback
+  assert.doesNotMatch(win, /brew|apt-get/);
+  assert.match(lib.pgInstallHint('darwin').join('\n'), /brew install postgresql@16/);
+  assert.match(lib.pgInstallHint('linux').join('\n'), /apt-get/);
+  const start = lib.pgStartHint('win32', { pgInstalls: [{ service: 'postgresql-x64-17' }] }).join('\n');
+  assert.match(start, /services\.msc/);
+  assert.match(start, /Start-Service postgresql-x64-17/);
+  assert.match(lib.pgStartHint('linux').join('\n'), /sudo service postgresql start/);
+});
+
+t('pgAuthHint: only on Windows, only for an authentication refusal', () => {
+  assert.match(lib.pgAuthHint('win32', 'fe_sendauth: no password supplied').join('\n'), /PGPASSWORD/);
+  assert.match(lib.pgAuthHint('win32', 'password authentication failed for user "postgres"').join('\n'), /"postgres"/);
+  assert.deepEqual(lib.pgAuthHint('win32', 'disk full'), []);
+  assert.deepEqual(lib.pgAuthHint('linux', 'no password supplied'), []);
+});
+
+t('bashMissingHint: Git for Windows first, Docker as the fallback, WSL explained', () => {
+  const h = lib.bashMissingHint('win32', { wslOnly: true }).join('\n');
+  assert.match(h, /git-scm\.com\/download\/win/);
+  assert.match(h, /self-host\.md/);
+  assert.match(h, /WSL/);
+  assert.doesNotMatch(lib.bashMissingHint('win32').join('\n'), /WSL/);
+  assert.deepEqual(lib.bashMissingHint('darwin'), []);
+});
+
+// ============ 2. dev.js wiring, process.platform + spawnSync stubbed ============
+
+// Run fn() as if on Windows: process.platform, spawnSync, existsSync, readdirSync
+// and the env keys the lookups read are all swapped, then restored however fn ends.
+// `spawn(cmd, args, opts)` answers each spawnSync; every call is recorded.
+function onWindows({ spawn, exists = () => false, readdir = null, env = {} }, fn) {
+  const realPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+  const real = { spawnSync: cp.spawnSync, existsSync: fs.existsSync, readdirSync: fs.readdirSync, log: console.log, error: console.error };
+  const envKeys = ['PATH', 'EXEPATH', 'ProgramFiles', 'ProgramW6432', 'ProgramFiles(x86)', 'LOCALAPPDATA', ...Object.keys(env)];
+  const savedEnv = Object.fromEntries(envKeys.map((k) => [k, process.env[k]]));
+  const calls = [];
+  const out = [];
+  Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+  for (const k of envKeys) if (k !== 'PATH') delete process.env[k];
+  Object.assign(process.env, env);
+  cp.spawnSync = (cmd, args = [], opts = {}) => {
+    calls.push({ cmd, args, opts });
+    const r = spawn(cmd, args, opts) || {};
+    return { status: 0, stdout: '', stderr: '', ...r };
+  };
+  fs.existsSync = (p) => exists(String(p));
+  if (readdir) fs.readdirSync = (d) => readdir(String(d));
+  console.log = (...a) => out.push(a.join(' '));
+  console.error = (...a) => out.push(a.join(' '));
+  try {
+    return { value: fn(), calls, out: out.join('\n') };
+  } finally {
+    Object.defineProperty(process, 'platform', realPlatform);
+    cp.spawnSync = real.spawnSync; fs.existsSync = real.existsSync; fs.readdirSync = real.readdirSync;
+    console.log = real.log; console.error = real.error;
+    for (const [k, v] of Object.entries(savedEnv)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+  }
+}
+
+// `where <bin>` answers from a { bin: [paths] } map; everything else exits 0.
+const whereFrom = (onPath) => (cmd, args) => {
+  if (cmd !== 'where') return {};
+  const hits = typeof onPath === 'function' ? onPath(args[0]) : onPath[args[0]];
+  return hits && hits.length ? { status: 0, stdout: hits.join('\r\n') + '\r\n' } : { status: 1 };
+};
+
+const INST = { instanceRoot: '/x/inst' };
+
+t('dev.js installDeps on Windows: npm runs through node + npm-cli.js, not a bare `npm` spawn', () => {
+  const { value, calls } = onWindows({
+    spawn: whereFrom({ npm: ['C:\\Program Files\\nodejs\\npm.cmd'] }),
+    exists: (p) => p.endsWith('package-lock.json') || p.endsWith('npm-cli.js'),
+  }, () => devCli.installDeps(INST));
+  assert.equal(value, true);
+  const npmRun = calls.find((c) => c.cmd !== 'where');
+  assert.equal(npmRun.cmd, process.execPath);
+  assert.match(npmRun.args[0], /npm-cli\.js$/);
+  assert.equal(npmRun.args[1], 'ci');
+  assert.ok(!npmRun.opts.shell, 'no shell needed when npm-cli.js is used');
+});
+
+t('dev.js installDeps on Windows without npm-cli.js: the npm.cmd shim goes through a shell', () => {
+  const { calls } = onWindows({
+    spawn: whereFrom({ npm: ['C:\\Program Files\\nodejs\\npm.cmd'] }),
+    exists: (p) => p.endsWith('package-lock.json'),
+  }, () => devCli.installDeps(INST));
+  const npmRun = calls.find((c) => c.cmd !== 'where');
+  assert.equal(npmRun.cmd, 'npm ci');
+  assert.equal(npmRun.opts.shell, true);
+});
+
+t('dev.js preflight on Windows: finds installed Postgres off PATH and Git Bash over WSL bash', () => {
+  const psqlVisible = () => lower(process.env.PATH || '').includes(lower(PG16_BIN));
+  const { value, out } = onWindows({
+    env: { ProgramFiles: PF },
+    spawn: whereFrom((bin) => {
+      if (['psql', 'createdb', 'pg_isready'].includes(bin)) return psqlVisible() ? [`${PG16_BIN}\\${bin}.exe`] : [];
+      if (bin === 'bash') return [WSL_BASH];
+      return [];
+    }),
+    readdir: (d) => { if (lower(d) === lower(`${PF}\\PostgreSQL`)) return ['16']; throw new Error('ENOENT'); },
+    exists: (p) => [lower(`${PG16_BIN}\\psql.exe`), lower(GIT_BASH), lower(WSL_BASH)].includes(lower(p)),
+  }, () => {
+    const r = devCli.preflight({});
+    return { ...r, pathHadPg: psqlVisible() };
+  });
+  assert.equal(value.ok, true, out);
+  assert.equal(value.pathHadPg, true, 'the installer’s bin folder was put on PATH');
+  assert.equal(value.bashBin, GIT_BASH);
+});
+
+t('dev.js preflight on Windows with no Postgres: Windows install steps, not Homebrew/apt-get', () => {
+  const { value, out } = onWindows({ env: { ProgramFiles: PF }, spawn: whereFrom({}), readdir: () => { throw new Error('ENOENT'); } },
+    () => devCli.preflight({}));
+  assert.equal(value.ok, false);
+  assert.match(out, /postgresql\.org\/download\/windows/);
+  assert.doesNotMatch(out, /brew install|apt-get/);
+});
+
+t('dev.js preflight on Windows with only WSL bash: refuses, names Git for Windows and Docker', () => {
+  const { value, out } = onWindows({
+    env: { ProgramFiles: PF },
+    spawn: whereFrom({ psql: ['p'], createdb: ['c'], pg_isready: ['r'], bash: [WSL_BASH] }),
+    exists: (p) => lower(p) === lower(WSL_BASH),
+  }, () => devCli.preflight({}));
+  assert.equal(value.ok, false);
+  assert.match(out, /git-scm\.com\/download\/win/);
+  assert.match(out, /self-host\.md/);
+  assert.match(out, /WSL/);
+  assert.doesNotMatch(out, /use WSL/); // WSL is no longer the recommended path
+});
+
+t('dev.js migrate on Windows: Git Bash gets a forward-slash migrate.sh path', () => {
+  const params = { coreRoot: 'C:\\core', instanceRoot: 'C:\\inst', pgHost: 'localhost', pgUser: 'postgres', dbName: 'inst', envPrefix: 'CLOUDBONGOS', gdsOnly: true };
+  const { value, calls } = onWindows({ spawn: () => ({ status: 0, stdout: 'apply core_001_x.sql\n' }) },
+    () => devCli.migrate(params, GIT_BASH));
+  assert.equal(value, true);
+  assert.equal(calls[0].cmd, GIT_BASH);
+  assert.equal(calls[0].args[0], 'C:/core/scripts/migrate.sh');
+});
+
+t('dev.js createDb on Windows: psql/createdb never prompt (-w) and a refusal explains PGPASSWORD', () => {
+  const params = { pgHost: 'localhost', pgUser: 'postgres', dbName: 'inst' };
+  const { value, calls, out } = onWindows({
+    spawn: (cmd) => (cmd === 'createdb'
+      ? { status: 1, stderr: 'createdb: error: connection to server failed: fe_sendauth: no password supplied' }
+      : { status: 2, stderr: 'fe_sendauth: no password supplied' }),
+  }, () => devCli.createDb(params));
+  assert.equal(value, false);
+  for (const c of calls.filter((x) => x.cmd === 'psql' || x.cmd === 'createdb')) assert.ok(c.args.includes('-w'), `${c.cmd} got -w`);
+  assert.match(out, /PGPASSWORD/);
+  assert.match(out, /"postgres"/);
+});
+
+t('dev.js usage: Windows is supported (Git Bash), Docker is the fallback, WSL is not the answer', () => {
+  const lines = [];
+  const realLog = console.log;
+  console.log = (...a) => lines.push(a.join(' '));
+  try { devCli.usage(); } finally { console.log = realLog; }
+  const u = lines.join('\n');
+  assert.match(u, /Windows/);
+  assert.match(u, /Git Bash/);
+  assert.match(u, /self-host\.md/);
+  assert.doesNotMatch(u, /use WSL/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);