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

package/README.md

@@ -24,12 +24,12 @@ The last two columns are the ones that matter when choosing. **"Resolves with ze
 
 | Subpath | Contents | Node builtins reached | Third-party | Resolves with zero deps installed? |
 |---|---|---|---|---|
-| `./path` | `safePath`, `toForwardSlash`, `toNfc`, `isAbsolutePath`, `isAbsoluteAnyPlatform`, `hasParentTraversalSegment`, `toAbsolutePath`, `getRelativePath`, `issueLocation` | `path` only | — | **yes** |
+| `./path` | `safePath`, `toForwardSlash`, `toNfc`, `isAbsolutePath`, `isAbsoluteAnyPlatform`, `hasParentTraversalSegment`, `relativeEscapesRoot`, `isSingleFsSegment`, `toAbsolutePath`, `getRelativePath`, `issueLocation` | `path` only | — | **yes** |
 | `./text` | `decodeTextContent` — the one bytes-to-text seam: BOM-announced UTF-8/UTF-16LE/UTF-16BE/UTF-32LE/UTF-32BE, BOM stripped, UTF-8 assumed otherwise; reports the encoding, whether it was a BOM fact or an assumption, and how many U+FFFD the decode substituted | **none** | — | **yes** |
 | `./zod` | `ZodTypeNames`, `getZodTypeName`, `isZodType`, `unwrapZodType`, `isZodOptional`, `isZodNullable` | **none** | — | **yes** |
 | `./glob` | `isGlob`, static base extraction, magic remainder | `path` only | — | **yes** |
-| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillSiblingNames`, `classifyFilenameCaseFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync` | `fs`, `fs/promises`, `os`, `path`, `url`, `util` | — | **yes** |
-| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
+| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillPathSpellings`, `pathSpellingFrom`, `DirectorySpellingIndex`, `spellingWalkRoot`, `fillRealpaths`, `realpathFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync` | `fs`, `fs/promises`, `os`, `path`, `url`, `util` | — | **yes** |
+| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `createTempDir`, `removeTempDir`, `tempDirTracker`, `CANNOT_DENY_READS`, `buildHostileTree`, `HOSTILE_NAMES`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
 | `./asset` | `resolveAssetReference` — paths and npm bare specifiers | `fs`, `module`, `os`, `path`, `url` | — | **yes** |
 | `./yaml` | `updateYamlIn`, `verifyConfinedYamlEdit` — byte-surgical YAML edits | **none** | `yaml` | no — needs `yaml` |
 | `./process` | `safeExecSync`, `safeExecResult`, `safeExecFromString`, `isToolAvailable`, `getToolVersion`, `hasShellSyntax`, `CommandExecutionError`, `spawnHardened`, `shouldUseShell`, `windowsShellQuote`, `buildWindowsShellLine`, `resolveShellCommandToken`, `isPathLike`, `makeStdioBlocking`, `describeStdioBlocking` | `child_process`, `path` | `@vibe-validate/git`, `which` | no — needs both |
@@ -134,6 +134,8 @@ These always return forward slashes on every platform, so they are safe for comp
 - `getRelativePath()` - relative path between two absolute paths
 - `isAbsolutePath()` / `isAbsoluteAnyPlatform()` - absolute-path predicates
 - `hasParentTraversalSegment()` - detect `..` segments before using a caller-supplied path
+- `relativeEscapesRoot()` - classify a root-relative path (`safePath.relative(root, p)`) as escaping the root: `..`, `../x`, or an absolute answer (Windows cross-drive). Lexical, for identities and reports; a sink asks `isUnderRoot()` instead
+- `isSingleFsSegment()` - true when a caller-supplied NAME can only ever be one entry directly under whatever it is joined to (no separators, not `.`/`..`, no NUL, no drive spelling). `..cache` passes; `../victim` does not
 - `issueLocation()` - format a `file:line`-style location relative to a project root
 
 ⚠️ **`toNfc()` produces a comparison key, never a path to open.** The same visible filename has two
@@ -158,12 +160,24 @@ These return **OS-native** separators, because they resolve real filesystem iden
 - `mkdirSyncReal()` - create a directory and return its real path
 - `resolveFromImportMeta()` - resolve paths relative to an `import.meta.url`
 - `dynamicImportPath()` - `import()` an absolute path (works on Windows, which rejects bare absolute paths)
-- `copyDirectory()`
-- `fillSiblingNames(filePaths, fsCache)` - pass 1 of the case-exact existence check: list the parent
-  directory of every path, de-duplicated by directory and issued concurrently. The only I/O in the pair
-- `classifyFilenameCaseFrom(table, filePath)` - pass 2: pure judgement against the table pass 1 returned,
-  reporting the entry actually on disk when only the case differs. Fill **once** over the whole set and
-  then judge each path — a fill per path reinstates the serialized `readdir` this shape removes
+- `copyDirectory()` - recursive copy that follows a symlinked directory into the tree it points at — contained: a link whose target is outside the source throws `CopyLinkEscapesSourceError`, and a link back into the tree throws `DirectoryWalkRevisitedError`
+- `isUnderRoot(root, candidate)` - the containment verdict a delete/copy/uninstall sink asks, answered by the filesystem: `'inside'` (a strict descendant, realpath-judged), `'outside'` (including the root itself and any symlink that leaves it), or `'absent'` (nothing there yet, and creating it would land inside). Both sides are canonicalized from their deepest existing ancestor, so a root reached through a symlink still contains its members; a refused path throws rather than reading as absent
+- `direntKind(entry)` - what a `Dirent` itself is: `'file' | 'directory' | 'symlink' | 'other'` — the link question asked first, for walks that must not follow (a delete, a size count)
+- `direntKindFollowing(dir, entry)` / `direntKindFollowingSync()` - what a `Dirent` resolves to, one `stat` for a link: `'file' | 'directory' | 'dangling' | 'other'` — for walks over a trusted tree where a link is how the entry got there. Both exist because `isFile()` and `isDirectory()` are BOTH false for a symlink, so a walk that tests only those drops every link silently (`local/dirent-type-needs-symlink-check` refuses that shape)
+- `FollowedWalk` - the cycle guard every following walk holds: `enter(dir)` on the root and each directory recursed into; a directory reached again under a second spelling (a link back into the tree) throws `DirectoryWalkRevisitedError` instead of recursing until the path length runs out
+- `fillPathSpellings(requests, fsCache)` - pass 1 of the case-exact existence check: walk each
+  `{ referrer, target }` from the deepest directory the two share, listing every directory on the way
+  down exactly once. The only I/O in the pair
+- `pathSpellingFrom(table, referrer, target)` - pass 2: pure judgement against the table pass 1
+  returned, reporting the path as disk spells it when the asked-for spelling differs only by case or
+  by Unicode normalization. Fill **once** over the whole set and then judge each reference — a fill
+  per reference reinstates the serialized `readdir` this shape removes.
+  ⚠️ It judges **every component**, not just the basename: judging only the last one hands each
+  directory component back to the host filesystem's own folding, so a link that resolves on
+  macOS/APFS 404s on a case-sensitive filesystem — and a basename-only correction still leaves the
+  author with a broken path
+- `DirectorySpellingIndex` / `spellingWalkRoot(referrer, target)` - the index the pair walks over, and
+  the root it walks from, for a caller that cannot enumerate its targets up front
 - `FsLookupCache` - per-run memo for `realpath`/`readdir`, sharing in-flight promises. Construct one per
   validation run and let it die with the run — never a module-level singleton, or a long-lived process
   answers from a stale directory listing.
@@ -191,6 +205,10 @@ These return **OS-native** separators, because they resolve real filesystem iden
 ### Test helpers — `@vibe-agent-toolkit/utils/testing`
 
 - `setupAsyncTempDirSuite()` / `setupSyncTempDirSuite()` - per-suite temp directories with cleanup
+- `createTempDir()` / `createTempDirAsync()` / `removeTempDir()` / `tempDirTracker()` - the per-call temp-directory primitives; `removeTempDir` refuses, by name, anything not inside the host tmpdir as the filesystem sees it
+- `CANNOT_DENY_READS` / `PERMISSIONS_ENFORCED` - whether a `chmod 000` denies anything on this host (Windows and uid 0 read everything); route through `skip()` so the skip is visible
+- `NODE_EXECUTABLE` / `gitExecutable()` / `resolveExecutable(name)` / `executableCandidates(name, platform, pathext)` - absolute paths for the binaries a fixture spawns: the running node, and `git` found by walking `PATH` once for the first regular executable file (`PATHEXT` names on Windows) and cached. A fixture spawns these instead of a bare `'git'` or `'node'`, so no writable directory on `PATH` decides what runs.
+- `buildHostileTree(base)` / `hostileTreePerTest(prefix)` / `HOSTILE_NAMES` - the one hostile fixture every sink is tested against: a root with a member, a `..`-named member, a symlink pointing out, one pointing in, a dangling one, an alias link to the root, an unreadable directory, a 200-character name, plus a sibling `victim/secret.txt` outside the root; and the table of names (`../victim`, `..`, `.`, `''`, `/victim`, `C:\victim`, a NUL byte, …) a sink must refuse. Fields the host cannot build are `null`
 - `getTestOutputDir()` / `getTestOutputBase()` - isolated test output paths
 - `symlinkCapability()` - probes once (memoized per process) whether this host can create symlinks (Windows needs Developer Mode or `SeCreateSymbolicLinkPrivilege`), returning a `SymlinkCapability` token or `null`
 - `createSymlink()` / `createSymlinkAsync()` - the sanctioned way to create a symlink in test code; both require a `SymlinkCapability` from `symlinkCapability()`, so a test cannot reach the raw syscall without first proving the host supports it (or explicitly skipping via vitest's `skip()`)
@@ -207,10 +225,26 @@ These are CLI-boundary functions: inner libraries should take a root as a parame
 
 They are nonetheless on their own [`./project`](#import-narrowly) entry rather than the barrel alone. The entry was briefly withdrawn on the grounds that the functions fit few repos — which is true, and is what the paragraph above says — but that answered the wrong question. What decides whether an *entry* exists is how heavy the only remaining door is, and barrel-only these four once cost five third-party packages to reach while their own code imports nothing but `node:fs` and `node:path`. Publishing the entry is not a claim that the ladder fits you — only that finding out shouldn't cost a dependency graph. The barrel is dependency-free now, which is that same rule applied everywhere rather than a reason to fold `./project` back in.
 
+### Errors — `@vibe-agent-toolkit/utils` (barrel only)
+
+- `VatError` - the base of every error VAT throws on purpose: `new VatError(code, message, { cause })`. `code` is a stable `SCREAMING_SNAKE` identity a catch block dispatches on; `name` is taken from the subclass.
+- `isVatError(error, code?)` - the dispatch predicate. Reads a `Symbol.for('vat.error')` brand plus `code`, never the prototype chain, so a `dist` copy of a class still matches a `src` instance. A foreign error carrying a `code` (every `node:fs` errno) answers `false`.
+- `prefixMessageOnce(error, prefix)` - prefix a message in place, once per error object — for a seam a retried item passes through more than once, without re-reading the message to find out.
+- `PathEscapesRootError` (on `./path` too) - what `safePath.joinUnderRoot` throws; recognise it with `isVatError(error, PathEscapesRootError.code)`.
+
+Never dispatch on `error.message` — the repo's ESLint config refuses `.message.includes(…)` and friends under `packages/*/src`. Prose is for humans and changes when it is improved; a code changes only when the meaning does.
+
 ### Directory crawling — `@vibe-agent-toolkit/utils/crawl`
 
 - `crawlDirectory()` / `crawlDirectorySync()` - gitignore-aware directory walks
 - `NEVER_CRAWL_GLOBS` / `BUILD_OUTPUT_GLOBS` - the standard exclusion sets
+- `UnreadablePolicy` - the REQUIRED `unreadable` option on every crawl (and on `gitLsFiles` /
+  `gitLsOthers` under `./git`): `{ refuse: { root, remedy } }` throws `DirectoryListingRefusedError`
+  with an adopter-facing, root-relative sentence when a directory cannot be listed;
+  `{ degrade: (refusal) => … }` keeps walking and hands the gap to you to report. There is no
+  default — a shorter list nothing can tell from a complete one is the failure this option exists
+  to prevent, so the caller states which answer is honest for its lane, and an omitted policy is
+  refused up front by name.
 
 Glob *pattern inspection* is a separate entry, `./glob`, and stays that way: `./glob` is dependency-free and reaches only `node:path`, whereas crawling reaches the filesystem, `git`, and `picomatch`.
 

package/dist/asset-reference.js

@@ -74,8 +74,9 @@ function formatActionableError(specifier, baseDir, cause) {
     // but a build step in the target package didn't run (or produced different
     // output). Name the missing file explicitly and point at the publisher.
     if (code === 'MODULE_NOT_FOUND' && missingPath && missingPath !== specifier && isAbsolutePath(missingPath)) {
-        const fileExists = safeExistsSync(missingPath);
-        if (!fileExists) {
+        // `existsSync` answers false for every failure and never throws, so no
+        // guard around it: the question here is only whether the file is there.
+        if (!existsSync(missingPath)) {
             return (`Failed to resolve asset reference '${specifier}': ` +
                 `the package's "exports" map points to '${missingPath}', but that file does not exist on disk.\n` +
                 `Hint: the target package was found, but a build step did not produce this file. ` +
@@ -108,15 +109,6 @@ function extractMissingModulePath(cause) {
     const match = CANNOT_FIND_MODULE_RE.exec(cause.message);
     return match?.[1];
 }
-function safeExistsSync(filePath) {
-    try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a Node-resolved exports target, used only to refine the error message
-        return existsSync(filePath);
-    }
-    catch {
-        return false;
-    }
-}
 function isBareSpecifier(value) {
     return BARE_SPECIFIER_RE.test(value);
 }

package/dist/asset-reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"asset-reference.js","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"asset-reference.js","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3D,uEAAuE;AACvE,wEAAwE;AACxE,uEAAuE;AACvE,cAAc;AACd,MAAM,iBAAiB,GAAG,8CAA8C,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,OAAe;IACtE,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAE5F,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,qEAAqE;QACrE,qEAAqE;QACrE,oEAAoE;QACpE,qBAAqB;QACrB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1D,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAc,EAAE,CAAC,CAAC;IAC/F,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,SAAiB,EAAE,OAAe,EAAE,KAAc;IAC/E,MAAM,QAAQ,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAI,KAAkC,EAAE,IAAI,CAAC;IACvD,MAAM,WAAW,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAEpD,wEAAwE;IACxE,wEAAwE;IACxE,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,IAAI,IAAI,KAAK,kBAAkB,IAAI,WAAW,IAAI,WAAW,KAAK,SAAS,IAAI,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3G,uEAAuE;QACvE,wEAAwE;QACxE,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC7B,OAAO,CACL,sCAAsC,SAAS,KAAK;gBACpD,0CAA0C,WAAW,4CAA4C;gBACjG,kFAAkF;gBAClF,6GAA6G;gBAC7G,mFAAmF;gBACnF,eAAe,QAAQ,EAAE,CAC1B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,IAAI,IAAI,KAAK,+BAA+B,EAAE,CAAC;QAC7C,OAAO,CACL,sCAAsC,SAAS,KAAK;YACpD,yEAAyE;YACzE,wHAAwH;YACxH,eAAe,QAAQ,EAAE,CAC1B,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,OAAO,CACL,sCAAsC,SAAS,MAAM,QAAQ,IAAI;QACjE,0DAA0D,OAAO,GAAG,CACrE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,8BAA8B,CAAC;AAE7D,SAAS,wBAAwB,CAAC,KAAc;IAC9C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxD,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAY;IACpC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACZ,GAAwB,CAAC,IAAI,KAAK,kBAAkB,CACtD,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAY;IACzC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,uEAAuE;QACvE,wDAAwD;QACxD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,OAAO,SAAS,IAAI,GAAG,CAAC,OAAO,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}

package/dist/crawl-timing.d.ts

@@ -115,7 +115,7 @@
  *
  * ⚠️ A rollup that sums a stratum's rows without regard to pass double-counts
  * every nested bracket. That is a real reading hazard, not a hypothetical: it is
- * what `packages/lab/src/facets/crawl/dump.ts` did until 2026-08-15, and it
+ * what `packages/lab/src/facets/crawl/dump.ts` used to do, and it
  * inflated the two arms by DIFFERENT factors, because they nest to different
  * depths. That reader now implements the rule above — `crawlRowRole` there is
  * the executable copy of it — so anyone adding a bracket to this seam should
@@ -204,8 +204,8 @@
  * It carries the process's own wall and CPU lifetime, like the parse dump, and
  * for the same reason: these brackets are wall-timed, so a reader has to be able
  * to see that the process spent its life waiting. It does **not** invite that
- * figure to be summed across processes. `parse-timing.ts`'s review finding of
- * 2026-08-14 records that the lab sums `process.wallMs` across dumps, which
+ * figure to be summed across processes. `parse-timing.ts`'s review finding
+ * records that the lab sums `process.wallMs` across dumps, which
  * double-counts real time under a multi-process verb because the parent
  * orchestrator's lifetime contains every child's. The reader for THIS dump
  * publishes one lifetime per process and never a total — see

package/dist/crawl-timing.js

@@ -115,7 +115,7 @@
  *
  * ⚠️ A rollup that sums a stratum's rows without regard to pass double-counts
  * every nested bracket. That is a real reading hazard, not a hypothetical: it is
- * what `packages/lab/src/facets/crawl/dump.ts` did until 2026-08-15, and it
+ * what `packages/lab/src/facets/crawl/dump.ts` used to do, and it
  * inflated the two arms by DIFFERENT factors, because they nest to different
  * depths. That reader now implements the rule above — `crawlRowRole` there is
  * the executable copy of it — so anyone adding a bracket to this seam should
@@ -204,8 +204,8 @@
  * It carries the process's own wall and CPU lifetime, like the parse dump, and
  * for the same reason: these brackets are wall-timed, so a reader has to be able
  * to see that the process spent its life waiting. It does **not** invite that
- * figure to be summed across processes. `parse-timing.ts`'s review finding of
- * 2026-08-14 records that the lab sums `process.wallMs` across dumps, which
+ * figure to be summed across processes. `parse-timing.ts`'s review finding
+ * records that the lab sums `process.wallMs` across dumps, which
  * double-counts real time under a multi-process verb because the parent
  * orchestrator's lifetime contains every child's. The reader for THIS dump
  * publishes one lifetime per process and never a total — see

package/dist/dirent-kind.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a directory entry IS — with the symlink question asked first.
+ *
+ * A `Dirent` from `readdir(…, { withFileTypes: true })` describes the entry
+ * itself, so for a symlink BOTH `isFile()` and `isDirectory()` are false. A
+ * walk written `if (e.isDirectory()) recurse(); else if (e.isFile()) read();`
+ * therefore neither refuses a link nor follows it: it drops the entry on the
+ * floor without a word. The sweep found staged skill trees, size accounting
+ * and packaging walks with exactly that shape, every one reporting a tree
+ * with a symlink in it as clean. `local/dirent-type-needs-symlink-check`
+ * refuses that shape; these two helpers are what a walk says instead, and
+ * each makes the caller pick a policy by name.
+ *
+ * - {@link direntKind} — lstat semantics. A link is `'symlink'`, never what it
+ *   points at. For a walk that must NOT follow (a delete, a size count of
+ *   what `rm -rf` will remove, a bundle that travels as a tarball).
+ * - {@link direntKindFollowing} — stat semantics. A link is answered by its
+ *   target: `'file'`, `'directory'`, or `'dangling'`. For a walk over a tree
+ *   the caller trusts (its own build output, a dev-mode install, a fixture),
+ *   where a link is simply how the entry got there.
+ *
+ * Neither helper decides for the caller. A `'symlink'` or `'dangling'` that
+ * the caller ignores is still ignored — but it is ignored in a `case` the
+ * reader can see, which is the whole difference.
+ */
+import type { Dirent } from 'node:fs';
+import { VatError } from './errors/vat-error.js';
+/** What the entry itself is. A link is a link. */
+export type DirentKind = 'file' | 'directory' | 'symlink' | 'other';
+/** What the entry resolves to. A link is answered by its target, or is `dangling`. */
+export type FollowedKind = 'file' | 'directory' | 'dangling' | 'other';
+/**
+ * Classify an entry WITHOUT following it.
+ *
+ * @param entry - A `Dirent` from a `withFileTypes` listing
+ * @returns `'symlink'` for any link, else the entry's own type
+ */
+export declare function direntKind(entry: Dirent): DirentKind;
+/**
+ * Classify an entry by what it resolves to, following a link with one `stat`.
+ *
+ * A non-link entry costs no syscall. A link whose target is absent is
+ * `'dangling'`; a link the OS refuses to resolve (`ELOOP`, `EACCES`) is a
+ * refusal, not an absence, and stays loud.
+ *
+ * @param dir - The directory `entry` was listed from
+ * @param entry - A `Dirent` from a `withFileTypes` listing of `dir`
+ * @returns The target's kind, or `'dangling'`
+ */
+export declare function direntKindFollowingSync(dir: string, entry: Dirent): FollowedKind;
+/** The async counterpart of {@link direntKindFollowingSync}. */
+export declare function direntKindFollowing(dir: string, entry: Dirent): Promise<FollowedKind>;
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export declare class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir: string, enteredAs: string);
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export declare class FollowedWalk {
+    #private;
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     */
+    enter(dir: string): void;
+}
+//# sourceMappingURL=dirent-kind.d.ts.map

package/dist/dirent-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirent-kind.d.ts","sourceRoot":"","sources":["../src/dirent-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAKtC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIjD,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpE,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAKpD;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAQhF;AAED,gEAAgE;AAChE,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAQ3F;AAED,wFAAwF;AACxF,qBAAa,2BAA4B,SAAQ,QAAQ;gBAC3C,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;;IAGvB;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAMzB"}

package/dist/dirent-kind.js

@@ -0,0 +1,129 @@
+/**
+ * What a directory entry IS — with the symlink question asked first.
+ *
+ * A `Dirent` from `readdir(…, { withFileTypes: true })` describes the entry
+ * itself, so for a symlink BOTH `isFile()` and `isDirectory()` are false. A
+ * walk written `if (e.isDirectory()) recurse(); else if (e.isFile()) read();`
+ * therefore neither refuses a link nor follows it: it drops the entry on the
+ * floor without a word. The sweep found staged skill trees, size accounting
+ * and packaging walks with exactly that shape, every one reporting a tree
+ * with a symlink in it as clean. `local/dirent-type-needs-symlink-check`
+ * refuses that shape; these two helpers are what a walk says instead, and
+ * each makes the caller pick a policy by name.
+ *
+ * - {@link direntKind} — lstat semantics. A link is `'symlink'`, never what it
+ *   points at. For a walk that must NOT follow (a delete, a size count of
+ *   what `rm -rf` will remove, a bundle that travels as a tarball).
+ * - {@link direntKindFollowing} — stat semantics. A link is answered by its
+ *   target: `'file'`, `'directory'`, or `'dangling'`. For a walk over a tree
+ *   the caller trusts (its own build output, a dev-mode install, a fixture),
+ *   where a link is simply how the entry got there.
+ *
+ * Neither helper decides for the caller. A `'symlink'` or `'dangling'` that
+ * the caller ignores is still ignored — but it is ignored in a `case` the
+ * reader can see, which is the whole difference.
+ */
+import { statSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { isPathAbsentError } from './errors/errno.js';
+import { VatError } from './errors/vat-error.js';
+import { toForwardSlash } from './path-core.js';
+import { normalizePath, safePath } from './path-utils.js';
+/**
+ * Classify an entry WITHOUT following it.
+ *
+ * @param entry - A `Dirent` from a `withFileTypes` listing
+ * @returns `'symlink'` for any link, else the entry's own type
+ */
+export function direntKind(entry) {
+    if (entry.isSymbolicLink())
+        return 'symlink';
+    if (entry.isDirectory())
+        return 'directory';
+    if (entry.isFile())
+        return 'file';
+    return 'other';
+}
+/** The kind a `stat` result reports. */
+function kindOfStats(stats) {
+    if (stats.isDirectory())
+        return 'directory';
+    if (stats.isFile())
+        return 'file';
+    return 'other';
+}
+/**
+ * Classify an entry by what it resolves to, following a link with one `stat`.
+ *
+ * A non-link entry costs no syscall. A link whose target is absent is
+ * `'dangling'`; a link the OS refuses to resolve (`ELOOP`, `EACCES`) is a
+ * refusal, not an absence, and stays loud.
+ *
+ * @param dir - The directory `entry` was listed from
+ * @param entry - A `Dirent` from a `withFileTypes` listing of `dir`
+ * @returns The target's kind, or `'dangling'`
+ */
+export function direntKindFollowingSync(dir, entry) {
+    if (!entry.isSymbolicLink())
+        return kindOfStats(entry);
+    try {
+        return kindOfStats(statSync(safePath.join(dir, entry.name)));
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return 'dangling';
+        throw error;
+    }
+}
+/** The async counterpart of {@link direntKindFollowingSync}. */
+export async function direntKindFollowing(dir, entry) {
+    if (!entry.isSymbolicLink())
+        return kindOfStats(entry);
+    try {
+        return kindOfStats(await fs.stat(safePath.join(dir, entry.name)));
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return 'dangling';
+        throw error;
+    }
+}
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir, enteredAs) {
+        super('DIRECTORY_WALK_REVISITED', `Refusing to enter ${dir}: it is the directory already walked as ${enteredAs} — a symlink leads the walk back into itself.`);
+    }
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export class FollowedWalk {
+    #entered = new Map();
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     */
+    enter(dir) {
+        const real = toForwardSlash(normalizePath(dir));
+        const before = this.#entered.get(real);
+        if (before !== undefined)
+            throw new DirectoryWalkRevisitedError(dir, before);
+        this.#entered.set(real, dir);
+    }
+}
+//# sourceMappingURL=dirent-kind.js.map

package/dist/dirent-kind.js.map

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

package/dist/entrypoint.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The one answer to "am I the script Node was asked to run?"
+ *
+ * Lives here, in the package every other one already depends on, because there
+ * has to be exactly one: the question was previously answered three different
+ * ways across this monorepo (`import.meta.main`, a raw `pathToFileURL` string
+ * compare, and this function), and two of those three answer `false` for the
+ * script they guard — which makes the process exit 0 having run nothing.
+ */
+/**
+ * Was this module invoked as the process entrypoint, rather than imported?
+ *
+ * ⛔ **Do not reach for `import.meta.main` here.** It shipped in Node 24.2 and
+ * 22.18; this repo declares a floor of `>=22.13.0`, and on a real 22.13.0 the
+ * property is `undefined`:
+ *
+ * ```
+ * $ node-v22.13.0 --input-type=module -e "console.log(import.meta.main)"  -> undefined
+ * ```
+ *
+ * That is not a cosmetic gap. Every `if (import.meta.main)` guard in the
+ * dev-tools package was silently dead on the declared floor — running
+ * `validate-repo-structure.ts` under 22.13.0 printed nothing and exited 0, so a
+ * contributor sitting exactly on the supported Node got a green pre-commit
+ * structure gate that had run no rule at all. Raising the floor to 22.18 would
+ * have hidden the defect behind the number instead of fixing it.
+ *
+ * ⛔ **Nor the raw string compare it replaced**, which was the other seven
+ * guards in this repo:
+ *
+ * ```ts
+ * import.meta.url === pathToFileURL(process.argv[1]).href   // ❌
+ * ```
+ *
+ * A `node_modules/.bin` entry is a SYMLINK to the real script, so `argv[1]` is
+ * the link and `import.meta.url` is the resolved target. The two strings differ
+ * and the guard is false — measured false through a `.bin`-style symlink on both
+ * Node 22.14.0 and 24.13.1, where this function is true.
+ *
+ * `process.argv[1]` is defined on every Node this repo supports, so the
+ * comparison below is the portable form of the same question. The realpath pass
+ * covers the case where the script is reached through a symlink on one side of
+ * the comparison but not the other.
+ *
+ * `local/no-fragile-entrypoint-guard` (shipped on this package's `./eslint`
+ * subpath) is what keeps either of the two banned spellings from coming back —
+ * the prose comments that used to stand in for it did not.
+ *
+ * @param importMetaUrl - The calling module's `import.meta.url`
+ * @param entryPath - The invoked script path; defaults to `process.argv[1]`
+ * @returns `true` only when this module is the script Node was asked to run
+ */
+export declare function isEntrypoint(importMetaUrl: string, entryPath?: string | undefined): boolean;
+//# sourceMappingURL=entrypoint.d.ts.map

package/dist/entrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.d.ts","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,MAAM,GAAG,SAA2B,GAC9C,OAAO,CAcT"}

package/dist/entrypoint.js

@@ -0,0 +1,71 @@
+/**
+ * The one answer to "am I the script Node was asked to run?"
+ *
+ * Lives here, in the package every other one already depends on, because there
+ * has to be exactly one: the question was previously answered three different
+ * ways across this monorepo (`import.meta.main`, a raw `pathToFileURL` string
+ * compare, and this function), and two of those three answer `false` for the
+ * script they guard — which makes the process exit 0 having run nothing.
+ */
+import { fileURLToPath } from 'node:url';
+import { safePath, toForwardSlash } from './path-core.js';
+import { normalizePath } from './path-utils.js';
+/**
+ * Was this module invoked as the process entrypoint, rather than imported?
+ *
+ * ⛔ **Do not reach for `import.meta.main` here.** It shipped in Node 24.2 and
+ * 22.18; this repo declares a floor of `>=22.13.0`, and on a real 22.13.0 the
+ * property is `undefined`:
+ *
+ * ```
+ * $ node-v22.13.0 --input-type=module -e "console.log(import.meta.main)"  -> undefined
+ * ```
+ *
+ * That is not a cosmetic gap. Every `if (import.meta.main)` guard in the
+ * dev-tools package was silently dead on the declared floor — running
+ * `validate-repo-structure.ts` under 22.13.0 printed nothing and exited 0, so a
+ * contributor sitting exactly on the supported Node got a green pre-commit
+ * structure gate that had run no rule at all. Raising the floor to 22.18 would
+ * have hidden the defect behind the number instead of fixing it.
+ *
+ * ⛔ **Nor the raw string compare it replaced**, which was the other seven
+ * guards in this repo:
+ *
+ * ```ts
+ * import.meta.url === pathToFileURL(process.argv[1]).href   // ❌
+ * ```
+ *
+ * A `node_modules/.bin` entry is a SYMLINK to the real script, so `argv[1]` is
+ * the link and `import.meta.url` is the resolved target. The two strings differ
+ * and the guard is false — measured false through a `.bin`-style symlink on both
+ * Node 22.14.0 and 24.13.1, where this function is true.
+ *
+ * `process.argv[1]` is defined on every Node this repo supports, so the
+ * comparison below is the portable form of the same question. The realpath pass
+ * covers the case where the script is reached through a symlink on one side of
+ * the comparison but not the other.
+ *
+ * `local/no-fragile-entrypoint-guard` (shipped on this package's `./eslint`
+ * subpath) is what keeps either of the two banned spellings from coming back —
+ * the prose comments that used to stand in for it did not.
+ *
+ * @param importMetaUrl - The calling module's `import.meta.url`
+ * @param entryPath - The invoked script path; defaults to `process.argv[1]`
+ * @returns `true` only when this module is the script Node was asked to run
+ */
+export function isEntrypoint(importMetaUrl, entryPath = process.argv[1]) {
+    // An empty argv[1] would resolve to the cwd and could then match a module by
+    // accident; `undefined` happens under `node -e`. Neither is an entrypoint.
+    if (entryPath === undefined || entryPath === '')
+        return false;
+    const modulePath = safePath.resolve(fileURLToPath(importMetaUrl));
+    const invokedPath = safePath.resolve(entryPath);
+    if (modulePath === invokedPath)
+        return true;
+    // `normalizePath` resolves symlinks and Windows 8.3 short names, and returns
+    // the path unchanged when it cannot — which is the right answer here, since
+    // the string comparison above has already decided the two differ and an
+    // unresolvable path carries no symlink information to compare.
+    return toForwardSlash(normalizePath(modulePath)) === toForwardSlash(normalizePath(invokedPath));
+}
+//# sourceMappingURL=entrypoint.js.map

package/dist/entrypoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.js","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,UAAU,YAAY,CAC1B,aAAqB,EACrB,YAAgC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE/C,6EAA6E;IAC7E,2EAA2E;IAC3E,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAE9D,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;IAClE,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAE5C,6EAA6E;IAC7E,4EAA4E;IAC5E,wEAAwE;IACxE,+DAA+D;IAC/D,OAAO,cAAc,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,KAAK,cAAc,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;AAClG,CAAC"}

package/dist/env-flag.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function parseEnvBoolean(raw: string | undefined): boolean | undefined;
+//# sourceMappingURL=env-flag.d.ts.map

package/dist/env-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-flag.d.ts","sourceRoot":"","sources":["../src/env-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAM5E"}