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

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/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.3-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": {