procband 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alec Larson
+
+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/README.md

@@ -0,0 +1,39 @@
+# procband
+
+## Purpose
+
+`procband` supervises subprocesses from TypeScript. It prefixes child output,
+matches future log lines, waits for terminal exit, optionally restarts failed
+processes, tree-kills descendants during shutdown, and propagates unobserved
+terminal failures to the parent process.
+
+## Installation
+
+```sh
+pnpm add procband
+```
+
+## Quick Example
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+
+await proc.waitFor('ready')
+const result = await proc
+console.log(result)
+```
+
+## Documentation Map
+
+- Concepts and lifecycle: [docs/context.md](docs/context.md)
+- Minimal usage example: [examples/basic-usage.ts](examples/basic-usage.ts)
+- Restart example: [examples/restart-on-failure.ts](examples/restart-on-failure.ts)
+- Sequencing example: [examples/sequenced-processes.ts](examples/sequenced-processes.ts)
+- Exact exported signatures: [dist/index.d.mts](dist/index.d.mts)

package/dist/index.d.mts

@@ -0,0 +1,294 @@
+import { ChildProcess } from "node:child_process";
+import { Writable } from "node:stream";
+
+//#region src/types.d.ts
+/**
+ * Accepted Node.js signal names.
+ */
+type Signals = NodeJS.Signals;
+/**
+ * Signal values accepted by `kill()` and `stop()`.
+ */
+type KillSignal = number | Signals;
+/**
+ * A line matcher used by `match()` and `waitFor()`.
+ *
+ * String patterns use substring matching. `RegExp` patterns are executed
+ * against the full observed line.
+ */
+type MatchPattern = string | RegExp;
+/**
+ * The output streams that can participate in line matching.
+ */
+type MatchStream = 'stdout' | 'stderr' | 'both';
+/**
+ * Configuration for a single supervised subprocess.
+ */
+interface ProcessConfig {
+  /**
+   * Stable identifier used in prefixed output and emitted match events.
+   */
+  name: string;
+  /**
+   * Executable or shell-free command name passed to `spawn()`.
+   */
+  command: string;
+  /**
+   * Positional arguments passed to the child process.
+   */
+  args?: string[];
+  /**
+   * Working directory for the child process.
+   */
+  cwd?: string;
+  /**
+   * Environment variables for the child process.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Human-facing label used in prefixed output.
+   *
+   * Defaults to `name`.
+   */
+  label?: string;
+  /**
+   * RGB color for this process's `stdout` prefix.
+   *
+   * When omitted, `procband` assigns the next color from its default palette.
+   * The reserved `stderr` red cannot be used here.
+   */
+  color?: RgbColor;
+  /**
+   * Optional extra sink for raw child `stderr` bytes.
+   *
+   * This is additive. It does not replace the normal prefixed writes to
+   * `process.stderr`.
+   */
+  stderr?: Writable;
+  /**
+   * Automatic restart behavior for terminal child exits.
+   *
+   * Use `true` for the built-in defaults or provide an explicit policy.
+   */
+  restart?: boolean | RestartPolicy;
+}
+/**
+ * A 24-bit RGB color tuple.
+ */
+type RgbColor = readonly [red: number, green: number, blue: number];
+/**
+ * Controls whether and how a supervised process restarts after exit.
+ */
+interface RestartPolicy {
+  /**
+   * Which exit outcomes trigger a restart.
+   *
+   * Defaults to `"on-failure"`.
+   */
+  when?: 'on-failure' | 'on-exit';
+  /**
+   * Delay before spawning the next attempt.
+   *
+   * Defaults to `1000`.
+   */
+  delayMs?: number;
+  /**
+   * Maximum failed exits allowed inside `windowMs` before restart is
+   * suppressed.
+   *
+   * Defaults to `3`.
+   */
+  maxFailures?: number;
+  /**
+   * Rolling time window used for failed-exit suppression.
+   *
+   * Defaults to `30000`.
+   */
+  windowMs?: number;
+}
+/**
+ * Common options for line-matching APIs.
+ */
+interface MatchOptions {
+  /**
+   * Which output stream to inspect.
+   *
+   * Defaults to `"both"`.
+   */
+  stream?: MatchStream;
+}
+/**
+ * Options for `waitFor()`.
+ */
+interface WaitForOptions extends MatchOptions {
+  /**
+   * Maximum time to wait for a future match before rejecting.
+   */
+  timeoutMs?: number;
+}
+/**
+ * A matched output line observed from a supervised process.
+ */
+interface MatchEvent {
+  /**
+   * The `ProcessConfig.name` associated with the process.
+   */
+  process: string;
+  /**
+   * Which child output stream produced the line.
+   */
+  stream: 'stdout' | 'stderr';
+  /**
+   * The matched line without its trailing newline.
+   */
+  line: string;
+  /**
+   * The `RegExp.exec()` result for regex patterns, or `null` for string
+   * patterns.
+   */
+  match: RegExpExecArray | null;
+  /**
+   * The wall-clock timestamp, in milliseconds since the Unix epoch, when the
+   * line was emitted to subscribers.
+   */
+  timestamp: number;
+}
+/**
+ * Callback invoked for each future matching line.
+ */
+type MatchCallback = (event: MatchEvent) => void;
+/**
+ * Stops a callback subscription created by `match()`.
+ */
+type Unsubscribe = () => void;
+/**
+ * Options for `stop()`.
+ */
+interface StopOptions {
+  /**
+   * Signal used for the initial process-tree shutdown attempt.
+   *
+   * Defaults to `"SIGTERM"`.
+   */
+  signal?: KillSignal;
+  /**
+   * Delay before escalating to `SIGKILL`.
+   *
+   * Defaults to `5000`.
+   */
+  killAfterMs?: number;
+}
+/**
+ * Final state for a supervised process after all restart attempts are done.
+ */
+interface ProcessResult {
+  /**
+   * The `ProcessConfig.name` for the completed process.
+   */
+  name: string;
+  /**
+   * Final child exit code, or `null` when the process exited by signal.
+   */
+  code: number | null;
+  /**
+   * Shell-style exit status for the final process outcome.
+   *
+   * This is equal to `code` for normal exits, or `128 + signalNumber` when the
+   * process exited by signal.
+   */
+  exitCode: number;
+  /**
+   * Final terminating signal, or `null` when the process exited normally.
+   */
+  signal: Signals | null;
+  /**
+   * Number of restart attempts that were started.
+   */
+  restarts: number;
+  /**
+   * Whether restart was disabled by the failure-suppression guard.
+   */
+  restartSuppressed: boolean;
+}
+/**
+ * A supervised child-process handle.
+ *
+ * `ProcbandProcess` behaves like the current active `ChildProcess`, while also
+ * exposing matching, terminal shutdown, and final-result helpers. The wrapper
+ * is thenable, so `await proc` is equivalent to `await proc.wait()`.
+ */
+interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
+  /**
+   * Subscribe to future matching lines from this process.
+   *
+   * Matching is line-based and forward-only. One subscription does not consume
+   * events from another. If `onMatch` throws, only that subscription is
+   * removed.
+   *
+   * @param pattern The string or regular expression to match against each
+   * future line.
+   * @param onMatch Invoked for every future matching line.
+   * @param options Optional stream filter.
+   * @returns An idempotent function that unsubscribes the callback.
+   */
+  match(pattern: MatchPattern, onMatch: MatchCallback, options?: MatchOptions): Unsubscribe;
+  /**
+   * Wait for the first future matching line from this process.
+   *
+   * @param pattern The string or regular expression to match against each
+   * future line.
+   * @param options Optional stream filter and timeout.
+   * @returns The first future matching event.
+   * @throws When `timeoutMs` elapses before a match is observed.
+   * @throws When the process becomes terminal before a match is observed.
+   */
+  waitFor(pattern: MatchPattern, options?: WaitForOptions): Promise<MatchEvent>;
+  /**
+   * Wait for the process to become terminal with no further restart pending.
+   *
+   * Unlike many process helpers, this resolves for both success and failure.
+   * Inspect the returned `ProcessResult` instead of relying on promise
+   * rejection for non-zero exits.
+   */
+  wait(): Promise<ProcessResult>;
+  /**
+   * Disable future restarts and terminate the active process tree.
+   *
+   * `stop()` targets the current child process and any descendants it spawned.
+   * It first uses the configured `signal`, then escalates to `SIGKILL` after
+   * `killAfterMs` if the tree is still alive.
+   */
+  stop(options?: StopOptions): Promise<void>;
+}
+//#endregion
+//#region src/process.d.ts
+/**
+ * Start supervising a single subprocess.
+ *
+ * The returned `ProcbandProcess` starts immediately, prefixes child output,
+ * exposes line-based matching helpers, and resolves when the process reaches a
+ * terminal state with no further restart pending.
+ *
+ * @param config The subprocess configuration to supervise.
+ * @returns A `ChildProcess`-compatible wrapper with procband-specific helpers.
+ * @throws When `config` is invalid, such as a missing `name`, missing
+ * `command`, or an invalid reserved color.
+ * @example
+ * ```ts
+ * import process from 'node:process'
+ * import { supervise } from 'procband'
+ *
+ * const proc = supervise({
+ *   name: 'server',
+ *   command: process.execPath,
+ *   args: ['-e', 'console.log("ready")'],
+ * })
+ *
+ * await proc.waitFor('ready')
+ * const result = await proc
+ * console.log(result)
+ * ```
+ */
+declare function supervise(config: ProcessConfig): ProcbandProcess;
+//#endregion
+export { type MatchCallback, type MatchEvent, type MatchOptions, type ProcbandProcess, type ProcessConfig, type ProcessResult, type RestartPolicy, type RgbColor, type StopOptions, type Unsubscribe, type WaitForOptions, supervise };

package/dist/index.mjs

@@ -0,0 +1,705 @@
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { constants } from "node:os";
+import process from "node:process";
+import ansiStyles from "ansi-styles";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import treeKill, { treeKillSync } from "@alloc/tree-kill";
+//#region src/colors.ts
+const prefixPalette = [
+	[
+		99,
+		102,
+		241
+	],
+	[
+		14,
+		165,
+		233
+	],
+	[
+		6,
+		182,
+		212
+	],
+	[
+		16,
+		185,
+		129
+	],
+	[
+		132,
+		204,
+		22
+	],
+	[
+		245,
+		158,
+		11
+	],
+	[
+		249,
+		115,
+		22
+	],
+	[
+		236,
+		72,
+		153
+	],
+	[
+		168,
+		85,
+		247
+	],
+	[
+		139,
+		92,
+		246
+	]
+];
+const stderrColor = [
+	239,
+	68,
+	68
+];
+let nextPaletteIndex = 0;
+function resolveProcessColor(color) {
+	if (color) return [...color];
+	const paletteColor = prefixPalette[nextPaletteIndex % prefixPalette.length];
+	nextPaletteIndex += 1;
+	return [...paletteColor];
+}
+function validateProcessColor(color) {
+	if (!color) return;
+	const [red, green, blue] = color;
+	for (const value of [
+		red,
+		green,
+		blue
+	]) if (!Number.isInteger(value) || value < 0 || value > 255) throw new Error("ProcessConfig.color must contain integer RGB values between 0 and 255");
+	if (red === stderrColor[0] && green === stderrColor[1] && blue === stderrColor[2]) throw new Error("ProcessConfig.color cannot use the reserved stderr color");
+}
+function writePrefixedLine(target, label, color, line, appendNewline) {
+	target.write(formatPrefix(label, color) + line + (appendNewline ? "\n" : ""));
+}
+function formatPrefix(label, color) {
+	return `${ansiStyles.color.ansi16m(...color)}[${label}]${ansiStyles.color.close} `;
+}
+//#endregion
+//#region src/matching.ts
+var MatchRegistry = class {
+	subscriptions = /* @__PURE__ */ new Set();
+	closedError = null;
+	processName;
+	constructor(processName) {
+		this.processName = processName;
+	}
+	match(pattern, onMatch, options) {
+		if (this.closedError) return () => {};
+		const subscription = {
+			active: true,
+			kind: "callback",
+			pattern,
+			stream: options?.stream ?? "both",
+			onMatch
+		};
+		this.subscriptions.add(subscription);
+		return () => {
+			this.unsubscribe(subscription);
+		};
+	}
+	waitFor(pattern, options) {
+		if (this.closedError) return Promise.reject(this.closedError);
+		return new Promise((resolve, reject) => {
+			const subscription = {
+				active: true,
+				kind: "promise",
+				pattern,
+				stream: options?.stream ?? "both",
+				resolve: (event) => {
+					this.unsubscribe(subscription);
+					resolve(event);
+				},
+				reject: (error) => {
+					this.unsubscribe(subscription);
+					reject(error);
+				},
+				timer: null
+			};
+			if (options?.timeoutMs != null) subscription.timer = setTimeout(() => {
+				subscription.reject(/* @__PURE__ */ new Error(`Timed out waiting for a match from process "${this.processName}"`));
+			}, options.timeoutMs);
+			this.subscriptions.add(subscription);
+		});
+	}
+	emit(stream, line) {
+		if (this.closedError) return;
+		const baseEvent = createMatchEvent(this.processName, stream, line);
+		for (const subscription of [...this.subscriptions]) {
+			if (!subscription.active || !matchesStream(subscription.stream, stream)) continue;
+			const match = matchPattern(subscription.pattern, line);
+			if (!match.matched) continue;
+			const event = {
+				...baseEvent,
+				match: match.value
+			};
+			if (subscription.kind === "callback") {
+				try {
+					subscription.onMatch(event);
+				} catch {
+					this.unsubscribe(subscription);
+				}
+				continue;
+			}
+			subscription.resolve(event);
+		}
+	}
+	close(error) {
+		if (this.closedError) return;
+		this.closedError = error;
+		for (const subscription of [...this.subscriptions]) if (subscription.kind === "promise") subscription.reject(error);
+		else this.unsubscribe(subscription);
+	}
+	unsubscribe(subscription) {
+		if (!subscription.active) return;
+		subscription.active = false;
+		if (subscription.kind === "promise" && subscription.timer) {
+			clearTimeout(subscription.timer);
+			subscription.timer = null;
+		}
+		this.subscriptions.delete(subscription);
+	}
+};
+function createMatchEvent(processName, stream, line) {
+	return {
+		process: processName,
+		stream,
+		line,
+		match: null,
+		timestamp: Date.now()
+	};
+}
+function matchesStream(expected, actual) {
+	return expected === "both" || expected === actual;
+}
+function matchPattern(pattern, line) {
+	if (typeof pattern === "string") return {
+		matched: line.includes(pattern),
+		value: null
+	};
+	pattern.lastIndex = 0;
+	const match = pattern.exec(line);
+	return {
+		matched: match != null,
+		value: match
+	};
+}
+//#endregion
+//#region src/restart.ts
+const defaultRestartPolicy = Object.freeze({
+	when: "on-failure",
+	delayMs: 1e3,
+	maxFailures: 3,
+	windowMs: 3e4
+});
+var RestartController = class {
+	policy;
+	restarts = 0;
+	restartSuppressed = false;
+	restartFailures = [];
+	restartTimer = null;
+	cancelRestartDelay = null;
+	constructor(restart) {
+		this.policy = normalizeRestartPolicy(restart);
+	}
+	shouldRestart(code, signal, restartDisabled, finalized) {
+		if (finalized || restartDisabled || !this.policy) return false;
+		if (this.policy.when === "on-exit") return true;
+		return isFailedExit(code, signal);
+	}
+	prepareRestart(code, signal) {
+		if (!this.policy) return false;
+		if (isFailedExit(code, signal)) {
+			const now = Date.now();
+			this.restartFailures.push(now);
+			this.restartFailures = this.restartFailures.filter((timestamp) => now - timestamp <= this.policy.windowMs);
+			if (this.restartFailures.length > this.policy.maxFailures) {
+				this.restartSuppressed = true;
+				return false;
+			}
+		}
+		this.restarts += 1;
+		return true;
+	}
+	waitForDelay() {
+		if (!this.policy || this.policy.delayMs <= 0) return Promise.resolve(true);
+		return new Promise((resolve) => {
+			this.restartTimer = setTimeout(() => {
+				this.restartTimer = null;
+				this.cancelRestartDelay = null;
+				resolve(true);
+			}, this.policy.delayMs);
+			this.cancelRestartDelay = () => {
+				if (this.restartTimer) {
+					clearTimeout(this.restartTimer);
+					this.restartTimer = null;
+				}
+				this.cancelRestartDelay = null;
+				resolve(false);
+			};
+		});
+	}
+	cancelDelay() {
+		this.cancelRestartDelay?.();
+	}
+};
+function normalizeRestartPolicy(restart) {
+	if (!restart) return null;
+	if (restart === true) return { ...defaultRestartPolicy };
+	return {
+		when: restart.when ?? defaultRestartPolicy.when,
+		delayMs: restart.delayMs ?? defaultRestartPolicy.delayMs,
+		maxFailures: restart.maxFailures ?? defaultRestartPolicy.maxFailures,
+		windowMs: restart.windowMs ?? defaultRestartPolicy.windowMs
+	};
+}
+function isFailedExit(code, signal) {
+	return signal != null || code !== 0;
+}
+//#endregion
+//#region src/shutdown.ts
+const liveTargets = /* @__PURE__ */ new Set();
+let parentCleanupInstalled = false;
+let handlingSignal = false;
+function registerCleanupTarget(target) {
+	liveTargets.add(target);
+	installParentCleanup();
+}
+function unregisterCleanupTarget(target) {
+	liveTargets.delete(target);
+	if (liveTargets.size === 0) uninstallParentCleanup();
+}
+function killTreeBestEffort(child, signal) {
+	try {
+		treeKillSync(child, signal);
+	} catch {}
+}
+async function stopChildTree(child, close, isClosed, signal, killAfterMs) {
+	try {
+		await treeKill(child, signal);
+	} catch (error) {
+		if (!isMissingProcessError(error)) throw error;
+	}
+	if (!await Promise.race([close.then(() => true), setTimeout$1(killAfterMs, false)]) && !isClosed()) {
+		try {
+			await treeKill(child, "SIGKILL");
+		} catch (error) {
+			if (!isMissingProcessError(error)) throw error;
+		}
+		await close;
+	}
+}
+function installParentCleanup() {
+	if (parentCleanupInstalled) return;
+	parentCleanupInstalled = true;
+	process.on("SIGINT", onParentSigint);
+	process.on("SIGTERM", onParentSigterm);
+	process.on("exit", onParentExit);
+}
+function uninstallParentCleanup() {
+	if (!parentCleanupInstalled) return;
+	parentCleanupInstalled = false;
+	process.off("SIGINT", onParentSigint);
+	process.off("SIGTERM", onParentSigterm);
+	process.off("exit", onParentExit);
+}
+function onParentExit() {
+	for (const target of [...liveTargets]) target.cleanupFromExit();
+}
+function onParentSigint() {
+	onParentSignal("SIGINT");
+}
+function onParentSigterm() {
+	onParentSignal("SIGTERM");
+}
+function onParentSignal(signal) {
+	if (handlingSignal) return;
+	handlingSignal = true;
+	const handler = signal === "SIGINT" ? onParentSigint : onParentSigterm;
+	const pending = [...liveTargets].map((target) => target.cleanupFromSignal(signal));
+	Promise.allSettled(pending).finally(() => {
+		handlingSignal = false;
+		process.off(signal, handler);
+		if (process.listenerCount(signal) === 0) {
+			process.kill(process.pid, signal);
+			return;
+		}
+		process.on(signal, handler);
+	});
+}
+function isMissingProcessError(error) {
+	return typeof error === "object" && error != null && "code" in error && error.code === "ESRCH";
+}
+//#endregion
+//#region src/process.ts
+/**
+* Start supervising a single subprocess.
+*
+* The returned `ProcbandProcess` starts immediately, prefixes child output,
+* exposes line-based matching helpers, and resolves when the process reaches a
+* terminal state with no further restart pending.
+*
+* @param config The subprocess configuration to supervise.
+* @returns A `ChildProcess`-compatible wrapper with procband-specific helpers.
+* @throws When `config` is invalid, such as a missing `name`, missing
+* `command`, or an invalid reserved color.
+* @example
+* ```ts
+* import process from 'node:process'
+* import { supervise } from 'procband'
+*
+* const proc = supervise({
+*   name: 'server',
+*   command: process.execPath,
+*   args: ['-e', 'console.log("ready")'],
+* })
+*
+* await proc.waitFor('ready')
+* const result = await proc
+* console.log(result)
+* ```
+*/
+function supervise(config) {
+	return new ProcbandProcessImpl(config);
+}
+var ProcbandProcessImpl = class extends EventEmitter {
+	config;
+	name;
+	label;
+	color;
+	matches;
+	restart;
+	finalPromise;
+	finalResolve;
+	attempt = null;
+	generation = 0;
+	stderrSink;
+	stderrSinkActive = true;
+	stderrSinkCleanup = null;
+	stopPromise = null;
+	shutdownRequested = false;
+	restartDisabled = false;
+	finalized = false;
+	lastResult = null;
+	terminalResultObserved = false;
+	constructor(config) {
+		super();
+		validateProcessConfig(config);
+		this.config = config;
+		this.name = config.name;
+		this.label = config.label ?? config.name;
+		this.color = resolveProcessColor(config.color);
+		this.matches = new MatchRegistry(this.name);
+		this.restart = new RestartController(config.restart);
+		this.stderrSink = config.stderr ?? null;
+		this.finalPromise = new Promise((resolve) => {
+			this.finalResolve = resolve;
+		});
+		this.bindStderrSink();
+		this.spawnAttempt();
+		registerCleanupTarget(this);
+		liveProcesses.add(this);
+	}
+	get pid() {
+		return this.currentChild?.pid;
+	}
+	get stdin() {
+		return this.currentChild?.stdin ?? null;
+	}
+	get stdout() {
+		return this.currentChild?.stdout ?? null;
+	}
+	get stderr() {
+		return this.currentChild?.stderr ?? null;
+	}
+	get stdio() {
+		return this.currentChild?.stdio ?? [
+			null,
+			null,
+			null
+		];
+	}
+	get killed() {
+		return this.currentChild?.killed ?? false;
+	}
+	get exitCode() {
+		return this.currentChild?.exitCode ?? this.lastResult?.code ?? null;
+	}
+	get signalCode() {
+		return this.currentChild?.signalCode ?? this.lastResult?.signal ?? null;
+	}
+	get connected() {
+		return this.currentChild?.connected ?? false;
+	}
+	get spawnargs() {
+		return this.currentChild?.spawnargs ?? [];
+	}
+	get spawnfile() {
+		return this.currentChild?.spawnfile ?? this.config.command;
+	}
+	get currentChild() {
+		return this.attempt?.child ?? null;
+	}
+	match(pattern, onMatch, options) {
+		return this.matches.match(pattern, onMatch, options);
+	}
+	waitFor(pattern, options) {
+		return this.matches.waitFor(pattern, options);
+	}
+	wait() {
+		this.markTerminalResultObserved();
+		return this.finalPromise;
+	}
+	then(onfulfilled, onrejected) {
+		this.markTerminalResultObserved();
+		return this.finalPromise.then(onfulfilled, onrejected);
+	}
+	kill(signal) {
+		const child = this.currentChild;
+		if (!child) return false;
+		return child.kill(signal);
+	}
+	ref() {
+		this.currentChild?.ref();
+		return this;
+	}
+	unref() {
+		this.currentChild?.unref();
+		return this;
+	}
+	disconnect() {
+		this.currentChild?.disconnect();
+	}
+	async stop(options) {
+		if (this.stopPromise) return this.stopPromise;
+		this.shutdownRequested = true;
+		this.restartDisabled = true;
+		this.restart.cancelDelay();
+		this.stopPromise = this.stopActiveTree(options?.signal ?? "SIGTERM", options?.killAfterMs ?? 5e3);
+		return this.stopPromise;
+	}
+	cleanupFromExit() {
+		this.shutdownRequested = true;
+		this.restartDisabled = true;
+		this.restart.cancelDelay();
+		const child = this.currentChild;
+		if (child) killTreeBestEffort(child);
+	}
+	async cleanupFromSignal(signal) {
+		this.shutdownRequested = true;
+		this.restartDisabled = true;
+		this.restart.cancelDelay();
+		await this.stopActiveTree(signal, 1e3);
+	}
+	async stopActiveTree(signal, killAfterMs) {
+		const attempt = this.attempt;
+		if (!attempt || attempt.closed) {
+			await this.finalPromise;
+			return;
+		}
+		await stopChildTree(attempt.child, attempt.close, () => attempt.closed, signal, killAfterMs);
+	}
+	spawnAttempt() {
+		this.generation += 1;
+		const child = spawn(this.config.command, this.config.args ?? [], {
+			cwd: this.config.cwd,
+			env: this.config.env,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		let settleClose;
+		const attempt = {
+			child,
+			generation: this.generation,
+			close: new Promise((resolve) => {
+				settleClose = resolve;
+			}),
+			settleClose,
+			stdout: {
+				text: "",
+				flushed: false
+			},
+			stderr: {
+				text: "",
+				flushed: false
+			},
+			closed: false
+		};
+		this.attempt = attempt;
+		this.attachAttempt(attempt);
+	}
+	attachAttempt(attempt) {
+		const { child } = attempt;
+		child.on("spawn", () => {
+			if (this.attempt === attempt) this.emit("spawn");
+		});
+		child.on("error", (error) => {
+			if (this.attempt === attempt) this.emit("error", error);
+		});
+		child.on("exit", (code, signal) => {
+			if (this.attempt === attempt) this.emit("exit", code, signal);
+		});
+		child.on("close", (code, signal) => {
+			if (this.attempt !== attempt) return;
+			attempt.closed = true;
+			this.flushLineBuffer(attempt, "stdout");
+			this.flushLineBuffer(attempt, "stderr");
+			attempt.settleClose({
+				code,
+				signal
+			});
+			this.emit("close", code, signal);
+			this.handleAttemptClose(code, signal);
+		});
+		child.stdout.on("data", (chunk) => {
+			if (this.attempt === attempt) this.handleChunk(attempt, "stdout", chunk);
+		});
+		child.stderr.on("data", (chunk) => {
+			if (this.attempt !== attempt) return;
+			this.writeStderrSink(chunk);
+			this.handleChunk(attempt, "stderr", chunk);
+		});
+		child.stdout.on("end", () => {
+			if (this.attempt === attempt) this.flushLineBuffer(attempt, "stdout");
+		});
+		child.stderr.on("end", () => {
+			if (this.attempt === attempt) this.flushLineBuffer(attempt, "stderr");
+		});
+	}
+	handleChunk(attempt, stream, chunk) {
+		const buffer = attempt[stream];
+		let text = buffer.text + chunk.toString("utf8");
+		let newlineIndex = text.indexOf("\n");
+		while (newlineIndex >= 0) {
+			const rawLine = text.slice(0, newlineIndex);
+			const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+			this.handleLine(stream, line, true);
+			text = text.slice(newlineIndex + 1);
+			newlineIndex = text.indexOf("\n");
+		}
+		buffer.text = text;
+	}
+	handleLine(stream, line, appendNewline) {
+		writePrefixedLine(stream === "stdout" ? process.stdout : process.stderr, this.label, stream === "stdout" ? this.color : stderrColor, line, appendNewline);
+		this.matches.emit(stream, line);
+	}
+	async handleAttemptClose(code, signal) {
+		if (this.restart.shouldRestart(code, signal, this.restartDisabled, this.finalized)) {
+			if (!this.restart.prepareRestart(code, signal)) {
+				this.finalize(this.createResult(code, signal));
+				return;
+			}
+			if (!await this.restart.waitForDelay() || this.finalized || this.restartDisabled) {
+				this.finalize(this.createResult(code, signal));
+				return;
+			}
+			this.spawnAttempt();
+			return;
+		}
+		this.finalize(this.createResult(code, signal));
+	}
+	createResult(code, signal) {
+		return {
+			name: this.name,
+			code,
+			exitCode: getResultExitCode(code, signal),
+			signal,
+			restarts: this.restart.restarts,
+			restartSuppressed: this.restart.restartSuppressed
+		};
+	}
+	finalize(result) {
+		if (this.finalized) return;
+		this.finalized = true;
+		this.restart.cancelDelay();
+		this.lastResult = result;
+		liveProcesses.delete(this);
+		if (liveProcesses.size === 0) propagatedFailure = false;
+		if (this.shouldPropagateFailure(result)) propagateFailure(result.exitCode);
+		this.matches.close(/* @__PURE__ */ new Error(`Process "${this.name}" exited before a matching line was observed`));
+		this.unbindStderrSink();
+		unregisterCleanupTarget(this);
+		this.finalResolve(result);
+	}
+	markTerminalResultObserved() {
+		this.terminalResultObserved = true;
+	}
+	shouldPropagateFailure(result) {
+		return result.exitCode !== 0 && !this.shutdownRequested && !this.terminalResultObserved;
+	}
+	bindStderrSink() {
+		const sink = this.stderrSink;
+		if (!sink || typeof sink.on !== "function") return;
+		const disable = () => {
+			this.stderrSinkActive = false;
+		};
+		sink.on("error", disable);
+		sink.on("close", disable);
+		this.stderrSinkCleanup = () => {
+			sink.off("error", disable);
+			sink.off("close", disable);
+		};
+	}
+	unbindStderrSink() {
+		this.stderrSinkCleanup?.();
+		this.stderrSinkCleanup = null;
+	}
+	writeStderrSink(chunk) {
+		const sink = this.stderrSink;
+		if (!sink || !this.stderrSinkActive) return;
+		try {
+			if ("destroyed" in sink && sink.destroyed) {
+				this.stderrSinkActive = false;
+				return;
+			}
+			sink.write(chunk);
+		} catch {
+			this.stderrSinkActive = false;
+		}
+	}
+	flushLineBuffer(attempt, stream) {
+		const buffer = attempt[stream];
+		if (buffer.flushed || buffer.text.length === 0) {
+			buffer.flushed = true;
+			return;
+		}
+		buffer.flushed = true;
+		const line = buffer.text.endsWith("\r") ? buffer.text.slice(0, -1) : buffer.text;
+		buffer.text = "";
+		this.handleLine(stream, line, false);
+	}
+};
+const liveProcesses = /* @__PURE__ */ new Set();
+let propagatedFailure = false;
+function validateProcessConfig(config) {
+	if (!config.name) throw new Error("ProcessConfig.name is required");
+	if (!config.command) throw new Error("ProcessConfig.command is required");
+	validateProcessColor(config.color);
+}
+function getResultExitCode(code, signal) {
+	if (code != null) return code;
+	if (signal) return 128 + (constants.signals[signal] ?? 0);
+	return 1;
+}
+function propagateFailure(exitCode) {
+	if (propagatedFailure) return;
+	propagatedFailure = true;
+	if (process.exitCode == null || process.exitCode === 0) process.exitCode = exitCode;
+	for (const proc of liveProcesses) proc.stop().catch(() => {});
+}
+//#endregion
+export { supervise };

package/docs/context.md

@@ -0,0 +1,146 @@
+# Overview
+
+`procband` supervises one subprocess per `supervise()` call.
+
+The returned `ProcbandProcess` is both:
+
+- a `ChildProcess`-compatible handle for the current active child attempt
+- a thenable wrapper that resolves to a `ProcessResult` when supervision is done
+
+Supervision adds four behaviors on top of raw `spawn()`:
+
+- prefixed `stdout` and `stderr`
+- line-based matching for future output
+- optional restart policy with failure suppression
+- tree-aware shutdown for the child and its descendants
+- parent-exit propagation for unobserved terminal failures
+
+# When to Use
+
+- You are writing project-specific TypeScript scripts, not a CLI.
+- You need to wait for a subprocess to print a "ready" line.
+- You want readable prefixed logs from multiple long-lived child processes.
+- You need one shutdown API that kills descendant processes too.
+- You want automatic restart with a small built-in guard against tight failure
+  loops.
+
+# When Not to Use
+
+- You need a standalone process manager or service supervisor.
+- You need buffered log history or replay for late subscribers.
+- You need shell pipelines, shell parsing, or a command-line tool.
+- You want one API that supervises many processes at once. `procband` keeps the
+  unit of supervision to one process per call.
+
+# Core Abstractions
+
+- `ProcessConfig`
+  Declares one supervised subprocess plus its label, color, restart policy, and
+  optional raw `stderr` tee.
+- `ProcbandProcess`
+  The live wrapper returned by `supervise()`. It is a `ChildProcess`-compatible
+  handle, a matching surface, a shutdown surface, and a thenable final result.
+- `MatchEvent`
+  A future matched line from `stdout` or `stderr`.
+- `RestartPolicy`
+  Rules for restart timing and failed-exit suppression.
+
+# Data Flow / Lifecycle
+
+1. `supervise(config)` spawns the first child process immediately.
+2. Child `stdout` and `stderr` are read as text and split into lines.
+3. Each line is prefixed and written to the parent `process.stdout` or
+   `process.stderr`.
+4. `stderr` can also be tee'd as raw bytes to `ProcessConfig.stderr`.
+5. Future matching lines are delivered through `match()` callbacks or
+   `waitFor()`.
+6. When a child exits, `procband` either finalizes or starts a new attempt,
+   depending on the restart policy.
+7. A terminal failed exit that nobody observed through `await proc` or
+   `proc.wait()` sets `process.exitCode` and begins
+   stopping any other live `procband` processes in the same parent script.
+8. `await proc` or `await proc.wait()` resolves only after the process is
+   terminal and no further restart will happen.
+
+# Common Tasks -> Recommended APIs
+
+- Wait for one readiness line:
+  `proc.waitFor('ready')`
+- React to repeated matching output:
+  `proc.match(pattern, callback, options)`
+- Stop the process and its descendants:
+  `proc.stop()`
+- Inspect final exit state:
+  `await proc` or `await proc.wait()`
+- Take ownership of a process failure:
+  `await proc` or `await proc.wait()`
+- Let an unobserved terminal failure fail the parent script:
+  Do not call `wait()` or await the thenable result
+- Capture raw child `stderr` in a file or custom stream:
+  `ProcessConfig.stderr`
+- Retry failed exits with sane defaults:
+  `restart: true`
+- Use explicit retry rules:
+  `restart: { when, delayMs, maxFailures, windowMs }`
+
+# Invariants and Constraints
+
+- Matching is line-based and future-only.
+- String patterns use substring matching.
+- RegExp patterns run against the full observed line.
+- `match()` subscriptions do not interfere with each other.
+- `waitFor()` rejects if the process becomes terminal before a future match is
+  observed.
+- `await proc` resolves for both successful and failed exits. Inspect the
+  returned `ProcessResult`.
+- `ProcessResult.exitCode` exposes the shell-style exit status for the final
+  outcome, including signal exits.
+- Calling `proc.wait()` or awaiting the thenable process marks its terminal
+  result as observed and suppresses default parent-exit propagation.
+- An unobserved terminal failure sets `process.exitCode` to the first failing
+  process's `ProcessResult.exitCode` and starts stopping other live `procband`
+  processes in the same parent script.
+- The wrapper survives restarts, but inherited `pid`, `stdin`, `stdout`,
+  `stderr`, and related `ChildProcess` fields always refer to the current active
+  child attempt.
+- `kill()` only signals the current direct child. `stop()` disables restart and
+  kills the full process tree.
+- Parent cleanup installs both `SIGINT` and `SIGTERM` handlers while any live
+  supervised process exists.
+- `stderr` prefixes always use the reserved red, even when a custom process
+  color is configured.
+
+# Error Model
+
+- `supervise()` throws synchronously for invalid config such as missing `name`,
+  missing `command`, or an invalid reserved color.
+- `waitFor()` rejects on timeout or terminal exit before a future match.
+- A thrown `match()` callback only unsubscribes that callback.
+- Errors from `ProcessConfig.stderr` stop teeing to that sink but do not stop
+  supervision.
+- Unobserved terminal failures do not reject promises. They set the parent
+  `process.exitCode` and start stopping sibling `procband` processes.
+- `stop()` may reject if tree-kill fails with a non-`ESRCH` error.
+
+# Terminology
+
+- Supervised process:
+  A `ProcbandProcess` wrapper plus its current child attempt.
+- Child attempt:
+  One concrete spawned process instance inside a supervision run.
+- Terminal:
+  No child is running and no restart will be started.
+- Restart suppression:
+  Automatic disabling of further restarts after too many failed exits inside the
+  configured window.
+- Match:
+  A future observed output line that satisfies a string or regex pattern.
+
+# Non-Goals
+
+- A standalone CLI
+- Historical log replay
+- Multi-process orchestration in one top-level API
+- Shell command parsing
+- Full service-management features such as persistence, cron scheduling, or host
+  restarts

package/examples/basic-usage.ts

@@ -0,0 +1,32 @@
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: [
+    '-e',
+    [
+      'console.log("booting")',
+      'setTimeout(() => console.log("ready"), 20)',
+      'setTimeout(() => console.error("warn"), 40)',
+      'setTimeout(() => process.exit(0), 60)',
+    ].join(';'),
+  ],
+})
+
+const unsubscribe = proc.match(
+  'warn',
+  event => {
+    console.log(`observed ${event.stream}: ${event.line}`)
+  },
+  { stream: 'stderr' },
+)
+
+const ready = await proc.waitFor('ready')
+console.log(`matched ${ready.line}`)
+
+const result = await proc
+unsubscribe()
+
+console.log(result)

package/examples/restart-on-failure.ts

@@ -0,0 +1,42 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import process from 'node:process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { supervise } from 'procband'
+
+const stateDir = mkdtempSync(join(tmpdir(), 'procband-example-'))
+const attemptFile = join(stateDir, 'attempt.txt')
+
+writeFileSync(attemptFile, '0')
+
+const script = [
+  'const fs = await import("node:fs")',
+  'const file = process.argv[1]',
+  'let attempt = Number(fs.readFileSync(file, "utf8"))',
+  'attempt += 1',
+  'fs.writeFileSync(file, String(attempt))',
+  'console.log(`attempt ${attempt}`)',
+  'if (attempt < 3) process.exit(1)',
+  'console.log("ready")',
+].join(';')
+
+const proc = supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', script, attemptFile],
+  restart: {
+    delayMs: 25,
+    maxFailures: 5,
+    windowMs: 1000,
+  },
+})
+
+proc.match(/^attempt \d+$/, event => {
+  console.log(`observed ${event.line}`)
+})
+
+await proc.waitFor('ready')
+const result = await proc
+
+console.log(result)
+rmSync(stateDir, { recursive: true, force: true })

package/examples/sequenced-processes.ts

@@ -0,0 +1,29 @@
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const api = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: [
+    '-e',
+    [
+      'console.log("booting")',
+      'setTimeout(() => console.log("ready"), 20)',
+      'setInterval(() => {}, 1000)',
+    ].join(';'),
+  ],
+})
+
+await api.waitFor('ready')
+
+supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: [
+    '-e',
+    [
+      'console.log("watching")',
+      'setTimeout(() => process.exit(1), 60)',
+    ].join(';'),
+  ],
+})

package/examples/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["./"],
+  "compilerOptions": {
+    "types": ["node"]
+  }
+}

package/package.json

@@ -1,13 +1,42 @@
 {
   "name": "procband",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.2.0",
+  "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
   "license": "MIT",
-  "type": "commonjs"
-}
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aleclarson/procband.git"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples"
+  ],
+  "type": "module",
+  "exports": {
+    "types": "./dist/index.d.mts",
+    "default": "./dist/index.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "dependencies": {
+    "@alloc/tree-kill": "^1.4.0",
+    "ansi-styles": "^6.2.3"
+  },
+  "scripts": {
+    "dev": "tsdown --sourcemap --watch",
+    "build": "tsdown",
+    "docs:check": "pnpm build && tsc -p examples --noEmit && node examples/basic-usage.ts && node examples/restart-on-failure.ts",
+    "format": "oxfmt .",
+    "lint": "oxlint src",
+    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
+    "test": "vitest"
+  }
+}

package/readme.md

@@ -1 +0,0 @@
-Coming soon...