procband 0.3.2 → 0.3.4

package/dist/index.d.mts

@@ -50,7 +50,10 @@ interface ProcessConfig {
   /**
    * Whether to spawn the child in a detached process group/session.
    *
-   * This is passed through to Node.js `spawn()` unchanged.
+   * This is passed through to Node.js `spawn()` unchanged. On Unix-like
+   * platforms, shutdown also signals the detached child's process group so
+   * same-group descendants are cleaned up even if they are no longer reachable
+   * through the child process tree.
    */
   detached?: boolean;
   /**
@@ -263,7 +266,8 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
    * Disable future restarts and terminate the active process tree.
    *
    * For supervised processes, `kill()` targets the current child process and
-   * any descendants it spawned instead of only the direct child.
+   * any descendants it spawned instead of only the direct child. Detached
+   * Unix-like children are also stopped by process group.
    * `kill(0)` preserves the normal `ChildProcess` existence-check behavior.
    */
   kill(signal?: KillSignal): boolean;

package/dist/index.mjs

@@ -111,7 +111,7 @@ var MatchRegistry = class {
 	}
 	waitFor(pattern, options) {
 		if (this.closedError) return Promise.reject(this.closedError);
-		return new Promise((resolve, reject) => {
+		const promise = new Promise((resolve, reject) => {
 			const subscription = {
 				active: true,
 				kind: "promise",
@@ -125,6 +125,9 @@ var MatchRegistry = class {
 					this.unsubscribe(subscription);
 					reject(error);
 				},
+				suppressUnhandledRejection: () => {
+					promise.catch(() => {});
+				},
 				timer: null
 			};
 			if (options?.timeoutMs != null) subscription.timer = setTimeout(() => {
@@ -132,6 +135,7 @@ var MatchRegistry = class {
 			}, options.timeoutMs);
 			this.subscriptions.add(subscription);
 		});
+		return promise;
 	}
 	emit(stream, line) {
 		if (this.closedError) return;
@@ -155,11 +159,17 @@ var MatchRegistry = class {
 			subscription.resolve(event);
 		}
 	}
+	hasPendingWait() {
+		for (const subscription of this.subscriptions) if (subscription.kind === "promise") return true;
+		return false;
+	}
 	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);
+		for (const subscription of [...this.subscriptions]) if (subscription.kind === "promise") {
+			subscription.suppressUnhandledRejection();
+			subscription.reject(error);
+		} else this.unsubscribe(subscription);
 	}
 	unsubscribe(subscription) {
 		if (!subscription.active) return;
@@ -280,18 +290,23 @@ function unregisterCleanupTarget(target) {
 	liveTargets.delete(target);
 	if (liveTargets.size === 0) uninstallParentCleanup();
 }
-function killTreeBestEffort(child, signal) {
+function killTreeBestEffort(child, signal, options = {}) {
+	if (options.detached) try {
+		killProcessGroup(child, signal);
+	} catch {}
 	try {
 		treeKillSync(child, signal);
 	} catch {}
 }
-async function stopChildTree(child, close, isClosed, signal, killAfterMs) {
+async function stopChildTree(child, close, isClosed, signal, killAfterMs, options = {}) {
+	if (options.detached) killProcessGroup(child, signal);
 	try {
 		await treeKill(child, signal);
 	} catch (error) {
 		if (!isMissingProcessError(error)) throw error;
 	}
 	if (!await Promise.race([close.then(() => true), setTimeout$1(killAfterMs, false)]) && !isClosed()) {
+		if (options.detached) killProcessGroup(child, "SIGKILL");
 		try {
 			await treeKill(child, "SIGKILL");
 		} catch (error) {
@@ -300,6 +315,14 @@ async function stopChildTree(child, close, isClosed, signal, killAfterMs) {
 		await close;
 	}
 }
+function killProcessGroup(child, signal) {
+	if (process.platform === "win32" || !child.pid) return;
+	try {
+		process.kill(-child.pid, signal);
+	} catch (error) {
+		if (!isMissingProcessError(error)) throw error;
+	}
+}
 function installParentCleanup() {
 	if (parentCleanupInstalled) return;
 	parentCleanupInstalled = true;
@@ -498,7 +521,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	cleanupFromExit() {
 		this.prepareShutdown();
 		const child = this.currentChild;
-		if (child) killTreeBestEffort(child, this.getParentCleanupSignal());
+		if (child) killTreeBestEffort(child, this.getParentCleanupSignal(), { detached: this.config.detached });
 	}
 	async cleanupFromSignal(signal) {
 		await this.beginShutdown(this.getParentCleanupSignal(signal), 1e3);
@@ -509,7 +532,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 			await this.finalPromise;
 			return;
 		}
-		await stopChildTree(attempt.child, attempt.close, () => attempt.closed, signal, killAfterMs);
+		await stopChildTree(attempt.child, attempt.close, () => attempt.closed, signal, killAfterMs, { detached: this.config.detached });
 	}
 	getParentCleanupSignal(fallback) {
 		return this.config.parentExitSignal ?? fallback;
@@ -639,11 +662,16 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		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.closeMatches();
 		this.unbindStderrSink();
 		unregisterCleanupTarget(this);
 		this.finalResolve(result);
 	}
+	closeMatches() {
+		const error = /* @__PURE__ */ new Error(`Process "${this.name}" exited before a matching line was observed`);
+		if (this.matches.hasPendingWait()) writePrefixedLine(process.stderr, this.label, stderrColor, error.message, true);
+		this.matches.close(error);
+	}
 	markTerminalResultObserved() {
 		this.terminalResultObserved = true;
 	}

package/docs/context.md

@@ -12,7 +12,7 @@ Supervision adds five 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
+- shutdown for the child and descendants, including detached Unix process groups
 - parent-exit propagation for unobserved terminal failures
 
 # When to Use
@@ -96,6 +96,9 @@ Supervision adds five behaviors on top of raw `spawn()`:
 # Recommended Patterns
 
 - Use `proc.kill()` for deliberate shutdown initiated by your own script.
+- Use `detached: true` when a child must run in its own process group/session.
+  On Unix-like platforms, `procband` uses that process group during shutdown in
+  addition to process-tree cleanup.
 - Reserve `parentExitSignal` for children that expect a specific signal from
   their supervisor during parent-driven cleanup.
 - Await `proc` or call `proc.wait()` when your script intends to own failure
@@ -130,12 +133,15 @@ Supervision adds five behaviors on top of raw `spawn()`:
 - The wrapper survives restarts, but inherited `pid`, `stdin`, `stdout`,
   `stderr`, and related `ChildProcess` fields always refer to the current active
   child attempt. `stdin` is `null` unless `ProcessConfig.stdin` is enabled.
-- `kill()` disables future restarts and kills the full process tree, except for
-  `kill(0)`, which only checks whether the current child attempt exists.
+- `kill()` disables future restarts and kills the full process tree. For
+  `detached: true` children on Unix-like platforms, shutdown also signals the
+  detached child's process group so same-group descendants are cleaned up even
+  when they are no longer reachable by parent PID. `kill(0)` only checks
+  whether the current child attempt exists.
 - Parent cleanup installs both `SIGINT` and `SIGTERM` handlers while any live
   supervised process exists. Set `ProcessConfig.parentExitSignal` to override
-  which signal is sent to the child tree during parent-driven cleanup. This
-  does not change the signal used by explicit `proc.kill()` calls.
+  which signal is sent during parent-driven cleanup. This does not change the
+  signal used by explicit `proc.kill()` calls.
 - `stderr` prefixes always use the reserved red, even when a custom process
   color is configured.
 - `ProcessConfig.name` is optional. When omitted, it falls back to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procband",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
   "license": "MIT",
   "author": "Alec Larson",