@svenroth-ai/shipwright 0.24.1-next.0

package/scripts/deploy-swap.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * deploy-swap.mjs — the detached half of the production deploy.
+ *
+ * The deploy scripts used to kill the old server and start the new one inline.
+ * Run from the Command Center's embedded terminal, the caller is a DESCENDANT of
+ * the Hono server it kills (Hono -> node-pty shell -> claude -> the script), so
+ * the kill tore down the ConPTY and took the caller with it: the "start the new
+ * server" step never ran. Fresh build on disk, NO server, no diagnostic — the
+ * process that would have printed one was the one that died (outage 2026-07-14).
+ *
+ * The caller spawns THIS helper detached *before* any kill happens, so it outlives
+ * that cascade and finishes what the caller cannot. Empirically verified: a
+ * `Start-Process` (Windows) / `nohup` (POSIX) child survives the kill.
+ *
+ * Contract — the caller owns install + build (a failed build must leave the running
+ * server untouched: it never gets here); this helper owns kill -> start ->
+ * readiness -> post-restart heal -> durable status. Full story + evidence:
+ * .shipwright/planning/iterate/2026-07-14-deploy-self-kill.md
+ *
+ * Usage (from the deploy scripts, detached):  node scripts/deploy-swap.mjs --port 3847
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { stopOldServer, waitForServerUp } from './deploy-procs.mjs';
+
+const DEFAULT_PORT = 3847;
+const READY_TIMEOUT_MS = 12_000;
+const PORT_FREE_TIMEOUT_MS = 5_000;
+const SWAP_LOG_CAP_BYTES = 256 * 1024;
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repo = path.resolve(here, '..');
+const serverDir = path.join(repo, 'server');
+const logDir = path.join(os.homedir(), '.shipwright-webui');
+const SERVER_LOG = path.join(logDir, 'server-manual.log');
+const SWAP_LOG = path.join(logDir, 'deploy-swap.log');
+const STATUS_FILE = path.join(logDir, 'deploy-status.json');
+
+// --- Pure helpers (unit-tested in deploy-swap.test.mjs) --------------------
+
+/**
+ * Resolve the Hono port. Mirrors the callers' guards (the .ps1's `^\d{1,5}$`,
+ * which also keeps the cast under Int32.MaxValue, and the .sh's `${PORT:-3847}`)
+ * so caller and swapper can never disagree on the target.
+ *
+ * @param {Record<string, unknown>} [env]
+ * @returns {number}
+ */
+const isValidPort = (raw) => /^\d{1,5}$/.test(raw) && Number(raw) > 0;
+
+export function resolvePort(env = {}) {
+  const raw = env?.PORT === undefined || env?.PORT === null ? '' : String(env.PORT);
+  return isValidPort(raw) ? Number(raw) : DEFAULT_PORT;
+}
+
+/**
+ * `--port` (passed by the caller, which already resolved it for its own readiness
+ * poll and operator messages) wins over the environment. One rule, one resolved
+ * value in every sink; a malformed flag degrades instead of throwing.
+ *
+ * @param {string[]} [argv]
+ * @param {Record<string, unknown>} [env]
+ * @returns {{ port: number }}
+ */
+export function parseArgs(argv = [], env = {}) {
+  const i = argv.indexOf('--port');
+  const raw = i !== -1 && argv[i + 1] !== undefined ? String(argv[i + 1]) : '';
+  return { port: isValidPort(raw) ? Number(raw) : resolvePort(env) };
+}
+
+/**
+ * The durable record of the deploy outcome. Inside an embedded terminal the caller
+ * is killed mid-deploy, so it cannot be the one to report success or failure —
+ * that is precisely how the 2026-07-14 outage stayed invisible for hours.
+ *
+ * @param {{ok: unknown, port: unknown, pid?: unknown, ts: unknown, error?: unknown, readiness?: string}} o
+ */
+export function buildStatus({ ok, port, pid = null, ts, error = null, readiness = 'listener' }) {
+  return {
+    ok: Boolean(ok),
+    port: Number(port),
+    pid: pid === null || pid === undefined ? null : Number(pid),
+    ts: Number(ts),
+    error: error ?? null,
+    // How `ok` was established: 'listener' (the new child owns the port — the
+    // strong claim) or 'process-alive' (no lsof on this host; the child was
+    // merely still running). The caller reports the verdict, so it must be able
+    // to tell the two apart.
+    readiness,
+  };
+}
+
+// --- Side-effecting steps --------------------------------------------------
+
+function log(msg) {
+  const line = `[deploy-swap] ${new Date().toISOString()} ${msg}`;
+  console.log(line);
+  try {
+    fs.appendFileSync(SWAP_LOG, line + '\n');
+  } catch {
+    // The log is a convenience; never fail the deploy over it.
+  }
+}
+
+/** Last lines of the server log — the only thing that explains an EADDRINUSE or a crash on boot. */
+function serverLogTail(lines = 12) {
+  try {
+    return fs
+      .readFileSync(SERVER_LOG, 'utf-8')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .slice(-lines)
+      .join(' | ');
+  } catch {
+    return '(no server log)';
+  }
+}
+
+/**
+ * Open the server log — and NEVER let it block the deploy.
+ *
+ * `w` (truncate) matches the old `> $log`. But the file can be held by another
+ * instance: a second webui on a different PORT shares this path, and a server
+ * launched the old way (a `cmd` redirect) holds it with restrictive sharing, so
+ * openSync throws EBUSY. Losing the log is a nuisance; losing the SERVER because
+ * we could not open a log file would be the very outage this helper exists to
+ * prevent. Degrade: truncate -> append -> no log at all.
+ */
+function openServerLog() {
+  for (const flags of ['w', 'a']) {
+    try {
+      return fs.openSync(SERVER_LOG, flags);
+    } catch { /* held by another instance — try the next mode */ }
+  }
+  log(`WARNING: ${SERVER_LOG} is not writable — starting the server without a log`);
+  return 'ignore';
+}
+
+/** Start the freshly built server, detached, so it outlives THIS helper too. */
+function startServer(port) {
+  const out = openServerLog();
+  const child = spawn(
+    process.execPath,
+    ['--env-file-if-exists=../.env.local', 'dist/index.js'],
+    {
+      cwd: serverDir,
+      env: { ...process.env, PORT: String(port) },
+      detached: true,
+      stdio: ['ignore', out, out],
+      shell: false,
+    },
+  );
+  child.unref();
+  return child;
+}
+
+/**
+ * Post-restart ~/.claude.json heal. It used to sit in the CALLER — i.e. in code
+ * already dead by the time it matters, because the server-kill it waits on is the
+ * same kill that takes the caller down. Best effort: never gated on.
+ */
+function heal(label) {
+  try {
+    spawnSync(process.execPath, [path.join(here, 'repair-claude-json.mjs')], {
+      stdio: 'ignore',
+    });
+    log(`~/.claude.json integrity check done (${label})`);
+  } catch {
+    log(`~/.claude.json integrity check skipped (${label})`);
+  }
+}
+
+function writeStatus(status) {
+  try {
+    fs.writeFileSync(STATUS_FILE, JSON.stringify(status, null, 2) + '\n');
+  } catch (e) {
+    log(`could not write ${STATUS_FILE}: ${String(e)}`);
+  }
+}
+
+/**
+ * Keep the swapper's history, but bounded. server-manual.log is truncated on every
+ * deploy; this one is appended to (it must survive the restart that truncates the
+ * other), so without a cap it grows forever.
+ */
+function capSwapLog() {
+  try {
+    if (fs.statSync(SWAP_LOG).size <= SWAP_LOG_CAP_BYTES) return;
+    const kept = fs.readFileSync(SWAP_LOG, 'utf-8').slice(-SWAP_LOG_CAP_BYTES / 2);
+    fs.writeFileSync(SWAP_LOG, kept);
+  } catch { /* no log yet, or unreadable — nothing to cap */ }
+}
+
+async function main() {
+  fs.mkdirSync(logDir, { recursive: true });
+  capSwapLog();
+  // A stale status file from a PREVIOUS deploy must never be mistaken for this
+  // run's verdict by the (possibly still alive) caller.
+  fs.rmSync(STATUS_FILE, { force: true });
+
+  const { port } = parseArgs(process.argv.slice(2), process.env);
+  const finish = (ok, extra) => {
+    // The verdict is written BEFORE the (best-effort, possibly slow) heal, so a
+    // caller waiting on it is never blocked by a step that cannot change it.
+    writeStatus(buildStatus({ ok, port, ts: Date.now(), ...extra }));
+    log(ok ? `OK — ${extra.pid ? `server up on ${port} (pid ${extra.pid})` : 'done'}` : `FAILED — ${extra.error}`);
+    return ok;
+  };
+
+  log(`swap starting (port ${port}, pid ${process.pid})`);
+
+  // 1. Stop the old server. From here on the caller may die at any moment — this
+  //    kill tears down the ConPTY that hosts it.
+  const { freed, killed, survivor } = await stopOldServer(port, {
+    timeoutMs: PORT_FREE_TIMEOUT_MS,
+  });
+  log(killed.length ? `stopped PID(s): ${killed.join(' ')}` : `nothing was listening on ${port}`);
+
+  if (!freed) {
+    // The port never came free. Starting now would only hit EADDRINUSE and leave
+    // the machine with NOTHING. The old server is still up — worse than a fresh
+    // one, far better than none. Say so loudly and stop here.
+    heal('kill-failed');
+    return finish(false, {
+      readiness: 'listener',
+      error:
+        `port ${port} is still held by PID ${survivor} after ${PORT_FREE_TIMEOUT_MS} ms — ` +
+        `the OLD server is still running and was NOT replaced (nothing new was started)`,
+    });
+  }
+
+  // 2. Start the fresh build.
+  const child = startServer(port);
+  log(`started node dist/index.js (pid ${child.pid})`);
+
+  // 3. Confirm OUR child took the port (or, without lsof, that it is alive).
+  const { ok, readiness, exited, exitCode } = await waitForServerUp(port, child, {
+    timeoutMs: READY_TIMEOUT_MS,
+  });
+
+  // 4. Heal ~/.claude.json in the clean window: the old embedded sessions are
+  //    dead and a UI reload has not spawned new ones yet.
+  heal('post-restart');
+
+  return finish(ok, {
+    pid: ok ? child.pid : null,
+    readiness,
+    error: ok
+      ? null
+      : exited
+        ? `the new server exited on startup (code ${exitCode}) — ${serverLogTail()}`
+        : `the new server did not take port ${port} within ${READY_TIMEOUT_MS} ms — ${serverLogTail()}`,
+  });
+}
+
+// Only run when invoked as a script — importing it (tests) must stay side-effect free.
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  main()
+    .then((ok) => process.exit(ok ? 0 : 1))
+    .catch((e) => {
+      // A throw AFTER the kill (spawn EACCES, an unwritable log) would otherwise
+      // leave no server AND no status file — the failure mode that made the
+      // original outage invisible. The record survives even the unexpected.
+      try {
+        const { port } = parseArgs(process.argv.slice(2), process.env);
+        writeStatus(buildStatus({ ok: false, port, ts: Date.now(), error: `swap crashed: ${String(e)}` }));
+      } catch { /* nothing left to do */ }
+      log(`CRASHED — ${String(e)}`);
+      process.exit(1);
+    });
+}

package/scripts/kill-targets.js

@@ -0,0 +1,140 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * Port-selection helper for dev-restart.js.
+ *
+ * Pure function: no subprocess calls, no filesystem. The kill-scope is
+ * exactly the two configured ports (Hono + Vite), each with a default.
+ *
+ * Worktree-parallel contract: if the operator sets PORT and VITE_PORT for
+ * their worktree, this function returns ONLY those ports — nothing
+ * hardcoded, nothing leaked from a different worktree's config. The
+ * historic VITE_ALT_PORT=5177 hardcode was removed in v0.3.2.
+ */
+
+const DEFAULT_HONO_PORT = 3847;
+const DEFAULT_VITE_PORT = 5173;
+
+/**
+ * @param {Record<string,string|undefined>} env
+ * @param {string} _platform  // reserved for future platform-specific overrides
+ * @returns {number[]} deduped, finite, positive kill targets
+ */
+function computeKillTargets(env, _platform) {
+  const honoPort = parsePort(env.PORT, DEFAULT_HONO_PORT);
+  const vitePort = parsePort(env.VITE_PORT, DEFAULT_VITE_PORT);
+  const seen = new Set();
+  const out = [];
+  for (const p of [honoPort, vitePort]) {
+    if (!Number.isFinite(p) || p <= 0) continue;
+    if (seen.has(p)) continue;
+    seen.add(p);
+    out.push(p);
+  }
+  return out;
+}
+
+function parsePort(raw, fallback) {
+  if (raw === undefined || raw === null || raw === '') return fallback;
+  const n = parseInt(String(raw), 10);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return n;
+}
+
+/**
+ * Extract the numeric port from a netstat "Local Address" token.
+ *
+ * Handles IPv4 (`0.0.0.0:5173`, `127.0.0.1:5173`) and IPv6
+ * (`[::]:5173`, `[::1]:5173`) — the port is always the run of digits after
+ * the LAST colon. Returns null when no numeric port is present.
+ *
+ * @param {string} addr
+ * @returns {number|null}
+ */
+function localAddressPort(addr) {
+  if (typeof addr !== 'string') return null;
+  const idx = addr.lastIndexOf(':');
+  if (idx === -1) return null;
+  const portStr = addr.slice(idx + 1);
+  if (!/^\d+$/.test(portStr)) return null;
+  return Number(portStr);
+}
+
+/**
+ * Structurally parse Windows `netstat -ano -p TCP` output and return the PIDs
+ * of processes LISTENING on one of the given ports.
+ *
+ * Fixes F16 (D11): the prior `netstat … | findstr :<port>` did plain substring
+ * matching over the whole line with no state filter, so it also caught
+ *   (1) ESTABLISHED browser sockets whose FOREIGN address ended `:<port>`, and
+ *   (2) port-prefix collisions (`:5173` is a substring of `:51730`),
+ * and taskkill /F /T'd those unrelated PIDs. This parser requires
+ * state === LISTENING AND an EXACT local-address port match.
+ *
+ * Handles IPv4 AND IPv6: plain `netstat -ano` output labels IPv6 rows proto
+ * `TCP` (distinguished by the `[::]` address), and some Windows builds use
+ * `TCPv6` — the proto check is `startsWith('TCP')` to cover both. UDP rows
+ * (`*:*` foreign, no State column, 4 tokens) fall out via the < 5 / state
+ * checks. Feed it `netstat -ano` (NOT `-p TCP`, which drops IPv6 listeners).
+ *
+ * @param {string} netstatOutput  raw stdout of `netstat -ano`
+ * @param {number[]} ports        kill-target ports (already validated)
+ * @returns {string[]}            deduped PID strings, in first-seen order
+ */
+function parseWindowsListenerPids(netstatOutput, ports) {
+  const wanted = new Set(ports.map(Number));
+  const seen = new Set();
+  const pids = [];
+  for (const rawLine of String(netstatOutput ?? '').split(/\r?\n/)) {
+    const cols = rawLine.trim().split(/\s+/);
+    // A TCP row is: Proto  LocalAddr  ForeignAddr  State  PID
+    if (cols.length < 5) continue;
+    if (!cols[0].toUpperCase().startsWith('TCP')) continue;
+    const state = cols[cols.length - 2].toUpperCase();
+    if (state !== 'LISTENING') continue;
+    const port = localAddressPort(cols[1]);
+    if (port === null || !wanted.has(port)) continue;
+    const pid = cols[cols.length - 1];
+    if (!/^\d+$/.test(pid)) continue;
+    if (seen.has(pid)) continue;
+    seen.add(pid);
+    pids.push(pid);
+  }
+  return pids;
+}
+
+/**
+ * Build the POSIX lsof command that lists only LISTENING PIDs on the given
+ * ports. The `-sTCP:LISTEN` state filter is the POSIX half of the F16 fix —
+ * without it, `lsof -ti tcp:<ports>` returns every socket (incl. the
+ * ESTABLISHED browser connections) bound to those ports.
+ *
+ * Argument ORDER is load-bearing: the address (`tcp:<ports>`) MUST stay bound
+ * to `-i`, with `-sTCP:LISTEN` APPENDED AFTER it. If `-sTCP:LISTEN` sat between
+ * `-i` and its address, `-i` would be addressless (its argument starts with
+ * `-`) → it selects EVERY internet file and `-sTCP:LISTEN` then narrows to ALL
+ * listeners machine-wide, killing every listener — the inverse of this fix.
+ *
+ * The command is run via `execSync` (shell), so — although callers pass ports
+ * already validated by computeKillTargets — every port is coerced to a positive
+ * integer and non-integers are dropped here too. That keeps the exported helper
+ * injection-proof regardless of caller (defense in depth at the boundary). An
+ * empty filtered port list returns '' (kill nothing) so a portless
+ * `lsof -ti tcp:` (which would select ALL TCP files) can never be built.
+ *
+ * @param {number[]} ports
+ * @returns {string} shell command string for execSync ('' when no valid ports)
+ */
+function buildLsofCommand(ports) {
+  const portList = ports
+    .map(Number)
+    .filter((p) => Number.isInteger(p) && p > 0)
+    .join(',');
+  if (portList === '') return '';
+  return `lsof -ti tcp:${portList} -sTCP:LISTEN`;
+}
+
+module.exports = {
+  computeKillTargets,
+  parseWindowsListenerPids,
+  buildLsofCommand,
+};