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

package/dist/link-following.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The ONE module that asks the kernel to FOLLOW a link — `stat`, `realpath` — and the only place
+ * `local/no-link-following-fs` lets such a call stand (every other `packages/*\/src` file asks
+ * here; the allowlist of operator's-own-path files is the rule's option, asserted both ways).
+ *
+ * The order is the guarantee. A Windows kernel asked to follow a link to `\\host\share` opens an
+ * SMB session and offers the operator's NTLM credentials to that host before any answer comes
+ * back, so every following call here first reads the chain of links to its path hop by hop, by
+ * `lstat` and `readlink` alone ({@link assertLocalChain}), and asks the kernel only once the chain
+ * is read and local. On every host: the walk is the same rule everywhere, its flavor bound from
+ * `process.platform` here, at the edge.
+ *
+ * Each call names the tree its path is crawled in, `within` — the operator's own input (a project
+ * root, a directory the operator named, VAT's own scratch). That root is resolved by the kernel
+ * once, as the operator's input always was, and the walk reads only what lies beneath it: the
+ * root's ancestors are the operator's, never probed and never blamed for a fault. A path that IS
+ * the operator's own input passes itself as `within`, and the kernel answers it directly.
+ *
+ * A probe the OS refuses is never a pass: it is thrown, raw, for the caller's classifier — a read
+ * lane records it as that one path's fault, a write lane stops on its own side.
+ */
+import { type BigIntStats, type Stats } from 'node:fs';
+import { type PathFlavor } from './tree-change/link-chain.js';
+/**
+ * The kernel's realpath of the operator's OWN path (an edge: a root the operator named, VAT's own
+ * scratch), in the host's separators — the one place the kernel follows a link no walk read.
+ *
+ * @throws The resolution's own error: the caller classifies it
+ */
+export declare function edgeRealpathSync(path: string): string;
+/**
+ * Throw unless every link on the way to `path` beneath `within` has been read and leads somewhere
+ * local — the check the kernel's following call is the SECOND lock behind. The user's own paths:
+ * an absolute local text is followed and walked by the same rules, so a later hop's network text
+ * is still caught. A chain that leads to nothing (a dangle, a cycle) is answered so — the kernel is
+ * not asked about it.
+ *
+ * @param path - Absolute, or relative to cwd; either separator
+ * @param within - The tree `path` is crawled in: the operator's own input (or `path` itself, for the operator's own path)
+ * @param flavor - Whose kernel is about to be asked: bound from `process.platform` at the edge
+ * @returns `'local'` when the kernel may now be asked; `'nothing'` when the chain leads to nothing
+ * @throws LinkChainRefusedError when a link on the way names a network or device path, or the chain
+ *   never ends; the raw errno of an `lstat`/`readlink` (or the root's realpath) the OS refused
+ */
+export declare function assertLocalChain(path: string, within: string, flavor: PathFlavor): 'local' | 'nothing';
+/**
+ * Throw what the kernel's own `syscall` would have thrown for a chain that leads to nothing — `ENOENT`
+ * for a dangle, `ELOOP` for a cycle — so the caller's classifier reads it as it always did; return
+ * when the chain is read, local, and the kernel may be asked.
+ */
+export declare function requireSomethingAt(path: string, within: string, syscall: string): void;
+/**
+ * The native realpath of a path crawled beneath `within` — the canonical ON-DISK spelling,
+ * forward-slashed — asked of the kernel only once the chain is read and local.
+ *
+ * @throws LinkChainRefusedError for a chain through a network path, or one that never ends; the
+ *   `ENOENT` of a chain that leads to nothing; else the resolution's own error — the caller classifies it
+ */
+export declare function realpathNativeSync(path: string, within: string): string;
+/** The asynchronous {@link realpathNativeSync}. */
+export declare function realpathNative(path: string, within: string): Promise<string>;
+/**
+ * Node's JS realpath (`fs.realpath`, not `.native`: the spelling the caller wrote is kept, so it
+ * stays in the namespace of a lexical fallback) of a path crawled beneath `within`, asked only once
+ * the chain is read and local. Read off the `node:fs` default object per call, so a spy installed
+ * after import still sees it.
+ *
+ * @throws as {@link realpathNativeSync}
+ */
+export declare function followedRealpath(path: string, within: string): Promise<string>;
+/** The synchronous {@link followedRealpath} (`fs.realpathSync`, the JS walk). */
+export declare function followedRealpathSync(path: string, within: string): string;
+/**
+ * The kernel's `stat` of the operator's OWN path (an edge: the base a crawl was asked to start
+ * from), raw: the caller classifies its error.
+ */
+export declare function edgeStatSync(path: string): Stats;
+/** {@link edgeStatSync} with `bigint` fields — the `dev`/`ino` an entry identity is built from. */
+export declare function edgeBigintStatSync(path: string): BigIntStats;
+/**
+ * What `path` (crawled beneath `within`) resolves to, its links followed — `undefined` when it
+ * resolves to nothing: absent, a dangling link, a cycle, or a chain the kernel itself calls a loop.
+ *
+ * @throws LinkChainRefusedError for a chain VAT will not hand the kernel; the raw errno of any probe
+ *   the OS refused (never folded into "absent")
+ */
+export declare function followedStatSync(path: string, within: string): Stats | undefined;
+/** The asynchronous {@link followedStatSync}. */
+export declare function followedStat(path: string, within: string): Promise<Stats | undefined>;
+/**
+ * {@link followedStatSync} for a caller that cannot go on without an answer: a path that resolves
+ * to nothing is the `ENOENT` (or, for a cycle, `ELOOP`) the kernel's own `stat` would have thrown,
+ * for the caller's classifier.
+ */
+export declare function requireFollowedStatSync(path: string, within: string): Stats;
+/** The asynchronous {@link requireFollowedStatSync}. */
+export declare function requireFollowedStat(path: string, within: string): Promise<Stats>;
+/**
+ * The `type` a link made to copy the link at `path` (crawled beneath `within`) is created with —
+ * `'dir'` when its chain, read by text, ends at a directory; `'file'` otherwise, a dangle or a cycle
+ * included (what Node itself picks for a target it cannot `stat`). Read by `lstat` and `readlink`
+ * alone: a `symlink` with no type has Node on Windows ask the KERNEL to follow the target to pick
+ * one, and a link text no walk read must never reach the kernel.
+ *
+ * @throws LinkChainRefusedError for a chain through a network or device path, or one that never
+ *   ends; the raw errno of an `lstat`/`readlink` the OS refused
+ */
+export declare function linkCopyType(path: string, within: string): 'dir' | 'file';
+/** What a followed path resolves to. */
+export type FollowedPathKind = 'directory' | 'file' | 'other' | 'absent';
+/** What `path` beneath `within` resolves to ({@link followedStatSync}): `absent` for nothing. */
+export declare function followedKindSync(path: string, within: string): FollowedPathKind;
+/** The asynchronous {@link followedKindSync}. */
+export declare function followedKind(path: string, within: string): Promise<FollowedPathKind>;
+//# sourceMappingURL=link-following.d.ts.map

package/dist/link-following.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-following.d.ts","sourceRoot":"","sources":["../src/link-following.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAe,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAO/D,OAAO,EAAmD,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAwB/G;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOrD;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,CAEtG;AASD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKtF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGvE;AAED,mDAAmD;AACnD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlF;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpF;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAEhD;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAQhF;AAED,iDAAiD;AACjD,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAQ3F;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAG3E;AAED,wDAAwD;AACxD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAGtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAMzE;AAED,wCAAwC;AACxC,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAQzE,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAE/E;AAED,iDAAiD;AACjD,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAE1F"}

package/dist/link-following.js

@@ -0,0 +1,283 @@
+/**
+ * The ONE module that asks the kernel to FOLLOW a link — `stat`, `realpath` — and the only place
+ * `local/no-link-following-fs` lets such a call stand (every other `packages/*\/src` file asks
+ * here; the allowlist of operator's-own-path files is the rule's option, asserted both ways).
+ *
+ * The order is the guarantee. A Windows kernel asked to follow a link to `\\host\share` opens an
+ * SMB session and offers the operator's NTLM credentials to that host before any answer comes
+ * back, so every following call here first reads the chain of links to its path hop by hop, by
+ * `lstat` and `readlink` alone ({@link assertLocalChain}), and asks the kernel only once the chain
+ * is read and local. On every host: the walk is the same rule everywhere, its flavor bound from
+ * `process.platform` here, at the edge.
+ *
+ * Each call names the tree its path is crawled in, `within` — the operator's own input (a project
+ * root, a directory the operator named, VAT's own scratch). That root is resolved by the kernel
+ * once, as the operator's input always was, and the walk reads only what lies beneath it: the
+ * root's ancestors are the operator's, never probed and never blamed for a fault. A path that IS
+ * the operator's own input passes itself as `within`, and the kernel answers it directly.
+ *
+ * A probe the OS refuses is never a pass: it is thrown, raw, for the caller's classifier — a read
+ * lane records it as that one path's fault, a write lane stops on its own side.
+ */
+// Every kernel call is reached through the DEFAULT objects, never a named binding: Node snapshots a
+// builtin's named ESM exports at import time, so a `vi.spyOn(fs, 'statSync')` cannot see a call made
+// through one — it attaches, counts zero, and reads exactly like "no I/O here" (the guards on
+// `pathSpellingFrom`/`realpathRowFrom` and the fault matrix are assertions of exactly that).
+import nodeFs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { isFinalPathUnanswerableError, isPathAbsentError, isUnresolvableLinkError } from './errors/errno-table.js';
+import { relativeEscapesRoot, safePath, toForwardSlash } from './path-core.js';
+import { LinkChainRefusedError, walkHostChain } from './tree-change/host-chain.js';
+import { HOST_PATH_FLAVOR, namedPathRoot } from './tree-change/link-chain.js';
+/**
+ * Whether a native realpath's failure must be asked again of Node's JS realpath before anyone
+ * believes it — the ONE fallback rule every native site shares.
+ *
+ * - A volume whose driver does not implement final-path queries (a RAM disk, some redirectors and
+ *   virtual drives) answers EVERY native realpath with `ERROR_INVALID_FUNCTION`, which libuv
+ *   reports as `EISDIR` ({@link isFinalPathUnanswerableError}). That says nothing about the path.
+ * - An absent answer ({@link isPathAbsentError}) is confirmed by the JS walk: on a musl libc
+ *   without procfs the native `realpath(3)` reports `ENOENT` for a path that exists, and Windows
+ *   answers `ENOENT` for a file on a volume mounted into a folder with no drive letter (pinned on a
+ *   real host by `realpath-native-folder-mount.integration.test.ts`). A path the JS walk also finds
+ *   absent throws the walk's own `ENOENT`, so nothing that is really missing reads as present.
+ *
+ * ⚠️ The JS answer is not the on-disk spelling: it keeps the casing the caller spelled (and, on
+ * Windows, an 8.3 short name), and it expands only what `lstat` calls a link — a `subst` drive and
+ * a volume mount point (which libuv reports as a plain directory) stay as spelled. A caller that
+ * needs the kernel's own identity compares `stat` identities, not these strings.
+ */
+function nativeAnswerNeedsJsWalk(error) {
+    return isFinalPathUnanswerableError(error) || isPathAbsentError(error);
+}
+/**
+ * The kernel's realpath of the operator's OWN path (an edge: a root the operator named, VAT's own
+ * scratch), in the host's separators — the one place the kernel follows a link no walk read.
+ *
+ * @throws The resolution's own error: the caller classifies it
+ */
+export function edgeRealpathSync(path) {
+    try {
+        return nodeFs.realpathSync.native(path);
+    }
+    catch (error) {
+        if (!nativeAnswerNeedsJsWalk(error))
+            throw error;
+        return nodeFs.realpathSync(path);
+    }
+}
+/**
+ * Read the chain to `path`, hop by hop, beneath the tree `within`.
+ *
+ * - `path` is `within` itself: the operator's own input, answered by the kernel (`edge`).
+ * - `path` lies beneath `within`: the walk starts at `within`'s real path and reads only the
+ *   components below it — never the root's own ancestors.
+ * - `path` lies outside `within` (a link target named by content, a path a caller built): the whole
+ *   of it is walked from its own root, ancestors included, as any link target is.
+ */
+function walkWithin(path, within, flavor) {
+    const start = toForwardSlash(safePath.resolve(path));
+    const root = toForwardSlash(safePath.resolve(within));
+    const below = safePath.relative(root, start);
+    if (below === '')
+        return { kind: 'edge' };
+    if (relativeEscapesRoot(below))
+        return walkWhole(start, flavor);
+    let real;
+    try {
+        real = realRootOf(root);
+    }
+    catch (error) {
+        // Nothing is beneath a root that is not there.
+        if (isPathAbsentError(error))
+            return { kind: 'nothing', at: root, cause: 'absent' };
+        throw error;
+    }
+    return walkHostChain(safePath.join(real, below), { flavor, root: real, outside: 'follow' });
+}
+/** The whole chain to `start` (forward-slashed, absolute), ancestors included, from the root it hangs from. */
+function walkWhole(start, flavor) {
+    return walkHostChain(start, { flavor, root: namedPathRoot(start, flavor), outside: 'follow' });
+}
+/**
+ * Each tree root's real path, resolved by the kernel ONCE per process — at the edge, as the operator's
+ * input always was — not once per path crawled beneath it. Only an answer is kept: a root the OS
+ * refused, or one not there yet, is asked again next time.
+ */
+const REAL_ROOTS = new Map();
+function realRootOf(root) {
+    const known = REAL_ROOTS.get(root);
+    if (known !== undefined)
+        return known;
+    const real = toForwardSlash(edgeRealpathSync(root));
+    REAL_ROOTS.set(root, real);
+    return real;
+}
+/**
+ * Throw unless every link on the way to `path` beneath `within` has been read and leads somewhere
+ * local — the check the kernel's following call is the SECOND lock behind. The user's own paths:
+ * an absolute local text is followed and walked by the same rules, so a later hop's network text
+ * is still caught. A chain that leads to nothing (a dangle, a cycle) is answered so — the kernel is
+ * not asked about it.
+ *
+ * @param path - Absolute, or relative to cwd; either separator
+ * @param within - The tree `path` is crawled in: the operator's own input (or `path` itself, for the operator's own path)
+ * @param flavor - Whose kernel is about to be asked: bound from `process.platform` at the edge
+ * @returns `'local'` when the kernel may now be asked; `'nothing'` when the chain leads to nothing
+ * @throws LinkChainRefusedError when a link on the way names a network or device path, or the chain
+ *   never ends; the raw errno of an `lstat`/`readlink` (or the root's realpath) the OS refused
+ */
+export function assertLocalChain(path, within, flavor) {
+    return nothingOnTheWay(path, within, flavor) === undefined ? 'local' : 'nothing';
+}
+/** {@link assertLocalChain}, naming why a chain leads to nothing: `undefined` when the kernel may be asked. */
+function nothingOnTheWay(path, within, flavor) {
+    const walked = walkWithin(path, within, flavor);
+    if (walked.kind === 'refused')
+        throw new LinkChainRefusedError(path, walked.refusal);
+    return walked.kind === 'nothing' ? walked.cause : undefined;
+}
+/**
+ * Throw what the kernel's own `syscall` would have thrown for a chain that leads to nothing — `ENOENT`
+ * for a dangle, `ELOOP` for a cycle — so the caller's classifier reads it as it always did; return
+ * when the chain is read, local, and the kernel may be asked.
+ */
+export function requireSomethingAt(path, within, syscall) {
+    const cause = nothingOnTheWay(path, within, HOST_PATH_FLAVOR);
+    if (cause === undefined)
+        return;
+    const [code, words] = cause === 'cycle' ? ['ELOOP', 'too many symbolic links encountered'] : ['ENOENT', 'no such file or directory'];
+    throw Object.assign(new Error(`${code}: ${words}, ${syscall} '${path}'`), { code, syscall, path });
+}
+/**
+ * The native realpath of a path crawled beneath `within` — the canonical ON-DISK spelling,
+ * forward-slashed — asked of the kernel only once the chain is read and local.
+ *
+ * @throws LinkChainRefusedError for a chain through a network path, or one that never ends; the
+ *   `ENOENT` of a chain that leads to nothing; else the resolution's own error — the caller classifies it
+ */
+export function realpathNativeSync(path, within) {
+    requireSomethingAt(path, within, 'realpath');
+    return toForwardSlash(edgeRealpathSync(path));
+}
+/** The asynchronous {@link realpathNativeSync}. */
+export async function realpathNative(path, within) {
+    requireSomethingAt(path, within, 'realpath');
+    try {
+        return toForwardSlash(await promisify(nodeFs.realpath.native)(path));
+    }
+    catch (error) {
+        if (!nativeAnswerNeedsJsWalk(error))
+            throw error;
+        return toForwardSlash(await promisify(nodeFs.realpath)(path));
+    }
+}
+/**
+ * Node's JS realpath (`fs.realpath`, not `.native`: the spelling the caller wrote is kept, so it
+ * stays in the namespace of a lexical fallback) of a path crawled beneath `within`, asked only once
+ * the chain is read and local. Read off the `node:fs` default object per call, so a spy installed
+ * after import still sees it.
+ *
+ * @throws as {@link realpathNativeSync}
+ */
+export async function followedRealpath(path, within) {
+    requireSomethingAt(path, within, 'realpath');
+    return await promisify(nodeFs.realpath)(path);
+}
+/** The synchronous {@link followedRealpath} (`fs.realpathSync`, the JS walk). */
+export function followedRealpathSync(path, within) {
+    requireSomethingAt(path, within, 'realpath');
+    return nodeFs.realpathSync(path);
+}
+/**
+ * The kernel's `stat` of the operator's OWN path (an edge: the base a crawl was asked to start
+ * from), raw: the caller classifies its error.
+ */
+export function edgeStatSync(path) {
+    return nodeFs.statSync(path);
+}
+/** {@link edgeStatSync} with `bigint` fields — the `dev`/`ino` an entry identity is built from. */
+export function edgeBigintStatSync(path) {
+    return nodeFs.statSync(path, { bigint: true });
+}
+/**
+ * What `path` (crawled beneath `within`) resolves to, its links followed — `undefined` when it
+ * resolves to nothing: absent, a dangling link, a cycle, or a chain the kernel itself calls a loop.
+ *
+ * @throws LinkChainRefusedError for a chain VAT will not hand the kernel; the raw errno of any probe
+ *   the OS refused (never folded into "absent")
+ */
+export function followedStatSync(path, within) {
+    if (assertLocalChain(path, within, HOST_PATH_FLAVOR) === 'nothing')
+        return undefined;
+    try {
+        return nodeFs.statSync(path);
+    }
+    catch (error) {
+        if (isUnresolvableLinkError(error))
+            return undefined;
+        throw error;
+    }
+}
+/** The asynchronous {@link followedStatSync}. */
+export async function followedStat(path, within) {
+    if (assertLocalChain(path, within, HOST_PATH_FLAVOR) === 'nothing')
+        return undefined;
+    try {
+        return await fsPromises.stat(path);
+    }
+    catch (error) {
+        if (isUnresolvableLinkError(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * {@link followedStatSync} for a caller that cannot go on without an answer: a path that resolves
+ * to nothing is the `ENOENT` (or, for a cycle, `ELOOP`) the kernel's own `stat` would have thrown,
+ * for the caller's classifier.
+ */
+export function requireFollowedStatSync(path, within) {
+    requireSomethingAt(path, within, 'stat');
+    return nodeFs.statSync(path);
+}
+/** The asynchronous {@link requireFollowedStatSync}. */
+export async function requireFollowedStat(path, within) {
+    requireSomethingAt(path, within, 'stat');
+    return await fsPromises.stat(path);
+}
+/**
+ * The `type` a link made to copy the link at `path` (crawled beneath `within`) is created with —
+ * `'dir'` when its chain, read by text, ends at a directory; `'file'` otherwise, a dangle or a cycle
+ * included (what Node itself picks for a target it cannot `stat`). Read by `lstat` and `readlink`
+ * alone: a `symlink` with no type has Node on Windows ask the KERNEL to follow the target to pick
+ * one, and a link text no walk read must never reach the kernel.
+ *
+ * @throws LinkChainRefusedError for a chain through a network or device path, or one that never
+ *   ends; the raw errno of an `lstat`/`readlink` the OS refused
+ */
+export function linkCopyType(path, within) {
+    const walked = walkWithin(path, within, HOST_PATH_FLAVOR);
+    // The link IS the tree's root: its chain is walked whole, from its own root, as any link target is.
+    const chain = walked.kind === 'edge' ? walkWhole(toForwardSlash(safePath.resolve(path)), HOST_PATH_FLAVOR) : walked;
+    if (chain.kind === 'refused')
+        throw new LinkChainRefusedError(path, chain.refusal);
+    return chain.kind === 'resolved' && chain.final === 'directory' ? 'dir' : 'file';
+}
+function kindOf(stats) {
+    if (stats === undefined)
+        return 'absent';
+    if (stats.isDirectory())
+        return 'directory';
+    return stats.isFile() ? 'file' : 'other';
+}
+/** What `path` beneath `within` resolves to ({@link followedStatSync}): `absent` for nothing. */
+export function followedKindSync(path, within) {
+    return kindOf(followedStatSync(path, within));
+}
+/** The asynchronous {@link followedKindSync}. */
+export async function followedKind(path, within) {
+    return kindOf(await followedStat(path, within));
+}
+//# sourceMappingURL=link-following.js.map

package/dist/link-following.js.map

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

package/dist/listing-refusal.d.ts

@@ -17,6 +17,7 @@
  * its stderr without a word); and the miss surfaced one review round later as
  * a HIGH. A required field is what makes `tsc` enumerate the callers.
  */
+import { type FsSide } from './errors/fs-fault.js';
 import { VatError } from './errors/vat-error.js';
 import { type DirectoryRefusal } from './fs-utils.js';
 /**
@@ -38,6 +39,15 @@ export interface RefuseListingContext {
      * differs per caller and is why the crawler cannot supply it.
      */
     remedy: string;
+    /**
+     * Which side of the calling verb the listed directories are on — an input it reads
+     * (`source`), an output it wrote (`destination`), or VAT's own scratch (`environment`).
+     * Required: the refusal table decides the refusal by it, and only the caller knows which
+     * tree it is listing. In a CRAWL, a directory that is (or lies in, or holds) one of the
+     * crawl's declared `outputs` is the destination's whatever this says: the crawl's
+     * `outputs` are the one declaration of what the verb writes ({@link settleCrawlRefusal}).
+     */
+    side: FsSide;
 }
 /**
  * The caller's decision about a directory the listing cannot open.
@@ -64,6 +74,13 @@ export type UnreadablePolicy = {
 /**
  * Thrown by a listing under `{ refuse }` when a directory refused to be
  * listed. The message is the adopter's sentence — see {@link refusedListingMessage}.
+ *
+ * Coded `FS_FAULT` and carrying the classified fault as its `cause` (side from
+ * the caller's context, class from the errno), so the refusal is the schema
+ * table's for that side and class — never a code of its own. A refused listing
+ * is a filesystem call's refusal by construction, so every errno has a class:
+ * one the table does not list is the unlisted class, as {@link fsFaultOf}
+ * answers for the error it came from.
  */
 export declare class DirectoryListingRefusedError extends VatError {
     readonly refusal: DirectoryRefusal;
@@ -94,6 +111,33 @@ export declare function refusedListingMessage(refusal: DirectoryRefusal, context
  * @param refusal - The directory that could not be listed
  */
 export declare function settleRefusal(policy: UnreadablePolicy, refusal: DirectoryRefusal): void;
+/**
+ * Whether `path` is on what a crawl's verb WRITES: one of its `outputs`, inside one, or holding
+ * one (the crawl base of a project a build writes into holds its output). THE one place a
+ * crawl derives a side from its `outputs` — the base `stat`, a refused listing at the base or
+ * beneath it, on every route. Paths are compared canonically (`canonicalPath`: real path, one
+ * spelling), so a directory git reports under its real path (`/private/var` for `/var`) or
+ * another drive-letter case is still the output.
+ *
+ * @param path - A directory the crawl met
+ * @param outputs - The trees the calling verb writes, `[]` for a verb that only reads
+ */
+export declare function onCrawlOutput(path: string, outputs: readonly string[]): boolean;
+/**
+ * The side of a path a crawl met: the destination's when it is on the verb's `outputs`
+ * ({@link onCrawlOutput}), else the side of the tree the verb reads — the policy's own
+ * (`source` when the policy degrades).
+ */
+export declare function crawlSideOf(path: string, outputs: readonly string[], policy: UnreadablePolicy): FsSide;
+/**
+ * Settle one refusal a CRAWL met: a refused directory that is on the crawl's `outputs`
+ * ({@link onCrawlOutput}) is the destination's; any other keeps the policy's own side.
+ *
+ * @param policy - The caller's decision
+ * @param refusal - The directory that could not be listed
+ * @param outputs - The trees the calling verb writes (the crawl's one declaration of them)
+ */
+export declare function settleCrawlRefusal(policy: UnreadablePolicy, refusal: DirectoryRefusal, outputs: readonly string[]): void;
 /**
  * Refuse an omitted policy up front, by name, before any directory is listed.
  *

package/dist/listing-refusal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listing-refusal.d.ts","sourceRoot":"","sources":["../src/listing-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,eAAe,CAAC;AAG9E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;CAAE,CAAC;AAE9D;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,QAAQ;IACxD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;gBAEvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB;CAIrE;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAOtG;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAGvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,gBAAgB,CAO7H"}
+{"version":3,"file":"listing-refusal.d.ts","sourceRoot":"","sources":["../src/listing-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,eAAe,CAAC;AAK9E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;CAAE,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,qBAAa,4BAA6B,SAAQ,QAAQ;IACxD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;gBAEvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB;CAIrE;AAgCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAOtG;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAGvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAO/E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAGtG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAGxH;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,gBAAgB,CAO7H"}

package/dist/listing-refusal.js

@@ -17,20 +17,43 @@
  * its stderr without a word); and the miss surfaced one review round later as
  * a HIGH. A required field is what makes `tsc` enumerate the callers.
  */
+import { filesystemErrnoClass, fsFaultOf } from './errors/errno-table.js';
+import { FS_FAULT_CODE, FsFaultError } from './errors/fs-fault.js';
 import { VatError } from './errors/vat-error.js';
 import { transientRefusalClause } from './fs-utils.js';
+import { canonicalPath } from './path-containment.js';
+import { relativeEscapesRoot } from './path-core.js';
 import { safePath, toForwardSlash } from './path-utils.js';
 /**
  * Thrown by a listing under `{ refuse }` when a directory refused to be
  * listed. The message is the adopter's sentence — see {@link refusedListingMessage}.
+ *
+ * Coded `FS_FAULT` and carrying the classified fault as its `cause` (side from
+ * the caller's context, class from the errno), so the refusal is the schema
+ * table's for that side and class — never a code of its own. A refused listing
+ * is a filesystem call's refusal by construction, so every errno has a class:
+ * one the table does not list is the unlisted class, as {@link fsFaultOf}
+ * answers for the error it came from.
  */
 export class DirectoryListingRefusedError extends VatError {
     refusal;
     constructor(refusal, context) {
-        super('DIRECTORY_LISTING_REFUSED', refusedListingMessage(refusal, context));
+        super(FS_FAULT_CODE, refusedListingMessage(refusal, context), { cause: classifiedListingFault(refusal, context.side) });
         this.refusal = refusal;
     }
 }
+/** The classified fault a refused listing stands for. */
+function classifiedListingFault(refusal, side) {
+    return new FsFaultError({
+        side,
+        faultClass: filesystemErrnoClass(refusal.code),
+        errno: refusal.code,
+        path: refusal.directory,
+        origin: 'content',
+        action: 'list a directory',
+        cause: undefined,
+    });
+}
 /**
  * What a refused listing costs, said so it is true on BOTH routes.
  *
@@ -82,6 +105,60 @@ export function settleRefusal(policy, refusal) {
         throw new DirectoryListingRefusedError(refusal, policy.refuse);
     policy.degrade(refusal);
 }
+/**
+ * Whether `path` is on what a crawl's verb WRITES: one of its `outputs`, inside one, or holding
+ * one (the crawl base of a project a build writes into holds its output). THE one place a
+ * crawl derives a side from its `outputs` — the base `stat`, a refused listing at the base or
+ * beneath it, on every route. Paths are compared canonically (`canonicalPath`: real path, one
+ * spelling), so a directory git reports under its real path (`/private/var` for `/var`) or
+ * another drive-letter case is still the output.
+ *
+ * @param path - A directory the crawl met
+ * @param outputs - The trees the calling verb writes, `[]` for a verb that only reads
+ */
+export function onCrawlOutput(path, outputs) {
+    if (outputs.length === 0)
+        return false;
+    const at = canonicalOrSpelled(path);
+    return outputs.some((output) => {
+        const out = canonicalOrSpelled(output);
+        return !relativeEscapesRoot(safePath.relative(out, at)) || !relativeEscapesRoot(safePath.relative(at, out));
+    });
+}
+/**
+ * The side of a path a crawl met: the destination's when it is on the verb's `outputs`
+ * ({@link onCrawlOutput}), else the side of the tree the verb reads — the policy's own
+ * (`source` when the policy degrades).
+ */
+export function crawlSideOf(path, outputs, policy) {
+    if (onCrawlOutput(path, outputs))
+        return 'destination';
+    return 'refuse' in policy ? policy.refuse.side : 'source';
+}
+/**
+ * Settle one refusal a CRAWL met: a refused directory that is on the crawl's `outputs`
+ * ({@link onCrawlOutput}) is the destination's; any other keeps the policy's own side.
+ *
+ * @param policy - The caller's decision
+ * @param refusal - The directory that could not be listed
+ * @param outputs - The trees the calling verb writes (the crawl's one declaration of them)
+ */
+export function settleCrawlRefusal(policy, refusal, outputs) {
+    const onOutput = 'refuse' in policy && onCrawlOutput(refusal.directory, outputs);
+    settleRefusal(onOutput ? { refuse: { ...policy.refuse, side: 'destination' } } : policy, refusal);
+}
+function canonicalOrSpelled(path) {
+    try {
+        // The refused directory and the verb's outputs are spelled by the verb: each is its own edge.
+        return toForwardSlash(canonicalPath(path, path));
+    }
+    catch (error) {
+        // A directory that refused its listing may refuse resolution too: its spelling is all there is.
+        if (fsFaultOf(error) === undefined)
+            throw error;
+        return toForwardSlash(safePath.resolve(path));
+    }
+}
 /**
  * Refuse an omitted policy up front, by name, before any directory is listed.
  *
@@ -98,7 +175,7 @@ export function settleRefusal(policy, refusal) {
  */
 export function requireUnreadablePolicy(policy, api) {
     if (policy === undefined) {
-        throw new TypeError(`${api}: \`unreadable\` is required — pass { refuse: { root, remedy } } to stop on a directory the listing cannot open, ` +
+        throw new TypeError(`${api}: \`unreadable\` is required — pass { refuse: { root, remedy, side } } to stop on a directory the listing cannot open, ` +
             'or { degrade: (refusal) => … } to keep going and report the gap yourself.');
     }
 }

package/dist/listing-refusal.js.map

@@ -1 +1 @@
-{"version":3,"file":"listing-refusal.js","sourceRoot":"","sources":["../src/listing-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAyB,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA4C3D;;;GAGG;AACH,MAAM,OAAO,4BAA6B,SAAQ,QAAQ;IAC/C,OAAO,CAAmB;IAEnC,YAAY,OAAyB,EAAE,OAA6B;QAClE,KAAK,CAAC,2BAA2B,EAAE,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,kBAAkB,GACtB,8EAA8E;IAC9E,mDAAmD,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAyB,EAAE,OAA6B;IAC5F,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IACpF,MAAM,KAAK,GAAG,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,kBAAkB,QAAQ,GAAG,CAAC;IACvF,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS;QAC9B,CAAC,CAAC,GAAG,sBAAsB,CAAC,OAAO,CAAC,IAAI,CAAC,6EAA6E;QACtH,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACnB,OAAO,WAAW,KAAK,iBAAiB,OAAO,CAAC,IAAI,MAAM,kBAAkB,KAAK,MAAM,EAAE,CAAC;AAC5F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAwB,EAAE,OAAyB;IAC/E,IAAI,QAAQ,IAAI,MAAM;QAAE,MAAM,IAAI,4BAA4B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACvF,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAoC,EAAE,GAAW;IACvF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,SAAS,CACjB,GAAG,GAAG,mHAAmH;YACvH,2EAA2E,CAC9E,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"listing-refusal.js","sourceRoot":"","sources":["../src/listing-refusal.ts"],"names":[],"mappings":"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"}

package/dist/name-fold.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One path segment as the strictest volume VAT writes onto compares it. Pure.
+ *
+ * Two segments with one fold are ONE entry on some volume, so a set of names holding both lands
+ * differently depending on where it is written — an archive's entry list and a plugin's `files:`
+ * destinations are both judged by it.
+ */
+/**
+ * A path segment as a filesystem that folds names compares it: the stream suffix and trailing dots
+ * and spaces cut (NTFS), decomposed, then case-folded UP and then down — NTFS compares upper-cased
+ * names, so `ß` and `SS` are one name, and a dotless `ı` (U+0131) is `I` there, which lower-casing
+ * alone leaves apart from `i`. The cut is made on every host, so a POSIX directory really named
+ * `skills:notes` compares as `skills` too.
+ *
+ * STRICTER than any one volume, on purpose. The decomposition is by compatibility (NFKD), where
+ * the volumes that normalise (APFS, HFS+) do so canonically: `x².md` and `x2.md` fold together
+ * here and are two names everywhere. And the stream cut makes `10:00.log` and `10:30.log` one
+ * name, which they are only on NTFS. A caller that refuses on equal folds over-refuses those, and
+ * says which rule matched.
+ *
+ * @param segment - One path segment, never a path
+ * @returns The segment's fold: equal for two names that are one entry on some volume
+ */
+export declare function foldedSegment(segment: string): string;
+//# sourceMappingURL=name-fold.d.ts.map