@nwire/supervisor 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/health.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Health-check helpers for `RunnerSupervisor.start({ healthCheck })`.
+ */
+import type { ManagedProcess } from "./supervisor.js";
+/**
+ * Poll a URL until it returns a 2xx response. The supervisor's
+ * `healthIntervalMs` drives retry cadence — this helper just performs one
+ * attempt and returns a boolean.
+ */
+export declare function httpHealthCheck(urlFactory: (proc: ManagedProcess) => string): (proc: ManagedProcess) => Promise<boolean>;
+/** Wait for `http://localhost:<port>/_nwire/manifest` to respond. */
+export declare function inspectHealthCheck(port: number): (proc: ManagedProcess) => Promise<boolean>;

package/dist/health.js

@@ -0,0 +1,24 @@
+/**
+ * Health-check helpers for `RunnerSupervisor.start({ healthCheck })`.
+ */
+/**
+ * Poll a URL until it returns a 2xx response. The supervisor's
+ * `healthIntervalMs` drives retry cadence — this helper just performs one
+ * attempt and returns a boolean.
+ */
+export function httpHealthCheck(urlFactory) {
+    return async (proc) => {
+        const url = urlFactory(proc);
+        try {
+            const res = await fetch(url);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/** Wait for `http://localhost:<port>/_nwire/manifest` to respond. */
+export function inspectHealthCheck(port) {
+    return httpHealthCheck(() => `http://localhost:${port}/_nwire/manifest`);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@nwire/supervisor` — process supervisor for dev tooling.
+ *
+ * Spawns Nwire wire/app processes, watches them, streams their stdout/stderr
+ * into a ring buffer, runs optional health checks, and stops them gracefully
+ * (SIGTERM → grace window → SIGKILL). Used by `nwire dev` and Studio's vite
+ * dev server; not a foundation primitive — runtime apps do not depend on it.
+ */
+export { RunnerSupervisor, type ManagedProcess, type ProcessStatus, type StartOptions, type LogLine, } from "./supervisor.js";
+export { httpHealthCheck, inspectHealthCheck } from "./health.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@nwire/supervisor` — process supervisor for dev tooling.
+ *
+ * Spawns Nwire wire/app processes, watches them, streams their stdout/stderr
+ * into a ring buffer, runs optional health checks, and stops them gracefully
+ * (SIGTERM → grace window → SIGKILL). Used by `nwire dev` and Studio's vite
+ * dev server; not a foundation primitive — runtime apps do not depend on it.
+ */
+export { RunnerSupervisor, } from "./supervisor.js";
+export { httpHealthCheck, inspectHealthCheck } from "./health.js";

package/dist/supervisor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `RunnerSupervisor` — spawns and watches Nwire wire processes.
+ *
+ * One supervisor manages N child processes. Each process runs
+ * `apps/run.ts` with `NWIRE_TOPOLOGY=<name>` set and a port from the
+ * topology spec. Stdout/stderr land in a per-process ring buffer + are
+ * fanned out to subscribers (Studio's SSE log viewer).
+ *
+ * Lifecycle:
+ *   start(topology) → spawn → wait-for-health → 'running'
+ *   stop(processId) → SIGTERM → drain → 'exited'
+ *   crash → child exits non-zero unprompted → 'crashed'
+ *
+ * The supervisor itself does NOT know how to compose topologies. It
+ * shells out to a wire entry script (typically under `__wires__/`).
+ * That keeps the runner generic — same supervisor can host any Nwire app's
+ * entry script.
+ */
+import { EventEmitter } from "node:events";
+export type ProcessStatus = "idle" | "starting" | "running" | "stopping" | "exited" | "crashed";
+export interface LogLine {
+    readonly seq: number;
+    /** ISO timestamp captured when the line was emitted. */
+    readonly ts: string;
+    readonly stream: "stdout" | "stderr";
+    readonly line: string;
+}
+export interface ManagedProcess {
+    readonly id: string;
+    readonly topology: string;
+    readonly port?: number;
+    readonly startedAt: string;
+    status: ProcessStatus;
+    pid?: number;
+    exitCode?: number | null;
+    signal?: string | null;
+    /** Last seen error message, if status is 'crashed'. */
+    errorMessage?: string;
+}
+export interface StartOptions {
+    /** Topology name (matches `apps/topologies/<name>.topology.ts`). */
+    readonly topology: string;
+    /** Optional port override. Forwarded as `PORT=<port>` to the child. */
+    readonly port?: number;
+    /** Repo root — the cwd the child runs in. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /** Entry script (relative to cwd). Defaults to `apps/run.ts`. */
+    readonly entry?: string;
+    /** Command + args to invoke. Defaults to `['pnpm', 'exec', 'vite-node', entry]`. */
+    readonly command?: readonly string[];
+    /** Additional env vars. Merged into `process.env`. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Ring-buffer capacity for stdout/stderr lines. Default 2000. */
+    readonly bufferSize?: number;
+    /**
+     * Optional health check called repeatedly until it returns truthy. When
+     * it returns truthy the process transitions to `'running'`. If absent,
+     * the process moves to `'running'` immediately after spawn.
+     */
+    readonly healthCheck?: (proc: ManagedProcess) => Promise<boolean>;
+    /** Health check poll interval (ms). Default 500. */
+    readonly healthIntervalMs?: number;
+    /** Health check timeout (ms). Default 30_000. */
+    readonly healthTimeoutMs?: number;
+}
+export declare class RunnerSupervisor extends EventEmitter {
+    private readonly states;
+    list(): readonly ManagedProcess[];
+    get(id: string): ManagedProcess | undefined;
+    recentLogs(id: string, n?: number): readonly LogLine[];
+    /**
+     * Spawn a child process running the given topology. Returns the
+     * ManagedProcess record. Health check runs in the background; subscribe
+     * via `on('status', ...)` to observe transitions.
+     */
+    start(options: StartOptions): Promise<ManagedProcess>;
+    private runHealthCheck;
+    /**
+     * Send SIGTERM to a managed process; wait until it exits. After
+     * `graceMs` (default 5s) escalate to SIGKILL.
+     */
+    stop(id: string, graceMs?: number): Promise<void>;
+    /** Stop every managed process. */
+    stopAll(): Promise<void>;
+    /** Drop the record for an exited process. No-op if still running. */
+    forget(id: string): void;
+}

package/dist/supervisor.js

@@ -0,0 +1,221 @@
+/**
+ * `RunnerSupervisor` — spawns and watches Nwire wire processes.
+ *
+ * One supervisor manages N child processes. Each process runs
+ * `apps/run.ts` with `NWIRE_TOPOLOGY=<name>` set and a port from the
+ * topology spec. Stdout/stderr land in a per-process ring buffer + are
+ * fanned out to subscribers (Studio's SSE log viewer).
+ *
+ * Lifecycle:
+ *   start(topology) → spawn → wait-for-health → 'running'
+ *   stop(processId) → SIGTERM → drain → 'exited'
+ *   crash → child exits non-zero unprompted → 'crashed'
+ *
+ * The supervisor itself does NOT know how to compose topologies. It
+ * shells out to a wire entry script (typically under `__wires__/`).
+ * That keeps the runner generic — same supervisor can host any Nwire app's
+ * entry script.
+ */
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+/**
+ * Windows toggle — `pnpm`, `vite-node`, and most other CLIs we spawn ship
+ * as `.cmd` shims on Windows. `spawn` only resolves `.exe` by default,
+ * so without `shell:true` every supervised child ENOENTs on Win.
+ */
+const IS_WIN = process.platform === "win32";
+export class RunnerSupervisor extends EventEmitter {
+    states = new Map();
+    list() {
+        return Array.from(this.states.values()).map((s) => s.proc);
+    }
+    get(id) {
+        return this.states.get(id)?.proc;
+    }
+    recentLogs(id, n) {
+        const state = this.states.get(id);
+        if (!state)
+            return [];
+        const limit = n ?? state.buffer.length;
+        return state.buffer.slice(-limit);
+    }
+    /**
+     * Spawn a child process running the given topology. Returns the
+     * ManagedProcess record. Health check runs in the background; subscribe
+     * via `on('status', ...)` to observe transitions.
+     */
+    async start(options) {
+        const id = randomUUID();
+        const startedAt = new Date().toISOString();
+        const entry = options.entry ?? "apps/run.ts";
+        const cwd = options.cwd ?? process.cwd();
+        const command = options.command ?? ["pnpm", "exec", "vite-node", entry];
+        const [cmd, ...args] = command;
+        if (!cmd)
+            throw new Error("RunnerSupervisor: empty command");
+        const env = {
+            ...process.env,
+            NWIRE_TOPOLOGY: options.topology,
+            ...(options.port ? { PORT: String(options.port) } : {}),
+            ...(options.env ?? {}),
+        };
+        const child = spawn(cmd, args, {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: IS_WIN,
+        });
+        const proc = {
+            id,
+            topology: options.topology,
+            port: options.port,
+            startedAt,
+            status: "starting",
+            pid: child.pid,
+        };
+        const state = {
+            proc,
+            child,
+            buffer: [],
+            bufferSize: options.bufferSize ?? 2000,
+            seq: 0,
+        };
+        this.states.set(id, state);
+        const capture = (stream) => (chunk) => {
+            const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            for (const raw of text.split(/\r?\n/)) {
+                if (!raw)
+                    continue;
+                const line = {
+                    seq: state.seq++,
+                    ts: new Date().toISOString(),
+                    stream,
+                    line: raw,
+                };
+                state.buffer.push(line);
+                while (state.buffer.length > state.bufferSize)
+                    state.buffer.shift();
+                this.emit("log", id, line);
+            }
+        };
+        child.stdout?.on("data", capture("stdout"));
+        child.stderr?.on("data", capture("stderr"));
+        child.on("exit", (code, signal) => {
+            proc.exitCode = code;
+            proc.signal = signal;
+            // Distinguish clean stop (we asked for it) from a crash.
+            if (proc.status === "stopping") {
+                proc.status = "exited";
+            }
+            else if (code === 0) {
+                proc.status = "exited";
+            }
+            else {
+                proc.status = "crashed";
+                proc.errorMessage = `child exited with code ${code}${signal ? ` (${signal})` : ""}`;
+            }
+            this.emit("status", id, proc.status, proc);
+        });
+        child.on("error", (err) => {
+            proc.status = "crashed";
+            proc.errorMessage = err.message;
+            this.emit("status", id, "crashed", proc);
+        });
+        this.emit("status", id, "starting", proc);
+        // Background health check. Don't await — return the proc record so the
+        // caller can subscribe; the status transition fires when health passes.
+        void this.runHealthCheck(state, options);
+        return proc;
+    }
+    async runHealthCheck(state, options) {
+        if (!options.healthCheck) {
+            // No health check: trust the spawn. Transition after one tick so
+            // listeners attached synchronously see the change.
+            setImmediate(() => {
+                if (state.proc.status === "starting") {
+                    state.proc.status = "running";
+                    this.emit("status", state.proc.id, "running", state.proc);
+                }
+            });
+            return;
+        }
+        const interval = options.healthIntervalMs ?? 500;
+        const timeout = options.healthTimeoutMs ?? 30_000;
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+            if (state.proc.status !== "starting")
+                return;
+            try {
+                if (await options.healthCheck(state.proc)) {
+                    state.proc.status = "running";
+                    this.emit("status", state.proc.id, "running", state.proc);
+                    return;
+                }
+            }
+            catch {
+                // try again
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        if (state.proc.status === "starting") {
+            state.proc.status = "crashed";
+            state.proc.errorMessage = `health check did not pass within ${timeout}ms`;
+            this.emit("status", state.proc.id, "crashed", state.proc);
+            // Best-effort kill so we don't leak orphans.
+            try {
+                state.child.kill("SIGTERM");
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    /**
+     * Send SIGTERM to a managed process; wait until it exits. After
+     * `graceMs` (default 5s) escalate to SIGKILL.
+     */
+    async stop(id, graceMs = 5000) {
+        const state = this.states.get(id);
+        if (!state)
+            return;
+        if (state.proc.status === "exited" || state.proc.status === "crashed")
+            return;
+        state.proc.status = "stopping";
+        this.emit("status", id, "stopping", state.proc);
+        state.child.kill("SIGTERM");
+        const exited = new Promise((resolve) => state.child.once("exit", () => resolve()));
+        const grace = new Promise((resolve) => setTimeout(() => resolve("escalate"), graceMs));
+        const result = await Promise.race([exited.then(() => "exited"), grace]);
+        if (result === "escalate") {
+            try {
+                // Windows collapses SIGTERM and SIGKILL into the same hard
+                // TerminateProcess call — the grace ladder is therefore
+                // POSIX-only. On Win we pass no signal so Node picks the
+                // platform default (TerminateProcess).
+                if (IS_WIN)
+                    state.child.kill();
+                else
+                    state.child.kill("SIGKILL");
+            }
+            catch {
+                // already dead
+            }
+            await exited;
+        }
+    }
+    /** Stop every managed process. */
+    async stopAll() {
+        await Promise.all([...this.states.keys()].map((id) => this.stop(id)));
+    }
+    /** Drop the record for an exited process. No-op if still running. */
+    forget(id) {
+        const state = this.states.get(id);
+        if (!state)
+            return;
+        if (state.proc.status === "running" || state.proc.status === "starting") {
+            throw new Error(`RunnerSupervisor.forget: process ${id} is still ${state.proc.status} — stop it first.`);
+        }
+        this.states.delete(id);
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nwire/supervisor",
+  "version": "0.10.0",
+  "private": false,
+  "description": "Spawns and watches Nwire wire processes for dev tooling. Used by `nwire dev` and Studio's vite dev server. Generic process supervisor with stdout/stderr ring buffer, health-check polling, SIGTERM-then-SIGKILL graceful stop.",
+  "keywords": [
+    "dev",
+    "supervisor",
+    "process",
+    "nwire"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "typecheck": "tsc --noEmit"
+  }
+}