tape-six 1.12.0 → 1.14.0

package/README.md

@@ -117,7 +117,7 @@ tape-six/
 
 ## Docs
 
-The documentation can be found in the [wiki](https://github.com/uhop/tape-six/wiki).
+Full documentation is in the **[wiki](https://github.com/uhop/tape-six/wiki)** — browse the [index](https://github.com/uhop/tape-six/wiki/Home), or [search it](https://uhop.github.io/wiki-search/app/?wiki=uhop/tape-six) by name.
 See how it can be used in [tests/](https://github.com/uhop/tape-six/tree/master/tests).
 
 For AI assistants: see [llms.txt](https://github.com/uhop/tape-six/blob/master/llms.txt) and [llms-full.txt](https://github.com/uhop/tape-six/blob/master/llms-full.txt) for LLM-optimized documentation.
@@ -427,6 +427,8 @@ Test output can be controlled by flags. See [Supported flags](https://github.com
 
 The most recent releases:
 
+- 1.14.0 _Internal housekeeping. Removed the Deno 2.9.0 workaround shim._
+- 1.13.0 _TypeScript declarations for the `EventServer`._
 - 1.12.0 _`tape6-server` is now pluggable, embeddable server for hermetic integration tests, runtime plugin registration, and an opt-in HTTP/2 mode._
 - 1.11.0 _Invariant host hooks for the new zero-dependency `tape-six-invariant` companion package. Workaround for a Deno 2.9.0 `node_modules/.bin` symlink regression._
 - 1.10.1 _A workaround for a Bun's bug with streams._
@@ -452,4 +454,6 @@ The most recent releases:
 - 1.5.1 _Better support for stopping parallel tests, better support for "failed to load" errors._
 - 1.5.0 _Internal refactoring (moved state to reporters), added type identification of values in the DOM and TTY reporters, multiple minor fixes._
 
+The full release notes are in the wiki: [Release notes](https://github.com/uhop/tape-six/wiki/Release-notes).
+
 For more info consult full [release notes](https://github.com/uhop/tape-six/wiki/Release-notes).

package/bin/tape6-deno.js

@@ -1,9 +1,106 @@
 #!/usr/bin/env -S deno run --allow-all --ext=js
 
-// Deno 2.9.0 doesn't realpath a symlinked entry (denoland/deno#35551), so the
-// `.bin/tape6-deno` symlink would resolve the runner's ../src imports wrong.
-// Realpath this entry, then load the runner (static imports intact) beside it.
-import {fileURLToPath, pathToFileURL} from 'node:url';
+import process from 'node:process';
+import {fileURLToPath} from 'node:url';
 
-const here = pathToFileURL(Deno.realPathSync(fileURLToPath(import.meta.url)));
-await import(new URL('tape6-deno-main.js', here).href);
+import {
+  getOptions,
+  initFiles,
+  initReporter,
+  showInfo,
+  printVersion,
+  printHelp,
+  printFlagOptions
+} from '../src/utils/config.js';
+
+import {getReporter, setReporter} from '../src/test.js';
+import {selectTimer} from '../src/utils/timer.js';
+
+import TestWorker from '../src/runners/deno/TestWorker.js';
+
+const rootFolder = Deno.cwd();
+
+const showSelf = () => {
+  const self = new URL(import.meta.url);
+  if (self.protocol === 'file:') {
+    console.log(fileURLToPath(self));
+  } else {
+    console.log(self);
+  }
+  Deno.exit(0);
+};
+
+const showVersion = () => {
+  printVersion('tape6-deno');
+  Deno.exit(0);
+};
+
+const showHelp = () => {
+  printHelp('tape6-deno', 'Tape6 test runner for Deno', 'tape6-deno [options] [files...]', [
+    ['--flags, -f <flags>', 'Set reporter flags (env: TAPE6_FLAGS)'],
+    ['--par, -p <n>', 'Set parallelism level (env: TAPE6_PAR)'],
+    ['--info', 'Show configuration info and exit'],
+    ['--self', 'Print the path to this script and exit'],
+    ['--help, -h', 'Show this help message and exit'],
+    ['--version, -v', 'Show version and exit']
+  ]);
+  printFlagOptions();
+  Deno.exit(0);
+};
+
+const main = async () => {
+  const currentOptions = getOptions({
+    '--self': {fn: showSelf, isValueRequired: false},
+    '--info': {isValueRequired: false},
+    '--help': {aliases: ['-h'], fn: showHelp, isValueRequired: false},
+    '--version': {aliases: ['-v'], fn: showVersion, isValueRequired: false}
+  });
+
+  const [files] = await Promise.all([
+    initFiles(currentOptions.files, rootFolder),
+    initReporter(getReporter, setReporter, currentOptions.flags),
+    selectTimer()
+  ]);
+
+  addEventListener('error', event => {
+    console.log('UNHANDLED ERROR:', event.message);
+    event.preventDefault();
+  });
+
+  if (currentOptions.optionFlags['--info'] === '') {
+    showInfo(currentOptions, files);
+    await new Promise(r => process.stdout.write('', r));
+    process.exitCode = 0;
+    return;
+  }
+
+  if (!files.length) {
+    console.log('No files found.');
+    await new Promise(r => process.stdout.write('', r));
+    process.exitCode = 1;
+    return;
+  }
+
+  const reporter = getReporter(),
+    worker = new TestWorker(reporter, currentOptions.parallel, currentOptions.flags);
+
+  reporter.report({type: 'test', test: 0});
+
+  await new Promise(resolve => {
+    worker.done = () => resolve();
+    worker.execute(files);
+  });
+
+  const hasFailed = reporter.state && reporter.state.failed > 0;
+
+  reporter.report({
+    type: 'end',
+    test: 0,
+    fail: hasFailed
+  });
+
+  await new Promise(r => process.stdout.write('', r));
+  process.exitCode = hasFailed ? 1 : 0;
+};
+
+main().catch(error => console.error('ERROR:', error));

package/bin/tape6-server.js

@@ -67,7 +67,7 @@ let traceCalls = false,
 const normalizePort = val => {
   const port = parseInt(val);
   if (isNaN(port)) return val; // named pipe
-  if (port >= 0) return port; // port number
+  if (port >= 0) return port;
   return false;
 };
 

package/index.js

@@ -175,9 +175,7 @@ const init = async () => {
 
   if (isBrowser && typeof window.addEventListener == 'function') {
     // Control plane: the parent page posts `tape6-terminate` to drain a running
-    // test (failOnce / bail / worker deadline). The reporter arms stopTest +
-    // fires the abort signal so the test unwinds. There is no in-page
-    // force-kill — see dev-docs/worker-control-channel.md.
+    // test; there is no in-page force-kill — see dev-docs/worker-control-channel.md.
     window.addEventListener('message', event => {
       if (event.data?.type === 'tape6-terminate') getReporter()?.terminate();
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "TAP-inspired unit test library for Node, Deno, Bun, and browsers. ES modules, TypeScript, zero dependencies.",
   "type": "module",
   "main": "index.js",
@@ -68,8 +68,6 @@
     "url": "https://github.com/uhop/tape-six/issues"
   },
   "homepage": "https://github.com/uhop/tape-six#readme",
-  "llms": "https://raw.githubusercontent.com/uhop/tape-six/master/llms.txt",
-  "llmsFull": "https://raw.githubusercontent.com/uhop/tape-six/master/llms-full.txt",
   "files": [
     "index.*",
     "bin",

package/src/State.d.ts

@@ -0,0 +1,94 @@
+import type {Timer} from './utils/timer.js';
+
+/** Marker property stamped on tape-six-owned errors and serialized specials. */
+export const signature: string;
+
+/** Thrown to unwind a test when `failOnce` or a bail-out fires. Detect with `isStopTest`. */
+export class StopTest extends Error {
+  constructor(...args: ConstructorParameters<typeof Error>);
+}
+
+/**
+ * `true` for `StopTest` instances, including cross-realm copies revived from
+ * serialized events (matched structurally via the `signature` marker).
+ */
+export const isStopTest: (error: unknown) => boolean;
+
+/** Structural check for `node:assert`-style `AssertionError` objects (any realm). */
+export const isAssertionError: (error: unknown) => boolean;
+
+/** Extract the `at ...` frames of an error stack as trimmed strings. */
+export const getStackList: (error: {stack: string}) => string[];
+
+/** A test event routed through the reporter pipeline — a loose bag. See TESTING.md. */
+export type TestEvent = {[key: string]: unknown};
+
+export type Hook = () => void | Promise<void>;
+
+export interface StateOptions {
+  name?: string;
+  test?: number;
+  time?: number;
+  skip?: boolean;
+  todo?: boolean;
+  failOnce?: boolean;
+  timer?: Timer;
+}
+
+/**
+ * Per-test bookkeeping node: assert/skip/fail counters, inherited flags
+ * (`skip`, `todo`, `failOnce`), hook queues, and the abort controller backing
+ * `t.signal`. States chain via `parent`; iterating a state walks that chain
+ * from the innermost out.
+ */
+export class State {
+  constructor(parent: State | null | undefined, options: StateOptions);
+
+  parent: State | null | undefined;
+  name: string;
+  test: number;
+  skip: boolean | undefined;
+  todo: boolean | undefined;
+  failOnce: boolean | undefined;
+  /** The parent's assert count at creation — offsets this state's assert ids. */
+  offset: number;
+  asserts: number;
+  skipped: number;
+  failed: number;
+  /** Direct assertions in this state only — `t.plan()`'s comparison basis. */
+  localAsserts: number;
+  stopTest: boolean;
+  timer: Timer;
+  startTime: number;
+  time: number;
+  abortController: AbortController;
+
+  beforeAll: Hook[];
+  afterAll: Hook[];
+  beforeEach: Hook[];
+  afterEach: Hook[];
+  isBeforeAllUsed: boolean;
+
+  /** Aborted when the test ends — backs `t.signal`. */
+  get signal(): AbortSignal;
+  abort(): void;
+  dispose(): void;
+
+  /** Roll this state's counters up into the parent. */
+  updateParent(): void;
+
+  runBeforeAll(): Promise<void>;
+  runAfterAll(): Promise<void>;
+  runBeforeEach(): Promise<void>;
+  runAfterEach(): Promise<void>;
+
+  /** Normalize an event: counters, ids, timing, stack extraction, stop propagation. */
+  preprocess(event: TestEvent): TestEvent;
+  /** Throws `StopTest` when the (pre-processed) event demands a stop, unless suppressed. */
+  postprocess(event: TestEvent, suppressStopTest?: boolean): void;
+
+  /** Walk this state and its ancestors, innermost first. */
+  [Symbol.iterator](): IterableIterator<State>;
+}
+
+export default State;

package/src/State.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./State.d.ts"
+
 import {getTimer} from './utils/timer.js';
 
 export const signature = 'tape6-!@#$%^&*';
@@ -184,9 +186,8 @@ export class State {
       typeof event.diffTime !== 'number' && (event.diffTime = event.time - this.startTime);
     }
 
-    // Stack walking is only needed when the event will be reported as a failure.
-    // Reporters (TapReporter, TTYReporter) only read event.at / event.stackList
-    // inside `if (event.fail)` blocks, so for passing assertions this is wasted work.
+    // reporters read event.at / event.stackList only for failures — stack
+    // walking on passing assertions is wasted work
     if (isFailed) {
       if (
         event.type === 'assert' &&

package/src/Tester.js

@@ -460,10 +460,7 @@ export class Tester {
 }
 Tester.prototype.any = Tester.prototype._ = any;
 
-// Idempotent registration of a method on Tester.prototype. Same name + same
-// function → no-op; same name + different function → throws. Lets plugins
-// extend the tester (e.g., spawnBin, withTempDir, waitFor) without colliding
-// silently when two of them claim the same name.
+// plugin extension point — a same-name collision must fail loudly, not silently override
 export const registerTesterMethod = (name, fn) => {
   if (typeof name !== 'string' || !name)
     throw new TypeError('registerTesterMethod: name must be a non-empty string');

package/src/reporters/Reporter.js

@@ -15,9 +15,6 @@ export class Reporter {
     this.terminating = false;
   }
 
-  // Emit one record to stdout, mirroring console.log's arguments. On Bun,
-  // console.log to a subprocess-piped stdout is lossy / stalls under load, so route
-  // through process.stdout.write there; Node/Deno keep the proven console.log path.
   writeOut(...args) {
     if (isBun) {
       process.stdout.write(args.map(a => (typeof a == 'string' ? a : String(a))).join(' ') + '\n');
@@ -34,14 +31,9 @@ export class Reporter {
     this.state?.abort();
   }
 
-  // Control plane: a `terminate` command reached this worker (failOnce / bail
-  // drain, or a worker deadline). Arm stopTest and fire the abort signal across
-  // the live state chain so a running test unwinds — StopTest at the next
-  // assertion, t.signal rejects signal-aware awaits — and remember it so any
-  // test that starts afterwards stops at its first assertion too (closing the
-  // race where `terminate` lands while the worker is still starting up). The
-  // test's cleanup (finally / afterEach / afterAll) still runs. See
-  // dev-docs/worker-control-channel.md.
+  // `terminating` is remembered so a test that starts after the terminate stops
+  // too — closes the race where `terminate` lands mid-startup. Cleanup
+  // (finally / afterEach / afterAll) still runs. See dev-docs/worker-control-channel.md.
   terminate() {
     this.terminating = true;
     for (let state = this.state; state; state = state.parent) {
@@ -61,8 +53,7 @@ export class Reporter {
       timer: this.timer
     });
     ++this.depth;
-    // A terminate landed before this test started — stop it at its first
-    // assertion rather than letting it run to completion.
+    // a terminate landed before this test started
     if (this.terminating) {
       this.state.stopTest = true;
       this.state.abort();

package/src/runners/bun/TestWorker.js

@@ -74,13 +74,10 @@ export class TestWorker extends EventServer {
     const worker = this.idToWorker[id];
     if (!worker) return;
     if (reason === 'done') {
-      // The test already finished; just tear the worker down.
       this.#kill(id);
       return;
     }
-    // Cooperative drain (abort): ask the child to fire its abort signal and run
-    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
-    // the test ignores the signal and never settles.
+    // force-kill backstop: the test may ignore the abort signal and never settle
     if (this.graceTimers[id]) return; // already draining
     try {
       worker.postMessage({type: 'terminate', reason});

package/src/runners/bun/worker.js

@@ -38,9 +38,7 @@ let currentReporter = null,
 
 addEventListener('message', async event => {
   const msg = event.data;
-  // Control plane: drain on `terminate`. The reporter arms stopTest + fires the
-  // abort signal so a running test unwinds (cleanup runs); a terminate that
-  // lands before the reporter exists is remembered and applied at startup.
+  // a terminate can land before the reporter exists — remember it, apply at startup
   if (msg?.type === 'terminate') {
     pendingTerminate = true;
     currentReporter?.terminate();

package/src/runners/deno/TestWorker.js

@@ -57,13 +57,10 @@ export class TestWorker extends EventServer {
     const worker = this.idToWorker[id];
     if (!worker) return;
     if (reason === 'done') {
-      // The test already finished; just tear the worker down.
       this.#kill(id);
       return;
     }
-    // Cooperative drain (abort): ask the child to fire its abort signal and run
-    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
-    // the test ignores the signal and never settles.
+    // force-kill backstop: the test may ignore the abort signal and never settle
     if (this.graceTimers[id]) return; // already draining
     try {
       worker.postMessage({type: 'terminate', reason});

package/src/runners/deno/worker.js

@@ -38,9 +38,7 @@ let currentReporter = null,
 
 addEventListener('message', async event => {
   const msg = event.data;
-  // Control plane: drain on `terminate`. The reporter arms stopTest + fires the
-  // abort signal so a running test unwinds (cleanup runs); a terminate that
-  // lands before the reporter exists is remembered and applied at startup.
+  // a terminate can land before the reporter exists — remember it, apply at startup
   if (msg?.type === 'terminate') {
     pendingTerminate = true;
     currentReporter?.terminate();

package/src/runners/node/TestWorker.js

@@ -76,14 +76,11 @@ export class TestWorker extends EventServer {
     const worker = this.idToWorker[id];
     if (!worker) return;
     if (reason === 'done') {
-      // The test already finished; worker_threads have no flush race, so just
-      // tear the worker down.
+      // worker_threads have no flush race
       this.#kill(id);
       return;
     }
-    // Cooperative drain (abort): ask the child to fire its abort signal and run
-    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
-    // the test ignores the signal and never settles.
+    // force-kill backstop: the test may ignore the abort signal and never settle
     if (this.graceTimers[id]) return; // already draining
     try {
       worker.postMessage({type: 'terminate', reason});

package/src/runners/node/worker.js

@@ -40,9 +40,7 @@ let currentReporter = null,
   pendingTerminate = false;
 
 parentPort.on('message', async msg => {
-  // Control plane: drain on `terminate`. The reporter arms stopTest + fires the
-  // abort signal so a running test unwinds (cleanup runs); a terminate that
-  // lands before the reporter exists is remembered and applied at startup.
+  // a terminate can land before the reporter exists — remember it, apply at startup
   if (msg?.type === 'terminate') {
     pendingTerminate = true;
     currentReporter?.terminate();

package/src/runners/seq/TestWorker.js

@@ -62,10 +62,8 @@ export class TestWorker extends EventServer {
   }
   destroyTask(id, reason = 'done') {
     if (reason !== 'done') {
-      // Abort trigger (failOnce / bail / worker deadline). The test runs in this
-      // same process, so "terminate" is just reporter.terminate(): arm stopTest
-      // + fire the abort signal. The run unwinds and closes itself with 'done',
-      // where the reset below happens.
+      // same process, no force-kill — the aborted run closes itself with 'done',
+      // where the reset below happens
       this.reporter.terminate();
       return;
     }

package/src/test.d.ts

@@ -0,0 +1,82 @@
+import type {Test, Tester, TestOptions} from '../index.js';
+import type {State, TestEvent} from './State.js';
+import type {Deferred} from './utils/makeDeferred.js';
+
+/**
+ * The output-reporter surface `runTests` relies on: an event sink plus the
+ * root `State` carrying suite-level hooks and the stop flag. Every shipped
+ * reporter satisfies it.
+ */
+export interface OutputReporter {
+  report(event: TestEvent): void;
+  state: State;
+  [key: string]: unknown;
+}
+
+/** `true` once a runner claimed this process (test files skip self-running then). */
+export const getConfiguredFlag: () => boolean;
+export const setConfiguredFlag: (value: unknown) => boolean;
+
+/** Resolves with the runner module once `setTestRunner` announces it. */
+export const testRunner: Promise<unknown>;
+export const setTestRunner: (runner: unknown) => void;
+
+/**
+ * Ask to be called (once, deferred) when the first top-level test registers —
+ * how runners learn a test file has content. Fires immediately if tests are
+ * already queued.
+ */
+export const registerNotifyCallback: (callback: () => void) => void;
+export const unregisterNotifyCallback: (callback: () => void) => boolean;
+
+/** The active tester stack, innermost last. */
+export const getTesters: () => Tester[];
+
+/** The innermost currently-running tester, or `null` outside any test. */
+export const getTester: () => Tester | null;
+
+/** A queued top-level test: normalized options + the deferred resolved when it finishes. */
+export interface QueuedTest {
+  options: TestOptions;
+  deferred?: Deferred<unknown>;
+}
+
+export const getTests: () => QueuedTest[];
+export const clearTests: () => void;
+
+export const getReporter: () => OutputReporter | null;
+export const setReporter: (newReporter: OutputReporter) => OutputReporter;
+
+export type Hook = () => void | Promise<void>;
+
+export const getBeforeAll: () => Hook[];
+export const clearBeforeAll: () => void;
+export const getAfterAll: () => Hook[];
+export const clearAfterAll: () => void;
+export const getBeforeEach: () => Hook[];
+export const clearBeforeEach: () => void;
+export const getAfterEach: () => Hook[];
+export const clearAfterEach: () => void;
+
+/**
+ * Run queued tests against the current reporter. Returns `false` when stopped
+ * early (`failOnce` / bail-out), `true` otherwise. Runner-facing — test files
+ * use `test()`.
+ */
+export const runTests: (tests: QueuedTest[]) => Promise<boolean>;
+
+/**
+ * Register a top-level test (delegates to the innermost tester when called
+ * inside a running test). Carries `skip` / `todo` / `asPromise` and the hook
+ * registrars as properties — see the `Test` interface.
+ */
+export const test: Test;
+
+export const beforeAll: (fn: Hook) => void;
+export const afterAll: (fn: Hook) => void;
+export const beforeEach: (fn: Hook) => void;
+export const afterEach: (fn: Hook) => void;
+
+export {beforeAll as before, afterAll as after};
+
+export default test;

package/src/test.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./test.d.ts"
+
 import {selectTimer} from './utils/timer.js';
 import {isAssertionError, isStopTest} from './State.js';
 import makeDeferred from './utils/makeDeferred.js';

package/src/utils/EventServer.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Teardown reason delivered to `destroyTask`:
+ * - `'done'` — the task finished; tear its worker down now.
+ * - `'failOnce'` — stop / bail-out: abort an in-flight task.
+ * - `'timeout'` — the per-worker deadline (`workerTimeout`) fired.
+ *
+ * Any reason but `'done'` means: drain cooperatively (let cleanup run),
+ * then force-kill after `graceTimeout` where the transport allows.
+ */
+export type DestroyReason = 'done' | 'failOnce' | 'timeout';
+
+/**
+ * A test event routed to the reporter — a loose bag (`type`, `test`,
+ * `name`, `marker`, `operator`, `fail`, `data`, ...). See TESTING.md.
+ */
+export type TestEvent = {[key: string]: unknown};
+
+/**
+ * The reporter surface `EventServer` needs. Structural — every tape-six
+ * reporter satisfies it.
+ */
+export interface EventServerReporter {
+  report(event: TestEvent, suppressStopTest?: boolean): void;
+  state?: {stopTest?: boolean; [key: string]: unknown} | null;
+}
+
+/**
+ * Options consumed by the base class. Runners pass their own keys through
+ * (`flags`, `importmap`, `serverUrl`, `browser`, ...) — hence the index
+ * signature.
+ */
+export interface EventServerOptions {
+  /**
+   * Cooperative-drain window in ms before a force-kill (default: 5000).
+   * CLI runners inject `TAPE6_GRACE_TIMEOUT` via `getOptions()`.
+   */
+  graceTimeout?: number;
+  /**
+   * Per-worker deadline in ms; unset or 0 disables it. CLI runners inject
+   * `TAPE6_WORKER_TIMEOUT` via `getOptions()`.
+   */
+  workerTimeout?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Base class for test-worker drivers (the parallel/seq runners and the
+ * `tape-six-proc` / `tape-six-puppeteer` / `tape-six-playwright` siblings).
+ *
+ * Two planes: DATA (worker → reporter — the `report()`/`close()`
+ * event-ordering machinery) and CONTROL (reporter/runner → worker — a
+ * single `terminate` delivered per transport by `destroyTask`). See
+ * dev-docs/worker-control-channel.md.
+ *
+ * Subclasses implement the two transport hooks: `makeTask` and
+ * `destroyTask`.
+ */
+export class EventServer {
+  constructor(reporter: EventServerReporter, numberOfTasks?: number, options?: EventServerOptions);
+
+  reporter: EventServerReporter;
+  numberOfTasks: number;
+  options: EventServerOptions;
+
+  /** Drain window in ms before a force-kill; see `EventServerOptions.graceTimeout`. */
+  graceTimeout: number;
+  /** Per-worker deadline in ms; 0 = off; see `EventServerOptions.workerTimeout`. */
+  workerTimeout: number;
+  /**
+   * Set on the first stop / bail-out signal; every in-flight task then gets
+   * `destroyTask(id, 'failOnce')`. Tasks that finish starting later must
+   * check it themselves (a just-created worker can miss the sweep).
+   */
+  stopRequested: boolean;
+
+  /** Completion hook: called once when the last task closes. Assigned by runners. */
+  done?: () => void;
+
+  // DATA-plane bookkeeping — not a consumer surface.
+  totalTasks: number;
+  fileQueue: string[];
+  passThroughId: string | null;
+  retained: Record<string, TestEvent[]>;
+  readyQueue: TestEvent[][];
+  liveTasks: Set<string>;
+  deadlineTimers: Record<string, ReturnType<typeof setTimeout>>;
+
+  /** DATA plane: forward one worker event, preserving per-task ordering. */
+  report(id: string, event: TestEvent): void;
+  /**
+   * DATA plane: a task's stream ended — release its retained events, start
+   * the next queued file, and call `destroyTask(id, 'done')`.
+   */
+  close(id: string): void;
+
+  /** Start a worker for `fileName` now if a slot is free, else queue it. */
+  createTask(fileName: string): void;
+  /** `createTask` every file. */
+  execute(files: string[]): void;
+
+  /**
+   * Transport hook: start a worker for `fileName` and return its task id.
+   * The base implementation is a no-op returning `undefined`.
+   */
+  makeTask(fileName: string): string | null | undefined;
+  /**
+   * Transport hook (CONTROL plane): deliver `terminate` to one worker.
+   * The base implementation is a no-op; see `DestroyReason` for the
+   * expected teardown semantics.
+   */
+  destroyTask(id: string, reason?: DestroyReason): void;
+}
+
+export default EventServer;

package/src/utils/EventServer.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./EventServer.d.ts"
+
 import defer from './defer.js';
 
 // Fallback used when no graceTimeout is supplied through options (e.g. the
@@ -5,15 +7,9 @@ import defer from './defer.js';
 // (TAPE6_GRACE_TIMEOUT) via getOptions(); see src/utils/config.js.
 const DEFAULT_GRACE_TIMEOUT = 5_000;
 
-// EventServer owns two planes. The DATA plane (worker -> reporter) is the
-// report()/close() event-ordering machinery. The CONTROL plane
-// (reporter/runner -> worker) is a single command, `terminate`, delivered per
-// transport by destroyTask(id, reason). Two triggers fire it:
-//   - normal completion: close() terminates the just-finished worker ('done');
-//   - stop / bail-out:   when reporter.state.stopTest is set (failOnce / bail),
-//                        every in-flight worker is terminated ('failOnce').
-// An optional per-worker wall-clock deadline (workerTimeout, Layer 2) fires the
-// same command on expiry ('timeout'). See dev-docs/worker-control-channel.md.
+// Two planes: DATA (worker -> reporter, the report()/close() event-ordering
+// machinery) and CONTROL (reporter/runner -> worker, a single `terminate`
+// delivered per transport by destroyTask). See dev-docs/worker-control-channel.md.
 export class EventServer {
   constructor(reporter, numberOfTasks = 1, options = {}) {
     this.reporter = reporter;
@@ -112,9 +108,7 @@ export class EventServer {
   execute(files) {
     files.forEach(fileName => this.createTask(fileName));
   }
-  // Spawn one worker and register it for control-plane tracking. Routes both
-  // the initial batch (createTask) and queue drains (close) so liveTasks and
-  // the optional deadline cover every task, not just the first numberOfTasks.
+  // createTask and close() both route here so liveTasks + the deadline cover every task
   #startTask(fileName) {
     const id = this.makeTask(fileName);
     if (id == null) return id;
@@ -134,9 +128,6 @@ export class EventServer {
       delete this.deadlineTimers[id];
     }
   }
-  // Terminate every in-flight worker (abort) on top of the existing "stop
-  // scheduling new files." Fires at most once per run; callers decide when a
-  // stop / bail-out signal has been observed.
   #requestStop() {
     if (this.stopRequested) return;
     this.stopRequested = true;

package/src/utils/config.d.ts

@@ -0,0 +1,139 @@
+import type {OutputReporter} from '../test.js';
+
+/** Print `<commandName> <version>` (version read from package.json). */
+export const printVersion: (commandName: string) => void;
+
+/** Print the standard `--help` header, usage line, and an aligned option table. */
+export const printHelp: (
+  commandName: string,
+  description: string,
+  usage: string,
+  options?: [flag: string, description: string][]
+) => void;
+
+/** Print the flag legend (uppercase = on, lowercase = off). */
+export const printFlagOptions: () => void;
+
+/**
+ * Expand wildcard patterns to files under `rootFolder`. A `!`-prefixed pattern
+ * excludes matches accumulated so far — order matters. Returns paths relative
+ * to `rootFolder`.
+ */
+export const resolvePatterns: (rootFolder: string, patterns: string[]) => Promise<string[]>;
+
+/** The `tape6` config bag: test-set patterns keyed by environment, plus the importmap. */
+export interface Tape6Config {
+  tests?: string | string[];
+  cli?: string | string[];
+  browser?: string | string[];
+  importmap?: {imports: Record<string, string>};
+  [key: string]: unknown;
+}
+
+/** Read `tape6.json`, else `package.json#tape6`, else the default patterns. */
+export const getConfig: (
+  rootFolder: string,
+  traceFn?: (msg: string) => void
+) => Promise<Tape6Config>;
+
+/** Resolve the file list for `type` (an environment-named test set + `cli` + `tests`). */
+export const resolveTests: (
+  rootFolder: string,
+  type: string,
+  traceFn?: (msg: string) => void
+) => Promise<string[]>;
+
+export type RuntimeName = 'node' | 'bun' | 'deno' | 'browser' | 'unknown';
+
+/** The detected runtime and its env-var accessor (returns `undefined` in browsers). */
+export const runtime: {name: RuntimeName; getEnvVar: (name: string) => string | undefined};
+
+export type ReporterType = 'jsonl' | 'min' | 'tap' | 'tty';
+
+export const reporterFileNames: Record<ReporterType, string>;
+
+/** Reporter selected by `TAPE6_JSONL` / `TAPE6_MIN` / `TAPE6_TAP`; `null` in browsers. */
+export const getReporterType: () => ReporterType | null;
+export const getReporterFileName: (type?: ReporterType | null) => string;
+
+export const DEFAULT_START_TIMEOUT: number;
+export const DEFAULT_GRACE_TIMEOUT: number;
+
+/** Per-worker startup budget (`TAPE6_WORKER_START_TIMEOUT`) in ms. */
+export const getTimeoutValue: () => number;
+/** Cooperative-drain window before force-kill (`TAPE6_GRACE_TIMEOUT`) in ms. */
+export const getGraceTimeout: () => number;
+/** Optional per-worker wall-clock budget (`TAPE6_WORKER_TIMEOUT`) in ms; 0 = off. */
+export const getWorkerTimeout: () => number;
+
+/** Single-letter flag → option name (`f` → `failureOnly`, ...). */
+export const flagNames: Record<string, string>;
+
+export interface ArgOption {
+  aliases?: string[];
+  initialValue?: string | null;
+  isValueRequired?: boolean;
+  /** Custom handler; mutate `flags` directly. */
+  fn?: (flags: Record<string, unknown>, name: string, value: string) => void;
+}
+
+/** A bare function is shorthand for `{fn, isValueRequired: true}`. */
+export type ArgOptions = Record<
+  string,
+  ArgOption | ((flags: Record<string, unknown>, name: string, value: string) => void)
+>;
+
+/** Parse CLI args into files + flag values. CLI-only: in a browser returns an empty array. */
+export const processArgs: (argOptions: ArgOptions) => {
+  files: string[];
+  flags: Record<string, unknown>;
+};
+
+export interface RunnerFlags {
+  /** The raw flag string, uppercase = on, lowercase = off. */
+  flags: string;
+  failureOnly?: boolean;
+  showTime?: boolean;
+  showBanner?: boolean;
+  showData?: boolean;
+  failOnce?: boolean;
+  showStack?: boolean;
+  showLog?: boolean;
+  showAssertNumber?: boolean;
+  monochrome?: boolean;
+  useJsonL?: boolean;
+  noConsoleCapture?: boolean;
+  hideStreams?: boolean;
+  /** Consumed by the parent (`EventServer`) only; children ignore them. */
+  graceTimeout?: number;
+  workerTimeout?: number;
+  [key: string]: unknown;
+}
+
+export interface RunnerOptions {
+  flags: RunnerFlags;
+  parallel: number;
+  files: string[];
+  /** Raw parsed option values, keyed by canonical option name. */
+  optionFlags: Record<string, unknown>;
+}
+
+/**
+ * Parse standard runner options (`--flags` / `-f`, `--par` / `-p`, plus
+ * `extraOptions`), fold in `TAPE6_*` env defaults, re-export `TAPE6_FLAGS`,
+ * and resolve `parallel` to the available hardware when unset.
+ */
+export const getOptions: (extraOptions?: ArgOptions) => RunnerOptions;
+
+/** Instantiate and install the environment-appropriate reporter if none is set. */
+export const initReporter: (
+  getReporter: () => OutputReporter | null,
+  setReporter: (reporter: OutputReporter) => void,
+  flags: RunnerFlags
+) => Promise<void>;
+
+/** Explicit `files` win; otherwise resolve the configured test sets for `type`. */
+export const initFiles: (files: string[], rootFolder: string, type?: string) => Promise<string[]>;
+
+/** Print the runtime / reporter / parallelism / flags / files banner. */
+export const showInfo: (options: RunnerOptions, files?: string[] | null) => void;

package/src/utils/config.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./config.d.ts"
+
 import {promises as fsp, readFileSync} from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -170,9 +172,6 @@ export const getReporterFileName = type => {
 export const DEFAULT_START_TIMEOUT = 5_000;
 export const DEFAULT_GRACE_TIMEOUT = 5_000;
 
-// Read a positive-millisecond env var, falling back to `fallback` when it is
-// unset, non-numeric, non-positive, or Infinity. Always returns `fallback` in
-// the browser, where these env vars don't exist.
 const readTimeoutEnv = (name, fallback) => {
   if (runtime.name === 'browser') return fallback;
   const value = runtime.getEnvVar(name);
@@ -192,8 +191,7 @@ export const getTimeoutValue = () =>
 // allows. See dev-docs/worker-control-channel.md.
 export const getGraceTimeout = () => readTimeoutEnv('TAPE6_GRACE_TIMEOUT', DEFAULT_GRACE_TIMEOUT);
 
-// Optional wall-clock budget per worker/file (Layer 2 termination). 0 disables
-// it — the default — so a worker deadline fires only when explicitly set.
+// Optional wall-clock budget per worker/file (Layer 2 termination); 0 (default) disables it.
 export const getWorkerTimeout = () => readTimeoutEnv('TAPE6_WORKER_TIMEOUT', 0);
 
 export const flagNames = Object.fromEntries(
@@ -322,8 +320,7 @@ export const getOptions = extraOptions => {
   }
   options.parallel = parallel;
 
-  // Control-channel budgets ride along in the options bag handed to the
-  // TestWorker (EventServer). Children ignore them; only the parent acts.
+  // children ignore these; only the parent (EventServer) acts on them
   options.flags.graceTimeout = getGraceTimeout();
   options.flags.workerTimeout = getWorkerTimeout();
 

package/src/utils/control-channel.js

@@ -99,9 +99,7 @@ export const listenControlChannel = async getReporter => {
   }
   if (buffer) handleLine(buffer);
 
-  // Control-channel EOF. If no explicit terminate arrived (parent died / pipe
-  // broke), soft-terminate so a still-running test drains. Then fall through:
-  // the loop empties and the runtime exits naturally, flushing stdout.
+  // EOF — soft-terminate per the header contract
   if (!terminated) getReporter()?.terminate();
   armWatchdog(graceTimeout, getExitCode);
 };

package/src/utils/controlFetch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Control-plane client for the tape6 test server's endpoints (`/--tests`,
+ * `/--patterns`, `/--importmap`). Owned by tape-six core: the endpoints and
+ * the cert-cache location (`node_modules/.cache/tape6/cert.pem`, written by
+ * `src/test-server/certs.js`) are core's contract — browser providers import
+ * this client instead of hand-mirroring it.
+ */
+
+/** `true` when a TLS request read a plaintext answer — an h1 server behind an `https:` URL. */
+export const isProtocolMismatch: (error: unknown) => boolean;
+
+/**
+ * The response surface the control client guarantees — the common subset of
+ * global `fetch`'s `Response` and the scoped-TLS path's shim.
+ */
+export interface ControlResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<any>;
+}
+
+/**
+ * Build a control fetch rooted at `rootFolder` (defaults to `process.cwd()`).
+ *
+ * Every request carries a 3s hard deadline (a dying listener can accept and
+ * never answer); timeouts surface as errors with `code: 'ETIMEDOUT'` and are
+ * never retried on a lower trust rung. `http:` URLs go through global `fetch`;
+ * `https:` goes through `node:https` so TLS trust stays scoped to control
+ * requests — never process-wide — walking the ladder: `TAPE6_CERT` pinned as
+ * CA (failures stay loud, no fallback), else the server's cached self-signed
+ * cert, else relaxed verification. The first successful rung is cached for
+ * the fetch's lifetime.
+ */
+export const createControlFetch: (rootFolder?: string) => (url: string) => Promise<ControlResponse>;

package/src/utils/controlFetch.js

@@ -0,0 +1,88 @@
+// @ts-self-types="./controlFetch.d.ts"
+
+import {readFile} from 'node:fs/promises';
+import https from 'node:https';
+import path from 'node:path';
+import process from 'node:process';
+
+// Control-plane client (/--tests, /--patterns, /--importmap). Global fetch can't
+// relax TLS per request, so https: goes through node:https with trust scoped to
+// these requests only — never process-wide. Ladder: TAPE6_CERT pinned as CA;
+// else the server's cached self-signed cert (tape6 cert-ladder location);
+// else relaxed verification.
+
+// hard deadline on every request: a dying listener can accept and never answer
+// (the 2026-07-04 chained-run hang)
+const TIMEOUT = 3000;
+
+// a TLS request read a plaintext HTTP answer — an h1 server behind an https: URL
+export const isProtocolMismatch = error =>
+  !!error && (error.code === 'EPROTO' || /wrong version number/i.test(error.message || ''));
+
+export const createControlFetch = (rootFolder = process.cwd()) => {
+  let tlsOptions = null;
+  const get = (url, options) =>
+    new Promise((resolve, reject) => {
+      const request = https.get(url, options, response => {
+        const chunks = [];
+        response.on('data', chunk => chunks.push(chunk));
+        response.on('error', error => {
+          clearTimeout(timer);
+          reject(error);
+        });
+        response.on('end', () => {
+          clearTimeout(timer);
+          const body = Buffer.concat(chunks);
+          resolve({
+            ok: response.statusCode >= 200 && response.statusCode < 300,
+            status: response.statusCode,
+            json: async () => JSON.parse(body.toString())
+          });
+        });
+      });
+      const timer = setTimeout(
+        () =>
+          request.destroy(
+            Object.assign(new Error(`control request timed out after ${TIMEOUT}ms: ${url}`), {
+              code: 'ETIMEDOUT'
+            })
+          ),
+        TIMEOUT
+      );
+      request.on('error', error => {
+        clearTimeout(timer);
+        reject(error);
+      });
+    });
+  return async url => {
+    if (!/^https:/i.test(url)) return fetch(url, {signal: AbortSignal.timeout(TIMEOUT)});
+    if (tlsOptions) return get(url, tlsOptions);
+    const certPath = process.env.TAPE6_CERT;
+    if (certPath) {
+      // explicit pin: failures stay loud, no fallback
+      const options = {ca: await readFile(path.resolve(rootFolder, certPath))};
+      const response = await get(url, options);
+      tlsOptions = options;
+      return response;
+    }
+    const cached = await readFile(
+      path.join(rootFolder, 'node_modules', '.cache', 'tape6', 'cert.pem')
+    ).catch(() => null);
+    if (cached) {
+      try {
+        const options = {ca: cached};
+        const response = await get(url, options);
+        tlsOptions = options;
+        return response;
+      } catch (error) {
+        // a relaxed retry after a timeout would just burn a second deadline
+        if (error.code === 'ETIMEDOUT') throw error;
+        // stale cache or an external server with its own cert — try relaxed
+      }
+    }
+    const options = {rejectUnauthorized: false};
+    const response = await get(url, options);
+    tlsOptions = options;
+    return response;
+  };
+};

package/src/utils/makeDeferred.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A promise with its `resolve` / `reject` exposed — `Promise.withResolvers()`
+ * where the platform provides it, a hand-rolled equivalent otherwise.
+ */
+export interface Deferred<T = unknown> {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+}
+
+export const makeDeferred: <T = unknown>() => Deferred<T>;
+
+export default makeDeferred;

package/src/utils/makeDeferred.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./makeDeferred.d.ts"
+
 class Deferred {
   constructor() {
     this.promise = new Promise((resolve, reject) => {

package/src/utils/timer.d.ts

@@ -0,0 +1,16 @@
+/** Minimal millisecond clock. `Date` satisfies it; so does a wrapped `performance`. */
+export interface Timer {
+  now(): number;
+}
+
+/** The current shared timer. Defaults to `Date` until `selectTimer()` upgrades it. */
+export const getTimer: () => Timer;
+
+/** Replace the shared timer; returns the new one. */
+export const setTimer: (newTimer: Timer) => Timer;
+
+/**
+ * Select the best clock available: `performance.now() + performance.timeOrigin`
+ * (native or via `node:perf_hooks`), falling back to `Date`.
+ */
+export const selectTimer: () => Promise<void>;

package/src/utils/timer.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./timer.d.ts"
+
 let timer = Date;
 
 export const getTimer = () => timer;

package/web-app/TestWorker.js

@@ -89,11 +89,9 @@ export default class TestWorker extends EventServer {
       this.#removeIframe(id);
       return;
     }
-    // Cooperative drain only — in-page JS can't force-kill a hung iframe script.
-    // postMessage `terminate` so a cooperative test unwinds and runs its cleanup
-    // hooks; if it doesn't exit within graceTimeout, remove the iframe as a
-    // best-effort backstop. A driver-backed run (puppeteer / playwright) can do
-    // a real kill from Node — not wired here. See dev-docs/worker-control-channel.md.
+    // in-page JS can't force-kill a hung iframe script — iframe removal after
+    // graceTimeout is a best-effort backstop; a real kill needs a driver
+    // (puppeteer / playwright). See dev-docs/worker-control-channel.md.
     if (this.graceTimers[id]) return;
     const iframe = document.getElementById('test-iframe-' + id);
     if (!iframe) return;

package/bin/tape6-deno-main.js

@@ -1,104 +0,0 @@
-import process from 'node:process';
-import {fileURLToPath} from 'node:url';
-
-import {
-  getOptions,
-  initFiles,
-  initReporter,
-  showInfo,
-  printVersion,
-  printHelp,
-  printFlagOptions
-} from '../src/utils/config.js';
-
-import {getReporter, setReporter} from '../src/test.js';
-import {selectTimer} from '../src/utils/timer.js';
-
-import TestWorker from '../src/runners/deno/TestWorker.js';
-
-const rootFolder = Deno.cwd();
-
-const showSelf = () => {
-  const self = new URL(import.meta.url);
-  if (self.protocol === 'file:') {
-    console.log(fileURLToPath(self));
-  } else {
-    console.log(self);
-  }
-  Deno.exit(0);
-};
-
-const showVersion = () => {
-  printVersion('tape6-deno');
-  Deno.exit(0);
-};
-
-const showHelp = () => {
-  printHelp('tape6-deno', 'Tape6 test runner for Deno', 'tape6-deno [options] [files...]', [
-    ['--flags, -f <flags>', 'Set reporter flags (env: TAPE6_FLAGS)'],
-    ['--par, -p <n>', 'Set parallelism level (env: TAPE6_PAR)'],
-    ['--info', 'Show configuration info and exit'],
-    ['--self', 'Print the path to this script and exit'],
-    ['--help, -h', 'Show this help message and exit'],
-    ['--version, -v', 'Show version and exit']
-  ]);
-  printFlagOptions();
-  Deno.exit(0);
-};
-
-const main = async () => {
-  const currentOptions = getOptions({
-    '--self': {fn: showSelf, isValueRequired: false},
-    '--info': {isValueRequired: false},
-    '--help': {aliases: ['-h'], fn: showHelp, isValueRequired: false},
-    '--version': {aliases: ['-v'], fn: showVersion, isValueRequired: false}
-  });
-
-  const [files] = await Promise.all([
-    initFiles(currentOptions.files, rootFolder),
-    initReporter(getReporter, setReporter, currentOptions.flags),
-    selectTimer()
-  ]);
-
-  addEventListener('error', event => {
-    console.log('UNHANDLED ERROR:', event.message);
-    event.preventDefault();
-  });
-
-  if (currentOptions.optionFlags['--info'] === '') {
-    showInfo(currentOptions, files);
-    await new Promise(r => process.stdout.write('', r));
-    process.exitCode = 0;
-    return;
-  }
-
-  if (!files.length) {
-    console.log('No files found.');
-    await new Promise(r => process.stdout.write('', r));
-    process.exitCode = 1;
-    return;
-  }
-
-  const reporter = getReporter(),
-    worker = new TestWorker(reporter, currentOptions.parallel, currentOptions.flags);
-
-  reporter.report({type: 'test', test: 0});
-
-  await new Promise(resolve => {
-    worker.done = () => resolve();
-    worker.execute(files);
-  });
-
-  const hasFailed = reporter.state && reporter.state.failed > 0;
-
-  reporter.report({
-    type: 'end',
-    test: 0,
-    fail: hasFailed
-  });
-
-  await new Promise(r => process.stdout.write('', r));
-  process.exitCode = hasFailed ? 1 : 0;
-};
-
-main().catch(error => console.error('ERROR:', error));