@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/json.js

@@ -3,37 +3,34 @@ import fsSync from "node:fs";
 import path from "node:path";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { readRegularFile, readRegularFileSync, statRegularFile } from "./regular-file.js";
 import { openRootFileSync } from "./root-file.js";
-import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { writeTempFileSync } from "./replace-file-descriptor.js";
+import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
 import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
 import { writeTextAtomic } from "./text-atomic.js";
 import { sleep } from "./timing.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 const READ_RETRY_MAX_ATTEMPTS = 5;
 const READ_RETRY_BASE_DELAY_MS = 50;
-function isRetryableReadError(err, options) {
+function isRetryableReadError(err) {
     if (err instanceof FsSafeError && err.code === "path-mismatch") {
         return true;
     }
-    if (options.retryOpenRaceErrors !== true) {
-        return false;
-    }
     const code = getErrorCode(err);
     return code === "ENOENT" || code === "EPERM";
 }
-async function readRegularFileWithRetry(filePath, options = {}) {
+async function readRegularFileWithRetry(filePath, maxBytes) {
     let lastErr;
     for (let attempt = 0; attempt < READ_RETRY_MAX_ATTEMPTS; attempt++) {
         try {
-            return (await readRegularFile({ filePath, maxBytes: options.maxBytes })).buffer;
+            return (await readRegularFile({ filePath, maxBytes })).buffer;
         }
         catch (err) {
             lastErr = err;
-            if (!isRetryableReadError(err, options) || attempt === READ_RETRY_MAX_ATTEMPTS - 1) {
+            if (!isRetryableReadError(err) || attempt === READ_RETRY_MAX_ATTEMPTS - 1) {
                 throw err;
             }
             await sleep(READ_RETRY_BASE_DELAY_MS * Math.pow(2, attempt));
@@ -46,52 +43,19 @@ async function readRegularFileIfExistsWithRetry(filePath, options = {}) {
     if (initial.missing) {
         return null;
     }
-    return await readRegularFileWithRetry(filePath, {
-        maxBytes: options.maxBytes,
-        retryOpenRaceErrors: true,
-    });
+    return await readRegularFileWithRetry(filePath, options.maxBytes);
 }
 const JSON_FILE_MODE = 0o600;
 const JSON_DIR_MODE = 0o700;
 function getErrorCode(err) {
     return err instanceof Error ? err.code : undefined;
 }
-function trySetSecureMode(pathname, expectedIdentity) {
-    let fd;
+function trySetSecureMode(fd) {
     try {
-        const before = fsSync.lstatSync(pathname, { bigint: true });
-        if (before.isSymbolicLink() ||
-            !before.isFile() ||
-            before.nlink !== 1n ||
-            !sameFileIdentityForCleanup(before, expectedIdentity)) {
-            return;
-        }
-        fd = fsSync.openSync(pathname, resolveReadOpenFlags());
-        const opened = fsSync.fstatSync(fd, { bigint: true });
-        const current = fsSync.lstatSync(pathname, { bigint: true });
-        if (!opened.isFile() ||
-            opened.nlink !== 1n ||
-            current.isSymbolicLink() ||
-            !current.isFile() ||
-            current.nlink !== 1n ||
-            !sameFileIdentityForCleanup(opened, expectedIdentity) ||
-            !sameFileIdentityForCleanup(current, opened)) {
-            return;
-        }
         fsSync.fchmodSync(fd, JSON_FILE_MODE);
     }
     catch {
-        // Best-effort mode application never falls back to a mutable pathname.
-    }
-    finally {
-        if (fd !== undefined) {
-            try {
-                fsSync.closeSync(fd);
-            }
-            catch {
-                // best-effort cleanup
-            }
-        }
+        // Best-effort mode application stays on the retained staging descriptor.
     }
 }
 function trySyncDirectory(pathname) {
@@ -114,48 +78,24 @@ function trySyncDirectory(pathname) {
         }
     }
 }
-function renameJsonFileWithFallback(tmpPath, pathname) {
+function renameJsonFileWithFallback(owner, pathname) {
+    owner.assertCurrent(fsSync);
     try {
-        fsSync.renameSync(tmpPath, pathname);
+        fsSync.renameSync(owner.pathname, pathname);
         return;
     }
     catch (error) {
-        const code = error.code;
+        const code = error?.code;
         if (code === "EPERM" || code === "EEXIST") {
-            const existing = (() => {
-                try {
-                    return fsSync.lstatSync(pathname);
-                }
-                catch (lstatError) {
-                    if (lstatError.code === "ENOENT") {
-                        return null;
-                    }
-                    throw lstatError;
-                }
-            })();
-            if (existing?.isSymbolicLink()) {
-                fsSync.rmSync(pathname, { force: true });
-                fsSync.renameSync(tmpPath, pathname);
-                return;
-            }
+            owner.assertCurrent(fsSync);
             fsSync.rmSync(pathname, { force: true });
-            fsSync.renameSync(tmpPath, pathname);
+            owner.assertCurrent(fsSync);
+            fsSync.renameSync(owner.pathname, pathname);
             return;
         }
         throw error;
     }
 }
-function writeTempJsonFile(pathname, payload) {
-    const fd = fsSync.openSync(pathname, "wx", JSON_FILE_MODE);
-    try {
-        fsSync.writeFileSync(fd, payload, "utf8");
-        fsSync.fsyncSync(fd);
-        return fsSync.fstatSync(fd, { bigint: true });
-    }
-    finally {
-        fsSync.closeSync(fd);
-    }
-}
 export function tryReadJsonSync(pathname, options = {}) {
     try {
         const raw = readRegularFileSync({
@@ -174,20 +114,31 @@ export function writeJsonSync(pathname, data) {
     const tmpPath = path.format({ ...path.parse(filePath), base: `.fs-safe-${randomUUID()}.tmp` });
     const payload = `${stringifyJsonDocument(data, null, 2)}\n`;
     fsSync.mkdirSync(recursiveMkdirPath(path.dirname(filePath)), { recursive: true, mode: JSON_DIR_MODE });
+    const owner = new SyncAtomicTempOwner(tmpPath);
+    let originalFailure;
     try {
-        const tempIdentity = writeTempJsonFile(tmpPath, payload);
-        trySetSecureMode(tmpPath, tempIdentity);
-        renameJsonFileWithFallback(tmpPath, filePath);
-        trySetSecureMode(filePath, tempIdentity);
+        owner.start();
+        const temp = writeTempFileSync({
+            fsModule: fsSync, tempPath: tmpPath, content: payload, mode: JSON_FILE_MODE,
+            sync: false, onIdentity: owner.onIdentity,
+        });
+        owner.adopt(temp);
+        owner.assertCurrent(fsSync);
+        trySetSecureMode(temp.fd);
+        fsSync.fsyncSync(temp.fd);
+        renameJsonFileWithFallback(owner, filePath);
+        owner.markRenamed();
+        owner.assertPublished(fsSync, filePath);
+        trySetSecureMode(temp.fd);
         trySyncDirectory(filePath);
+        owner.assertPublished(fsSync, filePath);
+    }
+    catch (error) {
+        originalFailure = { error };
+        throw error;
     }
     finally {
-        try {
-            fsSync.rmSync(tmpPath, { force: true });
-        }
-        catch {
-            // best-effort cleanup when rename does not happen
-        }
+        owner.finish({ fsModule: fsSync, originalFailure, throwOnCleanupError: false });
     }
 }
 export class JsonFileReadError extends Error {
@@ -312,10 +263,7 @@ export async function tryReadJson(filePath, options = {}) {
 export async function readJson(filePath, options = {}) {
     let raw;
     try {
-        raw = (await readRegularFileWithRetry(filePath, {
-            maxBytes: options.maxBytes,
-            retryOpenRaceErrors: true,
-        })).toString("utf8");
+        raw = (await readRegularFileWithRetry(filePath, options.maxBytes)).toString("utf8");
     }
     catch (err) {
         throw new JsonFileReadError(filePath, "read", err);

package/dist/local-file-access.d.ts

@@ -6,4 +6,3 @@ export declare function assertNoWindowsNetworkPath(filePath: string, label?: str
 export declare function safeFileURLToPath(fileUrl: string, platform?: NodeJS.Platform): string;
 export declare function trySafeFileURLToPath(fileUrl: string, platform?: NodeJS.Platform): string | undefined;
 export declare function basenameFromMediaSource(source?: string): string | undefined;
-//# sourceMappingURL=local-file-access.d.ts.map

package/dist/local-file-access.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { fileURLToPath, URL } from "node:url";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
 import { hasWindowsPathAlias } from "./windows-path-alias.js";
+import { isWindowsSeparator, rootedWindowsDriveColonIndex, windowsNamespaceMarker, } from "./windows-path-syntax.js";
 const ENCODED_FILE_URL_SEPARATOR_RE = /%(?:2f|5c)/i;
 const FILE_URL_PREFIX_RE = /^file:\/\//i;
 export function isFileUrl(input) {
@@ -18,16 +19,8 @@ export function isWindowsNetworkPath(filePath, platform = process.platform) {
     if (platform !== "win32") {
         return false;
     }
-    const normalized = filePath.replace(/\//g, "\\");
-    const extendedDrive = normalized.length >= 7 &&
-        normalized.startsWith("\\\\?\\") &&
-        /^[a-z]$/i.test(normalized[4] ?? "") &&
-        normalized[5] === ":" &&
-        normalized[6] === "\\";
-    if (extendedDrive) {
-        return false;
-    }
-    return normalized.startsWith("\\\\");
+    return isWindowsSeparator(filePath, 0) && isWindowsSeparator(filePath, 1) &&
+        !(windowsNamespaceMarker(filePath) === "?" && rootedWindowsDriveColonIndex(filePath) === 5);
 }
 export function isWindowsDriveLetterPath(filePath, platform = process.platform) {
     return platform === "win32" && /^[A-Za-z]:[\\/]/.test(filePath);

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

@@ -14,4 +14,3 @@ export declare function openLocalFileDescriptor(filePath: string, options?: {
     readWrite?: true;
 }): Promise<OwnedLocalFile>;
 export {};
-//# sourceMappingURL=local-file-descriptor.d.ts.map

package/dist/local-roots.d.ts

@@ -23,4 +23,3 @@ export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
 };
 export declare function resolveLocalPathFromRootsSync(options: ResolveLocalPathFromRootsSyncOptions): LocalRootsPathResult | null;
 export declare function readLocalFileFromRoots(options: ReadLocalFileFromRootsOptions): Promise<LocalRootsReadResult | null>;
-//# sourceMappingURL=local-roots.d.ts.map

package/dist/local-roots.js

@@ -71,7 +71,7 @@ function resolveRootRealSync(rootDir) {
     assertNoWindowsPathAlias(realPath, "filesystem", "local root uses a Windows filesystem namespace alias");
     return realPath;
 }
-export function resolveLocalPathFromRootsSync(options) {
+function prepareLocalRootsInput(options) {
     const label = options.label ?? "local roots";
     const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
     let requestedPath;
@@ -83,6 +83,13 @@ export function resolveLocalPathFromRootsSync(options) {
             return null;
         throw error;
     }
+    return { label, rootDirs, requestedPath };
+}
+export function resolveLocalPathFromRootsSync(options) {
+    const input = prepareLocalRootsInput(options);
+    if (!input)
+        return null;
+    const { label, rootDirs, requestedPath } = input;
     for (const rootDir of rootDirs) {
         const rootReal = resolveRootRealSync(rootDir);
         if (!rootReal) {
@@ -122,17 +129,17 @@ export function resolveLocalPathFromRootsSync(options) {
 }
 export async function readLocalFileFromRoots(options) {
     const maxBytes = normalizeMaxBytes(options.maxBytes);
-    const label = options.label ?? "local roots";
-    const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
-    let requestedPath;
-    try {
-        requestedPath = resolveLocalPathInput(options.filePath, "file path");
-    }
-    catch (error) {
-        if (isWindowsPathAliasError(error))
-            return null;
-        throw error;
-    }
+    const input = prepareLocalRootsInput(options);
+    if (!input || input.rootDirs.length === 0)
+        return null;
+    const { rootDirs, requestedPath } = input;
+    const readOptions = {
+        hardlinks: options.hardlinks,
+        symlinks: options.symlinks,
+    };
+    // Omission keeps Root's default cap; one policy snapshot serves every root.
+    if (maxBytes !== undefined)
+        readOptions.maxBytes = maxBytes;
     for (const rootDir of rootDirs) {
         let scopedRoot;
         try {
@@ -141,15 +148,6 @@ export async function readLocalFileFromRoots(options) {
         catch {
             continue;
         }
-        const readOptions = {
-            hardlinks: options.hardlinks,
-            symlinks: options.symlinks,
-        };
-        // Leave maxBytes absent when the caller omits it so Root's own default
-        // cap remains in force instead of being overwritten by undefined.
-        if (maxBytes !== undefined) {
-            readOptions.maxBytes = maxBytes;
-        }
         try {
             const result = await scopedRoot.readAbsolute(requestedPath, readOptions);
             return { ...result, root: scopedRoot.rootReal };

package/dist/lock-config.d.ts

@@ -7,4 +7,3 @@ export type FsSafeLockConfig = {
 };
 export declare function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
 export declare function getFsSafeLockConfig(): FsSafeLockConfig;
-//# sourceMappingURL=lock-config.d.ts.map

package/dist/move-path-cleanup.d.ts

@@ -1,13 +1,5 @@
 import fsSync from "node:fs";
-export type EntryIdentity = {
-    ctimeMs: number;
-    dev: number;
-    ino: number;
-    mode: number;
-    mtimeMs: number;
-    nlink: number;
-    size: number;
-};
+export type EntryIdentity = Readonly<Pick<fsSync.BigIntStats, "ctimeNs" | "dev" | "ino" | "mode" | "mtimeNs" | "nlink" | "size">>;
 export type CopiedEntryManifest = (EntryIdentity & {
     children: Array<{
         name: string;
@@ -27,19 +19,12 @@ type CleanupAliasGroup = {
 export type CleanupCopiedEntryState = {
     aliasGroups: Map<string, CleanupAliasGroup>;
 };
-export declare function entryIdentity(stat: {
-    ctimeMs: number;
-    dev: number;
-    ino: number;
-    mode: number;
-    mtimeMs: number;
-    nlink: number;
-    size: number;
-}): EntryIdentity;
+export declare function entryIdentity(stat: EntryIdentity): EntryIdentity;
 export declare function sameIdentity(a: EntryIdentity, b: EntryIdentity): boolean;
 export declare function sourceChangedError(sourcePath: string): Error;
+export declare function inspectSourceEntry(sourcePath: string, observe: () => fsSync.BigIntStats): fsSync.BigIntStats;
+export declare function inspectSourceDirectory(sourcePath: string, expected?: Pick<fsSync.BigIntStats, "dev" | "ino">): fsSync.BigIntStats;
 export declare function assertSourceStillMatches(sourcePath: string, identity: EntryIdentity): Promise<void>;
 export declare function createCleanupCopiedEntryState(sourcePath: string, manifest: CopiedEntryManifest): CleanupCopiedEntryState;
-export declare function cleanupCopiedEntry(sourcePath: string, manifest: CopiedEntryManifest, state: CleanupCopiedEntryState, assertBeforeMutation: () => void): Promise<CleanupCopiedEntryResult>;
+export declare function cleanupCopiedEntry(sourcePath: string, manifest: CopiedEntryManifest, state: CleanupCopiedEntryState, assertBeforeMutation: (() => void) | undefined): Promise<CleanupCopiedEntryResult>;
 export {};
-//# sourceMappingURL=move-path-cleanup.d.ts.map

package/dist/move-path-cleanup.js

@@ -2,14 +2,15 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 export function entryIdentity(stat) {
     return {
-        ctimeMs: stat.ctimeMs,
+        ctimeNs: stat.ctimeNs,
         dev: stat.dev,
         ino: stat.ino,
         mode: stat.mode,
-        mtimeMs: stat.mtimeMs,
+        mtimeNs: stat.mtimeNs,
         nlink: stat.nlink,
         size: stat.size,
     };
@@ -20,16 +21,32 @@ export function sameIdentity(a, b) {
         a.mode === b.mode &&
         a.nlink === b.nlink &&
         a.size === b.size &&
-        a.mtimeMs === b.mtimeMs &&
-        a.ctimeMs === b.ctimeMs);
+        a.mtimeNs === b.mtimeNs &&
+        a.ctimeNs === b.ctimeNs);
 }
 export function sourceChangedError(sourcePath) {
     return Object.assign(new Error(`Source changed during move fallback: ${sourcePath}`), {
         code: "ESTALE",
     });
 }
+export function inspectSourceEntry(sourcePath, observe) {
+    return inspectFileIdentitySync(observe, undefined, process.platform, () => sourceChangedError(sourcePath));
+}
+export function inspectSourceDirectory(sourcePath, expected) {
+    try {
+        return inspectDirectoryIdentitySync(sourcePath, expected);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR" ||
+            (error instanceof FsSafeError && (error.code === "path-mismatch" || error.code === "not-file"))) {
+            throw sourceChangedError(sourcePath);
+        }
+        throw error;
+    }
+}
 export async function assertSourceStillMatches(sourcePath, identity) {
-    if (!sameIdentity(identity, entryIdentity(fsSync.lstatSync(sourcePath)))) {
+    if (!sameIdentity(identity, inspectSourceEntry(sourcePath, () => fsSync.lstatSync(sourcePath, { bigint: true })))) {
         throw sourceChangedError(sourcePath);
     }
 }
@@ -43,7 +60,7 @@ function collectAliasCandidates(sourcePath, manifest, candidates) {
         }
         return;
     }
-    if (manifest.nlink <= 1) {
+    if (manifest.nlink <= 1n) {
         return;
     }
     const key = identityKey(manifest);
@@ -76,15 +93,26 @@ function sameOwnedUnlinkTransition(before, after) {
         before.ino === after.ino &&
         before.mode === after.mode &&
         before.size === after.size &&
-        before.mtimeMs === after.mtimeMs &&
-        before.nlink > 0 &&
-        after.nlink === before.nlink - 1 &&
-        after.ctimeMs >= before.ctimeMs);
+        before.mtimeNs === after.mtimeNs &&
+        before.nlink > 0n &&
+        after.nlink === before.nlink - 1n &&
+        after.ctimeNs >= before.ctimeNs);
 }
 function poisonAliasGroup(group) {
     group.stale = true;
     return "stale";
 }
+function inspectCleanupLeaf(sourcePath, expected) {
+    let mismatch;
+    try {
+        return inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }), expected, process.platform, () => mismatch = sourceChangedError(sourcePath));
+    }
+    catch (error) {
+        if (mismatch !== undefined && error === mismatch)
+            return undefined;
+        throw error;
+    }
+}
 async function observeOwnedAliasUnlink(sourcePath, group) {
     group.remainingPaths.delete(sourcePath);
     const remainingPath = group.remainingPaths.values().next().value;
@@ -93,7 +121,7 @@ async function observeOwnedAliasUnlink(sourcePath, group) {
     }
     let observed;
     try {
-        observed = fsSync.lstatSync(remainingPath);
+        observed = inspectCleanupLeaf(remainingPath, group.expected);
     }
     catch (error) {
         if (error?.code === "ENOENT") {
@@ -101,11 +129,10 @@ async function observeOwnedAliasUnlink(sourcePath, group) {
         }
         throw error;
     }
-    const observedIdentity = entryIdentity(observed);
-    if (!sameOwnedUnlinkTransition(group.expected, observedIdentity)) {
+    if (!observed || !sameOwnedUnlinkTransition(group.expected, observed)) {
         return poisonAliasGroup(group);
     }
-    group.expected = observedIdentity;
+    group.expected = entryIdentity(observed);
     return "removed";
 }
 function mergeCleanupResults(a, b) {
@@ -130,12 +157,16 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBefo
         // A same-inode directory can gain unrelated children after commit. Still
         // clean manifest children so the fallback does not duplicate copied files.
         let result = "removed";
+        const assertBeforeChildMutation = assertBeforeMutation ? () => {
+            assertBeforeMutation();
+            inspectSourceDirectory(sourcePath, manifest.directoryIdentity);
+        } : undefined;
         for (const child of manifest.children) {
-            result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state, assertBeforeMutation));
+            result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state, assertBeforeChildMutation));
         }
         // Child cleanup and the caller's authority check can replace the directory.
         // Keep the final exact observation after both, immediately before removal.
-        assertBeforeMutation();
+        assertBeforeMutation?.();
         try {
             currentStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }), manifest.directoryIdentity);
         }
@@ -166,9 +197,10 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBefo
     if (aliasGroup?.stale) {
         return "stale";
     }
+    const expected = aliasGroup?.expected ?? manifest;
     let currentStat;
     try {
-        currentStat = fsSync.lstatSync(sourcePath);
+        currentStat = inspectCleanupLeaf(sourcePath, expected);
     }
     catch (error) {
         if (error?.code === "ENOENT") {
@@ -176,11 +208,15 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBefo
         }
         throw error;
     }
-    const expected = aliasGroup?.expected ?? manifest;
-    if (!sameIdentity(expected, entryIdentity(currentStat))) {
-        return aliasGroup ? poisonAliasGroup(aliasGroup) : "stale";
+    for (let observation = 0;; observation++) {
+        if (!currentStat || !sameIdentity(expected, currentStat)) {
+            return aliasGroup ? poisonAliasGroup(aliasGroup) : "stale";
+        }
+        if (observation || !assertBeforeMutation)
+            break;
+        assertBeforeMutation();
+        currentStat = inspectCleanupLeaf(sourcePath, expected);
     }
-    assertBeforeMutation();
     await fs.unlink(sourcePath);
     return aliasGroup
         ? await observeOwnedAliasUnlink(sourcePath, aliasGroup)

package/dist/move-path-stage.d.ts

@@ -5,4 +5,3 @@ export declare function createMoveStageOwner(staged: string): Promise<{
     published(): void;
     cleanup(): Promise<void>;
 }>;
-//# sourceMappingURL=move-path-stage.d.ts.map

package/dist/move-path.d.ts

@@ -18,4 +18,3 @@ type MoveCopyFallbackReason = "cross-device" | "windows-rename-denied";
 export declare function moveCopyFallbackReasonForRenameError(error: unknown, platform?: NodeJS.Platform): MoveCopyFallbackReason | undefined;
 export declare function movePathWithCopyFallback(options: MovePathWithCopyFallbackOptions): Promise<void>;
 export {};
-//# sourceMappingURL=move-path.d.ts.map