procband 0.3.0 → 0.3.2

package/README.md

@@ -29,9 +29,6 @@ const result = await proc
 console.log(result)
 ```
 
-`stdin` is disabled by default. Set `stdin: true` to write to `proc.stdin`, or
-pass a readable stream to `stdin` to pipe input automatically.
-
 ## Documentation Map
 
 - Concepts and lifecycle: [docs/context.md](docs/context.md)

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.
    *
@@ -75,6 +81,15 @@ interface ProcessConfig {
    * pipe bytes into the child automatically.
    */
   stdin?: boolean | Readable;
+  /**
+   * Signal to send when the parent process is shutting down.
+   *
+   * 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.kill()` still uses its own explicit signal argument.
+   */
+  parentExitSignal?: KillSignal;
   /**
    * Automatic restart behavior for terminal child exits.
    *
@@ -171,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.
  */
@@ -264,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
@@ -301,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

@@ -387,7 +387,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	stderrSink;
 	stderrSinkActive = true;
 	stderrSinkCleanup = null;
-	stopPromise = null;
+	shutdownPromise = null;
 	shutdownRequested = false;
 	restartDisabled = false;
 	finalized = false;
@@ -466,9 +466,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 +484,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);
+		if (child) killTreeBestEffort(child, this.getParentCleanupSignal());
 	}
 	async cleanupFromSignal(signal) {
-		this.shutdownRequested = true;
-		this.restartDisabled = true;
-		this.restart.cancelDelay();
-		await this.stopActiveTree(signal, 1e3);
+		await this.beginShutdown(this.getParentCleanupSignal(signal), 1e3);
 	}
 	async stopActiveTree(signal, killAfterMs) {
 		const attempt = this.attempt;
@@ -510,10 +511,14 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		}
 		await stopChildTree(attempt.child, attempt.close, () => attempt.closed, signal, killAfterMs);
 	}
+	getParentCleanupSignal(fallback) {
+		return this.config.parentExitSignal ?? fallback;
+	}
 	spawnAttempt() {
 		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",
@@ -717,7 +722,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

@@ -7,7 +7,7 @@ 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()`:
+Supervision adds five behaviors on top of raw `spawn()`:
 
 - prefixed `stdout` and `stderr`
 - line-based matching for future output
@@ -36,7 +36,8 @@ Supervision adds four behaviors on top of raw `spawn()`:
 
 - `ProcessConfig`
   Declares one supervised subprocess plus its label, color, restart policy,
-  optional stdin behavior, 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.
@@ -72,7 +73,7 @@ Supervision adds four 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:
@@ -89,6 +90,25 @@ Supervision adds four behaviors on top of raw `spawn()`:
   `restart: true`
 - Use explicit retry rules:
   `restart: { when, delayMs, maxFailures, windowMs }`
+- Force a specific signal during parent shutdown:
+  `parentExitSignal: 'SIGHUP'`
+
+# Recommended Patterns
+
+- 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
+  handling instead of inheriting procband's default parent-exit propagation.
+
+# Patterns to Avoid
+
+- 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.
 
 # Invariants and Constraints
 
@@ -110,10 +130,12 @@ Supervision adds four 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.
+  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.
 - `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
@@ -130,7 +152,7 @@ Supervision adds four 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.0",
+  "version": "0.3.2",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
   "license": "MIT",
   "author": "Alec Larson",