@openclaw/fs-safe 0.9.0 → 0.11.0

package/dist/root-create-input.js

@@ -0,0 +1,80 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
+class CreateInputError extends FsSafeError {
+    rejection;
+    constructor(rejection) {
+        super("helper-failed", "create input failed", { cause: rejection });
+        this.rejection = rejection;
+    }
+}
+export function rethrowCreateInputError(error) {
+    if (error instanceof CreateInputError)
+        throw error.rejection;
+    throw error;
+}
+export function createInputOptions(data, options, defaultMaxBytes) {
+    if (typeof data === "string" || Buffer.isBuffer(data))
+        return options;
+    options.signal?.throwIfAborted();
+    if (options.encoding !== undefined || options.renameIdentity !== undefined) {
+        throw new TypeError("streamed create does not accept encoding or renameIdentity");
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: defaultMaxBytes });
+    return {
+        ...options,
+        maxBytes,
+        assertBeforeMutation: () => {
+            options.signal?.throwIfAborted();
+            return options.assertBeforeMutation?.();
+        },
+    };
+}
+export function rootWriteInput(params) {
+    const data = params.data;
+    if (typeof data === "string" || Buffer.isBuffer(data)) {
+        return { kind: "buffer", data, encoding: params.encoding };
+    }
+    return {
+        kind: "stream",
+        stageBeforePublish: true,
+        stream: (async function* () {
+            let iterator;
+            let completed = false;
+            try {
+                params.signal?.throwIfAborted();
+                iterator = data[Symbol.asyncIterator]();
+                while (true) {
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    const next = await iterator.next();
+                    completed = next.done === true;
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    if (completed)
+                        return;
+                    const chunk = next.value;
+                    if (!(chunk instanceof Uint8Array)) {
+                        throw new TypeError("streamed create chunks must be Uint8Array values");
+                    }
+                    yield chunk;
+                }
+            }
+            catch (error) {
+                if (error instanceof MutationAuthorityError)
+                    throw error;
+                throw new CreateInputError(error);
+            }
+            finally {
+                if (iterator && !completed) {
+                    try {
+                        await iterator.return?.();
+                    }
+                    catch (error) {
+                        throw new CreateInputError(error);
+                    }
+                }
+            }
+        })(),
+    };
+}

package/dist/root-directory-list.d.ts

@@ -0,0 +1,26 @@
+import type { Stats } from "node:fs";
+import { type RootContext } from "./root-context.js";
+import type { DirEntry, PathStat } from "./types.js";
+export declare function pathStatFromStats(stat: Stats): PathStat;
+export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: true): Promise<DirEntry[]>;
+export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: boolean): Promise<string[] | DirEntry[]>;
+export type RootDirectoryListing = {
+    next(): Promise<{
+        kind: "entry";
+        entry: DirEntry;
+    } | {
+        kind: "limit";
+        name: string;
+    } | undefined>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export type RootDirectoryListingOptions = {
+    order: "sorted" | "filesystem";
+    signal?: AbortSignal;
+    snapshot: boolean;
+    maxNames?: number;
+    metadataBatchSize?: number;
+    admitEntry(): boolean;
+};
+export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+//# sourceMappingURL=root-directory-list.d.ts.map

package/dist/root-directory-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-directory-list.d.ts","sourceRoot":"","sources":["../src/root-directory-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAQ1C,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAcvD;AAWD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AAClH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;AAqBhI,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAClG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAsJ/B"}

package/dist/root-directory-list.js

@@ -0,0 +1,219 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { rootPathChangedError } from "./root-errors.js";
+import { createSuppressedError } from "./suppressed-error.js";
+const METADATA_BATCH_SIZE = 32;
+export function pathStatFromStats(stat) {
+    return {
+        dev: Number(stat.dev),
+        gid: Number(stat.gid),
+        ino: Number(stat.ino),
+        isDirectory: stat.isDirectory(),
+        isFile: stat.isFile(),
+        isSymbolicLink: stat.isSymbolicLink(),
+        mode: stat.mode,
+        mtimeMs: stat.mtimeMs,
+        nlink: stat.nlink,
+        size: stat.size,
+        uid: stat.uid,
+    };
+}
+function normalizeDirectoryError(error) {
+    if (isNotFoundPathError(error)) {
+        return new FsSafeError("not-found", "directory not found", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    return error;
+}
+export async function listDirectoryPath(root, directory, withFileTypes) {
+    try {
+        const names = (await fs.readdir(directory)).sort();
+        const entries = withFileTypes
+            ? names.map(name => ({
+                name,
+                ...pathStatFromStats(fsSync.lstatSync(path.join(directory, name))),
+            }))
+            : names;
+        await assertRootIdentityCurrent(root);
+        return entries;
+    }
+    catch (error) {
+        throw normalizeDirectoryError(error);
+    }
+}
+export async function openRootDirectoryListing(root, directory, options) {
+    const guard = await createAsyncDirectoryGuard(directory, { bigint: true }).catch((error) => {
+        throw normalizeDirectoryError(error);
+    });
+    if (!isPathInside(root.rootReal, guard.realPath)) {
+        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
+    }
+    const guardPinsRoot = guard.dir === root.rootReal &&
+        guard.stat.dev === root.rootIdentity.dev && guard.stat.ino === root.rootIdentity.ino;
+    const assertCurrent = async () => {
+        options.signal?.throwIfAborted();
+        if (guardPinsRoot) {
+            // One exact receipt proves both identities without dropping the canonical-path check.
+            try {
+                await assertAsyncDirectoryGuard(guard);
+            }
+            catch (error) {
+                throw rootPathChangedError(error instanceof Error ? error : undefined);
+            }
+        }
+        else {
+            await assertRootIdentityCurrent(root);
+            await assertAsyncDirectoryGuard(guard);
+        }
+        options.signal?.throwIfAborted();
+    };
+    let handle;
+    let names;
+    let snapshot;
+    let index = 0;
+    let prepared = [];
+    let preparedIndex = 0;
+    let pendingFailure;
+    let pendingLimit;
+    let preparedBatch = false;
+    const close = async () => {
+        const owned = handle;
+        handle = undefined;
+        await owned?.close();
+    };
+    try {
+        await assertCurrent();
+        if (options.order === "filesystem") {
+            // A one-entry buffer keeps the truncation lookahead independent of width.
+            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+        }
+        else if (options.snapshot) {
+            snapshot = await listDirectoryPath(root, guard.realPath, true);
+        }
+        else if (options.maxNames !== undefined) {
+            names = [];
+            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            while (true) {
+                await assertCurrent();
+                const name = (await handle.read())?.name;
+                await assertCurrent();
+                if (name === undefined)
+                    break;
+                if (names.length >= options.maxNames) {
+                    throw new FsSafeError("too-large", "directory entry budget exceeded");
+                }
+                names.push(name);
+            }
+            await close();
+        }
+        else {
+            names = await fs.readdir(guard.realPath);
+        }
+        await assertCurrent();
+        names?.sort();
+    }
+    catch (error) {
+        const operationError = normalizeDirectoryError(error);
+        try {
+            await close();
+        }
+        catch (closeError) {
+            throw createSuppressedError(closeError, operationError, "directory setup and close both failed");
+        }
+        throw operationError;
+    }
+    const prepareBatch = async (sortedNames) => {
+        let name = sortedNames[index++];
+        if (name === undefined) {
+            await assertCurrent();
+            return;
+        }
+        if (!options.admitEntry()) {
+            pendingLimit = name;
+            return;
+        }
+        if (preparedBatch)
+            await yieldToEventLoop();
+        await assertCurrent();
+        preparedBatch = true;
+        prepared = [];
+        preparedIndex = 0;
+        while (true) {
+            try {
+                const entry = { name, ...pathStatFromStats(fsSync.lstatSync(path.join(guard.realPath, name))) };
+                prepared.push(entry);
+                // No later sibling can be observed before a possible recursive descent.
+                if (entry.isDirectory || entry.isSymbolicLink || prepared.length >= (options.metadataBatchSize ?? METADATA_BATCH_SIZE))
+                    break;
+            }
+            catch (error) {
+                pendingFailure = { error: normalizeDirectoryError(error) };
+                break;
+            }
+            name = sortedNames[index++];
+            if (name === undefined)
+                break;
+            if (!options.admitEntry()) {
+                pendingLimit = name;
+                break;
+            }
+        }
+        try {
+            await assertCurrent();
+        }
+        catch (error) {
+            if (pendingFailure) {
+                throw createSuppressedError(error, pendingFailure.error, "directory observation and identity checks both failed");
+            }
+            throw error;
+        }
+    };
+    return {
+        async next() {
+            try {
+                options.signal?.throwIfAborted();
+                if (snapshot) {
+                    const entry = snapshot[index++];
+                    if (!entry)
+                        return;
+                    return options.admitEntry() ? { kind: "entry", entry } : { kind: "limit", name: entry.name };
+                }
+                if (names) {
+                    if (preparedIndex >= prepared.length && !pendingFailure && pendingLimit === undefined) {
+                        await prepareBatch(names);
+                    }
+                    const entry = prepared[preparedIndex++];
+                    if (entry)
+                        return { kind: "entry", entry };
+                    if (pendingFailure)
+                        throw pendingFailure.error;
+                    if (pendingLimit !== undefined)
+                        return { kind: "limit", name: pendingLimit };
+                    return;
+                }
+                await assertCurrent();
+                const name = (await handle.read())?.name;
+                await assertCurrent();
+                if (name === undefined)
+                    return;
+                if (!options.admitEntry())
+                    return { kind: "limit", name };
+                // The stream's post-read fence is also the pre-stat fence in this owned operation.
+                const stat = fsSync.lstatSync(path.join(guard.realPath, name));
+                await assertCurrent();
+                return { kind: "entry", entry: { name, ...pathStatFromStats(stat) } };
+            }
+            catch (error) {
+                throw normalizeDirectoryError(error);
+            }
+        },
+        [Symbol.asyncDispose]: close,
+    };
+}

package/dist/root-entries.d.ts

@@ -0,0 +1,11 @@
+import { type RootContext } from "./root-context.js";
+import { type SymlinkPolicy } from "./root-symlink-policy.js";
+import type { DirEntry } from "./types.js";
+export type RootEntriesOptions = {
+    maxEntries?: number;
+    order?: "filesystem" | "sorted";
+    signal?: AbortSignal;
+    symlinks?: SymlinkPolicy;
+};
+export declare function entriesInRoot(root: RootContext, relativePath: string, options: RootEntriesOptions): AsyncGenerator<DirEntry>;
+//# sourceMappingURL=root-entries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-entries.d.ts","sourceRoot":"","sources":["../src/root-entries.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAErF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF,wBAAuB,aAAa,CAClC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,kBAAkB,GAC1B,cAAc,CAAC,QAAQ,CAAC,CAkD1B"}

package/dist/root-entries.js

@@ -0,0 +1,61 @@
+import { FsSafeError } from "./errors.js";
+import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { resolvePathInRoot } from "./root-context.js";
+import { openRootDirectoryListing } from "./root-directory-list.js";
+import { readSymlinkResolution } from "./root-symlink-policy.js";
+import { createSuppressedError } from "./suppressed-error.js";
+export async function* entriesInRoot(root, relativePath, options) {
+    const maxEntries = options.maxEntries;
+    if (maxEntries !== undefined && (!Number.isSafeInteger(maxEntries) || maxEntries < 0)) {
+        throw new RangeError("maxEntries must be a non-negative safe integer");
+    }
+    if (options.order !== undefined && options.order !== "filesystem" && options.order !== "sorted") {
+        throw new TypeError(`invalid root entries order: ${String(options.order)}`);
+    }
+    options.signal?.throwIfAborted();
+    validatePinnedOperationPayload({ relativePath });
+    const resolved = await resolvePathInRoot(root, relativePath, {
+        ...readSymlinkResolution(options.symlinks),
+        resolveCanonical: true,
+    });
+    options.signal?.throwIfAborted();
+    let examined = 0;
+    const listing = await openRootDirectoryListing(root, resolved.resolved, {
+        order: options.order ?? "filesystem",
+        signal: options.signal,
+        snapshot: false,
+        maxNames: maxEntries,
+        metadataBatchSize: 1,
+        admitEntry: () => maxEntries === undefined || examined++ < maxEntries,
+    });
+    let failed = false;
+    let operationError;
+    try {
+        while (true) {
+            const next = await listing.next();
+            options.signal?.throwIfAborted();
+            if (next === undefined)
+                return;
+            if (next.kind === "limit") {
+                throw new FsSafeError("too-large", "directory entry budget exceeded");
+            }
+            yield next.entry;
+        }
+    }
+    catch (error) {
+        failed = true;
+        operationError = error;
+        throw error;
+    }
+    finally {
+        try {
+            await listing[Symbol.asyncDispose]();
+        }
+        catch (closeError) {
+            if (failed) {
+                throw createSuppressedError(closeError, operationError, "directory iteration and close both failed");
+            }
+            throw closeError;
+        }
+    }
+}

package/dist/root-errors.d.ts

@@ -1,12 +1,13 @@
-import { FsSafeError } from "./errors.js";
-export declare function fileNotFoundError(cause?: unknown): FsSafeError;
+import { FsSafeError, type FsSafeErrorDetails } from "./errors.js";
+export declare function fileNotFoundError(cause?: unknown, details?: FsSafeErrorDetails): FsSafeError;
 export declare function outsideWorkspaceError(): FsSafeError;
+export declare function rootPathChangedError(cause?: Error): FsSafeError;
 export declare function directoryComponentNotDirectoryError(cause?: unknown): FsSafeError;
 export declare function hardlinkedPathNotAllowedError(): FsSafeError;
 export declare function isAlreadyExistsError(error: unknown): boolean;
 export declare function normalizePinnedWriteError(error: unknown): Error;
-export declare function normalizePinnedPathError(error: unknown): Error;
-export declare function normalizeRemoveGuardError(error: unknown): Error;
-export declare function normalizeRemovePathError(error: unknown): Error;
+export declare function normalizePinnedPathError(error: unknown, details?: FsSafeErrorDetails): Error;
+export declare function normalizeRemoveGuardError(error: unknown, details?: FsSafeErrorDetails): Error;
+export declare function normalizeRemovePathError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function throwFsSafeReadError(error: unknown, label: string): never;
 //# sourceMappingURL=root-errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"root-errors.d.ts","sourceRoot":"","sources":["../src/root-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAI9D;AAED,wBAAgB,qBAAqB,IAAI,WAAW,CAEnD;AAED,wBAAgB,mCAAmC,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAIhF;AAED,wBAAgB,6BAA6B,IAAI,WAAW,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAU/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO9D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAQ/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAe9D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAQzE"}
+{"version":3,"file":"root-errors.d.ts","sourceRoot":"","sources":["../src/root-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKnE,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAI5F;AAED,wBAAgB,qBAAqB,IAAI,WAAW,CAEnD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,WAAW,CAE/D;AAED,wBAAgB,mCAAmC,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAIhF;AAED,wBAAgB,6BAA6B,IAAI,WAAW,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAU/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ5F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ7F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAe5F;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAQzE"}

package/dist/root-errors.js

@@ -1,14 +1,17 @@
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isNodeError, isNotFoundPathError } from "./path.js";
 const REMOVE_NOT_EMPTY_CODES = new Set(["ENOTEMPTY", "EEXIST"]);
-export function fileNotFoundError(cause) {
+export function fileNotFoundError(cause, details) {
     return cause === undefined
-        ? new FsSafeError("not-found", "file not found")
-        : new FsSafeError("not-found", "file not found", { cause });
+        ? new FsSafeError("not-found", "file not found", { details })
+        : new FsSafeError("not-found", "file not found", { cause, details });
 }
 export function outsideWorkspaceError() {
     return new FsSafeError("outside-workspace", "file is outside workspace root");
 }
+export function rootPathChangedError(cause) {
+    return new FsSafeError("path-mismatch", "root path changed during operation", { cause });
+}
 export function directoryComponentNotDirectoryError(cause) {
     return cause === undefined
         ? new FsSafeError("not-file", "directory component must be a directory")
@@ -31,38 +34,39 @@ export function normalizePinnedWriteError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-export function normalizePinnedPathError(error) {
+export function normalizePinnedPathError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     return new FsSafeError("path-alias", "path is not under root", {
         cause: error instanceof Error ? error : undefined,
+        details,
     });
 }
-export function normalizeRemoveGuardError(error) {
+export function normalizeRemoveGuardError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     if (isNotFoundPathError(error)) {
-        return fileNotFoundError(error instanceof Error ? error : undefined);
+        return fileNotFoundError(error instanceof Error ? error : undefined, details);
     }
-    return normalizePinnedPathError(error);
+    return normalizePinnedPathError(error, details);
 }
-export function normalizeRemovePathError(error) {
+export function normalizeRemovePathError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     if (!isNodeError(error) || typeof error.code !== "string") {
-        return normalizePinnedPathError(error);
+        return normalizePinnedPathError(error, details);
     }
     const cause = error instanceof Error ? error : undefined;
     if (isNotFoundPathError(error)) {
-        return fileNotFoundError(cause);
+        return fileNotFoundError(cause, details);
     }
     if (REMOVE_NOT_EMPTY_CODES.has(error.code)) {
-        return new FsSafeError("not-empty", "directory is not empty", { cause });
+        return new FsSafeError("not-empty", "directory is not empty", { cause, details });
     }
-    return new FsSafeError("not-removable", "path could not be removed", { cause });
+    return new FsSafeError("not-removable", "path could not be removed", { cause, details });
 }
 export function throwFsSafeReadError(error, label) {
     if (error instanceof FsSafeError) {

package/dist/root-file.d.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import type { PathAliasPolicy } from "./path-policy.js";
+import { type SymlinkPolicy } from "./root-symlink-policy.js";
 import { type PinnedOpenSyncAllowedType, type PinnedOpenSyncFailureReason } from "./pinned-open.js";
 type BoundaryReadFs = Pick<typeof fs, "closeSync" | "constants" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "realpathSync">;
 export type RootFileOpenFailureReason = PinnedOpenSyncFailureReason | "validation";
@@ -25,6 +26,7 @@ export type OpenRootFileSyncParams = {
     maxBytes?: number;
     rejectHardlinks?: boolean;
     rejectSymlinks?: boolean;
+    symlinks?: SymlinkPolicy;
     allowedType?: PinnedOpenSyncAllowedType;
     skipLexicalRootCheck?: boolean;
     ioFs?: BoundaryReadFs;

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

@@ -1 +1 @@
-{"version":3,"file":"root-file.d.ts","sourceRoot":"","sources":["../src/root-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAE1B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,2BAA2B,GAAG,YAAY,CAAC;AAEnF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAE7E,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG;IACxD,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAQF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW3D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,kBAAkB,CAuBnF;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACjD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;CAC/C,GACA,CAAC,CAUH;AAoDD,wBAAsB,YAAY,CAChC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAwB7B"}
+{"version":3,"file":"root-file.d.ts","sourceRoot":"","sources":["../src/root-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAE1B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,2BAA2B,GAAG,YAAY,CAAC;AAEnF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAE7E,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG;IACxD,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAQF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW3D;AASD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,kBAAkB,CAuBnF;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACjD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;CAC/C,GACA,CAAC,CAUH;AAoDD,wBAAsB,YAAY,CAChC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAwB7B"}

package/dist/root-file.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveRootPath, resolveRootPathSync, } from "./root-path.js";
+import { readSymlinkResolution } from "./root-symlink-policy.js";
 import { openPinnedFileSync, } from "./pinned-open.js";
 export function canUseRootFileOpen(ioFs) {
     return (typeof ioFs.openSync === "function" &&
@@ -12,9 +13,16 @@ export function canUseRootFileOpen(ioFs) {
         typeof ioFs.constants === "object" &&
         ioFs.constants !== null);
 }
+function absoluteRootFilePath(filePath) {
+    if (path.isAbsolute(filePath))
+        return filePath;
+    const drive = path.parse(filePath).root;
+    const base = drive ? path.resolve(drive) : process.cwd();
+    return `${base}${path.sep}${filePath.slice(drive.length)}`;
+}
 export function openRootFileSync(params) {
     const ioFs = params.ioFs ?? fs;
-    const absolutePath = path.resolve(params.absolutePath);
+    const absolutePath = absoluteRootFilePath(params.absolutePath);
     let resolved;
     try {
         resolved = mapResolvedRootPath(absolutePath, resolveRootPathSync({
@@ -22,7 +30,7 @@ export function openRootFileSync(params) {
             rootPath: params.rootPath,
             rootCanonicalPath: params.rootRealPath,
             boundaryLabel: params.boundaryLabel,
-            rejectSymlinks: params.rejectSymlinks ?? true,
+            ...readSymlinkResolution(params.symlinks ?? (params.rejectSymlinks === false ? "follow-within-root" : "reject")),
             skipLexicalRootCheck: params.skipLexicalRootCheck,
         }));
     }
@@ -84,7 +92,7 @@ function finalizeRootFileOpen(params) {
 }
 export async function openRootFile(params) {
     const ioFs = params.ioFs ?? fs;
-    const absolutePath = path.resolve(params.absolutePath);
+    const absolutePath = absoluteRootFilePath(params.absolutePath);
     let resolved;
     try {
         resolved = mapResolvedRootPath(absolutePath, await resolveRootPath({
@@ -93,7 +101,7 @@ export async function openRootFile(params) {
             rootCanonicalPath: params.rootRealPath,
             boundaryLabel: params.boundaryLabel,
             policy: params.aliasPolicy,
-            rejectSymlinks: params.rejectSymlinks ?? true,
+            ...readSymlinkResolution(params.symlinks ?? (params.rejectSymlinks === false ? "follow-within-root" : "reject")),
             skipLexicalRootCheck: params.skipLexicalRootCheck,
         }));
     }