tape-six 1.13.0 → 1.14.1

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.1 _Bug fixes. Updated dependencies._
+- 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._
@@ -453,4 +455,4 @@ 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._
 
-For more info consult full [release notes](https://github.com/uhop/tape-six/wiki/Release-notes).
+The full release notes are in the wiki: [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/index.js

@@ -225,60 +225,67 @@ const getTestFileName = ({isBrowser, isBun, isDeno, isNode}) => {
 let settings = null;
 
 const testRunner = async () => {
-  if (!settings) {
-    await selectTimer();
-    settings = await init();
-  }
+  // ref'd keep-alive — a bare run holds no other ref'd handle, so a test awaiting
+  // only an unref'd timer (AbortSignal.timeout on Node/Bun) would exit 0 mid-suite
+  const keepAlive = setInterval(() => {}, 2 ** 31 - 1);
+  try {
+    if (!settings) {
+      await selectTimer();
+      settings = await init();
+    }
 
-  const {isBrowser, isCli} = settings,
-    reporter = getReporter(),
-    testFileName = getTestFileName(settings);
+    const {isBrowser, isCli} = settings,
+      reporter = getReporter(),
+      testFileName = getTestFileName(settings);
 
-  reporter.report({
-    type: 'test',
-    test: 0,
-    name: testFileName ? 'FILE: /' + testFileName : ''
-  });
+    reporter.report({
+      type: 'test',
+      test: 0,
+      name: testFileName ? 'FILE: /' + testFileName : ''
+    });
 
-  reporter.state.beforeAll = getBeforeAll();
-  clearBeforeAll();
-  reporter.state.afterAll = getAfterAll();
-  clearAfterAll();
-  reporter.state.beforeEach = getBeforeEach();
-  clearBeforeEach();
-  reporter.state.afterEach = getAfterEach();
-  clearAfterEach();
-  reporter.state.isBeforeAllUsed = false;
+    reporter.state.beforeAll = getBeforeAll();
+    clearBeforeAll();
+    reporter.state.afterAll = getAfterAll();
+    clearAfterAll();
+    reporter.state.beforeEach = getBeforeEach();
+    clearBeforeEach();
+    reporter.state.afterEach = getAfterEach();
+    clearAfterEach();
+    reporter.state.isBeforeAllUsed = false;
 
-  const currentState = reporter.state;
+    const currentState = reporter.state;
 
-  for (;;) {
-    const tests = getTests();
-    if (!tests.length) break;
-    clearTests();
-    const canContinue = await runTests(tests);
-    if (!canContinue) break;
-    await new Promise(resolve => defer(resolve));
-  }
+    for (;;) {
+      const tests = getTests();
+      if (!tests.length) break;
+      clearTests();
+      const canContinue = await runTests(tests);
+      if (!canContinue) break;
+      await new Promise(resolve => defer(resolve));
+    }
 
-  await currentState?.runAfterAll();
+    await currentState?.runAfterAll();
 
-  const runHasFailed = reporter.state && reporter.state.failed > 0;
+    const runHasFailed = reporter.state && reporter.state.failed > 0;
 
-  reporter.report({
-    type: 'end',
-    test: 0,
-    name: testFileName ? 'FILE: /' + testFileName : '',
-    fail: runHasFailed
-  });
+    reporter.report({
+      type: 'end',
+      test: 0,
+      name: testFileName ? 'FILE: /' + testFileName : '',
+      fail: runHasFailed
+    });
 
-  if (!getConfiguredFlag() && runHasFailed) {
-    if (isCli) {
-      process.exitCode = 1;
+    if (!getConfiguredFlag() && runHasFailed) {
+      if (isCli) {
+        process.exitCode = 1;
+      }
     }
-  }
-  if (isBrowser && typeof __tape6_reportResults == 'function') {
-    __tape6_reportResults(runHasFailed ? 'failure' : 'success');
+    if (isBrowser && typeof __tape6_reportResults == 'function') {
+      __tape6_reportResults(runHasFailed ? 'failure' : 'success');
+    }
+  } finally {
+    clearInterval(keepAlive);
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "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",
@@ -103,8 +101,8 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "prettier": "^3.9.4",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.1",
+    "prettier": "^3.9.5",
+    "typescript": "^7.0.2"
   }
 }

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-!@#$%^&*';

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

@@ -21,13 +21,15 @@ export type TestEvent = {[key: string]: unknown};
  */
 export interface EventServerReporter {
   report(event: TestEvent, suppressStopTest?: boolean): void;
-  state?: {stopTest?: boolean; [key: string]: unknown} | null;
+  // no index signature: class-typed states (`State`) have none and must remain assignable
+  state?: {stopTest?: boolean} | null;
 }
 
 /**
  * Options consumed by the base class. Runners pass their own keys through
  * (`flags`, `importmap`, `serverUrl`, `browser`, ...) — hence the index
- * signature.
+ * signature; `any`, not `unknown`, so checked-JS siblings read pass-through
+ * keys without casts (2026-07-10 decision, applies to all sidecar bags).
  */
 export interface EventServerOptions {
   /**
@@ -40,7 +42,7 @@ export interface EventServerOptions {
    * `TAPE6_WORKER_TIMEOUT` via `getOptions()`.
    */
   workerTimeout?: number;
-  [key: string]: unknown;
+  [key: string]: any;
 }
 
 /**

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]: any;
+}
+
+/** 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, any>, name: string, value: string) => void;
+}
+
+/** A bare function is shorthand for `{fn, isValueRequired: true}`. */
+export type ArgOptions = Record<
+  string,
+  ArgOption | ((flags: Record<string, any>, 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, any>;
+};
+
+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]: any;
+}
+
+export interface RunnerOptions {
+  flags: RunnerFlags;
+  parallel: number;
+  files: string[];
+  /** Raw parsed option values, keyed by canonical option name. */
+  optionFlags: Record<string, any>;
+}
+
+/**
+ * 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';

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/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));