procband 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,8 @@
 
 `procband` supervises subprocesses from TypeScript. It prefixes child output,
 matches future log lines, waits for terminal exit, optionally restarts failed
-processes, and tree-kills descendants during shutdown.
+processes, tree-kills descendants during shutdown, and propagates unobserved
+terminal failures to the parent process.
 
 ## Installation
 
@@ -34,4 +35,5 @@ console.log(result)
 - 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

@@ -190,6 +190,13 @@ interface ProcessResult {
    * 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.
    */
@@ -258,7 +265,7 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
 /**
  * Start supervising a single subprocess.
  *
- * The returned `ProccoliProcess` starts immediately, prefixes child output,
+ * 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.
  *

package/dist/index.mjs

@@ -1,9 +1,10 @@
 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 from "@alloc/tree-kill";
+import treeKill, { treeKillSync } from "@alloc/tree-kill";
 //#region src/colors.ts
 const prefixPalette = [
 	[
@@ -270,7 +271,7 @@ function isFailedExit(code, signal) {
 //#region src/shutdown.ts
 const liveTargets = /* @__PURE__ */ new Set();
 let parentCleanupInstalled = false;
-let handlingSigint = false;
+let handlingSignal = false;
 function registerCleanupTarget(target) {
 	liveTargets.add(target);
 	installParentCleanup();
@@ -280,7 +281,9 @@ function unregisterCleanupTarget(target) {
 	if (liveTargets.size === 0) uninstallParentCleanup();
 }
 function killTreeBestEffort(child, signal) {
-	treeKill(child, signal).catch(() => {});
+	try {
+		treeKillSync(child, signal);
+	} catch {}
 }
 async function stopChildTree(child, close, isClosed, signal, killAfterMs) {
 	try {
@@ -301,29 +304,38 @@ 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() {
-	if (handlingSigint) return;
-	handlingSigint = true;
-	const pending = [...liveTargets].map((target) => target.cleanupFromSigint());
+	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(() => {
-		handlingSigint = false;
-		process.off("SIGINT", onParentSigint);
-		if (process.listenerCount("SIGINT") === 0) {
-			process.kill(process.pid, "SIGINT");
+		handlingSignal = false;
+		process.off(signal, handler);
+		if (process.listenerCount(signal) === 0) {
+			process.kill(process.pid, signal);
 			return;
 		}
-		process.on("SIGINT", onParentSigint);
+		process.on(signal, handler);
 	});
 }
 function isMissingProcessError(error) {
@@ -334,7 +346,7 @@ function isMissingProcessError(error) {
 /**
 * Start supervising a single subprocess.
 *
-* The returned `ProccoliProcess` starts immediately, prefixes child output,
+* 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.
 *
@@ -376,9 +388,11 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	stderrSinkActive = true;
 	stderrSinkCleanup = null;
 	stopPromise = null;
+	shutdownRequested = false;
 	restartDisabled = false;
 	finalized = false;
 	lastResult = null;
+	terminalResultObserved = false;
 	constructor(config) {
 		super();
 		validateProcessConfig(config);
@@ -395,6 +409,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		this.bindStderrSink();
 		this.spawnAttempt();
 		registerCleanupTarget(this);
+		liveProcesses.add(this);
 	}
 	get pid() {
 		return this.currentChild?.pid;
@@ -443,17 +458,13 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		return this.matches.waitFor(pattern, options);
 	}
 	wait() {
+		this.markTerminalResultObserved();
 		return this.finalPromise;
 	}
 	then(onfulfilled, onrejected) {
+		this.markTerminalResultObserved();
 		return this.finalPromise.then(onfulfilled, onrejected);
 	}
-	catch(onrejected) {
-		return this.finalPromise.catch(onrejected);
-	}
-	finally(onfinally) {
-		return this.finalPromise.finally(onfinally);
-	}
 	kill(signal) {
 		const child = this.currentChild;
 		if (!child) return false;
@@ -472,26 +483,29 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	}
 	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 cleanupFromSigint() {
+	async cleanupFromSignal(signal) {
+		this.shutdownRequested = true;
 		this.restartDisabled = true;
 		this.restart.cancelDelay();
-		await this.stopActiveTree("SIGINT", 1e3);
+		await this.stopActiveTree(signal, 1e3);
 	}
 	async stopActiveTree(signal, killAfterMs) {
 		const attempt = this.attempt;
 		if (!attempt || attempt.closed) {
-			await this.wait().then(() => void 0);
+			await this.finalPromise;
 			return;
 		}
 		await stopChildTree(attempt.child, attempt.close, () => attempt.closed, signal, killAfterMs);
@@ -602,6 +616,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		return {
 			name: this.name,
 			code,
+			exitCode: getResultExitCode(code, signal),
 			signal,
 			restarts: this.restart.restarts,
 			restartSuppressed: this.restart.restartSuppressed
@@ -612,11 +627,20 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		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;
@@ -659,10 +683,23 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		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

@@ -13,6 +13,7 @@ Supervision adds four behaviors on top of raw `spawn()`:
 - 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
 
@@ -55,7 +56,10 @@ Supervision adds four behaviors on top of raw `spawn()`:
    `waitFor()`.
 6. When a child exits, `procband` either finalizes or starts a new attempt,
    depending on the restart policy.
-7. `await proc` or `await proc.wait()` resolves only after the process is
+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
@@ -68,6 +72,10 @@ Supervision adds four behaviors on top of raw `spawn()`:
   `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:
@@ -85,11 +93,20 @@ Supervision adds four behaviors on top of raw `spawn()`:
   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.
 
@@ -101,6 +118,8 @@ Supervision adds four behaviors on top of raw `spawn()`:
 - 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

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

@@ -1,6 +1,6 @@
 {
   "name": "procband",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
   "license": "MIT",
   "author": "Alec Larson",
@@ -27,7 +27,7 @@
     "vitest": "^4.1.2"
   },
   "dependencies": {
-    "@alloc/tree-kill": "^1.3.0",
+    "@alloc/tree-kill": "^1.4.0",
     "ansi-styles": "^6.2.3"
   },
   "scripts": {