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

package/dist/errors/path-present.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The one presence predicate: is something at this path — asked so that "I could
+ * not look" can never read as "nothing there".
+ *
+ * `existsSync` answers `false` for `ENOENT` and equally for `EACCES` (a parent the
+ * process may not search), `ELOOP` and every other errno, so a refused path goes on
+ * as an absent one. Here only the classifier's `absent` class can answer `false`;
+ * anything else is thrown classified (`local/no-existssync` points every caller here).
+ */
+import { type SideOfPath } from './fs-fault.js';
+/** How a presence probe treats a link: see {@link pathPresent}. */
+export type PresenceMode = 'entry' | {
+    readonly follow: string;
+};
+/**
+ * Whether something is at `path`, asked the way the caller will USE the answer — so
+ * neither choice is defaulted, and neither is inferred from `side`.
+ *
+ * `mode` — what counts as there:
+ * - `'entry'` (`lstat`): is there a directory entry at all, a dangling link
+ *   included? Right before writing there — `existsSync` calls a dangling link
+ *   absent, and the copy then trips over it.
+ * - `{ follow: within }` (`stat`): does it resolve to something that can be read? Right
+ *   before reading or staging from it — a dangling link is absent, so the caller
+ *   refuses it by its own "not there" message instead of failing later. `within` is the
+ *   tree the path is crawled in (the operator's own input, or the path itself when it IS
+ *   the operator's own): every link beneath it is read by its text before the kernel
+ *   follows it (`link-following.ts`), and a chain VAT will not hand the kernel is a fault
+ *   on `side`, of class `refused`.
+ *
+ * `absence` — how far a "nothing there" answer is believed:
+ * - `'confirmed'`: only once the parent's listing agrees (`requireConfirmedAbsent`).
+ *   Right when a wrong "absent" would silently do less or overwrite: a place about to
+ *   be written, an output the run itself made, a part of a package whose absence
+ *   means "install without it".
+ * - `'probe'`: the probe's own word. Right when the caller refuses or skips an absent
+ *   path by its own "not there" — a wrong answer is then loud or harmless — and the
+ *   listing is not worth one more read of the parent per probe.
+ *
+ * A `stat`/`lstat` the OS refuses is a classified fault on the caller's side, never
+ * "absent"; so is an absence the listing contradicts. Origin `content` is recorded
+ * for every path, a typed one included (`vat claude plugin install`'s source): the
+ * only fault raised here is about what is on disk at the path, and a typed path that
+ * is simply absent answers `false` for the caller to refuse in its own words.
+ *
+ * @param sideOf - The caller's side of each path the probe may touch — `path` itself, each
+ *   component a followed probe walks beneath `within`, and (`'confirmed'`) the parent it lists:
+ *   `source` for one it reads or stages from, `destination` for one it is about to write or that
+ *   the run itself wrote. A refusal is charged to the side of the path the OS refused.
+ * @throws {FsFaultError} when the OS refuses the probe, or (`'confirmed'`) the parent lists what it called absent
+ */
+export declare function pathPresent(path: string, mode: PresenceMode, sideOf: SideOfPath, absence: 'confirmed' | 'probe'): boolean;
+/**
+ * Whether `name` is in the directory `dir`, its link followed — the probe of each level of a
+ * root-discovery walk (`project-utils.ts`, `git-utils.ts`). Those walks climb from inside CRAWLED
+ * trees (`vat audit` asks `findProjectRoot` of every skill directory it finds), so the entry can be
+ * a link the tree's author planted.
+ *
+ * Answered by the link-chain walk ALONE — `lstat` and `readlink`, the kernel never asked to follow
+ * anything: `dir` is taken as spelled (the walk is already standing in it), and the entry's chain
+ * is read from there. A chain that ends at a file or a directory is present; one that leads to
+ * nothing (absent, a dangle, a cycle) is not; one through a network or device path is a `refused`
+ * fault on `source`, as a probe the OS refused is — never "absent". Neither `dir` nor its ancestors
+ * are resolved by the kernel: a crawled directory's own chain is not this probe's to follow, and a
+ * refused resolution of a corpus root stays the refusal of the lane that resolves it. A `dir` whose
+ * spelling holds a NUL holds nothing (no filesystem has such a name), and the walk goes on to its
+ * parent.
+ *
+ * @throws FsFaultError on `source` when the OS refuses a probe or the chain is one VAT will not follow
+ */
+export declare function entryPresentIn(dir: string, name: string): boolean;
+//# sourceMappingURL=path-present.d.ts.map

package/dist/errors/path-present.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-present.d.ts","sourceRoot":"","sources":["../../src/errors/path-present.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,EAAkC,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhF,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,GAAG,OAAO,CAazH;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAYjE"}

package/dist/errors/path-present.js

@@ -0,0 +1,110 @@
+/**
+ * The one presence predicate: is something at this path — asked so that "I could
+ * not look" can never read as "nothing there".
+ *
+ * `existsSync` answers `false` for `ENOENT` and equally for `EACCES` (a parent the
+ * process may not search), `ELOOP` and every other errno, so a refused path goes on
+ * as an absent one. Here only the classifier's `absent` class can answer `false`;
+ * anything else is thrown classified (`local/no-existssync` points every caller here).
+ */
+import { lstatSync } from 'node:fs';
+import { requireFollowedStatSync } from '../link-following.js';
+import { safePath } from '../path-core.js';
+import { LinkChainRefusedError, walkHostChain } from '../tree-change/host-chain.js';
+import { HOST_PATH_FLAVOR } from '../tree-change/link-chain.js';
+import { requireConfirmedAbsent } from './confirmed-absent.js';
+import { isPathAbsentError, isUnresolvableLinkError } from './errno-table.js';
+import { classifyFsFault, refusedPathOf } from './fs-fault.js';
+/**
+ * Whether something is at `path`, asked the way the caller will USE the answer — so
+ * neither choice is defaulted, and neither is inferred from `side`.
+ *
+ * `mode` — what counts as there:
+ * - `'entry'` (`lstat`): is there a directory entry at all, a dangling link
+ *   included? Right before writing there — `existsSync` calls a dangling link
+ *   absent, and the copy then trips over it.
+ * - `{ follow: within }` (`stat`): does it resolve to something that can be read? Right
+ *   before reading or staging from it — a dangling link is absent, so the caller
+ *   refuses it by its own "not there" message instead of failing later. `within` is the
+ *   tree the path is crawled in (the operator's own input, or the path itself when it IS
+ *   the operator's own): every link beneath it is read by its text before the kernel
+ *   follows it (`link-following.ts`), and a chain VAT will not hand the kernel is a fault
+ *   on `side`, of class `refused`.
+ *
+ * `absence` — how far a "nothing there" answer is believed:
+ * - `'confirmed'`: only once the parent's listing agrees (`requireConfirmedAbsent`).
+ *   Right when a wrong "absent" would silently do less or overwrite: a place about to
+ *   be written, an output the run itself made, a part of a package whose absence
+ *   means "install without it".
+ * - `'probe'`: the probe's own word. Right when the caller refuses or skips an absent
+ *   path by its own "not there" — a wrong answer is then loud or harmless — and the
+ *   listing is not worth one more read of the parent per probe.
+ *
+ * A `stat`/`lstat` the OS refuses is a classified fault on the caller's side, never
+ * "absent"; so is an absence the listing contradicts. Origin `content` is recorded
+ * for every path, a typed one included (`vat claude plugin install`'s source): the
+ * only fault raised here is about what is on disk at the path, and a typed path that
+ * is simply absent answers `false` for the caller to refuse in its own words.
+ *
+ * @param sideOf - The caller's side of each path the probe may touch — `path` itself, each
+ *   component a followed probe walks beneath `within`, and (`'confirmed'`) the parent it lists:
+ *   `source` for one it reads or stages from, `destination` for one it is about to write or that
+ *   the run itself wrote. A refusal is charged to the side of the path the OS refused.
+ * @throws {FsFaultError} when the OS refuses the probe, or (`'confirmed'`) the parent lists what it called absent
+ */
+export function pathPresent(path, mode, sideOf, absence) {
+    const ctx = { origin: 'content', action: 'examine the path', path };
+    try {
+        if (mode === 'entry')
+            lstatSync(path);
+        else
+            requireFollowedStatSync(path, mode.follow);
+        return true;
+    }
+    catch (error) {
+        // Followed, a chain that leads to nothing — a dangle or a cycle — is absent, as a missing path is.
+        const absent = mode === 'entry' ? isPathAbsentError(error) : isUnresolvableLinkError(error);
+        if (!absent)
+            throw classifyFsFault(error, { ...ctx, side: sideOf(refusedPathOf(error, path)) });
+        if (absence === 'confirmed')
+            requireConfirmedAbsent(path, error, ctx, { follows: mode !== 'entry', sideOf });
+        return false;
+    }
+}
+/** The NUL no filesystem name can hold. */
+const NUL = String.fromCodePoint(0);
+/**
+ * Whether `name` is in the directory `dir`, its link followed — the probe of each level of a
+ * root-discovery walk (`project-utils.ts`, `git-utils.ts`). Those walks climb from inside CRAWLED
+ * trees (`vat audit` asks `findProjectRoot` of every skill directory it finds), so the entry can be
+ * a link the tree's author planted.
+ *
+ * Answered by the link-chain walk ALONE — `lstat` and `readlink`, the kernel never asked to follow
+ * anything: `dir` is taken as spelled (the walk is already standing in it), and the entry's chain
+ * is read from there. A chain that ends at a file or a directory is present; one that leads to
+ * nothing (absent, a dangle, a cycle) is not; one through a network or device path is a `refused`
+ * fault on `source`, as a probe the OS refused is — never "absent". Neither `dir` nor its ancestors
+ * are resolved by the kernel: a crawled directory's own chain is not this probe's to follow, and a
+ * refused resolution of a corpus root stays the refusal of the lane that resolves it. A `dir` whose
+ * spelling holds a NUL holds nothing (no filesystem has such a name), and the walk goes on to its
+ * parent.
+ *
+ * @throws FsFaultError on `source` when the OS refuses a probe or the chain is one VAT will not follow
+ */
+export function entryPresentIn(dir, name) {
+    if (dir.includes(NUL))
+        return false;
+    const path = safePath.join(dir, name);
+    const ctx = { side: 'source', origin: 'content', action: 'examine the path', path };
+    let chain;
+    try {
+        chain = walkHostChain(path, { flavor: HOST_PATH_FLAVOR, root: safePath.resolve(dir), outside: 'follow' });
+    }
+    catch (error) {
+        throw classifyFsFault(error, ctx);
+    }
+    if (chain.kind === 'refused')
+        throw classifyFsFault(new LinkChainRefusedError(path, chain.refusal), ctx);
+    return chain.kind === 'resolved';
+}
+//# sourceMappingURL=path-present.js.map

package/dist/errors/path-present.js.map

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

package/dist/errors/rag-index-empty.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `VatError` code a RAG query over an index with no chunk table throws.
+ *
+ * Here rather than beside its thrower (`@vibe-agent-toolkit/rag-lancedb`)
+ * because its reader is the CLI's refusal map, which loads for every command:
+ * importing it from the optional RAG backend would load that backend with it.
+ * One constant, imported on both sides, so the thrower and the map cannot drift.
+ */
+export declare const RAG_INDEX_EMPTY_CODE = "RAG_INDEX_EMPTY";
+/**
+ * The `VatError` code for a RAG database whose table LanceDB cannot open — its
+ * files are damaged or truncated. The store is the caller's input, unreadable;
+ * kept here for the same reason as {@link RAG_INDEX_EMPTY_CODE}.
+ */
+export declare const RAG_DATABASE_UNREADABLE_CODE = "RAG_DATABASE_UNREADABLE";
+//# sourceMappingURL=rag-index-empty.d.ts.map

package/dist/errors/rag-index-empty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-index-empty.d.ts","sourceRoot":"","sources":["../../src/errors/rag-index-empty.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,4BAA4B,CAAC"}

package/dist/errors/rag-index-empty.js

@@ -0,0 +1,16 @@
+/**
+ * The `VatError` code a RAG query over an index with no chunk table throws.
+ *
+ * Here rather than beside its thrower (`@vibe-agent-toolkit/rag-lancedb`)
+ * because its reader is the CLI's refusal map, which loads for every command:
+ * importing it from the optional RAG backend would load that backend with it.
+ * One constant, imported on both sides, so the thrower and the map cannot drift.
+ */
+export const RAG_INDEX_EMPTY_CODE = 'RAG_INDEX_EMPTY';
+/**
+ * The `VatError` code for a RAG database whose table LanceDB cannot open — its
+ * files are damaged or truncated. The store is the caller's input, unreadable;
+ * kept here for the same reason as {@link RAG_INDEX_EMPTY_CODE}.
+ */
+export const RAG_DATABASE_UNREADABLE_CODE = 'RAG_DATABASE_UNREADABLE';
+//# sourceMappingURL=rag-index-empty.js.map

package/dist/errors/rag-index-empty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-index-empty.js","sourceRoot":"","sources":["../../src/errors/rag-index-empty.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,yBAAyB,CAAC"}

package/dist/errors/suppressed-faults.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Faults raised while a failure was already being handled — a temporary
+ * directory or a staged tree that would not go away after the work failed.
+ *
+ * The failure is rethrown UNCHANGED: never wrapped, never given a `cause`, never
+ * mutated (it may be frozen, shared, or carry a classified fault of its own that
+ * a cause walk must find first). The later fault is recorded beside it instead,
+ * off the cause chain, so it can never pose as the failure's classification, and
+ * a reporter reads it back with {@link suppressedFaultsOf} to name what was left.
+ *
+ * A reader walks the thrown value's cause chain (bounded, each error once), so a
+ * record made on a failure survives a wrapper thrown in its place — a
+ * rollback-incomplete error, a verb boundary's re-wrap. The walk only reads: it
+ * never decides the failure's classification.
+ *
+ * The record is keyed by the error object in a `WeakMap` held under a
+ * `Symbol.for` key on `globalThis`, so a `dist` copy and a `src` copy of this
+ * module share one record (the reason `VatError` brands with `Symbol.for`).
+ */
+/**
+ * Record `fault` as raised while `error` was being handled. A thrown value that is
+ * not an object cannot carry a record: the fault is then a process warning, so it
+ * is still never silent.
+ */
+export declare function recordSuppressedFault(error: unknown, fault: unknown): void;
+/**
+ * The faults recorded against `error`, and against every error on its cause chain,
+ * while each was being handled — outermost error first, each one's oldest first —
+ * each a leftover a report names as a warning. Empty when nothing was recorded.
+ *
+ * @param error - What a catch received
+ */
+export declare function suppressedFaultsOf(error: unknown): readonly unknown[];
+//# sourceMappingURL=suppressed-faults.d.ts.map

package/dist/errors/suppressed-faults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppressed-faults.d.ts","sourceRoot":"","sources":["../../src/errors/suppressed-faults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAQ1E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAUrE"}

package/dist/errors/suppressed-faults.js

@@ -0,0 +1,66 @@
+/**
+ * Faults raised while a failure was already being handled — a temporary
+ * directory or a staged tree that would not go away after the work failed.
+ *
+ * The failure is rethrown UNCHANGED: never wrapped, never given a `cause`, never
+ * mutated (it may be frozen, shared, or carry a classified fault of its own that
+ * a cause walk must find first). The later fault is recorded beside it instead,
+ * off the cause chain, so it can never pose as the failure's classification, and
+ * a reporter reads it back with {@link suppressedFaultsOf} to name what was left.
+ *
+ * A reader walks the thrown value's cause chain (bounded, each error once), so a
+ * record made on a failure survives a wrapper thrown in its place — a
+ * rollback-incomplete error, a verb boundary's re-wrap. The walk only reads: it
+ * never decides the failure's classification.
+ *
+ * The record is keyed by the error object in a `WeakMap` held under a
+ * `Symbol.for` key on `globalThis`, so a `dist` copy and a `src` copy of this
+ * module share one record (the reason `VatError` brands with `Symbol.for`).
+ */
+const REGISTRY_KEY = Symbol.for('vat.suppressed-faults');
+/** Bound on the cause walk: a malformed chain must not hang an error path. */
+const MAX_CAUSE_DEPTH = 10;
+function registry() {
+    const holder = globalThis;
+    const existing = holder[REGISTRY_KEY];
+    if (existing !== undefined)
+        return existing;
+    const created = new WeakMap();
+    holder[REGISTRY_KEY] = created;
+    return created;
+}
+/**
+ * Record `fault` as raised while `error` was being handled. A thrown value that is
+ * not an object cannot carry a record: the fault is then a process warning, so it
+ * is still never silent.
+ */
+export function recordSuppressedFault(error, fault) {
+    if (typeof error !== 'object' || error === null) {
+        process.emitWarning(fault instanceof Error ? fault.message : String(fault), 'VatSuppressedFault');
+        return;
+    }
+    const faults = registry().get(error);
+    if (faults === undefined)
+        registry().set(error, [fault]);
+    else
+        faults.push(fault);
+}
+/**
+ * The faults recorded against `error`, and against every error on its cause chain,
+ * while each was being handled — outermost error first, each one's oldest first —
+ * each a leftover a report names as a warning. Empty when nothing was recorded.
+ *
+ * @param error - What a catch received
+ */
+export function suppressedFaultsOf(error) {
+    const faults = [];
+    const seen = new Set();
+    let link = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof link === 'object' && link !== null && !seen.has(link); depth++) {
+        seen.add(link);
+        faults.push(...(registry().get(link) ?? []));
+        link = link.cause;
+    }
+    return faults;
+}
+//# sourceMappingURL=suppressed-faults.js.map

package/dist/errors/suppressed-faults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppressed-faults.js","sourceRoot":"","sources":["../../src/errors/suppressed-faults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEzD,8EAA8E;AAC9E,MAAM,eAAe,GAAG,EAAE,CAAC;AAI3B,SAAS,QAAQ;IACf,MAAM,MAAM,GAAG,UAA6D,CAAC;IAC7E,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,MAAM,OAAO,GAAa,IAAI,OAAO,EAAE,CAAC;IACxC,MAAM,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC;IAC/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,KAAc;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,CAAC,WAAW,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,oBAAoB,CAAC,CAAC;QAClG,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS;QAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;;QACpD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,IAAI,IAAI,GAAY,KAAK,CAAC;IAC1B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,eAAe,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACrH,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7C,IAAI,GAAI,IAA4B,CAAC,KAAK,CAAC;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/file-crawler.d.ts

@@ -1,6 +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';
+export { rootListingRefusal, type DirectoryRefusal } from './fs-utils.js';
+export { DirectoryListingRefusedError, onCrawlOutput, type RefuseListingContext, refusedListingMessage, settleCrawlRefusal, settleRefusal, type UnreadablePolicy, } from './listing-refusal.js';
 /**
  * Options for directory crawling
  */
@@ -29,6 +29,15 @@ export interface CrawlOptions {
      * DIVERGENCE block below), so it would have none to report.
      */
     onSymlinkNotFollowed?: (path: string) => void;
+    /**
+     * The trees the calling verb WRITES — its output and the staging it builds it in — or `[]`
+     * for a verb that only reads: the one declaration of which side a fault is on. A fault at
+     * (or a refused listing of) a directory that is, lies in, or holds one of them — the base of
+     * a project a build writes into included — is the destination's; anything else is on the
+     * `unreadable` policy's side (`source` when the policy degrades). Required: only the caller
+     * knows.
+     */
+    outputs: readonly string[];
     /** Return absolute paths in results (default: true) */
     absolute?: boolean;
     /** Only return files (not directories) - default: true */
@@ -155,24 +164,10 @@ export declare function crawlPathFilter(include: readonly string[], exclude: rea
  *   baseDir: '/project',
  *   include: ['**\/*.md'],
  *   exclude: ['**\/node_modules/**'],
+ *   unreadable: { refuse: { root: '/project', remedy: 'Fix the permissions.', side: 'source' } },
+ *   outputs: [],
  * });
  */
 export declare function crawlDirectory(options: CrawlOptions): Promise<string[]>;
-/**
- * Crawl a directory tree and return matching files (synchronous)
- *
- * Uses picomatch for glob pattern matching (same as Vitest)
- * Cross-platform compatible
- *
- * @param options - Crawl options
- * @returns Array of matching file paths
- *
- * @example
- * const files = crawlDirectorySync({
- *   baseDir: '/project',
- *   include: ['**\/*.md'],
- *   exclude: ['**\/node_modules/**'],
- * });
- */
 export declare function crawlDirectorySync(options: CrawlOptions): string[];
 //# sourceMappingURL=file-crawler.d.ts.map

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

@@ -1 +1 @@
-{"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;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,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;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CA4TlE"}
+{"version":3,"file":"file-crawler.d.ts","sourceRoot":"","sources":["../src/file-crawler.ts"],"names":[],"mappings":"AAeA,OAAO,EAA4D,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGvH,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAI1E,OAAO,EACL,4BAA4B,EAC5B,aAAa,EACb,KAAK,oBAAoB,EACzB,qBAAqB,EACrB,kBAAkB,EAClB,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;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C;;;;;;;OAOG;IACH,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,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;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIvE;AA0FD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CA2WlE"}