@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/regular-file.js

@@ -5,10 +5,10 @@ import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
-import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
-import { assertNoSymlinkParents, assertNoSymlinkParentsSync } from "./symlink-parents.js";
+import { assertNoSymlinkParentsSync } from "./symlink-parents.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { isNonRegularWriteOpenError, isNonRegularWriteOpenErrorSync, resolveNonblockingWriteFlag, } from "./write-open-flags.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
@@ -50,18 +50,7 @@ export function statRegularFileSync(filePath) {
     return { missing: false, stat };
 }
 export async function readRegularFile(params) {
-    const maxBytes = normalizeMaxBytes(params.maxBytes);
-    const filePath = params.filePath;
-    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
-    assertNoUnsafeDeviceReadPath(filePath);
-    const before = await inspectFileIdentity(async () => {
-        const stat = fsSync.lstatSync(filePath, { bigint: true });
-        assertRegularReadStat(stat, filePath, true);
-        return stat;
-    }).catch((error) => throwReadPreviewError(error, filePath));
-    if (maxBytes !== undefined && before.size > maxBytes) {
-        throw regularFileTooLargeError(filePath, maxBytes);
-    }
+    const { filePath, maxBytes, before } = prepareRegularRead(params);
     let handle;
     try {
         handle = await fs.open(filePath, resolveReadOpenFlags());
@@ -73,28 +62,7 @@ export async function readRegularFile(params) {
         throw err;
     }
     try {
-        const stat = fsSync.fstatSync(handle.fd);
-        const identity = await inspectFileIdentity(async () => {
-            const exact = fsSync.fstatSync(handle.fd, { bigint: true });
-            assertRegularReadStat(exact, filePath);
-            return exact;
-        }, before);
-        try {
-            await inspectFileIdentity(async () => {
-                const current = fsSync.lstatSync(filePath, { bigint: true });
-                assertRegularReadStat(current, filePath);
-                return current;
-            }, identity);
-        }
-        catch (err) {
-            if (isNotFoundPathError(err)) {
-                throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
-            }
-            throw err;
-        }
-        if (maxBytes !== undefined && stat.size > maxBytes) {
-            throw regularFileTooLargeError(filePath, maxBytes);
-        }
+        const stat = inspectOpenedRegularRead(handle.fd, filePath, before, maxBytes);
         // With a byte cap, avoid readFile(): a raced file growth would allocate
         // the oversized content before the post-read check could reject it.
         let buffer;
@@ -127,47 +95,7 @@ function assertRegularReadStat(stat, filePath, preview = false) {
         throw new Error(preview ? "path must be a regular file" : `File is not a regular file: ${filePath}`);
     }
 }
-function readOpenedRegularFileSync(params) {
-    const stat = fsSync.fstatSync(params.fd);
-    const identity = inspectFileIdentitySync(() => {
-        const exact = fsSync.fstatSync(params.fd, { bigint: true });
-        assertRegularReadStat(exact, params.filePath);
-        return exact;
-    }, params.preOpenStat);
-    try {
-        inspectFileIdentitySync(() => {
-            const current = fsSync.lstatSync(params.filePath, { bigint: true });
-            assertRegularReadStat(current, params.filePath);
-            return current;
-        }, identity);
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
-        }
-        throw error;
-    }
-    if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-        throw regularFileTooLargeError(params.filePath, params.maxBytes);
-    }
-    // Keep capped sync reads incremental for the same reason as async reads:
-    // readFileSync(fd) would buffer a raced oversized file before throwing.
-    let buffer;
-    try {
-        buffer =
-            params.maxBytes === undefined
-                ? fsSync.readFileSync(params.fd)
-                : readFileDescriptorBoundedSync(params.fd, params.maxBytes);
-    }
-    catch (error) {
-        if (params.maxBytes !== undefined) {
-            translateBoundedReadOverflow(error, params.filePath, params.maxBytes);
-        }
-        throw error;
-    }
-    return { buffer, stat };
-}
-export function readRegularFileSync(params) {
+function prepareRegularRead(params) {
     const maxBytes = normalizeMaxBytes(params.maxBytes);
     const filePath = params.filePath;
     assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
@@ -186,6 +114,35 @@ export function readRegularFileSync(params) {
     if (maxBytes !== undefined && before.size > maxBytes) {
         throw regularFileTooLargeError(filePath, maxBytes);
     }
+    return { filePath, maxBytes, before };
+}
+function inspectOpenedRegularRead(fd, filePath, preOpenStat, maxBytes) {
+    const stat = fsSync.fstatSync(fd);
+    const identity = inspectFileIdentitySync(() => {
+        const exact = fsSync.fstatSync(fd, { bigint: true });
+        assertRegularReadStat(exact, filePath);
+        return exact;
+    }, preOpenStat);
+    try {
+        inspectFileIdentitySync(() => {
+            const current = fsSync.lstatSync(filePath, { bigint: true });
+            assertRegularReadStat(current, filePath);
+            return current;
+        }, identity);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
+        }
+        throw error;
+    }
+    if (maxBytes !== undefined && stat.size > maxBytes) {
+        throw regularFileTooLargeError(filePath, maxBytes);
+    }
+    return stat;
+}
+export function readRegularFileSync(params) {
+    const { filePath, maxBytes, before } = prepareRegularRead(params);
     let fd;
     try {
         fd = fsSync.openSync(filePath, resolveReadOpenFlags());
@@ -197,12 +154,21 @@ export function readRegularFileSync(params) {
         throw error;
     }
     try {
-        return readOpenedRegularFileSync({
-            fd,
-            filePath,
-            preOpenStat: before,
-            maxBytes,
-        });
+        const stat = inspectOpenedRegularRead(fd, filePath, before, maxBytes);
+        // Keep capped reads incremental so raced growth cannot allocate unbounded content.
+        let buffer;
+        try {
+            buffer = maxBytes === undefined
+                ? fsSync.readFileSync(fd)
+                : readFileDescriptorBoundedSync(fd, maxBytes);
+        }
+        catch (error) {
+            if (maxBytes !== undefined) {
+                translateBoundedReadOverflow(error, filePath, maxBytes);
+            }
+            throw error;
+        }
+        return { buffer, stat };
     }
     finally {
         fsSync.closeSync(fd);
@@ -240,11 +206,10 @@ function inspectAppendPath(filePath) {
         throw new Error(`Refusing to append to non-file: ${filePath}`);
     return stat;
 }
-export async function appendRegularFile(options) {
-    const { filePath, content, encoding, mode, maxFileBytes, rejectSymlinkParents } = captureAppendOptions(options);
+function prepareRegularAppend(filePath, rejectSymlinkParents) {
     if (rejectSymlinkParents === true) {
         const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
-        await assertNoSymlinkParents({
+        assertNoSymlinkParentsSync({
             rootDir: path.parse(resolvedDir).root,
             targetPath: resolvedDir,
             allowMissing: false,
@@ -253,14 +218,35 @@ export async function appendRegularFile(options) {
             messagePrefix: "Refusing to append under",
         });
     }
-    let preOpenStat;
     try {
-        preOpenStat = await inspectFileIdentity(async () => inspectAppendPath(filePath));
+        return inspectFileIdentitySync(() => inspectAppendPath(filePath));
     }
     catch (error) {
         if (!isNotFoundPathError(error))
             throw error;
     }
+}
+function inspectOpenedRegularAppend(fd, filePath, preOpenStat) {
+    try {
+        const identity = inspectFileIdentitySync(() => {
+            const stat = fsSync.fstatSync(fd, { bigint: true });
+            assertRegularAppendStat(stat, filePath);
+            return stat;
+        }, preOpenStat);
+        inspectFileIdentitySync(() => {
+            const current = fsSync.lstatSync(filePath, { bigint: true });
+            assertRegularAppendStat(current, filePath);
+            return current;
+        }, identity);
+        return identity;
+    }
+    catch (error) {
+        throwAppendIdentityError(error, filePath);
+    }
+}
+export async function appendRegularFile(options) {
+    const { filePath, content, encoding, mode, maxFileBytes, rejectSymlinkParents } = captureAppendOptions(options);
+    const preOpenStat = prepareRegularAppend(filePath, rejectSymlinkParents);
     const contentBytes = Buffer.isBuffer(content) ? content.byteLength : Buffer.byteLength(content, encoding);
     if (maxFileBytes !== undefined &&
         Number(preOpenStat?.size ?? 0n) + contentBytes > maxFileBytes) {
@@ -279,22 +265,7 @@ export async function appendRegularFile(options) {
         throw error;
     }
     try {
-        let identity;
-        try {
-            identity = await inspectFileIdentity(async () => {
-                const stat = fsSync.fstatSync(handle.fd, { bigint: true });
-                assertRegularAppendStat(stat, filePath);
-                return stat;
-            }, preOpenStat);
-            await inspectFileIdentity(async () => {
-                const current = fsSync.lstatSync(filePath, { bigint: true });
-                assertRegularAppendStat(current, filePath);
-                return current;
-            }, identity);
-        }
-        catch (error) {
-            throwAppendIdentityError(error, filePath);
-        }
+        const identity = inspectOpenedRegularAppend(handle.fd, filePath, preOpenStat);
         if (maxFileBytes !== undefined &&
             Number(identity.size) + contentBytes > maxFileBytes) {
             return;
@@ -311,25 +282,7 @@ export async function appendRegularFile(options) {
 }
 export function appendRegularFileSync(options) {
     const { filePath, content, encoding, mode, maxFileBytes, rejectSymlinkParents } = captureAppendOptions(options);
-    if (rejectSymlinkParents === true) {
-        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
-        assertNoSymlinkParentsSync({
-            rootDir: path.parse(resolvedDir).root,
-            targetPath: resolvedDir,
-            allowMissing: false,
-            allowRootChildSymlink: true,
-            requireDirectories: true,
-            messagePrefix: "Refusing to append under",
-        });
-    }
-    let preOpenStat;
-    try {
-        preOpenStat = inspectFileIdentitySync(() => inspectAppendPath(filePath));
-    }
-    catch (error) {
-        if (!isNotFoundPathError(error))
-            throw error;
-    }
+    const preOpenStat = prepareRegularAppend(filePath, rejectSymlinkParents);
     const contentBuffer = typeof content === "string" ? Buffer.from(content, encoding) : Buffer.from(content);
     if (maxFileBytes !== undefined &&
         Number(preOpenStat?.size ?? 0n) + contentBuffer.byteLength > maxFileBytes) {
@@ -348,22 +301,7 @@ export function appendRegularFileSync(options) {
         throw error;
     }
     try {
-        let identity;
-        try {
-            identity = inspectFileIdentitySync(() => {
-                const stat = fsSync.fstatSync(fd, { bigint: true });
-                assertRegularAppendStat(stat, filePath);
-                return stat;
-            }, preOpenStat);
-            inspectFileIdentitySync(() => {
-                const current = fsSync.lstatSync(filePath, { bigint: true });
-                assertRegularAppendStat(current, filePath);
-                return current;
-            }, identity);
-        }
-        catch (error) {
-            throwAppendIdentityError(error, filePath);
-        }
+        const identity = inspectOpenedRegularAppend(fd, filePath, preOpenStat);
         if (maxFileBytes !== undefined &&
             Number(identity.size) + contentBuffer.byteLength > maxFileBytes) {
             return;

package/dist/replace-directory.d.ts

@@ -4,4 +4,3 @@ export type ReplaceDirectoryAtomicOptions = {
     backupPrefix?: string;
 };
 export declare function replaceDirectoryAtomic(options: ReplaceDirectoryAtomicOptions): Promise<void>;
-//# sourceMappingURL=replace-directory.d.ts.map

package/dist/replace-directory.js

@@ -8,9 +8,8 @@ import { classifyNativeRenameFailure, NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH, }
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { serializePathWrite } from "./write-queue.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 function distinctGuards(source, target) {
     return source === target ? [source] : [source, target];
 }

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

@@ -36,4 +36,3 @@ export declare function copyFallbackReplaceSync(params: {
     sync: boolean;
 }): void;
 export {};
-//# sourceMappingURL=replace-file-copy-fallback.d.ts.map

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

@@ -73,7 +73,12 @@ async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
         return handle;
     }
     catch (error) {
-        await handle.close().catch(() => undefined);
+        try {
+            await handle.close();
+        }
+        catch {
+            // Preserve the already-selected admission failure.
+        }
         throw error;
     }
 }
@@ -105,8 +110,14 @@ export async function assertDestinationHardlinkPolicy(fsModule, dest, policy) {
     if (policy !== "reject")
         return;
     const handle = await openPinnedDestination(fsModule, dest, "hardlinks");
-    if (handle)
-        await handle.close().catch(() => undefined);
+    if (!handle)
+        return;
+    try {
+        await handle.close();
+    }
+    catch {
+        // The asynchronous admission pin has best-effort close semantics.
+    }
 }
 export function assertDestinationHardlinkPolicySync(fsModule, dest, policy) {
     if (policy !== "reject")

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

@@ -18,4 +18,3 @@ export declare function readOwnedCopySourceSync(params: {
     mode: number;
 };
 export {};
-//# sourceMappingURL=replace-file-copy-source.d.ts.map

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

@@ -73,7 +73,12 @@ export async function readOwnedCopySource(params) {
         return { replacement: await handle.readFile(), mode: Number(opened.mode) };
     }
     finally {
-        await handle.close().catch(() => undefined);
+        try {
+            await handle.close();
+        }
+        catch {
+            // Best-effort close includes synchronous adapter throws.
+        }
     }
 }
 export function readOwnedCopySourceSync(params) {

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

@@ -48,4 +48,3 @@ export declare function writeTempFileSync(params: {
     identity: BigIntStats;
 };
 export {};
-//# sourceMappingURL=replace-file-descriptor.d.ts.map

package/dist/replace-file-descriptor.js

@@ -14,7 +14,12 @@ export async function syncDirectoryBestEffort(fsModule, dirPath) {
         // Best-effort on platforms/filesystems that do not support directory fsync.
     }
     finally {
-        await handle?.close().catch(() => undefined);
+        try {
+            await handle?.close();
+        }
+        catch {
+            // Best-effort close also covers synchronous adapter throws.
+        }
     }
 }
 export function syncDirectoryBestEffortSync(fsModule, dirPath) {

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

@@ -1,3 +1,2 @@
 import type { Stats } from "node:fs";
 export declare function inheritedRegularFileMode(stat: Stats): number;
-//# sourceMappingURL=replace-file-mode.d.ts.map

package/dist/replace-file-rename-policy.d.ts

@@ -1,7 +1,5 @@
-import type { RenameIdentityPolicy } from "./pinned-write.js";
-export type { RenameIdentityPolicy };
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
 export declare function validateRenameIdentity(policy: RenameIdentityPolicy | undefined): void;
 export declare function atomicExpectedContentHash(policy: RenameIdentityPolicy | undefined, content: string | Uint8Array): string | undefined;
 export declare function withAtomicRenameIdentityLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
 export declare function withAtomicRenameIdentityLockSync<T>(filePath: string, fn: () => T): T;
-//# sourceMappingURL=replace-file-rename-policy.d.ts.map

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

@@ -1,45 +1,45 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
+import { type TempPathRegistration } from "./temp-cleanup.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 class AsyncAtomicTempOwner {
-    #private;
+declare class AtomicTempOwner<Resource> {
     readonly pathname: string;
+    protected resource: Resource | undefined;
+    protected recordedIdentity: BigIntStats | undefined;
+    protected exists: boolean;
+    protected unregister: TempPathRegistration;
     constructor(pathname: string);
     start(): void;
     readonly onIdentity: (identity: BigIntStats) => void;
+    get identity(): BigIntStats;
+    markRenamed(): void;
+    protected takeResource(): Resource | undefined;
+}
+export declare class AsyncAtomicTempOwner extends AtomicTempOwner<FileHandle> {
     adopt(temp: {
         handle: FileHandle;
         identity: BigIntStats;
     }): void;
-    get identity(): BigIntStats;
     assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
     assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
-    markRenamed(): void;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): Promise<void>;
 }
-export declare class SyncAtomicTempOwner {
-    #private;
-    readonly pathname: string;
-    constructor(pathname: string);
-    start(): void;
-    readonly onIdentity: (identity: BigIntStats) => void;
+export declare class SyncAtomicTempOwner extends AtomicTempOwner<number> {
     adopt(temp: {
         fd: number;
         identity: BigIntStats;
     }): void;
-    get identity(): BigIntStats;
     assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
     assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
-    markRenamed(): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;
@@ -47,4 +47,3 @@ export declare class SyncAtomicTempOwner {
     }): void;
 }
 export {};
-//# sourceMappingURL=replace-file-temp-owner.d.ts.map