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

package/dist/path-core.d.ts

@@ -10,6 +10,26 @@
  * `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`) live in
  * `./path-utils.ts` and are exposed via the `./fs` entry.
  */
+import { VatError } from './errors/vat-error.js';
+/**
+ * Thrown by {@link safePath.joinUnderRoot} when the joined path would land
+ * outside its root.
+ *
+ * A class with a code rather than a prefixed sentence: three packages used to
+ * recognise this refusal with `error.message.startsWith('safePath.joinUnderRoot:')`,
+ * which is a contract on prose. Dispatch with
+ * `isVatError(error, PathEscapesRootError.code)` — it survives the `src`/`dist`
+ * boundary that `instanceof` does not.
+ */
+export declare class PathEscapesRootError extends VatError {
+    /** The code every instance carries, for `isVatError(error, PathEscapesRootError.code)`. */
+    static readonly code = "PATH_ESCAPES_ROOT";
+    /**
+     * @param root - The root the path had to stay under
+     * @param detail - Which segment, or which result, escaped it
+     */
+    constructor(root: string, detail: string);
+}
 /**
  * Check if a path is absolute
  *
@@ -44,8 +64,9 @@ export declare function isAbsoluteAnyPlatform(p: string): boolean;
 /**
  * True if `p` contains a `..` parent-directory traversal segment.
  *
- * Forward-slash-normalized, then inspects each `/`-delimited segment — so a
- * `..` is caught regardless of the original OS separator. A containment guard
+ * Backslashes are read as separators on every host (the input is author-written
+ * config), then each `/`-delimited segment is inspected — so a `..` is caught
+ * regardless of the separator the author typed. A containment guard
  * for config-supplied relative paths (skill `files:` dest values, glob magic
  * remainders) that must never climb above their anchor directory.
  *
@@ -56,13 +77,66 @@ export declare function isAbsoluteAnyPlatform(p: string): boolean;
  * hasParentTraversalSegment('a..b/c')      // false (".." must be a whole segment)
  */
 export declare function hasParentTraversalSegment(p: string): boolean;
+/**
+ * True when a root-relative path — as `safePath.relative(root, p)` spells it —
+ * names something the root does not contain.
+ *
+ * The three shapes `path.relative` can return for an outsider: the parent
+ * itself (`..`), a climb through it (`../x`), and, on Windows only, an
+ * absolute path (a target on another drive has no relative spelling). A name
+ * that merely BEGINS with two dots (`..notes.md`) is a member and reads as one;
+ * the bare `startsWith('..')` this replaces refused it, dropped the file from
+ * the package and unlinked the reference, at exit 0.
+ *
+ * ⚠️ **Lexical, on purpose.** This classifies a relative path that was already
+ * computed; it does not ask the filesystem, so a symlink inside the root that
+ * points outside reads as inside here. That is the right answer for the
+ * callers that own no root to ask about — a projection identity, a permission
+ * pattern, a report relativizer — and the WRONG one for a delete or copy sink,
+ * which must ask {@link isUnderRoot} from `@vibe-agent-toolkit/utils` instead.
+ * The empty relative (the root itself) is not an escape; whether equality is
+ * acceptable is the caller's question and is asked beside this one.
+ *
+ * @param normalizedRelative - A forward-slashed root-relative path
+ * @returns True when the root does not contain it
+ *
+ * @example
+ * relativeEscapesRoot(safePath.relative(root, p))   // the whole idiom
+ * relativeEscapesRoot('../x')       // true
+ * relativeEscapesRoot('..notes.md') // false — a member whose name starts with dots
+ */
+export declare function relativeEscapesRoot(normalizedRelative: string): boolean;
+/**
+ * True when `name` can only ever be ONE directory entry under whatever it is
+ * joined to: non-empty, not `.` or `..`, no separator of either platform, no
+ * NUL, no drive-letter prefix.
+ *
+ * The check for a caller-controlled NAME — a skill name from a manifest, a
+ * session id, a positional the user typed — that is about to become
+ * `join(root, name)`. A name is not a path: `..cache` and `a..b` are legitimate
+ * entries, and `includes('..')` refused them while `startsWith` let `x/../..`
+ * through. The question is whether the join can land anywhere but directly
+ * under `root`, and that is answered by the segment's shape alone, with no
+ * filesystem — which is also why this belongs beside the path helpers rather
+ * than beside {@link isUnderRoot}, which is the check for a PATH.
+ *
+ * @param name - The proposed entry name
+ * @returns True when `join(root, name)` is a direct child of `root`
+ *
+ * @example
+ * isSingleFsSegment('my-skill')   // true
+ * isSingleFsSegment('..cache')    // true — dots inside a name are just dots
+ * isSingleFsSegment('../victim')  // false
+ * isSingleFsSegment('..')         // false
+ */
+export declare function isSingleFsSegment(name: string): boolean;
 /**
  * Compute a `ValidationIssue.location`: an absolute source file path made
  * relative to the scan/project root, forward-slashed.
  *
  * This is the ONE relativizer every VAT validation lane uses. `location` is
  * contractually project-relative (see `ValidationIssue` in
- * `@vibe-agent-toolkit/agent-schema`), so producers must route through here
+ * `@vibe-agent-toolkit/schema`), so producers must route through here
  * rather than emitting `skillPath` directly — absolute locations leak the
  * developer's home directory into CI logs and make `validation.allow` globs,
  * which match against `location`, unwritable.
@@ -115,23 +189,42 @@ export declare function toAbsolutePath(p: string, baseDir: string): string;
  */
 export declare function getRelativePath(from: string, to: string): string;
 /**
- * Convert a path to forward slashes
+ * Convert a NATIVE path — one the filesystem, `path.*`, `readdir` or git
+ * handed you — to forward slashes.
  *
- * Windows accepts both forward slashes and backslashes as path separators.
- * This function normalizes all paths to use forward slashes for consistency.
- * Useful for glob pattern matching, cross-platform comparisons, and string operations.
+ * Converts only where a backslash is a separator (win32). On POSIX a backslash is a
+ * legal filename character, so `docs/x\y.md` is one file and is returned
+ * unchanged: converting it would invent a phantom `docs/x/` directory and, in
+ * {@link safePath.joinUnderRoot}, turn an `x\..\..` NAME into a climb.
  *
- * @param p - Path to convert
- * @returns Path with forward slashes
+ * For AUTHOR-WRITTEN text — an href, a glob, a config value, a CLI argument,
+ * an archive entry name — whose backslashes must read as separators on every
+ * host, use {@link toForwardSlashAnyPlatform}.
  *
- * @example
- * toForwardSlash('C:\\Users\\docs\\README.md')
- * // Returns: 'C:/Users/docs/README.md'
+ * @param p - A native path
+ * @returns The path with forward slashes (identity on POSIX)
  *
- * toForwardSlash('/project/docs/README.md')
- * // Returns: '/project/docs/README.md' (unchanged)
+ * @example
+ * toForwardSlash('C:\\Users\\docs\\README.md') // win32: 'C:/Users/docs/README.md'
+ * toForwardSlash('docs/x\\y.md')                // POSIX: 'docs/x\\y.md' (unchanged)
  */
 export declare function toForwardSlash(p: string): string;
+/**
+ * Convert every backslash to a forward slash, on every host.
+ *
+ * For AUTHOR-WRITTEN text that may carry Windows spellings regardless of where
+ * VAT runs — markdown hrefs, globs, config values, CLI arguments, zip entry
+ * names — and for containment guards that must refuse `..\x` everywhere.
+ * Never use it on a path read from the filesystem or git: on POSIX that
+ * backslash is part of a filename. Use {@link toForwardSlash} for those.
+ *
+ * @param text - Author-written path text
+ * @returns The text with every backslash replaced by `/`
+ *
+ * @example
+ * toForwardSlashAnyPlatform('..\\evil')   // '../evil' on every host
+ */
+export declare function toForwardSlashAnyPlatform(text: string): string;
 /**
  * Normalize text to Unicode NFC — the form in which two *visually identical*
  * filenames compare equal.
@@ -166,12 +259,14 @@ export declare function toNfc(value: string): string;
  * Cross-platform safe path operations.
  *
  * Wraps Node's `path.join()`, `path.resolve()`, and `path.relative()` to always
- * return forward-slash paths. On Windows, the native `path.*` functions return
+ * return forward-slash paths (converted through {@link toForwardSlash}, so a
+ * backslash inside a POSIX filename survives). On Windows, the native `path.*` functions return
  * backslashes, which causes bugs when paths are used as Map keys, compared as
  * strings, or matched with glob patterns.
  *
  * **Use these instead of importing from `node:path` directly.**
- * ESLint rules enforce this — see `no-path-join`, `no-path-resolve`, `no-path-relative`.
+ * An ESLint rule enforces this — see `no-raw-node-path` (its `functions` option
+ * table maps each of `join`/`resolve`/`relative` to its `safePath.*` replacement).
  *
  * @example
  * ```typescript
@@ -182,7 +277,7 @@ export declare function toNfc(value: string): string;
  * safePath.resolve('/project', './docs')                   // → '/project/docs'
  * safePath.relative('/project/docs', '/project')           // → '..'
  * safePath.joinUnderRoot('/harness', 'skill-abc')          // → '/harness/skill-abc'
- * safePath.joinUnderRoot('/harness', '../escape')          // throws Error
+ * safePath.joinUnderRoot('/harness', '../escape')          // throws PathEscapesRootError
  * ```
  */
 export declare const safePath: {
@@ -210,7 +305,7 @@ export declare const safePath: {
      * skill-test staging code was vulnerable to on Windows.
      *
      * @returns Forward-slash absolute path guaranteed to be inside `root`.
-     * @throws {Error} If the resolved path would escape `root`.
+     * @throws {PathEscapesRootError} If the resolved path would escape `root`.
      *
      * @example
      * ```typescript

package/dist/path-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-core.d.ts","sourceRoot":"","sources":["../src/path-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,QAAQ;IACnB,6DAA6D;8BAC9C,MAAM,EAAE,KAAG,MAAM;IAIhC,gEAAgE;iCAC9C,MAAM,EAAE,KAAG,MAAM;IAInC,iEAAiE;8BAClD,MAAM,MAAM,MAAM,KAAG,MAAM;IAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;mCACiB,MAAM,eAAe,MAAM,EAAE,KAAG,MAAM;CAuClD,CAAC"}
+{"version":3,"file":"path-core.d.ts","sourceRoot":"","sources":["../src/path-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,2FAA2F;IAC3F,MAAM,CAAC,QAAQ,CAAC,IAAI,uBAAuB;IAE3C;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAGzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAGvE;AAKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAMhE;AAKD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ;IACnB,6DAA6D;8BAC9C,MAAM,EAAE,KAAG,MAAM;IAIhC,gEAAgE;iCAC9C,MAAM,EAAE,KAAG,MAAM;IAInC,iEAAiE;8BAClD,MAAM,MAAM,MAAM,KAAG,MAAM;IAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;mCACiB,MAAM,eAAe,MAAM,EAAE,KAAG,MAAM;CAiClD,CAAC"}

package/dist/path-core.js

@@ -11,6 +11,28 @@
  * `./path-utils.ts` and are exposed via the `./fs` entry.
  */
 import path from 'node:path';
+import { VatError } from './errors/vat-error.js';
+/**
+ * Thrown by {@link safePath.joinUnderRoot} when the joined path would land
+ * outside its root.
+ *
+ * A class with a code rather than a prefixed sentence: three packages used to
+ * recognise this refusal with `error.message.startsWith('safePath.joinUnderRoot:')`,
+ * which is a contract on prose. Dispatch with
+ * `isVatError(error, PathEscapesRootError.code)` — it survives the `src`/`dist`
+ * boundary that `instanceof` does not.
+ */
+export class PathEscapesRootError extends VatError {
+    /** The code every instance carries, for `isVatError(error, PathEscapesRootError.code)`. */
+    static code = 'PATH_ESCAPES_ROOT';
+    /**
+     * @param root - The root the path had to stay under
+     * @param detail - Which segment, or which result, escaped it
+     */
+    constructor(root, detail) {
+        super(PathEscapesRootError.code, `safePath.joinUnderRoot: ${detail} escapes root "${root}".`);
+    }
+}
 /**
  * Check if a path is absolute
  *
@@ -49,8 +71,9 @@ export function isAbsoluteAnyPlatform(p) {
 /**
  * True if `p` contains a `..` parent-directory traversal segment.
  *
- * Forward-slash-normalized, then inspects each `/`-delimited segment — so a
- * `..` is caught regardless of the original OS separator. A containment guard
+ * Backslashes are read as separators on every host (the input is author-written
+ * config), then each `/`-delimited segment is inspected — so a `..` is caught
+ * regardless of the separator the author typed. A containment guard
  * for config-supplied relative paths (skill `files:` dest values, glob magic
  * remainders) that must never climb above their anchor directory.
  *
@@ -61,7 +84,74 @@ export function isAbsoluteAnyPlatform(p) {
  * hasParentTraversalSegment('a..b/c')      // false (".." must be a whole segment)
  */
 export function hasParentTraversalSegment(p) {
-    return toForwardSlash(p).split('/').includes('..');
+    // eslint-disable-next-line local/no-dotdot-containment -- this IS the one lexical `..`-segment test the rule points to; it classifies a config-supplied RELATIVE spelling before any root exists to ask the filesystem about. Sinks use isUnderRoot().
+    return toForwardSlashAnyPlatform(p).split('/').includes('..');
+}
+/**
+ * True when a root-relative path — as `safePath.relative(root, p)` spells it —
+ * names something the root does not contain.
+ *
+ * The three shapes `path.relative` can return for an outsider: the parent
+ * itself (`..`), a climb through it (`../x`), and, on Windows only, an
+ * absolute path (a target on another drive has no relative spelling). A name
+ * that merely BEGINS with two dots (`..notes.md`) is a member and reads as one;
+ * the bare `startsWith('..')` this replaces refused it, dropped the file from
+ * the package and unlinked the reference, at exit 0.
+ *
+ * ⚠️ **Lexical, on purpose.** This classifies a relative path that was already
+ * computed; it does not ask the filesystem, so a symlink inside the root that
+ * points outside reads as inside here. That is the right answer for the
+ * callers that own no root to ask about — a projection identity, a permission
+ * pattern, a report relativizer — and the WRONG one for a delete or copy sink,
+ * which must ask {@link isUnderRoot} from `@vibe-agent-toolkit/utils` instead.
+ * The empty relative (the root itself) is not an escape; whether equality is
+ * acceptable is the caller's question and is asked beside this one.
+ *
+ * @param normalizedRelative - A forward-slashed root-relative path
+ * @returns True when the root does not contain it
+ *
+ * @example
+ * relativeEscapesRoot(safePath.relative(root, p))   // the whole idiom
+ * relativeEscapesRoot('../x')       // true
+ * relativeEscapesRoot('..notes.md') // false — a member whose name starts with dots
+ */
+export function relativeEscapesRoot(normalizedRelative) {
+    // eslint-disable-next-line local/no-dotdot-containment -- this IS the one lexical relative-path classifier the rule points to; every former copy of this pair now calls here. Sinks use isUnderRoot().
+    return normalizedRelative === '..' || normalizedRelative.startsWith('../') || isAbsoluteAnyPlatform(normalizedRelative);
+}
+/** A Windows drive-relative spelling (`C:`) — `path.resolve` sends it to that drive's cwd. */
+const DRIVE_RELATIVE = /^[A-Za-z]:/u;
+/**
+ * True when `name` can only ever be ONE directory entry under whatever it is
+ * joined to: non-empty, not `.` or `..`, no separator of either platform, no
+ * NUL, no drive-letter prefix.
+ *
+ * The check for a caller-controlled NAME — a skill name from a manifest, a
+ * session id, a positional the user typed — that is about to become
+ * `join(root, name)`. A name is not a path: `..cache` and `a..b` are legitimate
+ * entries, and `includes('..')` refused them while `startsWith` let `x/../..`
+ * through. The question is whether the join can land anywhere but directly
+ * under `root`, and that is answered by the segment's shape alone, with no
+ * filesystem — which is also why this belongs beside the path helpers rather
+ * than beside {@link isUnderRoot}, which is the check for a PATH.
+ *
+ * @param name - The proposed entry name
+ * @returns True when `join(root, name)` is a direct child of `root`
+ *
+ * @example
+ * isSingleFsSegment('my-skill')   // true
+ * isSingleFsSegment('..cache')    // true — dots inside a name are just dots
+ * isSingleFsSegment('../victim')  // false
+ * isSingleFsSegment('..')         // false
+ */
+export function isSingleFsSegment(name) {
+    return (name !== '' &&
+        name !== '.' &&
+        name !== '..' &&
+        !name.includes('/') &&
+        !name.includes('\\') &&
+        !name.includes('\0') &&
+        !DRIVE_RELATIVE.test(name));
 }
 /**
  * Compute a `ValidationIssue.location`: an absolute source file path made
@@ -69,7 +159,7 @@ export function hasParentTraversalSegment(p) {
  *
  * This is the ONE relativizer every VAT validation lane uses. `location` is
  * contractually project-relative (see `ValidationIssue` in
- * `@vibe-agent-toolkit/agent-schema`), so producers must route through here
+ * `@vibe-agent-toolkit/schema`), so producers must route through here
  * rather than emitting `skillPath` directly — absolute locations leak the
  * developer's home directory into CI logs and make `validation.allow` globs,
  * which match against `location`, unwritable.
@@ -133,25 +223,49 @@ export function getRelativePath(from, to) {
     // Calculate relative path from source directory to target file
     return toForwardSlash(path.relative(fromDir, to));
 }
+/** True on hosts (win32) where a backslash is a path separator; everywhere else it is a filename character. */
+const BACKSLASH_IS_NATIVE_SEPARATOR = path.sep === '\\';
 /**
- * Convert a path to forward slashes
+ * Convert a NATIVE path — one the filesystem, `path.*`, `readdir` or git
+ * handed you — to forward slashes.
  *
- * Windows accepts both forward slashes and backslashes as path separators.
- * This function normalizes all paths to use forward slashes for consistency.
- * Useful for glob pattern matching, cross-platform comparisons, and string operations.
+ * Converts only where a backslash is a separator (win32). On POSIX a backslash is a
+ * legal filename character, so `docs/x\y.md` is one file and is returned
+ * unchanged: converting it would invent a phantom `docs/x/` directory and, in
+ * {@link safePath.joinUnderRoot}, turn an `x\..\..` NAME into a climb.
  *
- * @param p - Path to convert
- * @returns Path with forward slashes
+ * For AUTHOR-WRITTEN text — an href, a glob, a config value, a CLI argument,
+ * an archive entry name — whose backslashes must read as separators on every
+ * host, use {@link toForwardSlashAnyPlatform}.
  *
- * @example
- * toForwardSlash('C:\\Users\\docs\\README.md')
- * // Returns: 'C:/Users/docs/README.md'
+ * @param p - A native path
+ * @returns The path with forward slashes (identity on POSIX)
  *
- * toForwardSlash('/project/docs/README.md')
- * // Returns: '/project/docs/README.md' (unchanged)
+ * @example
+ * toForwardSlash('C:\\Users\\docs\\README.md') // win32: 'C:/Users/docs/README.md'
+ * toForwardSlash('docs/x\\y.md')                // POSIX: 'docs/x\\y.md' (unchanged)
  */
 export function toForwardSlash(p) {
-    return p.replaceAll('\\', '/');
+    return BACKSLASH_IS_NATIVE_SEPARATOR ? toForwardSlashAnyPlatform(p) : p;
+}
+/**
+ * Convert every backslash to a forward slash, on every host.
+ *
+ * For AUTHOR-WRITTEN text that may carry Windows spellings regardless of where
+ * VAT runs — markdown hrefs, globs, config values, CLI arguments, zip entry
+ * names — and for containment guards that must refuse `..\x` everywhere.
+ * Never use it on a path read from the filesystem or git: on POSIX that
+ * backslash is part of a filename. Use {@link toForwardSlash} for those.
+ *
+ * @param text - Author-written path text
+ * @returns The text with every backslash replaced by `/`
+ *
+ * @example
+ * toForwardSlashAnyPlatform('..\\evil')   // '../evil' on every host
+ */
+export function toForwardSlashAnyPlatform(text) {
+    // eslint-disable-next-line local/no-manual-path-normalize -- this IS the converter the rule's autofix writes; it cannot call itself.
+    return text.replaceAll('\\', '/');
 }
 /**
  * Normalize text to Unicode NFC — the form in which two *visually identical*
@@ -189,12 +303,14 @@ export function toNfc(value) {
  * Cross-platform safe path operations.
  *
  * Wraps Node's `path.join()`, `path.resolve()`, and `path.relative()` to always
- * return forward-slash paths. On Windows, the native `path.*` functions return
+ * return forward-slash paths (converted through {@link toForwardSlash}, so a
+ * backslash inside a POSIX filename survives). On Windows, the native `path.*` functions return
  * backslashes, which causes bugs when paths are used as Map keys, compared as
  * strings, or matched with glob patterns.
  *
  * **Use these instead of importing from `node:path` directly.**
- * ESLint rules enforce this — see `no-path-join`, `no-path-resolve`, `no-path-relative`.
+ * An ESLint rule enforces this — see `no-raw-node-path` (its `functions` option
+ * table maps each of `join`/`resolve`/`relative` to its `safePath.*` replacement).
  *
  * @example
  * ```typescript
@@ -205,7 +321,7 @@ export function toNfc(value) {
  * safePath.resolve('/project', './docs')                   // → '/project/docs'
  * safePath.relative('/project/docs', '/project')           // → '..'
  * safePath.joinUnderRoot('/harness', 'skill-abc')          // → '/harness/skill-abc'
- * safePath.joinUnderRoot('/harness', '../escape')          // throws Error
+ * safePath.joinUnderRoot('/harness', '../escape')          // throws PathEscapesRootError
  * ```
  */
 export const safePath = {
@@ -239,7 +355,7 @@ export const safePath = {
      * skill-test staging code was vulnerable to on Windows.
      *
      * @returns Forward-slash absolute path guaranteed to be inside `root`.
-     * @throws {Error} If the resolved path would escape `root`.
+     * @throws {PathEscapesRootError} If the resolved path would escape `root`.
      *
      * @example
      * ```typescript
@@ -255,12 +371,12 @@ export const safePath = {
         // BEFORE resolving, so the error message can name the offending segment.
         for (const seg of segments) {
             if (path.isAbsolute(seg)) {
-                throw new Error(`safePath.joinUnderRoot: segment "${seg}" is absolute and escapes root "${root}".`);
+                throw new PathEscapesRootError(root, `segment "${seg}" is absolute and`);
             }
             // Windows drive-letter check for POSIX hosts (path.isAbsolute won't catch
             // 'C:\...' on POSIX, but node's path.win32.isAbsolute does).
             if (path.win32.isAbsolute(seg)) {
-                throw new Error(`safePath.joinUnderRoot: segment "${seg}" contains a Windows drive letter and escapes root "${root}".`);
+                throw new PathEscapesRootError(root, `segment "${seg}" contains a Windows drive letter and`);
             }
         }
         const resolvedRoot = path.resolve(root);
@@ -275,7 +391,7 @@ export const safePath = {
         // which would match '/rootEvil' when root is '/root').
         const rootPrefix = fwdRoot.endsWith('/') ? fwdRoot : `${fwdRoot}/`;
         if (fwdResult !== fwdRoot && !fwdResult.startsWith(rootPrefix)) {
-            throw new Error(`safePath.joinUnderRoot: result "${fwdResult}" escapes root "${fwdRoot}".`);
+            throw new PathEscapesRootError(fwdRoot, `result "${fwdResult}"`);
         }
         return fwdResult;
     },

package/dist/path-core.js.map

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

package/dist/path-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAOlD;;;;;;;;;;GAUG;AACH,cAAc,gBAAgB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CA+BxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAezC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,CAiBR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhF"}
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAQlD;;;;;;;;;;GAUG;AACH,cAAc,gBAAgB,CAAC;AAmC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,CAIR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhF"}

package/dist/path-utils.js

@@ -2,6 +2,7 @@ import { mkdirSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isPathAbsentError } from './errors/errno.js';
 import { safePath } from './path-core.js';
 /**
  * Re-export every pure path helper so the package barrel keeps exposing the
@@ -15,6 +16,42 @@ import { safePath } from './path-core.js';
  * `test/path-fs-subpaths.test.ts`).
  */
 export * from './path-core.js';
+/**
+ * `realpathSync.native(target)`, or `target` itself when there is nothing at
+ * that path to canonicalize.
+ *
+ * Absence is the ONLY failure answered with the lexical path: `normalizePath`
+ * is documented to accept a path that does not exist, and a path that does not
+ * exist has no realpath. Everything else — `EACCES` on an ancestor, `ELOOP` on
+ * a symlink cycle, `ENAMETOOLONG` — is the filesystem refusing a path that IS
+ * there. Those used to come back as the lexical spelling with nothing to say
+ * so, which put a lexical path where every caller compares canonical ones: a
+ * containment check judged such a path by the spelling the OS had just refused
+ * to resolve. They stay loud.
+ *
+ * The JS `realpathSync` is asked before absence is concluded, because the
+ * native call can fail where the JS walk succeeds — Node's docs note that on a
+ * musl libc without procfs the native `realpath(3)` cannot work at all, and it
+ * reports that as `ENOENT` for a path that exists. Only when both agree that
+ * nothing is there is the lexical path the answer.
+ */
+function realpathOrSelf(target) {
+    try {
+        return realpathSync.native(target);
+    }
+    catch (error) {
+        if (!isPathAbsentError(error))
+            throw error;
+    }
+    try {
+        return realpathSync(target);
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return target;
+        throw error;
+    }
+}
 /**
  * Normalize any path (resolve short names on Windows)
  *
@@ -65,21 +102,9 @@ export function normalizePath(...paths) {
     else {
         resolved = path.resolve(...paths);
     }
-    try {
-        // Use native OS realpath for better Windows compatibility
-        return realpathSync.native(resolved);
-    }
-    catch {
-        // Fallback to regular realpathSync
-        try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- Safe: resolved is from path.resolve
-            return realpathSync(resolved);
-        }
-        catch {
-            // Last resort: return resolved path (better than original input)
-            return resolved;
-        }
-    }
+    // Native OS realpath first (resolves Windows short names); a path that is not
+    // there is answered with `resolved` — better than the original input.
+    return realpathOrSelf(resolved);
 }
 /**
  * Get normalized temp directory path
@@ -107,22 +132,7 @@ export function normalizePath(...paths) {
  * ```
  */
 export function normalizedTmpdir() {
-    const temp = tmpdir();
-    try {
-        // Use native OS realpath for better Windows compatibility
-        return realpathSync.native(temp);
-    }
-    catch {
-        // Fallback to regular realpathSync
-        try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- Safe: temp is from tmpdir()
-            return realpathSync(temp);
-        }
-        catch {
-            // Last resort: return original
-            return temp;
-        }
-    }
+    return realpathOrSelf(tmpdir());
 }
 /**
  * Create directory and return normalized path
@@ -156,23 +166,8 @@ export function normalizedTmpdir() {
  * ```
  */
 export function mkdirSyncReal(dirPath, options) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- This IS the mkdirSyncReal() implementation
     mkdirSync(dirPath, options);
-    try {
-        // Use native OS realpath for better Windows compatibility
-        return realpathSync.native(dirPath);
-    }
-    catch {
-        // Fallback to regular realpathSync
-        try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- Safe: dirPath is function parameter
-            return realpathSync(dirPath);
-        }
-        catch {
-            // Last resort: return original
-            return dirPath;
-        }
-    }
+    return realpathOrSelf(dirPath);
 }
 /**
  * Resolve an OS-native absolute path from an ESM module's `import.meta.url` and

package/dist/path-utils.js.map

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

package/dist/path.d.ts

@@ -8,5 +8,5 @@
  * If you need `normalizedTmpdir`, `mkdirSyncReal`, or `normalizePath`, those
  * touch the filesystem — import them from `@vibe-agent-toolkit/utils/fs`.
  */
-export { safePath, toForwardSlash, toNfc, isAbsolutePath, isAbsoluteAnyPlatform, hasParentTraversalSegment, toAbsolutePath, getRelativePath, issueLocation, } from './path-core.js';
+export { PathEscapesRootError, safePath, toForwardSlash, toForwardSlashAnyPlatform, toNfc, isAbsolutePath, isAbsoluteAnyPlatform, hasParentTraversalSegment, isSingleFsSegment, relativeEscapesRoot, toAbsolutePath, getRelativePath, issueLocation, } from './path-core.js';
 //# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,QAAQ,EACR,cAAc,EACd,KAAK,EACL,cAAc,EACd,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,yBAAyB,EACzB,KAAK,EACL,cAAc,EACd,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,gBAAgB,CAAC"}

package/dist/path.js

@@ -8,5 +8,5 @@
  * If you need `normalizedTmpdir`, `mkdirSyncReal`, or `normalizePath`, those
  * touch the filesystem — import them from `@vibe-agent-toolkit/utils/fs`.
  */
-export { safePath, toForwardSlash, toNfc, isAbsolutePath, isAbsoluteAnyPlatform, hasParentTraversalSegment, toAbsolutePath, getRelativePath, issueLocation, } from './path-core.js';
+export { PathEscapesRootError, safePath, toForwardSlash, toForwardSlashAnyPlatform, toNfc, isAbsolutePath, isAbsoluteAnyPlatform, hasParentTraversalSegment, isSingleFsSegment, relativeEscapesRoot, toAbsolutePath, getRelativePath, issueLocation, } from './path-core.js';
 //# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -1 +1 @@
-{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,QAAQ,EACR,cAAc,EACd,KAAK,EACL,cAAc,EACd,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,yBAAyB,EACzB,KAAK,EACL,cAAc,EACd,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,gBAAgB,CAAC"}