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

package/dist/errors/confirmed-absent.js

@@ -0,0 +1,43 @@
+/**
+ * Believe "nothing there" only when the parent's listing agrees.
+ *
+ * A probe — a read, an `lstat` — that the OS answers with `ENOENT` or `ENOTDIR`
+ * means absent only if it is right. Read as absent on its own word, a refusal of a
+ * file that IS there turns a registry into an empty one and a destination into a
+ * free one, and the write after it drops what was there. The parent's listing is a
+ * second, independent witness: an entry it names is there, and the probe's answer
+ * was a fault — except a link under a probe that follows links (a read), which
+ * sees through it to a target that really is missing. An `lstat` sees the link
+ * itself, so for it a listed link is a fault like any entry.
+ */
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { isPathAbsentError } from './errno-table.js';
+import { classifyFsFault, refusedPathOf } from './fs-fault.js';
+/**
+ * Confirm that nothing is at `entry` after a probe of it said "absent".
+ *
+ * @param entry - The path the probe examined
+ * @param absent - What the probe threw (`ENOENT` / `ENOTDIR`)
+ * @param ctx - The caller's action, for the fault
+ * @param probe - How the probe looked, and the side of each path it may charge
+ * @throws the probe's own error classified on `sideOf(entry)` (naming `entry`) when the parent
+ *   lists it (a link only to a probe that does not follow); the listing's error classified on
+ *   `sideOf(parent)` when the parent is there but cannot be listed — absence was never shown
+ */
+export function requireConfirmedAbsent(entry, absent, ctx, probe) {
+    const parent = path.dirname(entry);
+    let listed;
+    try {
+        listed = readdirSync(parent, { withFileTypes: true }).find((dirent) => dirent.name === path.basename(entry));
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return;
+        throw classifyFsFault(error, { ...ctx, side: probe.sideOf(refusedPathOf(error, parent)), path: parent });
+    }
+    if (listed === undefined || (probe.follows && listed.isSymbolicLink()))
+        return;
+    throw classifyFsFault(absent, { ...ctx, side: probe.sideOf(entry), path: entry });
+}
+//# sourceMappingURL=confirmed-absent.js.map

package/dist/errors/confirmed-absent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmed-absent.js","sourceRoot":"","sources":["../../src/errors/confirmed-absent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAuB,aAAa,EAAmB,MAAM,eAAe,CAAC;AAiBrG;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa,EAAE,MAAe,EAAE,GAAwB,EAAE,KAAwB;IACvH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/G,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO;QACrC,MAAM,eAAe,CAAC,KAAK,EAAE,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAAE,OAAO;IAC/E,MAAM,eAAe,CAAC,MAAM,EAAE,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACpF,CAAC"}

package/dist/errors/errno-table.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The errno table and every single-errno question — the leaf of the fs-fault
+ * family.
+ *
+ * ⚠️ This module imports nothing but `win32-namespace.ts`, a leaf that itself imports nothing. `path-containment.ts`, `path-utils.ts`,
+ * `dirent-kind.ts` and `fs-utils.ts` ask "is there nothing at this path?", and
+ * `fs-fault.ts` needs `path-containment.ts` to decide a side by containment, so
+ * the table cannot live in `fs-fault.ts` without an import cycle
+ * (`fs-fault → path-containment → fs-fault`). It lives here, and `fs-fault.ts`
+ * builds classification on top of it.
+ *
+ * The errno sets are those of the former `FILESYSTEM_ACCESS_ERRNOS`; every
+ * member keeps exactly one class. The table is not the guarantee: an errno it
+ * does not list, on an error a system call raised, is still a fault — of the
+ * `device` class ({@link UNLISTED_ERRNO_CLASS}) — so a code libuv adds, or one a
+ * host reports that nobody wrote down, is never handed back raw. An error with
+ * no errno-shaped `code` is not a filesystem fault and {@link fsFaultOf} answers
+ * `undefined`, so a `TypeError` from a validator is never read as the
+ * environment's fault. The errnos a socket shares with a file on a share — the
+ * network ones — and every unlisted errno count only when a filesystem call
+ * raised them ({@link isRaisedByFilesystemCall}), so a `connect` or a fetch that
+ * failed is never read as one either.
+ */
+/** What kind of thing the OS said went wrong, independent of which side of a verb it happened on. */
+export type FsFaultClass = 'absent' | 'refused' | 'exhausted' | 'wrong-type' | 'occupied' | 'busy' | 'unsupported' | 'device';
+/**
+ * The one place an errno gets a class. `EROFS` is `unsupported`: the filesystem cannot be written, no permission would change it.
+ *
+ * Frozen, lists included: the classifier's lookup is built from it once, at load, so a list a
+ * consumer could change afterwards would be a second table the classifier does not agree with.
+ */
+export declare const FS_FAULT_ERRNOS_BY_CLASS: Readonly<Record<FsFaultClass, readonly string[]>>;
+/**
+ * The class of an errno a caller already KNOWS a filesystem call raised — a listing git reported
+ * it could not open, say, where only the errno survives: the table's class, else
+ * {@link UNLISTED_ERRNO_CLASS}. Never `undefined`: the question "is this the filesystem?" was
+ * settled where the error was in hand.
+ *
+ * @param errno - The errno
+ * @returns Its class
+ */
+export declare function filesystemErrnoClass(errno: string): FsFaultClass;
+/**
+ * The code a path whose link chain VAT will not hand the kernel is refused with
+ * (`LinkChainRefusedError`, `tree-change/host-chain.ts`): a link on the way names
+ * a network path, or the chain never ends. Not an errno — VAT declined to ask the
+ * OS — but recorded where an errno is (a refused listing, a fault row), always
+ * of the `refused` class.
+ */
+export declare const LINK_CHAIN_REFUSED_CODE = "LINK_CHAIN_REFUSED";
+/** What `fsFaultOf` learned from the error that carried the errno. */
+export interface FsFaultFacts {
+    readonly errno: string;
+    readonly faultClass: FsFaultClass;
+    readonly path: string | undefined;
+    readonly dest: string | undefined;
+    readonly syscall: string | undefined;
+}
+/**
+ * The classified errno on `error` or down its `cause` chain, with the path the OS
+ * named — or `undefined` when this is not the filesystem refusing something.
+ *
+ * Deliberately NOT `error instanceof Error`: callers degrade on a hostile tree,
+ * and a `TypeError` is not that. Walks `cause` because the errno is routinely
+ * re-wrapped on its way up (the CLI config loader turns a read failure into
+ * `new Error('Failed to load config: …')`); a `code`-only check answered "not a
+ * filesystem error" for a plain `EACCES`.
+ *
+ * A listed errno anywhere on the chain wins (a network one only from a filesystem call); failing
+ * that, the first errno a filesystem call raised that the table does not list is a fault of
+ * {@link UNLISTED_ERRNO_CLASS} — never `undefined`, so no caller hands it back raw. A link chain VAT
+ * would not hand the kernel ({@link LINK_CHAIN_REFUSED_CODE}, a `LinkChainRefusedError` — matched by
+ * its code and its `refusal`, as this module cannot import it) is a fault of the `refused` class
+ * too, so every catch that asks "is this the filesystem?" answers it as one, never as a bug.
+ */
+export declare function fsFaultOf(error: unknown): FsFaultFacts | undefined;
+/**
+ * The paths the failing syscall ACTED ON, the one to name the fault by first.
+ *
+ * Node files a two-path call's first argument under `path` and its second under `dest`, whatever
+ * the call does with them. For `symlink(target, link)` the first is the link's TARGET TEXT — a
+ * string the call never resolved, often relative — so only `dest`, the link being created, is a
+ * path the call acted on. `rename(from, to)` acted on both, and what it could not do is land the
+ * entry: `dest` first. Every other call — `link(existing, new)` and `copyfile` included, whose
+ * two arguments are both real paths either of which may be the one refused — is read `path` first.
+ *
+ * @param facts - The fault's facts, as {@link fsFaultOf} read them off the errno
+ * @returns Every path the call acted on, the one that names the fault first; empty when the errno carries none
+ */
+export declare function pathsActedOn(facts: FsFaultFacts): readonly string[];
+/**
+ * For a refused `rename`, the entry that was being moved — the other end of the path the fault is
+ * named by. `undefined` for every other call, and for a rename whose errno names one path only.
+ *
+ * @param facts - The fault's facts, as {@link fsFaultOf} read them off the errno
+ */
+export declare function movedFromOf(facts: FsFaultFacts): string | undefined;
+/**
+ * Whether `error` means **there is nothing at this path** — `ENOENT`, or `ENOTDIR`
+ * for a path whose component turned out to be a file — and nothing else. The
+ * narrowing a `try { stat(p) } catch { return null }` is rewritten to under
+ * `no-blind-catch`: only an absence may produce the sentinel; a refusal or a
+ * bug is rethrown.
+ */
+export declare function isPathAbsentError(error: unknown): boolean;
+/**
+ * `ENOENT` alone: nothing at this path, with every directory above it real. For a
+ * site where `ENOTDIR` — a component that is a FILE — must stay loud, because it
+ * means a misconfiguration rather than "not there yet" ({@link isPathAbsentError}
+ * folds the two together).
+ */
+export declare function isNoSuchEntryError(error: unknown): boolean;
+/**
+ * `ENOTDIR` alone: a component of the path is a FILE. On a write whose layout an
+ * input decided, that is a file in the way of a directory the layout needs — a
+ * layout fault, though the class table files `ENOTDIR` under `absent` (for a read
+ * it means "nothing there").
+ */
+export declare function isFileInTheWayError(error: unknown): boolean;
+/** `EEXIST`: the exclusive create lost to something already there. */
+export declare function isAlreadyExistsError(error: unknown): boolean;
+/** The `occupied` class (`EEXIST`, `ENOTEMPTY`): something is in the way — a directory `rmdir` was asked to remove still holds entries. */
+export declare function isOccupiedError(error: unknown): boolean;
+/**
+ * Whether resolving a link failed because **the link resolves to nothing** ({@link UNRESOLVABLE_LINK_ERRNOS}),
+ * as opposed to a fault of the OS or the operator's tree, which the caller throws for the classifier.
+ * The one answer to "does this link resolve?" for every site that follows one. `false` for an
+ * error that carries no errno.
+ */
+export declare function isUnresolvableLinkError(error: unknown): boolean;
+/**
+ * `EISDIR`, `ENOTSUP`, `EOPNOTSUPP` from a NATIVE realpath (`realpathSync.native`, `fs/promises.realpath`):
+ * the volume cannot answer a final-path query, which says nothing about the path. On Windows libuv
+ * maps `ERROR_INVALID_FUNCTION` — what `GetFinalPathNameByHandleW` returns on a RAM disk or a
+ * redirector that does not implement it — to `EISDIR` (`src/win/error.c`). The answer is the JS
+ * realpath (an lstat/readlink walk), which never asks that question.
+ */
+export declare function isFinalPathUnanswerableError(error: unknown): boolean;
+/** `ENAMETOOLONG`: a name (or path) longer than this host's filesystem will take. */
+export declare function isNameTooLongError(error: unknown): boolean;
+/** `EINVAL`: the filesystem rejected the argument (e.g. `readlink` on a non-link). */
+export declare function isInvalidArgumentError(error: unknown): boolean;
+/** `EFTYPE`: BSD's "inappropriate file type" — a pipe, socket or device where content was expected. */
+export declare function isNotARegularFileError(error: unknown): boolean;
+/** `ETIMEDOUT`: an operation (a child process given a `timeout`, a network filesystem) ran out of time. */
+export declare function isTimedOutError(error: unknown): boolean;
+/** `EAGAIN`: a non-blocking descriptor (stdout on a full pipe) would block. */
+export declare function isWouldBlockError(error: unknown): boolean;
+/**
+ * `ESRCH` or `EPERM` from signalling a process group we created: no such group,
+ * or its id was recycled to a process we may not signal. Either way every
+ * process of ours in it has exited — the outcome the kill was after.
+ */
+export declare function isProcessGoneError(error: unknown): boolean;
+/** This host cannot create symlinks: Windows without Developer Mode (`EPERM`), or a filesystem with none (`ENOTSUP`/`EOPNOTSUPP`). */
+export declare function isSymlinkUnsupportedError(error: unknown): boolean;
+/**
+ * A refusal a re-ask can legitimately answer differently: the `busy` class
+ * (`EBUSY`, `ETXTBSY`, `EAGAIN`), or this process out of descriptors (`EMFILE`,
+ * `ENFILE`). Disk and quota exhaustion (`ENOSPC`, `EDQUOT`) share the `exhausted`
+ * class but are NOT retryable: re-asking frees no space, so "re-run first" would
+ * be the wrong advice.
+ */
+export declare function isRetryableShortageError(error: unknown): boolean;
+/**
+ * The errnos Windows raises when a rename races a scanner, indexer or handle
+ * that has the tree open: `EPERM`, `EBUSY`, `EACCES`. Worth a bounded retry;
+ * anything else is final.
+ */
+export declare function isRenameContentionError(error: unknown): boolean;
+/**
+ * The `refused` class (`EACCES`, `EPERM`): the OS refused the caller's access. A
+ * removal refused this way is retried once its directories are made owner-writable:
+ * a read-only directory refuses the removal of its entries.
+ */
+export declare function isAccessRefusedError(error: unknown): boolean;
+//# sourceMappingURL=errno-table.d.ts.map

package/dist/errors/errno-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errno-table.d.ts","sourceRoot":"","sources":["../../src/errors/errno-table.ts"],"names":[],"mappings":"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"}

package/dist/errors/errno-table.js

@@ -0,0 +1,343 @@
+/**
+ * The errno table and every single-errno question — the leaf of the fs-fault
+ * family.
+ *
+ * ⚠️ This module imports nothing but `win32-namespace.ts`, a leaf that itself imports nothing. `path-containment.ts`, `path-utils.ts`,
+ * `dirent-kind.ts` and `fs-utils.ts` ask "is there nothing at this path?", and
+ * `fs-fault.ts` needs `path-containment.ts` to decide a side by containment, so
+ * the table cannot live in `fs-fault.ts` without an import cycle
+ * (`fs-fault → path-containment → fs-fault`). It lives here, and `fs-fault.ts`
+ * builds classification on top of it.
+ *
+ * The errno sets are those of the former `FILESYSTEM_ACCESS_ERRNOS`; every
+ * member keeps exactly one class. The table is not the guarantee: an errno it
+ * does not list, on an error a system call raised, is still a fault — of the
+ * `device` class ({@link UNLISTED_ERRNO_CLASS}) — so a code libuv adds, or one a
+ * host reports that nobody wrote down, is never handed back raw. An error with
+ * no errno-shaped `code` is not a filesystem fault and {@link fsFaultOf} answers
+ * `undefined`, so a `TypeError` from a validator is never read as the
+ * environment's fault. The errnos a socket shares with a file on a share — the
+ * network ones — and every unlisted errno count only when a filesystem call
+ * raised them ({@link isRaisedByFilesystemCall}), so a `connect` or a fetch that
+ * failed is never read as one either.
+ */
+import { withoutWin32Namespace } from '../win32-namespace.js';
+/**
+ * The one place an errno gets a class. `EROFS` is `unsupported`: the filesystem cannot be written, no permission would change it.
+ *
+ * Frozen, lists included: the classifier's lookup is built from it once, at load, so a list a
+ * consumer could change afterwards would be a second table the classifier does not agree with.
+ */
+export const FS_FAULT_ERRNOS_BY_CLASS = {
+    absent: ['ENOENT', 'ENOTDIR'],
+    refused: ['EACCES', 'EPERM'],
+    exhausted: ['ENOSPC', 'EDQUOT', 'EMFILE', 'ENFILE'],
+    // EFTYPE: BSD's errno for a named pipe, socket or device where content was expected (`readDecodableBytes` raises it)
+    'wrong-type': ['EISDIR', 'EFTYPE', 'ELOOP', 'ENAMETOOLONG'],
+    occupied: ['EEXIST', 'ENOTEMPTY'],
+    busy: ['EBUSY', 'ETXTBSY', 'EAGAIN'],
+    unsupported: ['ENOTSUP', 'EOPNOTSUPP', 'EXDEV', 'EINVAL', 'EROFS'],
+    // The network errnos a file call on a share raises — libuv v1.x `src/win/error.c` maps
+    // `ERROR_NETWORK_UNREACHABLE` to ENETUNREACH (:131), `ERROR_HOST_UNREACHABLE` to EHOSTUNREACH
+    // (:100), `ERROR_NETNAME_DELETED` (the share went away mid-call) to ECONNRESET (:94) and
+    // `ERROR_NOT_CONNECTED` to ENOTCONN (:152).
+    //
+    // UNKNOWN: what `uv_translate_sys_error` answers for a Win32 error it has NO case for (`default:
+    // return UV_UNKNOWN;`, :172) — and only that; every Win32 error with a case is its mapped errno,
+    // the network ones above included. Among the unmapped: a share that is not there
+    // (`ERROR_BAD_NETPATH`, `ERROR_BAD_NET_NAME`), credentials or an ACL the share refused
+    // (`ERROR_LOGON_FAILURE`, `ERROR_NETWORK_ACCESS_DENIED`), a drive that is not ready or not there
+    // (`ERROR_NOT_READY`, `ERROR_DEV_NOT_EXIST`). The Win32 cause is lost, so UNKNOWN is ambiguous: a
+    // fault, never "resolves to nothing".
+    device: ['EIO', 'ESTALE', 'ETIMEDOUT', 'EHOSTDOWN', 'ENETDOWN', 'ENETUNREACH', 'EHOSTUNREACH', 'ECONNRESET', 'ENOTCONN', 'UNKNOWN'],
+};
+for (const errnos of Object.values(FS_FAULT_ERRNOS_BY_CLASS))
+    Object.freeze(errnos);
+Object.freeze(FS_FAULT_ERRNOS_BY_CLASS);
+const CLASS_BY_ERRNO = new Map(Object.entries(FS_FAULT_ERRNOS_BY_CLASS)
+    .flatMap(([faultClass, errnos]) => errnos.map((errno) => [errno, faultClass])));
+/**
+ * The class of an errno the table does not list, raised by a system call (`EFAULT`, `ECHARSET`,
+ * whatever a later libuv or another host adds). `device`: the OS could not complete the call for a
+ * reason VAT has no name for — a fault on the side it happened, with the "check the device" remedy,
+ * never "nothing there" and never an internal error.
+ */
+const UNLISTED_ERRNO_CLASS = 'device';
+/** An errno-shaped code: libuv's `E…` names and its `UNKNOWN`. Node's own `ERR_…` codes are not errnos. */
+const ERRNO_SHAPE = /^(E[A-Z0-9]+|UNKNOWN)$/;
+/**
+ * The listed errnos a socket raises as readily as a file call on a share does. Listed (a share
+ * reports them), but a fault only when a filesystem call raised them ({@link isRaisedByFilesystemCall}).
+ */
+const NETWORK_ERRNOS = new Set(['ENETUNREACH', 'EHOSTUNREACH', 'ECONNRESET', 'ENOTCONN']);
+/**
+ * The filesystem calls that act on a descriptor and so name no path. `read`, `write` and `close`
+ * are not here: a socket raises them too (a fetch's `ECONNRESET` is `syscall: 'read'`), and nothing
+ * on the error tells the two apart.
+ */
+const FILESYSTEM_FD_SYSCALLS = new Set(['fstat', 'ftruncate', 'fsync', 'fdatasync', 'futime', 'fchmod', 'fchown']);
+/**
+ * The ONE test of "a filesystem call raised this": the error names the path it acted on (`path`
+ * or `dest` — every path-taking fs call reports one, and no socket call does: a socket names an
+ * `address`), or its syscall is a descriptor-only filesystem call ({@link FILESYSTEM_FD_SYSCALLS}).
+ * Both the network errnos and the unlisted fallback ask it, so they cannot disagree.
+ */
+function isRaisedByFilesystemCall(node) {
+    if (stringField(node, 'path') !== undefined || stringField(node, 'dest') !== undefined)
+        return true;
+    const syscall = stringField(node, 'syscall');
+    return syscall !== undefined && FILESYSTEM_FD_SYSCALLS.has(syscall);
+}
+/** Whether the error that carries `code` holds a listed errno that is a fault here. */
+function isListedFault(code, node) {
+    return CLASS_BY_ERRNO.has(code) && (!NETWORK_ERRNOS.has(code) || isRaisedByFilesystemCall(node));
+}
+/** Whether the error that carries `code` is a refused link chain (`LinkChainRefusedError`, by shape). */
+function isRefusedLinkChain(code, node) {
+    return code === LINK_CHAIN_REFUSED_CODE && 'refusal' in node;
+}
+/** Whether the error that carries `code` is a filesystem call's errno the table does not list. */
+function isUnlistedFilesystemErrno(code, node) {
+    return ERRNO_SHAPE.test(code) && !CLASS_BY_ERRNO.has(code) && isRaisedByFilesystemCall(node);
+}
+/**
+ * The class of an errno a caller already KNOWS a filesystem call raised — a listing git reported
+ * it could not open, say, where only the errno survives: the table's class, else
+ * {@link UNLISTED_ERRNO_CLASS}. Never `undefined`: the question "is this the filesystem?" was
+ * settled where the error was in hand.
+ *
+ * @param errno - The errno
+ * @returns Its class
+ */
+export function filesystemErrnoClass(errno) {
+    if (errno === LINK_CHAIN_REFUSED_CODE)
+        return 'refused';
+    return CLASS_BY_ERRNO.get(errno) ?? UNLISTED_ERRNO_CLASS;
+}
+/**
+ * The code a path whose link chain VAT will not hand the kernel is refused with
+ * (`LinkChainRefusedError`, `tree-change/host-chain.ts`): a link on the way names
+ * a network path, or the chain never ends. Not an errno — VAT declined to ask the
+ * OS — but recorded where an errno is (a refused listing, a fault row), always
+ * of the `refused` class.
+ */
+export const LINK_CHAIN_REFUSED_CODE = 'LINK_CHAIN_REFUSED';
+const MAX_CAUSE_DEPTH = 10;
+/** A path field of an errno, without the win32 namespace prefix Node may report it with — read once, here, for every consumer. */
+function reportedPath(source, key) {
+    const reported = stringField(source, key);
+    return reported === undefined ? undefined : withoutWin32Namespace(reported);
+}
+function stringField(source, key) {
+    const value = source[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * The first error on `error`'s `cause` chain whose string `code` satisfies
+ * `accept`. Bounded: a malformed chain must not become an infinite loop inside
+ * an error path, which is the worst place to hang.
+ */
+function findCoded(error, accept) {
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        const code = stringField(current, 'code');
+        if (code !== undefined && accept(code, current))
+            return { node: current, code };
+        if (!('cause' in current))
+            return undefined;
+        current = current.cause;
+    }
+    return undefined;
+}
+/**
+ * The classified errno on `error` or down its `cause` chain, with the path the OS
+ * named — or `undefined` when this is not the filesystem refusing something.
+ *
+ * Deliberately NOT `error instanceof Error`: callers degrade on a hostile tree,
+ * and a `TypeError` is not that. Walks `cause` because the errno is routinely
+ * re-wrapped on its way up (the CLI config loader turns a read failure into
+ * `new Error('Failed to load config: …')`); a `code`-only check answered "not a
+ * filesystem error" for a plain `EACCES`.
+ *
+ * A listed errno anywhere on the chain wins (a network one only from a filesystem call); failing
+ * that, the first errno a filesystem call raised that the table does not list is a fault of
+ * {@link UNLISTED_ERRNO_CLASS} — never `undefined`, so no caller hands it back raw. A link chain VAT
+ * would not hand the kernel ({@link LINK_CHAIN_REFUSED_CODE}, a `LinkChainRefusedError` — matched by
+ * its code and its `refusal`, as this module cannot import it) is a fault of the `refused` class
+ * too, so every catch that asks "is this the filesystem?" answers it as one, never as a bug.
+ */
+export function fsFaultOf(error) {
+    const found = findCoded(error, isListedFault) ?? findCoded(error, isUnlistedFilesystemErrno) ?? findCoded(error, isRefusedLinkChain);
+    if (found === undefined)
+        return undefined;
+    return {
+        errno: found.code,
+        faultClass: filesystemErrnoClass(found.code),
+        path: reportedPath(found.node, 'path'),
+        dest: reportedPath(found.node, 'dest'),
+        syscall: stringField(found.node, 'syscall'),
+    };
+}
+/**
+ * The paths the failing syscall ACTED ON, the one to name the fault by first.
+ *
+ * Node files a two-path call's first argument under `path` and its second under `dest`, whatever
+ * the call does with them. For `symlink(target, link)` the first is the link's TARGET TEXT — a
+ * string the call never resolved, often relative — so only `dest`, the link being created, is a
+ * path the call acted on. `rename(from, to)` acted on both, and what it could not do is land the
+ * entry: `dest` first. Every other call — `link(existing, new)` and `copyfile` included, whose
+ * two arguments are both real paths either of which may be the one refused — is read `path` first.
+ *
+ * @param facts - The fault's facts, as {@link fsFaultOf} read them off the errno
+ * @returns Every path the call acted on, the one that names the fault first; empty when the errno carries none
+ */
+export function pathsActedOn(facts) {
+    const { path, dest, syscall } = facts;
+    let ordered = [path, dest];
+    if (syscall === 'symlink')
+        ordered = [dest];
+    else if (syscall === 'rename')
+        ordered = [dest, path];
+    return ordered.filter((each) => each !== undefined);
+}
+/**
+ * For a refused `rename`, the entry that was being moved — the other end of the path the fault is
+ * named by. `undefined` for every other call, and for a rename whose errno names one path only.
+ *
+ * @param facts - The fault's facts, as {@link fsFaultOf} read them off the errno
+ */
+export function movedFromOf(facts) {
+    return facts.syscall === 'rename' && facts.dest !== undefined ? facts.path : undefined;
+}
+function hasAnyErrno(error, errnos) {
+    return findCoded(error, (code) => errnos.includes(code)) !== undefined;
+}
+/**
+ * Whether `error` means **there is nothing at this path** — `ENOENT`, or `ENOTDIR`
+ * for a path whose component turned out to be a file — and nothing else. The
+ * narrowing a `try { stat(p) } catch { return null }` is rewritten to under
+ * `no-blind-catch`: only an absence may produce the sentinel; a refusal or a
+ * bug is rethrown.
+ */
+export function isPathAbsentError(error) {
+    return hasAnyErrno(error, FS_FAULT_ERRNOS_BY_CLASS.absent);
+}
+/**
+ * `ENOENT` alone: nothing at this path, with every directory above it real. For a
+ * site where `ENOTDIR` — a component that is a FILE — must stay loud, because it
+ * means a misconfiguration rather than "not there yet" ({@link isPathAbsentError}
+ * folds the two together).
+ */
+export function isNoSuchEntryError(error) {
+    return hasAnyErrno(error, ['ENOENT']);
+}
+/**
+ * `ENOTDIR` alone: a component of the path is a FILE. On a write whose layout an
+ * input decided, that is a file in the way of a directory the layout needs — a
+ * layout fault, though the class table files `ENOTDIR` under `absent` (for a read
+ * it means "nothing there").
+ */
+export function isFileInTheWayError(error) {
+    return hasAnyErrno(error, ['ENOTDIR']);
+}
+/** `EEXIST`: the exclusive create lost to something already there. */
+export function isAlreadyExistsError(error) {
+    return hasAnyErrno(error, ['EEXIST']);
+}
+/** The `occupied` class (`EEXIST`, `ENOTEMPTY`): something is in the way — a directory `rmdir` was asked to remove still holds entries. */
+export function isOccupiedError(error) {
+    return hasAnyErrno(error, FS_FAULT_ERRNOS_BY_CLASS.occupied);
+}
+/**
+ * The errnos with which the OS LOOKED and found nothing a link resolves to: the `absent` class
+ * (`ENOENT`, `ENOTDIR` — it dangles) and `ELOOP` (a cycle; on Windows
+ * `ERROR_CANT_RESOLVE_FILENAME`). On Windows a dangling link or junction is `ENOENT`. Every other
+ * errno says nothing about the link — the OS declining (`EACCES`, `EPERM`), running short
+ * (`EMFILE`, `ENOSPC`), being held (`EBUSY`), failing to look (`EIO`, `ESTALE`, `ETIMEDOUT`, the
+ * network errnos) — and so does an AMBIGUOUS one: libuv v1.x `src/win/error.c` reports
+ * `ERROR_INVALID_PARAMETER`, `ERROR_INVALID_DATA`, `ERROR_INSUFFICIENT_BUFFER` and
+ * `ERROR_SYMLINK_NOT_SUPPORTED` all as `EINVAL` (:102-105), `ERROR_BUFFER_OVERFLOW` as
+ * `ENAMETOOLONG` (:129), and every Win32 error it has no case for as `UNKNOWN` (:172) — a missing
+ * share AND refused credentials. A cause that cannot be told apart is a fault, never "nothing there".
+ */
+const UNRESOLVABLE_LINK_ERRNOS = Object.freeze([...FS_FAULT_ERRNOS_BY_CLASS.absent, 'ELOOP']);
+/**
+ * Whether resolving a link failed because **the link resolves to nothing** ({@link UNRESOLVABLE_LINK_ERRNOS}),
+ * as opposed to a fault of the OS or the operator's tree, which the caller throws for the classifier.
+ * The one answer to "does this link resolve?" for every site that follows one. `false` for an
+ * error that carries no errno.
+ */
+export function isUnresolvableLinkError(error) {
+    return hasAnyErrno(error, UNRESOLVABLE_LINK_ERRNOS);
+}
+/**
+ * `EISDIR`, `ENOTSUP`, `EOPNOTSUPP` from a NATIVE realpath (`realpathSync.native`, `fs/promises.realpath`):
+ * the volume cannot answer a final-path query, which says nothing about the path. On Windows libuv
+ * maps `ERROR_INVALID_FUNCTION` — what `GetFinalPathNameByHandleW` returns on a RAM disk or a
+ * redirector that does not implement it — to `EISDIR` (`src/win/error.c`). The answer is the JS
+ * realpath (an lstat/readlink walk), which never asks that question.
+ */
+export function isFinalPathUnanswerableError(error) {
+    return hasAnyErrno(error, ['EISDIR', 'ENOTSUP', 'EOPNOTSUPP']);
+}
+/** `ENAMETOOLONG`: a name (or path) longer than this host's filesystem will take. */
+export function isNameTooLongError(error) {
+    return hasAnyErrno(error, ['ENAMETOOLONG']);
+}
+/** `EINVAL`: the filesystem rejected the argument (e.g. `readlink` on a non-link). */
+export function isInvalidArgumentError(error) {
+    return hasAnyErrno(error, ['EINVAL']);
+}
+/** `EFTYPE`: BSD's "inappropriate file type" — a pipe, socket or device where content was expected. */
+export function isNotARegularFileError(error) {
+    return hasAnyErrno(error, ['EFTYPE']);
+}
+/** `ETIMEDOUT`: an operation (a child process given a `timeout`, a network filesystem) ran out of time. */
+export function isTimedOutError(error) {
+    return hasAnyErrno(error, ['ETIMEDOUT']);
+}
+/** `EAGAIN`: a non-blocking descriptor (stdout on a full pipe) would block. */
+export function isWouldBlockError(error) {
+    return hasAnyErrno(error, ['EAGAIN']);
+}
+/**
+ * `ESRCH` or `EPERM` from signalling a process group we created: no such group,
+ * or its id was recycled to a process we may not signal. Either way every
+ * process of ours in it has exited — the outcome the kill was after.
+ */
+export function isProcessGoneError(error) {
+    return hasAnyErrno(error, ['ESRCH', 'EPERM']);
+}
+/** This host cannot create symlinks: Windows without Developer Mode (`EPERM`), or a filesystem with none (`ENOTSUP`/`EOPNOTSUPP`). */
+export function isSymlinkUnsupportedError(error) {
+    return hasAnyErrno(error, ['EPERM', 'ENOTSUP', 'EOPNOTSUPP']);
+}
+/**
+ * A refusal a re-ask can legitimately answer differently: the `busy` class
+ * (`EBUSY`, `ETXTBSY`, `EAGAIN`), or this process out of descriptors (`EMFILE`,
+ * `ENFILE`). Disk and quota exhaustion (`ENOSPC`, `EDQUOT`) share the `exhausted`
+ * class but are NOT retryable: re-asking frees no space, so "re-run first" would
+ * be the wrong advice.
+ */
+export function isRetryableShortageError(error) {
+    return hasAnyErrno(error, [...FS_FAULT_ERRNOS_BY_CLASS.busy, 'EMFILE', 'ENFILE']);
+}
+/**
+ * The errnos Windows raises when a rename races a scanner, indexer or handle
+ * that has the tree open: `EPERM`, `EBUSY`, `EACCES`. Worth a bounded retry;
+ * anything else is final.
+ */
+export function isRenameContentionError(error) {
+    return hasAnyErrno(error, ['EPERM', 'EBUSY', 'EACCES']);
+}
+/**
+ * The `refused` class (`EACCES`, `EPERM`): the OS refused the caller's access. A
+ * removal refused this way is retried once its directories are made owner-writable:
+ * a read-only directory refuses the removal of its entries.
+ */
+export function isAccessRefusedError(error) {
+    return hasAnyErrno(error, FS_FAULT_ERRNOS_BY_CLASS.refused);
+}
+//# sourceMappingURL=errno-table.js.map

package/dist/errors/errno-table.js.map

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

package/dist/errors/fs-boundary.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `fsBoundary`: decide a fault's side from the path the OS named, against the
+ * roots each side owns. Built on the classifier (`fs-fault.ts`) and on
+ * `path-containment.ts`; it lives apart from the classifier so that the path
+ * helpers `path-containment.ts` itself imports can classify without a cycle.
+ */
+import { type FsSide, type SourceOrigin } from './fs-fault.js';
+/** The directories each side owns for one verb. */
+export interface FsRoots {
+    readonly source?: readonly string[];
+    readonly destination?: readonly string[];
+    readonly environment?: readonly string[];
+}
+/** Decides the side of a fault from the path the OS named. */
+export interface FsBoundary {
+    /** The side owning `path` (the most specific root wins), or `undefined` when it is under no root. */
+    sideOf(path: string): FsSide | undefined;
+    /** Classify an error already caught: by the path it names, else on `fallback`; a non-fs error comes back untouched. */
+    classify(error: unknown, action: string, fallback: FsSide): unknown;
+    run<T>(action: string, fallback: FsSide, work: () => Promise<T>): Promise<T>;
+    runSync<T>(action: string, fallback: FsSide, work: () => T): T;
+}
+/**
+ * Role by PATH, not by wrapper. A wrapper names the side its author had in mind;
+ * the path the failing call acted on ({@link pathsActedOn} — never a symlink's target
+ * text, and a rename's landing place first) is what actually failed, and one call routinely touches
+ * both an input and an output (a `copyFile` whose source is unreadable fails
+ * under the SOURCE root even though the wrapper says "write"). Falls back to the
+ * call's declared side only when the error names no path or the path is under no
+ * root.
+ */
+export declare function fsBoundary(roots: FsRoots, options?: {
+    origin?: SourceOrigin;
+    shapeFromSource?: boolean;
+}): FsBoundary;
+//# sourceMappingURL=fs-boundary.d.ts.map

package/dist/errors/fs-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-boundary.d.ts","sourceRoot":"","sources":["../../src/errors/fs-boundary.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAA6B,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAE1F,mDAAmD;AACnD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,qGAAqG;IACrG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,uHAAuH;IACvH,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpE,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CAChE;AA0CD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CA0DzH"}