@openclaw/fs-safe 0.4.7 → 0.5.1

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

@@ -0,0 +1,339 @@
+import syncFs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants;
+const NOFOLLOW = SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0;
+const OPEN_READ_FLAGS = syncFs.constants.O_RDONLY | NOFOLLOW;
+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;
+const READ_CHUNK_BYTES = 64 * 1024;
+function notFound(error) {
+    return error.code === "ENOENT";
+}
+function assertPinnedDestination(pathname, opened, dest, hardlinks) {
+    if (pathname.isSymbolicLink()) {
+        throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
+    }
+    if (!pathname.isFile() || !opened.isFile()) {
+        throw new FsSafeError("not-file", `Copy fallback destination must be a regular file: ${dest}`);
+    }
+    if (!sameFileIdentity(pathname, opened)) {
+        throw new FsSafeError("path-mismatch", `Copy fallback destination changed while opening: ${dest}`);
+    }
+    if (hardlinks === "reject" && opened.nlink > 1) {
+        throw new FsSafeError("hardlink", `Hardlinked copy fallback destination not allowed: ${dest}`);
+    }
+}
+async function openPinnedDestination(fsModule, dest, hardlinks) {
+    const preview = await fsModule.lstat(dest).catch((error) => {
+        if (notFound(error))
+            return null;
+        throw error;
+    });
+    if (!preview)
+        return null;
+    if (preview.isSymbolicLink()) {
+        throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
+    }
+    const handle = await fsModule.open(dest, OPEN_READ_WRITE_FLAGS);
+    try {
+        const opened = await handle.stat();
+        const current = await fsModule.lstat(dest);
+        assertPinnedDestination(current, opened, dest, hardlinks);
+        return { handle, stat: opened };
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+function openPinnedDestinationSync(fsModule, dest, hardlinks) {
+    let preview;
+    try {
+        preview = fsModule.lstatSync(dest);
+    }
+    catch (error) {
+        if (notFound(error))
+            return null;
+        throw error;
+    }
+    if (preview.isSymbolicLink()) {
+        throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
+    }
+    const fd = fsModule.openSync(dest, OPEN_READ_WRITE_FLAGS);
+    try {
+        const opened = fsModule.fstatSync(fd);
+        assertPinnedDestination(fsModule.lstatSync(dest), opened, dest, hardlinks);
+        return { fd, stat: opened };
+    }
+    catch (error) {
+        fsModule.closeSync(fd);
+        throw error;
+    }
+}
+export async function assertDestinationHardlinkPolicy(fsModule, dest, policy) {
+    if (policy !== "reject")
+        return;
+    const preview = await fsModule.lstat(dest).catch((error) => {
+        if (notFound(error))
+            return null;
+        throw error;
+    });
+    if (!preview || preview.isSymbolicLink() || !preview.isFile())
+        return;
+    const handle = await fsModule.open(dest, OPEN_READ_FLAGS);
+    try {
+        const opened = await handle.stat();
+        const current = 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 {
+        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 {
+        fsModule.closeSync(fd);
+    }
+}
+async function readBounded(handle, maxBytes) {
+    const chunks = [];
+    let position = 0;
+    while (position <= maxBytes) {
+        const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - position + 1));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+        if (bytesRead === 0)
+            break;
+        position += bytesRead;
+        if (position > maxBytes) {
+            throw new FsSafeError("too-large", `Atomic replace restore snapshot exceeds maxRestoreBytes (${maxBytes})`);
+        }
+        chunks.push(buffer.subarray(0, bytesRead));
+    }
+    return Buffer.concat(chunks, position);
+}
+function readBoundedSync(fsModule, fd, maxBytes) {
+    const chunks = [];
+    let position = 0;
+    while (position <= maxBytes) {
+        const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes - position + 1));
+        const bytesRead = fsModule.readSync(fd, buffer, 0, buffer.length, position);
+        if (bytesRead === 0)
+            break;
+        position += bytesRead;
+        if (position > maxBytes) {
+            throw new FsSafeError("too-large", `Atomic replace restore snapshot exceeds maxRestoreBytes (${maxBytes})`);
+        }
+        chunks.push(buffer.subarray(0, bytesRead));
+    }
+    return Buffer.concat(chunks, position);
+}
+async function writeAll(handle, data) {
+    await handle.truncate(0);
+    let written = 0;
+    while (written < data.length) {
+        const result = await handle.write(data, written, data.length - written, written);
+        if (result.bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += result.bytesWritten;
+    }
+    await handle.truncate(data.length);
+}
+function writeAllSync(fsModule, fd, data) {
+    fsModule.ftruncateSync(fd, 0);
+    let written = 0;
+    while (written < data.length) {
+        const bytesWritten = fsModule.writeSync(fd, data, written, data.length - written, written);
+        if (bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += bytesWritten;
+    }
+    fsModule.ftruncateSync(fd, data.length);
+}
+function restoreFailure(writeError, cleanup, restoreError) {
+    const primary = writeError instanceof Error ? writeError : new Error(String(writeError));
+    const details = { cleanup };
+    const cause = restoreError
+        ? new AggregateError([primary, restoreError], "copy fallback and original restoration both failed")
+        : primary;
+    return new FsSafeError("helper-failed", cleanup === "restored"
+        ? `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) {
+    const original = await readBounded(handle, maxRestoreBytes);
+    try {
+        await writeAll(handle, replacement);
+        await handle.sync();
+    }
+    catch (writeError) {
+        try {
+            await writeAll(handle, original);
+            await handle.sync();
+            throw restoreFailure(writeError, "restored");
+        }
+        catch (restoreError) {
+            if (restoreError instanceof FsSafeError && restoreError.details?.cleanup === "restored") {
+                throw restoreError;
+            }
+            throw restoreFailure(writeError, "restore-failed", restoreError);
+        }
+    }
+}
+function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes) {
+    const original = readBoundedSync(fsModule, fd, maxRestoreBytes);
+    try {
+        writeAllSync(fsModule, fd, replacement);
+        fsModule.fsyncSync(fd);
+    }
+    catch (writeError) {
+        try {
+            writeAllSync(fsModule, fd, original);
+            fsModule.fsyncSync(fd);
+            throw restoreFailure(writeError, "restored");
+        }
+        catch (restoreError) {
+            if (restoreError instanceof FsSafeError && restoreError.details?.cleanup === "restored") {
+                throw restoreError;
+            }
+            throw restoreFailure(writeError, "restore-failed", restoreError);
+        }
+    }
+}
+export async function copyFallbackReplace(params) {
+    const sourcePreview = await params.fsModule.lstat(params.src);
+    if (sourcePreview.isSymbolicLink() || !sourcePreview.isFile()) {
+        throw new Error(`Refusing copy fallback from non-file source: ${params.src}`);
+    }
+    const sourceHandle = await params.fsModule.open(params.src, OPEN_READ_FLAGS);
+    let destHandle = null;
+    try {
+        const sourceStat = await sourceHandle.stat();
+        const sourceCurrent = await params.fsModule.lstat(params.src);
+        if (!sourceStat.isFile() || sourceCurrent.isSymbolicLink() || !sameFileIdentity(sourceStat, sourceCurrent)) {
+            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
+        }
+        const replacement = await sourceHandle.readFile();
+        if (params.restore === "restore-original") {
+            const pinned = await openPinnedDestination(params.fsModule, params.dest, params.destinationHardlinks);
+            if (pinned) {
+                destHandle = pinned.handle;
+                await replacePinnedWithRestore(destHandle, replacement, params.maxRestoreBytes);
+            }
+        }
+        if (!destHandle) {
+            const destStat = await params.fsModule.lstat(params.dest).catch((error) => {
+                if (notFound(error))
+                    return null;
+                throw error;
+            });
+            if (destStat?.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${params.dest}`);
+            }
+            if (destStat) {
+                await assertDestinationHardlinkPolicy(params.fsModule, params.dest, params.destinationHardlinks);
+                await params.fsModule.rm(params.dest, { force: true });
+            }
+            destHandle = await params.fsModule.open(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
+            await destHandle.writeFile(replacement);
+        }
+    }
+    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);
+    if (sourcePreview.isSymbolicLink() || !sourcePreview.isFile()) {
+        throw new Error(`Refusing copy fallback from non-file source: ${params.src}`);
+    }
+    const sourceFd = params.fsModule.openSync(params.src, OPEN_READ_FLAGS);
+    let destFd;
+    try {
+        const sourceStat = params.fsModule.fstatSync(sourceFd);
+        const sourceCurrent = params.fsModule.lstatSync(params.src);
+        if (!sourceStat.isFile() || sourceCurrent.isSymbolicLink() || !sameFileIdentity(sourceStat, sourceCurrent)) {
+            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
+        }
+        const replacement = readBoundedSync(params.fsModule, sourceFd, Number.MAX_SAFE_INTEGER);
+        if (params.restore === "restore-original") {
+            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, params.destinationHardlinks);
+            if (pinned) {
+                destFd = pinned.fd;
+                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes);
+            }
+        }
+        if (destFd === undefined) {
+            let destStat = null;
+            try {
+                destStat = params.fsModule.lstatSync(params.dest);
+            }
+            catch (error) {
+                if (!notFound(error))
+                    throw error;
+            }
+            if (destStat?.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${params.dest}`);
+            }
+            if (destStat) {
+                assertDestinationHardlinkPolicySync(params.fsModule, params.dest, params.destinationHardlinks);
+                params.fsModule.rmSync(params.dest, { force: true });
+            }
+            destFd = params.fsModule.openSync(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
+            writeAllSync(params.fsModule, destFd, replacement);
+        }
+    }
+    finally {
+        if (destFd !== undefined) {
+            try {
+                params.fsModule.closeSync(destFd);
+            }
+            catch {
+                // Best-effort close after fallback replacement.
+            }
+        }
+        try {
+            params.fsModule.closeSync(sourceFd);
+        }
+        catch {
+            // Best-effort close after fallback replacement.
+        }
+    }
+    try {
+        params.fsModule.unlinkSync(params.src);
+    }
+    catch {
+        // Best-effort cleanup after fallback replacement.
+    }
+}

package/dist/replace-file.d.ts

@@ -1,9 +1,11 @@
 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">;
 };
-export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "chmodSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "statSync" | "lstatSync">;
+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;
     content: string | Uint8Array;
@@ -14,6 +16,9 @@ type ReplaceFileAtomicBaseOptions = {
     renameMaxRetries?: number;
     renameRetryBaseDelayMs?: number;
     copyFallbackOnPermissionError?: boolean;
+    copyFallbackRestore?: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
     syncTempFile?: boolean;
     syncParentDir?: boolean;
     throwOnCleanupError?: boolean;
@@ -37,5 +42,4 @@ export type ReplaceFileAtomicResult = {
 };
 export declare function replaceFileAtomic(options: ReplaceFileAtomicOptions): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicSync(options: ReplaceFileAtomicSyncOptions): ReplaceFileAtomicResult;
-export {};
 //# sourceMappingURL=replace-file.d.ts.map

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;AAMlC,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,UAAU,GACV,WAAW,CACd,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,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;AAySF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAMlC;AAyDD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAiEzB"}
+{"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"}

package/dist/replace-file.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 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 { assertSafePathPrefix } from "./safe-path-segment.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { serializePathWrite } from "./write-queue.js";
@@ -12,12 +13,6 @@ function isPermissionRenameError(error) {
     const code = error.code;
     return code === "EPERM" || code === "EEXIST";
 }
-const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants;
-const OPEN_READ_FLAGS = syncFs.constants.O_RDONLY | (SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0);
-const OPEN_WRITE_EXCLUSIVE_FLAGS = syncFs.constants.O_WRONLY |
-    syncFs.constants.O_CREAT |
-    syncFs.constants.O_EXCL |
-    (SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0);
 async function sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -33,7 +28,14 @@ async function renameWithRetry(params) {
                 continue;
             }
             if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
-                await copyFallbackReplace(params.fsModule, params.src, params.dest);
+                await copyFallbackReplace({
+                    fsModule: params.fsModule,
+                    src: params.src,
+                    dest: params.dest,
+                    destinationHardlinks: params.destinationHardlinks,
+                    restore: params.copyFallbackRestore,
+                    maxRestoreBytes: params.maxRestoreBytes,
+                });
                 return { method: "copy-fallback" };
             }
             throw error;
@@ -59,7 +61,14 @@ function renameWithRetrySync(params) {
                 continue;
             }
             if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
-                copyFallbackReplaceSync(params.fsModule, params.src, params.dest);
+                copyFallbackReplaceSync({
+                    fsModule: params.fsModule,
+                    src: params.src,
+                    dest: params.dest,
+                    destinationHardlinks: params.destinationHardlinks,
+                    restore: params.copyFallbackRestore,
+                    maxRestoreBytes: params.maxRestoreBytes,
+                });
                 return { method: "copy-fallback" };
             }
             throw error;
@@ -67,93 +76,21 @@ function renameWithRetrySync(params) {
     }
     throw new Error("Atomic rename retry loop exhausted.");
 }
-async function copyFallbackReplace(fsModule, src, dest) {
-    const sourceStat = await fsModule.lstat(src);
-    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-        throw new Error(`Refusing copy fallback from non-file source: ${src}`);
-    }
-    const destStat = await fsModule.lstat(dest).catch((lstatError) => {
-        if (lstatError.code === "ENOENT") {
-            return null;
-        }
-        throw lstatError;
-    });
-    if (destStat?.isSymbolicLink()) {
-        throw new Error(`Refusing copy fallback through symlink destination: ${dest}`);
-    }
-    if (destStat) {
-        await fsModule.rm(dest, { force: true });
-    }
-    let sourceHandle = null;
-    let destHandle = null;
-    try {
-        sourceHandle = await fsModule.open(src, OPEN_READ_FLAGS);
-        destHandle = await fsModule.open(dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
-        await destHandle.writeFile(await sourceHandle.readFile());
-    }
-    finally {
-        await destHandle?.close().catch(() => undefined);
-        await sourceHandle?.close().catch(() => undefined);
-    }
-    await fsModule.unlink(src).catch(() => undefined);
-}
-function copyFallbackReplaceSync(fsModule, src, dest) {
-    const sourceStat = fsModule.lstatSync(src);
-    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-        throw new Error(`Refusing copy fallback from non-file source: ${src}`);
-    }
-    let destStat = null;
-    try {
-        destStat = fsModule.lstatSync(dest);
-    }
-    catch (lstatError) {
-        if (lstatError.code !== "ENOENT") {
-            throw lstatError;
-        }
-    }
-    if (destStat?.isSymbolicLink()) {
-        throw new Error(`Refusing copy fallback through symlink destination: ${dest}`);
-    }
-    if (destStat) {
-        fsModule.rmSync(dest, { force: true });
-    }
-    let sourceFd;
-    let destFd;
-    try {
-        sourceFd = fsModule.openSync(src, OPEN_READ_FLAGS);
-        destFd = fsModule.openSync(dest, OPEN_WRITE_EXCLUSIVE_FLAGS, sourceStat.mode & 0o777);
-        fsModule.writeFileSync(destFd, fsModule.readFileSync(sourceFd));
-    }
-    finally {
-        if (destFd !== undefined) {
-            try {
-                fsModule.closeSync(destFd);
-            }
-            catch {
-                // Best-effort close after fallback replacement.
-            }
-        }
-        if (sourceFd !== undefined) {
-            try {
-                fsModule.closeSync(sourceFd);
-            }
-            catch {
-                // Best-effort close after fallback replacement.
-            }
-        }
-    }
-    try {
-        fsModule.unlinkSync(src);
-    }
-    catch {
-        // Best-effort cleanup after fallback replacement.
-    }
-}
 function validateReplaceFilePath(filePath) {
     if (!filePath || filePath.includes("\0")) {
         throw new Error("Atomic replace file path must be non-empty.");
     }
 }
+function validateRestoreOptions(options) {
+    if (options.copyFallbackRestore !== "restore-original")
+        return;
+    if (options.maxRestoreBytes === undefined) {
+        throw new RangeError("maxRestoreBytes is required when copyFallbackRestore is restore-original");
+    }
+    if (!Number.isSafeInteger(options.maxRestoreBytes) || options.maxRestoreBytes < 0) {
+        throw new RangeError("maxRestoreBytes must be a non-negative safe integer");
+    }
+}
 function buildReplaceTempPath(filePath, tempPrefix) {
     const dir = path.dirname(filePath);
     const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-replace", { label: "atomic replace temp prefix" });
@@ -261,6 +198,7 @@ async function cleanupTempFile(params) {
 export async function replaceFileAtomic(options) {
     const filePath = options.filePath;
     validateReplaceFilePath(filePath);
+    validateRestoreOptions(options);
     return await serializePathWrite(path.resolve(filePath), async () => {
         return await replaceFileAtomicUnserialized(options);
     });
@@ -280,12 +218,14 @@ async function replaceFileAtomicUnserialized(options) {
     try {
         tempExists = true;
         await fsModule.writeFile(tempPath, options.content, { mode, flag: "wx" });
+        unregisterTempPath.setIdentity(await fsModule.lstat(tempPath));
         if (options.syncTempFile) {
             await syncTempFile(fsModule, tempPath);
         }
         if (options.beforeRename) {
             await options.beforeRename({ filePath, tempPath });
         }
+        await assertDestinationHardlinkPolicy(fsModule, filePath, options.destinationHardlinks);
         const result = await renameWithRetry({
             fsModule,
             src: tempPath,
@@ -293,6 +233,9 @@ async function replaceFileAtomicUnserialized(options) {
             maxRetries: options.renameMaxRetries ?? 0,
             baseDelayMs: options.renameRetryBaseDelayMs ?? 50,
             copyFallbackOnPermissionError: options.copyFallbackOnPermissionError === true,
+            copyFallbackRestore: options.copyFallbackRestore ?? "none",
+            maxRestoreBytes: options.maxRestoreBytes,
+            destinationHardlinks: options.destinationHardlinks,
         });
         tempExists = false;
         unregisterTempPath();
@@ -321,6 +264,7 @@ async function replaceFileAtomicUnserialized(options) {
 export function replaceFileAtomicSync(options) {
     const filePath = options.filePath;
     validateReplaceFilePath(filePath);
+    validateRestoreOptions(options);
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
@@ -339,12 +283,14 @@ export function replaceFileAtomicSync(options) {
     try {
         tempExists = true;
         fsModule.writeFileSync(tempPath, options.content, { mode, flag: "wx" });
+        unregisterTempPath.setIdentity(fsModule.lstatSync(tempPath));
         if (options.syncTempFile) {
             syncTempFileSync(fsModule, tempPath);
         }
         if (options.beforeRename) {
             options.beforeRename({ filePath, tempPath });
         }
+        assertDestinationHardlinkPolicySync(fsModule, filePath, options.destinationHardlinks);
         const result = renameWithRetrySync({
             fsModule,
             src: tempPath,
@@ -352,6 +298,9 @@ export function replaceFileAtomicSync(options) {
             maxRetries: options.renameMaxRetries ?? 0,
             baseDelayMs: options.renameRetryBaseDelayMs ?? 50,
             copyFallbackOnPermissionError: options.copyFallbackOnPermissionError === true,
+            copyFallbackRestore: options.copyFallbackRestore ?? "none",
+            maxRestoreBytes: options.maxRestoreBytes,
+            destinationHardlinks: options.destinationHardlinks,
         });
         tempExists = false;
         unregisterTempPath();

package/dist/root-context.d.ts

@@ -7,7 +7,10 @@ export declare const ensureTrailingSep: (value: string) => string;
 export declare function assertValidRootRelativePath(relativePath: string): void;
 export declare function expandRelativePathWithHome(relativePath: string): Promise<string>;
 export declare function resolveRootContext(rootDir: string): Promise<RootContext>;
-export declare function resolvePathInRoot(root: RootContext, relativePath: string): Promise<{
+export declare function resolvePathInRoot(root: RootContext, relativePath: string, options?: {
+    aliasErrorCode?: "outside-workspace" | "path-alias";
+    allowFinalSymlink?: boolean;
+}): Promise<{
     rootReal: string;
     rootWithSep: string;
     resolved: 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":"AAOA,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,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAQtE;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":"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"}

package/dist/root-context.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { expandHomePrefix } from "./home-dir.js";
 import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.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");
@@ -48,13 +49,31 @@ export async function resolveRootContext(rootDir) {
         rootWithSep: ensureTrailingSep(rootReal),
     };
 }
-export async function resolvePathInRoot(root, relativePath) {
+export async function resolvePathInRoot(root, relativePath, options) {
     assertValidRootRelativePath(relativePath);
     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");
     }
+    const rawAbsolutePath = path.isAbsolute(expanded)
+        ? expanded
+        : `${root.rootWithSep}${expanded}`;
+    try {
+        await resolveRootPath({
+            absolutePath: rawAbsolutePath,
+            rootPath: root.rootReal,
+            rootCanonicalPath: root.rootReal,
+            boundaryLabel: "root",
+            policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+        });
+    }
+    catch (error) {
+        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,
+        });
+    }
     return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
 }
 export async function resolvePathWithinRoot(params) {