@pithy-sh/cli 0.1.0

package/src/dev/ports.ts

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { execFile } from "node:child_process";
+import net from "node:net";
+import { promisify } from "node:util";
+import { ConflictError } from "@pithy-sh/core/src/error/pithyError";
+
+const run = promisify(execFile);
+
+/**
+ * Try to bind `port` on `host`, resolving `true` when it is free and `false` when it is taken.
+ * The dual-stack primitive: a port is only usable if this succeeds on **both** `127.0.0.1` and `::1`
+ * (Vite binds IPv6-only, wrangler binds both families), so a loopback check on one family is not enough.
+ */
+export function tryBind(port: number, host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    srv.listen(port, host);
+  });
+}
+
+/** The bind seam — real {@link tryBind} in production, a stub in tests. */
+export type TryBind = (port: number, host: string) => Promise<boolean>;
+
+/**
+ * Assert a worker's **pinned** port is free — the deliberate divergence from CMS `pickPort`.
+ *
+ * The port is authoritative: it comes from the feature's `.dev.config.json`, assigned once at feature
+ * creation and held for the feature's life. So this only verifies; it never scans forward to another
+ * port. A worker that silently drifts off its pinned port breaks every sibling that was told its address
+ * ahead of time, so a conflict is reported, not worked around. The port must be free on **both** loopback
+ * families; a failure on either aborts the whole `pithy dev` session with one actionable error.
+ */
+export async function verifyPinnedPort(name: string, port: number, bind: TryBind = tryBind): Promise<void> {
+  const freeV4 = await bind(port, "127.0.0.1");
+  const freeV6 = await bind(port, "::1");
+  if (freeV4 && freeV6) return;
+  throw new ConflictError({
+    message: `Port ${port} for worker "${name}" is already in use.`,
+    action: "Stop whatever is holding it, then run pithy dev again.",
+    detail: `free on 127.0.0.1=${freeV4}, ::1=${freeV6}`,
+  });
+}
+
+/** Whether `pid` is a live process — `process.kill(pid, 0)` probes without signaling. */
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Sleep seam — real `setTimeout` in production, controllable in tests. */
+export type Sleep = (ms: number) => Promise<void>;
+const realSleep: Sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Poll until `pid` is dead or `timeoutMs` elapses; resolves `true` if it exited, `false` on timeout. */
+export async function waitForExit(
+  pid: number,
+  timeoutMs: number,
+  deps: { isAlive?: (pid: number) => boolean; sleep?: Sleep } = {},
+): Promise<boolean> {
+  const alive = deps.isAlive ?? isAlive;
+  const sleep = deps.sleep ?? realSleep;
+  const start = Date.now();
+  for (;;) {
+    if (!alive(pid)) return true;
+    if (Date.now() - start > timeoutMs) return false;
+    await sleep(100);
+  }
+}
+
+/** Look up the pids listening on a TCP `port` — the real one shells out to `lsof`. */
+export type LsofPort = (port: number) => Promise<number[]>;
+
+/** `lsof -ti tcp:<port>` → the pids holding it, or `[]` when lsof is missing or errors. */
+export const lsofPort: LsofPort = async (port) => {
+  try {
+    const { stdout } = await run("lsof", ["-ti", `tcp:${port}`]);
+    return stdout
+      .trim()
+      .split(/\s+/)
+      .map(Number)
+      .filter((n) => Number.isInteger(n) && n > 0);
+  } catch {
+    return [];
+  }
+};
+
+/** Look up a pid's full command line — the sweep's scope filter. */
+export type ProcessCommand = (pid: number) => Promise<string | null>;
+
+/** `ps -o args= -p <pid>` → the pid's command line, or `null` when it is gone or `ps` is unavailable. */
+export const psCommand: ProcessCommand = async (pid) => {
+  try {
+    const { stdout } = await run("ps", ["-o", "args=", "-p", String(pid)]);
+    const line = stdout.trim();
+    return line === "" ? null : line;
+  } catch {
+    return null;
+  }
+};
+
+/** Look up a pid's parent — walked upward so the sweep never signals its own ancestry. */
+export type ParentPid = (pid: number) => Promise<number | null>;
+
+/** `ps -o ppid= -p <pid>` → the parent pid, or `null` when it is gone or `ps` is unavailable. */
+export const psParent: ParentPid = async (pid) => {
+  try {
+    const { stdout } = await run("ps", ["-o", "ppid=", "-p", String(pid)]);
+    const ppid = Number(stdout.trim());
+    return Number.isInteger(ppid) && ppid > 0 ? ppid : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The binaries the sweep owns: the Workers runtime and its supervisor. */
+const WORKER_BINARY = /^(workerd|wrangler)(\.[cm]?js)?$/;
+/** Launchers that run a script — the script name, not the launcher, says what the process is. */
+const SCRIPT_RUNNER = /^(node|bun|deno|npx|bunx)$/;
+
+/** The last path segment of `token`, stripped of a Windows `.exe` suffix. */
+function commandBase(token: string): string {
+  return (token.split("/").pop() ?? "").replace(/\.exe$/, "");
+}
+
+/**
+ * Whether a command line is one of ours to reap — `workerd` itself, or a `wrangler` launched directly or
+ * through a script runner (`node …/.bin/wrangler dev`, `bun x wrangler dev`).
+ *
+ * The sweep exists to clear a crashed session's orphans, not to clear the port. Anything else holding a
+ * pinned port is a genuine external conflict and must reach `verifyPinnedPort`, which reports it.
+ */
+export function isReapableDevCommand(command: string | null): boolean {
+  if (!command) return false;
+  const tokens = command.trim().split(/\s+/);
+  const exe = commandBase(tokens[0] ?? "");
+  if (WORKER_BINARY.test(exe)) return true;
+  if (!SCRIPT_RUNNER.test(exe)) return false;
+  return tokens.slice(1).some((token) => WORKER_BINARY.test(commandBase(token)));
+}
+
+/** This process and every ancestor of it — never signaled, whatever is holding a port. */
+async function ancestorPids(selfPid: number, parentOf: ParentPid): Promise<Set<number>> {
+  const chain = new Set<number>([selfPid]);
+  let pid = selfPid;
+  for (let depth = 0; depth < 64; depth += 1) {
+    const parent = await parentOf(pid);
+    if (parent === null || parent <= 1 || chain.has(parent)) break;
+    chain.add(parent);
+    pid = parent;
+  }
+  return chain;
+}
+
+/** Seams for {@link sweepStaleDevPorts}, so it can be driven without real `lsof`/`ps`/`kill`. */
+export interface SweepDeps {
+  lsof?: LsofPort;
+  isAlive?: (pid: number) => boolean;
+  kill?: (pid: number, signal: NodeJS.Signals) => void;
+  log?: (message: string) => void;
+  /** Command-line lookup, the scope filter (default: {@link psCommand}). */
+  commandOf?: ProcessCommand;
+  /** Parent lookup, for the ancestry guard (default: {@link psParent}). */
+  parentOf?: ParentPid;
+  /** Pids the previous session recorded in `.dev-state.json` — ours by construction, reaped whatever they run. */
+  knownPids?: readonly number[];
+  /** This process's pid (default: `process.pid`). */
+  selfPid?: number;
+}
+
+/**
+ * Reap orphaned `workerd`/`wrangler` processes still holding the pinned dev ports — a crashed previous
+ * session must not block startup. Mirrors the CMS zombie-workerd sweep, with the scope its name promises:
+ * a pid is reaped only when it is one of ours — a `workerd`/`wrangler`-shaped command, or a pid the
+ * previous session recorded — and never when it is this process or one of its ancestors. Anything else
+ * is left alone and falls through to {@link verifyPinnedPort}, which reports an actionable conflict
+ * instead of silently SIGKILLing an unrelated dev server, database, or editor.
+ *
+ * Returns the pids reaped, so a re-run can report what it cleaned up.
+ */
+export async function sweepStaleDevPorts(ports: number[], deps: SweepDeps = {}): Promise<number[]> {
+  const lsof = deps.lsof ?? lsofPort;
+  const alive = deps.isAlive ?? isAlive;
+  const kill = deps.kill ?? ((pid, signal) => process.kill(pid, signal));
+  const commandOf = deps.commandOf ?? psCommand;
+  const parentOf = deps.parentOf ?? psParent;
+  const selfPid = deps.selfPid ?? process.pid;
+  const known = new Set(deps.knownPids ?? []);
+  const reaped: number[] = [];
+  // Resolved once, and only when something is actually about to be signaled.
+  let protectedPids: Set<number> | null = null;
+
+  for (const port of ports) {
+    for (const pid of await lsof(port)) {
+      if (pid === selfPid || !alive(pid)) continue;
+      const ours = known.has(pid);
+      if (!ours && !isReapableDevCommand(await commandOf(pid))) {
+        deps.log?.(`port ${port} is held by pid ${pid}, which is not a stale worker — leaving it`);
+        continue;
+      }
+      protectedPids ??= await ancestorPids(selfPid, parentOf);
+      if (protectedPids.has(pid)) continue;
+      deps.log?.(`reaping stale process on port ${port} (pid ${pid})`);
+      try {
+        kill(pid, "SIGKILL");
+        reaped.push(pid);
+      } catch {
+        // Already gone between the lsof and the kill — nothing to reap.
+      }
+    }
+  }
+  return reaped;
+}

package/src/dev/readyWatch.ts

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { dim } from "../terminal/style";
+
+/**
+ * How long a worker gets to match its ready signal before `pithy dev` names it (pithy-sh/pithy#429).
+ *
+ * Generous on purpose. The first `wrangler dev` of a session pays for a cold bundle, and a slow worker is
+ * not a broken one — a deadline that cries wolf teaches a developer to scroll past the one line that was
+ * ever going to reach them. The value below is longer than any healthy cold start we have measured and
+ * still short enough to arrive while the session is being watched.
+ *
+ * **It is measured from the spawn, not from the command.** The watch starts after the last child is
+ * running, so none of what `pithy dev` does first — `.dev.vars`, the host configs, stopping the previous
+ * session, the orphan sweep, both loopback families of every pinned port, the dev secrets — is on this
+ * clock. On a cold project that is tens of seconds, and charging it to a worker would make the budget a
+ * worker actually gets vary with how much housekeeping the run happened to need.
+ *
+ * `docs/commands/dev.md` states it in seconds, and says what it is measured from, in both places it
+ * appears; `readyWatchDocs.test.ts` pins both sentences to this constant.
+ */
+export const READY_DEADLINE_MS = 90_000;
+
+/**
+ * How often the still-waiting report repeats while at least one worker has not arrived.
+ *
+ * A single line at the deadline scrolls away exactly like the build error did — the other workers keep
+ * printing. Repeating is what makes it findable, and the value below is often enough to stay in view
+ * without becoming the noise it is trying to cut through.
+ */
+export const READY_REMINDER_MS = 30_000;
+
+/**
+ * Schedule `run` after `ms`; the returned function cancels it. The timer seam — real `setTimeout` in
+ * production, a hand-driven clock in tests, so nothing here waits ninety real seconds to be proven.
+ */
+export type Schedule = (ms: number, run: () => void) => () => void;
+
+/** The real timer. Unreferenced: the supervisor's lifetime is its children's, never a pending report's. */
+export const scheduleTimeout: Schedule = (ms, run) => {
+  const timer = setTimeout(run, ms);
+  timer.unref();
+  return () => clearTimeout(timer);
+};
+
+/**
+ * The report rendered for a person: who has not arrived, by name.
+ *
+ * *Still waiting* rather than *failed*, because the orchestrator does not know which it is — a worker
+ * this line names may be one bundle away from the banner. The reason it had to be a deadline that told
+ * you is said once, with the first report; the repeats are the short line alone.
+ *
+ * **The action line names the mechanism, never a cause.** It used to say `wrangler dev keeps running
+ * after a build error`, which is true of the case that prompted #429 and of nothing else the same
+ * deadline catches: a startup that hangs, a port that never binds, a binding that never resolves, and a
+ * `dev.command` worker — a Vite front end — where wrangler is not in the picture at all. What every one
+ * of them shares is the property that made the session look healthy: the child is *alive*, so no exit
+ * handler fires and nothing else in the run was ever going to mention it. That is what the line says,
+ * and it points at the worker's own output for the reason, which is the only place the reason exists.
+ *
+ * It names a restart because for the case that prompted this, a restart is not optional: a `wrangler dev`
+ * whose **first** build fails prints the error, keeps running, and does not rebuild when the file is fixed
+ * — measured against wrangler 4.123 on a Worker with an unresolvable import. Editing the file and waiting
+ * is the thing a developer would otherwise try, and it is the one thing that cannot work.
+ */
+export function stillWaitingLines(waiting: readonly string[], first: boolean): string[] {
+  const line = `Still waiting on: ${waiting.join(", ")}.`;
+  if (!first) return [line];
+  return [
+    line,
+    dim("  A worker that never becomes ready keeps running, so nothing else reports it."),
+    dim("  Each one's own output above says why. Fix it and run pithy dev again."),
+  ];
+}
+
+/** What {@link watchReady} needs: the set that has not arrived, somewhere to say it, and a clock. */
+export interface ReadyWatchOptions {
+  /** The workers yet to match their ready signal, in start order. Read afresh at every tick. */
+  pending: () => readonly string[];
+  /**
+   * Say it. Handed the set rather than a rendered line, because the two audiences render it differently:
+   * a person gets {@link stillWaitingLines}, and an agent driving `pithy dev --json` gets a record it can
+   * read. A seam that emitted prose would have made the machine-readable half unbuildable without parsing
+   * our own sentence back out of it.
+   *
+   * `first` is true for the report at the deadline and false for every repeat.
+   */
+  report: (waiting: readonly string[], first: boolean) => void;
+  /** Timer seam (default {@link scheduleTimeout}). */
+  schedule?: Schedule;
+  /** How long before the first report (default {@link READY_DEADLINE_MS}). */
+  deadlineMs?: number;
+  /** How long between repeats while the set stays non-empty (default {@link READY_REMINDER_MS}). */
+  reminderMs?: number;
+}
+
+/** A running watch. `stop()` cancels the pending timer and is safe to call more than once. */
+export interface ReadyWatch {
+  stop: () => void;
+}
+
+/**
+ * Watch for the workers that start and never become ready, and name them.
+ *
+ * `wrangler dev` does not exit when a build fails — it prints the error and keeps running — so a broken
+ * worker is a live child that never matches its ready signal. The banner waits on the whole set, so it
+ * never fires, and until this the session simply proceeded looking healthy with the error forty lines up
+ * the scrollback. This is the deadline that names it, and keeps naming it while it stays true.
+ *
+ * The set is read at every tick rather than captured, so a worker that arrives late drops out of the next
+ * report on its own. An empty set ends the watch: everything arrived, and the banner says the rest.
+ */
+export function watchReady(options: ReadyWatchOptions): ReadyWatch {
+  const schedule = options.schedule ?? scheduleTimeout;
+  const deadlineMs = options.deadlineMs ?? READY_DEADLINE_MS;
+  const reminderMs = options.reminderMs ?? READY_REMINDER_MS;
+
+  let cancel: (() => void) | null = null;
+  let stopped = false;
+  let reported = false;
+
+  const tick = () => {
+    cancel = null;
+    if (stopped) return;
+    const waiting = options.pending();
+    if (waiting.length === 0) return;
+    options.report(waiting, !reported);
+    reported = true;
+    cancel = schedule(reminderMs, tick);
+  };
+
+  cancel = schedule(deadlineMs, tick);
+
+  return {
+    stop: () => {
+      stopped = true;
+      cancel?.();
+      cancel = null;
+    },
+  };
+}

package/src/dev/state.ts

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFileSync, unlinkSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "../project/atomic";
+
+/**
+ * `.dev-state.json` — the running `pithy dev` session's live state, git-ignored, at the worktree root.
+ *
+ * Distinct from `.dev.config.json` (the feature's fixed dev config: reserved ports, per-worker origins,
+ * written once at feature creation). This file is ephemeral: the supervising pid, when it started, its
+ * child pids, and each worker's port + pid. A re-run reads it to stop the previous session before it
+ * spawns; shutdown removes it. It is rewritten fresh every session, so a corrupt file is discarded, not
+ * an error — there is nothing to recover.
+ */
+
+/** One worker's live entry in the running session — the port it holds and the pid serving it. */
+export const DevWorkerState = z
+  .object({
+    port: z.number().int().positive().describe("The local port this worker is bound to for the session."),
+    pid: z.number().int().describe("The spawned child process id serving this worker (its process-group leader)."),
+  })
+  .describe("A single worker's live process state within a running pithy dev session.");
+export type DevWorkerState = z.output<typeof DevWorkerState>;
+
+/** The `.dev-state.json` document: the supervising session and every worker it started. */
+export const DevState = z
+  .object({
+    pid: z.number().int().describe("The pid of the supervising pithy dev process that owns this session."),
+    startedAt: z.string().describe("When the session started, ISO-8601 — for operator diagnostics."),
+    childPids: z.array(z.number().int()).describe("Every spawned child pid, so a crashed session can be reaped."),
+    workers: z
+      .record(z.string(), DevWorkerState)
+      .describe("Each started worker's live port and pid, keyed by worker name."),
+  })
+  .describe("The live state of a running pithy dev session (git-ignored .dev-state.json).");
+export type DevState = z.output<typeof DevState>;
+
+/** The dev-state path for a project/worktree root: `<projectDir>/.dev-state.json`. */
+export function devStatePath(projectDir: string): string {
+  return join(projectDir, ".dev-state.json");
+}
+
+/**
+ * Read the previous session's state, or `null` when the file is absent, corrupt, or invalid. Unlike the
+ * feature dev config, a bad `.dev-state.json` never throws: it is a disposable session artifact this run
+ * overwrites, so an unreadable one is simply treated as "no previous session".
+ */
+export async function readDevState(path: string): Promise<DevState | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  const parsed = DevState.safeParse(safeJson(raw));
+  return parsed.success ? parsed.data : null;
+}
+
+/** Zod-validate then write the session state atomically (pretty JSON, trailing newline). */
+export async function writeDevState(path: string, state: DevState): Promise<void> {
+  const validated = DevState.parse(state);
+  await writeFileAtomic(path, `${JSON.stringify(validated, null, 2)}\n`);
+}
+
+/**
+ * Remove the state file **only when it still points at us** — race-safe teardown. A newer orchestrator
+ * (a re-run that already replaced the file) owns it now, so an older shutting-down process must not delete
+ * the newer session's state. Synchronous so it runs reliably inside a shutdown/exit path.
+ */
+export function removeDevState(path: string, ownPid: number): void {
+  try {
+    const current = DevState.safeParse(safeJson(readFileSync(path, "utf8")));
+    if (current.success && current.data.pid === ownPid) unlinkSync(path);
+  } catch {
+    // Already gone, or never ours — nothing to remove.
+  }
+}
+
+/** Parse JSON, returning `undefined` on failure so the caller's Zod parse decides validity. */
+function safeJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}