@openclaw/fs-safe 0.5.1 → 0.5.3

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

@@ -189,15 +189,18 @@ function restoreFailure(writeError, cleanup, restoreError) {
         ? `Atomic copy fallback failed; original destination restored: ${primary.message}`
         : `Atomic copy fallback failed and original restoration failed: ${primary.message}`, { cause, details });
 }
-async function replacePinnedWithRestore(handle, replacement, maxRestoreBytes) {
+async function replacePinnedWithRestore(handle, replacement, maxRestoreBytes, replacementMode) {
+    const originalMode = (await handle.stat()).mode;
     const original = await readBounded(handle, maxRestoreBytes);
     try {
         await writeAll(handle, replacement);
+        await handle.chmod(replacementMode);
         await handle.sync();
     }
     catch (writeError) {
         try {
             await writeAll(handle, original);
+            await handle.chmod(originalMode);
             await handle.sync();
             throw restoreFailure(writeError, "restored");
         }
@@ -209,15 +212,18 @@ async function replacePinnedWithRestore(handle, replacement, maxRestoreBytes) {
         }
     }
 }
-function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes) {
+function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes, replacementMode, fchmodSync) {
+    const originalMode = fsModule.fstatSync(fd).mode;
     const original = readBoundedSync(fsModule, fd, maxRestoreBytes);
     try {
         writeAllSync(fsModule, fd, replacement);
+        fchmodSync?.(fd, replacementMode);
         fsModule.fsyncSync(fd);
     }
     catch (writeError) {
         try {
             writeAllSync(fsModule, fd, original);
+            fchmodSync?.(fd, originalMode);
             fsModule.fsyncSync(fd);
             throw restoreFailure(writeError, "restored");
         }
@@ -247,7 +253,7 @@ export async function copyFallbackReplace(params) {
             const pinned = await openPinnedDestination(params.fsModule, params.dest, params.destinationHardlinks);
             if (pinned) {
                 destHandle = pinned.handle;
-                await replacePinnedWithRestore(destHandle, replacement, params.maxRestoreBytes);
+                await replacePinnedWithRestore(destHandle, replacement, params.maxRestoreBytes, sourceStat.mode);
             }
         }
         if (!destHandle) {
@@ -265,13 +271,16 @@ export async function copyFallbackReplace(params) {
             }
             destHandle = await params.fsModule.open(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
             await destHandle.writeFile(replacement);
+            await destHandle.chmod(sourceStat.mode);
+            if (params.sync) {
+                await destHandle.sync();
+            }
         }
     }
     finally {
         await destHandle?.close().catch(() => undefined);
         await sourceHandle.close().catch(() => undefined);
     }
-    await params.fsModule.unlink(params.src).catch(() => undefined);
 }
 export function copyFallbackReplaceSync(params) {
     const sourcePreview = params.fsModule.lstatSync(params.src);
@@ -291,7 +300,7 @@ export function copyFallbackReplaceSync(params) {
             const pinned = openPinnedDestinationSync(params.fsModule, params.dest, params.destinationHardlinks);
             if (pinned) {
                 destFd = pinned.fd;
-                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes);
+                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, sourceStat.mode, params.fchmodSync);
             }
         }
         if (destFd === undefined) {
@@ -312,6 +321,10 @@ export function copyFallbackReplaceSync(params) {
             }
             destFd = params.fsModule.openSync(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
             writeAllSync(params.fsModule, destFd, replacement);
+            params.fchmodSync?.(destFd, sourceStat.mode);
+            if (params.sync) {
+                params.fsModule.fsyncSync(destFd);
+            }
         }
     }
     finally {
@@ -330,10 +343,4 @@ export function copyFallbackReplaceSync(params) {
             // Best-effort close after fallback replacement.
         }
     }
-    try {
-        params.fsModule.unlinkSync(params.src);
-    }
-    catch {
-        // Best-effort cleanup after fallback replacement.
-    }
 }

package/dist/replace-file-descriptor.d.ts

@@ -0,0 +1,33 @@
+import syncFs, { type Stats } from "node:fs";
+import fs from "node:fs/promises";
+type AsyncTempFileSystem = Pick<typeof fs, "lstat" | "open" | "writeFile">;
+type SyncTempFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "lstatSync" | "openSync" | "writeFileSync">;
+export type SyncFchmod = (fd: number, mode: number) => void;
+export declare function applyDirectoryMode(params: {
+    fsModule: AsyncTempFileSystem;
+    dirPath: string;
+    mode: number;
+}): Promise<void>;
+export declare function applyDirectoryModeSync(params: {
+    fsModule: SyncTempFileSystem;
+    dirPath: string;
+    mode: number;
+    fchmodSync?: SyncFchmod;
+}): void;
+export declare function writeTempFile(params: {
+    fsModule: AsyncTempFileSystem;
+    tempPath: string;
+    content: string | Uint8Array;
+    mode: number;
+    sync: boolean;
+}): Promise<Stats>;
+export declare function writeTempFileSync(params: {
+    fsModule: SyncTempFileSystem;
+    tempPath: string;
+    content: string | Uint8Array;
+    mode: number;
+    fchmodSync?: SyncFchmod;
+    sync: boolean;
+}): Stats;
+export {};
+//# sourceMappingURL=replace-file-descriptor.d.ts.map

package/dist/replace-file-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file-descriptor.d.ts","sourceRoot":"","sources":["../src/replace-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAuB,MAAM,kBAAkB,CAAC;AAIvD,KAAK,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,IAAI,CAC5B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CACrF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AA2B5D,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAcP;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,KAAK,CAAC,CAkBjB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,KAAK,CAkBR"}

package/dist/replace-file-descriptor.js

@@ -0,0 +1,96 @@
+import syncFs, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+function directoryOpenFlags() {
+    return (syncFs.constants.O_RDONLY |
+        syncFs.constants.O_DIRECTORY |
+        syncFs.constants.O_NOFOLLOW |
+        syncFs.constants.O_NONBLOCK);
+}
+function assertDirectory(identity, dirPath) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("not-file", `Atomic replace parent must be a real directory: ${dirPath}`);
+    }
+}
+function assertSameDirectory(expected, opened, dirPath) {
+    assertDirectory(opened, dirPath);
+    if (!sameFileIdentity(expected, opened)) {
+        throw new FsSafeError("path-mismatch", `Atomic replace parent changed before its mode could be applied: ${dirPath}`);
+    }
+}
+export async function applyDirectoryMode(params) {
+    // Node does not enforce POSIX directory modes on Windows, and its directory
+    // descriptors are not consistently openable. mkdir(mode) remains the only
+    // bounded behavior there; never fall back to a pathname chmod.
+    if (process.platform === "win32") {
+        return;
+    }
+    const expected = await params.fsModule.lstat(params.dirPath);
+    assertDirectory(expected, params.dirPath);
+    const handle = await params.fsModule.open(params.dirPath, directoryOpenFlags());
+    try {
+        assertSameDirectory(expected, await handle.stat(), params.dirPath);
+        await handle.chmod(params.mode);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function applyDirectoryModeSync(params) {
+    if (process.platform === "win32") {
+        return;
+    }
+    const expected = params.fsModule.lstatSync(params.dirPath);
+    assertDirectory(expected, params.dirPath);
+    const fd = params.fsModule.openSync(params.dirPath, directoryOpenFlags());
+    try {
+        assertSameDirectory(expected, params.fsModule.fstatSync(fd), params.dirPath);
+        params.fchmodSync?.(fd, params.mode);
+    }
+    finally {
+        params.fsModule.closeSync(fd);
+    }
+}
+export async function writeTempFile(params) {
+    const handle = await params.fsModule.open(params.tempPath, "wx", params.mode);
+    try {
+        await params.fsModule.writeFile(handle, params.content);
+        await handle.chmod(params.mode);
+        if (params.sync) {
+            try {
+                await handle.sync();
+            }
+            catch (error) {
+                if (error.code !== "EPERM") {
+                    throw error;
+                }
+            }
+        }
+        return await handle.stat();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function writeTempFileSync(params) {
+    const fd = params.fsModule.openSync(params.tempPath, "wx", params.mode);
+    try {
+        params.fsModule.writeFileSync(fd, params.content);
+        params.fchmodSync?.(fd, params.mode);
+        if (params.sync) {
+            try {
+                params.fsModule.fsyncSync(fd);
+            }
+            catch (error) {
+                if (error.code !== "EPERM") {
+                    throw error;
+                }
+            }
+        }
+        return params.fsModule.fstatSync(fd);
+    }
+    finally {
+        params.fsModule.closeSync(fd);
+    }
+}

package/dist/replace-file.d.ts

@@ -2,9 +2,16 @@ import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import { type ReplaceFileAtomicRestoreCleanup, type ReplaceFileAtomicRestoreFailureDetails, type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
 export type ReplaceFileAtomicFileSystem = {
-    promises: Pick<typeof fs, "mkdir" | "chmod" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat">;
+    promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
+        /** @deprecated Accepted for adapter compatibility but never called. */
+        chmod?: typeof fs.chmod;
+    };
+};
+export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "fstatSync" | "statSync" | "lstatSync" | "ftruncateSync" | "readSync" | "writeSync"> & {
+    /** @deprecated Accepted for adapter compatibility but never called. */
+    chmodSync?: typeof syncFs.chmodSync;
+    fchmodSync?: typeof syncFs.fchmodSync;
 };
-export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "chmodSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "fstatSync" | "statSync" | "lstatSync" | "ftruncateSync" | "readSync" | "writeSync">;
 export type { ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, };
 type ReplaceFileAtomicBaseOptions = {
     filePath: string;

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

@@ -1 +1 @@
-{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC,OAAO,EAKL,KAAK,+BAA+B,EACpC,KAAK,sCAAsC,EAC3C,KAAK,oCAAoC,EACzC,KAAK,oCAAoC,EAC1C,MAAM,iCAAiC,CAAC;AAKzC,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,IAAI,CACZ,OAAO,EAAE,EACP,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,CACV,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,WAAW,GACX,eAAe,GACf,UAAU,GACV,WAAW,CACd,CAAC;AAEF,YAAY,EACV,+BAA+B,EAC/B,sCAAsC,EACtC,oCAAoC,EACpC,oCAAoC,GACrC,CAAC;AAEF,KAAK,4BAA4B,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,mBAAmB,CAAC,EAAE,oCAAoC,CAAC;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,GAAG;IACpE,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,4BAA4B,GAAG;IACxE,UAAU,CAAC,EAAE,+BAA+B,CAAC;IAC7C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACzE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,QAAQ,GAAG,eAAe,CAAC;CACpC,CAAC;AAoOF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAOlC;AA6DD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAsEzB"}
+{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC,OAAO,EAKL,KAAK,+BAA+B,EACpC,KAAK,sCAAsC,EAC3C,KAAK,oCAAoC,EACzC,KAAK,oCAAoC,EAC1C,MAAM,iCAAiC,CAAC;AAazC,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,IAAI,CACZ,OAAO,EAAE,EACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,CACV,GAAG;QACF,uEAAuE;QACvE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,OAAO,MAAM,EACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,WAAW,GACX,eAAe,GACf,UAAU,GACV,WAAW,CACd,GAAG;IACF,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,MAAM,CAAC,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,OAAO,MAAM,CAAC,UAAU,CAAC;CACvC,CAAC;AAEF,YAAY,EACV,+BAA+B,EAC/B,sCAAsC,EACtC,oCAAoC,EACpC,oCAAoC,GACrC,CAAC;AAEF,KAAK,4BAA4B,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,mBAAmB,CAAC,EAAE,oCAAoC,CAAC;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,GAAG;IACpE,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,4BAA4B,GAAG;IACxE,UAAU,CAAC,EAAE,+BAA+B,CAAC;IAC7C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACzE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,QAAQ,GAAG,eAAe,CAAC;CACpC,CAAC;AAgNF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAOlC;AAkED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAoFzB"}

package/dist/replace-file.js

@@ -3,8 +3,10 @@ import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertDestinationHardlinkPolicy, assertDestinationHardlinkPolicySync, copyFallbackReplace, copyFallbackReplaceSync, } from "./replace-file-copy-fallback.js";
+import { applyDirectoryMode, applyDirectoryModeSync, writeTempFile, writeTempFileSync, } from "./replace-file-descriptor.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
+import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 function isRetryableRenameError(error) {
     return error.code === "EBUSY";
@@ -13,9 +15,6 @@ function isPermissionRenameError(error) {
     const code = error.code;
     return code === "EPERM" || code === "EEXIST";
 }
-async function sleep(ms) {
-    await new Promise((resolve) => setTimeout(resolve, ms));
-}
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         try {
@@ -35,6 +34,7 @@ async function renameWithRetry(params) {
                     destinationHardlinks: params.destinationHardlinks,
                     restore: params.copyFallbackRestore,
                     maxRestoreBytes: params.maxRestoreBytes,
+                    sync: params.syncFallback,
                 });
                 return { method: "copy-fallback" };
             }
@@ -43,12 +43,6 @@ async function renameWithRetry(params) {
     }
     throw new Error("Atomic rename retry loop exhausted.");
 }
-function sleepSync(ms) {
-    if (ms <= 0) {
-        return;
-    }
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
 function renameWithRetrySync(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         try {
@@ -68,6 +62,8 @@ function renameWithRetrySync(params) {
                     destinationHardlinks: params.destinationHardlinks,
                     restore: params.copyFallbackRestore,
                     maxRestoreBytes: params.maxRestoreBytes,
+                    fchmodSync: params.fchmodSync,
+                    sync: params.syncFallback,
                 });
                 return { method: "copy-fallback" };
             }
@@ -126,33 +122,8 @@ function resolveModeSync(options) {
     }
     return stat ? stat.mode : defaultMode;
 }
-async function syncTempFile(fsModule, tempPath) {
-    const handle = await fsModule.open(tempPath, "r+");
-    try {
-        await handle.sync();
-    }
-    catch (error) {
-        if (error.code !== "EPERM") {
-            throw error;
-        }
-    }
-    finally {
-        await handle.close();
-    }
-}
-function syncTempFileSync(fsModule, tempPath) {
-    const fd = fsModule.openSync(tempPath, "r+");
-    try {
-        fsModule.fsyncSync(fd);
-    }
-    catch (error) {
-        if (error.code !== "EPERM") {
-            throw error;
-        }
-    }
-    finally {
-        fsModule.closeSync(fd);
-    }
+function missingFchmodSyncError() {
+    return new TypeError("fileSystem.fchmodSync is required when mode, dirMode, or preserveExistingMode is specified");
 }
 async function syncDirectoryBestEffort(fsModule, dirPath) {
     let handle;
@@ -191,9 +162,15 @@ async function cleanupTempFile(params) {
     const cleanupError = await params.fsModule
         .rm(params.tempPath, { force: true })
         .catch((error) => error);
-    if (cleanupError && params.throwOnCleanupError && params.originalError !== undefined) {
-        throw new Error(`Atomic file replace failed (${String(params.originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: params.originalError });
+    if (!cleanupError)
+        return true;
+    if (params.throwOnCleanupError) {
+        if (params.originalError !== undefined) {
+            throw new Error(`Atomic file replace failed (${String(params.originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: params.originalError });
+        }
+        throw cleanupError;
     }
+    return false;
 }
 export async function replaceFileAtomic(options) {
     const filePath = options.filePath;
@@ -213,15 +190,17 @@ async function replaceFileAtomicUnserialized(options) {
     const unregisterTempPath = registerTempPathForExit(tempPath);
     let tempExists = false;
     let originalError;
-    await fsModule.mkdir(dir, { recursive: true, mode: dirMode });
-    await fsModule.chmod(dir, dirMode).catch(() => undefined);
     try {
+        await fsModule.mkdir(dir, { recursive: true, mode: dirMode });
+        await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
         tempExists = true;
-        await fsModule.writeFile(tempPath, options.content, { mode, flag: "wx" });
-        unregisterTempPath.setIdentity(await fsModule.lstat(tempPath));
-        if (options.syncTempFile) {
-            await syncTempFile(fsModule, tempPath);
-        }
+        unregisterTempPath.setIdentity(await writeTempFile({
+            fsModule,
+            tempPath,
+            content: options.content,
+            mode,
+            sync: options.syncTempFile === true,
+        }));
         if (options.beforeRename) {
             await options.beforeRename({ filePath, tempPath });
         }
@@ -236,10 +215,12 @@ async function replaceFileAtomicUnserialized(options) {
             copyFallbackRestore: options.copyFallbackRestore ?? "none",
             maxRestoreBytes: options.maxRestoreBytes,
             destinationHardlinks: options.destinationHardlinks,
+            syncFallback: options.syncTempFile === true,
         });
-        tempExists = false;
-        unregisterTempPath();
-        await fsModule.chmod(filePath, mode).catch(() => undefined);
+        if (result.method === "rename") {
+            tempExists = false;
+            unregisterTempPath();
+        }
         if (options.syncParentDir) {
             await syncDirectoryBestEffort(fsModule, dir);
         }
@@ -250,15 +231,17 @@ async function replaceFileAtomicUnserialized(options) {
         throw error;
     }
     finally {
+        let tempRemoved = !tempExists;
         if (tempExists) {
-            await cleanupTempFile({
+            tempRemoved = await cleanupTempFile({
                 fsModule,
                 tempPath,
                 originalError,
                 throwOnCleanupError: options.throwOnCleanupError === true,
             });
         }
-        unregisterTempPath();
+        if (tempRemoved)
+            unregisterTempPath();
     }
 }
 export function replaceFileAtomicSync(options) {
@@ -269,24 +252,29 @@ export function replaceFileAtomicSync(options) {
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
     const mode = resolveModeSync(options);
+    const fchmodSync = options.fileSystem?.fchmodSync ?? (options.fileSystem === undefined ? syncFs.fchmodSync : undefined);
+    if (!fchmodSync &&
+        (options.mode !== undefined ||
+            options.preserveExistingMode === true ||
+            (process.platform !== "win32" && options.dirMode !== undefined))) {
+        throw missingFchmodSyncError();
+    }
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const unregisterTempPath = registerTempPathForExit(tempPath);
     let tempExists = false;
     let originalError;
-    fsModule.mkdirSync(dir, { recursive: true, mode: dirMode });
-    try {
-        fsModule.chmodSync(dir, dirMode);
-    }
-    catch {
-        // Best-effort on platforms that do not enforce POSIX modes.
-    }
     try {
+        fsModule.mkdirSync(dir, { recursive: true, mode: dirMode });
+        applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
         tempExists = true;
-        fsModule.writeFileSync(tempPath, options.content, { mode, flag: "wx" });
-        unregisterTempPath.setIdentity(fsModule.lstatSync(tempPath));
-        if (options.syncTempFile) {
-            syncTempFileSync(fsModule, tempPath);
-        }
+        unregisterTempPath.setIdentity(writeTempFileSync({
+            fsModule,
+            tempPath,
+            content: options.content,
+            mode,
+            fchmodSync,
+            sync: options.syncTempFile === true,
+        }));
         if (options.beforeRename) {
             options.beforeRename({ filePath, tempPath });
         }
@@ -301,14 +289,12 @@ export function replaceFileAtomicSync(options) {
             copyFallbackRestore: options.copyFallbackRestore ?? "none",
             maxRestoreBytes: options.maxRestoreBytes,
             destinationHardlinks: options.destinationHardlinks,
+            fchmodSync,
+            syncFallback: options.syncTempFile === true,
         });
-        tempExists = false;
-        unregisterTempPath();
-        try {
-            fsModule.chmodSync(filePath, mode);
-        }
-        catch {
-            // Best-effort on platforms that do not enforce POSIX modes.
+        if (result.method === "rename") {
+            tempExists = false;
+            unregisterTempPath();
         }
         if (options.syncParentDir) {
             syncDirectoryBestEffortSync(fsModule, dir);
@@ -320,17 +306,23 @@ export function replaceFileAtomicSync(options) {
         throw error;
     }
     finally {
+        let tempRemoved = !tempExists;
         if (tempExists) {
             try {
                 fsModule.rmSync(tempPath, { force: true });
+                tempRemoved = true;
             }
             catch (cleanupError) {
-                if (options.throwOnCleanupError && originalError !== undefined) {
-                    throw new Error(`Atomic file replace failed (${String(originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: originalError });
+                if (options.throwOnCleanupError) {
+                    if (originalError !== undefined) {
+                        throw new Error(`Atomic file replace failed (${String(originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: originalError });
+                    }
+                    throw cleanupError;
                 }
                 // The temp file is best-effort cleanup after write failure.
             }
         }
-        unregisterTempPath();
+        if (tempRemoved)
+            unregisterTempPath();
     }
 }

package/dist/root-context.d.ts

@@ -1,15 +1,23 @@
 export type RootContext = {
     rootDir: string;
+    rootIdentity: {
+        dev: number;
+        ino: number;
+    };
     rootReal: string;
     rootWithSep: string;
 };
 export declare const ensureTrailingSep: (value: string) => string;
 export declare function assertValidRootRelativePath(relativePath: string): void;
+export declare function assertValidRootDestinationPath(relativePath: string): void;
 export declare function expandRelativePathWithHome(relativePath: string): Promise<string>;
 export declare function resolveRootContext(rootDir: string): Promise<RootContext>;
+export declare function assertRootIdentityCurrent(root: RootContext): Promise<void>;
 export declare function resolvePathInRoot(root: RootContext, relativePath: string, options?: {
     aliasErrorCode?: "outside-workspace" | "path-alias";
     allowFinalSymlink?: boolean;
+    rejectUnsafeDeviceReads?: boolean;
+    rejectSymlinks?: boolean;
 }): Promise<{
     rootReal: string;
     rootWithSep: string;

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

@@ -1 +1 @@
-{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAID,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB9E;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}
+{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAID,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA0B9E;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhF;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0CtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}

package/dist/root-context.js

@@ -2,13 +2,22 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
 import { expandHomePrefix } from "./home-dir.js";
-import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
+import { outsideWorkspaceError } from "./root-errors.js";
+import { isDriveRelativePath } from "./safe-path-segment.js";
 export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
 export function assertValidRootRelativePath(relativePath) {
     assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
 }
+export function assertValidRootDestinationPath(relativePath) {
+    assertValidRootRelativePath(relativePath);
+    if (isDriveRelativePath(relativePath)) {
+        throw new FsSafeError("invalid-path", "relative path must not start with a drive letter");
+    }
+}
 let cachedHomePath;
 export async function expandRelativePathWithHome(relativePath) {
     const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
@@ -27,12 +36,14 @@ export async function expandRelativePathWithHome(relativePath) {
 export async function resolveRootContext(rootDir) {
     assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
     let rootReal;
+    let rootIdentity;
     try {
         rootReal = await fs.realpath(rootDir);
         const rootStat = await fs.stat(rootReal);
         if (!rootStat.isDirectory()) {
             throw new FsSafeError("invalid-path", "root dir is not a directory");
         }
+        rootIdentity = { dev: rootStat.dev, ino: rootStat.ino };
     }
     catch (err) {
         if (err instanceof FsSafeError) {
@@ -45,16 +56,37 @@ export async function resolveRootContext(rootDir) {
     }
     return {
         rootDir: path.resolve(rootDir),
+        rootIdentity,
         rootReal,
         rootWithSep: ensureTrailingSep(rootReal),
     };
 }
+export async function assertRootIdentityCurrent(root) {
+    let current;
+    try {
+        current = await fs.lstat(root.rootReal);
+    }
+    catch (error) {
+        throw new FsSafeError("path-mismatch", "root path changed during operation", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    if (current.isSymbolicLink() ||
+        !current.isDirectory() ||
+        !sameFileIdentity(current, root.rootIdentity)) {
+        throw new FsSafeError("path-mismatch", "root path changed during operation");
+    }
+}
 export async function resolvePathInRoot(root, relativePath, options) {
     assertValidRootRelativePath(relativePath);
+    await assertRootIdentityCurrent(root);
     const expanded = await expandRelativePathWithHome(relativePath);
     const resolved = path.resolve(root.rootWithSep, expanded);
     if (!isPathInside(root.rootWithSep, resolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
+        throw outsideWorkspaceError();
+    }
+    if (options?.rejectUnsafeDeviceReads === true) {
+        assertNoUnsafeDeviceReadPath(resolved);
     }
     const rawAbsolutePath = path.isAbsolute(expanded)
         ? expanded
@@ -66,9 +98,18 @@ export async function resolvePathInRoot(root, relativePath, options) {
             rootCanonicalPath: root.rootReal,
             boundaryLabel: "root",
             policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+            rejectSymlinks: options?.rejectSymlinks,
         });
     }
     catch (error) {
+        if (error instanceof FsSafeError && error.code === "symlink") {
+            throw error;
+        }
+        if (hasNodeErrorCode(error, "ENAMETOOLONG")) {
+            throw new FsSafeError("invalid-path", "relative path is too long", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
         const code = options?.aliasErrorCode ?? "outside-workspace";
         throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", {
             cause: error instanceof Error ? error : undefined,

package/dist/root-errors.d.ts

@@ -1,4 +1,11 @@
+import { FsSafeError } from "./errors.js";
+export declare function fileNotFoundError(cause?: unknown): FsSafeError;
+export declare function outsideWorkspaceError(): 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;
 //# 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":"AAGA,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO9D"}
+{"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"}