tape-six-proc 1.2.8 → 1.3.0

package/README.md

@@ -14,6 +14,11 @@ in its own subprocess instead, providing full process isolation. This prevents s
 leaks and is useful when tests need a clean environment. TypeScript test files (`.ts`)
 run natively on modern Node, Deno, and Bun — no transpilation needed.
 
+A control channel lets the runner stop workers mid-run: `failOnce` (flag `O`) drains
+the test files still in flight, and `TAPE6_WORKER_TIMEOUT` sets a per-worker time limit.
+Both cancel cooperatively (cleanup hooks run) with a force-kill backstop after
+`TAPE6_GRACE_TIMEOUT`. See [Stopping tests early](https://github.com/uhop/tape-six-proc/wiki/Utility-%E2%80%90-tape6-proc#stopping-tests-early).
+
 ## Install
 
 ```bash
@@ -88,6 +93,8 @@ LLM-friendly documentation is available:
 
 The most recent releases:
 
+- 1.3.0 _Implemented the terminate protocol. Updated dependencies._
+- 1.2.9 _Added `js-check`, Bun + Deno CI, tuned dependabot. Updated dependencies._
 - 1.2.8 _Fixed Bun stdout flush bug. Added GitHub Actions CI. Updated dependencies._
 - 1.2.7 _Added `--help` and `--version` flags. Updated dependencies._
 - 1.2.6 _Updated dependencies. Added AI agent rule files. Improved workflows._

package/bin/tape6-proc-node.js

@@ -102,7 +102,7 @@ const main = async () => {
   }
 
   const reporter = getReporter(),
-    worker = new TestWorker(reporter, options.parallel, options.flags);
+    worker = /** @type {*} */ (new TestWorker(reporter, options.parallel, options.flags));
 
   reporter.report({type: 'test', test: 0});
 

package/llms-full.txt

@@ -9,6 +9,7 @@
 - Same configuration format as `tape-six`
 - Parallel execution with configurable concurrency
 - TAP, TTY (colored), JSONL, and minimal output formats
+- Worker control channel: `failOnce` stops in-flight workers, plus an optional per-worker time limit
 
 ## Install
 
@@ -115,7 +116,7 @@ Flags are a string of characters. Uppercase = enabled, lowercase = disabled.
 - `T` — show Time for each test.
 - `B` — show Banner with summary.
 - `D` — show Data of failed tests.
-- `O` — fail Once: stop at first failure.
+- `O` — fail Once: stop at first failure. Via the control channel this also drains the workers still in flight (cleanup hooks run), not just the file queue.
 - `N` — show assert Number.
 - `M` — Monochrome: no colors.
 - `C` — don't Capture console output.
@@ -150,9 +151,12 @@ Environment-specific subsections (`node`, `deno`, `bun`) are supported. The runn
 - `TAPE6_TAP` — force TAP reporter (any non-empty value).
 - `TAPE6_JSONL` — force JSONL reporter (any non-empty value).
 - `TAPE6_MIN` — force minimal reporter (any non-empty value).
+- `TAPE6_GRACE_TIMEOUT` — milliseconds a worker is given to drain (run cleanup hooks, flush) after a `terminate` before it is force-killed. Default 5000. Shared with `tape-six`.
+- `TAPE6_WORKER_TIMEOUT` — per-worker wall-clock deadline in milliseconds; on expiry the worker is terminated (drain → kill). Default 0 (disabled). Shared with `tape-six`.
 - `TAPE6_TEST` — set by the runner: unique ID for each spawned test process.
 - `TAPE6_TEST_FILE_NAME` — set by the runner: file name of the current test.
 - `TAPE6_JSONL_PREFIX` — set by the runner: UUID prefix for JSONL lines in stdout.
+- `TAPE6_CONTROL` — set by the runner: marks a spawned child as controlled, so the tape-six runtime opens the stdin control channel and stays alive after `end` until told to exit.
 
 ## Architecture
 
@@ -178,12 +182,12 @@ Delegates argument parsing, reporter setup, and file resolution to `tape-six/uti
 Extends `EventServer` from `tape-six`. Manages parallel subprocess execution:
 
 - **`constructor(reporter, numberOfTasks, options)`** — initializes with a reporter, concurrency limit, and options. Generates a UUID prefix for JSONL parsing.
-- **`makeTask(fileName)`** — spawns a child process for a test file using `dollar-shell`. Sets up stream pipelines for stdout and stderr. Returns a task ID.
-- **`destroyTask(id)`** — cleans up a completed task.
+- **`makeTask(fileName)`** — spawns a child process for a test file using `dollar-shell` (`stdin: 'pipe'` so it can be controlled). Sets up stream pipelines for stdout and stderr, marks completion when the child's top-level `end` is read, and reports premature exits. Returns a task ID.
+- **`destroyTask(id, reason)`** — the control-plane terminate. Writes a line-delimited `terminate` command to the child's stdin and EOFs it, then arms a `TAPE6_GRACE_TIMEOUT` deadline after which the child is force-killed (`worker.kill()`, SIGTERM). The base `EventServer` calls it with `reason` `'done'` (the worker finished — read its `end`), `'failOnce'` (a sibling tripped failOnce / bail), or `'timeout'` (the per-worker deadline). Idempotent per task.
 
 ### Stream pipeline
 
-Each spawned process has two stream pipelines:
+Each spawned process has two data-plane stream pipelines (worker → reporter) plus a stdin control plane (reporter → worker, carrying `terminate`):
 
 **stdout pipeline:**
 ```
@@ -202,15 +206,16 @@ process.stderr → TextDecoderStream → lines → wrap-lines → report
 
 ### Process lifecycle
 
-1. Process is spawned with environment variables: `TAPE6_FLAGS`, `TAPE6_TEST`, `TAPE6_TEST_FILE_NAME`, `TAPE6_JSONL=Y`, `TAPE6_JSONL_PREFIX`.
-2. The test file runs and outputs JSONL-prefixed lines to stdout.
-3. After the process exits, `TestWorker` checks exit code and signal.
-4. Non-zero exit codes are reported as errors with a `{type: 'terminated'}` event.
-5. The task is closed and the next queued test file starts.
+1. Process is spawned with environment variables: `TAPE6_FLAGS`, `TAPE6_TEST`, `TAPE6_TEST_FILE_NAME`, `TAPE6_JSONL=Y`, `TAPE6_JSONL_PREFIX`, `TAPE6_CONTROL=Y`, `TAPE6_GRACE_TIMEOUT`.
+2. The test file runs and outputs JSONL-prefixed lines to stdout. Marked by `TAPE6_CONTROL`, the tape-six runtime opens a stdin control channel and stays alive after emitting its top-level `end` — it no longer self-exits.
+3. **Normal completion** is keyed off the parent *reading* that top-level `end` (not racing the child's exit). The parent then issues `terminate` (drain + EOF stdin); the child exits and the next queued file starts. Because the child exits only after `end` has been consumed, the Bun stdout-flush bug (a dropped tail on self-exit) cannot occur.
+4. **Abort** (`failOnce` / bail, or a `TAPE6_WORKER_TIMEOUT` deadline) issues `terminate` to every in-flight worker. Each drains its running test through `reporter.terminate()` — `t.signal` fires, `finally` / `afterEach` / `afterAll` run — then exits, emitting its `end` as usual.
+5. **Force-kill backstop.** A worker that does not exit within `TAPE6_GRACE_TIMEOUT` of a `terminate` (a test hung in a non-signal-aware `await`) is killed with `worker.kill()` (SIGTERM).
+6. A premature exit — the child closes stdout without a top-level `end` (crash, bad import, force-kill) — is reported as an error with a `{type: 'terminated'}` event, including the exit code / signal, unless a failure was already reported.
 
 ## Dependencies
 
-- **`tape-six`** — the core test library. Imports: `utils/config.js` (`getOptions`, `initFiles`, `initReporter`, `showInfo`, `printFlagOptions`), `test.js` (`getReporter`, `setReporter`), `utils/timer.js`, `State.js`, `utils/EventServer.js`, `utils/makeDeferred.js`.
+- **`tape-six`** — the core test library. Imports: `utils/config.js` (`getOptions`, `initFiles`, `initReporter`, `showInfo`, `printFlagOptions`), `test.js` (`getReporter`, `setReporter`), `utils/timer.js`, `State.js`, `utils/EventServer.js`, `utils/makeDeferred.js`. The worker control channel additionally depends on tape-six's child-side listener (`src/utils/control-channel.js`, opened via `TAPE6_CONTROL`) and the `getGraceTimeout` / `getWorkerTimeout` config it injects through `getOptions`, so it requires a tape-six version that ships them.
 - **`dollar-shell`** — cross-runtime process spawning. Imports: `spawn`, `currentExecPath`, `runFileArgs`.
 
 ## Writing tests

package/llms.txt

@@ -42,6 +42,7 @@ test('my test', async t => {
 - **Cross-runtime** — works with Node, Deno, and Bun using the same test files.
 - **TypeScript without transpilation** — runs `.ts` test files natively on modern Node, Deno, and Bun.
 - **Drop-in replacement** — uses the same configuration and test format as `tape6` (worker-thread runner).
+- **Early termination** — a control channel lets `failOnce` (flag `O`) stop in-flight workers and supports a per-worker time limit (`TAPE6_WORKER_TIMEOUT`); both drain cleanly (cleanup hooks run) with a force-kill backstop after `TAPE6_GRACE_TIMEOUT`.
 
 ## CLI: tape6-proc
 
@@ -102,6 +103,8 @@ Environment-specific subsections: `node`, `deno`, `bun`.
 - `TAPE6_TAP` — force TAP reporter.
 - `TAPE6_JSONL` — force JSONL reporter.
 - `TAPE6_MIN` — force minimal reporter.
+- `TAPE6_GRACE_TIMEOUT` — ms a worker may drain (cleanup, flush) after a `terminate` before it is force-killed. Default 5000.
+- `TAPE6_WORKER_TIMEOUT` — per-worker wall-clock deadline in ms; on expiry the worker is terminated. Default 0 (off).
 - `TAPE6_TEST_FILE_NAME` — set by the runner: file name of the current test.
 
 ## Links

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six-proc",
-  "version": "1.2.8",
+  "version": "1.3.0",
   "description": "Process-isolated test runner for tape-six. Runs each test file in its own subprocess. Works with Node, Deno, and Bun. Supports TypeScript without transpilation.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "lint": "prettier --check .",
     "lint:fix": "prettier --write .",
+    "js-check": "tsc --project tsconfig.check.json",
     "test": "node ./bin/tape6-proc.js --flags FO",
     "test:bun": "bun run ./bin/tape6-proc.js --flags FO",
     "test:deno": "deno run -A ./bin/tape6-proc.js -r --allow-read -r --allow-env --flags FO"
@@ -56,8 +57,8 @@
     "llms-full.txt"
   ],
   "dependencies": {
-    "dollar-shell": "^1.1.13",
-    "tape-six": "^1.7.13"
+    "dollar-shell": "^1.1.14",
+    "tape-six": "^1.10.0"
   },
   "tape6": {
     "tests": [
@@ -65,6 +66,7 @@
     ]
   },
   "devDependencies": {
-    "chai": "^6.2.2"
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
   }
 }

package/src/TestWorker.js

@@ -15,6 +15,8 @@ import wrap from './streams/wrap-lines.js';
 
 const baseName = pathToFileURL(process.cwd() + sep);
 
+const encoder = new TextEncoder();
+
 export default class TestWorker extends EventServer {
   constructor(reporter, numberOfTasks, options) {
     super(reporter, numberOfTasks, options);
@@ -23,34 +25,43 @@ export default class TestWorker extends EventServer {
     this.prefix = crypto.randomUUID();
   }
   makeTask(fileName) {
+    const self = /** @type {*} */ (this);
     const testName = new URL(fileName, baseName),
-      id = String(++this.counter),
+      id = String(++self.counter),
       worker = spawn(
-        [currentExecPath(), ...runFileArgs, ...this.options.runFileArgs, fileURLToPath(testName)],
+        [currentExecPath(), ...runFileArgs, ...self.options.runFileArgs, fileURLToPath(testName)],
         {
-          stdin: 'ignore',
+          // stdin is the control channel: the parent writes a line-delimited
+          // `terminate` and ends the stream to drive the child's exit. See
+          // dev-docs/worker-control-channel.md (tape-six).
+          stdin: 'pipe',
           stdout: 'pipe',
           stderr: 'pipe',
           env: {
             ...process.env,
-            TAPE6_FLAGS: this.options.flags,
+            TAPE6_FLAGS: self.options.flags,
             TAPE6_TEST: id,
             TAPE6_TEST_FILE_NAME: fileName,
             TAPE6_JSONL: 'Y',
-            TAPE6_JSONL_PREFIX: this.prefix,
+            TAPE6_JSONL_PREFIX: self.prefix,
+            TAPE6_CONTROL: 'Y',
+            TAPE6_GRACE_TIMEOUT: String(self.graceTimeout),
             TAPE6_MIN: '',
             TAPE6_TAP: '',
             TAPE6_TTY: ''
           }
         }
       );
-    this.idToWorker[id] = worker;
-    const self = this;
+    // Per-task control-plane state. `endSeen` keys completion off *reading* the
+    // child's top-level `end` (not racing the child's own exit); `terminating`
+    // makes destroyTask idempotent; `graceTimer` is the force-kill backstop.
+    const task = {worker, endSeen: false, terminating: false, graceTimer: null};
+    self.idToWorker[id] = task;
     const stdoutDeferred = makeDeferred();
     worker.stdout
       .pipeThrough(new TextDecoderStream())
       .pipeThrough(lines())
-      .pipeThrough(parse(this.prefix))
+      .pipeThrough(parse(self.prefix))
       .pipeTo(
         new WritableStream({
           write(msg) {
@@ -62,6 +73,13 @@ export default class TestWorker extends EventServer {
                 throw error;
               }
             }
+            // Normal completion: the parent has consumed the top-level `end`.
+            // Tell the child to exit (drain + EOF its control channel) — this is
+            // the parent-driven exit that closes the Bun flush race.
+            if (msg && msg.type === 'end' && msg.test === 0) {
+              task.endSeen = true;
+              self.destroyTask(id, 'done');
+            }
           },
           close() {
             stdoutDeferred.resolve();
@@ -84,7 +102,13 @@ export default class TestWorker extends EventServer {
         })
       );
     Promise.allSettled([worker.exited, stdoutDeferred.promise, stderrDeferred.promise]).then(() => {
-      if (!self.reporter.state || !self.reporter.state.failed) {
+      if (task.graceTimer) {
+        clearTimeout(task.graceTimer);
+        task.graceTimer = null;
+      }
+      // A premature exit (no top-level `end` read) is a crash or a force-killed
+      // hung child — surface it, unless a failure was already reported.
+      if (!task.endSeen && (!self.reporter.state || !self.reporter.state.failed)) {
         const reason = [];
         if (worker.exitCode) {
           reason.push(`exit code: ${worker.exitCode}`);
@@ -103,15 +127,41 @@ export default class TestWorker extends EventServer {
           self.report(id, {type: 'terminated', test: 0, name: 'FILE: /' + fileName});
         }
       }
+      delete self.idToWorker[id];
       self.close(id);
     });
     return id;
   }
-  destroyTask(id) {
-    const worker = this.idToWorker[id];
-    if (worker) {
-      // worker.kill();
-      delete this.idToWorker[id];
+  // Deliver `terminate` to one child: write the line-delimited command, then
+  // EOF the control channel. The child drains a running test (reporter
+  // .terminate() — cleanup hooks run) and exits on its own; the graceTimeout
+  // backstop force-kills a test that won't drain. Idempotent per task.
+  destroyTask(id, reason = 'done') {
+    const task = this.idToWorker[id];
+    if (!task || task.terminating) return;
+    task.terminating = true;
+    this.#sendTerminate(task.worker, reason);
+    task.graceTimer = setTimeout(() => this.#kill(id), /** @type {*} */ (this).graceTimeout);
+  }
+  async #sendTerminate(worker, reason) {
+    const stdin = worker.stdin;
+    if (!stdin) return;
+    try {
+      const writer = stdin.getWriter();
+      await writer.write(encoder.encode(JSON.stringify({cmd: 'terminate', reason}) + '\n'));
+      await writer.close();
+    } catch (e) {
+      void e; // child already gone / pipe closed
+    }
+  }
+  #kill(id) {
+    const task = this.idToWorker[id];
+    if (!task) return;
+    task.graceTimer = null;
+    try {
+      task.worker.kill();
+    } catch (e) {
+      void e;
     }
   }
 }