@openclaw/fs-safe 0.13.1 → 0.15.0

package/dist/replace-file-copy-fallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAQ/D,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AAyFF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AA+HD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAkEP"}
+{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAQ/D,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AAqHF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAIN;AA+HD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAuEP"}

package/dist/replace-file-copy-fallback.js

@@ -10,10 +10,28 @@ const NOFOLLOW = SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0;
 const OPEN_READ_FLAGS = resolveReadOpenFlags();
 const OPEN_READ_WRITE_FLAGS = syncFs.constants.O_RDWR | NOFOLLOW;
 const OPEN_WRITE_EXCLUSIVE_FLAGS = syncFs.constants.O_WRONLY | syncFs.constants.O_CREAT | syncFs.constants.O_EXCL | NOFOLLOW;
+function closeSyncAfterAdmissionFailure(fsModule, fd, error) {
+    try {
+        fsModule.closeSync(fd);
+    }
+    catch {
+        // Preserve the already-selected admission failure.
+    }
+    throw error;
+}
 function notFound(error) {
     return error.code === "ENOENT";
 }
-function assertPinnedDestination(pathname, opened, dest, hardlinks) {
+function assertPinnedDestination(pathname, opened, dest, hardlinks, admission) {
+    if (admission === "hardlinks") {
+        if (pathname.isSymbolicLink() || !pathname.isFile() || !sameFileIdentity(pathname, opened)) {
+            throw new FsSafeError("path-mismatch", `Atomic replace destination changed while opening: ${dest}`);
+        }
+        if (opened.nlink > 1) {
+            throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${dest}`);
+        }
+        return;
+    }
     if (pathname.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
@@ -27,7 +45,7 @@ function assertPinnedDestination(pathname, opened, dest, hardlinks) {
         throw new FsSafeError("hardlink", `Hardlinked copy fallback destination not allowed: ${dest}`);
     }
 }
-async function openPinnedDestination(fsModule, dest, hardlinks) {
+async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
     let preview;
     try {
         preview = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
@@ -39,22 +57,24 @@ async function openPinnedDestination(fsModule, dest, hardlinks) {
     }
     if (!preview)
         return null;
-    if (preview.isSymbolicLink()) {
+    if (admission === "hardlinks" && (preview.isSymbolicLink() || !preview.isFile()))
+        return null;
+    if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
-    const handle = await fsModule.open(dest, OPEN_READ_WRITE_FLAGS);
+    const handle = await fsModule.open(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         const opened = fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
         const current = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
-        assertPinnedDestination(current, opened, dest, hardlinks);
-        return { handle, stat: opened };
+        assertPinnedDestination(current, opened, dest, hardlinks, admission);
+        return handle;
     }
     catch (error) {
         await handle.close().catch(() => undefined);
         throw error;
     }
 }
-function openPinnedDestinationSync(fsModule, dest, hardlinks) {
+function openPinnedDestinationSync(fsModule, dest, admission, hardlinks) {
     let preview;
     try {
         preview = fsModule.lstatSync(dest);
@@ -64,77 +84,34 @@ function openPinnedDestinationSync(fsModule, dest, hardlinks) {
             return null;
         throw error;
     }
-    if (preview.isSymbolicLink()) {
+    if (admission === "hardlinks" && (preview.isSymbolicLink() || !preview.isFile()))
+        return null;
+    if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
-    const fd = fsModule.openSync(dest, OPEN_READ_WRITE_FLAGS);
+    const fd = fsModule.openSync(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         const opened = fsModule.fstatSync(fd);
-        assertPinnedDestination(fsModule.lstatSync(dest), opened, dest, hardlinks);
-        return { fd, stat: opened };
+        assertPinnedDestination(fsModule.lstatSync(dest), opened, dest, hardlinks, admission);
+        return fd;
     }
     catch (error) {
-        fsModule.closeSync(fd);
-        throw error;
+        closeSyncAfterAdmissionFailure(fsModule, fd, error);
     }
 }
 export async function assertDestinationHardlinkPolicy(fsModule, dest, policy) {
     if (policy !== "reject")
         return;
-    let preview;
-    try {
-        preview = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
-    }
-    catch (error) {
-        if (notFound(error))
-            return;
-        throw error;
-    }
-    if (!preview || preview.isSymbolicLink() || !preview.isFile())
-        return;
-    const handle = await fsModule.open(dest, OPEN_READ_FLAGS);
-    try {
-        const opened = fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
-        const current = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
-        if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(current, opened)) {
-            throw new FsSafeError("path-mismatch", `Atomic replace destination changed while opening: ${dest}`);
-        }
-        if (opened.nlink > 1) {
-            throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${dest}`);
-        }
-    }
-    finally {
+    const handle = await openPinnedDestination(fsModule, dest, "hardlinks");
+    if (handle)
         await handle.close().catch(() => undefined);
-    }
 }
 export function assertDestinationHardlinkPolicySync(fsModule, dest, policy) {
     if (policy !== "reject")
         return;
-    let preview;
-    try {
-        preview = fsModule.lstatSync(dest);
-    }
-    catch (error) {
-        if (notFound(error))
-            return;
-        throw error;
-    }
-    if (preview.isSymbolicLink() || !preview.isFile())
-        return;
-    const fd = fsModule.openSync(dest, OPEN_READ_FLAGS);
-    try {
-        const opened = fsModule.fstatSync(fd);
-        const current = fsModule.lstatSync(dest);
-        if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(current, opened)) {
-            throw new FsSafeError("path-mismatch", `Atomic replace destination changed while opening: ${dest}`);
-        }
-        if (opened.nlink > 1) {
-            throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${dest}`);
-        }
-    }
-    finally {
+    const fd = openPinnedDestinationSync(fsModule, dest, "hardlinks");
+    if (fd !== null)
         fsModule.closeSync(fd);
-    }
 }
 function restoreReadOptions(stat, maxBytes) {
     return {
@@ -183,7 +160,7 @@ function writeAllSync(fsModule, fd, data) {
 function restoreFailure(writeError, cleanup, restoreError) {
     const primary = writeError instanceof Error ? writeError : new Error(String(writeError));
     const details = { cleanup };
-    const cause = restoreError
+    const cause = cleanup === "restore-failed"
         ? new AggregateError([primary, restoreError], "copy fallback and original restoration both failed")
         : primary;
     return new FsSafeError("helper-failed", cleanup === "restored"
@@ -246,11 +223,12 @@ export async function copyFallbackReplace(params) {
     });
     const { replacement } = source;
     let destHandle = null;
+    let closeRequiredForSuccess = false;
     try {
         if (params.restore === "restore-original") {
-            const pinned = await openPinnedDestination(params.fsModule, params.dest, params.destinationHardlinks);
+            const pinned = await openPinnedDestination(params.fsModule, params.dest, "restore", params.destinationHardlinks);
             if (pinned) {
-                destHandle = pinned.handle;
+                destHandle = pinned;
                 await replacePinnedWithRestore(params.fsModule, destHandle, replacement, params.maxRestoreBytes, source.mode);
             }
         }
@@ -277,10 +255,20 @@ export async function copyFallbackReplace(params) {
             if (params.sync) {
                 await destHandle.sync();
             }
+            closeRequiredForSuccess = !params.sync;
         }
     }
     finally {
-        await destHandle?.close().catch(() => undefined);
+        if (destHandle) {
+            try {
+                await destHandle.close();
+            }
+            catch (closeError) {
+                if (closeRequiredForSuccess) {
+                    throw closeError;
+                }
+            }
+        }
     }
 }
 export function copyFallbackReplaceSync(params) {
@@ -291,11 +279,12 @@ export function copyFallbackReplaceSync(params) {
     });
     const { replacement } = source;
     let destFd;
+    let closeRequiredForSuccess = false;
     try {
         if (params.restore === "restore-original") {
-            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, params.destinationHardlinks);
-            if (pinned) {
-                destFd = pinned.fd;
+            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, "restore", params.destinationHardlinks);
+            if (pinned !== null) {
+                destFd = pinned;
                 replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, source.mode, params.fchmodSync);
             }
         }
@@ -321,6 +310,7 @@ export function copyFallbackReplaceSync(params) {
             if (params.sync) {
                 params.fsModule.fsyncSync(destFd);
             }
+            closeRequiredForSuccess = !params.sync;
         }
     }
     finally {
@@ -328,8 +318,10 @@ export function copyFallbackReplaceSync(params) {
             try {
                 params.fsModule.closeSync(destFd);
             }
-            catch {
-                // Best-effort close after fallback replacement.
+            catch (closeError) {
+                if (closeRequiredForSuccess) {
+                    throw closeError;
+                }
             }
         }
     }

package/dist/replace-file-copy-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-copy-source.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-source.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAQnD,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;AACvF,KAAK,oBAAoB,GAAG,IAAI,CAC9B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAClE,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BjD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA8BxC"}
+{"version":3,"file":"replace-file-copy-source.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-source.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAQ/D,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;AACvF,KAAK,oBAAoB,GAAG,IAAI,CAC9B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAClE,CAAC;AA8DF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAyBjD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyBxC"}

package/dist/replace-file-copy-source.js

@@ -17,6 +17,14 @@ function assertSourcePreview(source, src) {
         throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${src}`);
     }
 }
+function assertOpenedSource(opened, current, src) {
+    if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
+        throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${src}`);
+    }
+    if (opened.nlink !== 1) {
+        throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${src}`);
+    }
+}
 function sourceSymlinkError(src, cause) {
     return new FsSafeError("symlink", `Refusing copy fallback from non-file source: ${src}`, {
         cause,
@@ -66,12 +74,7 @@ export async function readOwnedCopySource(params) {
         const opened = params.fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
         const current = params.fsModule === fs
             ? syncFs.lstatSync(params.src) : await params.fsModule.lstat(params.src);
-        if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
-            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
-        }
-        if (opened.nlink !== 1) {
-            throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${params.src}`);
-        }
+        assertOpenedSource(opened, current, params.src);
         return { replacement: await handle.readFile(), mode: opened.mode };
     }
     finally {
@@ -88,12 +91,7 @@ export function readOwnedCopySourceSync(params) {
         }
         const opened = params.fsModule.fstatSync(fd);
         const current = params.fsModule.lstatSync(params.src);
-        if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
-            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
-        }
-        if (opened.nlink !== 1) {
-            throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${params.src}`);
-        }
+        assertOpenedSource(opened, current, params.src);
         return { replacement: readAllSync(params.fsModule, fd, opened.size), mode: opened.mode };
     }
     finally {

package/dist/replace-file-temp-owner.d.ts

@@ -3,6 +3,9 @@ import fs, { type FileHandle } from "node:fs/promises";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
 type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
+export type AtomicTempFailure = Readonly<{
+    error: unknown;
+}>;
 export declare function removePathIfIdentityUnchanged(targetPath: string, identity: Pick<BigIntStats, "dev" | "ino">): Promise<void>;
 export declare function cleanupPinnedFilePath(params: {
     pathname: string;
@@ -26,7 +29,7 @@ export declare class AsyncAtomicTempOwner {
     markRenamed(): void;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
-        originalError?: unknown;
+        originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): Promise<void>;
 }
@@ -46,7 +49,7 @@ export declare class SyncAtomicTempOwner {
     markRenamed(): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
-        originalError?: unknown;
+        originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): void;
 }

package/dist/replace-file-temp-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-temp-owner.d.ts","sourceRoot":"","sources":["../src/replace-file-temp-owner.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAwD,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAQzH,KAAK,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;AACzE,KAAK,mBAAmB,GAAG,IAAI,CAC7B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CACrF,CAAC;AAIF,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC,CAOf;AA8DD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB;AA+BD,qBAAa,oBAAoB;;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAG/D;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAEK,aAAa,CAAC,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Cf;IAED,WAAW,IAAI,IAAI,CAGlB;IAEK,MAAM,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,oBAAoB,CAAC;QAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB;CACF;AAED,qBAAa,mBAAmB;;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAGvD;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAED,aAAa,CAAC,QAAQ,EAAE,mBAAmB,EAAE,QAAQ,SAAgB,GAAG,IAAI,CAkB3E;IAED,eAAe,CACb,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAkDN;IAED,WAAW,IAAI,IAAI,CAGlB;IAED,MAAM,CAAC,MAAM,EAAE;QACb,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,IAAI,CAkCP;CACF"}
+{"version":3,"file":"replace-file-temp-owner.d.ts","sourceRoot":"","sources":["../src/replace-file-temp-owner.ts"],"names":[],"mappings":"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"}

package/dist/replace-file-temp-owner.js

@@ -9,6 +9,33 @@ import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 const PUBLISHED_READ_FLAGS = resolveReadOpenFlags();
+function hasErrorCode(error, expected) {
+    if ((typeof error !== "object" || error === null) && typeof error !== "function") {
+        return false;
+    }
+    try {
+        return Reflect.get(error, "code") === expected;
+    }
+    catch {
+        return false;
+    }
+}
+function describeFailure(error) {
+    try {
+        return String(error);
+    }
+    catch {
+        return "<unprintable failure>";
+    }
+}
+function isErrorValue(error) {
+    try {
+        return error instanceof Error;
+    }
+    catch {
+        return false;
+    }
+}
 export async function removePathIfIdentityUnchanged(targetPath, identity) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath), { bigint: true });
     await withAsyncDirectoryGuards([parentGuard], async () => {
@@ -34,11 +61,11 @@ function missingOwnedFile(pathname, cause) {
         cause,
     });
 }
-function cleanupFailure(originalError, cleanupError) {
-    if (originalError !== undefined) {
-        return new Error(`Atomic file replace failed (${String(originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: originalError });
+function cleanupFailure(originalFailure, cleanupError) {
+    if (originalFailure) {
+        return new Error(`Atomic file replace failed (${describeFailure(originalFailure.error)}); cleanup also failed (${describeFailure(cleanupError)})`, { cause: originalFailure.error });
     }
-    return cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError));
+    return isErrorValue(cleanupError) ? cleanupError : new Error(describeFailure(cleanupError));
 }
 async function cleanupOwnedPath(params) {
     if (!params.identity)
@@ -57,10 +84,10 @@ async function cleanupOwnedPath(params) {
         return true;
     }
     catch (cleanupError) {
-        if (cleanupError.code === "ENOENT")
+        if (hasErrorCode(cleanupError, "ENOENT"))
             return true;
         if (params.throwOnCleanupError) {
-            throw cleanupFailure(params.originalError, cleanupError);
+            throw cleanupFailure(params.originalFailure, cleanupError);
         }
         return false;
     }
@@ -108,10 +135,10 @@ function cleanupOwnedPathSync(params) {
         return true;
     }
     catch (cleanupError) {
-        if (cleanupError.code === "ENOENT")
+        if (hasErrorCode(cleanupError, "ENOENT"))
             return true;
         if (params.throwOnCleanupError) {
-            throw cleanupFailure(params.originalError, cleanupError);
+            throw cleanupFailure(params.originalFailure, cleanupError);
         }
         return false;
     }
@@ -202,7 +229,9 @@ export class AsyncAtomicTempOwner {
             if (sha256Hex(await published.readFile()) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
-            await this.#handle?.close();
+            const previousHandle = this.#handle;
+            this.#handle = undefined;
+            await previousHandle?.close();
             this.#handle = published;
             this.#identity = identity;
             published = undefined;
@@ -216,7 +245,7 @@ export class AsyncAtomicTempOwner {
         this.#unregister();
     }
     async finish(params) {
-        let deferredError;
+        let deferredFailure;
         let cleanupComplete = !this.#exists;
         if (this.#exists) {
             try {
@@ -224,28 +253,32 @@ export class AsyncAtomicTempOwner {
                     fsModule: params.fsModule,
                     pathname: this.pathname,
                     identity: this.#identity,
-                    originalError: params.originalError,
+                    originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
             }
             catch (error) {
-                deferredError = error;
+                deferredFailure = { error };
             }
         }
         if (cleanupComplete)
             this.#unregister();
+        const handle = this.#handle;
+        this.#handle = undefined;
         try {
-            await this.#handle?.close();
+            await handle?.close();
         }
         catch (closeError) {
-            deferredError = deferredError
-                ? new AggregateError([deferredError, closeError], "Atomic temp cleanup and close failed")
-                : params.originalError !== undefined
-                    ? new AggregateError([params.originalError, closeError], "Atomic file replace and close failed")
-                    : closeError;
+            deferredFailure = {
+                error: deferredFailure
+                    ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
+                    : params.originalFailure
+                        ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
+                        : closeError,
+            };
         }
-        if (deferredError)
-            throw deferredError;
+        if (deferredFailure)
+            throw deferredFailure.error;
     }
 }
 export class SyncAtomicTempOwner {
@@ -353,7 +386,7 @@ export class SyncAtomicTempOwner {
         this.#unregister();
     }
     finish(params) {
-        let deferredError;
+        let deferredFailure;
         let cleanupComplete = !this.#exists;
         if (this.#exists) {
             try {
@@ -361,12 +394,12 @@ export class SyncAtomicTempOwner {
                     fsModule: params.fsModule,
                     pathname: this.pathname,
                     identity: this.#identity,
-                    originalError: params.originalError,
+                    originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
             }
             catch (error) {
-                deferredError = error;
+                deferredFailure = { error };
             }
         }
         if (cleanupComplete)
@@ -378,14 +411,16 @@ export class SyncAtomicTempOwner {
                 params.fsModule.closeSync(fd);
             }
             catch (closeError) {
-                deferredError = deferredError
-                    ? new AggregateError([deferredError, closeError], "Atomic temp cleanup and close failed")
-                    : params.originalError !== undefined
-                        ? new AggregateError([params.originalError, closeError], "Atomic file replace and close failed")
-                        : closeError;
+                deferredFailure = {
+                    error: deferredFailure
+                        ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
+                        : params.originalFailure
+                            ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
+                            : closeError,
+                };
             }
         }
-        if (deferredError)
-            throw deferredError;
+        if (deferredFailure)
+            throw deferredFailure.error;
     }
 }

package/dist/replace-file.js

@@ -171,7 +171,7 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
     const expectedHash = atomicExpectedContentHash(renameIdentity, options.content);
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
@@ -229,13 +229,13 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         await tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }
@@ -271,7 +271,7 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
     }
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new SyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
         fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
@@ -327,13 +327,13 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }

package/dist/retained-directory-replacement.d.ts

@@ -0,0 +1,26 @@
+import type { BigIntStats } from "node:fs";
+import type { NativeBinding, NativeOwnedTreeRemovalResult } from "./native-binding.js";
+type RenameBinding = NativeBinding & Required<Pick<NativeBinding, "renameNoReplaceWithIdentity">>;
+export type RetainedReplacementParent = Readonly<{
+    path: string;
+    realPath: string;
+    identity: Pick<BigIntStats, "dev" | "ino">;
+}>;
+export declare class RetainedDirectoryReplacement {
+    #private;
+    private constructor();
+    static requireBinding(): RenameBinding;
+    static retain(params: {
+        targetParent: RetainedReplacementParent;
+        stagedParent: RetainedReplacementParent;
+        originalTarget?: Readonly<{
+            path: string;
+            identity: Pick<BigIntStats, "dev" | "ino">;
+        }>;
+    }, binding?: RenameBinding): RetainedDirectoryReplacement;
+    renameNoReplace(sourceParent: "staged" | "target", sourceBasename: string, targetBasename: string, expectedSource: Pick<BigIntStats, "dev" | "ino">): void;
+    removeOriginal(backupBasename: string): Promise<NativeOwnedTreeRemovalResult["outcome"]>;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=retained-directory-replacement.d.ts.map

package/dist/retained-directory-replacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retained-directory-replacement.d.ts","sourceRoot":"","sources":["../src/retained-directory-replacement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,OAAO,KAAK,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAGvF,KAAK,aAAa,GAAG,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,EAC9D,6BAA6B,CAAC,CAAC,CAAC;AAIlC,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;CAC5C,CAAC,CAAC;AAsHH,qBAAa,4BAA4B;;IAQvC,OAAO,eAUN;IAED,MAAM,CAAC,cAAc,IAAI,aAAa,CAQrC;IAED,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE;QACpB,YAAY,EAAE,yBAAyB,CAAC;QACxC,YAAY,EAAE,yBAAyB,CAAC;QACxC,cAAc,CAAC,EAAE,QAAQ,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC;YACb,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;SAC5C,CAAC,CAAC;KACJ,EAAE,OAAO,gBAAgD,GAAG,4BAA4B,CAiDxF;IAED,eAAe,CACb,YAAY,EAAE,QAAQ,GAAG,QAAQ,EACjC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GAC/C,IAAI,CAYN;IAEK,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,CAAC,SAAS,CAAC,CAAC,CA2B7F;IAED,KAAK,IAAI,IAAI,CAQZ;CACF"}