@vibe-agent-toolkit/utils 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/testing/fault-fs.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `installFaultFs` — an in-process fs fault injector for tests.
+ *
+ * A destructive verb is only as safe as its behaviour on the filesystem's bad
+ * days: a full disk, a read-only mount, a file the OS refuses deep in a tree. The
+ * real thing cannot be summoned on demand, so this module fails a chosen call
+ * with a chosen errno, and can rewrite what `stat` reports (an `ino` of 0, a
+ * case-aliased identity).
+ *
+ * ## How it reaches code that never asked to be faulted
+ *
+ * 1. It replaces the methods ON THE BUILTIN OBJECTS — `require('node:fs')`,
+ *    `fs.promises` (the same object as `node:fs/promises`) and
+ *    `FileHandle.prototype` — for all three API styles (`*Sync`, callback,
+ *    promise).
+ * 2. It then calls `module.syncBuiltinESMExports()`, so a named import
+ *    (`import { rmSync } from 'node:fs'`) sees the replacement. `restore()` undoes
+ *    both steps.
+ * 3. Dependencies that look methods up on the module object at call time — adm-zip
+ *    (`require('fs')`, reading the tree the archive module zips) and write streams
+ *    (`createWriteStream` resolves `open`/`write` from the module) — see the
+ *    replacements with no extra seam. `test/integration/fault-fs-reach` and
+ *    `test/integration/archive-extract` pin every one of these; none is assumed. (No archive
+ *    library WRITES for VAT: an extraction's writes are the archive module's own `fs` calls.)
+ * 4. An fd to path map, filled from intercepted `open*`, gives handle and stream
+ *    operations the path they act on.
+ * 5. `realpathSync.native` and `realpath.native` are properties of the functions, not
+ *    of the module, so they are wrapped on the wrappers, traced as the op `realpath`.
+ *
+ * ## What it cannot reach
+ *
+ * ⚠️ `cpSync`, and on Node >= 23 recursive `rmSync`, are implemented natively: the
+ * harness can fail the CALL (family `write` / `remove`) but never a file inside it.
+ * A verb that wants per-file fault coverage must not use those calls.
+ *
+ * ⚠️ Recursive `fs.rm` / `fs.promises.rm` keep the `fs` functions they found the first time Node
+ * removed a tree in this process. If that was outside a session — on Node 22 any earlier
+ * recursive `rmSync`, which is what a test's cleanup does; on later Nodes an earlier `fs.rm` — no
+ * session sees or fails a call INSIDE the removal, only the `rm` call itself.
+ *
+ * ⚠️ A `FileHandle` is only traced when it was opened AFTER `installFaultFs`:
+ * the fd to path map cannot know the path of a handle that was already open, and
+ * the prototype is patched when the first traced handle is opened. Install first,
+ * then open.
+ *
+ * ## Counting
+ *
+ * Calls made synchronously from inside an intercepted call (an `fs` function that
+ * is itself written in terms of another public one) are not traced again, so one
+ * caller-visible operation is one {@link FsCall}. A rule fires on its `nth` match
+ * only; the calls around it succeed. `FsApi` `'stream'` is reserved: stream I/O
+ * reaches the harness as `callback` calls on the fs object, which is what it is —
+ * so one stream write is three calls (`open`, `write`, `close`), each counted.
+ *
+ * ⛔ Framework-free, like everything under `testing/`: no `vitest` import, so the
+ * `./testing` subpath keeps the empty third-party set its purity pin asserts.
+ */
+import { type FaultRule, type FsApi, type FsOpFamily } from './fault-spec.js';
+export interface FsCall {
+    readonly seq: number;
+    readonly op: string;
+    readonly family: FsOpFamily;
+    readonly api: FsApi;
+    /** Forward-slash, absolute; for handle ops, the path the fd was opened at. */
+    readonly path: string;
+    /** The rename / copyFile / symlink target side. */
+    readonly dest?: string;
+}
+export interface StatRewrite {
+    readonly op: 'stat' | 'lstat' | 'fstat';
+    readonly path: (path: string) => boolean;
+    readonly rewrite: <S extends {
+        ino: number | bigint;
+        dev: number | bigint;
+    }>(stats: S) => S;
+}
+export interface FaultFsSession {
+    /** Only calls under `within`. */
+    readonly calls: readonly FsCall[];
+    /** The calls that were failed. */
+    readonly fired: readonly FsCall[];
+    /** Idempotent; also undoes `syncBuiltinESMExports`. */
+    restore(): void;
+    /**
+     * Resolves once no traced asynchronous call is in flight. A caller's promise can settle while
+     * work it started goes on — Node's `rm` rejects on the first child that fails and leaves its
+     * siblings running — so a run is over when this resolves, not when its verb returns: restore
+     * earlier and that work runs on under the NEXT session.
+     *
+     * @throws Error when calls are still in flight after 10 s (a run that never settles is hung)
+     */
+    settled(): Promise<void>;
+}
+/**
+ * Run `work` — synchronous fs calls a TEST makes on its own behalf while a session is active (a mock
+ * standing in for a child process, capturing what it was handed) — outside the session: none of its
+ * calls is traced, so none becomes an injection point, and none is failed. Without it a harness's own
+ * bookkeeping is indistinguishable from the code under test.
+ *
+ * ⛔ Synchronous only: an asynchronous call started inside returns to the event loop with the session
+ * active again, and its continuation is traced.
+ */
+export declare function untracedFs<T>(work: () => T): T;
+/**
+ * Trace and fault fs calls on paths under `within` until `restore()` is called.
+ *
+ * One session at a time: a second install while one is active throws, because two
+ * stacked sets of wrappers cannot be unwound independently.
+ */
+export declare function installFaultFs(options: {
+    within: string;
+    faults?: readonly FaultRule[];
+    rewrites?: readonly StatRewrite[];
+}): FaultFsSession;
+//# sourceMappingURL=fault-fs.d.ts.map

package/dist/testing/fault-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault-fs.d.ts","sourceRoot":"","sources":["../../src/testing/fault-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAQH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,KAAK,UAAU,EAA4D,MAAM,iBAAiB,CAAC;AAExI,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS;QAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;CAC7F;AAED,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,uDAAuD;IACvD,OAAO,IAAI,IAAI,CAAC;IAChB;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAqCD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAO9C;AAmQD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC9B,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CACnC,GAAG,cAAc,CAwCjB"}

package/dist/testing/fault-fs.js

@@ -0,0 +1,411 @@
+/**
+ * `installFaultFs` — an in-process fs fault injector for tests.
+ *
+ * A destructive verb is only as safe as its behaviour on the filesystem's bad
+ * days: a full disk, a read-only mount, a file the OS refuses deep in a tree. The
+ * real thing cannot be summoned on demand, so this module fails a chosen call
+ * with a chosen errno, and can rewrite what `stat` reports (an `ino` of 0, a
+ * case-aliased identity).
+ *
+ * ## How it reaches code that never asked to be faulted
+ *
+ * 1. It replaces the methods ON THE BUILTIN OBJECTS — `require('node:fs')`,
+ *    `fs.promises` (the same object as `node:fs/promises`) and
+ *    `FileHandle.prototype` — for all three API styles (`*Sync`, callback,
+ *    promise).
+ * 2. It then calls `module.syncBuiltinESMExports()`, so a named import
+ *    (`import { rmSync } from 'node:fs'`) sees the replacement. `restore()` undoes
+ *    both steps.
+ * 3. Dependencies that look methods up on the module object at call time — adm-zip
+ *    (`require('fs')`, reading the tree the archive module zips) and write streams
+ *    (`createWriteStream` resolves `open`/`write` from the module) — see the
+ *    replacements with no extra seam. `test/integration/fault-fs-reach` and
+ *    `test/integration/archive-extract` pin every one of these; none is assumed. (No archive
+ *    library WRITES for VAT: an extraction's writes are the archive module's own `fs` calls.)
+ * 4. An fd to path map, filled from intercepted `open*`, gives handle and stream
+ *    operations the path they act on.
+ * 5. `realpathSync.native` and `realpath.native` are properties of the functions, not
+ *    of the module, so they are wrapped on the wrappers, traced as the op `realpath`.
+ *
+ * ## What it cannot reach
+ *
+ * ⚠️ `cpSync`, and on Node >= 23 recursive `rmSync`, are implemented natively: the
+ * harness can fail the CALL (family `write` / `remove`) but never a file inside it.
+ * A verb that wants per-file fault coverage must not use those calls.
+ *
+ * ⚠️ Recursive `fs.rm` / `fs.promises.rm` keep the `fs` functions they found the first time Node
+ * removed a tree in this process. If that was outside a session — on Node 22 any earlier
+ * recursive `rmSync`, which is what a test's cleanup does; on later Nodes an earlier `fs.rm` — no
+ * session sees or fails a call INSIDE the removal, only the `rm` call itself.
+ *
+ * ⚠️ A `FileHandle` is only traced when it was opened AFTER `installFaultFs`:
+ * the fd to path map cannot know the path of a handle that was already open, and
+ * the prototype is patched when the first traced handle is opened. Install first,
+ * then open.
+ *
+ * ## Counting
+ *
+ * Calls made synchronously from inside an intercepted call (an `fs` function that
+ * is itself written in terms of another public one) are not traced again, so one
+ * caller-visible operation is one {@link FsCall}. A rule fires on its `nth` match
+ * only; the calls around it succeed. `FsApi` `'stream'` is reserved: stream I/O
+ * reaches the harness as `callback` calls on the fs object, which is what it is —
+ * so one stream write is three calls (`open`, `write`, `close`), each counted.
+ *
+ * ⛔ Framework-free, like everything under `testing/`: no `vitest` import, so the
+ * `./testing` subpath keeps the empty third-party set its purity pin asserts.
+ */
+import fs from 'node:fs';
+import { syncBuiltinESMExports } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { relativeEscapesRoot, safePath } from '../path-core.js';
+import { injectedErrnoError, OPS } from './fault-spec.js';
+/** How long {@link FaultFsSession.settled} waits for in-flight calls before it calls the run hung. */
+const SETTLE_LIMIT_MS = 10_000;
+/** `FileHandle.prototype` method name to the op it is traced as. */
+const HANDLE_OPS = {
+    read: 'read', readFile: 'readFile', write: 'write', writev: 'writev', writeFile: 'writeFile',
+    appendFile: 'appendFile', stat: 'fstat', chmod: 'fchmod', truncate: 'ftruncate', sync: 'fsync',
+};
+const REWRITABLE_OPS = new Set(['stat', 'lstat', 'fstat']);
+let active;
+/** Non-zero while an intercepted call is running its original body synchronously, or while {@link untracedFs} runs. */
+let depth = 0;
+/**
+ * Run `work` — synchronous fs calls a TEST makes on its own behalf while a session is active (a mock
+ * standing in for a child process, capturing what it was handed) — outside the session: none of its
+ * calls is traced, so none becomes an injection point, and none is failed. Without it a harness's own
+ * bookkeeping is indistinguishable from the code under test.
+ *
+ * ⛔ Synchronous only: an asynchronous call started inside returns to the event loop with the session
+ * active again, and its continuation is traced.
+ */
+export function untracedFs(work) {
+    depth += 1;
+    try {
+        return work();
+    }
+    finally {
+        depth -= 1;
+    }
+}
+const isUnder = (root, path) => !relativeEscapesRoot(safePath.relative(root, path));
+function toPath(value) {
+    if (typeof value === 'string')
+        return safePath.resolve(value);
+    if (value instanceof URL)
+        return safePath.resolve(fileURLToPath(value));
+    if (Buffer.isBuffer(value))
+        return safePath.resolve(value.toString());
+    return undefined;
+}
+function openFamily(flags) {
+    if (flags === undefined)
+        return 'read';
+    if (typeof flags === 'number') {
+        const writing = fs.constants.O_WRONLY | fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_APPEND;
+        return (flags & writing) === 0 ? 'read' : 'write';
+    }
+    return typeof flags === 'string' && /^[rs]+$/.test(flags) ? 'read' : 'write';
+}
+/** The fd a call acts on: the handle's own for a handle method, else the first argument. */
+function fdOf(style, self, args) {
+    const value = style === 'handle' ? self?.fd : args[0];
+    return typeof value === 'number' ? value : undefined;
+}
+function locate(spec, style, self, args, session) {
+    // A handle method acts on its own fd whatever its module twin takes (`readFile` takes a path there).
+    if (spec.shape === 'fd' || style === 'handle') {
+        const fd = fdOf(style, self, args);
+        const path = fd === undefined ? undefined : session.fdPaths.get(fd);
+        return path === undefined ? undefined : { path };
+    }
+    const first = toPath(args[0]);
+    if (spec.shape === 'one')
+        return first === undefined ? undefined : { path: first };
+    const second = toPath(args[1]);
+    if (first === undefined || second === undefined)
+        return undefined;
+    return spec.shape === 'link' ? { path: second, dest: first } : { path: first, dest: second };
+}
+/** Record the call if it is under `within`; undefined means it is not ours to touch. */
+function trace(session, op, spec, style, self, args) {
+    const located = locate(spec, style, self, args, session);
+    if (located === undefined)
+        return undefined;
+    const { path, dest } = located;
+    if (!isUnder(session.within, path) && !(dest !== undefined && isUnder(session.within, dest)))
+        return undefined;
+    const flags = typeof args[1] === 'function' ? undefined : args[1];
+    const family = spec.family === 'open' ? openFamily(flags) : spec.family;
+    const call = {
+        seq: session.mutableCalls.length + 1, op, family, api: style, path, ...(dest === undefined ? {} : { dest }),
+    };
+    session.mutableCalls.push(call);
+    return call;
+}
+/** Whether `call` is `earlier` asked again: the same operation, through the same API, on the same paths. */
+function isRepeatOf(earlier, call) {
+    return earlier.op === call.op && earlier.api === call.api && earlier.path === call.path && earlier.dest === call.dest;
+}
+function faultFor(session, call) {
+    // A retry of the call an `everyTry` rule just failed fails again, and is no new match of any rule.
+    const { last } = session.retried;
+    if (last !== undefined && isRepeatOf(last.call, call))
+        return last.rule.errno;
+    delete session.retried.last;
+    for (const rule of session.faults) {
+        const matches = (rule.family === undefined || rule.family === call.family)
+            && (rule.op === undefined || rule.op === call.op)
+            && (rule.path(call.path) || (call.dest !== undefined && rule.path(call.dest)));
+        if (!matches)
+            continue;
+        const seen = (session.hits.get(rule) ?? 0) + 1;
+        session.hits.set(rule, seen);
+        if (seen !== (rule.nth ?? 1))
+            continue;
+        if (rule.everyTry === true)
+            session.retried.last = { rule, call };
+        return rule.errno;
+    }
+    return undefined;
+}
+function fail(style, args, error) {
+    if (style === 'promise' || style === 'handle')
+        return Promise.reject(error);
+    const callback = [...args].reverse().find((arg) => typeof arg === 'function');
+    if (style === 'callback' && callback !== undefined) {
+        process.nextTick(callback, error);
+        return undefined;
+    }
+    throw error;
+}
+/**
+ * An injected `close` fault, as the OS reports one: close(2) releases the descriptor even when
+ * it returns an error, so the real close runs and only then is the fault reported. A close the
+ * injection skipped would leave the descriptor open for the rest of the process, and Node closes
+ * an abandoned `FileHandle` during garbage collection as an uncaught error. A real close that
+ * itself fails is reported as itself: the injection only ever adds a fault, never hides one.
+ */
+function failAfterClosing(style, close, args, error) {
+    depth += 1;
+    try {
+        if (style === 'promise' || style === 'handle') {
+            return close(...args).then(() => {
+                throw error;
+            });
+        }
+        const index = args.findLastIndex((arg) => typeof arg === 'function');
+        if (style === 'callback' && index >= 0) {
+            const callback = args[index];
+            // A real close that itself fails is reported as itself, as the other styles do.
+            close(...args.slice(0, index), (closeError) => callback(closeError ?? error));
+            return undefined;
+        }
+        // A real close that itself fails is a real fault, and propagates as one.
+        close(...args);
+        throw error;
+    }
+    finally {
+        depth -= 1;
+    }
+}
+function patch(session, target, key, make) {
+    const original = target[key];
+    if (typeof original !== 'function')
+        return;
+    const wrapped = make(original);
+    // Carry `realpath.native`, util.promisify.custom and the like over to the wrapper.
+    for (const own of Reflect.ownKeys(original)) {
+        if (own === 'length' || own === 'name' || own === 'prototype')
+            continue;
+        Object.defineProperty(wrapped, own, Object.getOwnPropertyDescriptor(original, own));
+    }
+    session.patches.push({ target, key, original });
+    target[key] = wrapped;
+}
+function rewriteStats(session, op, path, value) {
+    let stats = value;
+    for (const rule of session.rewrites) {
+        if (rule.op === op && rule.path(path))
+            stats = rule.rewrite(stats);
+    }
+    return stats;
+}
+/** What to do with a successful result: map an opened fd, patch the first handle, rewrite stats. */
+function adaptResult(session, op, call, value) {
+    if (typeof value !== 'object' || value === null) {
+        if (op === 'open' && typeof value === 'number')
+            session.fdPaths.set(value, call.path);
+        return value;
+    }
+    if (op === 'open') {
+        const fd = value.fd;
+        if (typeof fd === 'number')
+            session.fdPaths.set(fd, call.path);
+        patchFileHandle(session, value);
+        return value;
+    }
+    return REWRITABLE_OPS.has(op) ? rewriteStats(session, op, call.path, value) : value;
+}
+/**
+ * Route a callback API's success value through `settle`, and count the call in flight until its
+ * callback runs; other arguments pass untouched.
+ */
+function settleInCallback(session, args, settle) {
+    const index = args.findLastIndex((arg) => typeof arg === 'function');
+    const callback = args[index];
+    if (callback === undefined)
+        return [...args];
+    const out = [...args];
+    session.inFlight += 1;
+    out[index] = (error, value, ...rest) => {
+        session.inFlight -= 1;
+        return callback(error, error ? value : settle(value), ...rest);
+    };
+    return out;
+}
+/** Count a promise-API call in flight until it settles, whichever way. */
+function countedPromise(session, result, settle) {
+    session.inFlight += 1;
+    return result.finally(() => {
+        session.inFlight -= 1;
+    }).then(settle);
+}
+/**
+ * The wrapper acts for whichever session is active WHEN IT IS CALLED, not the one that made it: code
+ * that captured an `fs` function while a session was active (Node's own `fs.promises.rm` does, on its
+ * first call) keeps calling this wrapper after `restore()`, and must be traced by every later session.
+ */
+function makeWrapper(op, spec, style, original) {
+    return function wrapped(...args) {
+        const session = active;
+        if (session === undefined || depth > 0)
+            return original.apply(this, args);
+        const call = trace(session, op, spec, style, this, args);
+        if (call === undefined)
+            return original.apply(this, args);
+        const errno = faultFor(session, call);
+        if (errno !== undefined) {
+            session.mutableFired.push(call);
+            const error = injectedErrnoError(errno, op, call.path);
+            return op === 'close' ? failAfterClosing(style, original.bind(this), args, error) : fail(style, args, error);
+        }
+        // A close forgets its fd whatever the API; the fd is only known before the call.
+        const closing = op === 'close' ? fdOf(style, this, args) : undefined;
+        const settle = (value) => {
+            if (closing !== undefined)
+                session.fdPaths.delete(closing);
+            return adaptResult(session, op, call, value);
+        };
+        const callArgs = style === 'callback' ? settleInCallback(session, args, settle) : args;
+        depth += 1;
+        let result;
+        try {
+            result = original.apply(this, callArgs);
+        }
+        finally {
+            depth -= 1;
+        }
+        if (style === 'sync')
+            return settle(result);
+        if (style === 'promise' || style === 'handle')
+            return countedPromise(session, result, settle);
+        return result;
+    };
+}
+const nextTurn = () => new Promise((resolve) => {
+    setImmediate(resolve);
+});
+/** Turn the event loop until nothing the session traced is in flight: a completed call's continuation may start the next one. */
+async function settledOf(session, deadline = Date.now() + SETTLE_LIMIT_MS) {
+    await nextTurn();
+    if (session.inFlight === 0)
+        return;
+    if (Date.now() > deadline)
+        throw new Error(`fault-fs: ${session.inFlight} traced fs call(s) still in flight after ${SETTLE_LIMIT_MS} ms`);
+    return settledOf(session, deadline);
+}
+/**
+ * Patch `FileHandle.prototype` from the first traced handle, and every traced handle's own
+ * `close` (Node defines it per handle, as a class field); `restore()` puts all of them back.
+ */
+function patchFileHandle(session, handle) {
+    const close = OPS['close'];
+    if (close !== undefined)
+        patch(session, handle, 'close', (original) => makeWrapper('close', close, 'handle', original));
+    if (session.handlePatched)
+        return;
+    session.handlePatched = true;
+    const prototype = Object.getPrototypeOf(handle);
+    for (const [method, op] of Object.entries(HANDLE_OPS)) {
+        const spec = OPS[op];
+        if (spec !== undefined)
+            patch(session, prototype, method, (original) => makeWrapper(op, spec, 'handle', original));
+    }
+}
+/**
+ * Wrap `realpathSync.native` and `realpath.native` as the op `realpath`. They hang off the
+ * functions as properties, so {@link patch} copies them onto the wrappers UNWRAPPED, and
+ * `normalizePath` asks the native one first: without this every product realpath fault was
+ * out of the harness's reach. The patch lands on the wrapper, which `restore()` drops along
+ * with its property; the originals never change.
+ */
+function patchNativeRealpath(session) {
+    const spec = OPS['realpath'];
+    if (spec === undefined)
+        return;
+    patch(session, fs.realpathSync, 'native', (original) => makeWrapper('realpath', spec, 'sync', original));
+    patch(session, fs.realpath, 'native', (original) => makeWrapper('realpath', spec, 'callback', original));
+}
+/**
+ * Trace and fault fs calls on paths under `within` until `restore()` is called.
+ *
+ * One session at a time: a second install while one is active throws, because two
+ * stacked sets of wrappers cannot be unwound independently.
+ */
+export function installFaultFs(options) {
+    if (active !== undefined)
+        throw new Error('installFaultFs: a fault session is already active; restore() it first');
+    const mutableCalls = [];
+    const mutableFired = [];
+    const session = {
+        within: safePath.resolve(options.within),
+        faults: options.faults ?? [],
+        rewrites: options.rewrites ?? [],
+        hits: new Map(),
+        retried: {},
+        fdPaths: new Map(),
+        patches: [],
+        mutableCalls,
+        mutableFired,
+        handlePatched: false,
+        restored: false,
+        inFlight: 0,
+        calls: mutableCalls,
+        fired: mutableFired,
+        restore() {
+            if (session.restored)
+                return;
+            session.restored = true;
+            for (const { target, key, original } of session.patches.toReversed()) {
+                target[key] = original;
+            }
+            session.fdPaths.clear();
+            if (active === session)
+                active = undefined;
+            syncBuiltinESMExports();
+        },
+        settled: () => settledOf(session),
+    };
+    active = session;
+    for (const [op, spec] of Object.entries(OPS)) {
+        patch(session, fs, `${op}Sync`, (original) => makeWrapper(op, spec, 'sync', original));
+        patch(session, fs, op, (original) => makeWrapper(op, spec, 'callback', original));
+        patch(session, fs.promises, op, (original) => makeWrapper(op, spec, 'promise', original));
+    }
+    patchNativeRealpath(session);
+    syncBuiltinESMExports();
+    return session;
+}
+//# sourceMappingURL=fault-fs.js.map

package/dist/testing/fault-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault-fs.js","sourceRoot":"","sources":["../../src/testing/fault-fs.ts"],"names":[],"mappings":"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"}

package/dist/testing/fault-spec.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The fault harness's vocabulary, with no filesystem call in it: the errnos it raises, the
+ * operations it traces and their families, a rule, the error a rule raises, and the JSON spec a
+ * spawned process is handed (`VAT_FAULT_FS`). `fault-fs.ts` is the half that patches `node:fs`.
+ *
+ * ⛔ Framework-free, like everything under `testing/`.
+ */
+/**
+ * Every errno the injector raises (`EDQUOT` too on a host whose `os.constants.errno` lacks it: it gets
+ * `-1`). At least one of every class of the errno table: `EEXIST` / `ENOTEMPTY` (`occupied`) are what a
+ * concurrent writer or a name collision produces, `EIO` (`device`) what a failing disk does, `UNKNOWN`
+ * (`device` too) what Windows reports for a network share that is not there AND for credentials the
+ * share refused (libuv `src/win/error.c:172`; `-1` too). `ENETUNREACH`, `EHOSTUNREACH`, `ECONNRESET`
+ * and `ENOTCONN` are what a file call on a share raises when the network fails (`device`);
+ * `EINVAL` and `ENAMETOOLONG` are Windows' ambiguous answers for a link (:102-105, :129). `EWHATEVER`
+ * is no errno at all: one no table lists, which must still be classified, never handed back raw.
+ */
+export declare const INJECTED_ERRNOS: readonly ["EACCES", "EPERM", "ENOSPC", "EDQUOT", "EROFS", "EMFILE", "ENFILE", "ENOENT", "EISDIR", "ENOTDIR", "EBUSY", "EXDEV", "EEXIST", "ENOTEMPTY", "EIO", "UNKNOWN", "ENETUNREACH", "EHOSTUNREACH", "ECONNRESET", "ENOTCONN", "EINVAL", "ENAMETOOLONG", "EWHATEVER"];
+export type InjectedErrno = (typeof INJECTED_ERRNOS)[number];
+declare const FS_OP_FAMILIES: readonly ["read", "write", "meta", "list", "remove", "rename", "create"];
+export type FsOpFamily = (typeof FS_OP_FAMILIES)[number];
+export type FsApi = 'sync' | 'callback' | 'promise' | 'handle' | 'stream';
+export interface FaultRule {
+    readonly family?: FsOpFamily;
+    readonly op?: string;
+    readonly path: (path: string) => boolean;
+    /** 1-based among calls matching family / op / path. Default 1. */
+    readonly nth?: number;
+    readonly errno: InjectedErrno;
+    /**
+     * Also fail every IMMEDIATE repeat of the call the rule failed — the same operation on the same
+     * paths, no other traced call between: what a retry is. The repeats are not matches of their own,
+     * so `nth` numbers the same calls whoever retries.
+     *
+     * Without it a rule fails exactly one call, and a caller that retries turns that into a success:
+     * under win32 every tree-change rename is retried on `EACCES`, `EPERM` and `EBUSY`. A test that
+     * means "this rename is refused" sets it, and then asks the same thing on every platform.
+     */
+    readonly everyTry?: boolean;
+}
+/**
+ * Build the error Node would have thrown for `errno`.
+ *
+ * `errno` carries libuv's negative number (`-28` for `ENOSPC`) from `os.constants`;
+ * a code the host lacks (`EDQUOT` on win32) gets `-1`.
+ */
+export declare function injectedErrnoError(errno: InjectedErrno, syscall: string, path: string): NodeJS.ErrnoException;
+export type PathShape = 'fd' | 'one' | 'two' | 'link';
+export interface OpSpec {
+    /** `'open'` is decided by the flags: a read-only open is `read`, anything else `write`. */
+    readonly family: FsOpFamily | 'open';
+    /** Where the path is: an fd, the first argument, the first two, or `symlink(target, path)`. */
+    readonly shape: PathShape;
+}
+/** Every operation the harness traces and can fail; the three wrappers are generated from it. */
+export declare const OPS: Readonly<Record<string, OpSpec>>;
+/**
+ * A {@link FaultRule} that can cross a process boundary as JSON: the path is matched by a
+ * substring of its forward-slash form, since a predicate cannot be serialised.
+ */
+export interface FaultSpec {
+    readonly family?: FsOpFamily;
+    readonly op?: string;
+    readonly pathIncludes: string;
+    readonly nth?: number;
+    readonly errno: InjectedErrno;
+}
+/** What `fault-fs-preload` reads from `VAT_FAULT_FS`: the session's root and its faults. */
+export interface FaultFsSpec {
+    readonly within: string;
+    readonly faults: readonly FaultSpec[];
+}
+/** The rule a {@link FaultSpec} stands for; what the spec leaves out, the injector defaults. */
+export declare function faultRuleOf(spec: FaultSpec): FaultRule;
+/**
+ * Parse the `VAT_FAULT_FS` JSON a spawned process is handed.
+ *
+ * @throws Error naming the variable when the text is not JSON, has no `within`, or holds a fault
+ *   the injector cannot raise as written: a malformed spec must not run the process unfaulted
+ */
+export declare function faultFsSpecOf(text: string): FaultFsSpec;
+export {};
+//# sourceMappingURL=fault-spec.d.ts.map

package/dist/testing/fault-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault-spec.d.ts","sourceRoot":"","sources":["../../src/testing/fault-spec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,yQAGlB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,QAAA,MAAM,cAAc,0EAA2E,CAAC;AAChG,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AACzD,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,CAQ7G;AAED,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AACtD,MAAM,WAAW,MAAM;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IACrC,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED,iGAAiG;AACjG,eAAO,MAAM,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkChD,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;CACvC;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAQtD;AA2BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAavD"}