@bongos/core 1.17.0

package/scripts/gds/upgrade.js

@@ -0,0 +1,421 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/upgrade.js — the `bongos upgrade` update-consumption channel (ADR 0100 §2, task 1690).
+//
+// Turns the former stub (which only ran a module-vs-core compatibility PRE-CHECK) into the real
+// channel a two-repo consumer uses to pull the Cloud Bongos core from version N to N+1:
+//
+//   pre-flight   clean git tree + module-compat vs the TARGET core version
+//     → bump pin   vendor the new core .tgz, rewrite the package.json `file:` dependency
+//     → npm install  node_modules/@cloudbongos/core becomes the new version
+//     → migrate      `npm run migrate` → the core's migrate.sh applies additive `core_*` migrations
+//     → materialize  refresh .claude/ skills+settings+hooks from the new core (claude-materialize / W3)
+//     → restart      restart the instance's service so the new core is live
+//     → verify       installed package version == target (+ optional /healthz + ledger row)
+//
+// SCOPE (ADR 0100 §2, reshaped by ADR 0103 §4): the SMALLEST channel the FIRST real consumer needs
+// on its first core bump — driven by that consumer, not designed up front. That consumer is
+// emersonian-circles (task 1917): a greenfield npm-dependency instance that pins the core as
+//   "@cloudbongos/core": "file:vendor/cloudbongos-core-<ver>.tgz"
+// with `start`/`migrate` npm scripts and a materialized .claude/. Every step below maps to something
+// that consumer actually has. A published-registry source, rollback, and multi-consumer shapes are
+// deliberately OUT — they are follow-ups a second consumer's needs will define.
+//
+// Runs from the consumer instance root (default) or `--instance <dir>`. This script ships IN the core
+// package, so once a consumer is on core vN+1 its own `bongos upgrade` is this code. The FIRST bump
+// (before vN+1 is installed) is driven by running THIS file out of the new version's staged tree
+// against `--instance <consumer>` — see docs/recipes for the bootstrap note.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { arg, hasFlag } = require('./cli-lib');
+
+const CORE_PKG = '@cloudbongos/core';
+const ARTIFACT = 'cloudbongos-core';
+
+// ---- pure helpers (no I/O side effects beyond the injected fs) --------------
+
+// The pin a consumer carries is the vendored-tarball version in its `file:` dependency — there is no
+// separate pin file for this consumer shape. Extract the version from either the dep string or the
+// installed package.
+function versionFromTgzPath(p) {
+  const m = String(p || '').match(new RegExp(`${ARTIFACT}-(\\d+\\.\\d+\\.\\d+[^/]*)\\.tgz$`));
+  return m ? m[1] : null;
+}
+
+function readJson(file, fsImpl = fs) {
+  try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// The version currently installed under node_modules — the authoritative "from".
+function readInstalledCoreVersion(instanceDir, fsImpl = fs) {
+  const pkg = readJson(path.join(instanceDir, 'node_modules', CORE_PKG, 'package.json'), fsImpl);
+  return pkg && pkg.version ? pkg.version : null;
+}
+
+// The version the consumer's package.json currently pins (from the `file:` tarball path).
+function readPinnedCoreVersion(instanceDir, fsImpl = fs) {
+  const pkg = readJson(path.join(instanceDir, 'package.json'), fsImpl);
+  const dep = pkg && ((pkg.dependencies || {})[CORE_PKG] || (pkg.devDependencies || {})[CORE_PKG]);
+  return versionFromTgzPath(dep);
+}
+
+// Rewrite the consumer package.json to pin `file:<vendorRel>`. Returns the previous dep string.
+function writePin(instanceDir, vendorRel, fsImpl = fs) {
+  const pkgPath = path.join(instanceDir, 'package.json');
+  const pkg = readJson(pkgPath, fsImpl);
+  if (!pkg) throw new Error(`no readable package.json at ${pkgPath}`);
+  pkg.dependencies = pkg.dependencies || {};
+  const prev = pkg.dependencies[CORE_PKG];
+  pkg.dependencies[CORE_PKG] = `file:${vendorRel}`;
+  fsImpl.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  return prev;
+}
+
+// ---- steps (each injectable for tests) --------------------------------------
+
+function gitTreeClean(instanceDir, run = spawnSync) {
+  const r = run('git', ['status', '--porcelain'], { cwd: instanceDir, encoding: 'utf8' });
+  if (!r || r.error || r.status !== 0) return { ok: false, reason: 'git status failed (not a git repo?)' };
+  const dirty = (r.stdout || '').trim();
+  return { ok: dirty === '', dirty };
+}
+
+// Copy the source .tgz (+ its side-car manifest, if present) into the consumer's vendor/ dir under the
+// canonical name. Returns the vendor-relative tarball path to pin.
+function vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs) {
+  const vendorDir = path.join(instanceDir, 'vendor');
+  fsImpl.mkdirSync(vendorDir, { recursive: true });
+  const destName = `${ARTIFACT}-${targetVersion}.tgz`;
+  const destAbs = path.join(vendorDir, destName);
+  fsImpl.copyFileSync(fromTgz, destAbs);
+  const fromManifest = fromTgz.replace(/\.tgz$/, '.manifest.json');
+  if (fsImpl.existsSync(fromManifest)) {
+    fsImpl.copyFileSync(fromManifest, path.join(vendorDir, `${ARTIFACT}-${targetVersion}.manifest.json`));
+  }
+  return path.join('vendor', destName);
+}
+
+// Lightweight module-compat pre-check reusing module.js against the TARGET core version. Best-effort:
+// a vanilla consumer has no modules/ (trivially OK); any failure downgrades to a warning, never blocks
+// the MVP bump. Returns { ok, blocking:[], note }.
+function preflightModules({ instanceDir, targetVersion }, deps = {}) {
+  const modulesDir = path.join(instanceDir, 'modules');
+  if (!fs.existsSync(modulesDir)) return { ok: true, blocking: [], note: 'no modules/ — nothing to pre-check' };
+  try {
+    const mod = deps.moduleLib || require('./module');
+    const data = mod.gatherUpgrade({ modulesDir, core: targetVersion });
+    const verdict = mod.evaluateUpgrade(data);
+    return { ok: verdict.ok, blocking: verdict.blocking || [], note: verdict.ok ? 'all enabled modules satisfy the target' : 'incompatible enabled module(s)' };
+  } catch (e) {
+    return { ok: true, blocking: [], note: `module pre-check skipped (${e.message})` };
+  }
+}
+
+function npmInstall(instanceDir, run = spawnSync) {
+  // `npm install` (NOT `npm ci`): the pin just changed, so the lockfile must be regenerated from the
+  // new tarball; `npm ci` would refuse on the package.json↔lock divergence.
+  const r = run('npm', ['install', '--no-audit', '--no-fund'], { cwd: instanceDir, stdio: 'inherit' });
+  return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
+}
+
+function runMigrate(instanceDir, run = spawnSync) {
+  const r = run('npm', ['run', 'migrate'], { cwd: instanceDir, stdio: 'inherit' });
+  return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
+}
+
+// Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
+// client) from the NEW core's routes — the claude-materialize sibling (task 2051).
+// WHY: the routes + generators ship WITH core, but the generated spec/docs/client are
+// EXCLUDED from the package (per-instance artifacts), so a bump changes the served API
+// while the instance's committed spec/client lag until the next ship's fitness gate.
+// This closes that gap on upgrade. We SPAWN the new core's generators (a fresh child
+// captures its output root from the env below) with <FALLBACK_PREFIX>_INSTANCE_ROOT set
+// so resolveDocsRoot() writes INTO the instance repo, not node_modules. docs first — the
+// client reads the spec it produces. Best-effort: a hiccup warns, never fails the bump
+// (fitness `gen-api-docs --check` + the api_client test backstop it on the next ship).
+// Runs AFTER npm install so the generators come from the NEW core.
+function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsImpl = fs) {
+  const env = { ...process.env, CLOUDBONGOS_INSTANCE_ROOT: instanceDir };
+  const ran = [];
+  for (const gen of ['gen-api-docs.js', 'gen-api-client.js']) {
+    const script = path.join(coreRoot, 'scripts', 'gds', gen);
+    if (!fsImpl.existsSync(script)) return { ok: false, ran, reason: `${gen} not found in core (${coreRoot})` };
+    const r = run(process.execPath, [script], { cwd: instanceDir, env, stdio: 'inherit' });
+    if (!r || r.error || r.status !== 0) {
+      return { ok: false, ran, reason: r && r.error ? r.error.message : `${gen} exited ${r && r.status}` };
+    }
+    ran.push(gen);
+  }
+  return { ok: true, ran };
+}
+
+function restartService({ service, restartCmd }, run = spawnSync) {
+  if (restartCmd) {
+    const parts = restartCmd.split(/\s+/);
+    const r = run(parts[0], parts.slice(1), { stdio: 'inherit' });
+    return { ok: !!r && !r.error && r.status === 0, code: r && r.status };
+  }
+  if (service) {
+    const r = run('systemctl', ['restart', service], { stdio: 'inherit' });
+    return { ok: !!r && !r.error && r.status === 0, code: r && r.status };
+  }
+  return { ok: null, skipped: true };
+}
+
+const LEDGER_INSERT_COLS = 'INSERT INTO core_upgrades (from_version, to_version, source_commit, note)';
+
+// Best-effort append to the core_upgrades ledger (migration core_189). Resolves the DB the same two
+// ways a consumer might connect:
+//   • DATABASE_URL — a connection string (managed / hosted shape): via the pg driver.
+//   • PGDATABASE   — a bare db name over the unix socket + peer auth (the self-host shape): by
+//     delegating to `psql -d "$PGDATABASE"`, EXACTLY as migrate.sh does. We shell out rather than
+//     reuse pg here because pg defaults host to localhost/TCP, so `new Pool({database})` would miss
+//     the socket + peer auth a provisioned instance relies on (systemd sets only PGDATABASE — task
+//     1976 found the URL-only path silently skipped on emersonian, the very shape it must serve).
+// Skips silently only when NEITHER is present (a local rehearsal with no DB pointed at) — the bump's
+// verification never depends on the ledger. An attempted-but-failed insert returns skipped:false so
+// the caller can surface it (the manual-INSERT footgun from 1976), never lose it.
+async function recordLedger({ fromVersion, toVersion, sourceCommit, note }, deps = {}) {
+  const url = deps.databaseUrl !== undefined ? deps.databaseUrl : process.env.DATABASE_URL;
+  const database = deps.pgDatabase !== undefined ? deps.pgDatabase : process.env.PGDATABASE;
+  if (!url && !database) return { ok: false, skipped: true, reason: 'no DATABASE_URL or PGDATABASE' };
+
+  // DATABASE_URL path: the pg driver with a bound-parameter query (no psql client needed).
+  if (url) {
+    let Pool;
+    try { ({ Pool } = deps.pg || require('pg')); } catch { return { ok: false, skipped: true, reason: 'pg not resolvable' }; }
+    const pool = new Pool({ connectionString: url });
+    try {
+      await pool.query(
+        `${LEDGER_INSERT_COLS} VALUES ($1,$2,$3,$4)`,
+        [fromVersion || null, toVersion, sourceCommit || null, note || null]
+      );
+      return { ok: true };
+    } catch (e) {
+      return { ok: false, skipped: false, reason: e.message };
+    } finally {
+      try { await pool.end(); } catch { /* ignore */ }
+    }
+  }
+
+  // PGDATABASE path: `psql -d <db>` lets libpq resolve the socket + peer auth (same as migrate.sh).
+  // Values pass as separate argv `--set`s (no shell → no shell injection) and reach the SQL as psql
+  // :'var' literals, which psql quotes/escapes safely (no SQL injection). NULLIF maps an absent value
+  // to NULL, matching the `x || null` of the pg path. The SQL is fed on STDIN, not `-c`: `-c` requires
+  // pure server-parseable SQL and does NOT run :'var' interpolation, so a `-c` INSERT would send the
+  // literal `:'from_version'` and syntax-error — psql only interpolates variables in script/stdin
+  // mode. ON_ERROR_STOP=1 guarantees a non-zero exit on any SQL error.
+  const run = deps.run || spawnSync;
+  const sql = `${LEDGER_INSERT_COLS}\n  VALUES (NULLIF(:'from_version',''), :'to_version', NULLIF(:'source_commit',''), NULLIF(:'note',''));\n`;
+  const r = run('psql', [
+    '-d', database,
+    '-v', 'ON_ERROR_STOP=1',
+    '-q', '--no-psqlrc',
+    '--set', `from_version=${fromVersion || ''}`,
+    '--set', `to_version=${toVersion || ''}`,
+    '--set', `source_commit=${sourceCommit || ''}`,
+    '--set', `note=${note || ''}`,
+  ], { encoding: 'utf8', input: sql });
+  if (!r || r.error) {
+    const enoent = !!(r && r.error && r.error.code === 'ENOENT');
+    return { ok: false, skipped: enoent, reason: enoent ? 'psql not found' : (r && r.error ? r.error.message : 'psql spawn failed') };
+  }
+  if (r.status !== 0) return { ok: false, skipped: false, reason: (r.stderr || '').trim() || `psql exit ${r.status}` };
+  return { ok: true };
+}
+
+// Poll a health URL until it returns 2xx or the time budget (~30s) elapses. After `systemctl restart`
+// the service needs a moment to bind its port, so a single immediate GET races the restart and
+// spuriously reports `fetch failed` (task 1976 — it bound ~1s later on the emersonian 1.15→1.16 bump).
+// Connection-refused fails fast, so the early retries are cheap; the backoff caps at 2s.
+async function pollHealth(healthUrl, deps = {}) {
+  const fetchImpl = deps.fetch || fetch;
+  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = deps.now || Date.now;
+  const budgetMs = deps.healthBudgetMs != null ? deps.healthBudgetMs : 30_000;
+  const deadline = now() + budgetMs;
+  let attempt = 0;
+  let last = { ok: false, error: 'not attempted' };
+  for (;;) {
+    attempt++;
+    try {
+      const res = await fetchImpl(healthUrl, { signal: AbortSignal.timeout(5_000) });
+      if (res.ok) return { ok: true, status: res.status, attempts: attempt };
+      last = { ok: false, status: res.status };
+    } catch (e) {
+      last = { ok: false, error: e.message };
+    }
+    if (now() >= deadline) return { ...last, attempts: attempt, timedOut: true };
+    await sleep(Math.min(2_000, 500 * attempt));
+  }
+}
+
+// ---- orchestration ----------------------------------------------------------
+
+async function runUpgrade(opts, deps = {}) {
+  const log = deps.log || console.log;
+  const err = deps.err || console.error;
+  const run = deps.run || spawnSync;
+  const fsImpl = deps.fs || fs;
+  const materialize = deps.materialize || require('./claude-materialize').materializeClaude;
+
+  const instanceDir = path.resolve(opts.instance || process.cwd());
+  const targetVersion = opts.to;
+  const dryRun = !!opts.dryRun;
+  if (!targetVersion) return { ok: false, error: 'missing --to <version> (the target core version)' };
+
+  const fromVersion = readInstalledCoreVersion(instanceDir, fsImpl) || readPinnedCoreVersion(instanceDir, fsImpl);
+  log(`bongos upgrade — ${CORE_PKG}: ${fromVersion || '(none)'} → ${targetVersion}`);
+  log(`  instance: ${instanceDir}${dryRun ? '   [DRY RUN — no changes]' : ''}`);
+  if (fromVersion === targetVersion && !opts.force) {
+    return { ok: false, error: `already on ${targetVersion} (pass --force to re-run the steps anyway)`, fromVersion };
+  }
+
+  // 1. pre-flight: clean tree (so the pin change is reviewable + revertable) + module compatibility.
+  if (!opts.force) {
+    const tree = gitTreeClean(instanceDir, run);
+    if (!tree.ok) return { ok: false, error: `working tree not clean — commit/stash first, or pass --force.\n${tree.dirty || tree.reason || ''}` };
+  }
+  const mods = preflightModules({ instanceDir, targetVersion }, deps);
+  log(`  ✓ pre-flight: ${mods.note}`);
+  if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
+
+  // 2. bump the pin (vendor the tarball + rewrite the file: dep).
+  let vendorRel = opts.pinPath || (opts.from ? null : path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`));
+  if (opts.from) {
+    if (!fsImpl.existsSync(opts.from)) return { ok: false, error: `--from tarball not found: ${opts.from}` };
+    if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`); }
+    else vendorRel = vendorTarball({ instanceDir, fromTgz: path.resolve(opts.from), targetVersion }, fsImpl);
+  }
+  if (!fsImpl.existsSync(path.join(instanceDir, vendorRel)) && !dryRun) {
+    return { ok: false, error: `no core tarball at ${vendorRel} — pass --from <path-to-.tgz> to vendor it` };
+  }
+  const prevPin = dryRun ? null : writePin(instanceDir, vendorRel, fsImpl);
+  log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → file:${vendorRel}${prevPin ? `  (was ${prevPin})` : ''}`);
+
+  if (dryRun) { log('  [dry-run] would: npm install → npm run migrate → materialize .claude → regen API docs+client → restart → verify'); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
+
+  // 3. npm install.
+  const inst = npmInstall(instanceDir, run);
+  if (!inst.ok) return { ok: false, error: `npm install failed (${inst.reason || 'exit ' + inst.code})`, fromVersion };
+  log('  ✓ npm install');
+
+  // 4. migrate (additive core_* migrations).
+  if (!opts.skipMigrate) {
+    const mig = runMigrate(instanceDir, run);
+    if (!mig.ok) return { ok: false, error: `migrate failed (${mig.reason || 'exit ' + mig.code})`, fromVersion };
+    log('  ✓ migrate');
+  } else log('  • migrate skipped (--skip-migrate)');
+
+  // 5. materialize .claude/ from the freshly-installed core.
+  if (!opts.skipMaterialize) {
+    const coreRoot = path.join(instanceDir, 'node_modules', CORE_PKG);
+    const sum = materialize({ coreRoot, instanceDir, log: (m) => log(m) });
+    log(`  ✓ materialized .claude/ (${sum.skills} skill file(s)${sum.settings ? ', settings.json' : ''}${sum.hooks ? `, ${sum.hooks} hook(s)` : ''})`);
+  } else log('  • materialize skipped (--skip-materialize)');
+
+  // 5b. regenerate the per-instance API artifacts (OpenAPI spec + typed client) from the
+  // new core's routes — the claude-materialize sibling (task 2051). Best-effort: a regen
+  // hiccup is a warning, not a failed bump (the next ship's fitness gate refreshes them).
+  if (!opts.skipRegenDocs) {
+    const coreRoot = path.join(instanceDir, 'node_modules', CORE_PKG);
+    const regen = (deps.regenerateApiArtifacts || regenerateApiArtifacts)({ instanceDir, coreRoot }, run);
+    if (regen.ok) log(`  ✓ regenerated API docs + typed client from core ${targetVersion}`);
+    else err(`  ! API-artifact regen incomplete (${regen.reason}) — ran ${regen.ran.join(', ') || 'nothing'}; the next ship's fitness gate refreshes them.`);
+  } else log('  • API-artifact regen skipped (--skip-regen-docs)');
+
+  // 6. restart.
+  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run);
+  if (rs.skipped) log(`  • restart: no --service/--restart-cmd — restart the instance service to load core ${targetVersion}.`);
+  else if (!rs.ok) err(`  ! restart command failed (exit ${rs.code}) — restart the service manually.`);
+  else log(`  ✓ restarted ${opts.service || 'service'}`);
+
+  // 7. verify: installed version == target, optional /healthz, ledger row.
+  const installed = readInstalledCoreVersion(instanceDir, fsImpl);
+  const versionOk = installed === targetVersion;
+  log(`  ${versionOk ? '✓' : '!'} installed core version: ${installed || '(unknown)'}${versionOk ? '' : ` (expected ${targetVersion})`}`);
+
+  let healthOk = null;
+  if (opts.healthUrl) {
+    const h = await pollHealth(opts.healthUrl, deps);
+    healthOk = h.ok;
+    if (h.ok) log(`  ✓ health ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (ready after ${h.attempts} tries)` : ''}`);
+    else err(`  ! health ${opts.healthUrl} not ready after ${h.attempts} tr${h.attempts === 1 ? 'y' : 'ies'}: ${h.error || 'status ' + h.status}`);
+  }
+
+  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: opts.note }, deps);
+  if (ledger.ok) log('  ✓ recorded in core_upgrades ledger');
+  else if (ledger.skipped) log(`  • ledger skipped (${ledger.reason})`);
+  else err(`  ! ledger insert failed (${ledger.reason}) — record it manually`);
+
+  const ok = versionOk && healthOk !== false;
+  log(ok ? `\n✓ upgrade complete — core ${fromVersion || '(none)'} → ${targetVersion}` : `\n! upgrade finished with warnings — review above.`);
+  return { ok, fromVersion, toVersion: targetVersion, versionOk, healthOk, ledger: ledger.ok };
+}
+
+function parseArgs(argv) {
+  return {
+    to: arg('--to', argv),
+    from: arg('--from', argv),
+    instance: arg('--instance', argv),
+    service: arg('--service', argv),
+    restartCmd: arg('--restart-cmd', argv),
+    healthUrl: arg('--health-url', argv),
+    sourceCommit: arg('--source-commit', argv),
+    note: arg('--note', argv),
+    pinPath: arg('--pin-path', argv),
+    dryRun: hasFlag('--dry-run', argv),
+    force: hasFlag('--force', argv),
+    skipMigrate: hasFlag('--skip-migrate', argv),
+    skipMaterialize: hasFlag('--skip-materialize', argv),
+    skipRegenDocs: hasFlag('--skip-regen-docs', argv),
+  };
+}
+
+async function main(argv = process.argv.slice(2)) {
+  if (hasFlag('--help', argv) || argv[0] === 'help') {
+    process.stdout.write([
+      'bongos upgrade — pull the Cloud Bongos core to a new version and apply it.',
+      '',
+      'Usage:',
+      '  bongos upgrade                         module-compat pre-check against the installed core (exit 1 on mismatch)',
+      '  bongos upgrade --to <version> [opts]   pull + apply a new core version (the real channel)',
+      '',
+      '  --to <version>       target core version — presence switches from pre-check to a real bump',
+      '  --from <tgz>         source tarball to vendor into vendor/ (else it must already be there)',
+      '  --instance <dir>     consumer instance root (default: cwd)',
+      '  --service <unit>     systemd unit to restart after applying',
+      '  --restart-cmd <cmd>  explicit restart command (overrides --service)',
+      '  --health-url <url>   poll after restart (~30s) until 2xx; still-failing is a warning',
+      '  --skip-migrate       do not run `npm run migrate`',
+      '  --skip-materialize   do not refresh .claude/',
+      '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
+      '  --dry-run            show the plan; change nothing',
+      '  --force              skip the clean-tree + same-version guards',
+      '',
+      'Full bump: pre-flight → bump pin → npm install → migrate → materialize .claude → regen API docs+client → restart → verify.',
+    ].join('\n') + '\n');
+    return 0;
+  }
+  // Backward-compatible: bare `bongos upgrade` (no --to) is the documented module-compatibility
+  // PRE-CHECK — unchanged behavior, delegated to the module CLI. A --to switches to the real channel.
+  if (!arg('--to', argv)) {
+    return require('./module').cmdUpgrade(argv);
+  }
+  const res = await runUpgrade(parseArgs(argv));
+  if (!res.ok) { process.stderr.write(`\n✖ ${res.error || 'upgrade failed'}\n`); return 1; }
+  return 0;
+}
+
+module.exports = {
+  runUpgrade, parseArgs, main,
+  versionFromTgzPath, readInstalledCoreVersion, readPinnedCoreVersion, writePin,
+  vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, restartService, recordLedger, pollHealth,
+  CORE_PKG, ARTIFACT,
+};
+
+if (require.main === module) {
+  main().then((code) => process.exit(code)).catch((e) => { process.stderr.write(`✖ ${e.message}\n`); process.exit(1); });
+}

package/scripts/gds/validate-design.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+'use strict';
+// validate-design.js — minimal validator for the neutral design contract (task 1377).
+// See docs/design-contract.md §6 for the full spec.
+//
+// Usage:
+//   node scripts/gds/validate-design.js           # exits 0 on pass, 1 on failure
+//   node scripts/gds/validate-design.js --json    # machine-readable { ok, errors, warnings }
+//   node scripts/gds/validate-design.js --strict  # treat warnings as errors
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_MODE = ARGS.has('--json');
+const STRICT = ARGS.has('--strict');
+
+const NEUTRAL_TOKENS  = path.join(REPO_ROOT, 'config', 'design-tokens.neutral.json');
+const INSTANCE_TOKENS = path.join(REPO_ROOT, 'config', 'design-tokens.json');
+const TOKENS_SCHEMA   = path.join(REPO_ROOT, 'config', 'design-tokens.schema.json');
+const DESIGN_SOURCES  = path.join(REPO_ROOT, 'config', 'design-sources.json');
+const UI_SRC          = path.join(REPO_ROOT, 'src', 'ui');
+const UI_ASSETS       = path.join(REPO_ROOT, 'assets', 'ui');
+const ADAPTERS_DIR    = path.join(REPO_ROOT, 'src', 'ui', 'adapters');
+
+const TOOL_ENUM = new Set(['claude-design', 'figma', 'hand', 'asset']);
+const REQUIRED_COLORS = ['bg', 'bgCard', 'ink', 'accent'];
+const REQUIRED_FONTS  = ['display', 'body'];
+
+const errors   = [];
+const warnings = [];
+
+function err(msg)  { errors.push(msg); }
+function warn(msg) { warnings.push(msg); }
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    err(`${label}: cannot read/parse — ${e.message}`);
+    return null;
+  }
+}
+
+function deepMerge(base, override) {
+  if (!override) return base;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(override)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && typeof out[k] === 'object') {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function isUri(s) {
+  try { new URL(s); return true; } catch { return false; }
+}
+
+function dirExists(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function fileExists(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function listDirs(p) {
+  if (!dirExists(p)) return [];
+  return fs.readdirSync(p, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name);
+}
+
+// ── Check 1: neutral tokens file exists + parses ─────────────────────────────
+
+const schema   = readJson(TOKENS_SCHEMA, 'config/design-tokens.schema.json');
+const neutral  = readJson(NEUTRAL_TOKENS, 'config/design-tokens.neutral.json');
+
+if (!neutral) {
+  err('config/design-tokens.neutral.json is missing — this is the required baseline');
+}
+
+// ── Check 2: instance tokens file, if present, parses ────────────────────────
+
+let instance = null;
+if (fileExists(INSTANCE_TOKENS)) {
+  instance = readJson(INSTANCE_TOKENS, 'config/design-tokens.json');
+}
+
+// ── Check 3: merged tokens satisfy required fields ───────────────────────────
+
+const merged = neutral ? deepMerge(neutral, instance) : null;
+
+if (merged) {
+  if (!merged.colors || typeof merged.colors !== 'object') {
+    err('merged tokens: "colors" group is missing');
+  } else {
+    for (const key of REQUIRED_COLORS) {
+      if (!merged.colors[key]) err(`merged tokens: colors.${key} is required but missing`);
+      else if (typeof merged.colors[key] !== 'string') err(`merged tokens: colors.${key} must be a string`);
+    }
+    for (const [key, val] of Object.entries(merged.colors)) {
+      if (typeof val !== 'string') err(`merged tokens: colors.${key} must be a string`);
+    }
+  }
+
+  if (!merged.fonts || typeof merged.fonts !== 'object') {
+    err('merged tokens: "fonts" group is missing');
+  } else {
+    for (const key of REQUIRED_FONTS) {
+      if (!merged.fonts[key]) err(`merged tokens: fonts.${key} is required but missing`);
+      else if (typeof merged.fonts[key] !== 'string') err(`merged tokens: fonts.${key} must be a string`);
+    }
+    if (merged.fonts.links !== undefined) {
+      if (!Array.isArray(merged.fonts.links)) {
+        err('merged tokens: fonts.links must be an array');
+      } else {
+        for (const link of merged.fonts.links) {
+          if (typeof link !== 'string' || !isUri(link)) {
+            err(`merged tokens: fonts.links entry is not a valid URI: ${link}`);
+          }
+        }
+      }
+    }
+  }
+
+  // Optional groups: check value types if present
+  if (merged.scale) {
+    for (const [k, v] of Object.entries(merged.scale)) {
+      if (typeof v !== 'string') err(`merged tokens: scale.${k} must be a string`);
+    }
+  }
+  if (merged.radius) {
+    for (const [k, v] of Object.entries(merged.radius)) {
+      if (typeof v !== 'string') err(`merged tokens: radius.${k} must be a string`);
+    }
+  }
+  if (merged.motion) {
+    for (const [k, v] of Object.entries(merged.motion)) {
+      if (typeof v !== 'string') err(`merged tokens: motion.${k} must be a string`);
+    }
+  }
+}
+
+// ── Check 4: design-sources.json is valid + entries have required fields ─────
+
+let sources = null;
+if (fileExists(DESIGN_SOURCES)) {
+  sources = readJson(DESIGN_SOURCES, 'config/design-sources.json');
+  if (sources) {
+    if (!sources.surfaces || typeof sources.surfaces !== 'object') {
+      err('config/design-sources.json: "surfaces" key must be an object');
+    } else {
+      for (const [surfaceId, entry] of Object.entries(sources.surfaces)) {
+        if (!entry || typeof entry !== 'object') {
+          err(`design-sources: surface "${surfaceId}" entry must be an object`);
+          continue;
+        }
+        if (!entry.tool) {
+          err(`design-sources: surface "${surfaceId}" is missing "tool" field`);
+        } else if (!TOOL_ENUM.has(entry.tool)) {
+          err(`design-sources: surface "${surfaceId}" tool "${entry.tool}" is not in allowed enum (${[...TOOL_ENUM].join(', ')})`);
+        }
+        if (entry.sourceUrl !== undefined) {
+          if (typeof entry.sourceUrl !== 'string' || !isUri(entry.sourceUrl)) {
+            err(`design-sources: surface "${surfaceId}" sourceUrl is not a valid URI`);
+          }
+        } else if (entry.tool && !['hand', 'asset'].includes(entry.tool)) {
+          warn(`design-sources: surface "${surfaceId}" tool "${entry.tool}" has no sourceUrl`);
+        }
+        if (entry.lastSyncedAt !== undefined) {
+          if (typeof entry.lastSyncedAt !== 'string' || isNaN(Date.parse(entry.lastSyncedAt))) {
+            err(`design-sources: surface "${surfaceId}" lastSyncedAt is not a valid ISO 8601 date`);
+          }
+        }
+      }
+    }
+  }
+} else {
+  warn('config/design-sources.json not found — this is optional until adapters are in use');
+}
+
+// ── Check 5: design-sources surface ids match directories (if dirs exist) ─────
+
+const hasUiSrc    = dirExists(UI_SRC);
+const hasUiAssets = dirExists(UI_ASSETS);
+
+if (sources && sources.surfaces) {
+  const uiSrcDirs    = hasUiSrc    ? new Set(listDirs(UI_SRC).filter(n => n !== 'adapters')) : new Set();
+  const uiAssetsDirs = hasUiAssets ? new Set(listDirs(UI_ASSETS)) : new Set();
+
+  for (const surfaceId of Object.keys(sources.surfaces)) {
+    const inSrc    = uiSrcDirs.has(surfaceId);
+    const inAssets = uiAssetsDirs.has(surfaceId);
+    if (!inSrc && !inAssets && (hasUiSrc || hasUiAssets)) {
+      warn(`design-sources: surface "${surfaceId}" has no matching directory in src/ui/ or assets/ui/`);
+    }
+  }
+}
+
+// ── Check 6: adapter directories have valid index.js ─────────────────────────
+
+if (dirExists(ADAPTERS_DIR)) {
+  for (const adapterName of listDirs(ADAPTERS_DIR)) {
+    const indexPath = path.join(ADAPTERS_DIR, adapterName, 'index.js');
+    if (!fileExists(indexPath)) {
+      err(`adapter "${adapterName}": missing index.js at src/ui/adapters/${adapterName}/index.js`);
+      continue;
+    }
+    let mod;
+    try {
+      mod = require(indexPath);
+    } catch (e) {
+      err(`adapter "${adapterName}": index.js threw on require — ${e.message}`);
+      continue;
+    }
+    if (typeof mod.id !== 'string' || !mod.id) {
+      err(`adapter "${adapterName}": index.js must export a non-empty string "id"`);
+    } else if (mod.id !== adapterName) {
+      warn(`adapter "${adapterName}": exported id "${mod.id}" does not match directory name`);
+    }
+    if (typeof mod.import !== 'function') {
+      err(`adapter "${adapterName}": index.js must export an "import" function`);
+    }
+    if (typeof mod.export !== 'function') {
+      err(`adapter "${adapterName}": index.js must export an "export" function`);
+    }
+  }
+}
+
+// ── Report ────────────────────────────────────────────────────────────────────
+
+const effectiveErrors = STRICT ? [...errors, ...warnings] : errors;
+const ok = effectiveErrors.length === 0;
+
+if (JSON_MODE) {
+  process.stdout.write(JSON.stringify({ ok, errors, warnings }, null, 2) + '\n');
+} else {
+  const label = ok ? '✓ design contract valid' : '✗ design contract invalid';
+  process.stdout.write(`${label}\n`);
+  for (const e of errors)   process.stdout.write(`  ERROR   ${e}\n`);
+  for (const w of warnings) process.stdout.write(`  WARNING ${w}\n`);
+  if (ok && !STRICT && warnings.length) {
+    process.stdout.write(`  (${warnings.length} warning(s); use --strict to fail on warnings)\n`);
+  }
+}
+
+process.exit(ok ? 0 : 1);