@bongos/core 1.17.0

package/scripts/render-diagrams.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Render Mermaid (.mmd) diagram sources to SVG + PNG.
+#
+# Usage:
+#   scripts/render-diagrams.sh                 # render every docs/onboarding/diagrams/*.mmd
+#   scripts/render-diagrams.sh a.mmd b.mmd ...  # render only the given sources
+#
+# Each <name>.mmd renders to BOTH:
+#   <name>.svg  — vector; the crisp, pannable/zoomable asset the /builders viewer
+#                 (modules/hall-ui/public/diagram-viewer.js) loads and injects inline.
+#   <name>.png  — 2x raster; the <img> fallback (no-JS / SVG-fetch failure) and
+#                 for external embeds (README, OG images).
+# Keep node labels free of literal "[]" — the renderer's font shows it as a
+# missing-glyph box; write "dependencies"/"touches" instead.
+#
+# Chromium (ADR 0110 pt.3 / task 2027): mermaid-cli drives puppeteer, which by
+# DEFAULT downloads its own headless Chromium on first run — a multi-minute
+# network fetch that STALLS the small prod droplet. So this script prefers an
+# already-installed browser and forbids the download when it finds one; it only
+# falls back to puppeteer's own download where nothing is installed (a dev
+# laptop, where that fetch works fine). This is what makes render-at-deploy
+# viable (deploy-prod.sh + infra/box-source-fetch.sh call this).
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DIAGRAM_DIR="$REPO_ROOT/docs/onboarding/diagrams"
+# Shared Mermaid config (generous spacing for all diagrams — task 1066).
+CONFIG="$DIAGRAM_DIR/render-config.json"
+# Puppeteer launch config — carries --no-sandbox, required for headless Chrome as
+# the non-root deploy user on Ubuntu 24.04 (restricted unprivileged user
+# namespaces break Chrome's own sandbox); harmless on a dev laptop.
+PPTR_CONFIG="$DIAGRAM_DIR/puppeteer-config.json"
+CONFIG_ARGS=()
+[ -f "$CONFIG" ] && CONFIG_ARGS+=(-c "$CONFIG")
+[ -f "$PPTR_CONFIG" ] && CONFIG_ARGS+=(-p "$PPTR_CONFIG")
+
+# Resolve a headless Chromium once. Honor a caller-provided
+# PUPPETEER_EXECUTABLE_PATH; otherwise auto-detect a common system browser. When
+# one is found, export PUPPETEER_SKIP_DOWNLOAD so puppeteer never tries to fetch
+# its own (the droplet-stalling download). When none is found we say so and let
+# puppeteer download — the dev-laptop path, unchanged.
+if [ -z "${PUPPETEER_EXECUTABLE_PATH:-}" ]; then
+  for b in google-chrome-stable google-chrome chromium chromium-browser; do
+    p="$(command -v "$b" 2>/dev/null || true)"
+    if [ -n "$p" ]; then export PUPPETEER_EXECUTABLE_PATH="$p"; break; fi
+  done
+fi
+if [ -n "${PUPPETEER_EXECUTABLE_PATH:-}" ]; then
+  export PUPPETEER_SKIP_DOWNLOAD=1
+  echo "render-diagrams: using installed Chromium at $PUPPETEER_EXECUTABLE_PATH (no browser download)"
+else
+  echo "render-diagrams: no system Chromium found — puppeteer will download its own (ok on a dev laptop; stalls a small droplet — install Google Chrome there, see ADR 0122)"
+fi
+
+# Prefer a mmdc already on PATH (a global/CI install — no per-run npx fetch);
+# else npx with a PINNED major so a mermaid-cli breaking release can't silently
+# change the renders.
+if command -v mmdc >/dev/null 2>&1; then
+  MMDC=(mmdc)
+else
+  MMDC=(npx -y @mermaid-js/mermaid-cli@11)
+fi
+
+if [ "$#" -gt 0 ]; then
+  SOURCES=("$@")
+else
+  SOURCES=()
+  while IFS= read -r f; do SOURCES+=("$f"); done < <(find "$DIAGRAM_DIR" -name '*.mmd' | sort)
+fi
+
+if [ "${#SOURCES[@]}" -eq 0 ]; then
+  echo "render-diagrams: no .mmd sources found"
+  exit 0
+fi
+
+for src in "${SOURCES[@]}"; do
+  [ -f "$src" ] || { echo "render-diagrams: skip missing $src"; continue; }
+  svg="${src%.mmd}.svg"
+  png="${src%.mmd}.png"
+  echo "render-diagrams: $src -> $svg + $png"
+  # SVG first (vector, scale-independent — the interactive viewer's primary
+  # asset), then PNG at 2x (the static fallback). White background so both read
+  # correctly on the parchment page and don't show through as transparent.
+  "${MMDC[@]}" -i "$src" -o "$svg" -b white "${CONFIG_ARGS[@]}" >/dev/null 2>&1
+  "${MMDC[@]}" -i "$src" -o "$png" -s 2 -b white "${CONFIG_ARGS[@]}" >/dev/null 2>&1
+done
+
+echo "render-diagrams: done (${#SOURCES[@]} source(s))"

package/scripts/security/dep-audit.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// Dependency vulnerability scan — single source of truth for both CI and the
+// droplet nightly cron (V3.R37 / #258).
+//
+// Two scans are run, in order:
+//   1. `npm audit --audit-level=high --json` against the root package.json.
+//   2. `python3 -m pip_audit -r art/pipeline/requirements.txt --format json`.
+//
+// The script parses both outputs and emits ONE deterministic JSON report on
+// stdout containing every high/critical finding. A short, builder-readable
+// summary goes to stderr so a CI log is skim-able.
+//
+// Two modes:
+//
+//   --report-mode=ci         (default; used by .github/workflows/dep-audit.yml)
+//                            exit 1 if ANY finding is high or critical.
+//                            exit 0 if both scans clean.
+//
+//   --report-mode=nightly    (used by .claude/scheduled-tasks/dep-audit-nightly)
+//                            ALWAYS exit 0 — a nightly cron must not block the
+//                            droplet's other routines. The skill consumes the
+//                            JSON, posts to the team chat-inbox, and creates a
+//                            vulnerability_report row in the Archon security
+//                            view via src/bongos/security.js.
+//
+// Tool resolution:
+//   - npm is required (CI image has it; droplet has it).
+//   - pip-audit is resolved as `python3 -m pip_audit` (works whether installed
+//     via pip, pipx, or pip --user — module form is the most portable).
+//     If neither is found, the script reports `tool_missing: pip-audit` and the
+//     mode decides whether to fail.
+//
+// Output schema (stdout, always valid JSON, even on failure):
+//   {
+//     "ran_at": "<ISO timestamp>",
+//     "mode": "ci" | "nightly",
+//     "npm": { "ok": true|false, "tool_missing": false|true, "findings": [...] },
+//     "pip": { "ok": true|false, "tool_missing": false|true, "findings": [...] },
+//     "high_or_critical_count": <int>,
+//     "exit_code": <int>
+//   }
+//
+// A "finding" has at minimum: { ecosystem, package, severity, id, summary, fix }.
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PIP_REQUIREMENTS = path.join(REPO_ROOT, 'art', 'pipeline', 'requirements.txt');
+
+// CLI args ----------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { mode: 'ci' };
+  for (const a of argv.slice(2)) {
+    if (a === '--report-mode=ci') out.mode = 'ci';
+    else if (a === '--report-mode=nightly') out.mode = 'nightly';
+    else if (a === '--help' || a === '-h') out.help = true;
+    else {
+      console.error(`dep-audit: unknown arg "${a}"`);
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+function printHelp() {
+  console.error(`Usage: node scripts/security/dep-audit.js [--report-mode=ci|nightly]
+
+  --report-mode=ci         (default) exit non-zero on any high/critical finding
+  --report-mode=nightly    always exit 0; emit JSON for the nightly skill
+`);
+}
+
+// npm audit ---------------------------------------------------------------
+
+// npm audit emits a JSON document. `--audit-level=high` controls the EXIT CODE
+// only — the JSON still contains every level. We parse the full set, then we
+// filter to high+critical ourselves so the threshold is consistent across both
+// scanners.
+function runNpmAudit() {
+  const res = spawnSync('npm', ['audit', '--audit-level=high', '--json'], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  // npm audit exits 1 when findings >= the threshold, 0 otherwise. Both cases
+  // still produce JSON on stdout. We don't trust the exit code; we read the
+  // JSON and decide for ourselves.
+  if (res.error) {
+    return { ok: false, tool_missing: true, findings: [], raw_error: String(res.error.message || res.error) };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.stdout || '{}');
+  } catch (e) {
+    return {
+      ok: false, tool_missing: false, findings: [],
+      raw_error: `npm audit JSON parse failed: ${e.message}; stderr=${res.stderr.slice(0, 500)}`,
+    };
+  }
+  const findings = extractNpmFindings(parsed);
+  return { ok: true, tool_missing: false, findings };
+}
+
+// npm audit v7+ JSON shape: `vulnerabilities` is an object keyed by package
+// name; each entry has { severity, via, fixAvailable, name, ... }. `via` is
+// either a string (the upstream package whose advisory chains here) or an
+// array of advisory objects { source, name, dependency, title, url, severity,
+// cwe, cvss, range }. We only surface high+critical at the top level.
+function extractNpmFindings(parsed) {
+  const out = [];
+  const vulns = (parsed && parsed.vulnerabilities) || {};
+  for (const [pkg, entry] of Object.entries(vulns)) {
+    const sev = entry.severity;
+    if (sev !== 'high' && sev !== 'critical') continue;
+    // Pull the most informative advisory we can find.
+    let advisory = null;
+    const via = Array.isArray(entry.via) ? entry.via : [];
+    for (const v of via) {
+      if (v && typeof v === 'object' && (v.severity === 'high' || v.severity === 'critical')) {
+        advisory = v;
+        break;
+      }
+    }
+    out.push({
+      ecosystem: 'npm',
+      package: pkg,
+      severity: sev,
+      id: advisory ? (advisory.source || advisory.url || advisory.name) : null,
+      summary: advisory ? (advisory.title || advisory.name) : `${pkg} has a ${sev}-severity advisory`,
+      fix: entry.fixAvailable ? (
+        typeof entry.fixAvailable === 'object'
+          ? `${entry.fixAvailable.name}@${entry.fixAvailable.version}${entry.fixAvailable.isSemVerMajor ? ' (major bump)' : ''}`
+          : 'available'
+      ) : 'no fix available',
+      url: advisory ? advisory.url : null,
+    });
+  }
+  return out;
+}
+
+// pip-audit ---------------------------------------------------------------
+
+function runPipAudit() {
+  if (!fs.existsSync(PIP_REQUIREMENTS)) {
+    return {
+      ok: false, tool_missing: false, findings: [],
+      raw_error: `requirements file not found: ${PIP_REQUIREMENTS}`,
+    };
+  }
+  const res = spawnSync('python3', [
+    '-m', 'pip_audit',
+    '-r', PIP_REQUIREMENTS,
+    '--format', 'json',
+    '--vulnerability-service', 'pypi',
+  ], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  if (res.error) {
+    return { ok: false, tool_missing: true, findings: [], raw_error: String(res.error.message || res.error) };
+  }
+  if (res.status !== 0 && res.status !== 1) {
+    // pip-audit exits 0 on clean, 1 on findings. Anything else (missing module,
+    // bad requirements file) is a tool problem.
+    const stderr = (res.stderr || '').slice(0, 1000);
+    const missing = /No module named ['"]?pip_audit/.test(stderr);
+    return {
+      ok: false, tool_missing: missing, findings: [],
+      raw_error: `pip-audit exit=${res.status}; stderr=${stderr}`,
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.stdout || '{}');
+  } catch (e) {
+    return {
+      ok: false, tool_missing: false, findings: [],
+      raw_error: `pip-audit JSON parse failed: ${e.message}; stderr=${res.stderr.slice(0, 500)}`,
+    };
+  }
+  const findings = extractPipFindings(parsed);
+  return { ok: true, tool_missing: false, findings };
+}
+
+// pip-audit JSON shape: { "dependencies": [ { "name", "version",
+// "vulns": [ { "id", "fix_versions": [], "description", "aliases": [] } ] } ] }
+// pip-audit does NOT classify severity itself — PyPI/OSV advisories carry it
+// in `aliases` (CVE IDs) plus a `description` field. To stay conservative, we
+// treat EVERY pip-audit finding as high — by the time PyPI's advisory DB has
+// picked it up, the project's posture is "fix or document." This is the same
+// stance the GitHub `pip-audit-action` takes by default.
+function extractPipFindings(parsed) {
+  const out = [];
+  const deps = (parsed && parsed.dependencies) || [];
+  for (const dep of deps) {
+    const vulns = Array.isArray(dep.vulns) ? dep.vulns : [];
+    for (const v of vulns) {
+      out.push({
+        ecosystem: 'pypi',
+        package: dep.name,
+        version: dep.version,
+        severity: 'high', // see note above
+        id: v.id || (Array.isArray(v.aliases) && v.aliases[0]) || null,
+        summary: (v.description || '').split('\n')[0].slice(0, 240) || `${dep.name} ${dep.version}: ${v.id}`,
+        fix: Array.isArray(v.fix_versions) && v.fix_versions.length
+          ? `upgrade to ${v.fix_versions.join(' / ')}`
+          : 'no fix available',
+        url: v.id ? `https://osv.dev/vulnerability/${v.id}` : null,
+      });
+    }
+  }
+  return out;
+}
+
+// Main --------------------------------------------------------------------
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) { printHelp(); process.exit(2); }
+
+  const ranAt = new Date().toISOString();
+  const npm = runNpmAudit();
+  const pip = runPipAudit();
+
+  const allFindings = [...npm.findings, ...pip.findings];
+  const highCount = allFindings.filter(f => f.severity === 'high' || f.severity === 'critical').length;
+
+  // CI mode: a tool being entirely missing in a CI environment is a build
+  // problem, not a security problem — fail loudly so we don't ship blind.
+  const toolProblem = (npm.tool_missing || pip.tool_missing) && args.mode === 'ci';
+
+  let exitCode = 0;
+  if (toolProblem) exitCode = 2;
+  else if (args.mode === 'ci' && highCount > 0) exitCode = 1;
+  // nightly mode → always 0.
+
+  const report = {
+    ran_at: ranAt,
+    mode: args.mode,
+    npm,
+    pip,
+    high_or_critical_count: highCount,
+    findings: allFindings,
+    exit_code: exitCode,
+  };
+
+  // Human summary to stderr.
+  const lines = [];
+  lines.push(`dep-audit [${args.mode}] @ ${ranAt}`);
+  lines.push(`  npm:       ${npm.tool_missing ? 'TOOL MISSING' : (npm.ok ? `${npm.findings.length} high/critical` : `ERROR — ${npm.raw_error}`)}`);
+  lines.push(`  pip-audit: ${pip.tool_missing ? 'TOOL MISSING' : (pip.ok ? `${pip.findings.length} high/critical` : `ERROR — ${pip.raw_error}`)}`);
+  if (allFindings.length) {
+    lines.push(`  findings:`);
+    for (const f of allFindings) {
+      lines.push(`    - [${f.ecosystem}/${f.severity}] ${f.package}${f.version ? '@' + f.version : ''} — ${f.id || '(no id)'} — ${f.summary} (fix: ${f.fix})`);
+    }
+  }
+  lines.push(`  exit_code: ${exitCode}`);
+  process.stderr.write(lines.join('\n') + '\n');
+
+  // Machine-readable report to stdout.
+  process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  process.exit(exitCode);
+}
+
+if (require.main === module) main();
+
+// Exported for unit testing / for the nightly skill if it ever wants to drive
+// the scan in-process instead of via spawn.
+module.exports = { runNpmAudit, runPipAudit, extractNpmFindings, extractPipFindings };

package/scripts/setup-builder.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// setup-builder.js — one-command bootstrap for a new OTB builder (#673).
+//
+// The cross-platform port of setup-builder.sh: node is the project's guaranteed
+// runtime, so this runs identically on Windows, macOS, and Linux, whereas the
+// bash original could not run at all on a Windows box without Git Bash. The
+// bootstrap a new builder runs right after cloning:
+//
+//   node scripts/setup-builder.js
+//   node scripts/setup-builder.js --skip-keys   # don't prompt for API keys
+//   node scripts/setup-builder.js --no-auth      # skip the GDS Device Flow step
+//   node scripts/setup-builder.js --help
+//
+// Idempotent: safe to re-run; each step checks before acting and reports
+// "already done" rather than clobbering. What it does, in order:
+//   1. Verify Node >= 22 and Python >= 3.10 (the two required toolchains).
+//   2. `npm ci` to install JS dependencies.
+//   3. Copy .env.local.example -> .env.local (if absent) + optionally prompt
+//      for the Google AI Studio key (--skip-keys / non-TTY takes placeholders).
+//   4. `node scripts/gds/setup.js` — GitHub Device Flow auth (--no-auth skips).
+//   5. Print the "ready" banner pointing at /builder-start.
+//
+// Audience: a brand-new builder with nothing else configured. Every error
+// prints the exact remediation command to paste — no fishing.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const IS_WIN = process.platform === 'win32';
+
+// ---- arg parsing ----
+const argv = process.argv.slice(2);
+let SKIP_KEYS = false;
+let NO_AUTH = false;
+for (const a of argv) {
+  if (a === '--skip-keys') SKIP_KEYS = true;
+  else if (a === '--no-auth') NO_AUTH = true;
+  else if (a === '-h' || a === '--help') {
+    console.log(`setup-builder.js — one-command bootstrap for a new OTB builder.
+
+Usage:
+  node scripts/setup-builder.js
+  node scripts/setup-builder.js --skip-keys     # don't prompt for API keys
+  node scripts/setup-builder.js --no-auth       # skip the GDS Device Flow step
+  node scripts/setup-builder.js --help
+
+Runs: toolchain checks (Node>=22, Python>=3.10) -> npm ci -> .env.local -> GDS auth.`);
+    process.exit(0);
+  } else {
+    console.error(`Unknown argument: ${a}`);
+    console.error('Run with --help for usage.');
+    process.exit(2);
+  }
+}
+
+// ---- color helpers (no color when stdout isn't a TTY) ----
+const TTY = process.stdout.isTTY;
+const C = {
+  green: TTY ? '\x1b[32m' : '', red: TTY ? '\x1b[31m' : '',
+  dim: TTY ? '\x1b[2m' : '', bold: TTY ? '\x1b[1m' : '', reset: TTY ? '\x1b[0m' : '',
+};
+const ok = (m) => console.log(`  ${C.green}ok${C.reset}  ${m}`);
+const skip = (m) => console.log(`  ${C.dim}--${C.reset}  ${m}`);
+const fail = (m) => console.error(`  ${C.red}!!${C.reset} ${m}`);
+const step = (m) => { console.log(''); console.log(`${C.bold}${m}${C.reset}`); };
+
+// Run a command, inheriting stdio. `shell` is an EXPLICIT opt-in (default off)
+// and never spread from caller-supplied opts: shell:true on Windows runs the
+// args through cmd.exe expansion, so it's used ONLY for `npm` (a .cmd shim that
+// can't be spawned without a shell) and ONLY with hardcoded args — never with
+// anything caller- or user-controlled. Returns the exit status (null on spawn fail).
+function run(cmd, args, { shell = false } = {}) {
+  const r = spawnSync(cmd, args, {
+    cwd: REPO_ROOT, stdio: 'inherit', shell, windowsHide: true,
+  });
+  return r.status;
+}
+// Capture a command's output (stdout+stderr) without inheriting; null if it
+// can't spawn. No shell: node/python/py launchers are real executables that
+// spawnSync resolves directly on every OS (incl. .exe on Windows), so there's
+// no cmd.exe expansion surface here at all.
+function capture(cmd, args) {
+  const r = spawnSync(cmd, args, { cwd: REPO_ROOT, encoding: 'utf8', windowsHide: true });
+  if (r.error) return null;
+  return `${r.stdout || ''}${r.stderr || ''}`.trim();
+}
+
+// ---------------------------------------------------------------------------
+// 1. Toolchain checks
+// ---------------------------------------------------------------------------
+function checkToolchain() {
+  step('1/5  Checking toolchain');
+
+  // Node >= 22 — we're running in node, so just inspect the running version.
+  const nodeMajor = Number((process.versions.node || '0').split('.')[0]);
+  if (!Number.isFinite(nodeMajor) || nodeMajor < 22) {
+    fail(`Node ${process.version} found, but >= 22 is required.`);
+    console.error('');
+    console.error('  Upgrade with:');
+    console.error('    brew install node@22 && brew link --overwrite --force node@22   (macOS)');
+    console.error('    nvm install 22 && nvm use 22                                    (nvm, any OS)');
+    console.error('    or download from https://nodejs.org/                            (Windows/Linux)');
+    process.exit(1);
+  }
+  ok(`Node ${process.version} (>= 22)`);
+
+  // Python >= 3.10. Candidate launchers differ by OS: `py` is the Windows
+  // launcher; python3/python cover macOS/Linux (and some Windows installs).
+  const candidates = IS_WIN ? ['py', 'python', 'python3'] : ['python3', 'python'];
+  let pyVer = null;
+  let pyCmd = null;
+  for (const c of candidates) {
+    const out = capture(c, ['--version']);
+    const m = out && /Python\s+(\d+)\.(\d+)/.exec(out);
+    if (m) { pyCmd = c; pyVer = { major: Number(m[1]), minor: Number(m[2]), raw: `${m[1]}.${m[2]}` }; break; }
+  }
+  if (!pyVer) {
+    fail('Python is not installed (or not on PATH).');
+    console.error('');
+    console.error('  Install it with:');
+    console.error('    brew install python@3.11                       (macOS)');
+    console.error('    or download from https://www.python.org/downloads/  (Windows/Linux — tick "Add to PATH")');
+    process.exit(1);
+  }
+  if (pyVer.major < 3 || (pyVer.major === 3 && pyVer.minor < 10)) {
+    fail(`Python ${pyVer.raw} found, but >= 3.10 is required.`);
+    console.error('');
+    console.error('  Upgrade with:');
+    console.error('    brew install python@3.11           (macOS)');
+    console.error('    pyenv install 3.11 && pyenv global 3.11   (pyenv, any OS)');
+    process.exit(1);
+  }
+  ok(`Python ${pyVer.raw} (>= 3.10) [${pyCmd}]`);
+}
+
+// ---------------------------------------------------------------------------
+// 2. npm ci
+// ---------------------------------------------------------------------------
+function npmCi() {
+  step('2/5  Installing JS dependencies (npm ci)');
+  if (!fs.existsSync(path.join(REPO_ROOT, 'package-lock.json'))) {
+    fail('package-lock.json missing — refusing to run npm ci.');
+    console.error("  Run 'npm install' once to generate a lockfile, then re-run setup.");
+    process.exit(1);
+  }
+  // npm is `npm.cmd` on Windows — it can't be spawned without a shell, so this
+  // is the one shell:true call; args are hardcoded (no injection surface).
+  const status = run('npm', ['ci', '--no-audit', '--no-fund'], { shell: IS_WIN });
+  if (status === 0) {
+    ok('Dependencies installed');
+  } else {
+    fail('npm ci failed. Common fixes:');
+    console.error('    rm -rf node_modules && npm ci    (delete node_modules then retry)');
+    console.error('    or check your network / proxy settings');
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 3. .env.local
+// ---------------------------------------------------------------------------
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(answer); });
+  });
+}
+
+async function envLocal() {
+  step('3/5  Local environment (.env.local)');
+  const example = path.join(REPO_ROOT, '.env.local.example');
+  const target = path.join(REPO_ROOT, '.env.local');
+  if (!fs.existsSync(example)) {
+    fail('.env.local.example is missing from this checkout.');
+    console.error('  Pull the latest main, or restore: git checkout main -- .env.local.example');
+    process.exit(1);
+  }
+  if (fs.existsSync(target)) {
+    ok('.env.local already exists — leaving it alone');
+    skip('to start over, back it up and re-run:  mv .env.local .env.local.bak && node scripts/setup-builder.js');
+    return;
+  }
+  fs.copyFileSync(example, target);
+  ok('Created .env.local from .env.local.example');
+
+  // Prompt for the Google AI Studio key only with a TTY and without --skip-keys.
+  // An empty value is not fatal — the pipeline also resolves the key from
+  // ~/.config/otb/env, so it just means art-pipeline calls raise the standard
+  // "GOOGLE_AI_STUDIO_KEY not found" error until set.
+  if (SKIP_KEYS) {
+    skip('--skip-keys set; leaving GOOGLE_AI_STUDIO_KEY blank in .env.local');
+    skip('you can edit .env.local later, or set it in ~/.config/otb/env');
+    return;
+  }
+  if (!process.stdin.isTTY) {
+    skip('no TTY; leaving GOOGLE_AI_STUDIO_KEY blank in .env.local');
+    return;
+  }
+  console.log('');
+  console.log(`  ${C.dim}Google AI Studio key for the pixel-art pipeline.`);
+  console.log('  Get one at https://aistudio.google.com/app/apikey .');
+  console.log(`  Press Enter to skip — you can always edit .env.local later.${C.reset}`);
+  // Strip CR/LF so a pasted value with a stray newline can't inject extra
+  // lines into the builder's .env.local; trim handles surrounding whitespace.
+  const input = (await ask('  GOOGLE_AI_STUDIO_KEY: ')).replace(/[\r\n]+/g, '').trim();
+  if (input) {
+    const contents = fs.readFileSync(target, 'utf8');
+    // Function replacement (not a string): String.replace treats $&, $1, $$ etc.
+    // in a replacement STRING as special, which would silently corrupt a key
+    // containing a bare `$`. A function return value is spliced verbatim.
+    const next = contents.replace(/^GOOGLE_AI_STUDIO_KEY=.*$/m, () => `GOOGLE_AI_STUDIO_KEY=${input}`);
+    fs.writeFileSync(target, next);
+    ok('Saved GOOGLE_AI_STUDIO_KEY to .env.local');
+  } else {
+    skip('left GOOGLE_AI_STUDIO_KEY blank — edit .env.local when you have one');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 4. GitHub Device Flow auth
+// ---------------------------------------------------------------------------
+function gdsAuth() {
+  step('4/5  GDS session (GitHub Device Flow)');
+  if (NO_AUTH) {
+    skip('--no-auth set; skipping GDS Device Flow');
+    console.log('    Authenticate on first connect with:  node scripts/gds/setup.js   (or /builder-setup)');
+    return;
+  }
+  // setup.js is idempotent (pre-flights GET /me, short-circuits if still valid).
+  // process.execPath (not bare 'node') resolves on Windows cmd.exe regardless of PATH.
+  console.log('  Handing off to scripts/gds/setup.js ...');
+  console.log('');
+  const setupArgs = [path.join(REPO_ROOT, 'scripts', 'gds', 'setup.js')];
+  if (SKIP_KEYS) setupArgs.push('--skip-keys');
+  const status = run(process.execPath, setupArgs); // shell defaults off
+  if (status === 0) {
+    ok('GDS session ready');
+  } else {
+    fail(`scripts/gds/setup.js exited with status ${status}`);
+    console.error('  Re-run just this step with:  node scripts/gds/setup.js --force');
+    console.error('  Or run the doctor:           node scripts/gds/doctor.js');
+    process.exit(status || 1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 5. Ready banner
+// ---------------------------------------------------------------------------
+function banner() {
+  step('5/5  Done');
+  console.log('');
+  console.log(`  ${C.green}${C.bold}You're ready.${C.reset}`);
+  console.log('');
+  console.log(`  Next step: open Claude Code and run  ${C.bold}/builder-start${C.reset}`);
+  console.log('  to see what tasks you can claim.');
+  console.log('');
+  console.log(`  ${C.dim}Project memory lives in CLAUDE.md — read it before editing code.${C.reset}`);
+  console.log('');
+}
+
+(async () => {
+  checkToolchain();
+  npmCi();
+  await envLocal();
+  gdsAuth();
+  banner();
+  process.exit(0);
+})().catch((err) => {
+  fail(`setup-builder: unexpected error: ${err && err.message ? err.message : err}`);
+  process.exit(1);
+});

package/scripts/setup-builder.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# setup-builder.sh — thin compatibility shim (#673).
+#
+# The bootstrap logic now lives in scripts/setup-builder.js (Node), so it runs
+# on Windows/macOS/Linux alike. This shim stays so existing references keep
+# working on Mac/Linux — README, the onboarding primer, and the devcontainer's
+# post-create.sh all invoke `./scripts/setup-builder.sh` / `bash scripts/
+# setup-builder.sh ...`. It simply forwards all arguments to the Node script.
+#
+# On Windows (no Git Bash), run the Node entry directly instead:
+#   node scripts/setup-builder.js [--skip-keys] [--no-auth] [--help]
+#
+# Usage (Mac/Linux):
+#   ./scripts/setup-builder.sh [--skip-keys] [--no-auth] [--help]
+#
+# Run this from INSIDE a clone of the repo. If you don't have the code yet,
+# do "Step 0 — get the project onto your machine" first (see README.md):
+#   git clone https://github.com/lars589/amazonprimea.git && cd amazonprimea
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Guard: this shim must run from inside the repo (where setup-builder.js lives).
+if [ ! -f "$SCRIPT_DIR/setup-builder.js" ]; then
+  echo "setup-builder: can't find setup-builder.js next to this script." >&2
+  echo "Did you clone the repo and cd into it? See README.md 'Step 0 — get the project onto your machine'." >&2
+  echo "  git clone https://github.com/lars589/amazonprimea.git && cd amazonprimea" >&2
+  exit 1
+fi
+exec node "$SCRIPT_DIR/setup-builder.js" "$@"