@openclaw/fs-safe 0.4.7 → 0.5.0

package/dist/root-path-existing.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { isNotFoundPathError } from "./path.js";
+function isFilesystemRoot(candidate) {
+    return path.parse(candidate).root === candidate;
+}
+async function pathExists(targetPath) {
+    try {
+        await fsp.lstat(targetPath);
+        return true;
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function resolvePathViaExistingAncestor(targetPath) {
+    const normalized = path.resolve(targetPath);
+    let cursor = normalized;
+    const missingSuffix = [];
+    while (!isFilesystemRoot(cursor) && !(await pathExists(cursor))) {
+        missingSuffix.unshift(path.basename(cursor));
+        const parent = path.dirname(cursor);
+        if (parent === cursor) {
+            break;
+        }
+        cursor = parent;
+    }
+    if (!(await pathExists(cursor))) {
+        return normalized;
+    }
+    try {
+        const resolvedAncestor = path.resolve(await fsp.realpath(cursor));
+        return missingSuffix.length === 0
+            ? resolvedAncestor
+            : path.resolve(resolvedAncestor, ...missingSuffix);
+    }
+    catch {
+        return normalized;
+    }
+}
+export function resolvePathViaExistingAncestorSync(targetPath) {
+    const normalized = path.resolve(targetPath);
+    let cursor = normalized;
+    const missingSuffix = [];
+    while (!isFilesystemRoot(cursor) && !fs.existsSync(cursor)) {
+        missingSuffix.unshift(path.basename(cursor));
+        const parent = path.dirname(cursor);
+        if (parent === cursor) {
+            break;
+        }
+        cursor = parent;
+    }
+    if (!fs.existsSync(cursor)) {
+        return normalized;
+    }
+    try {
+        const resolvedAncestor = path.resolve(fs.realpathSync(cursor));
+        return missingSuffix.length === 0
+            ? resolvedAncestor
+            : path.resolve(resolvedAncestor, ...missingSuffix);
+    }
+    catch {
+        return normalized;
+    }
+}

package/dist/root-path.d.ts

@@ -1,3 +1,4 @@
+export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
 type RootPathIntent = "read" | "write" | "create" | "delete" | "stat";
 export type RootPathAliasPolicy = {
     allowFinalSymlinkForUnlink?: boolean;
@@ -34,6 +35,4 @@ export type ResolvedRootPath = {
 };
 export declare function resolveRootPath(params: ResolveRootPathParams): Promise<ResolvedRootPath>;
 export declare function resolveRootPathSync(params: ResolveRootPathParams): ResolvedRootPath;
-export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;
-export {};
 //# sourceMappingURL=root-path.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAMA,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;aACnC,MAAM;;;;aAIN,YAAY;;;;CAIJ,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CA+BnF;AAmkBD,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA6B7E"}
+{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,kCAAkC,EAAE,MAAM,yBAAyB,CAAC;AAE7E,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;aACnC,MAAM;;;;aAIN,YAAY;;;;CAIJ,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CA+BnF"}

package/dist/root-path.js

@@ -3,6 +3,8 @@ import fsp from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { isNotFoundPathError, isPathInside, isPathRelativeEscape } from "./path.js";
+import { resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
+export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
 export const ROOT_PATH_ALIAS_POLICIES = {
     strict: Object.freeze({
         allowFinalSymlinkForUnlink: false,
@@ -80,15 +82,40 @@ function isPromiseLike(value) {
         typeof value.then === "function");
 }
 function createLexicalTraversalState(params) {
-    const relative = path.relative(params.rootPath, params.absolutePath);
+    const rawAbsolutePath = params.params.absolutePath;
+    const rawRelativePath = rawPathRelativeToRoot(params.rootPath, rawAbsolutePath);
+    const relative = rawRelativePath ?? path.relative(params.rootPath, params.absolutePath);
     return {
-        segments: relative.split(path.sep).filter(Boolean),
+        segments: splitTraversalSegments(relative),
         allowFinalSymlink: params.params.policy?.allowFinalSymlinkForUnlink === true,
         canonicalCursor: params.rootCanonicalPath,
         lexicalCursor: params.rootPath,
         preserveFinalSymlink: false,
     };
 }
+function splitTraversalSegments(value) {
+    return value
+        .split(process.platform === "win32" ? /[\\/]+/ : /\/+/)
+        .filter((segment) => Boolean(segment) && segment !== ".");
+}
+function rawPathRelativeToRoot(rootPath, candidatePath) {
+    if (!path.isAbsolute(candidatePath)) {
+        return undefined;
+    }
+    const root = path.resolve(rootPath);
+    const candidate = process.platform === "win32"
+        ? candidatePath.replaceAll("/", path.sep)
+        : candidatePath;
+    if (candidate === root) {
+        return "";
+    }
+    const rootWithSep = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+    const candidatePrefix = candidate.slice(0, rootWithSep.length);
+    const prefixMatches = process.platform === "win32"
+        ? candidatePrefix.toLowerCase() === rootWithSep.toLowerCase()
+        : candidatePrefix === rootWithSep;
+    return prefixMatches ? candidate.slice(rootWithSep.length) : undefined;
+}
 function assertLexicalCursorInsideBoundary(params) {
     assertInsideBoundary({
         boundaryLabel: params.params.boundaryLabel,
@@ -99,13 +126,15 @@ function assertLexicalCursorInsideBoundary(params) {
 }
 function applyMissingSuffixToCanonicalCursor(params) {
     const missingSuffix = params.state.segments.slice(params.missingFromIndex);
-    params.state.canonicalCursor = path.resolve(params.state.canonicalCursor, ...missingSuffix);
-    assertLexicalCursorInsideBoundary({
-        params: params.params,
-        rootCanonicalPath: params.rootCanonicalPath,
-        candidatePath: params.state.canonicalCursor,
-        absolutePath: params.absolutePath,
-    });
+    for (const segment of missingSuffix) {
+        advanceCanonicalCursorForSegment({
+            state: params.state,
+            segment,
+            rootCanonicalPath: params.rootCanonicalPath,
+            params: params.params,
+            absolutePath: params.absolutePath,
+        });
+    }
 }
 function advanceCanonicalCursorForSegment(params) {
     params.state.canonicalCursor = path.resolve(params.state.canonicalCursor, params.segment);
@@ -221,11 +250,20 @@ function resolveAndApplySymlinkHop(params) {
         boundaryLabel: params.boundaryLabel,
     });
 }
+function applyParentTraversalStep(params) {
+    params.state.lexicalCursor = path.resolve(params.state.lexicalCursor, "..");
+    advanceCanonicalCursorForSegment({
+        state: params.state,
+        segment: "..",
+        rootCanonicalPath: params.rootCanonicalPath,
+        params: params.resolveParams,
+        absolutePath: params.absolutePath,
+    });
+}
 function* iterateLexicalTraversal(state) {
     for (let idx = 0; idx < state.segments.length; idx += 1) {
         const segment = state.segments[idx] ?? "";
         const isLast = idx === state.segments.length - 1;
-        state.lexicalCursor = path.join(state.lexicalCursor, segment);
         yield { idx, segment, isLast };
     }
 }
@@ -238,6 +276,14 @@ async function resolveRootPathLexicalAsync(params) {
         absolutePath: params.absolutePath,
     };
     for (const { idx, segment, isLast } of iterateLexicalTraversal(state)) {
+        if (segment === "..") {
+            applyParentTraversalStep({
+                ...sharedStepParams,
+                resolveParams: params.params,
+            });
+            continue;
+        }
+        state.lexicalCursor = path.join(state.lexicalCursor, segment);
         const stat = await readLexicalStat({
             ...sharedStepParams,
             missingFromIndex: idx,
@@ -265,7 +311,7 @@ async function resolveRootPathLexicalAsync(params) {
             resolveLinkCanonical: (cursor) => resolveSymlinkHopPath(cursor),
         });
     }
-    const kind = await getPathKind(params.absolutePath, state.preserveFinalSymlink);
+    const kind = await getPathKind(state.canonicalCursor, state.preserveFinalSymlink);
     return finalizeLexicalResolution({
         ...params,
         state,
@@ -277,6 +323,15 @@ function resolveRootPathLexicalSync(params) {
     for (let idx = 0; idx < state.segments.length; idx += 1) {
         const segment = state.segments[idx] ?? "";
         const isLast = idx === state.segments.length - 1;
+        if (segment === "..") {
+            applyParentTraversalStep({
+                state,
+                rootCanonicalPath: params.rootCanonicalPath,
+                resolveParams: params.params,
+                absolutePath: params.absolutePath,
+            });
+            continue;
+        }
         state.lexicalCursor = path.join(state.lexicalCursor, segment);
         const maybeStat = readLexicalStat({
             state,
@@ -318,7 +373,7 @@ function resolveRootPathLexicalSync(params) {
             throw new Error("Unexpected async symlink resolution");
         }
     }
-    const kind = getPathKindSync(params.absolutePath, state.preserveFinalSymlink);
+    const kind = getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
     return finalizeLexicalResolution({
         ...params,
         state,
@@ -434,60 +489,6 @@ function buildResolvedRootPath(params) {
         kind: params.kind.kind,
     };
 }
-async function resolvePathViaExistingAncestor(targetPath) {
-    const normalized = path.resolve(targetPath);
-    let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) && !(await pathExists(cursor))) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
-    }
-    if (!(await pathExists(cursor))) {
-        return normalized;
-    }
-    try {
-        const resolvedAncestor = path.resolve(await fsp.realpath(cursor));
-        if (missingSuffix.length === 0) {
-            return resolvedAncestor;
-        }
-        return path.resolve(resolvedAncestor, ...missingSuffix);
-    }
-    catch {
-        return normalized;
-    }
-}
-export function resolvePathViaExistingAncestorSync(targetPath) {
-    const normalized = path.resolve(targetPath);
-    let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) && !fs.existsSync(cursor)) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
-    }
-    if (!fs.existsSync(cursor)) {
-        return normalized;
-    }
-    try {
-        // Keep sync behavior aligned with async (`fsp.realpath`) to avoid
-        // platform-specific canonical alias drift (notably on Windows).
-        const resolvedAncestor = path.resolve(fs.realpathSync(cursor));
-        if (missingSuffix.length === 0) {
-            return resolvedAncestor;
-        }
-        return path.resolve(resolvedAncestor, ...missingSuffix);
-    }
-    catch {
-        return normalized;
-    }
-}
 async function getPathKind(absolutePath, preserveFinalSymlink) {
     try {
         const stat = preserveFinalSymlink
@@ -555,21 +556,6 @@ function shortPath(value) {
     }
     return value;
 }
-function isFilesystemRoot(candidate) {
-    return path.parse(candidate).root === candidate;
-}
-async function pathExists(targetPath) {
-    try {
-        await fsp.lstat(targetPath);
-        return true;
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            return false;
-        }
-        throw error;
-    }
-}
 async function resolveSymlinkHopPath(symlinkPath) {
     try {
         return path.resolve(await fsp.realpath(symlinkPath));

package/dist/root-walk.d.ts

@@ -0,0 +1,41 @@
+import type { DirEntry } from "./types.js";
+export type RootWalkSymlinkPolicy = "skip" | "follow-within-root";
+export type RootWalkLimitBehavior = "truncate" | "throw";
+export type RootWalkDirectoryErrorBehavior = "throw" | "skip-and-report";
+export type RootWalkEntryFilterResult = "include" | "skip" | "skip-subtree";
+export type RootWalkDataEntryKind = "file" | "directory" | "other";
+export type RootWalkEntryKind = RootWalkDataEntryKind | "directory-error" | "truncated";
+export type RootWalkDataEntry = {
+    relativePath: string;
+    kind: RootWalkDataEntryKind;
+    size: number;
+};
+export type RootWalkEntry = RootWalkDataEntry | {
+    relativePath: string;
+    kind: "truncated";
+    size: 0;
+} | {
+    relativePath: string;
+    kind: "directory-error";
+    size: 0;
+    error: unknown;
+};
+export type RootWalkEntryFilter = (entry: RootWalkDataEntry) => RootWalkEntryFilterResult;
+export type RootWalkOptions = {
+    maxDepth?: number;
+    maxEntries?: number;
+    symlinkPolicy: RootWalkSymlinkPolicy;
+    signal?: AbortSignal;
+    limitBehavior?: RootWalkLimitBehavior;
+    entryFilter?: RootWalkEntryFilter;
+    onDirectoryError?: RootWalkDirectoryErrorBehavior;
+};
+type RootWalkCapability = {
+    rootReal: string;
+    list(relativePath: string, options: {
+        withFileTypes: true;
+    }): Promise<DirEntry[]>;
+};
+export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: RootWalkOptions): AsyncGenerator<RootWalkEntry>;
+export {};
+//# sourceMappingURL=root-walk.d.ts.map

package/dist/root-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-walk.d.ts","sourceRoot":"","sources":["../src/root-walk.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,oBAAoB,CAAC;AAClE,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,8BAA8B,GAAG,OAAO,GAAG,iBAAiB,CAAC;AACzE,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,MAAM,GAAG,cAAc,CAAC;AAC5E,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC;AACnE,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAExF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACpD;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,yBAAyB,CAAC;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,qBAAqB,CAAC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;CACnD,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACnF,CAAC;AAqBF,wBAAuB,QAAQ,CAC7B,IAAI,EAAE,kBAAkB,EACxB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC,aAAa,CAAC,CAgG/B"}

package/dist/root-walk.js

@@ -0,0 +1,114 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { resolveRootPath } from "./root-path.js";
+function validateBudget(name, value) {
+    if (value === undefined)
+        return Number.POSITIVE_INFINITY;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function entryKind(entry) {
+    if (entry.isSymbolicLink)
+        return "symlink";
+    if (entry.isDirectory)
+        return "directory";
+    if (entry.isFile)
+        return "file";
+    return "other";
+}
+function limitEntry(relativePath) {
+    return { relativePath, kind: "truncated", size: 0 };
+}
+export async function* walkRoot(root, relativePath, options) {
+    const maxDepth = validateBudget("maxDepth", options.maxDepth);
+    const maxEntries = validateBudget("maxEntries", options.maxEntries);
+    const visitedDirectories = new Set();
+    let examined = 0;
+    const onLimit = (atPath) => {
+        if ((options.limitBehavior ?? "truncate") === "throw") {
+            throw new FsSafeError("too-large", `root walk budget exceeded at ${atPath || "."}`);
+        }
+        return limitEntry(atPath);
+    };
+    async function* visit(directory, depth) {
+        options.signal?.throwIfAborted();
+        let entries;
+        try {
+            const resolvedDirectory = await resolveRootPath({
+                absolutePath: path.resolve(root.rootReal, directory),
+                rootPath: root.rootReal,
+                rootCanonicalPath: root.rootReal,
+                boundaryLabel: "root walk",
+            });
+            if (!resolvedDirectory.exists || resolvedDirectory.kind !== "directory") {
+                throw new FsSafeError("not-file", `root walk path is not a directory: ${directory || "."}`);
+            }
+            if (visitedDirectories.has(resolvedDirectory.canonicalPath)) {
+                return;
+            }
+            visitedDirectories.add(resolvedDirectory.canonicalPath);
+            const listingDirectory = path
+                .relative(root.rootReal, resolvedDirectory.canonicalPath)
+                .split(path.sep)
+                .join(path.posix.sep);
+            entries = await root.list(listingDirectory, { withFileTypes: true });
+        }
+        catch (error) {
+            if ((options.onDirectoryError ?? "throw") === "throw")
+                throw error;
+            yield { relativePath: directory, kind: "directory-error", size: 0, error };
+            return;
+        }
+        for (const entry of entries) {
+            options.signal?.throwIfAborted();
+            const child = directory
+                ? path.posix.join(directory.split(path.sep).join(path.posix.sep), entry.name)
+                : entry.name;
+            if (examined >= maxEntries) {
+                yield onLimit(child);
+                return;
+            }
+            examined += 1;
+            let kind = entryKind(entry);
+            let size = entry.size;
+            if (kind === "symlink") {
+                if (options.symlinkPolicy === "skip") {
+                    continue;
+                }
+                const resolved = await resolveRootPath({
+                    absolutePath: path.resolve(root.rootReal, child),
+                    rootPath: root.rootReal,
+                    rootCanonicalPath: root.rootReal,
+                    boundaryLabel: "root walk",
+                });
+                if (!resolved.exists) {
+                    continue;
+                }
+                kind = resolved.kind === "directory" ? "directory" : resolved.kind === "file" ? "file" : "other";
+                size = entry.size;
+            }
+            const walkEntry = { relativePath: child, kind, size };
+            const filterResult = options.entryFilter?.(walkEntry) ?? "include";
+            if (!["include", "skip", "skip-subtree"].includes(filterResult)) {
+                throw new TypeError(`invalid root walk entryFilter result: ${String(filterResult)}`);
+            }
+            if (filterResult === "include") {
+                yield walkEntry;
+            }
+            if (kind !== "directory") {
+                continue;
+            }
+            if (filterResult === "skip-subtree") {
+                continue;
+            }
+            if (depth >= maxDepth) {
+                yield onLimit(child);
+                return;
+            }
+            yield* visit(child, depth + 1);
+        }
+    }
+    yield* visit(relativePath, 0);
+}

package/dist/root.d.ts

@@ -1,2 +1,4 @@
 export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root-impl.js";
+export type { ContainmentGuarantee } from "./containment.js";
+export type { RootWalkDataEntry, RootWalkDataEntryKind, RootWalkDirectoryErrorBehavior, RootWalkEntry, RootWalkEntryFilter, RootWalkEntryFilterResult, RootWalkEntryKind, RootWalkLimitBehavior, RootWalkOptions, RootWalkSymlinkPolicy, } from "./root-walk.js";
 //# sourceMappingURL=root.d.ts.map

package/dist/root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,kCAAkC,EAClC,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,kCAAkC,EAClC,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,8BAA8B,EAC9B,aAAa,EACb,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/secret-file.d.ts

@@ -8,11 +8,14 @@ export type SecretFileReadOptions = {
 };
 export declare function readSecretFileSync(filePath: string, label: string, options?: SecretFileReadOptions): string;
 export declare function tryReadSecretFileSync(filePath: string | undefined, label: string, options?: SecretFileReadOptions): string | undefined;
-export declare function writeSecretFileAtomic(params: {
+type SecretFileWriteParams = {
     rootDir: string;
     filePath: string;
     content: string | Uint8Array;
     mode?: number;
     dirMode?: number;
-}): Promise<void>;
+};
+export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
+export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
+export {};
 //# sourceMappingURL=secret-file.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAqIF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAcpB;AAoID,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+ChB"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAqIF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAcpB;AAoID,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAyDF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAExF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYzF"}

package/dist/secret-file.js

@@ -257,7 +257,7 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     }
     return { rootGuard, targetReal: await fsp.realpath(resolvedTarget) };
 }
-export async function writeSecretFileAtomic(params) {
+async function materializeSecretFileAtomic(params, createOnly) {
     const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
     const dirMode = params.dirMode ?? PRIVATE_SECRET_DIR_MODE;
     const resolvedRoot = path.resolve(params.rootDir);
@@ -272,6 +272,9 @@ export async function writeSecretFileAtomic(params) {
     const finalFilePath = path.join(targetReal, fileName);
     try {
         const stat = await fsp.lstat(finalFilePath);
+        if (createOnly) {
+            throw new FsSafeError("secret-exists", `Private secret file ${finalFilePath} already exists.`);
+        }
         if (stat.isSymbolicLink()) {
             throw new Error(`Private secret file ${finalFilePath} must not be a symlink.`);
         }
@@ -292,7 +295,7 @@ export async function writeSecretFileAtomic(params) {
         basename: fileName,
         mkdir: false,
         mode,
-        overwrite: true,
+        overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
     });
@@ -300,3 +303,18 @@ export async function writeSecretFileAtomic(params) {
     await assertAsyncDirectoryGuard(parentGuard);
     await enforcePrivateFileIdentityAndMode(finalFilePath, identity, mode);
 }
+export async function writeSecretFileAtomic(params) {
+    await materializeSecretFileAtomic(params, false);
+}
+export async function createSecretFileAtomic(params) {
+    try {
+        await materializeSecretFileAtomic(params, true);
+    }
+    catch (error) {
+        if ((error instanceof FsSafeError && error.code === "already-exists") ||
+            error.code === "EEXIST") {
+            throw new FsSafeError("secret-exists", "Private secret file already exists.", { cause: error });
+        }
+        throw error;
+    }
+}

package/dist/secret-read-async.d.ts

@@ -0,0 +1,4 @@
+import { type SecretFileReadOptions } from "./secret-file.js";
+export declare function readSecretFile(filePath: string, label: string, options?: SecretFileReadOptions): Promise<string>;
+export declare function tryReadSecretFile(filePath: string | undefined, label: string, options?: SecretFileReadOptions): Promise<string | undefined>;
+//# sourceMappingURL=secret-read-async.d.ts.map

package/dist/secret-read-async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AAqF1B,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B"}

package/dist/secret-read-async.js

@@ -0,0 +1,95 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { resolveHomeRelativePath } from "./home-dir.js";
+import { DEFAULT_SECRET_FILE_MAX_BYTES, } from "./secret-file.js";
+function pathErrorCode(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
+}
+async function readSecretFileOutcome(filePath, label, options) {
+    const resolvedPath = resolveHomeRelativePath(filePath.trim());
+    if (!resolvedPath) {
+        return { ok: false, code: "invalid-path", message: `${label} file path is empty.` };
+    }
+    const maxBytes = options.maxBytes ?? DEFAULT_SECRET_FILE_MAX_BYTES;
+    let previewStat;
+    try {
+        previewStat = await fs.lstat(resolvedPath);
+        if (previewStat.isSymbolicLink()) {
+            if (options.rejectSymlink) {
+                return { ok: false, code: "symlink", message: `${label} file at ${resolvedPath} must not be a symlink.` };
+            }
+            previewStat = await fs.stat(resolvedPath);
+        }
+    }
+    catch (error) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        return {
+            ok: false,
+            code: pathErrorCode(error),
+            error: normalized,
+            message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
+        };
+    }
+    if (!previewStat.isFile()) {
+        return { ok: false, code: "not-file", message: `${label} file at ${resolvedPath} must be a regular file.` };
+    }
+    if (options.rejectHardlinks !== false && previewStat.nlink > 1) {
+        return { ok: false, code: "hardlink", message: `${label} file at ${resolvedPath} must not be hardlinked.` };
+    }
+    if (previewStat.size > maxBytes) {
+        return { ok: false, code: "too-large", message: `${label} file at ${resolvedPath} exceeds ${maxBytes} bytes.` };
+    }
+    let handle;
+    try {
+        const realPath = await fs.realpath(resolvedPath);
+        const noFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
+            ? fsSync.constants.O_NOFOLLOW
+            : 0;
+        handle = await fs.open(realPath, fsSync.constants.O_RDONLY | noFollow);
+        const openedStat = await handle.stat();
+        const pathStat = await fs.lstat(realPath);
+        if (!openedStat.isFile() ||
+            !pathStat.isFile() ||
+            !sameFileIdentity(previewStat, openedStat) ||
+            !sameFileIdentity(pathStat, openedStat) ||
+            (options.rejectHardlinks !== false && openedStat.nlink > 1)) {
+            throw new FsSafeError("path-mismatch", "security validation failed");
+        }
+        const secret = (await readFileHandleBounded(handle, maxBytes)).toString("utf8").trim();
+        return secret
+            ? { ok: true, secret }
+            : { ok: false, code: "invalid-path", message: `${label} file at ${resolvedPath} is empty.` };
+    }
+    catch (error) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        return {
+            ok: false,
+            code: error instanceof FsSafeError ? error.code : pathErrorCode(error) === "not-found" ? "not-found" : "path-mismatch",
+            error: normalized,
+            message: `Failed to read ${label} file at ${resolvedPath}: ${String(normalized)}`,
+        };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+export async function readSecretFile(filePath, label, options = {}) {
+    const result = await readSecretFileOutcome(filePath, label, options);
+    if (result.ok)
+        return result.secret;
+    throw new FsSafeError(result.code, result.message, { cause: result.error });
+}
+export async function tryReadSecretFile(filePath, label, options = {}) {
+    if (!filePath?.trim())
+        return undefined;
+    const result = await readSecretFileOutcome(filePath, label, options);
+    if (result.ok)
+        return result.secret;
+    if (result.code === "not-found")
+        return undefined;
+    throw new FsSafeError(result.code, result.message, { cause: result.error });
+}