@svenroth-ai/shipwright 0.24.2-next.0 → 0.24.4-next.0

package/bin/shipwright.mjs

@@ -142,7 +142,32 @@ export function printSummary(log, { plugin, server, port }) {
   log(`========================================`);
 }
 
-export async function main(argv = process.argv.slice(2), log = (m) => console.log(m)) {
+/**
+ * Decide whether to boot the Command Center after the plugin phase.
+ *
+ * The cold-start failure this closes: when a hard prerequisite (Claude / uv /
+ * Python) is missing, the plugin phase is correctly SKIPPED — but the bin then
+ * booted the Command Center anyway, i.e. a WebUI that launches a Claude with NO
+ * `/shipwright-*` commands. That is useless, so the default flow now STOPS.
+ * `--webui-only` is the explicit opt-out (it never runs the plugin phase, so
+ * `pluginSkipped` is false there and it still boots).
+ *
+ * @param {{ pluginsOnly: boolean, webuiOnly: boolean, pluginSkipped: boolean }} s
+ * @returns {{ boot: boolean, reason: "plugins-only" | "prereqs-missing" | "ok" }}
+ */
+export function serverBootDecision({ pluginsOnly, webuiOnly, pluginSkipped }) {
+  if (pluginsOnly) return { boot: false, reason: "plugins-only" };
+  if (pluginSkipped && !webuiOnly) return { boot: false, reason: "prereqs-missing" };
+  return { boot: true, reason: "ok" };
+}
+
+export async function main(argv = process.argv.slice(2), log = (m) => console.log(m), deps = {}) {
+  // Seams (default to the real implementations) so main's control flow — the
+  // prereqs-missing hard-stop especially — is unit-testable without a real
+  // toolchain or a live :3847.
+  const runPluginPhase = deps.pluginPhase ?? pluginPhase;
+  const runEnsureServer = deps.ensureServer ?? ensureServer;
+
   const args = parseArgs(argv);
   if (args.version) { log(SELF_VERSION); return 0; }
   if (args.help) { log(HELP); return 0; }
@@ -161,13 +186,32 @@ export async function main(argv = process.argv.slice(2), log = (m) => console.lo
   let server = null;
 
   if (!args.webuiOnly) {
-    plugin = await pluginPhase(log);
+    plugin = await runPluginPhase(log);
     exitCode = Math.max(exitCode, plugin.exitCode ?? 0);
   }
 
-  if (!args.pluginsOnly) {
+  const bootDecision = serverBootDecision({
+    pluginsOnly: args.pluginsOnly,
+    webuiOnly: args.webuiOnly,
+    pluginSkipped: plugin?.skipped === true,
+  });
+
+  if (bootDecision.reason === "prereqs-missing") {
+    // Hard-stop: a Command Center with no plugins would launch a Claude with no
+    // /shipwright-* commands. The per-tool install hints already printed above
+    // (renderVerdict); here we say why we stopped and how to override.
+    log(`\n${MARK.fail} Not starting the Command Center — required tools are missing.`);
+    log(`      Shipwright needs Claude Code, Python 3.11+ with uv, and git installed first;`);
+    log(`      without them the plugins cannot install and the Command Center would be empty.`);
+    log(`      Install whichever tools are marked missing above, then re-run  npx @svenroth-ai/shipwright@latest`);
+    log(`      (To start the Command Center anyway, without plugins: add --webui-only.)`);
+    printSummary(log, { plugin, server: null, port: null });
+    return Math.max(exitCode, 1);
+  }
+
+  if (bootDecision.boot) {
     try {
-      server = await ensureServer({ port, pkgRoot: PKG_ROOT, packageVersion: SELF_VERSION, noOpen: args.noOpen, log });
+      server = await runEnsureServer({ port, pkgRoot: PKG_ROOT, packageVersion: SELF_VERSION, noOpen: args.noOpen, log });
     } catch (e) {
       log(`${MARK.fail} ${String(e?.message ?? e)}`);
       exitCode = Math.max(exitCode, 1);

package/lib/preflight.mjs

@@ -15,8 +15,10 @@
  */
 
 import { spawnSync } from "node:child_process";
+import os from "node:os";
 
 import { MIN_NODE, compareSemver, installHint, isWindows } from "./util.mjs";
+import { probeEnv, resolvePosixBin } from "./probe-path.mjs";
 import { resolveSpawn } from "./win32-spawn.mjs";
 
 /**
@@ -31,7 +33,9 @@ import { resolveSpawn } from "./win32-spawn.mjs";
  * `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"]`.
+ * (claude / uv / python3 / python / py / git / gh) and `args` is a fixed internal
+ * literal too — `["--version"]` for every probe, plus the one `["python",
+ * "find", ">=3.11"]` uv-can-supply-Python predicate. NO caller passes user input.
  * 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
@@ -48,9 +52,17 @@ import { resolveSpawn } from "./win32-spawn.mjs";
  * @param {string} cmd @param {string[]} [args]
  * @returns {{ ok: boolean, stdout: string, stderr: string, code: number | null }}
  */
-export function defaultRun(cmd, args = ["--version"]) {
+export function defaultRun(cmd, args = ["--version"], deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const homedir = deps.homedir ?? os.homedir();
+  const env = probeEnv(platform, homedir, deps.env ?? process.env);
   try {
-    const plan = resolveSpawn([cmd, ...args]);
+    // Windows resolves shims via PATHEXT against the augmented `env`; POSIX
+    // resolves the absolute path itself so the augmented PATH actually applies.
+    const plan =
+      platform === "win32"
+        ? resolveSpawn([cmd, ...args], { platform, env })
+        : { command: resolvePosixBin(cmd, env), 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
@@ -63,6 +75,7 @@ export function defaultRun(cmd, args = ["--version"]) {
       encoding: "utf-8",
       shell: false,
       timeout: 8000,
+      env,
       windowsVerbatimArguments: plan.windowsVerbatimArguments,
     });
     const stdout = (r.stdout ?? "").toString();
@@ -132,13 +145,33 @@ export function runPreflight(deps = {}) {
     hard: true,
   });
 
-  // python — TEST-RUN probe (Store-stub trap), require >= 3.11.
+  // python — the stack runs every hook via `uv run`, which resolves a
+  // uv-MANAGED interpreter. So a working system python3 >= 3.11 satisfies the
+  // gate, but so does uv being able to PROVIDE 3.11+ — the common Mac case where
+  // `uv python install 3.11` left system `python3` at 3.9. System probe first
+  // (TEST-RUN, Store-stub trap); only fall through to uv when it is short.
   const py = resolvePython(run);
-  const pyOk = py != null && compareSemver(py.version, "3.11.0") >= 0;
+  const sysOk = py != null && compareSemver(py.version, "3.11.0") >= 0;
+  let pyOk = sysOk;
+  let pyDetail = py ? `${py.version} (${py.bin})` : "not found (tried python3, python, py)";
+  if (!pyOk && uv.ok) {
+    // `uv python find` locates an installed 3.11+ WITHOUT downloading — a clean,
+    // side-effect-free predicate for "uv can supply Python for the hooks".
+    const uvPy = run("uv", ["python", "find", ">=3.11"]);
+    // Gate on EXIT CODE, not defaultRun's version-shaped `ok`: `uv python find`
+    // prints a PATH, and a resolved interpreter whose path carries no decimal
+    // (e.g. a `/usr/local/bin/python3` symlink) would fail the `\d+\.\d+` output
+    // test despite a clean exit — re-introducing the very false "not found" this
+    // change removes. uv exits 0 on a hit, 2 on a miss (verified 2026-08-22).
+    if (uvPy.code === 0) {
+      pyOk = true;
+      pyDetail = `${extractVersion(uvPy.stdout + uvPy.stderr) || "3.11+"} (uv-managed)`;
+    }
+  }
   checks.push({
     name: "python",
     ok: pyOk,
-    detail: py ? `${py.version} (${py.bin})` : "not found (tried python3, python, py)",
+    detail: pyDetail,
     hint: pyOk ? undefined : installHint("python", platform),
     hard: true,
   });
@@ -204,5 +237,16 @@ export function renderVerdict(result, mark) {
     lines.push(`  ${glyph} ${c.name}: ${c.detail}`);
     if (!c.ok && c.hint) lines.push(`        -> ${c.hint}`);
   }
+  // A just-installed tool lands in ~/.local/bin but the running shell's PATH was
+  // captured before the install — so "not found" here is often really "not on
+  // PATH yet". Say so, once, OS-aware, whenever a hard prerequisite is missing.
+  if (result.checks.some((c) => c.hard && !c.ok)) {
+    lines.push("");
+    lines.push(
+      result.isWindows
+        ? "  Note: if you JUST installed one of these, open a NEW terminal so it lands on your PATH, then re-run."
+        : "  Note: if you JUST installed one of these, open a new terminal (or `source ~/.zshrc` / `~/.bashrc`) so it lands on your PATH, then re-run.",
+    );
+  }
   return lines.join("\n");
 }

package/lib/probe-path.mjs

@@ -0,0 +1,84 @@
+/**
+ * probe-path.mjs — where the prerequisite probe LOOKS for a binary.
+ *
+ * Split out of preflight.mjs (iterate-2026-08-22): the "augment the lookup PATH
+ * and resolve a bare name to an absolute executable" concern is cohesive and
+ * independently testable, and keeping it here holds preflight.mjs under the
+ * 300-line ceiling. preflight.mjs owns the VERDICT; this module owns the LOOKUP.
+ */
+
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Return a copy of `baseEnv` whose PATH also contains the well-known user-level
+ * bin dirs that the uv and Claude Code installers write to.
+ *
+ * WHY (Mac cold-start, iterate-2026-08-22): those installers drop their binary
+ * in `~/.local/bin` (and Homebrew in `/opt/homebrew/bin` | `/usr/local/bin`) and
+ * only APPEND that dir to the shell rc. The npx process that runs this
+ * bootstrapper still carries the PATH captured before the install, so a
+ * `shell: false` probe reported a perfectly-installed uv/claude as ABSENT until
+ * the user opened a fresh terminal. Augmenting the lookup PATH lets the probe
+ * find a just-installed tool without the restart.
+ *
+ * The extra dirs are APPENDED, never prepended — an explicitly-configured tool
+ * on the real PATH always wins; `~/.local/bin` is only a fallback. Bare-name,
+ * PATH-only: no cwd is ever added, so the win32-spawn security posture holds.
+ *
+ * Windows subtlety: `process.env` is case-insensitive but a plain object is not,
+ * so we collapse every `path`-cased key into a single canonical `PATH` — never
+ * hand spawn both a stale `Path` and an augmented `PATH`.
+ *
+ * @param {NodeJS.Platform} platform
+ * @param {string} homedir
+ * @param {Record<string, string | undefined>} [baseEnv]
+ * @returns {Record<string, string>}
+ */
+export function probeEnv(platform, homedir, baseEnv = {}) {
+  const sep = platform === "win32" ? ";" : ":";
+  const extra =
+    platform === "win32"
+      ? [path.win32.join(homedir, ".local", "bin")]
+      : [path.posix.join(homedir, ".local", "bin"), "/opt/homebrew/bin", "/usr/local/bin"];
+
+  const out = {};
+  let current = "";
+  for (const [k, v] of Object.entries(baseEnv)) {
+    if (k.toLowerCase() === "path") {
+      if (v != null) current = v;
+      continue; // drop every path-cased key; a single PATH is re-added below
+    }
+    if (v != null) out[k] = v;
+  }
+  const merged = current ? current.split(sep).filter(Boolean) : [];
+  for (const d of extra) if (!merged.includes(d)) merged.push(d);
+  out.PATH = merged.join(sep);
+  return out;
+}
+
+/**
+ * Resolve a bare command name to an absolute executable path by scanning the
+ * (already augmented) PATH — POSIX only. Node's own bare-name lookup does not
+ * reliably honour `options.env.PATH`, so we resolve the absolute path ourselves
+ * and spawn THAT, making the augmented PATH actually take effect. PATH-only,
+ * never cwd. Returns the bare name unchanged when nothing resolves (spawn then
+ * yields the same ENOENT → `ok:false` verdict as before).
+ * @param {string} name @param {Record<string,string|undefined>} env
+ */
+export function resolvePosixBin(name, env) {
+  if (name.includes("/")) return name; // already a path
+  for (const dir of (env.PATH ?? "").split(":")) {
+    if (!dir) continue;
+    const cand = path.posix.join(dir, name);
+    try {
+      if (statSync(cand).isFile()) {
+        accessSync(cand, fsConstants.X_OK);
+        return cand;
+      }
+    } catch {
+      // not a usable executable here — keep searching
+    }
+  }
+  return name;
+}

package/lib/server.mjs

@@ -16,7 +16,7 @@
 
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { readFileSync, openSync, closeSync, mkdirSync } from "node:fs";
 import os from "node:os";
 
 import { compareSemver } from "./util.mjs";
@@ -149,7 +149,52 @@ function runPlan(plan) {
   return child.pid ?? null;
 }
 
-const defaultBootServer = (port, pkgRoot) => runPlan(bootSpawnPlan(port, pkgRoot));
+/**
+ * The file the DETACHED packaged server's stdout+stderr is redirected to — and
+ * the SAME path the boot readiness-timeout error tells the user to read. Kept as
+ * one exported function so the two can never drift apart again: the boot used to
+ * spawn with `stdio:"ignore"` (output discarded) while the error pointed the
+ * user at this log, which nothing wrote — an undiagnosable dead end.
+ */
+export function bootLogPath() {
+  return path.join(os.homedir(), ".shipwright-webui", "server-manual.log");
+}
+
+/** Open the boot log for append, creating its dir. Returns an fd, or null when
+ * it cannot be opened — logging is best-effort and must NEVER block the boot. */
+function defaultOpenBootLog() {
+  try {
+    mkdirSync(path.dirname(bootLogPath()), { recursive: true });
+    return openSync(bootLogPath(), "a");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the `stdio` for the detached boot: route BOTH stdout and stderr at the
+ * log fd when it opens, else fall back to `"ignore"` (the pre-fix behaviour, now
+ * only the degraded path). Pure over its `open` seam so both branches are
+ * unit-testable without touching the filesystem.
+ * @param {() => number | null} [open]
+ */
+export function resolveBootStdio(open = defaultOpenBootLog) {
+  const fd = open();
+  return fd == null ? "ignore" : ["ignore", fd, fd];
+}
+
+const defaultBootServer = (port, pkgRoot) => {
+  const plan = bootSpawnPlan(port, pkgRoot);
+  const stdio = resolveBootStdio();
+  const child = spawn(plan.command, plan.args, { ...plan.options, stdio });
+  child.unref();
+  // The child dups the fd at spawn time; drop the parent's copy so the
+  // short-lived npx process leaves no handle open (both slots share one fd).
+  if (Array.isArray(stdio) && typeof stdio[1] === "number") {
+    try { closeSync(stdio[1]); } catch { /* already gone — nothing to do */ }
+  }
+  return child.pid ?? null;
+};
 const defaultSpawnSwapper = (port, pkgRoot) => runPlan(swapperSpawnPlan(port, pkgRoot));
 
 /** Default: read the swapper's durable verdict (pid + ok) if present. */
@@ -279,7 +324,8 @@ export async function ensureServer(opts) {
     if (!ready.ok) {
       throw new Error(
         `the packaged server did not become ready on ${url} within ${timeoutMs} ms — ` +
-          `check ~/.shipwright-webui/server-manual.log`,
+          `check ${bootLogPath()} (if that file is empty or absent, its directory was unwritable — ` +
+          `re-run from a terminal to see the server's output directly)`,
       );
     }
     result = { ...result, pid, version: ready.probe.version };

package/lib/util.mjs

@@ -1,83 +1,88 @@
-/**
- * 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: "[..]",
-});
+/**
+ * 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":
+      // Coupled to uv: the whole stack runs via `uv run`, which resolves a
+      // uv-MANAGED Python — a system python3 is neither required nor sufficient.
+      // Lead with the uv path; the OS package manager / python.org is the fallback.
+      return win
+        ? "install Python 3.11+ via uv (`uv python install 3.11`) — or from https://www.python.org/downloads/ (NOT the Microsoft Store stub)"
+        : "install Python 3.11+ via uv (`uv python install 3.11`) — or your package manager (e.g. `brew install python@3.11`)";
+    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 win
+        ? 'powershell -c "irm https://claude.ai/install.ps1 | iex"'
+        : "curl -fsSL https://claude.ai/install.sh | bash";
+    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: "[..]",
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svenroth-ai/shipwright",
-  "version": "0.24.2-next.0",
+  "version": "0.24.4-next.0",
   "description": "One command to install AND update Shipwright — the /shipwright-* SDLC plugins and the Command Center. Run `npx @svenroth-ai/shipwright@latest`.",
   "type": "module",
   "bin": {
@@ -50,6 +50,7 @@
     "@lydell/node-pty": "^1.1.0",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
+    "cron-parser": "^5.5.0",
     "hono": "^4.12.34",
     "ignore": "^5.3.2",
     "p-queue": "^9.2.0",