procband 0.3.5 → 0.3.7

package/docs/context.md

@@ -1,184 +1,268 @@
-# Overview
-
-`procband` supervises one subprocess per `supervise()` call.
-
-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 five behaviors on top of raw `spawn()`:
-
-- prefixed `stdout` and `stderr`
-- line-based matching for future output
-- optional restart policy with failure suppression
-- shutdown for the child and descendants, including detached Unix process groups
-- parent-exit propagation for unobserved terminal failures
-
-# When to Use
-
-- You are writing project-specific TypeScript scripts, not a CLI.
-- You need to wait for a subprocess to print a "ready" line.
-- You want readable prefixed logs from multiple long-lived child processes.
-- You need one shutdown API that kills descendant processes too.
-- You want automatic restart with a small built-in guard against tight failure
-  loops.
-
-# When Not to Use
-
-- You need a standalone process manager or service supervisor.
-- You need buffered log history or replay for late subscribers.
-- You need shell pipelines, shell parsing, or a command-line tool.
-- You want one API that supervises many processes at once. `procband` keeps the
-  unit of supervision to one process per call.
-
-# Core Abstractions
-
-- `ProcessConfig`
-  Declares one supervised subprocess plus its label, color, restart policy,
-  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.
-- `MatchEvent`
-  A future matched line from `stdout` or `stderr`.
-- `RestartPolicy`
-  Rules for restart timing and failed-exit suppression.
-
-# Data Flow / Lifecycle
-
-1. `supervise(config)` spawns the first child process immediately.
-2. Child `stdout` and `stderr` are read as text and split into lines.
-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. `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()`.
-7. When a child exits, `procband` either finalizes or starts a new attempt,
-   depending on the restart policy.
-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.
-9. `await proc` or `await proc.wait()` resolves only after the process is
-   terminal and no further restart will happen.
-
-# Common Tasks -> Recommended APIs
-
-- Wait for one readiness line:
-  `proc.waitFor('ready')`
-- React to repeated matching output:
-  `proc.match(pattern, callback, options)`
-- Stop the process and its descendants:
-  `proc.kill()`
-- 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`
-- 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.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
-  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
-
-- Matching is line-based and future-only.
-- String patterns use substring matching.
-- RegExp patterns run against the full observed line.
-- `match()` subscriptions do not interfere with each other.
-- `waitFor()` rejects if the process becomes terminal before a future match is
-  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. `stdin` is `null` unless `ProcessConfig.stdin` is enabled.
-- `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 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
-  trailing `/[-\w]+$/` match from `command`.
-
-# Error Model
-
-- `supervise()` throws synchronously for invalid config such as missing
-  `command`, a `command` that does not produce a fallback `name`, or an
-  invalid reserved color.
-- `waitFor()` rejects on timeout or terminal exit before a future match.
-- 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.
-- `kill()` emits `error` if tree-kill fails with a non-`ESRCH` error.
-
-# Terminology
-
-- Supervised process:
-  A `ProcbandProcess` wrapper plus its current child attempt.
-- Child attempt:
-  One concrete spawned process instance inside a supervision run.
-- Terminal:
-  No child is running and no restart will be started.
-- Restart suppression:
-  Automatic disabling of further restarts after too many failed exits inside the
-  configured window.
-- Match:
-  A future observed output line that satisfies a string or regex pattern.
-
-# Non-Goals
+# Concepts and Lifecycle
+
+> `procband` supervises one child process at a time; this page defines the
+> wrapper lifecycle, restart boundary, shutdown behavior, and failure model that
+> guide pages rely on.
+
+## Core Model
+
+Each `supervise(config)` call creates one supervised process. The returned
+`ProcbandProcess` is both:
+
+| Surface              | What it represents                                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Child-process handle | The current active child attempt. Inherited fields such as `pid`, `stdin`, `stdout`, and `stderr` update across restarts. |
+| Matching surface     | Future output lines observed by `match()` and `waitFor()`.                                                                |
+| Shutdown surface     | `kill()` disables future restarts and stops the current child process tree.                                               |
+| Thenable result      | `await proc` is equivalent to `await proc.wait()` and resolves to the terminal `ProcessResult`.                           |
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+
+await proc.waitFor('ready')
+const result = await proc
+```
+
+After the readiness line is observed, `result` is available only when the
+process is terminal and no restart delay or attempt remains.
+
+## Lifecycle
+
+1. `supervise(config)` validates the config and spawns the first child
+   immediately.
+2. Child `stdout` and `stderr` are decoded as UTF-8 text and split into lines.
+3. Each line is written to the parent `process.stdout` or `process.stderr` with
+   a process prefix unless `ProcessConfig.prefix` is `false`. `stderr` prefixes
+   always use the reserved red color.
+4. If `ProcessConfig.stderr` is provided, raw child `stderr` bytes are also
+   written to that sink.
+5. Matching subscribers receive future lines through `match()` callbacks or
+   `waitFor()` promises.
+6. When the child exits, `procband` either finalizes or schedules another child
+   attempt according to the restart policy.
+7. `await proc`, `await proc.wait()`, and `await proc.expectSuccess()` settle
+   only after the supervised process is terminal.
+
+Use this shape when one process must become ready before another starts:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const api = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'setTimeout(() => console.log("ready"), 20)'],
+})
+
+await api.waitFor('ready')
+
+supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'console.log("watching")'],
+})
+```
+
+The worker starts after the API prints a future line containing `ready`.
+
+## Output Prefixes
+
+By default, each child output line is written to the parent terminal with the
+process label:
+
+```ts
+supervise({
+  name: 'server',
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+```
+
+Set `prefix: false` when a child should keep raw `stdout` and `stderr` output:
+
+```ts
+supervise({
+  name: 'server',
+  prefix: false,
+  command: process.execPath,
+  args: ['-e', 'console.log("ready")'],
+})
+```
+
+Disabling the prefix changes only parent-visible output and procband
+diagnostics. Matching events and final results still use the process `name`.
+
+## Matching
+
+Matching is line-based and future-only. A subscription sees lines emitted after
+the subscription is registered; it does not replay earlier output.
+
+| Pattern  | Behavior                                                                     |
+| -------- | ---------------------------------------------------------------------------- |
+| String   | Matches when the observed line includes the string.                          |
+| `RegExp` | Runs against the full observed line. `lastIndex` is reset before each match. |
+
+Use `waitFor()` for one required line:
+
+```ts
+const event = await proc.waitFor(/^ready$/, {
+  stream: 'stdout',
+  timeoutMs: 5000,
+})
+
+console.log(event.process, event.line)
+```
+
+Use `match()` for repeated lines:
+
+```ts
+const unsubscribe = proc.match(
+  /^attempt \d+$/,
+  (event) => {
+    console.log(`observed ${event.line}`)
+  },
+  { stream: 'stdout' },
+)
+
+unsubscribe()
+```
+
+`waitFor()` rejects when its timeout elapses or the process becomes terminal
+before a matching future line appears. If a `match()` callback throws, only that
+subscription is removed.
+
+## Restarts
+
+`restart: true` uses the built-in policy:
+
+| Field         | Default        | Meaning                                                  |
+| ------------- | -------------- | -------------------------------------------------------- |
+| `when`        | `'on-failure'` | Restart only non-zero exits or signal exits.             |
+| `delayMs`     | `1000`         | Wait this long before the next attempt.                  |
+| `maxFailures` | `3`            | Suppress restart after more than this many failed exits. |
+| `windowMs`    | `30000`        | Count failed exits inside this rolling window.           |
+
+Pass an explicit policy when the defaults are too slow or too permissive:
+
+```ts
+const proc = supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+  restart: {
+    delayMs: 25,
+    maxFailures: 5,
+    windowMs: 1000,
+  },
+})
+
+const result = await proc
+console.log(result.restarts, result.restartSuppressed)
+```
+
+If the child keeps failing inside the configured window, `restartSuppressed`
+becomes `true` and the final failed result is returned.
+
+## Shutdown
+
+Use `proc.kill()` for deliberate shutdown from your own script:
+
+```ts
+const stopped = proc.kill('SIGTERM')
+```
+
+`kill()` disables future restarts and stops the active child process tree. For
+`detached: true` children on Unix-like platforms, shutdown also signals the
+detached child process group so same-group descendants are cleaned up even when
+they are no longer reachable by parent PID.
+
+> [!NOTE]
+> `kill(0)` keeps the normal Node.js existence-check behavior. It does not stop
+> supervision or disable restarts.
+
+Parent cleanup installs `SIGINT` and `SIGTERM` handlers while live supervised
+processes exist. Set `parentExitSignal` only when children require a specific
+signal during parent-driven cleanup:
+
+```ts
+supervise({
+  name: 'server',
+  command: process.execPath,
+  args: ['server.mjs'],
+  parentExitSignal: 'SIGHUP',
+})
+```
+
+`parentExitSignal` does not change the signal used by explicit `proc.kill()`
+calls.
+
+## Failure Model
+
+`procband` separates terminal process failure from promise rejection:
+
+| API                                    | Failed terminal exit                                                                |
+| -------------------------------------- | ----------------------------------------------------------------------------------- |
+| `await proc`                           | Resolves to `ProcessResult`.                                                        |
+| `proc.wait()`                          | Resolves to `ProcessResult`.                                                        |
+| `proc.wait({ rejectOnFailure: true })` | Rejects with `ProcessExitError`.                                                    |
+| `proc.expectSuccess()`                 | Rejects with `ProcessExitError`.                                                    |
+| Unobserved process                     | Sets parent `process.exitCode` and starts stopping other live supervised processes. |
+
+`ProcessExitError` includes the original config, final result, command, args,
+exit code, and signal:
+
+```ts
+import { ProcessExitError } from 'procband'
+
+try {
+  await proc.expectSuccess()
+} catch (error) {
+  if (error instanceof ProcessExitError) {
+    console.error(error.command, error.exitCode, error.signal)
+  }
+  throw error
+}
+```
+
+## Configuration Boundaries
+
+| Field      | Boundary                                                                                                         |
+| ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| `command`  | Required shell-free executable or command name passed to `spawn()`.                                              |
+| `name`     | Optional stable process identifier. Defaults to the trailing `/[-\w]+$/` match from `command`.                   |
+| `label`    | Optional human-facing output prefix. Defaults to `name`.                                                         |
+| `prefix`   | Defaults to `true`. Set to `false` to write output and diagnostics without the process label prefix.             |
+| `stdin`    | Defaults to disconnected. Use `true` for writable `proc.stdin`, or pass a readable stream to pipe automatically. |
+| `stderr`   | Optional extra sink for raw child `stderr`; prefixed parent `stderr` output still happens.                       |
+| `detached` | Passed through to `spawn()` and used during shutdown on Unix-like platforms.                                     |
+| `color`    | Optional RGB prefix color for `stdout`; reserved `stderr` red cannot be used.                                    |
+
+Invalid config, such as a missing `command`, a command without an inferable
+fallback `name`, or a reserved color, throws synchronously from `supervise()`.
+
+## Terminology
+
+| Term                | Meaning                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| Supervised process  | A `ProcbandProcess` wrapper plus its current child attempt.                                       |
+| Child attempt       | One concrete spawned process instance inside a supervision run.                                   |
+| Terminal            | No child is running and no restart will be started.                                               |
+| Restart suppression | Automatic disabling of further restarts after too many failed exits inside the configured window. |
+| Match               | A future observed output line that satisfies a string or regex pattern.                           |
+
+## Non-Goals
 
 - A standalone CLI
 - Historical log replay
 - Multi-process orchestration in one top-level API
 - Shell command parsing
-- Full service-management features such as persistence, cron scheduling, or host
+- Service-management features such as persistence, cron scheduling, or host
   restarts

package/docs/guides/foreground-commands.md

@@ -0,0 +1,80 @@
+# Foreground Commands
+
+> Use `expectSuccess()` when a supervised child process represents a script step
+> that must succeed before the parent script can continue.
+
+`procband` normally resolves failed exits to `ProcessResult` because background
+supervision often needs to inspect failures instead of throwing immediately.
+Foreground command-runner steps usually want the opposite behavior.
+
+## Reject Failed Exits
+
+Use `expectSuccess()` when a non-zero exit or signal exit should reject:
+
+```ts
+import process from 'node:process'
+import { ProcessExitError, supervise } from 'procband'
+
+try {
+  await supervise({
+    name: 'db',
+    command: 'pnpm',
+    args: ['db', 'ensure'],
+  }).expectSuccess()
+} catch (error) {
+  if (error instanceof ProcessExitError) {
+    console.error(error.command, error.args, error.exitCode)
+  }
+  throw error
+}
+```
+
+When the command exits successfully, the promise resolves to `ProcessResult`.
+When it fails, `ProcessExitError` exposes the command, args, exit code, signal,
+original config, and terminal result.
+
+## Use `wait()` When the Choice Is Dynamic
+
+`expectSuccess()` is equivalent to `wait({ rejectOnFailure: true })`. Use
+`wait()` when a caller decides the behavior:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'check',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+})
+
+const result = await proc.wait({ rejectOnFailure: shouldThrow })
+```
+
+If `shouldThrow` is `false`, the failed exit resolves to `ProcessResult`. If it
+is `true`, the same exit rejects with `ProcessExitError`.
+
+## Let Background Failures Propagate
+
+For background processes that should fail the parent script when nobody handles
+their result, leave the process unobserved:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'setTimeout(() => process.exit(1), 60)'],
+})
+```
+
+If this process reaches a failed terminal state and no code has awaited it or
+called `wait()`, `procband` sets the parent `process.exitCode` and starts
+stopping other live `procband` processes in the same parent script.
+
+> [!IMPORTANT]
+> Awaiting `proc` or calling `proc.wait()` marks the terminal result as
+> observed. Once observed, default parent-exit propagation is suppressed for
+> that process.

package/docs/guides/readiness.md

@@ -0,0 +1,104 @@
+# Readiness and Matching
+
+> Use future line matching when a parent script must wait for a child process to
+> announce readiness or react to repeated output without buffering log history.
+
+Matching starts when you call `waitFor()` or `match()`. Earlier output is not
+replayed, so create the supervised process and register the wait before the line
+you need can be missed.
+
+## Wait for One Line
+
+Use `waitFor()` when the next step cannot start until the child prints a known
+line:
+
+```ts
+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(';'),
+  ],
+})
+
+const event = await api.waitFor('ready', {
+  stream: 'stdout',
+  timeoutMs: 5000,
+})
+
+console.log(`api is ${event.line}`)
+```
+
+The wait resolves with the first future `stdout` line that contains `ready`.
+When `timeoutMs` elapses first, or the process exits before a matching line is
+observed, the wait rejects.
+
+## Match Repeated Lines
+
+Use `match()` when the child may print the same kind of line many times:
+
+```ts
+const unsubscribe = api.match(
+  /^warn:/,
+  (event) => {
+    console.log(`observed ${event.stream}: ${event.line}`)
+  },
+  { stream: 'stderr' },
+)
+
+// Later, when this script no longer needs warning callbacks:
+unsubscribe()
+```
+
+Each subscription is independent. If one callback throws, that subscription is
+removed and other subscriptions keep running.
+
+## Choose a Pattern
+
+| Pattern     | Best for                             | Result detail                                      |
+| ----------- | ------------------------------------ | -------------------------------------------------- |
+| `'ready'`   | Simple substring checks.             | `event.match` is `null`.                           |
+| `/^ready$/` | Exact line shape or captured values. | `event.match` contains the `RegExp.exec()` result. |
+
+```ts
+const event = await api.waitFor(/^listening on (\d+)$/)
+const port = Number(event.match?.[1])
+```
+
+The regular expression runs against the full observed line without the trailing
+newline.
+
+## Start Another Process After Readiness
+
+This pattern keeps sequencing explicit: wait for the first process, then start
+the dependent process.
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const api = supervise({
+  name: 'api',
+  command: process.execPath,
+  args: ['-e', 'setTimeout(() => console.log("ready"), 20)'],
+})
+
+await api.waitFor('ready')
+
+supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'console.log("watching")'],
+})
+```
+
+After the API prints `ready`, the worker starts and its output is prefixed
+separately.