@svenroth-ai/shipwright 0.24.1-next.0

package/lib/preflight.mjs

@@ -0,0 +1,208 @@
+/**
+ * preflight.mjs — AC1a, the prerequisite gate (the THIRD silent death).
+ *
+ * The plugins do NOT run on Node alone: their hooks shell out to `uv` (159
+ * `uv run` call sites across the installed hooks.json files), which resolves a
+ * Python. Without uv + a WORKING Python every hook dies at session start while
+ * `claude plugin list` still shows a cheerful checkmark. So preflight is a
+ * loud, actionable gate, not a warning buried above "Command Center running".
+ *
+ * The Windows trap this file exists to dodge: `python3` is usually the
+ * Microsoft-Store App-Execution-Alias stub — `command -v`/`where` FINDS it, but
+ * running it does nothing. We therefore probe by TEST-RUNNING `--version` and
+ * accept the first candidate that actually reports one (ported from
+ * `scripts/verify-setup.sh`), never by mere presence on PATH.
+ */
+
+import { spawnSync } from "node:child_process";
+
+import { MIN_NODE, compareSemver, installHint, isWindows } from "./util.mjs";
+import { resolveSpawn } from "./win32-spawn.mjs";
+
+/**
+ * Default runner: invoke `<cmd> --version` with `shell: false` and report
+ * whether it actually ran.
+ *
+ * On Windows some of these tools are `.cmd`/`.bat` shims (`claude` from an npm
+ * install) that a bare `shell: false` spawn CANNOT reach — probing them that way
+ * would report a perfectly-installed Claude as ABSENT and skip the plugin phase
+ * forever. That used to be answered with `shell: true`; `resolveSpawn` now finds
+ * the real file via PATHEXT and routes a shim through an explicit
+ * `cmd.exe /d /s /c` instead (see lib/win32-spawn.mjs).
+ *
+ * CALLER INVARIANT, still load-bearing: `cmd` is a fixed internal literal
+ * (claude / uv / python3 / python / py / git / gh) and `args` is `["--version"]`.
+ * NOTHING here validates that — `defaultRun` is exported from a published `lib/`
+ * and reaches the cmd.exe wrap with no charset gate of its own (unlike
+ * `claude-cli.mjs`, which has `SAFE_ARG`). Only `runPreflight`'s call sites
+ * honour it. A caller passing user input must gate it first.
+ *
+ * An unresolvable name yields `ok: false` — exactly the verdict the old shell
+ * path produced via a non-zero exit. Note what "unresolvable" now means: a bare
+ * name that PATHEXT cannot place falls back to a direct `CreateProcess` spawn
+ * rather than being abandoned, because `realpath` cannot follow a Windows
+ * App-Execution-Alias at all — so a genuinely INSTALLED Microsoft-Store Python
+ * would otherwise be reported absent. The Store STUB is still rejected, by the
+ * unchanged `\d+\.\d+` output requirement below rather than by failing to
+ * resolve. Both verified on Windows 11, 2026-07-31.
+ * @param {string} cmd @param {string[]} [args]
+ * @returns {{ ok: boolean, stdout: string, stderr: string, code: number | null }}
+ */
+export function defaultRun(cmd, args = ["--version"]) {
+  try {
+    const plan = resolveSpawn([cmd, ...args]);
+    // UNREACHABLE as of iterate-2026-07-31 (win32-spawn divergence 5: an
+    // unresolvable bare name comes back as itself). `spawnSync` does NOT throw
+    // for a missing binary — it returns `{ error: ENOENT, status: null }` — so
+    // the failure is carried by the `!r.error` term in `ok` below and never
+    // reaches the catch. (An earlier version of this comment said "lands in the
+    // catch"; Stage-3 doubt review disproved it. The verdict was always right,
+    // the stated mechanism was not.) Kept as contract insurance.
+    if (!plan) return { ok: false, stdout: "", stderr: "", code: null };
+    const r = spawnSync(plan.command, plan.args, {
+      encoding: "utf-8",
+      shell: false,
+      timeout: 8000,
+      windowsVerbatimArguments: plan.windowsVerbatimArguments,
+    });
+    const stdout = (r.stdout ?? "").toString();
+    const stderr = (r.stderr ?? "").toString();
+    // A real interpreter/tool exits 0 AND prints a version somewhere. The MS
+    // Store python3 stub exits non-zero (or prints its "not found" nag), so
+    // requiring both status 0 and a digit-bearing line rejects it.
+    const ok = r.status === 0 && !r.error && /\d+\.\d+/.test(stdout + stderr);
+    return { ok, stdout, stderr, code: r.status ?? null };
+  } catch {
+    return { ok: false, stdout: "", stderr: "", code: null };
+  }
+}
+
+/** First `\d+.\d+(.\d+)?` token in a `--version` blob, or "". */
+export function extractVersion(out) {
+  const m = /(\d+\.\d+(?:\.\d+)?)/.exec(String(out ?? ""));
+  return m ? m[1] : "";
+}
+
+/**
+ * Resolve ONE working Python by test-running `--version` (python3 → python →
+ * py). Returns `{ bin, version }` or `null`. The MS-Store stub fails the
+ * `run().ok` test and is skipped — the whole reason this is not `command -v`.
+ * @param {(cmd: string, args?: string[]) => ReturnType<typeof defaultRun>} run
+ */
+export function resolvePython(run) {
+  for (const bin of ["python3", "python", "py"]) {
+    const r = run(bin, ["--version"]);
+    if (r.ok) return { bin, version: extractVersion(r.stdout + r.stderr) };
+  }
+  return null;
+}
+
+/**
+ * Run the full preflight. Pure over its injected seams (`run`, `nodeVersion`,
+ * `platform`) so every branch is unit-testable without a real toolchain.
+ *
+ * @param {{
+ *   run?: (cmd: string, args?: string[]) => ReturnType<typeof defaultRun>,
+ *   nodeVersion?: string,
+ *   platform?: NodeJS.Platform,
+ * }} [deps]
+ */
+export function runPreflight(deps = {}) {
+  const { run = defaultRun, nodeVersion = process.version, platform = process.platform } = deps;
+  /** @type {{name:string, ok:boolean, detail:string, hint?:string, hard:boolean, optional?:boolean}[]} */
+  const checks = [];
+
+  // claude — its own gate: absent → skip plugins + loud warning + non-zero exit.
+  const claude = run("claude", ["--version"]);
+  checks.push({
+    name: "claude",
+    ok: claude.ok,
+    detail: claude.ok ? extractVersion(claude.stdout + claude.stderr) : "not found",
+    hint: claude.ok ? undefined : installHint("claude", platform),
+    hard: true,
+  });
+
+  // uv — hard requirement for every plugin hook.
+  const uv = run("uv", ["--version"]);
+  checks.push({
+    name: "uv",
+    ok: uv.ok,
+    detail: uv.ok ? extractVersion(uv.stdout + uv.stderr) : "not found",
+    hint: uv.ok ? undefined : installHint("uv", platform),
+    hard: true,
+  });
+
+  // python — TEST-RUN probe (Store-stub trap), require >= 3.11.
+  const py = resolvePython(run);
+  const pyOk = py != null && compareSemver(py.version, "3.11.0") >= 0;
+  checks.push({
+    name: "python",
+    ok: pyOk,
+    detail: py ? `${py.version} (${py.bin})` : "not found (tried python3, python, py)",
+    hint: pyOk ? undefined : installHint("python", platform),
+    hard: true,
+  });
+
+  // node — assert the packaged server's minimum.
+  const nodeOk = compareSemver(nodeVersion, MIN_NODE) >= 0;
+  checks.push({
+    name: "node",
+    ok: nodeOk,
+    detail: nodeOk ? nodeVersion : `${nodeVersion} (need >= ${MIN_NODE})`,
+    hint: nodeOk ? undefined : installHint("node", platform),
+    hard: true,
+  });
+
+  // git — needed by the SDLC plugins.
+  const git = run("git", ["--version"]);
+  checks.push({
+    name: "git",
+    ok: git.ok,
+    detail: git.ok ? extractVersion(git.stdout + git.stderr) : "not found",
+    hint: git.ok ? undefined : installHint("git", platform),
+    hard: true,
+  });
+
+  // gh — optional (PRs). A soft note, never a failure.
+  const gh = run("gh", ["--version"]);
+  checks.push({
+    name: "gh",
+    ok: gh.ok,
+    detail: gh.ok ? extractVersion(gh.stdout + gh.stderr) : "not found (optional — needed for PRs)",
+    hard: false,
+    optional: true,
+  });
+
+  const hardFailures = checks.filter((c) => c.hard && !c.ok);
+  // The plugin phase needs claude + uv + python (hook runtime) AND git —
+  // `claude plugin marketplace add` clones the marketplace over git, and the
+  // SDLC plugins are git-based. Node is NOT gated here: it gates the SERVER
+  // (and npx already blocks a too-old engine), not the plugin install.
+  const pluginPhaseOk = claude.ok && uv.ok && pyOk && git.ok;
+
+  return {
+    checks,
+    python: py,
+    hasClaude: claude.ok,
+    hasUv: uv.ok,
+    hasPython: pyOk,
+    hasNode: nodeOk,
+    hasGit: git.ok,
+    /** Plugins can only be installed when claude + uv + python are all real. */
+    pluginPhaseOk,
+    /** Non-zero exit when any hard prerequisite is missing (AC1a). */
+    exitCode: hardFailures.length,
+    isWindows: isWindows(platform),
+  };
+}
+
+/** Render the one honest verdict block a `doctor`-style tool prints. */
+export function renderVerdict(result, mark) {
+  const lines = ["Prerequisites:"];
+  for (const c of result.checks) {
+    const glyph = c.ok ? mark.pass : c.optional ? mark.skip : mark.fail;
+    lines.push(`  ${glyph} ${c.name}: ${c.detail}`);
+    if (!c.ok && c.hint) lines.push(`        -> ${c.hint}`);
+  }
+  return lines.join("\n");
+}

package/lib/probes.mjs

@@ -0,0 +1,53 @@
+/**
+ * probes.mjs — low-level, self-contained runtime probes used by server.mjs.
+ *
+ * Kept apart from the boot/attach/swap orchestration so each stays focused and
+ * under the 300-line ceiling: this file owns "is the port occupied?" and "can
+ * the native terminal load?", server.mjs owns what to DO about the answers.
+ */
+
+import net from "node:net";
+
+/**
+ * TCP-connect to 127.0.0.1:port. `connected` → the port is OCCUPIED (by
+ * anything); ECONNREFUSED → FREE. A connect timeout is treated as free (a
+ * filtered localhost port does not occur in practice; erring toward free avoids
+ * a false-foreign that would block boot on a genuinely open port).
+ * @returns {Promise<boolean>} occupied
+ */
+export function tcpOccupied(port, { host = "127.0.0.1", timeoutMs = 1500 } = {}) {
+  return new Promise((resolve) => {
+    const sock = net.connect({ port, host });
+    let settled = false;
+    const done = (occupied) => {
+      if (settled) return;
+      settled = true;
+      sock.destroy();
+      resolve(occupied);
+    };
+    sock.setTimeout(timeoutMs);
+    sock.once("connect", () => done(true));
+    sock.once("timeout", () => done(false));
+    sock.once("error", () => done(false)); // ECONNREFUSED = nothing listening
+  });
+}
+
+/**
+ * Verify @lydell/node-pty's NATIVE binary actually loads. It is the only native
+ * piece of the packaged server; if it fails to resolve a binding, the Command
+ * Center boots with a terminal that cannot spawn — a silent half-death. Probe
+ * it (in the bootstrapper process, a same-platform proxy for the server) and
+ * fail LOUD before booting, never after (spec §1).
+ * @param {(m: string) => Promise<any>} [importFn]
+ * @returns {Promise<{ ok: boolean, error: string | null }>}
+ */
+export async function checkNativePty(importFn = (m) => import(m)) {
+  try {
+    const mod = await importFn("@lydell/node-pty");
+    const spawnFn = mod?.spawn ?? mod?.default?.spawn;
+    if (typeof spawnFn !== "function") return { ok: false, error: "loaded but exposes no spawn()" };
+    return { ok: true, error: null };
+  } catch (e) {
+    return { ok: false, error: String(e?.message ?? e) };
+  }
+}

package/lib/server.mjs

@@ -0,0 +1,315 @@
+/**
+ * server.mjs — AC1c + AC4: port-check, then boot / attach / swap. Open browser.
+ *
+ * Probe :3847 on 127.0.0.1 (IPv4 — Node resolves `localhost` → ::1 but Hono
+ * binds v4; a known trap in this repo). Then:
+ *   free                        → boot the packaged server (detached, outlives npx)
+ *   Shipwright, same-or-newer   → ATTACH (open browser, no 2nd server)
+ *   Shipwright, OLDER           → SWAP via the DETACHED deploy-swap.mjs
+ *   foreign                     → FAIL LOUD with a PORT= remediation, incumbent ALIVE
+ *
+ * This module issues NO kill/taskkill/process.kill — ever. The incumbent on
+ * :3847 may be hosting the very terminal this command runs in (PR #249, the
+ * deploy self-kill). The swap's kill lives ONLY inside the detached swapper,
+ * which is spawned BEFORE any kill so it outlives the caller's death cascade.
+ */
+
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+
+import { compareSemver } from "./util.mjs";
+import { tcpOccupied, checkNativePty } from "./probes.mjs";
+import { win32CmdWrap } from "./win32-spawn.mjs";
+
+// Re-exported so callers/tests keep a single `server.mjs` surface.
+export { tcpOccupied, checkNativePty } from "./probes.mjs";
+
+const DEFAULT_PORT = 3847;
+
+/**
+ * The Command Center's wire-protocol identity — MUST match `APP_NAME` in the
+ * server's diagnostics route. A foreign process that happens to answer
+ * `/api/diagnostics` with an `app.version` but NOT this exact name is treated
+ * as FOREIGN (left alive, never killed), so a version alone can never
+ * misidentify a stranger's server as ours.
+ */
+export const APP_IDENTITY = "shipwright-command-center";
+
+/**
+ * Classify a port. TCP occupancy is decided FIRST, independent of HTTP: a
+ * process that accepts connections but never answers /api/diagnostics (or is
+ * not HTTP at all) is FOREIGN, not free — booting a second server onto it is
+ * exactly the bug AC4 forbids. Only a Shipwright server (200 +
+ * `app.name === APP_IDENTITY` + `app.version`) counts as ours. Offline-safe.
+ * @param {number} port
+ * @param {{ fetchImpl?: typeof fetch, timeoutMs?: number, tcpProbe?: typeof tcpOccupied }} [deps]
+ * @returns {Promise<{ reachable: boolean, shipwright: boolean, version: string | null }>}
+ */
+export async function probeServer(port, deps = {}) {
+  const {
+    fetchImpl = typeof fetch === "function" ? fetch : undefined,
+    timeoutMs = 2000,
+    tcpProbe = tcpOccupied,
+  } = deps;
+
+  const occupied = await tcpProbe(port, { timeoutMs: Math.min(timeoutMs, 1500) });
+  if (!occupied) return { reachable: false, shipwright: false, version: null };
+  if (!fetchImpl) return { reachable: true, shipwright: false, version: null };
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}/api/diagnostics`, { signal: ctrl.signal });
+    if (!res || !res.ok) return { reachable: true, shipwright: false, version: null };
+    const body = await res.json();
+    const app = body && typeof body.app === "object" ? body.app : null;
+    const isOurs = app != null && app.name === APP_IDENTITY && typeof app.version === "string";
+    return { reachable: true, shipwright: isOurs, version: isOurs ? app.version : null };
+  } catch {
+    // Occupied but not identifiable over HTTP → foreign (reachable, not ours).
+    return { reachable: true, shipwright: false, version: null };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Decide the action from a probe result. Pure — the heart of AC1c/AC4.
+ * @param {{ reachable: boolean, shipwright: boolean, version: string | null }} probe
+ * @param {string} packageVersion
+ * @returns {"boot"|"attach"|"swap"|"foreign"}
+ */
+export function decideAction(probe, packageVersion) {
+  if (!probe.reachable) return "boot";
+  if (!probe.shipwright) return "foreign";
+  // Older running server → swap (a naive attach serves the OLD UI: silent
+  // no-op update). Same or newer → attach (never needlessly restart or downgrade).
+  return compareSemver(probe.version ?? "", packageVersion) < 0 ? "swap" : "attach";
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Poll the probe until `predicate(probe)` holds or the deadline passes.
+ * @returns {Promise<{ ok: boolean, probe: Awaited<ReturnType<typeof probeServer>> }>}
+ */
+export async function pollUntil(probeFn, predicate, { timeoutMs = 15000, intervalMs = 500 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let last = { reachable: false, shipwright: false, version: null };
+  while (Date.now() < deadline) {
+    last = await probeFn();
+    if (predicate(last)) return { ok: true, probe: last };
+    await sleep(intervalMs);
+  }
+  return { ok: false, probe: last };
+}
+
+/**
+ * Pure spawn PLAN for booting the packaged server. Detached so it outlives the
+ * short-lived npx process; env points the resolver at the packaged static +
+ * profiles dirs. Exported so the detached property is unit-testable without a
+ * real spawn.
+ */
+export function bootSpawnPlan(port, pkgRoot) {
+  return {
+    command: process.execPath,
+    args: [path.join(pkgRoot, "server", "dist", "index.js")],
+    options: {
+      env: {
+        ...process.env,
+        PORT: String(port),
+        SHIPWRIGHT_STATIC_DIR: path.join(pkgRoot, "client", "dist"),
+        SHIPWRIGHT_PROFILES_DIR: path.join(pkgRoot, "server", "profiles"),
+      },
+      detached: true,
+      stdio: "ignore",
+      shell: false,
+    },
+  };
+}
+
+/**
+ * Pure spawn PLAN for the DETACHED swapper. It — not the bootstrapper — owns
+ * the kill, and it is spawned detached BEFORE any kill so an invocation from
+ * inside the Command Center's own terminal survives the death cascade (AC1c).
+ */
+export function swapperSpawnPlan(port, pkgRoot) {
+  return {
+    command: process.execPath,
+    args: [path.join(pkgRoot, "scripts", "deploy-swap.mjs"), "--port", String(port)],
+    options: { detached: true, stdio: "ignore", shell: false },
+  };
+}
+
+function runPlan(plan) {
+  const child = spawn(plan.command, plan.args, plan.options);
+  child.unref();
+  return child.pid ?? null;
+}
+
+const defaultBootServer = (port, pkgRoot) => runPlan(bootSpawnPlan(port, pkgRoot));
+const defaultSpawnSwapper = (port, pkgRoot) => runPlan(swapperSpawnPlan(port, pkgRoot));
+
+/** Default: read the swapper's durable verdict (pid + ok) if present. */
+function defaultReadDeployStatus() {
+  try {
+    const p = path.join(os.homedir(), ".shipwright-webui", "deploy-status.json");
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure spawn PLAN for opening the browser. Exported so the shell-free property
+ * is unit-testable on every platform without a real spawn.
+ *
+ * Windows needs cmd.exe because `start` is a cmd BUILTIN, not an executable —
+ * but it gets it EXPLICITLY (the resolved ComSpec, discrete argv, `shell: false`)
+ * rather than by asking Node to build a shell command line for us. Nothing here
+ * needs PATHEXT resolution, so this is the one of the four remediated sites that
+ * reaches for `win32ComSpec` directly instead of `resolveSpawn`.
+ */
+export function openBrowserPlan(url, platform = process.platform, env = process.env) {
+  if (platform === "win32") {
+    // Built through the SAME wrap as every other cmd.exe invocation rather than
+    // splicing the url into discrete argv. That is not decoration: a url with a
+    // query string (`http://h/?a=1&b=2`) would otherwise reach cmd.exe with a
+    // bare `&` and run `b=2` as a second command. Today's only caller passes
+    // `http://localhost:<validated port>`, but this is exported public API in a
+    // published package, so it must not depend on that.
+    // The empty string is `start`'s window-TITLE argument; without it `start`
+    // consumes a quoted URL as the title and opens nothing.
+    //
+    // A literal `"` is the ONE character quoting cannot contain — it would close
+    // the quoted region early and let the rest be read as a command — so it is
+    // percent-encoded here rather than trusted. `"` is never valid unescaped in a
+    // URL, so this cannot corrupt a legitimate one. Residual, stated rather than
+    // implied: `%VAR%` still expands inside double quotes, so a url carrying a
+    // real environment-variable reference would be substituted. Today's only
+    // caller passes `http://localhost:<validated port>`.
+    return win32CmdWrap("start", ["", url.replace(/"/g, "%22")], env);
+  }
+  return { command: platform === "darwin" ? "open" : "xdg-open", args: [url] };
+}
+
+/**
+ * Default: open the browser per platform. Never fatal.
+ *
+ * Exported ONLY so the never-fatal contract is testable — without a way to call
+ * it, the async-error guard below could not be falsified, and a guard that
+ * cannot be falsified is decoration.
+ */
+export function defaultOpenBrowser(url) {
+  const plan = openBrowserPlan(url);
+  try {
+    const child = spawn(plan.command, plan.args, { detached: true, stdio: "ignore", shell: false });
+    // `spawn` reports a launch failure ASYNCHRONOUSLY via the "error" event, so
+    // the try/catch above cannot see it — and an unhandled "error" on an
+    // EventEmitter throws, which would take the bootstrapper down and break the
+    // "Never fatal" contract one line above. A bad ComSpec or a missing
+    // xdg-open is exactly that case.
+    child.on("error", () => {
+      /* headless / no opener — the URL is printed by the caller regardless */
+    });
+    child.unref();
+  } catch {
+    /* synchronous spawn failure — same non-fatal outcome */
+  }
+}
+
+/**
+ * Orchestrate boot / attach / swap + browser open. Pure over its seams.
+ * @param {{
+ *   port?: number, pkgRoot: string, packageVersion: string, noOpen?: boolean,
+ *   probeFn?: () => Promise<Awaited<ReturnType<typeof probeServer>>>,
+ *   bootServer?: (port:number, pkgRoot:string) => number | null,
+ *   spawnSwapper?: (port:number, pkgRoot:string) => number | null,
+ *   readDeployStatus?: () => any,
+ *   openBrowser?: (url:string) => void,
+ *   log?: (msg:string) => void,
+ *   timeoutMs?: number,
+ * }} opts
+ */
+export async function ensureServer(opts) {
+  const port = opts.port ?? DEFAULT_PORT;
+  const url = `http://localhost:${port}`;
+  const log = opts.log ?? (() => {});
+  const probeFn = opts.probeFn ?? (() => probeServer(port));
+  const bootServer = opts.bootServer ?? defaultBootServer;
+  const spawnSwapper = opts.spawnSwapper ?? defaultSpawnSwapper;
+  const readDeployStatus = opts.readDeployStatus ?? defaultReadDeployStatus;
+  const openBrowser = opts.openBrowser ?? defaultOpenBrowser;
+  const nativePtyCheck = opts.nativePtyCheck ?? checkNativePty;
+  const timeoutMs = opts.timeoutMs ?? 15000;
+
+  const probe = await probeFn();
+  const action = decideAction(probe, opts.packageVersion);
+  let result = { action, url, port, version: probe.version };
+
+  if (action === "foreign") {
+    throw new Error(
+      `port ${port} is held by a NON-Shipwright process — it was left running and NOT killed. ` +
+        `Free the port or pick another: re-run with  PORT=<n> npx @svenroth-ai/shipwright@latest`,
+    );
+  }
+
+  // Starting a new server (boot OR swap) requires a working native terminal —
+  // never start one that cannot spawn (spec §1). Attach skips this: the
+  // incumbent already proved itself.
+  if (action === "boot" || action === "swap") {
+    const pty = await nativePtyCheck();
+    if (!pty.ok) {
+      throw new Error(
+        `the embedded terminal's native module (@lydell/node-pty) failed to load: ${pty.error}. ` +
+          `Ensure Node >= 20.12 and your platform's build tools are present, then re-run. ` +
+          `A Command Center whose terminal cannot spawn was NOT started.`,
+      );
+    }
+  }
+
+  if (action === "attach") {
+    log(`Shipwright ${probe.version} already running on ${url} — attaching (no second server).`);
+  } else if (action === "boot") {
+    log(`Port ${port} free — starting the Command Center.`);
+    const pid = bootServer(port, opts.pkgRoot);
+    const ready = await pollUntil(probeFn, (p) => p.shipwright, { timeoutMs });
+    if (!ready.ok) {
+      throw new Error(
+        `the packaged server did not become ready on ${url} within ${timeoutMs} ms — ` +
+          `check ~/.shipwright-webui/server-manual.log`,
+      );
+    }
+    result = { ...result, pid, version: ready.probe.version };
+  } else if (action === "swap") {
+    log(`Older server (${probe.version}) on ${url} — swapping to ${opts.packageVersion} via the detached swapper.`);
+    const swapperPid = spawnSwapper(port, opts.pkgRoot);
+    // Readiness = the port now serves EXACTLY the package version (AC1c: "the
+    // version the server reports afterwards equals the package's"). `>=` would
+    // let an unexpected newer instance winning the race masquerade as our swap.
+    const ready = await pollUntil(
+      probeFn,
+      (p) => p.shipwright && compareSemver(p.version ?? "", opts.packageVersion) === 0,
+      { timeoutMs: Math.max(timeoutMs, 20000) },
+    );
+    const status = readDeployStatus();
+    if (!ready.ok) {
+      throw new Error(
+        `the swap did not reach ${opts.packageVersion} on ${url} in time — ` +
+          `see ~/.shipwright-webui/deploy-swap.log${status?.error ? ` (${status.error})` : ""}`,
+      );
+    }
+    result = {
+      ...result,
+      swapperPid,
+      newPid: status && typeof status.pid === "number" ? status.pid : null,
+      previousVersion: probe.version,
+      version: ready.probe.version,
+    };
+  }
+
+  if (!opts.noOpen) openBrowser(url);
+  return result;
+}

package/lib/util.mjs

@@ -0,0 +1,83 @@
+/**
+ * util.mjs — pure, dependency-free helpers shared across the bootstrapper.
+ *
+ * Everything here is side-effect free and unit-testable in isolation: SemVer
+ * parsing/compare (attach-vs-swap + stale-copy decisions ride on it), platform
+ * detection, and the actionable install hints a missing prerequisite must
+ * print. No `claude`, no network, no filesystem — those live in the sibling
+ * modules behind injected seams.
+ */
+
+/** @param {string} v @returns {[number, number, number] | null} */
+export function parseSemver(v) {
+  if (typeof v !== "string") return null;
+  const m = /^\s*v?(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Compare two SemVer-shaped strings by MAJOR.MINOR.PATCH.
+ * Returns -1 (a<b), 0 (equal or either unparseable), 1 (a>b). Pre-release
+ * tails are ignored — the bootstrapper only ever needs the numeric triple.
+ * @param {string} a @param {string} b @returns {-1 | 0 | 1}
+ */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] < pb[i]) return -1;
+    if (pa[i] > pb[i]) return 1;
+  }
+  return 0;
+}
+
+/** @param {NodeJS.Platform} [platform] */
+export function isWindows(platform = process.platform) {
+  return platform === "win32";
+}
+
+/**
+ * Platform-correct, copy-pasteable install command for a missing prerequisite.
+ * A missing tool must never be a vague "install it" — the user gets the exact
+ * line for THEIR OS. Mirrors the pointers `scripts/verify-setup.sh` prints.
+ * @param {"uv"|"python"|"node"|"git"|"claude"} tool
+ * @param {NodeJS.Platform} [platform]
+ * @returns {string}
+ */
+export function installHint(tool, platform = process.platform) {
+  const win = isWindows(platform);
+  switch (tool) {
+    case "uv":
+      return win
+        ? 'powershell -c "irm https://astral.sh/uv/install.ps1 | iex"'
+        : "curl -LsSf https://astral.sh/uv/install.sh | sh";
+    case "python":
+      return win
+        ? "install Python 3.11+ from https://www.python.org/downloads/ (NOT the Microsoft Store stub)"
+        : "install Python 3.11+ (e.g. `brew install python` / `apt install python3`)";
+    case "node":
+      return "install Node.js >= 20.12.0 from https://nodejs.org/";
+    case "git":
+      return win
+        ? "install Git from https://git-scm.com/download/win"
+        : "install git (e.g. `brew install git` / `apt install git`)";
+    case "claude":
+      return "install Claude Code — https://docs.claude.com/en/docs/claude-code";
+    default:
+      return "";
+  }
+}
+
+/** Minimum Node the packaged server needs (mirrors server/package.json engines). */
+export const MIN_NODE = "20.12.0";
+
+/** ASCII status glyphs — no emoji, PowerShell-5.1-safe, honest verdict blocks. */
+export const MARK = Object.freeze({
+  pass: "[OK]",
+  fail: "[!!]",
+  warn: "[??]",
+  skip: "[--]",
+  info: "[..]",
+});