@vibe-agent-toolkit/utils 0.2.0-rc.6 → 0.2.0-rc.8

package/dist/env-flag.js

@@ -0,0 +1,57 @@
+/**
+ * Read an environment variable as a boolean.
+ *
+ * 🔑 **Returns `undefined` for anything it does not recognise, and never
+ * guesses.** That is the whole point: the caller — not this function — decides
+ * what an unreadable value means, because only the caller knows which way is
+ * safe. A token-fetching kill switch wants "deny"; a cache toggle wants
+ * "leave the cache on". A parser that folded the unknown case into `false`
+ * would have made that choice for both of them.
+ *
+ * 🚨 **Why this exists at all.** Three switches were each a comparison against
+ * the literal string `'0'`, so `=false` turned none of them off — measured for
+ * `VAT_LINKAUTH_ALLOW_COMMAND`, which *still spawned subprocesses*. Every
+ * spelling a human reaches for (`false`, `no`, `off`, `FALSE`, a value with a
+ * stray space) failed open. A switch whose off position is one exact string is
+ * not a switch.
+ *
+ * 📍 **Why it lives in `utils`.** It was written next to its first consumer in
+ * `resources`, on the rule that utils takes a utility when a SECOND package
+ * needs it rather than speculatively. That second package arrived:
+ * `packages/cli`'s `projectionStoreSelected()` reads the same `VAT_CACHE` the
+ * `resources` parse cache does, and two independent readings of one variable is
+ * the defect, not the fix. The three consumers today:
+ *
+ * | Caller | Variable | Reads `undefined` as | Why |
+ * |---|---|---|---|
+ * | `link-auth/resolve-token.ts` | `VAT_LINKAUTH_ALLOW_COMMAND` | **deny** | gates a capability — fail closed |
+ * | `resources/parse-cache.ts` | `VAT_CACHE` | cache stays on | gates a cache — an unreadable value must not silently change behaviour |
+ * | `cli/utils/projection-store.ts` | `VAT_CACHE` | not a veto | same variable, same reading, one implementation |
+ *
+ * Same parser, different safe sides, each chosen at its own call site. That is
+ * the contract; do not move a default in here.
+ */
+const TRUE_SPELLINGS = new Set(['1', 'true', 'yes', 'y', 'on']);
+const FALSE_SPELLINGS = new Set(['0', 'false', 'no', 'n', 'off']);
+/**
+ * Parse an env value as a boolean.
+ *
+ * Case-insensitive and surrounding whitespace is trimmed, because a value that
+ * arrived through a shell, a CI YAML block, or a `.env` file routinely carries
+ * both. Everything else — including the empty string, which is what an unset
+ * shell variable expands to — returns `undefined`.
+ *
+ * @param raw - The raw env value, or `undefined` when the variable is unset
+ * @returns `true` / `false` for a recognised spelling; `undefined` otherwise
+ */
+export function parseEnvBoolean(raw) {
+    if (raw === undefined)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (TRUE_SPELLINGS.has(normalized))
+        return true;
+    if (FALSE_SPELLINGS.has(normalized))
+        return false;
+    return undefined;
+}
+//# sourceMappingURL=env-flag.js.map

package/dist/env-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-flag.js","sourceRoot":"","sources":["../src/env-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AACrF,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAEvF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/errors/errno.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Errno predicates — the two questions every catch site asks of an OS error,
+ * answered by the `code` on the error or down its `cause` chain.
+ *
+ * ⚠️ This module imports NOTHING. It is the leaf that `fs-utils.ts`,
+ * `path-utils.ts`, `dirent-kind.ts`, `path-containment.ts` and the rest of the
+ * package share; it lived in `fs-utils.ts` until that put three of them in an
+ * import cycle (`fs-utils → path-utils → fs-utils` and two more), and a leaf
+ * is the one place a shared predicate cannot re-open one. (The cycle was once
+ * blamed for a platform-dependent knip verdict on these two names; breaking it
+ * changed nothing there — the cause was a missing knip entry, see
+ * `docs/contributing/traps.md`, "A subpath module's re-exports flap by platform".)
+ */
+/**
+ * Whether `error` is the filesystem refusing a path rather than a bug.
+ *
+ * Deliberately NOT `error instanceof Error`: the point of every caller is to
+ * degrade on a hostile tree, and a `TypeError` from a validator is not that.
+ * Treating one as environmental turns a real defect into a warning about
+ * whichever file it happened on — which makes a tool quietest exactly when it is
+ * most wrong.
+ *
+ * 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: …')`;
+ * without following the chain the predicate answered "not a filesystem error" for
+ * a plain `EACCES`, and an unreadable config aborted a whole `vat audit` run. Any
+ * layer that adds context to an OS error defeats a `code`-only check, so the check
+ * cannot be `code`-only.
+ */
+export declare function isFilesystemAccessError(error: unknown): boolean;
+/**
+ * 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.
+ *
+ * This is the narrowing a `try { stat(p) } catch { return null }` is rewritten
+ * to under the `no-blind-catch` lint rule: the sentinel stands for *absent*,
+ * so only an absence may produce it; a refusal (`EACCES`, `EPERM`, `ELOOP`) or
+ * a bug (`TypeError`) is rethrown and stays loud.
+ *
+ * ⚠️ Deliberately NOT {@link isFilesystemAccessError}. That predicate answers
+ * "is this the environment's fault?" and to answer it groups `ENOENT` with
+ * `EACCES` — the exact conflation that once turned an unreadable directory
+ * into an empty one. The two questions have two predicates on purpose; see
+ * also {@link listingFailure}, which makes the same split for `readdir`.
+ *
+ * Walks `cause` for the same reason its sibling does: the errno is routinely
+ * re-wrapped on its way up.
+ */
+export declare function isPathAbsentError(error: unknown): boolean;
+//# sourceMappingURL=errno.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errno.d.ts","sourceRoot":"","sources":["../../src/errors/errno.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwCH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD"}

package/dist/errors/errno.js

@@ -0,0 +1,112 @@
+/**
+ * Errno predicates — the two questions every catch site asks of an OS error,
+ * answered by the `code` on the error or down its `cause` chain.
+ *
+ * ⚠️ This module imports NOTHING. It is the leaf that `fs-utils.ts`,
+ * `path-utils.ts`, `dirent-kind.ts`, `path-containment.ts` and the rest of the
+ * package share; it lived in `fs-utils.ts` until that put three of them in an
+ * import cycle (`fs-utils → path-utils → fs-utils` and two more), and a leaf
+ * is the one place a shared predicate cannot re-open one. (The cycle was once
+ * blamed for a platform-dependent knip verdict on these two names; breaking it
+ * changed nothing there — the cause was a missing knip entry, see
+ * `docs/contributing/traps.md`, "A subpath module's re-exports flap by platform".)
+ */
+/**
+ * Errno codes meaning "the filesystem refused this path", as opposed to a defect
+ * in our own code.
+ *
+ * Shared because two lanes need the same answer and must not drift: `vat audit`
+ * decides whether to degrade a scan over a tree it does not own, and the skill
+ * packager decides whether a `files:` match is copyable. A second, independently
+ * written list is how those two come to disagree about what counts as the
+ * environment's fault.
+ *
+ * The set is deliberately broad. An earlier, "conservative" version omitted
+ * `ENOTSUP` — the errno of the very issue this was written for — along with
+ * `EEXIST`, which an ordinary two-entry `files:` config reaches with no
+ * permissions involved at all. Both escaped raw. Every code here means the OS
+ * refused a syscall on a path; none of them can be produced by a type error or a
+ * logic bug in our own code, which is the only distinction the callers need.
+ *
+ * `EIO` and `EBUSY` are included even though they can indicate failing hardware:
+ * neither caller *swallows* anything, each reports the path and the OS message,
+ * so a dying disk surfaces once per affected path. Aborting the run instead would
+ * report less. `ENOENT` is included because a bulk scan races real filesystems —
+ * an entry listed by `readdir` can be gone by the time it is opened.
+ */
+const FILESYSTEM_ACCESS_ERRNOS = new Set([
+    // Permission and ownership
+    'EACCES', 'EPERM', 'EROFS',
+    // Presence and shape
+    'ENOENT', 'EEXIST', 'ENOTDIR', 'EISDIR', 'ENOTEMPTY', 'ELOOP', 'ENAMETOOLONG',
+    // Capability of the object or filesystem
+    'ENOTSUP', 'EOPNOTSUPP', 'EXDEV', 'ETXTBSY', 'EINVAL',
+    // Resource exhaustion and transient device state
+    'ENOSPC', 'EDQUOT', 'EMFILE', 'ENFILE', 'EIO', 'EBUSY', 'EAGAIN',
+    // Network filesystems
+    'ESTALE', 'ETIMEDOUT', 'EHOSTDOWN', 'ENETDOWN',
+    // Windows surfaces this for reparse points and some network paths
+    'UNKNOWN',
+]);
+/**
+ * Whether `error` is the filesystem refusing a path rather than a bug.
+ *
+ * Deliberately NOT `error instanceof Error`: the point of every caller is to
+ * degrade on a hostile tree, and a `TypeError` from a validator is not that.
+ * Treating one as environmental turns a real defect into a warning about
+ * whichever file it happened on — which makes a tool quietest exactly when it is
+ * most wrong.
+ *
+ * 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: …')`;
+ * without following the chain the predicate answered "not a filesystem error" for
+ * a plain `EACCES`, and an unreadable config aborted a whole `vat audit` run. Any
+ * layer that adds context to an OS error defeats a `code`-only check, so the check
+ * cannot be `code`-only.
+ */
+export function isFilesystemAccessError(error) {
+    return hasErrnoCode(error, (code) => FILESYSTEM_ACCESS_ERRNOS.has(code));
+}
+/**
+ * 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.
+ *
+ * This is the narrowing a `try { stat(p) } catch { return null }` is rewritten
+ * to under the `no-blind-catch` lint rule: the sentinel stands for *absent*,
+ * so only an absence may produce it; a refusal (`EACCES`, `EPERM`, `ELOOP`) or
+ * a bug (`TypeError`) is rethrown and stays loud.
+ *
+ * ⚠️ Deliberately NOT {@link isFilesystemAccessError}. That predicate answers
+ * "is this the environment's fault?" and to answer it groups `ENOENT` with
+ * `EACCES` — the exact conflation that once turned an unreadable directory
+ * into an empty one. The two questions have two predicates on purpose; see
+ * also {@link listingFailure}, which makes the same split for `readdir`.
+ *
+ * Walks `cause` for the same reason its sibling does: the errno is routinely
+ * re-wrapped on its way up.
+ */
+export function isPathAbsentError(error) {
+    return hasErrnoCode(error, (code) => code === 'ENOENT' || code === 'ENOTDIR');
+}
+/**
+ * Whether any string `code` on `error` or down its `cause` chain satisfies
+ * `accept`. Bounded: a malformed `cause` chain must not become an infinite
+ * loop inside an error path, which is the worst place to hang.
+ */
+function hasErrnoCode(error, accept) {
+    for (let current = error, depth = 0; depth < 10; depth++) {
+        if (typeof current !== 'object' || current === null)
+            return false;
+        if ('code' in current) {
+            const { code } = current;
+            if (typeof code === 'string' && accept(code))
+                return true;
+        }
+        if (!('cause' in current))
+            return false;
+        current = current.cause;
+    }
+    return false;
+}
+//# sourceMappingURL=errno.js.map

package/dist/errors/errno.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errno.js","sourceRoot":"","sources":["../../src/errors/errno.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAC;IAC5D,2BAA2B;IAC3B,QAAQ,EAAE,OAAO,EAAE,OAAO;IAC1B,qBAAqB;IACrB,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc;IAC7E,yCAAyC;IACzC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ;IACrD,iDAAiD;IACjD,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ;IAChE,sBAAsB;IACtB,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU;IAC9C,kEAAkE;IAClE,SAAS;CACV,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAc,EAAE,MAAiC;IACrE,KAAK,IAAI,OAAO,GAAY,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC;QAClE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAClE,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;YACtB,MAAM,EAAE,IAAI,EAAE,GAAG,OAA4B,CAAC;YAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,GAAI,OAA8B,CAAC,KAAK,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/errors/vat-error.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The base class of every error VAT throws on purpose.
+ *
+ * `code` is the one field a catch block may dispatch on. A message is prose
+ * for a human and changes whenever the prose improves; a code is a contract
+ * and changes only when the meaning does. Three packages used to recognise a
+ * root-escape by `error.message.startsWith('safePath.joinUnderRoot:')`, which
+ * held exactly until someone reworded the sentence — the ESLint restriction
+ * on `.message.includes(…)` exists so nobody writes the fourth.
+ *
+ * The brand is a registry symbol rather than the class identity because the
+ * class identity is not stable across the one boundary VAT crosses every day:
+ * a `dist` copy of a class never `instanceof`-matches a `src` instance, and
+ * `packages/cli` imports the same modules from both during tests.
+ * `Symbol.for` is realm-global, so {@link isVatError} answers the same on both
+ * sides.
+ */
+declare const VAT_ERROR_BRAND: unique symbol;
+/** An error VAT threw on purpose, with a stable machine-readable `code`. */
+export declare class VatError extends Error {
+    /** Stable identity for dispatch — `SCREAMING_SNAKE`, never read from prose. */
+    readonly code: string;
+    readonly [VAT_ERROR_BRAND] = true;
+    /**
+     * @param code - The stable identity a catch block dispatches on
+     * @param message - What went wrong, for a human
+     * @param options - `cause`, as on a native Error
+     */
+    constructor(code: string, message: string, options?: ErrorOptions);
+    toString(): string;
+}
+/**
+ * Whether `error` is a VAT error — optionally one carrying exactly `code`.
+ *
+ * Reads the brand and the `code` field, never the prototype chain, so an
+ * instance produced by another copy of this module (a `dist` build beside a
+ * `src` import) still answers yes. A foreign error that happens to carry a
+ * `code` — every `node:fs` errno does — answers no: the brand is the claim.
+ *
+ * @param error - Anything a catch block received
+ * @param code - When given, the exact code required
+ */
+export declare function isVatError(error: unknown, code?: string): error is VatError;
+/**
+ * Prefix an error's message IN PLACE, exactly once per error object.
+ *
+ * In place rather than re-wrapped because the error's class is what its
+ * catch blocks dispatch on (`GradingNonceError`, `RateLimitSignal`, …), and a
+ * wrapper would flatten every class into one. Once, because a retried item or
+ * a cached error object passes through the same seam more than once and must
+ * not accumulate prefixes. "Once" is remembered per object, not detected by
+ * re-reading the message — the previous check was `message.startsWith(prefix)`,
+ * which is a dispatch on prose by another name.
+ *
+ * @param error - Anything a catch block received; a non-Error is left alone
+ * @param prefix - Text to put before the message
+ */
+export declare function prefixMessageOnce(error: unknown, prefix: string): void;
+export {};
+//# sourceMappingURL=vat-error.d.ts.map

package/dist/errors/vat-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-error.d.ts","sourceRoot":"","sources":["../../src/errors/vat-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,QAAA,MAAM,eAAe,EAAE,OAAO,MAAgC,CAAC;AAE/D,4EAA4E;AAC5E,qBAAa,QAAS,SAAQ,KAAK;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,CAAC,eAAe,CAAC,QAAQ;IAElC;;;;OAIG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAMxD,QAAQ,IAAI,MAAM;CAG5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAM3E;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAItE"}

package/dist/errors/vat-error.js

@@ -0,0 +1,86 @@
+/**
+ * The base class of every error VAT throws on purpose.
+ *
+ * `code` is the one field a catch block may dispatch on. A message is prose
+ * for a human and changes whenever the prose improves; a code is a contract
+ * and changes only when the meaning does. Three packages used to recognise a
+ * root-escape by `error.message.startsWith('safePath.joinUnderRoot:')`, which
+ * held exactly until someone reworded the sentence — the ESLint restriction
+ * on `.message.includes(…)` exists so nobody writes the fourth.
+ *
+ * The brand is a registry symbol rather than the class identity because the
+ * class identity is not stable across the one boundary VAT crosses every day:
+ * a `dist` copy of a class never `instanceof`-matches a `src` instance, and
+ * `packages/cli` imports the same modules from both during tests.
+ * `Symbol.for` is realm-global, so {@link isVatError} answers the same on both
+ * sides.
+ */
+const VAT_ERROR_BRAND = Symbol.for('vat.error');
+/** An error VAT threw on purpose, with a stable machine-readable `code`. */
+export class VatError extends Error {
+    /** Stable identity for dispatch — `SCREAMING_SNAKE`, never read from prose. */
+    code;
+    [VAT_ERROR_BRAND] = true;
+    /**
+     * @param code - The stable identity a catch block dispatches on
+     * @param message - What went wrong, for a human
+     * @param options - `cause`, as on a native Error
+     */
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.code = code;
+    }
+    toString() {
+        return `${this.name} [${this.code}]: ${this.message}`;
+    }
+}
+/**
+ * Whether `error` is a VAT error — optionally one carrying exactly `code`.
+ *
+ * Reads the brand and the `code` field, never the prototype chain, so an
+ * instance produced by another copy of this module (a `dist` build beside a
+ * `src` import) still answers yes. A foreign error that happens to carry a
+ * `code` — every `node:fs` errno does — answers no: the brand is the claim.
+ *
+ * @param error - Anything a catch block received
+ * @param code - When given, the exact code required
+ */
+export function isVatError(error, code) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    if (!(VAT_ERROR_BRAND in error) || error[VAT_ERROR_BRAND] !== true)
+        return false;
+    const declared = error.code;
+    if (typeof declared !== 'string')
+        return false;
+    return code === undefined || declared === code;
+}
+/**
+ * Marks an error {@link prefixMessageOnce} has already prefixed. A registry
+ * symbol on the error itself rather than a module-local `WeakSet`: under the
+ * same src/dist duplication that justifies the `Symbol.for` brand above, a
+ * per-module set would make "once" mean "once per copy of this module".
+ */
+const PREFIXED = Symbol.for('vat.error.prefixed');
+/**
+ * Prefix an error's message IN PLACE, exactly once per error object.
+ *
+ * In place rather than re-wrapped because the error's class is what its
+ * catch blocks dispatch on (`GradingNonceError`, `RateLimitSignal`, …), and a
+ * wrapper would flatten every class into one. Once, because a retried item or
+ * a cached error object passes through the same seam more than once and must
+ * not accumulate prefixes. "Once" is remembered per object, not detected by
+ * re-reading the message — the previous check was `message.startsWith(prefix)`,
+ * which is a dispatch on prose by another name.
+ *
+ * @param error - Anything a catch block received; a non-Error is left alone
+ * @param prefix - Text to put before the message
+ */
+export function prefixMessageOnce(error, prefix) {
+    if (!(error instanceof Error) || PREFIXED in error)
+        return;
+    Object.defineProperty(error, PREFIXED, { value: true, enumerable: false });
+    error.message = `${prefix}${error.message}`;
+}
+//# sourceMappingURL=vat-error.js.map

package/dist/errors/vat-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-error.js","sourceRoot":"","sources":["../../src/errors/vat-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,eAAe,GAAkB,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AAE/D,4EAA4E;AAC5E,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,+EAA+E;IACtE,IAAI,CAAS;IACb,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;IAElC;;;;OAIG;IACH,YAAY,IAAY,EAAE,OAAe,EAAE,OAAsB;QAC/D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAEQ,QAAQ;QACf,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACxD,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc,EAAE,IAAa;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,CAAC,CAAC,eAAe,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACjF,MAAM,QAAQ,GAAI,KAA4B,CAAC,IAAI,CAAC;IACpD,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,IAAI,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,QAAQ,GAAkB,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,MAAc;IAC9D,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,QAAQ,IAAI,KAAK;QAAE,OAAO;IAC3D,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,KAAK,CAAC,OAAO,GAAG,GAAG,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;AAC9C,CAAC"}

package/dist/file-crawler.d.ts

@@ -1,3 +1,6 @@
+import { type UnreadablePolicy } from './listing-refusal.js';
+export type { DirectoryRefusal } from './fs-utils.js';
+export { DirectoryListingRefusedError, type RefuseListingContext, refusedListingMessage, settleRefusal, type UnreadablePolicy, } from './listing-refusal.js';
 /**
  * Options for directory crawling
  */
@@ -35,6 +38,25 @@ export interface CrawlOptions {
      * committed yet"; `respectGitignore: false` is not, and costs the whole walk.
      */
     includeUntracked?: boolean;
+    /**
+     * What to do with a directory the walk could not LIST. Required, with no
+     * default: see {@link UnreadablePolicy} for the two answers and why the
+     * caller — not the crawler — is the one who knows which is honest here.
+     *
+     * A directory that VANISHED between being enumerated and being listed
+     * (`ENOENT` / `ENOTDIR`) is not a refusal: it is no longer in the population
+     * and is skipped without a call.
+     *
+     * **Both routes settle it.** The `git ls-files` route walks the working tree
+     * whenever {@link CrawlOptions.includeUntracked} is set (`--others`), and a
+     * directory git could not open arrives here too — read off git's stderr,
+     * where it is the only trace: git exits 0 and lists fewer files. A directory
+     * the `exclude` patterns drop is not reported on either route, because the
+     * walk never lists one. The tracked-only listing (`includeUntracked: false`)
+     * opens no directory at all — the index names every member — so it has no
+     * gap to report.
+     */
+    unreadable: UnreadablePolicy;
 }
 /**
  * Directories no VAT crawl should ever walk into. THE canonical list — any lane

package/dist/file-crawler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-crawler.d.ts","sourceRoot":"","sources":["../src/file-crawler.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,iBAAiB,sJAQpB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,yBAA0B,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAQnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAgQlE"}
+{"version":3,"file":"file-crawler.d.ts","sourceRoot":"","sources":["../src/file-crawler.ts"],"names":[],"mappings":"AAUA,OAAO,EAA0C,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGrG,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD,OAAO,EACL,4BAA4B,EAC5B,KAAK,oBAAoB,EACzB,qBAAqB,EACrB,aAAa,EACb,KAAK,gBAAgB,GACtB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,iBAAiB,sJAQpB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,yBAA0B,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAQnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAuTlE"}

package/dist/file-crawler.js

@@ -1,7 +1,13 @@
 import fs from 'node:fs';
 import picomatch from 'picomatch';
+import { directoryRefusalFor, listingFailure, } from './fs-utils.js';
 import { gitFindRoot, gitLsFiles } from './git-utils.js';
+import { requireUnreadablePolicy, settleRefusal } from './listing-refusal.js';
 import { toForwardSlash, safePath } from './path-utils.js';
+// The refusal vocabulary lives in `listing-refusal.ts` so `git-utils.ts` can
+// share it without importing this module (which imports that one). Re-exported
+// here because `./crawl` is where every caller of the walk already looks.
+export { DirectoryListingRefusedError, refusedListingMessage, settleRefusal, } from './listing-refusal.js';
 /**
  * Glob options shared by every pattern this module compiles.
  *
@@ -136,17 +142,35 @@ export async function crawlDirectory(options) {
  * });
  */
 export function crawlDirectorySync(options) {
-    const { baseDir, include = ['**/*'], exclude = DEFAULT_EXCLUDE, followSymlinks = false, absolute = true, filesOnly = true, respectGitignore = true, includeUntracked = false, } = options;
+    const { baseDir, include = ['**/*'], exclude = DEFAULT_EXCLUDE, followSymlinks = false, absolute = true, filesOnly = true, respectGitignore = true, includeUntracked = false, unreadable, } = options;
+    requireUnreadablePolicy(unreadable, 'crawlDirectory');
     const picoOptions = PICOMATCH_OPTIONS;
     // Resolve base directory to absolute path
     const resolvedBaseDir = safePath.resolve(baseDir);
+    // Compiled once, ahead of the route choice, because BOTH routes ask it: the
+    // walk before it lists a directory, the git route before it reports one git
+    // could not list. One matcher is what keeps "is this directory excluded?"
+    // answered the same way on both sides of the fork.
+    const isExcluded = exclude.length > 0 ? picomatch(exclude, picoOptions) : () => false;
+    /**
+     * Check if a path should be excluded based on patterns
+     */
+    function shouldExclude(normalizedPath) {
+        // Check explicit exclude patterns
+        return isExcluded(normalizedPath) || isExcluded(normalizedPath + '/');
+    }
+    /**
+     * A refused listing surfaces under the caller's policy — thrown, or handed
+     * over. Never a silent skip, on either route.
+     */
+    function raiseRefusal(refusal) {
+        settleRefusal(unreadable, refusal);
+    }
     // Ensure base directory exists
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- baseDir is from controlled config, not user input
     if (!fs.existsSync(resolvedBaseDir)) {
         throw new Error(`Base directory does not exist: ${resolvedBaseDir}`);
     }
     // Ensure base directory is actually a directory
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved path validated above
     const baseStat = fs.statSync(resolvedBaseDir);
     if (!baseStat.isDirectory()) {
         throw new Error(`Base path is not a directory: ${resolvedBaseDir}`);
@@ -161,6 +185,24 @@ export function crawlDirectorySync(options) {
             const gitFiles = gitLsFiles({
                 cwd: resolvedBaseDir,
                 includeUntracked,
+                // The SAME decision the walk makes, in the same order: a directory
+                // outside this crawl's base or dropped by `exclude` is never listed by
+                // the walk, so a refusal on it is not this crawl's gap; anything else
+                // is, and goes where the walk's would go.
+                // `degrade` from git's side only: the refusal is filtered to this
+                // crawl's territory and then settled under the CALLER's policy, which
+                // may well be `refuse`.
+                unreadable: {
+                    degrade: (refusal) => {
+                        // Strictly beneath the base: a repository is often an ancestor of
+                        // the crawl, and git names every refusal in the whole worktree.
+                        if (!toForwardSlash(refusal.directory).startsWith(`${toForwardSlash(resolvedBaseDir)}/`))
+                            return;
+                        if (shouldExclude(toForwardSlash(safePath.relative(resolvedBaseDir, refusal.directory))))
+                            return;
+                        raiseRefusal(refusal);
+                    },
+                },
             });
             if (gitFiles !== null) {
                 // ⚠️ KNOWN DIVERGENCE: this branch ignores `followSymlinks`.
@@ -199,7 +241,6 @@ export function crawlDirectorySync(options) {
     // Fall back to manual directory crawling (not in git repo or git ls-files failed)
     // Compile glob patterns using picomatch
     const isIncluded = picomatch(include, picoOptions);
-    const isExcluded = exclude.length > 0 ? picomatch(exclude, picoOptions) : () => false;
     const results = [];
     /**
      * Real paths of directories already walked, maintained ONLY when following
@@ -218,13 +259,6 @@ export function crawlDirectorySync(options) {
      * directory cannot be reached twice, so the default path pays no `realpath`.
      */
     const visitedRealDirs = new Set();
-    /**
-     * Check if a path should be excluded based on patterns
-     */
-    function shouldExclude(normalizedPath) {
-        // Check explicit exclude patterns
-        return isExcluded(normalizedPath) || isExcluded(normalizedPath + '/');
-    }
     /**
      * Add a path to results if it matches include patterns
      */
@@ -233,24 +267,49 @@ export function crawlDirectorySync(options) {
             results.push(absolute ? fullPath : relativePath);
         }
     }
+    /**
+     * What a failed `readdirSync` / `statSync` means for the walk.
+     *
+     * Absence (`ENOENT` / `ENOTDIR`) is an entry that vanished between being
+     * enumerated by its parent and being asked about itself — not in the
+     * population, nothing to report. Anything else is a refusal, and a refusal
+     * is a GAP: handed to the caller if it asked, thrown otherwise. Never a
+     * silent `return` — that is the shorter list this walk used to hand back.
+     *
+     * @param error - What the filesystem threw
+     * @param target - The directory (or link) it was asked about
+     * @returns True when the entry is simply gone and the walk should move on
+     */
+    function reportOrSkip(error, target) {
+        const listing = listingFailure(error);
+        if (listing.outcome === 'absent')
+            return true;
+        if (listing.outcome === 'unreadable')
+            raiseRefusal(directoryRefusalFor(listing, target));
+        return false;
+    }
     /**
      * Record a directory as walked, reporting whether it had already been seen.
      *
      * Identity is `realpathSync.native`, not the traversal path: two names for
      * one directory must collide here or the alias is enumerated twice. A
-     * directory whose real path cannot be read is treated as already-walked —
-     * refusing to descend into something we cannot identify is the safe side of
-     * a guard whose whole job is bounding traversal.
+     * directory whose real path cannot be read is not descended into — refusing
+     * to walk something we cannot identify is the safe side of a guard whose
+     * whole job is bounding traversal — but it is NOT silently "already walked":
+     * a directory that vanished is skipped like any other absence, and one the
+     * OS refused to canonicalise is a gap, surfaced under the caller's policy
+     * exactly as a refused listing is (see `reportOrSkip`).
      *
      * @param dir - Directory about to be walked
-     * @returns True when this directory has been walked before
+     * @returns True when this directory must not be walked (seen before, gone, or refused)
      */
     function alreadyWalked(dir) {
         let realPath;
         try {
             realPath = fs.realpathSync.native(dir);
         }
-        catch {
+        catch (error) {
+            reportOrSkip(error, dir);
             return true;
         }
         if (visitedRealDirs.has(realPath)) {
@@ -269,11 +328,12 @@ export function crawlDirectorySync(options) {
         // Resolve symlink and check if it's a directory or file
         let targetStat;
         try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- path constructed from validated baseDir + entries
             targetStat = fs.statSync(fullPath);
         }
-        catch {
-            // Skip broken symlinks
+        catch (error) {
+            // A broken symlink is absence and is skipped; a target the OS refused to
+            // stat is a gap, and goes the same way a refused listing does.
+            reportOrSkip(error, fullPath);
             return;
         }
         if (targetStat.isDirectory()) {
@@ -309,11 +369,12 @@ export function crawlDirectorySync(options) {
         }
         let entries;
         try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- path constructed from validated baseDir, recursively walking
             entries = fs.readdirSync(currentDir, { withFileTypes: true });
         }
-        catch {
-            // Skip directories we don't have permission to read
+        catch (error) {
+            // 🚨 Not a silent skip. A directory that refused to be listed is a gap in
+            // the population this walk defines — see `reportOrSkip`.
+            reportOrSkip(error, currentDir);
             return;
         }
         // Two passes, not one: `readdirSync` order is filesystem-defined (see