procband 0.3.5 → 0.3.7

package/docs/guides/restarts.md

@@ -0,0 +1,115 @@
+# Restart Failed Processes
+
+> Add a restart policy when a child process may fail transiently and the parent
+> script should retry before treating the supervision run as terminal.
+
+Restarts are disabled by default. Enable them per process with `restart: true`
+or an explicit `RestartPolicy`.
+
+## Use the Built-In Policy
+
+Use `restart: true` when the defaults are acceptable:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'worker',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+  restart: true,
+})
+
+const result = await proc
+console.log(result.restarts, result.restartSuppressed)
+```
+
+The default policy restarts failed exits after `1000` milliseconds and suppresses
+restart after more than `3` failed exits inside `30000` milliseconds.
+
+## Set an Explicit Policy
+
+Use an explicit policy when tests, examples, or short-lived scripts need faster
+feedback:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const proc = supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+  restart: {
+    when: 'on-failure',
+    delayMs: 25,
+    maxFailures: 5,
+    windowMs: 1000,
+  },
+})
+```
+
+With this policy, failed attempts are retried after `25` milliseconds. Once more
+than `5` failures occur inside `1000` milliseconds, `procband` stops retrying
+and resolves the terminal result with `restartSuppressed: true`.
+
+## Wait for a Later Attempt
+
+`waitFor()` watches future output across restart attempts, so it can wait for a
+line that appears only after earlier attempts fail:
+
+```ts
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import process from 'node:process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { supervise } from 'procband'
+
+const stateDir = mkdtempSync(join(tmpdir(), 'procband-example-'))
+const attemptFile = join(stateDir, 'attempt.txt')
+writeFileSync(attemptFile, '0')
+
+const script = [
+  'const fs = await import("node:fs")',
+  'const file = process.argv[1]',
+  'let attempt = Number(fs.readFileSync(file, "utf8"))',
+  'attempt += 1',
+  'fs.writeFileSync(file, String(attempt))',
+  'console.log(`attempt ${attempt}`)',
+  'if (attempt < 3) process.exit(1)',
+  'console.log("ready")',
+].join(';')
+
+const proc = supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', script, attemptFile],
+  restart: {
+    delayMs: 25,
+    maxFailures: 5,
+    windowMs: 1000,
+  },
+})
+
+proc.match(/^attempt \d+$/, (event) => {
+  console.log(`observed ${event.line}`)
+})
+
+await proc.waitFor('ready')
+const result = await proc
+```
+
+The first two attempts can exit unsuccessfully, the third attempt can print
+`ready`, and the final result includes the number of restart attempts that were
+started.
+
+## Pick `when` Deliberately
+
+| `when`         | Restarts after                   | Use it when                                                                          |
+| -------------- | -------------------------------- | ------------------------------------------------------------------------------------ |
+| `'on-failure'` | Non-zero exits and signal exits. | A clean exit means the work is done.                                                 |
+| `'on-exit'`    | Any exit.                        | The child is expected to be long-lived and should be relaunched even after code `0`. |
+
+`proc.kill()` disables future restarts before stopping the active process tree,
+so deliberate shutdown does not start another attempt.

package/docs/index.md

@@ -0,0 +1,61 @@
+# Documentation Overview
+
+> Choose the right `procband` behavior before reaching for an API: readiness
+> matching, failure observation, restart policy, and shutdown each change how a
+> script should supervise its child process.
+
+`procband` is for TypeScript scripts that need to run child processes with a
+small amount of supervision. It is not a daemon, service manager, CLI runner, or
+multi-process orchestrator.
+
+## What It Adds
+
+Each `supervise()` call wraps one child process and adds five behaviors on top
+of Node.js `spawn()`:
+
+| Behavior                       | Use it when                                                                |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| Optional prefixed output       | Multiple child processes write to the same parent terminal.                |
+| Future line matching           | The parent script must wait for a readiness line or react to logs.         |
+| Optional restarts              | A transient failure should start another child attempt.                    |
+| Process-tree shutdown          | Deliberate cleanup should stop descendants as well as the direct child.    |
+| Unobserved failure propagation | A background failure should fail the parent script when nobody awaited it. |
+
+```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')
+```
+
+After `supervise()` runs, the child has already started and future output can be
+matched.
+
+## First Decisions
+
+| Decision         | Default                                       | Change it when                                                             |
+| ---------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
+| Process identity | `name` is inferred from `command`.            | The command path does not end in `/[-\w]+$/`, or logs need a stable label. |
+| Output prefix    | Child output is labeled.                      | Pass `prefix: false` when the child should write raw output.               |
+| Failure handling | Awaiting resolves to `ProcessResult`.         | Use `expectSuccess()` for command-runner steps that should reject.         |
+| Matching scope   | `waitFor()` and `match()` watch both streams. | Pass `{ stream: 'stdout' }` or `{ stream: 'stderr' }` to narrow matching.  |
+| Restart behavior | No restart.                                   | Pass `restart: true` or a policy for transient child failures.             |
+| Stdin            | Disconnected.                                 | Pass `stdin: true` or a readable stream when the child needs input.        |
+
+## Where to Go Next
+
+| Page                                                 | Reader job                                                          |
+| ---------------------------------------------------- | ------------------------------------------------------------------- |
+| [Readiness and matching](guides/readiness.md)        | Wait for future output or subscribe to repeated matching lines.     |
+| [Restart failed processes](guides/restarts.md)       | Configure retries with a failure-suppression guard.                 |
+| [Foreground commands](guides/foreground-commands.md) | Make a supervised command reject on failed exit.                    |
+| [Concepts and lifecycle](context.md)                 | Understand terminal state, shutdown, config boundaries, and errors. |
+
+Runnable scripts in [`../examples/`](../examples/) cover the same workflows with
+project-realistic child processes that can be checked by `pnpm docs:check`.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "procband",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
+  "packageManager": "pnpm@11.5.1",
   "license": "MIT",
   "author": "Alec Larson",
   "repository": {
@@ -18,8 +19,19 @@
     "types": "./dist/index.d.mts",
     "default": "./dist/index.mjs"
   },
+  "scripts": {
+    "dev": "tsdown --sourcemap --watch",
+    "build": "tsdown",
+    "docs:check": "pnpm build && tsc -p examples --noEmit && node examples/basic-usage.ts && node examples/restart-on-failure.ts",
+    "format": "oxfmt .",
+    "lint": "oxlint src",
+    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
+    "test": "vitest",
+    "prepublishOnly": "pnpm build"
+  },
   "devDependencies": {
     "@types/node": "^25.5.2",
+    "lildocs": "^0.1.11",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.58.0",
     "tsdown": "^0.21.7",
@@ -29,14 +41,5 @@
   "dependencies": {
     "@alloc/tree-kill": "^1.4.0",
     "ansi-styles": "^6.2.3"
-  },
-  "scripts": {
-    "dev": "tsdown --sourcemap --watch",
-    "build": "tsdown",
-    "docs:check": "pnpm build && tsc -p examples --noEmit && node examples/basic-usage.ts && node examples/restart-on-failure.ts",
-    "format": "oxfmt .",
-    "lint": "oxlint src",
-    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
-    "test": "vitest"
   }
-}
+}