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

package/bin/shipwright.mjs

@@ -13,7 +13,7 @@
  * the installed plugin set changed.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -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);
@@ -178,8 +222,39 @@ export async function main(argv = process.argv.slice(2), log = (m) => console.lo
   return exitCode;
 }
 
+/**
+ * True when this module is the process entry point — INCLUDING when it is
+ * invoked through a symlink. npm/npx install the executable as a symlink in
+ * `node_modules/.bin/`, so on macOS/Linux `process.argv[1]` is that symlink
+ * while Node realpaths the entry for `import.meta.url` (the real file). A plain
+ * `path.resolve` comparison of the two therefore never matches and `main()`
+ * never runs — the bootstrapper exits 0 having done NOTHING (the silent-no-op
+ * bug: `npx @svenroth-ai/shipwright` printed nothing on the Mac). Windows hid it
+ * because its npm `.cmd` shim invokes node with the REAL path, not a symlink.
+ *
+ * Fix: realpath BOTH sides before comparing, so a symlink and its target compare
+ * equal. The realpath is applied SYMMETRICALLY: if EITHER side cannot be
+ * realpath'd (`realpathSync` throws — ENOENT from an odd launcher, or a
+ * virtualized path such as Yarn PnP that has no on-disk realpath, or EACCES /
+ * ELOOP), BOTH sides fall back to plain `path.resolve`. A mixed branch — one
+ * side realpath'd, the other only resolved — would spuriously mismatch and
+ * re-introduce the very silent-no-op this fixes; symmetry rules that out. An
+ * entry-point guard must also never crash the bootstrapper on import, hence the
+ * catch. The real npx entry always has an existing argv[1], so both sides
+ * realpath and canonicalize identically.
+ */
+export function isMainModule(argv1, metaUrl) {
+  if (!argv1) return false;
+  const self = fileURLToPath(metaUrl);
+  try {
+    return realpathSync(argv1) === realpathSync(self);
+  } catch {
+    return path.resolve(argv1) === path.resolve(self);
+  }
+}
+
 // Run only when invoked as a script — importing (tests) stays side-effect free.
-if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+if (isMainModule(process.argv[1], import.meta.url)) {
   main().then((code) => process.exit(code)).catch((e) => {
     console.error(`[shipwright] fatal: ${String(e?.stack ?? e)}`);
     process.exit(1);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svenroth-ai/shipwright",
-  "version": "0.24.1-next.0",
+  "version": "0.24.3-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",