workkit-core 0.0.0-stage → 0.86.0

package/LICENSE.md

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 ITW Creative Works
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# workkit-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The test runner and test library of [workkit](https://github.com/itw-creative-works/workkit), as an npm package. It runs every suite in parallel worker processes, prints each suite's output whole and in order, and ends on one totals line.
+
+## Use it
+
+```sh
+npm i -D workkit-core
+```
+
+Then set the repo's test script to the package's bin:
+
+```json
+{ "scripts": { "test": "workkit test" } }
+```
+
+`npm test` runs every `test/**/*.test.js` suite; `npm test -- test/x.test.js` runs only that file.
+With the workkit plugin installed, `workkit test` and `workkit test test/x.test.js` in a terminal do the same: the global command hands its arguments to `npm test`, and inside `npm test` npm puts this package's bin first on PATH.
+The bin runs only `test`; any other verb exits 2 and names the global `workkit` command it belongs to.
+
+## The run
+
+- Every `test/**/*.test.js` file is a suite, each run in its own process, as many at once as the machine has cores less one; a repo with no `test/` folder is read from `tests/`.
+- A suite named in the repo's `test/lib/serial.js` (`module.exports = { SERIAL: ['x.test.js'] }`) runs alone, after the parallel wave.
+- `test/mods/*.test.ts` suites run after that through `claude plugin test`, skipped by name with no `claude` on PATH.
+- The run ends with `N passed, M failed (Ns, K suites)` and a `slowest:` line, then names every skipped suite and case, then every failure; any failure exits 1.
+- A suite written on `node:test` runs too, through Node's own `run()`, counted the same way.
+
+## The library
+
+`workkit-core/test` is ES, and `require()` loads it as well:
+
+```js
+const { test, assertEq, summary, selfRun } = require('workkit-core/test');
+
+const run = async () => {
+  await test('adds', () => assertEq(1 + 1, 2));
+  return summary();
+};
+module.exports = run;
+if (require.main === module) selfRun(run);
+```
+
+- The cases: `group`, `test`, `assert`, `assertEq`, `skip`, `testUnless`, `skipSuite`, `summary`, `selfRun`, `log` (lines printed under a failing case, and under every case with `TEST_LOG=1`), `stripAnsi`, `hasLaunchd`.
+- Scratch and worlds: `mkTmp(prefix)`, a temp folder removed at exit; `seeded(build)`, a folder built once per process and copied per case.
+- Processes on one deadline (`SPAWN_DEADLINE`): `run`, `start` (with `end()` climbing SIGINT, SIGTERM, SIGKILL), `endTree`, `until`, `elapsedUntil`, `alive`, `readPid`.
+- Suite discovery: `findSuites`, `findModSuites`, `POOL`.
+
+What a test must be worth and may cost, and the shape every runner keeps: [docs/tests.md](https://github.com/itw-creative-works/workkit/blob/main/docs/tests.md).
+
+## License
+
+[FSL-1.1-MIT](https://github.com/itw-creative-works/workkit/blob/main/LICENSE.md), the same as workkit.

package/bin/workkit.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// The package's `workkit` bin, the one npm puts first on PATH inside `npm test`:
+// `workkit test [paths]` runs the test runner over the current folder. Every
+// other verb belongs to the global `workkit` command, so it exits 2 naming it.
+
+import { main } from '../test/run.js';
+
+const [verb, ...args] = process.argv.slice(2);
+
+if (verb === 'test') {
+  main(args);
+} else {
+  // The global command's error shape (wk_error): `✖ <verb>: <message>`.
+  const named = verb === undefined ? 'workkit' : `workkit ${verb}`;
+  console.error(`\u2716 ${verb ?? 'workkit'}: workkit-core's bin runs only \`workkit test [paths]\`; \`${named}\` belongs to the global workkit command (the workkit plugin's workflow/workkit.sh)`);
+  process.exitCode = 2;
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "workkit-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.86.0",
+  "description": "The workkit test runner and its harness: `workkit test` runs a repo's suites in worker processes and prints one totals line.",
+  "private": false,
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itw-creative-works/workkit.git",
+    "directory": "packages/core"
+  },
+  "engines": {
+    "node": ">=22.22"
+  },
+  "files": [
+    "bin",
+    "test"
+  ],
+  "bin": {
+    "workkit": "bin/workkit.js"
+  },
+  "exports": {
+    "./test": "./test/index.js"
+  },
+  "scripts": {
+    "prepack": "node -e \"require('node:fs').copyFileSync('../../LICENSE.md','LICENSE.md')\""
+  }
+}

package/test/index.js

@@ -0,0 +1,4 @@
+// `workkit-core/test`: the test library's entry, every export of the harness and
+// the concern files it carries. A CJS suite `require()`s it, an ES one imports it.
+
+export * from './lib/harness.js';

package/test/lib/harness.js

@@ -0,0 +1,130 @@
+/* eslint-disable no-console */
+// Tiny zero-dependency test harness shared across the suites: `test()` prints
+// a mark per case and each suite reports via `summary()`. AGENTS.md § Tests.
+// It is the library's one entry: every concern file's exports ride on its own.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openCase, drain, CASE_INDENT } from './log.js';
+
+export * from './process.js';
+export * from './scratch.js';
+export * from './seed.js';
+export * from './suites.js';
+export * from './log.js';
+export * from './spawn.js';
+
+// The workflow state directory's name for the test layer. The engine and the
+// hooks hold their own copy, so change all three together.
+export const WORKKIT_DIR = '.workkit';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+const skips = [];
+
+// A stack line with its file:/// URL (an ESM frame) in path form, so it reads as a plain frame.
+const pathForm = (line) => line.replace(/file:\/\/\S+?(?=:\d+:\d+\)?$)/, (url) => fileURLToPath(url));
+
+// The first stack frame outside this library: the line in the suite that threw.
+// The stack opens with the message, so its lines are skipped before frames are read.
+const caseFrame = (err) => {
+  const stack = String(err?.stack ?? '');
+  const message = String(err?.message ?? '');
+  const at = stack.indexOf(message);
+  return (at === -1 ? stack : stack.slice(at + message.length)).split('\n')
+    .map((line) => pathForm(line.trim()))
+    .find((line) => {
+      const file = line.match(/^at (?:async )?(?:.* \()?(.+?):\d+:\d+\)?$/)?.[1];
+      return file !== undefined && path.isAbsolute(file) && !file.startsWith(`${import.meta.dirname}${path.sep}`);
+    });
+};
+
+export const group = (name) => {
+  console.log(`\n\x1b[1m[${name}]\x1b[0m`);
+};
+
+export const test = async (name, fn) => {
+  openCase();
+  try {
+    await fn();
+    passed++;
+    console.log(`  \x1b[32m✓\x1b[0m ${name}`);
+    const lines = drain();
+    if (process.env.TEST_LOG === '1') for (const line of lines) console.log(`${CASE_INDENT}${line}`);
+  } catch (err) {
+    failed++;
+    failures.push({ name, err });
+    console.log(`  \x1b[31m✗\x1b[0m ${name}`);
+    console.log(`${CASE_INDENT}\x1b[31m${err.message}\x1b[0m`);
+    for (const line of drain()) console.log(`${CASE_INDENT}${line}`);
+    const frame = caseFrame(err);
+    if (frame) console.log(`${CASE_INDENT}\x1b[2m${frame}\x1b[0m`);
+  }
+  // One event-loop turn per case: a killed runner's disconnect reaches the
+  // worker between cases, which an await on a sync case alone never gives it.
+  await new Promise((resolve) => setImmediate(resolve));
+};
+
+export const assert = (cond, msg) => {
+  if (!cond) {
+    throw new Error(msg || 'assertion failed');
+  }
+};
+
+export const assertEq = (actual, expected, msg) => {
+  if (actual !== expected) {
+    throw new Error(`${msg || 'assertEq failed'}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+};
+
+// One case this machine cannot answer, named rather than dropped: it counts as
+// neither pass nor failure. skipSuite() would drop the whole file, cases that
+// could run included.
+export const skip = (name, reason) => {
+  skips.push({ name, reason });
+  console.log(`  \x1b[33m⊘\x1b[0m ${name} \x1b[33m(skipped: ${reason})\x1b[0m`);
+};
+
+// `test` where the case is answerable, a named skip where it is not. Asking the
+// question inside the body instead scores a pass for a case that asserted nothing.
+//   const newsTest = testUnless(IS_WINDOWS, 'the gh shim is not startable here');
+export const testUnless = (skipIt, reason) => (skipIt ? (name) => skip(name, reason) : test);
+
+// A suite whose preconditions are absent skips itself instead of failing, so
+// `npm test` stays the one command everywhere and the requirement lives in the
+// suite it describes.
+export const skipSuite = (reason) => {
+  const err = new Error(reason);
+  err.suiteSkipped = true;
+  throw err;
+};
+
+// Mirrors the engine's `uname -s` question rather than probing PATH for
+// launchctl, so the two never disagree about which branch the code takes.
+export const hasLaunchd = () => process.platform === 'darwin';
+
+// Log output with the helpers' color codes removed, so lines compare exactly.
+export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+
+// Snapshot and reset this file's totals; the runner sums them across files.
+export const summary = () => {
+  const result = { passed, failed, failures: failures.slice(), skips: skips.slice() };
+  passed = 0;
+  failed = 0;
+  failures.length = 0;
+  skips.length = 0;
+  return result;
+};
+
+// Runs one suite file on its own; without it a whole-suite skip would surface
+// as an unhandled crash.
+export const selfRun = (runner) => {
+  runner()
+    .then(({ failed }) => process.exit(failed > 0 ? 1 : 0))
+    .catch((err) => {
+      if (!err.suiteSkipped) throw err;
+      console.log(`\x1b[33m⊘ skipped:\x1b[0m ${err.message}`);
+      process.exit(0);
+    });
+};

package/test/lib/log.js

@@ -0,0 +1,32 @@
+/* eslint-disable no-console */
+// A case's own log: lines a case writes as it runs, held in the one slot the
+// running case owns, which the harness drains as the case ends and prints under
+// a failure (and under a pass with TEST_LOG=1). A line written with no case
+// running prints at once, indented as a case's lines are.
+
+import util from 'node:util';
+
+// The indent of every line the harness prints under a case's mark.
+export const CASE_INDENT = '    ';
+
+// The running case's lines, null while no case runs.
+let current = null;
+
+/** Log one line: the parts joined by spaces, a non-string inspected as console.log shows it. */
+export const log = (...parts) => {
+  const line = parts.map((part) => (typeof part === 'string' ? part : util.inspect(part))).join(' ');
+  if (current) current.push(line);
+  else console.log(`${CASE_INDENT}${line}`);
+};
+
+/** Open the slot of a case starting to run. */
+export const openCase = () => {
+  current = [];
+};
+
+/** The running case's lines, in the order written; the slot is closed after. */
+export const drain = () => {
+  const lines = current ?? [];
+  current = null;
+  return lines;
+};

package/test/lib/node-test.js

@@ -0,0 +1,88 @@
+// The runner's second suite shape (test/run.js): a file written on
+// `node:test`, told apart by its text since requiring it runs its tests, and run
+// through Node's own `run()` into the result object a kit-harness suite sends.
+
+import { run } from 'node:test';
+
+// Met outside any quote: a `require('node:test')` call, or the specifier of an
+// `import ... from` or bare `import` naming it.
+const IMPORT_AT = /\brequire\(\s*(['"])node:test\1\s*\)|\b(?:from|import)\s*(['"])node:test\2/y;
+const COMMENT = /^(?:\/\/|\/\*|\*)/;
+// The line Node prints for an uncaught error, `Error: msg` or `Error [CODE]: msg`.
+const ERROR_LINE = /^\w*Error(?: \[[^\]]+\])?: (.+)$/;
+
+/**
+ * Whether a suite's source imports `node:test`. Comment lines, quoted strings
+ * and template literals (a fixture another suite writes) never count; only a
+ * template literal runs past its line, and a backtick inside a quote opens none.
+ * @param {string} text the suite file's source
+ * @returns {boolean}
+ */
+export const isNodeTestSuite = (text) => {
+  let quote = '';
+  for (const line of text.split('\n')) {
+    if (!quote && COMMENT.test(line.trim())) continue;
+    for (let i = 0; i < line.length; i++) {
+      const c = line[i];
+      if (c === '\\') {
+        i++;
+      } else if (quote) {
+        if (c === quote) quote = '';
+      } else if (c === '/' && line[i + 1] === '/') {
+        break;
+      } else if (c === "'" || c === '"' || c === '`') {
+        quote = c;
+      } else {
+        IMPORT_AT.lastIndex = i;
+        if (IMPORT_AT.test(line)) return true;
+      }
+    }
+    if (quote !== '`') quote = '';
+  }
+  return false;
+};
+
+/**
+ * Runs one `node:test` suite and resolves the kit harness's result object.
+ * Its stdout and stderr are written through as they arrive; a load failure is
+ * the whole-suite failure `load <rel>`.
+ * @param {string} suite the suite's absolute path
+ * @param {string} rel the suite's path relative to test/, its name in a failure
+ * @returns {Promise<{passed: number, failed: number, failures: object[], skips: object[]}>}
+ */
+export const runNodeTest = (suite, rel) => new Promise((resolve, reject) => {
+  const result = { passed: 0, failed: 0, failures: [], skips: [] };
+  const stderrLines = [];
+  const stream = run({ files: [suite], concurrency: 1 });
+  stream.on('data', ({ type, data }) => {
+    if (type === 'test:stdout') {
+      process.stdout.write(data.message);
+    } else if (type === 'test:stderr') {
+      process.stderr.write(data.message);
+      stderrLines.push(data.message.trimEnd());
+    } else if (type === 'test:fail' && data.name === suite) {
+      // A load failure's event says only `test failed`; the thrown error's
+      // message is in the child's stderr, the last line Node printed for it.
+      const thrown = stderrLines.map((line) => line.match(ERROR_LINE)).filter(Boolean).pop();
+      result.failed++;
+      result.failures.push({ name: `load ${rel}`, message: thrown ? thrown[1] : data.details.error.message, whole: true });
+    } else if (data.todo && (type === 'test:pass' || type === 'test:fail')) {
+      // A todo test may throw; Node never counts it as a failure. A todo
+      // describe counts nothing, a body that throws included.
+      if (data.details.type === 'test') result.skips.push({ name: data.name, reason: 'todo' });
+    } else if (type === 'test:pass' && data.skip) {
+      // A skipped describe emits nothing for its tests, so its own skip is
+      // their one trace.
+      result.skips.push({ name: data.name, reason: data.skip === true ? 'skipped' : data.skip });
+    } else if (type === 'test:pass' && data.details.type === 'test') {
+      result.passed++;
+    } else if (type === 'test:fail' && (data.details.type === 'test' || data.details.error.failureType !== 'subtestsFailed')) {
+      // A suite fails on its own only when its body or a hook threw; a failed
+      // test inside it is already counted.
+      result.failed++;
+      result.failures.push({ name: data.name, message: data.details.error.message });
+    }
+  });
+  stream.on('error', reject);
+  stream.on('end', () => resolve(result));
+});

package/test/lib/process.js

@@ -0,0 +1,58 @@
+/**
+ * Watching a process a suite started without waiting for it: whether a pid is
+ * alive, a bounded poll for a condition, a pid read from the file a script
+ * left, the one spawn deadline and the pipe grace.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * The cap every spawn a suite makes carries (`timeout:` on spawnSync, the
+ * `until` bound a case leaves unset): wide enough for a loaded pool, since a
+ * case asserts order and never a duration.
+ */
+export const SPAWN_DEADLINE = 60000;
+
+// How long a child's pipes stay open past its exit, for a grandchild still
+// holding them; the child's own output is already in the pipe by then.
+export const PIPE_GRACE_MS = 1000;
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+
+/** Whether <pid> names a live process this user may signal. */
+export const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+
+/**
+ * Poll <predicate> every 100 ms until it holds or <ms> pass; the caller's
+ * assert names what never appeared.
+ * @param {Function} predicate
+ * @param {number} [ms]
+ * @returns {Promise<boolean>} the predicate's last answer
+ */
+export const until = async (predicate, ms = SPAWN_DEADLINE) => {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    if (predicate()) return true;
+    await sleep(100);
+  }
+  return predicate();
+};
+
+/**
+ * Poll <predicate> every millisecond until it holds or <ms> pass, for a spawn
+ * a case must catch on sight: until's 100 ms step is too coarse.
+ * @param {Function} predicate
+ * @param {number} [ms]
+ * @returns {Promise<number>} the milliseconds it took, or Infinity if it never held
+ */
+export const elapsedUntil = async (predicate, ms = SPAWN_DEADLINE) => {
+  const begin = Date.now();
+  while (Date.now() - begin < ms) {
+    if (predicate()) return Date.now() - begin;
+    await new Promise((resolve) => { setTimeout(resolve, 1); });
+  }
+  return predicate() ? Date.now() - begin : Infinity;
+};
+
+/** The pid a script wrote to <file>, as a number. */
+export const readPid = (file) => Number(fs.readFileSync(file, 'utf8').trim());

package/test/lib/scratch.js

@@ -0,0 +1,25 @@
+// The one writer of a scratch folder: every suite and helper makes its
+// throwaway directories here, and one exit handler removes them all (forced, so
+// a folder a case already removed is harmless). The path is always resolved:
+// the temp dir is a symlink on macOS, and a child's output names the resolved
+// form.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const made = [];
+
+process.on('exit', () => {
+  for (const dir of made) {
+    // A folder a hard-ended child still holds never stops the removals after it.
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+  }
+});
+
+/** A fresh folder in the temp dir, named `<prefix>XXXXXX`, removed at exit. */
+export const mkTmp = (prefix) => {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+  made.push(dir);
+  return dir;
+};

package/test/lib/seed.js

@@ -0,0 +1,27 @@
+// A folder built once per process for each shape a caller asks for, on first
+// use, and copied whole into a case's own folder: a case that writes into its
+// copy writes alone, and no case is handed the seed. mkTmp removes every seed
+// when the process exits.
+
+import fs from 'node:fs';
+import { mkTmp } from './scratch.js';
+
+/**
+ * @param {function(string, *): void} build - fills the empty seed folder, given
+ *   it and the shape it is for
+ * @returns {function(string, *=): void} the copier: `(dir, shape)` copies that
+ *   shape's seed into `dir`, made if missing and merged into if not
+ */
+export const seeded = (build) => {
+  const seeds = new Map();
+  return (dir, shape = null) => {
+    const key = JSON.stringify(shape);
+    if (!seeds.has(key)) {
+      const seed = mkTmp('workkit-seed-');
+      build(seed, shape);
+      seeds.set(key, seed);
+    }
+    // A relative link in a seed copies as the link it is, the way cp -R copies it.
+    fs.cpSync(seeds.get(key), dir, { recursive: true, verbatimSymlinks: true });
+  };
+};

package/test/lib/spawn.js

@@ -0,0 +1,178 @@
+/**
+ * Process management for a suite: a child run to its end under the spawn
+ * deadline, a child started and watched (its streams, its exit, a watchdog at
+ * the deadline), and the end of the process group a child leads.
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import { inspect } from 'node:util';
+import { SPAWN_DEADLINE, PIPE_GRACE_MS, until } from './process.js';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+// The rungs `end()` climbs, INT first so the child can log its own end, then
+// TERM, then KILL, END_GRACE apart: the shell's `wk_end_run` ladder.
+const LADDER = ['SIGINT', 'SIGTERM', 'SIGKILL'];
+const END_GRACE = 1500;
+
+/**
+ * Send <signal> to <target> (a pid, or a group as -pid).
+ * @returns {'sent'|'gone'|'refused'} gone on ESRCH, refused on EPERM
+ */
+const trySignal = (target, signal) => {
+  try {
+    process.kill(target, signal);
+    return 'sent';
+  } catch (err) {
+    if (err.code === 'ESRCH') return 'gone';
+    if (err.code === 'EPERM') return 'refused';
+    throw err;
+  }
+};
+
+/**
+ * trySignal, with a refusal thrown as `<who>: signal refused for pid <pid> (EPERM)`,
+ * so a process not ours is never read as alive and waited on.
+ * @returns {'sent'|'gone'}
+ */
+const send = (who, target, pid, signal) => {
+  const outcome = trySignal(target, signal);
+  if (outcome === 'refused') throw new Error(`${who}: signal refused for pid ${pid} (EPERM)`);
+  return outcome;
+};
+
+// The group <pid> leads, else <pid> alone. kill(-1) is every process this user
+// may signal, not a group, so pid 1 is signalled alone. A refused group falls
+// through too: on macOS a leader that exited unreaped refuses its group, so only
+// a refusal of the pid itself throws.
+const signalTree = (who, pid, signal) => {
+  if (pid === 1 || trySignal(-pid, signal) !== 'sent') send(who, pid, pid, signal);
+};
+
+/**
+ * End the tree a raw <pid> heads: the group it leads, else the pid; on Windows
+ * `taskkill /T /F` ends its whole tree. A pid that is not a positive integer
+ * throws, since 0 or a negative one signals the caller's own group or another;
+ * a refused signal throws `endTree: signal refused for pid <N> (EPERM)`.
+ * @param {number} pid
+ * @param {string} [signal]
+ */
+export const endTree = (pid, signal = 'SIGTERM') => {
+  if (!Number.isInteger(pid) || pid <= 0) throw new Error(`endTree: pid must be a positive integer, got ${inspect(pid)}`);
+  if (IS_WINDOWS) {
+    spawnSync('taskkill', ['/T', '/F', '/PID', String(pid)], { stdio: 'ignore', timeout: SPAWN_DEADLINE });
+    return;
+  }
+  signalTree('endTree', pid, signal);
+};
+
+/**
+ * Run <cmd> to its end under <deadline>, every stream piped; the deadline KILLs,
+ * so a child that traps TERM cannot outlast it.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{cwd?: string, env?: object, input?: string, deadline?: number}} [opts]
+ * @returns {{status: ?number, signal: ?string, stdout: string, stderr: string, output: string, timedOut: boolean}}
+ */
+export const run = (cmd, args, { cwd, env, input, deadline = SPAWN_DEADLINE } = {}) => {
+  const result = spawnSync(cmd, args, {
+    cwd, env, input, timeout: deadline, killSignal: 'SIGKILL', encoding: 'utf8', stdio: 'pipe',
+  });
+  const timedOut = result.error?.code === 'ETIMEDOUT';
+  if (result.error && !timedOut) throw result.error;
+  // spawnSync hands the streams back apart, so the order kept is stdout's then stderr's.
+  return {
+    status: result.status,
+    signal: result.signal,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    output: result.stdout + result.stderr,
+    timedOut,
+  };
+};
+
+/**
+ * Start <cmd> without waiting, stdout and stderr piped. `done` resolves once the child has exited and its streams
+ * closed, PIPE_GRACE_MS after the exit at most. A watchdog at <deadline> marks `timedOut` and calls `end()`, whose
+ * rejection rejects `done`. `end(signal)` climbs the ladder from that rung while the target lives: a detached child's
+ * group, else the child alone; on Windows one `taskkill` tree end, which reaches no grandchild once a detached leader
+ * has exited. A signal off the ladder rejects; a child that never spawned ends at once, `done` rejecting with the error.
+ * A refused rung rejects `end: signal refused for pid <N> (EPERM)`; alive END_GRACE after SIGKILL, `end: pid <N> survived SIGKILL`.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{cwd?: string, env?: object, deadline?: number, detached?: boolean}} [opts]
+ * @returns {{child: object, pid: number, output: Function, stdout: Function, stderr: Function, done: Promise, end: Function}}
+ */
+export const start = (cmd, args, { cwd, env, deadline = SPAWN_DEADLINE, detached = false } = {}) => {
+  const child = spawn(cmd, args, { cwd, env, detached, stdio: ['ignore', 'pipe', 'pipe'] });
+  let out = '';
+  let err = '';
+  let all = '';
+  child.stdout.setEncoding('utf8');
+  child.stderr.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => { out += chunk; all += chunk; });
+  child.stderr.on('data', (chunk) => { err += chunk; all += chunk; });
+
+  let timedOut = false;
+  let exit = {};
+  const gone = () => child.exitCode !== null || child.signalCode !== null;
+  const closePipes = () => {
+    child.stdout.destroy();
+    child.stderr.destroy();
+  };
+  const exited = new Promise((resolve) => {
+    child.once('exit', (status, signal) => {
+      exit = { status, signal };
+      setTimeout(closePipes, PIPE_GRACE_MS).unref();
+      resolve();
+    });
+  });
+  const { promise: done, resolve: settleDone, reject: failDone } = Promise.withResolvers();
+  child.once('error', failDone);
+  child.once('close', () => settleDone({ ...exit, timedOut }));
+  // `done` still rejects for whoever awaits it; a caller that only awaits
+  // `end()` must not die of the unhandled rejection.
+  done.catch(() => {});
+
+  // A detached group outlives its leader, so its life is the group's, not the child's.
+  // Windows has no process group: its one end is taskkill's tree end.
+  const group = detached && !IS_WINDOWS;
+  // A group whose members exited but are not yet reaped answers EPERM on macOS,
+  // so the zero probe reads it as gone, as `_wk_group_gone` does; a real rung's refusal throws.
+  const lives = () => (group ? trySignal(-child.pid, 0) === 'sent' : !gone());
+  // Wait until the target is gone or END_GRACE has passed, polled as the shell's
+  // `_wk_group_gone` does, since a group has no exit event.
+  const settle = () => until(() => !lives(), END_GRACE);
+
+  const end = async (signal = 'SIGINT') => {
+    if (!LADDER.includes(signal)) throw new Error(`end: signal must be one of ${LADDER.join(', ')}, got ${inspect(signal)}`);
+    clearTimeout(watchdog);
+    if (child.pid === undefined) return;
+    if (IS_WINDOWS) {
+      if (lives()) endTree(child.pid);
+    } else {
+      for (const rung of LADDER.slice(LADDER.indexOf(signal))) {
+        if (!lives()) break;
+        if (group) signalTree('end', child.pid, rung);
+        else send('end', child.pid, child.pid, rung);
+        await settle();
+      }
+      if (lives()) throw new Error(`end: pid ${child.pid} survived SIGKILL`);
+    }
+    await exited;
+    // The exit's own grace closes the streams, so output written while ending is read.
+    await done;
+  };
+
+  const watchdog = setTimeout(() => {
+    if (gone()) return;
+    timedOut = true;
+    // No caller awaits the watchdog's end, so its rejection fails `done` instead.
+    end().catch(failDone);
+  }, deadline);
+  watchdog.unref();
+
+  return {
+    child, pid: child.pid, output: () => all, stdout: () => out, stderr: () => err, done, end,
+  };
+};

package/test/lib/suites.js

@@ -0,0 +1,33 @@
+// Suite discovery for the kit's runner (test/run.js) and a repo's
+// runner suite (test/runner.test.js), so which files count as a suite has one home:
+// the Node suites, and the mod half's `test/mods/*.test.ts`.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// How many suites the runner runs at once: a core left for everything else.
+export const POOL = Math.max(1, os.availableParallelism() - 1);
+
+export const findSuites = (dir) => {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'lib') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...findSuites(full));
+    } else if (entry.name.endsWith('.test.js')) {
+      out.push(full);
+    }
+  }
+  return out;
+};
+
+// The mod half's wiring suites: every `*.test.ts` and `*.test.tsx` in the
+// test/mods/ folder, which `claude plugin test` runs; none when there is no folder.
+export const findModSuites = (dir) => {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /\.test\.tsx?$/.test(entry.name))
+    .map((entry) => path.join(dir, entry.name));
+};

package/test/run.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// The kit's test runner, over the repo at the cwd: every
+// `test/**/*.test.js` in worker processes, a parallel wave then the serial tail
+// the repo's `test/lib/serial.js` names, then the mod half (`claude plugin test`
+// over `test/mods/*.test.ts`), totalled; non-zero on any failure. Suite paths
+// after `--` narrow the run. A repo reaches it through `workkit test`, the
+// package's bin. A repo with no `test/` is read from `tests/`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { stripVTControlCharacters } from 'node:util';
+import { fork, spawnSync } from 'node:child_process';
+import { findSuites, findModSuites, POOL } from './lib/suites.js';
+import { isNodeTestSuite, runNodeTest } from './lib/node-test.js';
+import { PIPE_GRACE_MS } from './lib/process.js';
+
+// Suites and a repo's serial list are CommonJS, loaded by absolute path.
+const require = createRequire(import.meta.url);
+
+const TAIL_LINES = 3;
+const SLOWEST = 5;
+
+// The repo's suite folder: `test/`, Node's convention; `tests/` only when the
+// repo has that folder and no `test/`.
+const suiteDir = (root) => {
+  const isDir = (dir) => fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory() === true;
+  const dir = path.join(root, 'test');
+  const legacy = path.join(root, 'tests');
+  return !isDir(dir) && isDir(legacy) ? legacy : dir;
+};
+
+// The repo the run covers, the cwd, and the suite paths it was handed: `--`
+// dropped, every other argument a suite path.
+const parseArgs = (argv) => {
+  const root = process.cwd();
+  const testDir = suiteDir(root);
+  return { root, testDir, modDir: path.join(testDir, 'mods'), paths: argv.filter((arg) => arg !== '--') };
+};
+
+// The repo's serial tail, relative to the suite folder; none without a serial.js.
+const serialOf = (testDir) => {
+  const file = path.join(testDir, 'lib', 'serial.js');
+  return fs.existsSync(file) ? require(file).SERIAL : [];
+};
+
+// The named suites, or every suite when none is named; a name that is no
+// suite ends the run before anything starts. A named `.test.ts` picks the mod
+// half, which `claude plugin test` runs whole, since it takes a folder. A
+// serial entry that is no suite ends the run the same way.
+const pickSuites = ({ root, testDir, modDir, paths: args }, serialRels) => {
+  const all = fs.existsSync(testDir) ? findSuites(testDir) : [];
+  const mods = findModSuites(modDir);
+  for (const rel of serialRels) {
+    if (!all.includes(path.join(testDir, rel))) {
+      console.error(`No suite matches ${rel} (${path.basename(testDir)}/lib/serial.js)`);
+      process.exit(1);
+    }
+  }
+  if (args.length === 0) return { suites: all.sort(), withMods: mods.length > 0 };
+  const picked = new Set();
+  let withMods = false;
+  for (const arg of args) {
+    const full = path.resolve(root, arg);
+    if (mods.includes(full)) {
+      withMods = true;
+      continue;
+    }
+    if (!all.includes(full)) {
+      console.error(`No suite matches ${arg} under ${path.basename(testDir)}/`);
+      process.exit(1);
+    }
+    picked.add(full);
+  }
+  return { suites: [...picked].sort(), withMods };
+};
+
+// The mod half: the plugin's wiring suites, run by the engine itself on the repo
+// root (`claude plugin test` takes a plugin folder). No claude binary is a skip.
+const runModHalf = (root) => {
+  const res = spawnSync('claude', ['plugin', 'test', root], { cwd: root, encoding: 'utf8' });
+  if (res.error) {
+    return { skip: res.error.code === 'ENOENT' ? 'no claude binary on PATH' : `claude did not start: ${res.error.message}` };
+  }
+  const out = `${res.stdout || ''}${res.stderr || ''}`;
+  process.stdout.write(out);
+  const count = (word) => Number((out.match(new RegExp(`^\\s*(\\d+) ${word}$`, 'm')) || [])[1] || 0);
+  const failures = [...out.matchAll(/^\(fail\) (.+?)(?: \[[\d.]+ms\])?$/gm)]
+    .map((m) => ({ name: m[1], message: 'failed under claude plugin test' }));
+  let failed = count('fail');
+  if (res.status !== 0 && failed === 0) {
+    failed = 1;
+    failures.push({ name: 'claude plugin test', message: `exited ${res.status}` });
+  }
+  return { passed: count('pass'), failed, failures };
+};
+
+// Worker mode: runs one suite and sends its result as ONE message, then exits 0
+// once its output is flushed. A whole-suite failure (no load, no runner, a
+// throw) is a `whole` failure, named as the runner always named it. A
+// `node:test` suite is picked before any require, which would run its tests.
+const runOne = async (suite, testDir) => {
+  const rel = path.relative(testDir, suite);
+  const result = { passed: 0, failed: 0, failures: [], skips: [], skipped: null };
+  const send = () => process.send(result, () => {
+    process.stdout.write('', () => process.stderr.write('', () => process.exit(0)));
+  });
+  if (isNodeTestSuite(fs.readFileSync(suite, 'utf8'))) {
+    Object.assign(result, await runNodeTest(suite, rel));
+    send();
+    return;
+  }
+  const wholeFailure = (name, message) => {
+    result.failed = 1;
+    result.failures = [{ name, message, whole: true }];
+  };
+  let mod;
+  let loaded = false;
+  try {
+    mod = require(suite);
+    loaded = true;
+  } catch (err) {
+    console.error(`\x1b[31mfailed to load ${rel}:\x1b[0m ${err.stack || err}`);
+    wholeFailure(`load ${rel}`, err.message);
+  }
+  if (loaded && typeof mod !== 'function') {
+    console.error(`\x1b[31m${rel} does not export an async runner function\x1b[0m`);
+    wholeFailure(`export ${rel}`, 'no default export function');
+  } else if (loaded) {
+    try {
+      const res = await mod();
+      result.passed = res.passed || 0;
+      result.failed = res.failed || 0;
+      result.failures = (res.failures || []).map((f) => ({ name: f.name, message: f.err.message }));
+      result.skips = (res.skips || []).map((s) => ({ name: s.name, reason: s.reason }));
+    } catch (err) {
+      // skipSuite() reports a missing precondition, not a defect.
+      if (err.suiteSkipped) {
+        console.log(`\x1b[33m⊘ skipped:\x1b[0m ${err.message}`);
+        result.skipped = err.message;
+      } else {
+        console.error(`\x1b[31m${rel} threw:\x1b[0m ${err.stack || err}`);
+        wholeFailure(`run ${rel}`, err.message);
+      }
+    }
+  }
+  send();
+};
+
+// One suite in a worker process: everything it wrote, both streams in arrival
+// order, its message (null when it ended without one) and its wall time in ms.
+const runWorker = (suite, testDir) => new Promise((resolve) => {
+  const began = Date.now();
+  const child = fork(import.meta.filename, ['--worker', suite, testDir], { stdio: ['ignore', 'pipe', 'pipe', 'ipc'] });
+  const chunks = [];
+  let result = null;
+  let settled = false;
+  const settle = (outcome) => {
+    if (settled) return;
+    settled = true;
+    resolve({ output: Buffer.concat(chunks).toString(), result, ms: Date.now() - began, ...outcome });
+  };
+  child.stdout.on('data', (chunk) => chunks.push(chunk));
+  child.stderr.on('data', (chunk) => chunks.push(chunk));
+  child.on('message', (message) => { result = message; });
+  child.on('exit', () => {
+    setTimeout(() => { child.stdout.destroy(); child.stderr.destroy(); }, PIPE_GRACE_MS).unref();
+  });
+  child.on('close', (code, signal) => settle({ code, signal }));
+  child.on('error', (err) => settle({ code: null, signal: null, error: err.message }));
+});
+
+// Why a worker that sent nothing ended: its exit code or signal, then the last
+// lines it wrote, so the failure line alone says where it stopped.
+const crashMessage = ({ output, code, signal, error }) => {
+  const how = error ? `did not run: ${error}` : signal ? `killed by ${signal}` : `exited with code ${code}`;
+  const tail = stripVTControlCharacters(output).split('\n').map((line) => line.trim()).filter(Boolean).slice(-TAIL_LINES);
+  return `${how} without a result${tail.length ? `; last output: ${tail.join(' | ')}` : ''}`;
+};
+
+/**
+ * One run over a repo: the whole of what `npm test` prints and exits with.
+ * @param {string[]} argv `[--] [suite paths...]`, or a worker's
+ *   `--worker <suite> <suite dir>`
+ * @returns {Promise<void>}
+ */
+export const main = async (argv) => {
+  if (argv[0] === '--worker') {
+    // A parent that is gone takes its workers with it.
+    process.on('disconnect', () => process.exit(1));
+    await runOne(argv[1], argv[2]);
+    return;
+  }
+
+  const start = Date.now();
+  const args = parseArgs(argv);
+  const { root, testDir } = args;
+  const serialRels = serialOf(testDir);
+  const { suites, withMods } = pickSuites(args, serialRels);
+
+  if (suites.length === 0 && !withMods) {
+    console.error(`No *.test.js suites found under ${path.basename(testDir)}/.`);
+    process.exit(1);
+  }
+
+  let passed = 0;
+  let failed = 0;
+  const allFailures = [];
+  const skippedSuites = [];
+  const skippedCases = [];
+  const timings = [];
+
+  // One finished suite: its block printed whole, its counts and time added.
+  const report = (suite, outcome) => {
+    const rel = path.relative(testDir, suite);
+    timings.push({ rel, ms: outcome.ms });
+    process.stdout.write(`\n\x1b[1m\x1b[36m▶ ${rel}\x1b[0m\n${outcome.output}`);
+    const res = outcome.result;
+    if (!res) {
+      failed++;
+      allFailures.push({ name: `run ${rel}`, message: crashMessage(outcome) });
+      return;
+    }
+    if (res.skipped !== null) {
+      skippedSuites.push({ name: rel, reason: res.skipped });
+      return;
+    }
+    passed += res.passed;
+    failed += res.failed;
+    for (const f of res.failures) {
+      allFailures.push({ name: f.whole ? f.name : `${rel} › ${f.name}`, message: f.message });
+    }
+    for (const s of res.skips) {
+      skippedCases.push({ name: `${rel} › ${s.name}`, reason: s.reason });
+    }
+  };
+
+  // The parallel wave: POOL workers at a time, each block printed once it and
+  // every suite before it have finished, so the order is the sorted list's.
+  const serial = new Set(serialRels.map((rel) => path.join(testDir, rel)));
+  const wave = suites.filter((suite) => !serial.has(suite));
+  const outcomes = [];
+  let next = 0;
+  let printed = 0;
+  const lane = async () => {
+    while (next < wave.length) {
+      const i = next++;
+      outcomes[i] = await runWorker(wave[i], testDir);
+      while (printed < wave.length && outcomes[printed]) {
+        report(wave[printed], outcomes[printed]);
+        printed++;
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(POOL, wave.length) }, lane));
+
+  for (const suite of suites.filter((s) => serial.has(s))) {
+    report(suite, await runWorker(suite, testDir));
+  }
+
+  if (withMods) {
+    console.log(`\n\x1b[1m\x1b[36m▶ mod half: claude plugin test\x1b[0m`);
+    const mod = runModHalf(root);
+    if (mod.skip) {
+      console.log(`\x1b[33m⊘ skipped:\x1b[0m ${mod.skip}`);
+      skippedSuites.push({ name: 'mod half (claude plugin test)', reason: mod.skip });
+    } else {
+      passed += mod.passed;
+      failed += mod.failed;
+      for (const f of mod.failures) allFailures.push({ name: `mod half › ${f.name}`, message: f.message });
+    }
+  }
+  const ran = suites.length + (withMods ? 1 : 0);
+
+  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+  const suiteNote = skippedSuites.length ? `, ${skippedSuites.length} suite${skippedSuites.length === 1 ? '' : 's'} skipped` : '';
+  const caseNote = skippedCases.length ? `, ${skippedCases.length} case${skippedCases.length === 1 ? '' : 's'} skipped` : '';
+  console.log(`\n\x1b[1m${passed} passed, ${failed} failed${suiteNote}${caseNote}\x1b[0m (${elapsed}s, ${ran} suite${ran === 1 ? '' : 's'})`);
+  if (timings.length) {
+    const slowest = timings.sort((a, b) => b.ms - a.ms).slice(0, SLOWEST);
+    console.log(`slowest: ${slowest.map(({ rel, ms }) => `${rel} ${(ms / 1000).toFixed(1)}s`).join(', ')}`);
+  }
+
+  // Name every skip, file and case alike: a run must never quietly cover less
+  // than the reader assumes.
+  for (const s of [...skippedSuites, ...skippedCases]) {
+    console.log(`  \x1b[33m⊘ ${s.name}: ${s.reason}\x1b[0m`);
+  }
+
+  if (failed > 0) {
+    console.log('\n\x1b[1mFailures:\x1b[0m');
+    for (const f of allFailures) {
+      console.log(`  - ${f.name}: ${f.message}`);
+    }
+  }
+  // exitCode, not exit(): a block may still be draining into a slow pipe.
+  process.exitCode = failed > 0 ? 1 : 0;
+};
+
+if (import.meta.main) main(process.argv.slice(2));