procband 0.2.3 → 0.3.1

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { ChildProcess } from "node:child_process";
-import { Writable } from "node:stream";
+import { Readable, Writable } from "node:stream";
 
 //#region src/types.d.ts
 /**
@@ -67,6 +67,23 @@ interface ProcessConfig {
    * `process.stderr`.
    */
   stderr?: Writable;
+  /**
+   * Child stdin behavior.
+   *
+   * Defaults to `false`, which connects the child stdin to the null device.
+   * Use `true` to expose a writable `proc.stdin`, or pass a readable stream to
+   * 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.stop()` and `proc.kill()` still use their own explicit signals.
+   */
+  parentExitSignal?: KillSignal;
   /**
    * Automatic restart behavior for terminal child exits.
    *

package/dist/index.mjs

@@ -494,13 +494,13 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		this.restartDisabled = true;
 		this.restart.cancelDelay();
 		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.stopActiveTree(this.getParentCleanupSignal(signal), 1e3);
 	}
 	async stopActiveTree(signal, killAfterMs) {
 		const attempt = this.attempt;
@@ -510,13 +510,16 @@ 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,
 			env: this.config.env,
 			stdio: [
-				"pipe",
+				this.config.stdin ? "pipe" : "ignore",
 				"pipe",
 				"pipe"
 			]
@@ -537,13 +540,15 @@ var ProcbandProcessImpl = class extends EventEmitter {
 				text: "",
 				flushed: false
 			},
-			closed: false
+			closed: false,
+			stdinCleanup: null
 		};
 		this.attempt = attempt;
 		this.attachAttempt(attempt);
 	}
 	attachAttempt(attempt) {
 		const { child } = attempt;
+		attempt.stdinCleanup = this.bindAttemptStdin(attempt);
 		child.on("spawn", () => {
 			if (this.attempt === attempt) this.emit("spawn");
 		});
@@ -556,6 +561,8 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		child.on("close", (code, signal) => {
 			if (this.attempt !== attempt) return;
 			attempt.closed = true;
+			attempt.stdinCleanup?.();
+			attempt.stdinCleanup = null;
 			this.flushLineBuffer(attempt, "stdout");
 			this.flushLineBuffer(attempt, "stderr");
 			attempt.settleClose({
@@ -682,6 +689,15 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		buffer.text = "";
 		this.handleLine(stream, line, false);
 	}
+	bindAttemptStdin(attempt) {
+		const source = this.config.stdin;
+		const destination = attempt.child.stdin;
+		if (!destination || typeof source !== "object") return null;
+		source.pipe(destination);
+		return () => {
+			source.unpipe(destination);
+		};
+	}
 };
 const liveProcesses = /* @__PURE__ */ new Set();
 let propagatedFailure = false;

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
@@ -35,8 +35,9 @@ Supervision adds four behaviors on top of raw `spawn()`:
 # Core Abstractions
 
 - `ProcessConfig`
-  Declares one supervised subprocess plus its label, color, restart policy, and
-  optional raw `stderr` tee.
+  Declares one supervised subprocess plus its label, color, restart policy,
+  optional stdin behavior, 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.
@@ -52,14 +53,17 @@ Supervision adds four behaviors on top of raw `spawn()`:
 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
+5. `stdin` is disconnected by default. Set `ProcessConfig.stdin` to `true` for
+   a writable child stdin, or pass a readable stream to pipe input into the
+   child automatically.
+6. Future matching lines are delivered through `match()` callbacks or
    `waitFor()`.
-6. When a child exits, `procband` either finalizes or starts a new attempt,
+7. 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
+8. 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
+9. `await proc` or `await proc.wait()` resolves only after the process is
    terminal and no further restart will happen.
 
 # Common Tasks -> Recommended APIs
@@ -78,10 +82,34 @@ Supervision adds four behaviors on top of raw `spawn()`:
   Do not call `wait()` or await the thenable result
 - Capture raw child `stderr` in a file or custom stream:
   `ProcessConfig.stderr`
+- Write to child stdin manually:
+  `stdin: true`, then `proc.stdin?.write(...)`
+- Pipe a custom input stream into the child:
+  `stdin: readable`
 - Retry failed exits with sane defaults:
   `restart: true`
 - Use explicit retry rules:
   `restart: { when, delayMs, maxFailures, windowMs }`
+- Force a specific signal during parent shutdown:
+  `parentExitSignal: 'SIGHUP'`
+
+# Recommended Patterns
+
+- Use `proc.stop()` 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 `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 expect historical log replay from `match()` or `waitFor()`. Matching
+  is future-only by design.
 
 # Invariants and Constraints
 
@@ -102,11 +130,13 @@ Supervision adds four behaviors on top of raw `spawn()`:
   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.
+  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.
 - 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.stop()` 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.2.3",
+  "version": "0.3.1",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
   "license": "MIT",
   "author": "Alec Larson",