procband 0.3.1 → 0.3.3

package/dist/index.d.mts

@@ -7,7 +7,7 @@ import { Readable, Writable } from "node:stream";
  */
 type Signals = NodeJS.Signals;
 /**
- * Signal values accepted by `kill()` and `stop()`.
+ * Signal values accepted by `kill()`.
  */
 type KillSignal = number | Signals;
 /**
@@ -47,6 +47,12 @@ interface ProcessConfig {
    * Environment variables for the child process.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Whether to spawn the child in a detached process group/session.
+   *
+   * This is passed through to Node.js `spawn()` unchanged.
+   */
+  detached?: boolean;
   /**
    * Human-facing label used in prefixed output.
    *
@@ -81,7 +87,7 @@ interface ProcessConfig {
    * When provided, `procband` uses this signal for parent-driven cleanup on
    * `SIGINT`, `SIGTERM`, and `exit` instead of mirroring the parent signal or
    * relying on the platform default. This only affects parent-driven cleanup;
-   * `proc.stop()` and `proc.kill()` still use their own explicit signals.
+   * `proc.kill()` still uses its own explicit signal argument.
    */
   parentExitSignal?: KillSignal;
   /**
@@ -180,23 +186,6 @@ 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.
  */
@@ -273,11 +262,11 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<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.
+   * For supervised processes, `kill()` targets the current child process and
+   * any descendants it spawned instead of only the direct child.
+   * `kill(0)` preserves the normal `ChildProcess` existence-check behavior.
    */
-  stop(options?: StopOptions): Promise<void>;
+  kill(signal?: KillSignal): boolean;
 }
 //#endregion
 //#region src/process.d.ts
@@ -310,4 +299,4 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
  */
 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 };
+export { type MatchCallback, type MatchEvent, type MatchOptions, type ProcbandProcess, type ProcessConfig, type ProcessResult, type RestartPolicy, type RgbColor, type Unsubscribe, type WaitForOptions, supervise };

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;
@@ -387,7 +397,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	stderrSink;
 	stderrSinkActive = true;
 	stderrSinkCleanup = null;
-	stopPromise = null;
+	shutdownPromise = null;
 	shutdownRequested = false;
 	restartDisabled = false;
 	finalized = false;
@@ -466,9 +476,12 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		return this.finalPromise.then(onfulfilled, onrejected);
 	}
 	kill(signal) {
-		const child = this.currentChild;
-		if (!child) return false;
-		return child.kill(signal);
+		if (signal === 0) return this.currentChild?.kill(0) ?? false;
+		if (!this.attempt || this.finalized) return false;
+		this.beginShutdown(signal ?? "SIGTERM", 5e3).catch((error) => {
+			this.emit("error", error);
+		});
+		return true;
 	}
 	ref() {
 		this.currentChild?.ref();
@@ -481,26 +494,24 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	disconnect() {
 		this.currentChild?.disconnect();
 	}
-	async stop(options) {
-		if (this.stopPromise) return this.stopPromise;
+	prepareShutdown() {
 		this.shutdownRequested = true;
 		this.restartDisabled = true;
 		this.restart.cancelDelay();
-		this.stopPromise = this.stopActiveTree(options?.signal ?? "SIGTERM", options?.killAfterMs ?? 5e3);
-		return this.stopPromise;
+	}
+	beginShutdown(signal, killAfterMs) {
+		this.prepareShutdown();
+		if (this.shutdownPromise) return this.shutdownPromise;
+		this.shutdownPromise = this.stopActiveTree(signal, killAfterMs);
+		return this.shutdownPromise;
 	}
 	cleanupFromExit() {
-		this.shutdownRequested = true;
-		this.restartDisabled = true;
-		this.restart.cancelDelay();
+		this.prepareShutdown();
 		const child = this.currentChild;
 		if (child) killTreeBestEffort(child, this.getParentCleanupSignal());
 	}
 	async cleanupFromSignal(signal) {
-		this.shutdownRequested = true;
-		this.restartDisabled = true;
-		this.restart.cancelDelay();
-		await this.stopActiveTree(this.getParentCleanupSignal(signal), 1e3);
+		await this.beginShutdown(this.getParentCleanupSignal(signal), 1e3);
 	}
 	async stopActiveTree(signal, killAfterMs) {
 		const attempt = this.attempt;
@@ -517,6 +528,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		this.generation += 1;
 		const child = spawn(this.config.command, this.config.args ?? [], {
 			cwd: this.config.cwd,
+			detached: this.config.detached,
 			env: this.config.env,
 			stdio: [
 				this.config.stdin ? "pipe" : "ignore",
@@ -637,11 +649,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;
 	}
@@ -720,7 +737,7 @@ 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(() => {});
+	for (const proc of liveProcesses) proc.kill();
 }
 //#endregion
 export { supervise };

package/docs/context.md

@@ -36,8 +36,8 @@ Supervision adds five behaviors on top of raw `spawn()`:
 
 - `ProcessConfig`
   Declares one supervised subprocess plus its label, color, restart policy,
-  optional stdin behavior, optional parent-exit signal override, and optional
-  raw `stderr` tee.
+  optional stdin behavior, optional detached spawn mode, optional
+  parent-exit signal override, 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.
@@ -73,7 +73,7 @@ Supervision adds five behaviors on top of raw `spawn()`:
 - React to repeated matching output:
   `proc.match(pattern, callback, options)`
 - Stop the process and its descendants:
-  `proc.stop()`
+  `proc.kill()`
 - Inspect final exit state:
   `await proc` or `await proc.wait()`
 - Take ownership of a process failure:
@@ -95,7 +95,7 @@ Supervision adds five behaviors on top of raw `spawn()`:
 
 # Recommended Patterns
 
-- Use `proc.stop()` for deliberate shutdown initiated by your own script.
+- Use `proc.kill()` for deliberate shutdown initiated by your own script.
 - 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
@@ -103,11 +103,10 @@ Supervision adds five behaviors on top of raw `spawn()`:
 
 # Patterns to Avoid
 
-- Do not treat `parentExitSignal` as a replacement for `StopOptions.signal`.
-  The former only changes parent-driven cleanup; the latter controls
-  explicit `proc.stop()` calls.
-- Do not rely on `kill()` for full shutdown when descendants may still be
-  running. `kill()` only targets the current direct child.
+- Do not treat `parentExitSignal` as a replacement for the signal passed to
+  `proc.kill(signal)`. The former only changes parent-driven cleanup.
+- Do not expect `kill(0)` to stop supervision. `kill(0)` remains an existence
+  check for the current child attempt.
 - Do not expect historical log replay from `match()` or `waitFor()`. Matching
   is future-only by design.
 
@@ -131,12 +130,12 @@ 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()` only signals the current direct child. `stop()` disables restart and
-  kills the full process tree.
+- `kill()` disables future restarts and kills the full process tree, except for
+  `kill(0)`, which 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.stop()` calls.
+  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
@@ -153,7 +152,7 @@ Supervision adds five behaviors on top of raw `spawn()`:
   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.
+- `kill()` emits `error` if tree-kill fails with a non-`ESRCH` error.
 
 # Terminology
 

package/package.json

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