@bongos/core 1.18.3 → 1.18.18

package/scripts/gds/dev.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/dev.js — `bongos dev`: stand up THIS instance locally, in one command.
+//
+// The gap it closes (ADR 0149): a project the creation flow scaffolds ships a repo
+// configured for http://localhost:<port> but no way to START it locally. `bongos
+// onboard` provisions a CLOUD server (domain + DO/Cloudflare); Docker serves a
+// vanilla brand on :3000. Running THIS repo's brand on its OWN port meant a manual
+// six-part Postgres+migrate+env+server assembly with three silent mismatches. This
+// command does the whole thing, idempotently, and hands off to sign-in.
+//
+//   bongos dev            up: Postgres -> createdb -> migrate -> server -> login
+//   bongos dev stop       stop the background server this launched
+//   bongos dev status     is it up? what URL? is sign-in configured?
+//
+// Flags: --foreground (run attached; Ctrl-C stops), --no-login (don't auto sign in),
+//        --skip-migrate, --port <n>, --db <name>.
+//
+// Design notes:
+//  * The server runs DETACHED but MANAGED (pid/log keyed per instance) — the fix for
+//    the orphaned-background-server confusion (a stale server on :3005 answering a
+//    new project's login). `bongos dev status`/`stop` make it visible + killable, and
+//    a re-run is a no-op if it's already up. --foreground is there for those who want
+//    Ctrl-C lifecycle.
+//  * PORT is forced to branding's port (the server ignores branding — platform-server.js:44).
+//  * PGDATABASE is set for BOTH migrate.sh and the server (fixes the pool.js/migrate.sh
+//    default split); PGHOST defaults to TCP localhost (not the Linux peer socket).
+
+const cp = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const dev = require('./dev-lib');
+const { arg, hasFlag, loadSessionSync } = require('./cli-lib');
+
+// ---- small terminal helpers (ascii-first; a builder's private surface) ---------
+const ok = (m) => console.log(`  ✓ ${m}`);
+const info = (m) => console.log(`▸ ${m}`);
+const warn = (m) => console.log(`  ⚠ ${m}`);
+const fail = (m) => console.error(`✖ ${m}`);
+const blank = () => console.log('');
+
+function run(cmd, args, opts = {}) {
+  const r = cp.spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '', error: r.error };
+}
+function has(bin) {
+  // `command -v` via the binary's own --version is unreliable across tools; probe PATH directly.
+  const which = process.platform === 'win32' ? 'where' : 'which';
+  return run(which, [bin]).status === 0;
+}
+function tail(s, n = 6) {
+  return String(s || '').trimEnd().split('\n').slice(-n).join('\n');
+}
+// Portable synchronous pause (no subprocess, no foreground-sleep dependency).
+function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function usage() {
+  console.log(`bongos dev — run THIS instance locally, in one command.
+
+Usage:
+  bongos dev [--foreground] [--no-login] [--skip-migrate] [--port <n>] [--db <name>]
+  bongos dev stop        Stop the local server this launched
+  bongos dev status      Show whether it's running, its URL, and sign-in state
+
+What it does (idempotent — safe to re-run):
+  1. Make sure Postgres is running (starts it via Homebrew if it isn't)
+  2. Create this instance's database if it doesn't exist
+  3. Build/refresh its tables (migrations)
+  4. Start the server on the port in config/branding.json
+  5. Sign you in to this instance (unless --no-login)
+
+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).`);
+}
+
+// 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;
+}
+
+function pgReady(params) {
+  return run('pg_isready', [...pgArgs(params), '-q']).status === 0;
+}
+
+// Best-effort: start a Homebrew-managed Postgres, then poll until it accepts
+// connections. Returns true if ready, false if we couldn't bring it up.
+function ensurePostgres(params) {
+  if (pgReady(params)) { ok('Postgres is running'); return true; }
+  info('Postgres is not running — trying to start it…');
+  if (has('brew')) {
+    const formulae = run('brew', ['list', '--formula']).stdout
+      .split(/\s+/).filter((x) => /^postgresql(@\d+)?$/.test(x))
+      .sort().reverse();
+    const target = formulae[0] || 'postgresql@16';
+    run('brew', ['services', 'start', target], { stdio: 'ignore' });
+  } else if (has('pg_ctl') && process.env.PGDATA) {
+    run('pg_ctl', ['start', '-w', '-D', process.env.PGDATA], { stdio: 'ignore' });
+  }
+  // Poll for readiness (~15s). pg_isready is cheap; pause between probes.
+  for (let i = 0; i < 15; i++) {
+    if (pgReady(params)) { ok('Postgres started'); return true; }
+    sleepSync(1000);
+  }
+  return pgReady(params);
+}
+
+function dbExists(params) {
+  const r = run('psql', [...pgArgs(params), '-d', 'postgres', '-tAc',
+    `SELECT 1 FROM pg_database WHERE datname='${params.dbName}'`]);
+  return r.status === 0 && r.stdout.trim() === '1';
+}
+
+function createDb(params) {
+  if (dbExists(params)) { ok(`database "${params.dbName}" exists`); return true; }
+  const r = run('createdb', [...pgArgs(params), params.dbName]);
+  if (r.status === 0) { ok(`created database "${params.dbName}"`); return true; }
+  // A race or prior partial run may have created it; treat "already exists" as fine.
+  if (/already exists/i.test(r.stderr)) { ok(`database "${params.dbName}" exists`); return true; }
+  fail(`could not create database "${params.dbName}": ${tail(r.stderr, 2) || r.error}`);
+  return false;
+}
+
+function migrate(params) {
+  const migrateSh = path.join(params.coreRoot, 'scripts', 'migrate.sh');
+  const env = dev.buildEnv(params, { role: 'migrate' });
+  const r = run('bash', [migrateSh], { cwd: params.instanceRoot, env });
+  if (r.status !== 0) {
+    fail('migrations failed:');
+    console.error(tail(r.stderr || r.stdout, 12));
+    return false;
+  }
+  const applied = (r.stdout.match(/^apply /gm) || []).length;
+  ok(applied ? `schema migrated (${applied} migration${applied === 1 ? '' : 's'} applied)` : 'schema up to date');
+  return true;
+}
+
+// Guidance for the ONE step that can require the user: a GitHub OAuth App. Only
+// printed when no creds are resolvable — most machines that already ran another
+// instance carry usable creds and skip this entirely.
+function printOAuthGuidance(params) {
+  const cb = `${params.publicOrigin}/api/gds/auth/web/callback`;
+  const credsPath = path.join(require('node:os').homedir(), '.config', params.configDir, 'gds-github.json');
+  blank();
+  warn('Sign-in is not configured yet (no GitHub OAuth credentials found).');
+  console.log('  The server will run, but `bongos login` needs a GitHub OAuth App first:');
+  console.log('    1. github.com → Settings → Developer settings → OAuth Apps → New OAuth App');
+  console.log(`       Homepage URL:              ${params.publicOrigin}`);
+  console.log(`       Authorization callback URL: ${cb}`);
+  console.log('       Then tick "Enable Device Flow" and Save (a separate save).');
+  console.log('    2. Copy the Client ID; generate a client secret.');
+  console.log(`    3. Save both into ${credsPath} as:`);
+  console.log('       { "client_id": "…", "client_secret": "…" }');
+  console.log('    4. Re-run `bongos dev`.');
+}
+
+function signedInToThisInstance(params) {
+  try {
+    const s = loadSessionSync();
+    if (!s || !s.token || !s.api_base) return false;
+    return new URL(s.api_base).host === new URL(params.publicOrigin).host;
+  } catch { return false; }
+}
+
+async function waitHealthy(params, ms = 20000) {
+  const start = Date.now();
+  while (Date.now() - start < ms) {
+    const h = await dev.health(params);
+    if (h.up) return h;
+    await sleep(1000);
+  }
+  return dev.health(params);
+}
+
+function loginNow(params) {
+  const loginJs = path.join(params.coreRoot, 'scripts', 'gds', 'login.js');
+  info(`Signing in to ${params.publicOrigin}${params.firstAdmin ? ` (sign in as ${params.firstAdmin})` : ''}…`);
+  const r = cp.spawnSync(process.execPath, [loginJs, params.publicOrigin], { stdio: 'inherit' });
+  return r.status === 0;
+}
+
+// ---- subcommands ---------------------------------------------------------------
+
+function cmdStop(params) {
+  const res = dev.stop(params);
+  if (res.wasRunning) ok(`stopped the local ${params.dbName} server (pid ${res.pid})`);
+  else console.log(`  (no running ${params.dbName} server to stop)`);
+  return 0;
+}
+
+async function cmdStatus(params) {
+  const running = dev.isRunning(params);
+  console.log(`instance:  ${path.basename(params.instanceRoot)}  (${params.publicOrigin})`);
+  console.log(`database:  ${params.dbName}  on ${params.pgHost}`);
+  if (!running) { console.log('server:    not running  — start it with `bongos dev`'); return 0; }
+  const h = await dev.health(params);
+  console.log(`server:    running (pid ${dev.readPid(params)}), health ${h.up ? 'OK' : 'starting/unreachable'}`);
+  console.log(`sign-in:   ${h.authConfigured ? 'configured' : 'NOT configured (see `bongos dev`)'}`);
+  console.log(`logs:      ${dev.logPath(params)}`);
+  return 0;
+}
+
+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).
+  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');
+  }
+
+  // Preflight: DB tooling + bash for migrations.
+  const missing = ['psql', 'createdb', 'pg_isready'].filter((b) => !has(b));
+  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;
+  }
+  if (!skipMigrate && !has('bash')) {
+    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;
+  }
+
+  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');
+    return 1;
+  }
+  if (!createDb(params)) return 1;
+  if (skipMigrate) warn('skipping migrations (--skip-migrate)');
+  else if (!migrate(params)) return 1;
+
+  const authReady = dev.authWillWork();
+  if (authReady) ok('sign-in configured');
+
+  // Foreground mode: run the server attached; Ctrl-C stops it. Print the login hint
+  // up front (the server owns the terminal once it starts).
+  if (foreground) {
+    blank();
+    info(`Starting ${params.dbName} on ${params.publicOrigin}  (Ctrl-C to stop)`);
+    if (authReady && !signedInToThisInstance(params)) {
+      console.log('  Once it says "listening", open a SECOND terminal and run:');
+      console.log(`     bongos login ${params.publicOrigin}${params.firstAdmin ? `   (sign in as ${params.firstAdmin})` : ''}`);
+    } else if (!authReady) printOAuthGuidance(params);
+    blank();
+    const env = dev.buildEnv(params, { role: 'server' });
+    const r = cp.spawnSync(process.execPath, [dev.serverEntry(params)], { cwd: params.instanceRoot, env, stdio: 'inherit' });
+    return r.status == null ? 1 : r.status;
+  }
+
+  // Default: managed background server.
+  const started = dev.startDetached(params);
+  if (started.already) ok(`server already running (pid ${started.pid})`);
+  const h = await waitHealthy(params);
+  if (!h.up) {
+    fail('the server did not become healthy in time. Recent log:');
+    try { console.error(tail(fs.readFileSync(started.log, 'utf8'), 12)); } catch { /* no log */ }
+    dev.stop(params); // don't leave a broken detached server behind
+    return 1;
+  }
+  if (!started.already) ok(`server running on ${params.publicOrigin} (pid ${started.pid})`);
+  blank();
+  console.log(`  → ${params.publicOrigin}`);
+  console.log(`     status:  bongos dev status      logs: ${started.log}`);
+  console.log(`     stop:    bongos dev stop`);
+  blank();
+
+  if (!authReady) { printOAuthGuidance(params); return 0; }
+  if (noLogin) { console.log('  Sign in when ready:  bongos login ' + params.publicOrigin); return 0; }
+  if (signedInToThisInstance(params)) { ok('already signed in to this instance'); return 0; }
+  const signedIn = loginNow(params);
+  blank();
+  if (signedIn) ok('all set — you’re signed in. Try:  bongos start');
+  else console.log('  Sign-in didn’t finish — re-run:  bongos login ' + params.publicOrigin);
+  return 0;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (hasFlag('--help') || hasFlag('-h') || argv[0] === 'help') { usage(); return 0; }
+
+  const params = dev.resolveRunParams({ instanceRoot: process.cwd(), argv });
+  const sub = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'up';
+
+  if (sub === 'stop') return cmdStop(params);
+  if (sub === 'status') return cmdStatus(params);
+  if (sub !== 'up') { fail(`unknown subcommand "${sub}"`); usage(); return 2; }
+
+  return cmdUp(params, {
+    foreground: hasFlag('--foreground'),
+    noLogin: hasFlag('--no-login'),
+    skipMigrate: hasFlag('--skip-migrate'),
+  });
+}
+
+if (require.main === module) {
+  main().then((code) => process.exit(code || 0)).catch((e) => { fail(e && e.message ? e.message : String(e)); process.exit(1); });
+}
+
+module.exports = { usage, pgArgs };

package/scripts/gds/doctor.js

@@ -28,6 +28,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { execSync, spawnSync } = require('node:child_process');
 const { cliClient, SESSION_PATH, loadSession } = require('./cli-lib');
+const { preflightChecks } = require('./preflight');
 
 // ANSI helpers (only if stdout is a TTY; otherwise emit plain text)
 const TTY = process.stdout.isTTY;
@@ -130,77 +131,101 @@ async function checkSession() {
 function checkToolchain() {
   section('Toolchain');
 
-  // Node — setup-builder.sh requires >= 22; the scripts assume modern Node.
-  const nodeMajor = Number((process.versions.node || '0').split('.')[0]);
-  if (nodeMajor >= 22) {
-    ok('toolchain', `Node ${process.version} (>= 22 required).`);
-  } else {
-    fail('toolchain', `Node ${process.version} is below the required v22. Upgrade Node (e.g. nvm install 22, or https://nodejs.org).`);
+  // Node + deps + `claude` come from the shared onboarding preflight (preflight.js)
+  // — the single source of truth also run up front at /builder-setup (task 1002401),
+  // so doctor and setup can never drift. (This also gives doctor the node_modules
+  // check it previously lacked.)
+  const results = preflightChecks();
+  for (const r of results) {
+    if (r.level === 'ok') {
+      ok('toolchain', `${r.title}: ${r.detail}`);
+    } else {
+      const emit = r.level === 'warn' ? warn : fail;
+      emit('toolchain', `${r.title}: ${r.detail}`);
+      if (r.fix) emit('toolchain', `Fix: ${r.fix}`);
+    }
   }
 
-  // claude CLI — same resolution order the grader uses.
-  const fromEnv = process.env.OTB_CLAUDE_BIN
-    ? ' (via OTB_CLAUDE_BIN)'
-    : process.env.CLAUDE_BIN
-    ? ' (via CLAUDE_BIN)'
-    : '';
-  const bin = process.env.OTB_CLAUDE_BIN || process.env.CLAUDE_BIN || 'claude';
-  let r;
-  try {
-    r = spawnSync(bin, ['--version'], {
-      encoding: 'utf8',
-      shell: process.platform === 'win32',
-      windowsHide: true,
-      timeout: 15000,
-    });
-  } catch (err) {
-    r = { error: err };
-  }
-  if (r && !r.error && r.status === 0) {
-    const ver = (r.stdout || '').trim().split('\n')[0] || 'present';
-    ok('toolchain', `claude CLI launches${fromEnv}: ${ver} — the grader can spawn its workers.`);
-    // Windows-only: warn if the resolved binary is the desktop "App execution
-    // alias" stub. It can pass --version yet misbehave under the grader's
-    // stdio redirection (SUBAGENT_NONZERO_EXIT). Learning #42.
-    if (process.platform === 'win32' && !process.env.OTB_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 || '')) {
-          warn('toolchain', `claude resolves to the WindowsApps desktop alias, which can fail headless grading (SUBAGENT_NONZERO_EXIT). Prefer a real CLI: npm i -g @anthropic-ai/claude-code (learning #42).`);
-        }
-      } catch (_) { /* best-effort */ }
-    }
-  } else {
-    const why = r && r.error ? (r.error.code || r.error.message) : `exited ${r ? r.status : '?'}`;
-    fail('toolchain', `claude CLI not launchable (${bin}: ${why}). The grader spawns it per worker — without it, ships fail grading with SUBAGENT_SPAWN_FAILED.`);
-    fail('toolchain', `Fix: npm i -g @anthropic-ai/claude-code  (puts a real claude on PATH). If it lives elsewhere, set OTB_CLAUDE_BIN to its full path and re-run.`);
+  // Windows-only extra (beyond the shared preflight): even when `claude` launches,
+  // warn if it resolves to the WindowsApps desktop "App execution alias" stub — it
+  // 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) {
+    try {
+      const where = spawnSync('where', ['claude'], { encoding: 'utf8', shell: true, timeout: 8000 });
+      if (where.status === 0 && /WindowsApps/i.test(where.stdout || '')) {
+        warn('toolchain', `claude resolves to the WindowsApps desktop alias, which can fail headless grading (SUBAGENT_NONZERO_EXIT). Prefer a real CLI: npm i -g @anthropic-ai/claude-code (learning #42).`);
+      }
+    } catch (_) { /* best-effort */ }
   }
 }
 
 // --------------------------------------------------------------------------
 // Check 3 — Git plumbing
 // --------------------------------------------------------------------------
-function checkGitPlumbing() {
-  section('Git plumbing');
-  const hooksPath = gitOut('git config --get core.hooksPath');
+// Pure verdict for the hooks gate, extracted so the truth table is testable
+// (tests/doctor_hooks.mjs) — the box-auth-check `decideBoxAuth` precedent.
+//
+// `.husky/` is INSTANCE topology, not shipped in the portable core (README
+// "Secrets scanning"). So its absence is not a builder error: it means ADR 0043
+// layer 1 has nothing to activate here, and CI + the post-push main audit are
+// the enforcing layers. Recommending `.husky` regardless is what produced the
+// unbreakable red loop this replaces — doctor demanded a dir that wasn't there,
+// then failed on the dangling path it had just told you to set.
+function classifyHooksState({ hooksPath, worktreeRoot, exists = fs.existsSync }) {
+  const huskyDir = worktreeRoot ? path.join(worktreeRoot, '.husky') : '.husky';
+  const huskyPresent = exists(huskyDir);
+  const installer = 'node scripts/gds/install-git-hooks.js';
+
   if (!hooksPath) {
-    fail('git', `core.hooksPath is unset. Activate the pre-commit secrets guard with:\n      git config core.hooksPath .husky`);
-    return;
-  }
-  // Resolve relative to current worktree root (git's behavior for relative
-  // hooksPath values). Absolute paths resolve as-is.
-  let resolved = hooksPath;
-  if (!path.isAbsolute(hooksPath)) {
-    const top = gitOut('git rev-parse --show-toplevel');
-    if (top) resolved = path.join(top, hooksPath);
+    if (!huskyPresent) {
+      return {
+        status: 'warn',
+        code: 'no-hooks-dir',
+        resolved: null,
+        message:
+          'No hooks dir in this checkout (.husky/ is instance topology, not shipped in the portable core), '
+          + 'so the local pre-commit/pre-push gates are inactive. CI secrets-scan and the post-push main audit still enforce.',
+      };
+    }
+    return {
+      status: 'fail',
+      code: 'inactive',
+      resolved: null,
+      message: `.husky/ is present but core.hooksPath is unset — the secrets + permission gates are not running. Activate with: ${installer}`,
+    };
   }
-  if (!fs.existsSync(resolved)) {
-    fail('git', `core.hooksPath="${hooksPath}" resolves to a non-existent path: ${resolved}`);
-    fail('git', `Reset with: git config core.hooksPath .husky`);
-    return;
+
+  // Relative hooksPath resolves against the worktree root (git's behavior);
+  // absolute resolves as-is.
+  const resolved = path.isAbsolute(hooksPath) || !worktreeRoot
+    ? hooksPath
+    : path.join(worktreeRoot, hooksPath);
+
+  if (!exists(resolved)) {
+    return {
+      status: 'fail',
+      code: 'dangling',
+      resolved,
+      message: huskyPresent
+        ? `core.hooksPath="${hooksPath}" resolves to a non-existent path: ${resolved}. Repoint it with: ${installer}`
+        : `core.hooksPath="${hooksPath}" resolves to a non-existent path: ${resolved}, and this checkout has no .husky/ to point at. Clear it with: git config --unset core.hooksPath`,
+    };
   }
-  ok('git', `core.hooksPath="${hooksPath}" → ${resolved} (exists)`);
-  const preCommit = path.join(resolved, 'pre-commit');
+  return { status: 'ok', code: 'active', resolved, message: `core.hooksPath="${hooksPath}" → ${resolved} (exists)` };
+}
+
+function checkGitPlumbing() {
+  section('Git plumbing');
+  const verdict = classifyHooksState({
+    hooksPath: gitOut('git config --get core.hooksPath'),
+    worktreeRoot: gitOut('git rev-parse --show-toplevel'),
+  });
+  const report = { ok, warn, fail }[verdict.status];
+  report('git', verdict.message);
+  if (verdict.status !== 'ok') return;
+  const preCommit = path.join(verdict.resolved, 'pre-commit');
   if (!fs.existsSync(preCommit)) {
     warn('git', `No pre-commit file at ${preCommit} — secrets-guard hook will not fire.`);
   } else {
@@ -353,7 +378,11 @@ function checkDeployTooling() {
 // --------------------------------------------------------------------------
 // main
 // --------------------------------------------------------------------------
-(async () => {
+// Guarded so requiring this file for its pure helpers (tests/doctor_hooks.mjs)
+// does not run the checks, which shell out to git and hit the network.
+module.exports = { classifyHooksState };
+
+if (require.main === module) (async () => {
   console.log(`${C.bold}GDS Doctor${C.reset} — local-machine health check`);
   await checkSession();
   checkToolchain();

package/scripts/gds/fetch-art-key.js

@@ -46,7 +46,7 @@ async function main() {
     const res = await fetch(`${base}/api/gds/me/art-key`, {
       headers: {
         Authorization: `Bearer ${session.token}`,
-        'User-Agent': 'amazonprimea-fetch-art-key/1.0',
+        'User-Agent': require('../../src/branding').userAgent(),
       },
       signal: ctrl.signal,
     });

package/scripts/gds/fetch-sound-prefs.js

@@ -49,11 +49,11 @@ async function main() {
     // existing cached state (fail-open).
     const [soundRes, eventRes] = await Promise.all([
       fetch(`${sess.apiBase}/api/gds/me/sound-prefs`, {
-        headers: { Authorization: `Bearer ${sess.token}`, 'User-Agent': 'amazonprimea-fetch-sound-prefs/1.0' },
+        headers: { Authorization: `Bearer ${sess.token}`, 'User-Agent': require('../../src/branding').userAgent() },
         signal: ctrl.signal,
       }),
       fetch(`${sess.apiBase}/api/gds/me/event-sound-prefs`, {
-        headers: { Authorization: `Bearer ${sess.token}`, 'User-Agent': 'amazonprimea-fetch-sound-prefs/1.0' },
+        headers: { Authorization: `Bearer ${sess.token}`, 'User-Agent': require('../../src/branding').userAgent() },
         signal: ctrl.signal,
       }),
     ]);