@bongos/core 1.19.319 → 1.19.320

package/scripts/gds/ship-deploy-target.js

@@ -0,0 +1,388 @@
+// scripts/gds/ship-deploy-target.js — deploy-mode + deploy-target resolution, the gh helpers and push-path selection.
+//
+// Carved out of scripts/gds/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 639-989 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadSessionSync } = require('./cli-lib');
+const { argvOk, argvOut } = require('./ship-git.js');
+const { REPO_ROOT } = require('./ship-state.js');
+
+// ---------- CI deploy mode (#679, ADR 0042) ----------
+//
+// Two ways the confirmed→shipped land can run, chosen by a SINGLE committed
+// switch (config/deploy.json `mode`, env OTB_DEPLOY_MODE overrides):
+//
+//   'laptop' (default) — the operator's machine merges to main locally and, IFF a
+//      deploy target is configured (config/deploy.json "sshTarget" or
+//      <PREFIX>_DEPLOY_SSH_TARGET, resolveDeployTarget()), SSHes `~/deploy.sh` on it.
+//      The core carries NO target of its own, so by default this is a merge-to-main
+//      with no SSH deploy — a change reaches a live instance via package-core +
+//      `bongos upgrade` (pin-bump), NOT an SSH deploy (ADR 0108). When a target IS
+//      set it requires that host's SSH key, so only the operator can land.
+//
+//   'ci' — NO builder box holds the prod key. ship pushes the branch, opens a
+//      PR, and enables GitHub auto-merge; once required checks pass, GitHub
+//      merges to main and .github/workflows/deploy-prod.yml deploys from
+//      Actions. ship then CONFIRMS the deploy landed (PR merged + the
+//      deploy-prod workflow run succeeded for the merge commit + public
+//      healthz 200) so the synchronous "deploy-confirmed" UX is preserved
+//      without the key. This is what lets a Windows/Chromebook builder with no
+//      main checkout and no droplet key land their own work.
+//
+// parseDeployMode is pure (env string + raw config file contents → mode) and
+// exported so the test can assert the precedence + the safe default without
+// touching fs/env. The default is 'laptop' precisely so this code is INERT
+// until the deliberate, atomic cutover (config flip + GitHub arming together).
+function parseDeployMode(envVal, configRaw) {
+  const fromEnv = String(envVal || '').trim().toLowerCase();
+  if (fromEnv === 'ci' || fromEnv === 'laptop') return fromEnv;
+  if (configRaw) {
+    try {
+      const m = String(JSON.parse(configRaw).mode || '').trim().toLowerCase();
+      if (m === 'ci' || m === 'laptop') return m;
+    } catch (_) {
+      /* malformed config → fall through to the safe default */
+    }
+  }
+  return 'laptop';
+}
+
+// effectiveDeployMode — credential- and protection-aware adjustment of the parsed
+// mode (pure; exported for the regression test). The 'laptop' land path pushes
+// main + SSHes the droplet FROM THIS MACHINE, so it requires a local GitHub push
+// credential. A machine without one — a dev box, or a fresh/stale local clone that
+// can't even `git pull` (token-less origin, ADR 0053) — physically cannot run it;
+// it must ship via the 'ci' server-mediated publish path instead
+// (pushVia()==='server', ADR 0055), which lets the GDS server push with its own
+// credential. So when the parsed mode is 'laptop' but the machine can't push
+// locally AND the mode was NOT pinned by an explicit OTB_DEPLOY_MODE, fall back to
+// 'ci' rather than strand every ship at merge. This is the scootermack 2026-06-22
+// case: a checkout left at the pre-cutover 'laptop' default that can't pull
+// forward to 'ci', so it kept attempting a push it had no credential for. An
+// explicit env override always wins (tests/staging may force 'laptop'). Mirrors
+// pushVia()'s existing credential-awareness — the asymmetry (pushVia smart,
+// resolveDeployMode blind) WAS the bug. (task 1449)
+//
+// Second input, same shape (task 1002629): a machine WITH push credentials but a
+// branch-PROTECTED main also cannot run the laptop land — GitHub refuses the
+// direct `git push origin main` no matter whose credential it is. When task
+// 1002619 armed protection (required `unit` check), every ship resolved 'laptop'
+// and pushed into the wall, stranding graded-PASS tasks at confirmed (tasks
+// 1002608/1002609; learning 1000177). mainProtected must be STRICTLY true to
+// trigger — null/undefined means the probe couldn't answer (no gh, offline, no
+// permission) and keeps today's behavior rather than rerouting on a guess.
+function effectiveDeployMode(mode, { canPushLocally, envForced, mainProtected } = {}) {
+  if (mode === 'laptop' && !envForced && !canPushLocally) return 'ci';
+  if (mode === 'laptop' && !envForced && mainProtected === true) return 'ci';
+  return mode;
+}
+
+// mainIsProtected — true/false when GitHub answers, null when it can't. The
+// `gh api` resolves {owner}/{repo} from the checkout's origin; any failure
+// (gh missing, offline, non-200) is null = unknown, which effectiveDeployMode
+// treats as "no change". Same spawn discipline as ghAvailableAndAuthed().
+function mainIsProtected() {
+  try {
+    const r = spawnSync('gh', ['api', 'repos/{owner}/{repo}/branches/main', '--jq', '.protected'], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    if (!r || r.error || r.status !== 0) return null;
+    const out = String(r.stdout || '').trim();
+    if (out === 'true') return true;
+    if (out === 'false') return false;
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function resolveDeployMode() {
+  const configRaw = readDeployConfigRaw();
+  const mode = parseDeployMode(process.env.OTB_DEPLOY_MODE, configRaw);
+  const envForced = ['ci', 'laptop'].includes(
+    String(process.env.OTB_DEPLOY_MODE || '').trim().toLowerCase()
+  );
+  // Probe `gh` ONLY when it can change the answer (resolved 'laptop', no env
+  // override) — the happy 'ci' path and an env-pinned mode spawn no extra gh,
+  // keeping the documented spawn discipline (the line-1019 note). The protection
+  // probe runs only when the credential check kept us on 'laptop' (a
+  // credential-less machine already falls back without it).
+  if (mode === 'laptop' && !envForced) {
+    const canPushLocally = ghAvailableAndAuthed();
+    const mainProtected = canPushLocally ? mainIsProtected() : null;
+    const effective = effectiveDeployMode(mode, { canPushLocally, envForced, mainProtected });
+    if (effective === 'ci' && mainProtected === true) {
+      console.log('  deploy mode: main is branch-protected (direct pushes refused) — landing via the ci PR path');
+    }
+    return effective;
+  }
+  return mode;
+}
+
+// readDeployConfigRaw — raw contents of config/deploy.json (or null if absent /
+// unreadable). One reader shared by resolveDeployMode (the mode switch) and
+// resolveDeployTarget (the SSH target) so they never diverge on where the file is.
+function readDeployConfigRaw() {
+  try {
+    return fs.readFileSync(path.join(REPO_ROOT, 'config', 'deploy.json'), 'utf8');
+  } catch (_) {
+    return null; // no config file → callers apply their safe default
+  }
+}
+
+// safeBranding — the instance brand pack, or null if it can't be read. Guarded the
+// same way ship.js guards the sound player (line ~91): a deploy must never crash
+// because the brand file is missing on a fresh / re-seeded checkout.
+function safeBranding() {
+  try {
+    return require('../../src/branding').branding();
+  } catch (_) {
+    return null;
+  }
+}
+
+// readSessionApiBase — the signed-in session's persisted api_base (the instance the
+// CLI is actually pointed at), or null when not signed in / unreadable. This is the
+// session's OWN value only — deliberately NOT readSessionToken().apiBase, which
+// already folds in the env override + branding default; resolveInstanceBase orders
+// that precedence itself so it stays pure over its injected inputs.
+function readSessionApiBase() {
+  try {
+    const s = loadSessionSync();
+    return (s && typeof s.api_base === 'string' && s.api_base.trim()) ? s.api_base.trim() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// resolveInstanceBase — the ORIGIN of the instance this ship is landing on, used by
+// the ci-land deployed-version probe (/version), the /healthz re-probe, the ci
+// PR-body deploy note, and the manual-confirm curl guidance. Precedence mirrors the
+// CLI's own base resolution: <PREFIX>_API_BASE env → the signed-in session's
+// api_base → branding publicOrigin → null (unknowable). There is NO hardcoded
+// founder host — 5 sites here baked in `https://amazonprimea.com`, so a ci-land /
+// manual-confirm on a migrated instance pointed the builder at the WRONG box; the
+// ci-land/guidance sibling of resolveDeployTarget()'s laptop-mode fix (task 1002232
+// ⊃ task 1002202). Pure over its injected inputs (env / sessionApiBase / branding)
+// so the precedence is unit-tested without fs/env/network; the defaults read the
+// real session file + brand pack.
+function resolveInstanceBase({
+  env = process.env,
+  sessionApiBase = readSessionApiBase(),
+  branding = safeBranding(),
+} = {}) {
+  const ic = require('../../src/instance-config');
+  const trim = (s) => (typeof s === 'string' && s.trim() ? s.trim().replace(/\/+$/, '') : null);
+  const envBase = trim(ic.resolveEnv('API_BASE', { env }));
+  if (envBase) return envBase;
+  const sess = trim(sessionApiBase);
+  if (sess) return sess;
+  const origin = branding && branding.domains && branding.domains.publicOrigin;
+  return trim(origin);
+}
+
+// deployedVersionUrl — the instance's /version endpoint, or null when no instance
+// origin is resolvable (then fetchDeployedVersion is a no-op). Derived from
+// resolveInstanceBase — no hardcoded host (task 1002232).
+function deployedVersionUrl() {
+  const base = resolveInstanceBase();
+  return base ? `${base}/version` : null;
+}
+
+// resolveDeployTarget — WHERE a laptop-mode ship SSHes `~/deploy.sh`, and which
+// /healthz it re-probes when deploy.sh's own health check races the restart window.
+// Pure (env + raw config + branding → target) and exported so the precedence and the
+// safe "no target" default are unit-tested without touching fs/env/network.
+//
+// There is deliberately NO hardcoded default. The founder instance's old game-box
+// SSH target was baked in here, so a laptop-mode ship from a migrated
+// checkout SSHed the WRONG server (task 1002202). The core carries no deploy target
+// of its own — under the standalone model a core change reaches a live instance via
+// package-core + `bongos upgrade` (pin-bump), not an SSH deploy (ADR 0108). An
+// instance whose OWN checkout is its live server opts back into laptop-SSH deploy by
+// setting the target:
+//   config/deploy.json  → { "sshTarget": "user@host", "healthzUrl": "https://…/healthz" }
+//   env                 → <PREFIX>_DEPLOY_SSH_TARGET, <PREFIX>_DEPLOY_HEALTHZ_URL
+// healthzUrl, when unset, falls back to the instance's own publicOrigin + /healthz
+// (never a hardcoded host); null when even that is unknown (re-probe then skipped).
+function resolveDeployTarget({ env = process.env, configRaw = null, branding = null } = {}) {
+  const ic = require('../../src/instance-config');
+  let cfg = {};
+  if (configRaw) {
+    try { cfg = JSON.parse(configRaw) || {}; } catch (_) { cfg = {}; }
+  }
+  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+  const sshTarget = ic.resolveEnv('DEPLOY_SSH_TARGET', { env }) || str(cfg.sshTarget) || null;
+
+  let healthzUrl = ic.resolveEnv('DEPLOY_HEALTHZ_URL', { env }) || str(cfg.healthzUrl) || null;
+  const publicOrigin = branding && branding.domains && branding.domains.publicOrigin;
+  if (!healthzUrl && str(publicOrigin)) {
+    try { healthzUrl = new URL('/healthz', publicOrigin).toString(); }
+    catch (_) { /* malformed origin → leave healthzUrl null */ }
+  }
+  return { sshTarget, healthzUrl };
+}
+
+// gh runners — mirror gitArgvOk/gitOk but for the GitHub CLI. No shell, ever:
+// branch names + DB-sourced value_summary reach `gh` as literal argv elements
+// (same injection discipline as #681). ghArgvOk = boolean side-effect; ghJson =
+// parse `gh ... --json` stdout to an object/array (null on any failure).
+function ghArgvOk(args, opts = {}) {
+  return argvOk('gh', args, opts);
+}
+
+function ghJson(args, opts = {}) {
+  const out = argvOut('gh', args, opts);
+  if (out == null) return null;
+  try { return JSON.parse(out); } catch (_) { return null; }
+}
+
+// Pure argv builders for the PR land path — exported + tested so the untrusted
+// value_summary is proven to ride as ONE literal argv element (never a shell
+// string), exactly like buildMergeArgv.
+function buildPrCreateArgv(branch, title, body) {
+  return ['pr', 'create', '--head', branch, '--base', 'main', '--title', title, '--body', body];
+}
+
+// --merge keeps the project's --no-ff merge-commit convention (architecture.md
+// branch-cleanup note); --auto arms GitHub to merge the instant required checks
+// pass + branch protection is satisfied; --delete-branch mirrors the laptop
+// path's origin-branch cleanup.
+function buildPrMergeArgv(branch) {
+  return ['pr', 'merge', '--auto', '--merge', '--delete-branch', branch];
+}
+
+// Pure: did the prod-deploy workflow finish successfully for the merge commit?
+// `runs` is the parsed `gh run list --json headSha,status,conclusion` array.
+function deployRunSucceeded(runs, mergeSha) {
+  if (!mergeSha) return false;
+  return (runs || []).some(
+    (r) => r && r.headSha === mergeSha && r.status === 'completed' && r.conclusion === 'success'
+  );
+}
+
+// Pure: does the prod /version endpoint (#858) report it's running the commit we
+// just merged? 'match' = commit-pinned confirmation; 'mismatch' = prod is on a
+// different commit (e.g. a later deploy already superseded ours — still fine, our
+// run succeeded); 'unknown' = /version absent or unparseable (older prod / blip)
+// → caller falls back to the deploy-run + healthz signal. Compares on the shorter
+// length so a short vs full sha still matches. Exported + tested.
+function deployedCommitStatus(versionBody, mergeSha) {
+  if (!versionBody || !mergeSha) return 'unknown';
+  const c = String(versionBody.commit || '');
+  if (!/^[0-9a-f]{7,40}$/i.test(c)) return 'unknown';
+  const n = Math.min(c.length, String(mergeSha).length);
+  return c.slice(0, n).toLowerCase() === String(mergeSha).slice(0, n).toLowerCase()
+    ? 'match'
+    : 'mismatch';
+}
+
+// Fetch + parse the prod /version JSON (#858). null on any failure — never throws.
+// Default target is the resolved instance origin (no hardcoded host — task 1002232);
+// null when none is resolvable, in which case the probe is skipped.
+function fetchDeployedVersion(url = deployedVersionUrl()) {
+  if (!url) return null; // no resolvable instance origin → nothing to probe
+  // stdio override DISCARDS stderr (a curl progress/error line must not pollute
+  // the JSON parse) — the documented per-caller difference from ghJson.
+  const out = argvOut('curl', ['-fsS', '--max-time', '10', url], { stdio: ['ignore', 'pipe', 'ignore'] });
+  if (out == null) return null;
+  try { return JSON.parse(out); } catch (_) { return null; }
+}
+
+// ciLand — the 'ci' deploy-mode analogue of the laptop merge+SSH block. Pushes
+// the branch, ensures a PR exists, enables auto-merge, then confirms the deploy
+// actually landed. Returns true ONLY when prod is confirmed live on the merge
+// commit — so the caller flips the task to shipped exactly as the laptop path
+// does. Any earlier exit leaves the task at confirmed with a clear next step.
+// pushVia — which publish path ship uses in 'ci' mode (ADR 0055 / task 1025):
+//   'local'  — this machine pushes the branch + opens the PR with git + gh
+//              (laptop: gh present + authenticated). Today's behaviour.
+//   'server' — this machine has NO GitHub push credential (a dev box: no gh, a
+//              credential-less origin). ship uploads a thin branch bundle to the
+//              GDS, which pushes + opens the PR + auto-merges with the SERVER's
+//              credential. The box holds nothing (#919 model preserved).
+// Override with OTB_PUSH_VIA_SERVER=1 (force server) / =0 (force local) for tests.
+function ghAvailableAndAuthed() {
+  try {
+    const a = spawnSync('gh', ['auth', 'status'], {
+      stdio: 'ignore',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    return !!a && !a.error && a.status === 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+function pushVia() {
+  const o = String(process.env.OTB_PUSH_VIA_SERVER || '').trim();
+  if (o === '1') return 'server';
+  if (o === '0') return 'local';
+  // No explicit override: a machine that can run an authenticated gh (laptop)
+  // takes the local path; everything else (a dev box) goes server-mediated.
+  return ghAvailableAndAuthed() ? 'local' : 'server';
+}
+
+// broadcastHandledByServer — task 1045: on the server-mediated publish path the
+// SERVER posts the Discord ship-broadcast after it confirms the deploy (it holds
+// the webhook secrets; the box does NOT — ADR 0053). So ship.js must NOT also post
+// locally there, or the box would either double-post (impossible — no secret) or,
+// as before, fail silently. True only when the publish actually goes server-side:
+// ci deploy mode AND this machine has no GitHub push credential (pushVia 'server').
+// The laptop path (pushVia 'local') keeps posting locally, exactly as today. Pure
+// w.r.t. its inputs (env + committed deploy.json) + exported so the gate is tested.
+function broadcastHandledByServer() {
+  return resolveDeployMode() === 'ci' && pushVia() === 'server';
+}
+
+// shouldBailOnFetchFailure — autoMerge's decision when `git fetch origin main`
+// fails. A credential-less dev box (private origin, scrubbed clone token —
+// ADR 0053) CANNOT fetch origin, and that is FINE for the server-mediated
+// publish path (ADR 0055): ciLandServer bundles against the box's LOCAL
+// origin/main and the SERVER tops up main with its own credential. So a fetch
+// failure is fatal ONLY when we are NOT taking that path — otherwise the box can
+// never reach ciLand and strands every ship at confirmed (the bug task 1027
+// surfaced: ADR 0055 shipped the server path but left this fetch guard in front
+// of it). Pure + exported for the regression test (no git, no network).
+// NOTE: callers must still guard the pushVia() gh-probe behind `!fetchedMain` so
+// the happy path (fetch ok) spawns no extra gh and laptop behavior is unchanged.
+function shouldBailOnFetchFailure(fetchedMain, deployMode, via) {
+  if (fetchedMain) return false;
+  const serverPublish = deployMode === 'ci' && via === 'server';
+  return !serverPublish;
+}
+
+module.exports = {
+  broadcastHandledByServer,
+  buildPrCreateArgv,
+  buildPrMergeArgv,
+  deployRunSucceeded,
+  deployedCommitStatus,
+  effectiveDeployMode,
+  fetchDeployedVersion,
+  ghArgvOk,
+  ghJson,
+  mainIsProtected,
+  parseDeployMode,
+  pushVia,
+  readDeployConfigRaw,
+  resolveDeployMode,
+  resolveDeployTarget,
+  resolveInstanceBase,
+  safeBranding,
+  shouldBailOnFetchFailure,
+};