@openclaw/fs-safe 0.5.1 → 0.5.3

package/dist/sidecar-lock-reclaim.js

@@ -2,9 +2,10 @@ import { randomBytes } from "node:crypto";
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { readFileHandleBounded } from "./bounded-read.js";
+import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 const MAX_LOCK_PAYLOAD_BYTES = 1024 * 1024;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES = 16;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS = SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES * 8;
@@ -55,6 +56,7 @@ export function parseSidecarLockPayload(raw, parser) {
     }
 }
 export async function readSidecarLockSnapshot(lockPath, options = {}) {
+    let handle;
     try {
         if (options.lockRoot) {
             const opened = await options.lockRoot.open(relativeSidecarLockPath(options.lockRoot, lockPath));
@@ -70,9 +72,44 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
                 await opened.handle.close().catch(() => undefined);
             }
         }
-        const stat = await fs.lstat(lockPath);
-        const raw = await fs.readFile(lockPath, "utf8");
-        return { raw, payload: parseSidecarLockPayload(raw, options.parsePayload), stat };
+        const before = await fs.lstat(lockPath);
+        if (!before.isFile() || before.isSymbolicLink()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
+        await getFsSafeTestHooks()?.beforeSidecarLockSnapshotOpen?.(lockPath);
+        const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
+            ? fsSync.constants.O_NOFOLLOW
+            : 0;
+        try {
+            handle = await fs.open(lockPath, fsSync.constants.O_RDONLY |
+                noFollow |
+                (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0));
+        }
+        catch (error) {
+            if (options.rejectNonFile && error.code === "ELOOP") {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        const opened = await handle.stat();
+        if (!opened.isFile()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
+        if (!options.allowDescriptorIdentityDrift && !sameFileIdentity(before, opened))
+            return null;
+        const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
+        const after = await fs.lstat(lockPath);
+        if (!after.isFile() || !sameFileIdentity(before, after))
+            return null;
+        return { raw, payload: parseSidecarLockPayload(raw, options.parsePayload), stat: after };
     }
     catch (err) {
         if (err.code === "ENOENT" ||
@@ -81,19 +118,26 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
         }
         throw err;
     }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
 }
-export function readSidecarLockSnapshotSync(lockPath, parsePayload) {
+export function readSidecarLockSnapshotSync(lockPath, parsePayload, options = {}) {
     let fd;
     try {
         const before = fsSync.lstatSync(lockPath);
-        if (!before.isFile() || before.isSymbolicLink())
+        if (!before.isFile() || before.isSymbolicLink()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
             return null;
+        }
         const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
             ? fsSync.constants.O_NOFOLLOW
             : 0;
         fd = fsSync.openSync(lockPath, fsSync.constants.O_RDONLY | noFollow);
         const opened = fsSync.fstatSync(fd);
-        const raw = fsSync.readFileSync(fd, "utf8");
+        const raw = readFileDescriptorBoundedSync(fd, MAX_LOCK_PAYLOAD_BYTES).toString("utf8");
         const after = fsSync.lstatSync(lockPath);
         if (!sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
             return null;
@@ -139,7 +183,10 @@ export function sidecarLockSnapshotMatches(current, observed) {
     return observed.stat !== undefined && current.stat !== undefined;
 }
 export async function removeSidecarLockIfUnchanged(lockPath, observed, options = {}) {
-    const current = await readSidecarLockSnapshot(lockPath, options);
+    const current = await readSidecarLockSnapshot(lockPath, {
+        ...options,
+        allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
+    });
     if (!current || !observed || !sidecarLockSnapshotMatches(current, observed)) {
         return false;
     }
@@ -152,7 +199,10 @@ export async function removeSidecarLockIfUnchanged(lockPath, observed, options =
     return true;
 }
 export async function sidecarLockSnapshotStillPresent(lockPath, observed, options = {}) {
-    const current = await readSidecarLockSnapshot(lockPath, options);
+    const current = await readSidecarLockSnapshot(lockPath, {
+        ...options,
+        allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
+    });
     return !!current && !!observed && sidecarLockSnapshotMatches(current, observed);
 }
 export async function sidecarReclaimGuardExists(pathname) {

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EAEpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAKjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAsLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAgB3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAgNL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBASW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAmLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAS3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBASW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/sidecar-lock.js

@@ -1,13 +1,11 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { sameFileIdentity } from "./file-identity.js";
-import { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotMatches, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
-import { FsSafeError } from "./errors.js";
-import { createNativeExclusiveFile } from "./native-operations.js";
+import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
 import { createHeldSidecarLockHandle } from "./sidecar-lock-handle.js";
-import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, } from "./sidecar-lock-policy.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
+const GLOBAL_CLEANUP_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistered");
+const GLOBAL_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockCleanupHandler");
 function getGlobalManagers() {
     const globalWithState = globalThis;
     if (!globalWithState[GLOBAL_STATE_KEY]) {
@@ -79,17 +77,6 @@ function snapshotMatchesSync(lockPath, observed) {
         }
     }
 }
-async function resolveNormalizedTargetPath(targetPath) {
-    const resolved = path.resolve(targetPath);
-    const dir = path.dirname(resolved);
-    await fs.mkdir(dir, { recursive: true });
-    try {
-        return path.join(await fs.realpath(dir), path.basename(resolved));
-    }
-    catch {
-        return resolved;
-    }
-}
 function releaseAllReclaimGuardsSync(state) {
     for (const reclaimGuardPath of state.reclaimGuards) {
         try {
@@ -116,6 +103,19 @@ function releaseAllLocksSync(state) {
     }
     releaseAllReclaimGuardsSync(state);
 }
+function ensureGlobalExitCleanupRegistered() {
+    const globalWithCleanup = globalThis;
+    if (globalWithCleanup[GLOBAL_CLEANUP_KEY])
+        return;
+    globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
+    const cleanup = () => {
+        for (const state of getGlobalManagers().values()) {
+            releaseAllLocksSync(state);
+        }
+    };
+    globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
+    process.on("exit", cleanup);
+}
 async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);
     if (current !== held) {
@@ -164,217 +164,18 @@ function handleForHeldLock(state, normalizedTargetPath, held) {
 export function createSidecarLockManager(key) {
     const state = resolveManagerState(key);
     function ensureExitCleanupRegistered() {
-        if (!state.cleanupRegistered) {
-            state.cleanupRegistered = true;
-            state.reclaimCleanupRegistered = true;
-            process.on("exit", () => releaseAllLocksSync(state));
-            return;
-        }
-        if (!state.reclaimCleanupRegistered) {
-            state.reclaimCleanupRegistered = true;
-            process.on("exit", () => releaseAllReclaimGuardsSync(state));
-        }
+        state.cleanupRegistered = true;
+        state.reclaimCleanupRegistered = true;
+        ensureGlobalExitCleanupRegistered();
     }
     async function acquire(options) {
-        ensureExitCleanupRegistered();
-        const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
-        const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
-        const held = state.held.get(normalizedTargetPath);
-        if (held &&
-            options.reentrantOwner !== undefined &&
-            held.reentrantOwner !== undefined &&
-            options.reentrantOwner === held.reentrantOwner) {
-            held.refCount += 1;
-            return handleForHeldLock(state, normalizedTargetPath, held);
-        }
-        const startedAt = Date.now();
-        const retry = options.retry ?? {};
-        const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
-        const reclaimGuardPath = `${lockPath}.reclaim`;
-        let ownsReclaimGuard = false;
-        let attempt = 0;
-        const waitForRetry = async () => {
-            const elapsed = Date.now() - startedAt;
-            if ((options.timeoutMs !== undefined &&
-                options.timeoutMs !== Number.POSITIVE_INFINITY &&
-                elapsed >= options.timeoutMs) ||
-                (maxRetries !== undefined && attempt >= maxRetries)) {
-                throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                    code: "file_lock_timeout",
-                    lockPath,
-                    normalizedTargetPath,
-                });
-            }
-            const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
-                ? Number.POSITIVE_INFINITY
-                : Math.max(0, options.timeoutMs - elapsed);
-            const delay = Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
-            attempt += 1;
-            await new Promise((resolve) => setTimeout(resolve, delay));
-        };
-        try {
-            while (true) {
-                if (!ownsReclaimGuard && (await sidecarReclaimGuardExists(reclaimGuardPath))) {
-                    await waitForRetry();
-                    continue;
-                }
-                let handle = null;
-                try {
-                    const payload = await options.payload();
-                    const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
-                    if (options.lockRoot) {
-                        const relativeLockPath = relativeSidecarLockPath(options.lockRoot, lockPath);
-                        try {
-                            await options.lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
-                        }
-                        catch (error) {
-                            if (error instanceof FsSafeError && error.code === "already-exists") {
-                                throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
-                            }
-                            throw error;
-                        }
-                        handle = (await options.lockRoot.open(relativeLockPath)).handle;
-                    }
-                    else {
-                        handle = (await createNativeExclusiveFile(lockPath, 0o600)) ?? await fs.open(lockPath, "wx");
-                        await handle.writeFile(raw, "utf8");
-                    }
-                    const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
-                    const createdHeld = {
-                        refCount: 1,
-                        reentrantOwner: options.reentrantOwner,
-                        handle,
-                        lockPath,
-                        snapshot,
-                        acquiredAt: Date.now(),
-                        metadata: options.metadata ?? {},
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    };
-                    state.held.set(normalizedTargetPath, createdHeld);
-                    if (ownsReclaimGuard) {
-                        try {
-                            await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
-                            ownsReclaimGuard = false;
-                        }
-                        catch (err) {
-                            await releaseHeldLock(state, normalizedTargetPath, createdHeld, { force: true });
-                            throw err;
-                        }
-                    }
-                    const returnedHandle = handleForHeldLock(state, normalizedTargetPath, createdHeld);
-                    const interval = options.compromiseCheckIntervalMs;
-                    if (options.onCompromised && interval !== undefined && interval > 0) {
-                        createdHeld.compromiseTimer = setInterval(() => {
-                            void returnedHandle.verifyStillHeld().then((stillHeld) => {
-                                if (!stillHeld && createdHeld.compromiseTimer) {
-                                    clearInterval(createdHeld.compromiseTimer);
-                                    createdHeld.compromiseTimer = undefined;
-                                    options.onCompromised?.({ lockPath, normalizedTargetPath });
-                                }
-                            });
-                        }, interval);
-                        createdHeld.compromiseTimer.unref();
-                    }
-                    return returnedHandle;
-                }
-                catch (err) {
-                    if (handle) {
-                        const failedSnapshot = { payload: null };
-                        try {
-                            failedSnapshot.stat = await handle.stat();
-                        }
-                        catch {
-                            // Best-effort cleanup of a failed exclusive create.
-                        }
-                        const current = state.held.get(normalizedTargetPath);
-                        if (current?.handle === handle) {
-                            state.held.delete(normalizedTargetPath);
-                        }
-                        // If payload serialization/write fails, the file may be empty or
-                        // partial JSON, so remove while our exclusive handle is still open.
-                        if (!options.lockRoot) {
-                            await fs.rm(lockPath, { force: true }).catch(() => undefined);
-                        }
-                        await handle.close().catch(() => undefined);
-                        // Windows can refuse removing an open file; retry after close but
-                        // only if the path still points at the file identity we created.
-                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                            lockRoot: options.lockRoot,
-                            parsePayload: options.parsePayload,
-                        });
-                    }
-                    if (err.code !== "EEXIST") {
-                        throw err;
-                    }
-                    if (ownsReclaimGuard) {
-                        await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
-                        ownsReclaimGuard = false;
-                        continue;
-                    }
-                    const nowMs = Date.now();
-                    const snapshot = await readSidecarLockSnapshot(lockPath, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
-                    if (!snapshot) {
-                        continue;
-                    }
-                    if (state.held.has(normalizedTargetPath)) {
-                        await waitForRetry();
-                        continue;
-                    }
-                    const shouldReclaim = options.shouldReclaim ?? defaultSidecarLockShouldReclaim;
-                    if (await shouldReclaim({
-                        lockPath,
-                        normalizedTargetPath,
-                        payload: snapshot?.payload ?? null,
-                        staleMs: options.staleMs,
-                        nowMs,
-                        heldByThisProcess: state.held.has(normalizedTargetPath),
-                    })) {
-                        if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
-                            lockRoot: options.lockRoot,
-                            parsePayload: options.parsePayload,
-                        }))) {
-                            continue;
-                        }
-                        const staleRecovery = options.staleRecovery ?? "fail-closed";
-                        if (staleRecovery === "remove-if-unchanged") {
-                            if (!(await tryAcquireSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath))) {
-                                await waitForRetry();
-                                continue;
-                            }
-                            ownsReclaimGuard = true;
-                            const removal = await removeStaleSidecarLockIfAllowed({
-                                lockPath,
-                                normalizedTargetPath,
-                                snapshot,
-                                shouldRemoveStaleLock: options.shouldRemoveStaleLock,
-                                lockRoot: options.lockRoot,
-                                parsePayload: options.parsePayload,
-                            });
-                            if (removal === "removed" || removal === "changed") {
-                                continue;
-                            }
-                            await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
-                            ownsReclaimGuard = false;
-                        }
-                        throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                            code: "file_lock_stale",
-                            lockPath,
-                            normalizedTargetPath,
-                        });
-                    }
-                    await waitForRetry();
-                }
-            }
-        }
-        finally {
-            if (ownsReclaimGuard) {
-                await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath).catch(() => undefined);
-            }
-        }
+        return await acquireSidecarLock(options, {
+            held: state.held,
+            reclaimGuards: state.reclaimGuards,
+            ensureExitCleanupRegistered,
+            handleForHeldLock: (normalizedTargetPath, held) => handleForHeldLock(state, normalizedTargetPath, held),
+            releaseHeldLock: async (normalizedTargetPath, held, releaseOptions) => await releaseHeldLock(state, normalizedTargetPath, held, releaseOptions),
+        });
     }
     async function withLock(options, fn) {
         const lock = await acquire(options);

package/dist/symlink-parents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA0BN"}
+{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}

package/dist/symlink-parents.js

@@ -1,7 +1,8 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
+import { FsSafeError } from "./errors.js";
+import { hasNodeErrorCode, isPathRelativeEscape } from "./path.js";
 function resolvePathWalk(params) {
     const root = path.resolve(params.rootDir);
     const target = path.resolve(params.targetPath);
@@ -26,7 +27,7 @@ export async function assertNoSymlinkParents(params) {
         return;
     }
     let current = walk.root;
-    for (const segment of walk.segments) {
+    for (const [index, segment] of walk.segments.entries()) {
         current = path.join(current, segment);
         try {
             const stat = await fs.lstat(current);
@@ -36,12 +37,12 @@ export async function assertNoSymlinkParents(params) {
                 }
                 throw new Error(formatUnsafePath(params, current));
             }
-            if (params.requireDirectories && !stat.isDirectory()) {
-                throw new Error(`${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
+            if ((params.requireDirectories || index < walk.segments.length - 1) && !stat.isDirectory()) {
+                throw new FsSafeError("not-file", `${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
             }
         }
         catch (err) {
-            if (isNotFoundPathError(err) && params.allowMissing !== false) {
+            if (hasNodeErrorCode(err, "ENOENT") && params.allowMissing !== false) {
                 return;
             }
             throw err;
@@ -54,7 +55,7 @@ export function assertNoSymlinkParentsSync(params) {
         return;
     }
     let current = walk.root;
-    for (const segment of walk.segments) {
+    for (const [index, segment] of walk.segments.entries()) {
         current = path.join(current, segment);
         try {
             const stat = fsSync.lstatSync(current);
@@ -64,8 +65,8 @@ export function assertNoSymlinkParentsSync(params) {
                 }
                 throw new Error(formatUnsafePath(params, current));
             }
-            if (params.requireDirectories && !stat.isDirectory()) {
-                throw new Error(`${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
+            if ((params.requireDirectories || index < walk.segments.length - 1) && !stat.isDirectory()) {
+                throw new FsSafeError("not-file", `${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
             }
         }
         catch (err) {

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA0EF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyBD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA0EF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAsCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
-import { mkdtemp, rm } from "node:fs/promises";
+import { lstat, mkdtemp, rm } from "node:fs/promises";
 import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
 import { assertSafePathSegment, sanitizeSafePathSegment } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
@@ -89,8 +90,17 @@ function isNodeErrorWithCode(err, code) {
         "code" in err &&
         err.code === code);
 }
-async function cleanupTempDir(dir, onCleanupError) {
+async function cleanupTempDir(dir, identity, onCleanupError) {
     try {
+        const current = await lstat(dir).catch((error) => {
+            if (isNodeErrorWithCode(error, "ENOENT")) {
+                return undefined;
+            }
+            throw error;
+        });
+        if (!current || !sameFileIdentity(current, identity)) {
+            return;
+        }
         await rm(dir, { recursive: true, force: true });
     }
     catch (err) {
@@ -106,11 +116,12 @@ export async function tempFile(params) {
     const rootDir = resolveTempRoot(params.rootDir);
     const prefix = `${sanitizePrefix(params.prefix)}-`;
     const dir = await mkdtemp(path.join(rootDir, prefix));
-    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true });
+    const identity = await lstat(dir);
+    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
     const file = (fileName) => path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
     const cleanup = async () => {
         try {
-            await cleanupTempDir(dir, params.onCleanupError);
+            await cleanupTempDir(dir, identity, params.onCleanupError);
         }
         finally {
             unregisterTempDir();

package/dist/test-hooks.d.ts

@@ -10,6 +10,7 @@ export type FsSafeTestHooks = {
     beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
     afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
     beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+    beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
     afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
     beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;

package/dist/test-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAC1B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,0BAA0B,CAAC,EAAE,CAC3B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}
+{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,6BAA6B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAC1B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,0BAA0B,CAAC,EAAE,CAC3B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}

package/dist/timing.d.ts

@@ -1,3 +1,5 @@
+export declare function sleep(ms: number): Promise<void>;
+export declare function sleepSync(ms: number): void;
 export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, labelOrOptions?: string | {
     label?: string;
     message?: string;

package/dist/timing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CA6BZ"}
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAK1C;AAED,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CA6BZ"}

package/dist/timing.js

@@ -1,3 +1,12 @@
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function sleepSync(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 export async function withTimeout(promise, timeoutMs, labelOrOptions = {
     message: "timeout",
 }) {

package/dist/trash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAwKF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}
+{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAkLF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/trash.js

@@ -117,6 +117,15 @@ function reserveTrashDestination(trashDir, base, timestamp) {
     }
     return resolveContainedPath(container, base);
 }
+function copyTrashTargetSync(target, dest) {
+    if (target.stat.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(target.path);
+        assertTrashTargetGuard(target);
+        fs.symlinkSync(linkTarget, dest);
+        return;
+    }
+    fs.cpSync(target.path, dest, { recursive: true, force: false, errorOnExist: true });
+}
 function movePathToDestination(target, dest) {
     getFsSafeTestHooks()?.beforeTrashMove?.(target.path, dest);
     assertTrashTargetGuard(target);
@@ -134,7 +143,7 @@ function movePathToDestination(target, dest) {
     }
     try {
         assertTrashTargetGuard(target);
-        fs.cpSync(target.path, dest, { recursive: true, force: false, errorOnExist: true });
+        copyTrashTargetSync(target, dest);
         assertTrashTargetGuard(target);
         guardedRmSync({ target: target.path, recursive: true, force: false, verifyAfter: false });
         return true;

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA8EF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAwDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAwD1C"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA+FF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAyDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAyD1C"}

package/dist/walk.js

@@ -1,6 +1,19 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+function validateWalkBudget(name, value) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function validateWalkOptions(options) {
+    validateWalkBudget("maxDepth", options.maxDepth);
+    validateWalkBudget("maxEntries", options.maxEntries);
+    if (options.symlinks !== undefined &&
+        !["skip", "follow", "include"].includes(options.symlinks)) {
+        throw new TypeError(`invalid walk symlink policy: ${String(options.symlinks)}`);
+    }
+}
 function kindForDirent(dirent) {
     if (dirent.isDirectory())
         return "directory";
@@ -75,6 +88,7 @@ async function resolveAsyncKind(fullPath, dirent, symlinks) {
     return "other";
 }
 export function walkDirectorySync(rootDir, options = {}) {
+    validateWalkOptions(options);
     const root = path.resolve(rootDir);
     const symlinks = options.symlinks ?? "skip";
     const result = {
@@ -133,6 +147,7 @@ export function walkDirectorySync(rootDir, options = {}) {
     return result;
 }
 export async function walkDirectory(rootDir, options = {}) {
+    validateWalkOptions(options);
     const root = path.resolve(rootDir);
     const symlinks = options.symlinks ?? "skip";
     const result = {