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

package/dist/gitignore-checker.js.map

@@ -1 +1 @@
-{"version":3,"file":"gitignore-checker.js","sourceRoot":"","sources":["../src/gitignore-checker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,MAAuB,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAgB;IAClE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,+BAA+B;IAC/B,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACf,QAAQ,GAAG,IAAI,CAAC;IAEhB,kDAAkD;IAClD,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC;IACtD,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAElD,+CAA+C;IAC/C,MAAM,iBAAiB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IAE1D,OAAO,cAAc,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAChE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,UAAU,KAAK,eAAe,EAAE,CAAC;YACnC,MAAM;QACR,CAAC;QACD,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACvD,qHAAqH;QACrH,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,sFAAsF;gBACtF,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;gBACxD,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,qCAAqC;YACvC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"gitignore-checker.js","sourceRoot":"","sources":["../src/gitignore-checker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,MAAuB,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAgB;IAClE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,+BAA+B;IAC/B,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACf,QAAQ,GAAG,IAAI,CAAC;IAEhB,kDAAkD;IAClD,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC;IACtD,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAElD,+CAA+C;IAC/C,MAAM,iBAAiB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IAE1D,OAAO,cAAc,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAChE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,UAAU,KAAK,eAAe,EAAE,CAAC;YACnC,MAAM;QACR,CAAC;QACD,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACvD,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,wEAAwE;gBACxE,oEAAoE;gBACpE,yEAAyE;gBACzE,qBAAqB;gBACrB,EAAE,CAAC,GAAG,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC;YAClD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,wEAAwE;gBACxE,gEAAgE;gBAChE,wEAAwE;gBACxE,kEAAkE;gBAClE,+CAA+C;gBAC/C,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;oBAAE,MAAM,KAAK,CAAC;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9B,CAAC"}

package/dist/glob/glob-pattern.js

@@ -11,7 +11,7 @@
  * sets an `escaped` flag when it sees `\`; the *next* character is skipped for
  * magic detection if `escaped` is true.
  */
-import { toForwardSlash } from '../path-core.js';
+import { toForwardSlashAnyPlatform } from '../path-core.js';
 /** The glob metacharacters recognised by this module. */
 const MAGIC_CHARS = new Set(['*', '?', '[']);
 /** Sentinel returned by {@link staticGlobBase} when the first segment is magic. */
@@ -69,9 +69,9 @@ export function isGlob(source) {
  * staticGlobBase('foo/bar.txt')            // 'foo/bar.txt'
  */
 export function staticGlobBase(pattern) {
-    // Glob patterns are always forward-slash; toForwardSlash() satisfies the
-    // no-hardcoded-path-split lint rule while being a no-op in practice.
-    const normalized = toForwardSlash(pattern);
+    // A glob is author-written text: a Windows-spelled separator reads as `/` on
+    // every host, whatever platform VAT runs on.
+    const normalized = toForwardSlashAnyPlatform(pattern);
     const segments = normalized.split('/');
     const staticSegments = [];
     for (const segment of segments) {
@@ -112,7 +112,7 @@ export function staticGlobBase(pattern) {
  * globMagicRemainder('../mycli/dist/*.mjs')   // '*.mjs'
  */
 export function globMagicRemainder(pattern) {
-    const forward = toForwardSlash(pattern);
+    const forward = toForwardSlashAnyPlatform(pattern);
     const base = staticGlobBase(pattern);
     if (base === DOT) {
         // First segment was magic — the remainder is the full (forward-slash) pattern.

package/dist/glob/glob-pattern.js.map

@@ -1 +1 @@
-{"version":3,"file":"glob-pattern.js","sourceRoot":"","sources":["../../src/glob/glob-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,yDAAyD;AACzD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAE7C,mFAAmF;AACnF,MAAM,GAAG,GAAG,GAAG,CAAC;AAEhB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,KAAK,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,yEAAyE;IACzE,qEAAqE;IACrE,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACpB,MAAM;QACR,CAAC;QACD,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9C,oEAAoE;QACpE,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,uEAAuE;QACvE,uEAAuE;QACvE,sEAAsE;QACtE,uEAAuE;QACvE,gDAAgD;QAChD,OAAO,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,+EAA+E;QAC/E,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,yDAAyD;QACzD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,yEAAyE;QACzE,yEAAyE;QACzE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IACD,wDAAwD;IACxD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"glob-pattern.js","sourceRoot":"","sources":["../../src/glob/glob-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,yDAAyD;AACzD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAE7C,mFAAmF;AACnF,MAAM,GAAG,GAAG,GAAG,CAAC;AAEhB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,KAAK,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,6EAA6E;IAC7E,6CAA6C;IAC7C,MAAM,UAAU,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACpB,MAAM;QACR,CAAC;QACD,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9C,oEAAoE;QACpE,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,uEAAuE;QACvE,uEAAuE;QACvE,sEAAsE;QACtE,uEAAuE;QACvE,gDAAgD;QAChD,OAAO,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,OAAO,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,+EAA+E;QAC/E,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,yDAAyD;QACzD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,yEAAyE;QACzE,yEAAyE;QACzE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IACD,wDAAwD;IACxD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/index.d.ts

@@ -3,31 +3,45 @@
  * Core shared utilities with no dependencies on other packages
  *
  * Utilities are added as needed by other packages, not speculatively.
+ *
+ * **A module that brings a third-party dependency belongs on a subpath, not
+ * here.** This entry has ~245 in-repo importers plus published adopters, and
+ * every one of them pays for the whole graph reachable from it — a bundler that
+ * cannot tree-shake a dependency (a CJS package, or one reached through
+ * `new URL(..., import.meta.url)`) inlines it into every consumer that touched
+ * a path helper. The domains that carry weight each have their own entry:
+ * `./crawl`, `./git`, `./process`, `./skill-test`, `./template`, `./yaml`.
+ * `./skill-test` is there for a *transitive* reason rather than a direct one —
+ * it declares no dependency itself, but spawning a headless agent goes through
+ * `./process`, which reaches `which` and (because `safeExecSync` refuses `git`
+ * and delegates) `@vibe-validate/git`. Reachability is the criterion, not the
+ * import a module happens to write.
+ *
+ * The rule is enforced, not merely stated: `test/subpath-purity.test.ts` asserts
+ * this entry's reachable third-party set by equality, so a dependency arriving
+ * here — directly or transitively, through any module below — turns that row red
+ * and has to be an argued edit rather than an unnoticed one.
  */
-export * from './safe-exec.js';
-export * from './windows-shell.js';
-export * from './spawn-hardened.js';
+export * from './errors/vat-error.js';
 export * from './path-utils.js';
-export * from './stdio-blocking.js';
+export * from './path-containment.js';
+export * from './dirent-kind.js';
+export * from './text-content.js';
+export * from './text-file.js';
 export * from './asset-reference.js';
-export * from './fs-utils.js';
-export * from './file-crawler.js';
-export * from './gitignore-checker.js';
-export * from './git-url.js';
-export * from './git-utils.js';
+export { isFilesystemAccessError, isPathAbsentError } from './errors/errno.js';
+export { copyDirectory, CopyLinkEscapesSourceError, FsLookupCache, transientRefusalClause, } from './fs-utils.js';
+export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathFrom, spellingWalkRoot, } from './fs-utils.js';
+export type { AbsenceCause, ComponentMatch, FilenameMatch, PathProbe, PathProbeStats, PathSpelling, PathSpellingRequest, PathSpellingTable, RealpathTable, VerifiedPrefix, } from './fs-utils.js';
 export * from './project-utils.js';
-export * from './git-tracker.js';
-export * from './test-helpers.js';
+export { createSymlink, createSymlinkAsync, detachGitEnv, errnoError, INHERITED_GIT_ENV, symlinkCapability, type SymlinkCapability, } from './test-helpers.js';
 export * from './zod-introspection.js';
-export * from './template.js';
 export * from './skill-targets.js';
-export { type LinkAuthConfig, type Provider, type ProviderAuth, type ProviderCheck, resolveAuthenticatedUrl, type ResolveOutcome, } from './link-auth/resolve.js';
-export type { ProviderMatch } from './link-auth/select-provider.js';
-export type { RewriteRule } from './link-auth/rewrite.js';
-export { defaultRunCommand, type TokenSource } from './link-auth/resolve-token.js';
-export { expandMacro, UnknownMacroError } from './link-auth/expand-macro.js';
-export * from './skill-test/index.js';
 export * from './glob/glob-pattern.js';
 export * from './fs/file-hash.js';
-export * from './yaml/surgical-yaml.js';
+export { parseWholeNumberAtLeast } from './numeric-args.js';
+export { parseEnvBoolean } from './env-flag.js';
+export { compareCodeUnits } from './compare-code-units.js';
+export { CRAWL_BLOB_POPULATE_ID, CRAWL_CLOSURE_CONTRIBUTE_ID, CRAWL_CLOSURE_RESOLVE_ID, CRAWL_PASS_INSIDE, CRAWL_REGISTRY_ADMIT_ID, CRAWL_REGISTRY_ENUMERATE_ID, CRAWL_REGISTRY_ID_PREFIX, CRAWL_REGISTRY_RESOLVE_LINKS_ID, CRAWL_SHARED_GIT_TRACKER_ID, CRAWL_STORE_READ_ID, CRAWL_STORE_WRITE_ID, CRAWL_STRATA, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, recordContributorInvocation, recordCrawlPass, recordRegistryPass, recordSharedPass, withContributorStratum, withOuterBracket, type CrawlDriverStratum, type CrawlStratum, type CrawlTimingDump, type CrawlTimingEntry, type CrawlTimingProcess, } from './crawl-timing.js';
+export { ensureTimingDirectory, normalizeTimingDirectory, readTimingProcess, type TimingProcess, writeTimingDump, } from './timing-dump.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAI/B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,eAAe,CAAC;AAG9B,cAAc,oBAAoB,CAAC;AAInC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,uBAAuB,EACvB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAG7E,cAAc,uBAAuB,CAAC;AAGtC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,cAAc,uBAAuB,CAAC;AAGtC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,kBAAkB,CAAC;AASjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,sBAAsB,CAAC;AAyCrC,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,aAAa,EACb,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAC;AAIvB,cAAc,oBAAoB,CAAC;AASnC,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,cAAc,wBAAwB,CAAC;AAGvC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAK5D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAgB3D,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,aAAa,EAClB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -3,53 +3,133 @@
  * Core shared utilities with no dependencies on other packages
  *
  * Utilities are added as needed by other packages, not speculatively.
+ *
+ * **A module that brings a third-party dependency belongs on a subpath, not
+ * here.** This entry has ~245 in-repo importers plus published adopters, and
+ * every one of them pays for the whole graph reachable from it — a bundler that
+ * cannot tree-shake a dependency (a CJS package, or one reached through
+ * `new URL(..., import.meta.url)`) inlines it into every consumer that touched
+ * a path helper. The domains that carry weight each have their own entry:
+ * `./crawl`, `./git`, `./process`, `./skill-test`, `./template`, `./yaml`.
+ * `./skill-test` is there for a *transitive* reason rather than a direct one —
+ * it declares no dependency itself, but spawning a headless agent goes through
+ * `./process`, which reaches `which` and (because `safeExecSync` refuses `git`
+ * and delegates) `@vibe-validate/git`. Reachability is the criterion, not the
+ * import a module happens to write.
+ *
+ * The rule is enforced, not merely stated: `test/subpath-purity.test.ts` asserts
+ * this entry's reachable third-party set by equality, so a dependency arriving
+ * here — directly or transitively, through any module below — turns that row red
+ * and has to be an argued edit rather than an unnoticed one.
  */
-// Safe command execution (cross-platform, no shell injection)
-export * from './safe-exec.js';
-// Windows shell-invocation helpers (.cmd/.bat/.ps1 handling), shared by every spawn wrapper
-export * from './windows-shell.js';
-// Hardened async spawn (streaming stdio + correct Windows .cmd/.bat launching)
-export * from './spawn-hardened.js';
+// The base of every error VAT throws on purpose; `code` is what a catch
+// block dispatches on, never `message`.
+export * from './errors/vat-error.js';
 // Cross-platform path utilities
 export * from './path-utils.js';
-// Blocking stdio for published bins (process.exit must not truncate output)
-export * from './stdio-blocking.js';
+// The filesystem-backed containment verdict every delete/copy/uninstall sink asks.
+export * from './path-containment.js';
+// The Dirent classifiers a walk uses instead of a bare isFile()/isDirectory().
+export * from './dirent-kind.js';
+// THE content-decoding seam: bytes to text, in one place. `decodeTextContent` is
+// pure and also reachable from the dependency-free `./text` entry; the two
+// file-reading wrappers need `node:fs` and are also on `./fs`. Other routes from
+// bytes to text — `buf.toString('utf-8')`, `new TextDecoder()`,
+// `readFile(p, 'utf-8')` — are a lint error under `local/no-raw-text-decode`
+// WHERE IT IS REGISTERED (this package's `src` and `resources`' `src`); the rest
+// of the repo is a migration ledger in `eslint.config.js`, not a covered claim.
+export * from './text-content.js';
+export * from './text-file.js';
 // Asset reference resolution (paths + npm bare specifiers)
 export * from './asset-reference.js';
-// Filesystem utilities
-export * from './fs-utils.js';
-// Directory crawling with glob patterns
-export * from './file-crawler.js';
-// Git ignore checking
-export * from './gitignore-checker.js';
-// Git URL parsing (parse/detect git URLs, GitHub shorthand, SSH forms)
-export * from './git-url.js';
-// Git utilities (using git commands directly)
-export * from './git-utils.js';
+// Filesystem utilities.
+//
+// Named rather than `export *` on purpose: `fs-utils.ts` holds internal members
+// of the fill+judge pairs below — the per-directory index build, the table-key
+// derivation — and a star re-export would publish each of them on this barrel
+// the moment it was written. (The `./fs` subpath was already an explicit list
+// and was never at risk.) The public surface is a decision, not a side effect of
+// module layout.
+//
+// TWO materialized columns are published, both shaped fill-first-then-judge:
+//
+//   - path spellings — `fillPathSpellings` plus `pathSpellingFrom`. It judges a
+//     WHOLE path, which is what a caller validating references needs: judging
+//     only the basename hands every directory component back to the host
+//     filesystem's own folding, so a link that resolves on macOS 404s on a
+//     case-sensitive filesystem. The `DirectorySpellingIndex` underneath is
+//     published too, for the lazy caller that cannot enumerate its targets up
+//     front.
+//   - realpaths — `fillRealpaths` (every canonicalization, once, up front) plus
+//     `realpathFrom`.
+//
+// In both, the row lookup IS the judge: the row is the answer, so there is
+// nothing left to keep internal.
+//
+// There is deliberately no one-call wrapper composing either pair: handed one, a
+// caller with many paths loops over it, which reinstates the per-path `await` the
+// pairs exist to remove.
+//
+// `PathSpellingTable` and `RealpathTable` — what the fills return and the judges
+// consume — are the types a caller can name, as are `PathSpelling`,
+// `PathSpellingRequest`, `ComponentMatch` and `FilenameMatch`, which a consumer
+// receives and branches on.
+//
+// The cost of that decision, stated so it is not a surprise: a new *type* added
+// to `fs-utils.ts` no longer reaches consumers automatically, and
+// `barrel-exports.test.ts` pins runtime names only, so nothing will fail. The
+// symptom is a type that cannot be imported, which surfaces the first time
+// someone tries — not a silent break in existing code.
+// The lookups themselves, plus the memo every fill shares.
+export { isFilesystemAccessError, isPathAbsentError } from './errors/errno.js';
+export { copyDirectory, CopyLinkEscapesSourceError, FsLookupCache, transientRefusalClause, } from './fs-utils.js';
+// The two fill+judge pairs, in the order the note above lists them, plus the
+// lazy index a caller that cannot enumerate its targets up front reaches for.
+export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathFrom, spellingWalkRoot, } from './fs-utils.js';
 // Project root discovery (canonical: config → git → null).
 // CLI-boundary use only — see docs/concepts/roots-and-config.md.
 export * from './project-utils.js';
-// Git tracking cache (for efficient git-ignore checking)
-export * from './git-tracker.js';
-// Test helpers for isolated test output directories
-export * from './test-helpers.js';
+// The runtime half of `test-helpers.ts`: symlink creation with its host
+// capability probe, and the git-environment detachment every child process
+// needs. Named rather than `export *` because the SAME module also holds the
+// fs-refusal fakes (`refuseSyncFs` and siblings), which are test scaffolding
+// and reach adopters on the `./testing` subpath only. A published runtime
+// barrel that carried them — eight such names, once — was the audit's finding,
+// and an `export *` here is how they got in.
+export { createSymlink, createSymlinkAsync, detachGitEnv, errnoError, INHERITED_GIT_ENV, symlinkCapability, } from './test-helpers.js';
 // Zod type introspection (version-agnostic)
 export * from './zod-introspection.js';
-// Handlebars template rendering (cached, no HTML escaping)
-export * from './template.js';
 // Skill target resolution (cross-platform flat skill install paths)
 export * from './skill-targets.js';
-// linkAuth pure engine — public API only (issue #113).
-// Internal helpers (rewrite, build-headers, etc.) stay module-private.
-export { resolveAuthenticatedUrl, } from './link-auth/resolve.js';
-export { defaultRunCommand } from './link-auth/resolve-token.js';
-export { expandMacro, UnknownMacroError } from './link-auth/expand-macro.js';
-// Skill testing utilities (environment management for headless agent runs)
-export * from './skill-test/index.js';
 // Glob pattern helpers (isGlob, staticGlobBase, globMagicRemainder)
 export * from './glob/glob-pattern.js';
 // Filesystem hashing (sha256 of raw file bytes)
 export * from './fs/file-hash.js';
-// Byte-surgical YAML value updater (replace/insert without reflowing the doc)
-export * from './yaml/surgical-yaml.js';
+export { parseWholeNumberAtLeast } from './numeric-args.js';
+// THE reading of an environment variable as a boolean. One implementation
+// because three switches each had their own `!== '0'` comparison and none of
+// them turned off for `=false`.
+export { parseEnvBoolean } from './env-flag.js';
+// Machine-independent string ordering for hashed/serialized output — never `localeCompare`.
+export { compareCodeUnits } from './compare-code-units.js';
+// The crawl-timing seam: which contributor, stratum and fixpoint pass owns the
+// time it takes to FIND documents.
+//
+// It lives HERE, at the bottom of the graph, because the work it measures is
+// spread across four packages above this one — `resources` builds the registry,
+// `agent-skills` walks the link graph, `claude-marketplace` enumerates an
+// inventory, and `utils` itself initializes the `GitTracker` both crawlers
+// consume. Both arms must record through ONE recorder or the two are not
+// comparable, and only `utils` is beneath all of them. See the module header.
+//
+// Named rather than `export *`: the accumulator internals (`addEntry`,
+// `keyOf`, `recordInheritedPass`) are not surface, and `timing-dump.ts` is
+// plumbing shared with `resources`' package-internal `parse-timing.ts` — a star
+// re-export would publish both the moment either grew a symbol.
+export { CRAWL_BLOB_POPULATE_ID, CRAWL_CLOSURE_CONTRIBUTE_ID, CRAWL_CLOSURE_RESOLVE_ID, CRAWL_PASS_INSIDE, CRAWL_REGISTRY_ADMIT_ID, CRAWL_REGISTRY_ENUMERATE_ID, CRAWL_REGISTRY_ID_PREFIX, CRAWL_REGISTRY_RESOLVE_LINKS_ID, CRAWL_SHARED_GIT_TRACKER_ID, CRAWL_STORE_READ_ID, CRAWL_STORE_WRITE_ID, CRAWL_STRATA, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, recordContributorInvocation, recordCrawlPass, recordRegistryPass, recordSharedPass, withContributorStratum, withOuterBracket, } from './crawl-timing.js';
+// The three `__*ForTest` seams of the same module are on `./testing`, not here.
+// The on-disk plumbing both timing seams share. Exported because
+// `resources`' `parse-timing.ts` is the other consumer and now sits a package
+// away; nothing else should reach for it.
+export { ensureTimingDirectory, normalizeTimingDirectory, readTimingProcess, writeTimingDump, } from './timing-dump.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,cAAc,gBAAgB,CAAC;AAE/B,4FAA4F;AAC5F,cAAc,oBAAoB,CAAC;AAEnC,+EAA+E;AAC/E,cAAc,qBAAqB,CAAC;AAEpC,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,4EAA4E;AAC5E,cAAc,qBAAqB,CAAC;AAEpC,2DAA2D;AAC3D,cAAc,sBAAsB,CAAC;AAErC,uBAAuB;AACvB,cAAc,eAAe,CAAC;AAE9B,wCAAwC;AACxC,cAAc,mBAAmB,CAAC;AAElC,sBAAsB;AACtB,cAAc,wBAAwB,CAAC;AAEvC,uEAAuE;AACvE,cAAc,cAAc,CAAC;AAE7B,8CAA8C;AAC9C,cAAc,gBAAgB,CAAC;AAE/B,2DAA2D;AAC3D,iEAAiE;AACjE,cAAc,oBAAoB,CAAC;AAEnC,yDAAyD;AACzD,cAAc,kBAAkB,CAAC;AAEjC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,2DAA2D;AAC3D,cAAc,eAAe,CAAC;AAE9B,oEAAoE;AACpE,cAAc,oBAAoB,CAAC;AAEnC,uDAAuD;AACvD,uEAAuE;AACvE,OAAO,EAKL,uBAAuB,GAExB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,iBAAiB,EAAoB,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAE7E,2EAA2E;AAC3E,cAAc,uBAAuB,CAAC;AAEtC,oEAAoE;AACpE,cAAc,wBAAwB,CAAC;AAEvC,gDAAgD;AAChD,cAAc,mBAAmB,CAAC;AAElC,8EAA8E;AAC9E,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,wEAAwE;AACxE,wCAAwC;AACxC,cAAc,uBAAuB,CAAC;AAEtC,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAChC,mFAAmF;AACnF,cAAc,uBAAuB,CAAC;AACtC,+EAA+E;AAC/E,cAAc,kBAAkB,CAAC;AAEjC,iFAAiF;AACjF,2EAA2E;AAC3E,iFAAiF;AACjF,gEAAgE;AAChE,6EAA6E;AAC7E,iFAAiF;AACjF,gFAAgF;AAChF,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAE/B,2DAA2D;AAC3D,cAAc,sBAAsB,CAAC;AAErC,wBAAwB;AACxB,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,iFAAiF;AACjF,iBAAiB;AACjB,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAC9E,aAAa;AACb,gFAAgF;AAChF,sBAAsB;AACtB,EAAE;AACF,2EAA2E;AAC3E,iCAAiC;AACjC,EAAE;AACF,iFAAiF;AACjF,kFAAkF;AAClF,yBAAyB;AACzB,EAAE;AACF,iFAAiF;AACjF,oEAAoE;AACpE,gFAAgF;AAChF,4BAA4B;AAC5B,EAAE;AACF,gFAAgF;AAChF,kEAAkE;AAClE,8EAA8E;AAC9E,2EAA2E;AAC3E,uDAAuD;AACvD,2DAA2D;AAC3D,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,aAAa,EACb,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,6EAA6E;AAC7E,8EAA8E;AAC9E,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAcvB,2DAA2D;AAC3D,iEAAiE;AACjE,cAAc,oBAAoB,CAAC;AAEnC,wEAAwE;AACxE,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,+EAA+E;AAC/E,6CAA6C;AAC7C,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAE3B,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,oEAAoE;AACpE,cAAc,oBAAoB,CAAC;AAEnC,oEAAoE;AACpE,cAAc,wBAAwB,CAAC;AAEvC,gDAAgD;AAChD,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,0EAA0E;AAC1E,6EAA6E;AAC7E,gCAAgC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,4FAA4F;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,+EAA+E;AAC/E,mCAAmC;AACnC,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,0EAA0E;AAC1E,2EAA2E;AAC3E,yEAAyE;AACzE,8EAA8E;AAC9E,EAAE;AACF,uEAAuE;AACvE,2EAA2E;AAC3E,gFAAgF;AAChF,gEAAgE;AAChE,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GAMjB,MAAM,mBAAmB,CAAC;AAC3B,gFAAgF;AAEhF,iEAAiE;AACjE,8EAA8E;AAC9E,0CAA0C;AAC1C,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EAEjB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/listing-refusal.d.ts

@@ -0,0 +1,112 @@
+/**
+ * What a listing does with a directory it was refused — the vocabulary shared
+ * by the filesystem walk (`file-crawler.ts`) and the git listings
+ * (`git-utils.ts`), so a caller decides ONCE for both routes.
+ *
+ * 🚨 A refused listing is a gap in the POPULATION: every file beneath that
+ * directory the listing would have found was never seen and is absent from
+ * every count downstream. There are exactly two honest answers — stop, with a
+ * sentence the adopter can act on, or keep going and REPORT the gap — and
+ * which one is right is the caller's knowledge, not the crawler's. So the
+ * policy is {@link UnreadablePolicy}, it is REQUIRED wherever a listing is
+ * asked for, and it has no default.
+ *
+ * 🪤 It used to be `onUnreadable?`, an optional callback. Every caller that
+ * ignored it compiled; the two routes then defaulted differently (the walk
+ * threw a programmer-facing sentence, the git route dropped the refusal off
+ * 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 { VatError } from './errors/vat-error.js';
+import { type DirectoryRefusal } from './fs-utils.js';
+/**
+ * What a caller that STOPS on a refusal tells the person reading the error.
+ *
+ * A caller that has decided to stop — a build that must not ship an incomplete
+ * bundle, a discovery that must not silently find fewer skills — owes the
+ * adopter the directory against the root they know, and the knob THEY have.
+ */
+export interface RefuseListingContext {
+    /**
+     * The root the refused directory is expressed against. An absolute path in
+     * an error is the developer's `$HOME` in every CI log.
+     */
+    root: string;
+    /**
+     * What the adopter can do about it — naming this lane's deliberate-drop
+     * mechanism (`resources.exclude`, a plugin `exclude:`, `--exclude`), which
+     * differs per caller and is why the crawler cannot supply it.
+     */
+    remedy: string;
+}
+/**
+ * The caller's decision about a directory the listing cannot open.
+ *
+ * - `{ refuse }` — STOP: the listing throws {@link DirectoryListingRefusedError}
+ *   with the adopter-facing sentence built from the context. Right for every
+ *   lane whose output is acted on as a complete population (a build, a
+ *   discovery, a fingerprint, a copy).
+ * - `{ degrade }` — KEEP GOING and hand the refusal over. The caller is
+ *   promising to REPORT the gap — as its own finding, with the directory and
+ *   errno the refusal carries — not to drop it. Right for a backstop appended
+ *   to a larger report, where one unlistable directory must not destroy every
+ *   finding beside it.
+ *
+ * A directory that VANISHED between being enumerated and being listed
+ * (`ENOENT` / `ENOTDIR`) is not a refusal under either arm: it is no longer in
+ * the population and is skipped without a call.
+ */
+export type UnreadablePolicy = {
+    readonly refuse: RefuseListingContext;
+} | {
+    readonly degrade: (refusal: DirectoryRefusal) => void;
+};
+/**
+ * Thrown by a listing under `{ refuse }` when a directory refused to be
+ * listed. The message is the adopter's sentence — see {@link refusedListingMessage}.
+ */
+export declare class DirectoryListingRefusedError extends VatError {
+    readonly refusal: DirectoryRefusal;
+    constructor(refusal: DirectoryRefusal, context: RefuseListingContext);
+}
+/**
+ * The adopter-facing sentence: root-relative directory, errno, the gap, and
+ * the caller's remedy — **the one owner of that sentence.**
+ *
+ * Exported so every lane that refuses says the same thing. Three lanes used to
+ * compose this by hand and had drifted by a clause each ("enumerated" /
+ * "scanned" / "the population could not be enumerated"); the transient clause
+ * in particular was written once in `fs-utils.ts` precisely so nobody would.
+ * See {@link REFUSAL_GAP_CLAUSE} for why it asserts nothing about what WAS
+ * enumerated beneath the directory.
+ *
+ * @param refusal - What was refused
+ * @param context - The root to express it against, and what the adopter can do
+ * @returns One sentence, root-relative, never containing the absolute path
+ */
+export declare function refusedListingMessage(refusal: DirectoryRefusal, context: RefuseListingContext): string;
+/**
+ * Apply the caller's policy to one refusal: throw under `{ refuse }`, hand it
+ * over under `{ degrade }`. The single place either route settles a refusal,
+ * so the two cannot drift.
+ *
+ * @param policy - The caller's decision
+ * @param refusal - The directory that could not be listed
+ */
+export declare function settleRefusal(policy: UnreadablePolicy, refusal: DirectoryRefusal): void;
+/**
+ * Refuse an omitted policy up front, by name, before any directory is listed.
+ *
+ * The type already makes `unreadable` required, and that is what enumerates
+ * the TypeScript callers. This is the runtime half, for the callers the type
+ * cannot reach — test files are not typechecked by the build, and a JavaScript
+ * adopter has no compiler at all. Without it an omitted policy would surface
+ * only on the first refusal, as a `TypeError` from the `in` operator, and a
+ * tree with nothing unreadable would keep returning complete lists — the
+ * optional seam back again, one layer down.
+ *
+ * @param policy - What the caller passed as `unreadable`
+ * @param api - The entry point, for the sentence
+ */
+export declare function requireUnreadablePolicy(policy: UnreadablePolicy | undefined, api: string): asserts policy is UnreadablePolicy;
+//# sourceMappingURL=listing-refusal.d.ts.map

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

@@ -0,0 +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"}

package/dist/listing-refusal.js

@@ -0,0 +1,105 @@
+/**
+ * What a listing does with a directory it was refused — the vocabulary shared
+ * by the filesystem walk (`file-crawler.ts`) and the git listings
+ * (`git-utils.ts`), so a caller decides ONCE for both routes.
+ *
+ * 🚨 A refused listing is a gap in the POPULATION: every file beneath that
+ * directory the listing would have found was never seen and is absent from
+ * every count downstream. There are exactly two honest answers — stop, with a
+ * sentence the adopter can act on, or keep going and REPORT the gap — and
+ * which one is right is the caller's knowledge, not the crawler's. So the
+ * policy is {@link UnreadablePolicy}, it is REQUIRED wherever a listing is
+ * asked for, and it has no default.
+ *
+ * 🪤 It used to be `onUnreadable?`, an optional callback. Every caller that
+ * ignored it compiled; the two routes then defaulted differently (the walk
+ * threw a programmer-facing sentence, the git route dropped the refusal off
+ * 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 { VatError } from './errors/vat-error.js';
+import { transientRefusalClause } from './fs-utils.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}.
+ */
+export class DirectoryListingRefusedError extends VatError {
+    refusal;
+    constructor(refusal, context) {
+        super('DIRECTORY_LISTING_REFUSED', refusedListingMessage(refusal, context));
+        this.refusal = refusal;
+    }
+}
+/**
+ * What a refused listing costs, said so it is true on BOTH routes.
+ *
+ * 🪤 It used to read "so nothing beneath it was enumerated: every file there
+ * is in the declared scan". Both halves were the readdir walk's truth and the
+ * git route's lie: `git ls-files --others` reports the refusal while the index
+ * has already named every TRACKED file beneath the directory — the same run
+ * that printed the sentence had scanned one of them — and the projection's
+ * population is the whole non-ignored tree, which no `include`/`exclude`
+ * "declared". What holds on every route is the hazard itself: whatever the
+ * listing would have found and nothing else named is missing, and the shorter
+ * result is indistinguishable from a complete one.
+ */
+const REFUSAL_GAP_CLAUSE = 'any file beneath it that no other listing named is absent from every count, ' +
+    'and the result cannot be told from a complete one';
+/**
+ * The adopter-facing sentence: root-relative directory, errno, the gap, and
+ * the caller's remedy — **the one owner of that sentence.**
+ *
+ * Exported so every lane that refuses says the same thing. Three lanes used to
+ * compose this by hand and had drifted by a clause each ("enumerated" /
+ * "scanned" / "the population could not be enumerated"); the transient clause
+ * in particular was written once in `fs-utils.ts` precisely so nobody would.
+ * See {@link REFUSAL_GAP_CLAUSE} for why it asserts nothing about what WAS
+ * enumerated beneath the directory.
+ *
+ * @param refusal - What was refused
+ * @param context - The root to express it against, and what the adopter can do
+ * @returns One sentence, root-relative, never containing the absolute path
+ */
+export function refusedListingMessage(refusal, context) {
+    const relative = toForwardSlash(safePath.relative(context.root, refusal.directory));
+    const where = relative === '' ? 'the scan root itself' : `the directory '${relative}'`;
+    const remedy = refusal.transient
+        ? `${transientRefusalClause(refusal.code)}, so nothing is wrong with the tree — re-run before investigating anything.`
+        : context.remedy;
+    return `Listing ${where} was refused (${refusal.code}): ${REFUSAL_GAP_CLAUSE}. ${remedy}`;
+}
+/**
+ * Apply the caller's policy to one refusal: throw under `{ refuse }`, hand it
+ * over under `{ degrade }`. The single place either route settles a refusal,
+ * so the two cannot drift.
+ *
+ * @param policy - The caller's decision
+ * @param refusal - The directory that could not be listed
+ */
+export function settleRefusal(policy, refusal) {
+    if ('refuse' in policy)
+        throw new DirectoryListingRefusedError(refusal, policy.refuse);
+    policy.degrade(refusal);
+}
+/**
+ * Refuse an omitted policy up front, by name, before any directory is listed.
+ *
+ * The type already makes `unreadable` required, and that is what enumerates
+ * the TypeScript callers. This is the runtime half, for the callers the type
+ * cannot reach — test files are not typechecked by the build, and a JavaScript
+ * adopter has no compiler at all. Without it an omitted policy would surface
+ * only on the first refusal, as a `TypeError` from the `in` operator, and a
+ * tree with nothing unreadable would keep returning complete lists — the
+ * optional seam back again, one layer down.
+ *
+ * @param policy - What the caller passed as `unreadable`
+ * @param api - The entry point, for the sentence
+ */
+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, ` +
+            'or { degrade: (refusal) => … } to keep going and report the gap yourself.');
+    }
+}
+//# sourceMappingURL=listing-refusal.js.map

package/dist/listing-refusal.js.map

@@ -0,0 +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"}

package/dist/numeric-args.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Validation for numeric command-line arguments.
+ *
+ * Deliberately free of any CLI-framework types: the rule is "is this a whole
+ * number at or above a floor", which has nothing to do with Commander. Callers
+ * that need a framework-specific error catch this one and re-raise, which is
+ * what lets a CLI print a usage message while the rule itself stays testable
+ * without a parser.
+ */
+/**
+ * Parse a whole number that must be at or above a floor.
+ *
+ * The error names the flag as the user spelled it, because "expects a whole
+ * number" without saying *which* option is a message that sends someone back to
+ * `--help` to guess.
+ *
+ * @param value - Raw string as typed on the command line
+ * @param floor - Smallest value that makes sense for this option
+ * @param flag - Flag spelling, used in the error message
+ * @returns The parsed number
+ * @throws Error when the value is not a whole number at or above the floor
+ */
+export declare function parseWholeNumberAtLeast(value: string, floor: number, flag: string): number;
+//# sourceMappingURL=numeric-args.d.ts.map

package/dist/numeric-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-args.d.ts","sourceRoot":"","sources":["../src/numeric-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB1F"}

package/dist/numeric-args.js

@@ -0,0 +1,37 @@
+/**
+ * Validation for numeric command-line arguments.
+ *
+ * Deliberately free of any CLI-framework types: the rule is "is this a whole
+ * number at or above a floor", which has nothing to do with Commander. Callers
+ * that need a framework-specific error catch this one and re-raise, which is
+ * what lets a CLI print a usage message while the rule itself stays testable
+ * without a parser.
+ */
+/**
+ * Parse a whole number that must be at or above a floor.
+ *
+ * The error names the flag as the user spelled it, because "expects a whole
+ * number" without saying *which* option is a message that sends someone back to
+ * `--help` to guess.
+ *
+ * @param value - Raw string as typed on the command line
+ * @param floor - Smallest value that makes sense for this option
+ * @param flag - Flag spelling, used in the error message
+ * @returns The parsed number
+ * @throws Error when the value is not a whole number at or above the floor
+ */
+export function parseWholeNumberAtLeast(value, floor, flag) {
+    const invalid = new Error(`${flag} expects a whole number of at least ${String(floor)}; got '${value}'.`);
+    // Number() coercion accepts far more than decimal digits — '' -> 0,
+    // '0x10' -> 16, '1e21' -> a value Number.isInteger still calls whole.
+    // Require plain ASCII digits before ever calling Number() on it.
+    if (!/^\d+$/.test(value)) {
+        throw invalid;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < floor) {
+        throw invalid;
+    }
+    return parsed;
+}
+//# sourceMappingURL=numeric-args.js.map

package/dist/numeric-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-args.js","sourceRoot":"","sources":["../src/numeric-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,KAAa,EAAE,IAAY;IAChF,MAAM,OAAO,GAAG,IAAI,KAAK,CACvB,GAAG,IAAI,uCAAuC,MAAM,CAAC,KAAK,CAAC,UAAU,KAAK,IAAI,CAC/E,CAAC;IAEF,oEAAoE;IACpE,sEAAsE;IACtE,iEAAiE;IACjE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,OAAO,CAAC;IAChB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;QAChD,MAAM,OAAO,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}