@openclaw/fs-safe 0.1.2 → 0.2.1

package/dist/json-durable-queue.js

@@ -0,0 +1,200 @@
+import fs from "node:fs";
+import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
+import { replaceFileAtomic } from "./replace-file.js";
+import { assertSafePathSegment } from "./safe-path-segment.js";
+export const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES = 16 * 1024 * 1024;
+function getErrnoCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+function assertSafeQueueEntryId(id) {
+    assertSafePathSegment(id, { label: "queue entry id" });
+}
+export async function unlinkBestEffort(filePath) {
+    await fs.promises.unlink(filePath).catch(() => undefined);
+}
+export async function jsonDurableQueueEntryExists(filePath) {
+    try {
+        const stat = await fs.promises.lstat(filePath);
+        return stat.isFile();
+    }
+    catch (error) {
+        if (getErrnoCode(error) === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function unlinkStaleTmpBestEffort(filePath, now, maxAgeMs) {
+    try {
+        const stat = await fs.promises.stat(filePath);
+        if (stat.isFile() && now - stat.mtimeMs >= maxAgeMs) {
+            await unlinkBestEffort(filePath);
+        }
+    }
+    catch (error) {
+        if (getErrnoCode(error) !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+export function resolveJsonDurableQueueEntryPaths(queueDir, id) {
+    assertSafeQueueEntryId(id);
+    return {
+        jsonPath: path.join(queueDir, `${id}.json`),
+        deliveredPath: path.join(queueDir, `${id}.delivered`),
+    };
+}
+export async function ensureJsonDurableQueueDirs(params) {
+    await fs.promises.mkdir(params.queueDir, { recursive: true, mode: 0o700 });
+    await fs.promises.mkdir(params.failedDir, { recursive: true, mode: 0o700 });
+}
+export async function writeJsonDurableQueueEntry(params) {
+    await replaceFileAtomic({
+        filePath: params.filePath,
+        content: JSON.stringify(params.entry, null, 2),
+        mode: 0o600,
+        tempPrefix: params.tempPrefix,
+    });
+}
+async function readBoundedUtf8File(params) {
+    const initialStat = await fs.promises.lstat(params.filePath);
+    if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
+        throw new Error("queue entry is not a regular file");
+    }
+    if (initialStat.size > params.maxBytes) {
+        throw new Error(`queue entry exceeds ${params.maxBytes} bytes`);
+    }
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" && process.platform !== "win32"
+        ? fs.constants.O_NOFOLLOW
+        : 0;
+    const handle = await fs.promises.open(params.filePath, fs.constants.O_RDONLY | noFollow);
+    try {
+        const openedStat = await handle.stat();
+        const pathStat = await fs.promises.lstat(params.filePath);
+        if (!openedStat.isFile() ||
+            pathStat.isSymbolicLink() ||
+            !pathStat.isFile() ||
+            !sameFileIdentity(initialStat, openedStat) ||
+            !sameFileIdentity(pathStat, openedStat)) {
+            throw new Error("queue entry changed during read");
+        }
+        const chunks = [];
+        const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, params.maxBytes + 1));
+        let total = 0;
+        while (true) {
+            const { bytesRead } = await handle.read(scratch, 0, scratch.length, null);
+            if (bytesRead === 0) {
+                return Buffer.concat(chunks, total).toString("utf8");
+            }
+            total += bytesRead;
+            if (total > params.maxBytes) {
+                throw new Error(`queue entry exceeds ${params.maxBytes} bytes`);
+            }
+            chunks.push(Buffer.from(scratch.subarray(0, bytesRead)));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readJsonDurableQueueEntry(filePath, options = {}) {
+    return JSON.parse(await readBoundedUtf8File({
+        filePath,
+        maxBytes: options.maxBytes ?? DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES,
+    }));
+}
+export async function ackJsonDurableQueueEntry(paths) {
+    try {
+        await fs.promises.rename(paths.jsonPath, paths.deliveredPath);
+    }
+    catch (error) {
+        if (getErrnoCode(error) === "ENOENT") {
+            await unlinkBestEffort(paths.deliveredPath);
+            return;
+        }
+        throw error;
+    }
+    await unlinkBestEffort(paths.deliveredPath);
+}
+export async function loadJsonDurableQueueEntry(params) {
+    try {
+        const stat = await fs.promises.lstat(params.paths.jsonPath);
+        if (!stat.isFile()) {
+            return null;
+        }
+        const raw = await readJsonDurableQueueEntry(params.paths.jsonPath, {
+            maxBytes: params.maxBytes,
+        });
+        const result = params.read ? await params.read(raw, params.paths.jsonPath) : { entry: raw };
+        if (result.migrated) {
+            await writeJsonDurableQueueEntry({
+                filePath: params.paths.jsonPath,
+                entry: result.entry,
+                tempPrefix: params.tempPrefix,
+            });
+        }
+        return result.entry;
+    }
+    catch (error) {
+        if (getErrnoCode(error) === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function loadPendingJsonDurableQueueEntries(options) {
+    let files;
+    try {
+        files = await fs.promises.readdir(options.queueDir);
+    }
+    catch (error) {
+        if (getErrnoCode(error) === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const now = Date.now();
+    for (const file of files) {
+        if (file.endsWith(".delivered")) {
+            await unlinkBestEffort(path.join(options.queueDir, file));
+        }
+        else if (options.cleanupTmpMaxAgeMs !== undefined && file.endsWith(".tmp")) {
+            await unlinkStaleTmpBestEffort(path.join(options.queueDir, file), now, options.cleanupTmpMaxAgeMs);
+        }
+    }
+    const entries = [];
+    for (const file of files) {
+        if (!file.endsWith(".json")) {
+            continue;
+        }
+        const filePath = path.join(options.queueDir, file);
+        try {
+            const stat = await fs.promises.lstat(filePath);
+            if (!stat.isFile()) {
+                continue;
+            }
+            const raw = await readJsonDurableQueueEntry(filePath, { maxBytes: options.maxBytes });
+            const result = options.read ? await options.read(raw, filePath) : { entry: raw };
+            if (result.migrated) {
+                await writeJsonDurableQueueEntry({
+                    filePath,
+                    entry: result.entry,
+                    tempPrefix: options.tempPrefix,
+                });
+            }
+            entries.push(result.entry);
+        }
+        catch {
+            continue;
+        }
+    }
+    return entries;
+}
+export async function moveJsonDurableQueueEntryToFailed(params) {
+    assertSafeQueueEntryId(params.id);
+    await fs.promises.mkdir(params.failedDir, { recursive: true, mode: 0o700 });
+    await fs.promises.rename(path.join(params.queueDir, `${params.id}.json`), path.join(params.failedDir, `${params.id}.json`));
+}

package/dist/json.d.ts

@@ -1,3 +1,6 @@
+import fsSync from "node:fs";
+import { type RootFileOpenFailure } from "./root-file.js";
+import { type WriteTextAtomicOptions } from "./text-atomic.js";
 export declare function tryReadJsonSync<T = unknown>(pathname: string): T | null;
 export declare function writeJsonSync(pathname: string, data: unknown): void;
 export declare class JsonFileReadError extends Error {
@@ -5,13 +8,40 @@ export declare class JsonFileReadError extends Error {
     readonly reason: "read" | "parse";
     constructor(filePath: string, reason: "read" | "parse", cause: unknown);
 }
+export type RootStructuredFileReadResult<T> = {
+    ok: true;
+    value: T;
+    stat: fsSync.Stats;
+    path: string;
+    rootRealPath: string;
+} | {
+    ok: false;
+    reason: "open";
+    failure: RootFileOpenFailure;
+} | {
+    ok: false;
+    reason: "invalid" | "parse";
+    error: string;
+};
+export type ReadRootStructuredFileSyncOptions<T> = {
+    rootDir: string;
+    rootRealPath?: string;
+    relativePath: string;
+    boundaryLabel: string;
+    rejectHardlinks?: boolean;
+    maxBytes?: number;
+    parse: (raw: string) => unknown;
+    validate?: (value: unknown) => value is T;
+    invalidMessage?: string | ((relativePath: string) => string);
+};
+export type ReadRootJsonSyncOptions = Omit<ReadRootStructuredFileSyncOptions<unknown>, "parse" | "validate" | "invalidMessage">;
+export declare function readRootStructuredFileSync<T>(options: ReadRootStructuredFileSyncOptions<T>): RootStructuredFileReadResult<T>;
+export declare function readRootJsonSync<T = unknown>(options: ReadRootJsonSyncOptions): RootStructuredFileReadResult<T>;
+export declare function readRootJsonObjectSync(options: ReadRootJsonSyncOptions): RootStructuredFileReadResult<Record<string, unknown>>;
 export declare function tryReadJson<T>(filePath: string): Promise<T | null>;
 export declare function readJson<T>(filePath: string): Promise<T>;
 export declare function readJsonIfExists<T>(filePath: string): Promise<T | null>;
 export declare function readJsonSync<T = unknown>(filePath: string): T;
-export declare function writeJson(filePath: string, value: unknown, options?: {
-    mode?: number;
-    trailingNewline?: boolean;
-    dirMode?: number;
-}): Promise<void>;
+export type WriteJsonOptions = Pick<WriteTextAtomicOptions, "dirMode" | "durable" | "mode" | "trailingNewline">;
+export declare function writeJson(filePath: string, value: unknown, options?: WriteJsonOptions): Promise<void>;
 //# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AA8FA,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOvE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,QAmB5D;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO;CAMvE;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAOxE;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAY9D;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAe7E;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAY7D;AAED,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,iBAQzE"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"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"}

package/dist/json.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import fsSync from "node:fs";
 import path from "node:path";
 import { readRegularFile, readRegularFileSync } from "./regular-file.js";
+import { openRootFileSync } from "./root-file.js";
 import { writeTextAtomic } from "./text-atomic.js";
 const JSON_FILE_MODE = 0o600;
 const JSON_DIR_MODE = 0o700;
@@ -74,8 +75,8 @@ function renameJsonFileWithFallback(tmpPath, pathname) {
                 fsSync.renameSync(tmpPath, pathname);
                 return;
             }
-            fsSync.copyFileSync(tmpPath, pathname);
-            fsSync.rmSync(tmpPath, { force: true });
+            fsSync.rmSync(pathname, { force: true });
+            fsSync.renameSync(tmpPath, pathname);
             return;
         }
         throw error;
@@ -131,6 +132,71 @@ export class JsonFileReadError extends Error {
         this.reason = reason;
     }
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveInvalidMessage(invalidMessage, relativePath) {
+    if (typeof invalidMessage === "function") {
+        return invalidMessage(relativePath);
+    }
+    return invalidMessage ?? `${relativePath} has an unexpected shape`;
+}
+export function readRootStructuredFileSync(options) {
+    const absolutePath = path.resolve(options.rootDir, options.relativePath);
+    const opened = openRootFileSync({
+        absolutePath,
+        rootPath: options.rootDir,
+        ...(options.rootRealPath !== undefined ? { rootRealPath: options.rootRealPath } : {}),
+        boundaryLabel: options.boundaryLabel,
+        rejectHardlinks: options.rejectHardlinks,
+        maxBytes: options.maxBytes,
+        allowedType: "file",
+    });
+    if (!opened.ok) {
+        return { ok: false, reason: "open", failure: opened };
+    }
+    try {
+        const parsed = options.parse(fsSync.readFileSync(opened.fd, "utf8"));
+        if (options.validate && !options.validate(parsed)) {
+            return {
+                ok: false,
+                reason: "invalid",
+                error: resolveInvalidMessage(options.invalidMessage, options.relativePath),
+            };
+        }
+        return {
+            ok: true,
+            value: parsed,
+            stat: opened.stat,
+            path: opened.path,
+            rootRealPath: opened.rootRealPath,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "parse",
+            error: `failed to parse ${options.relativePath}: ${String(error)}`,
+        };
+    }
+    finally {
+        fsSync.closeSync(opened.fd);
+    }
+}
+export function readRootJsonSync(options) {
+    return readRootStructuredFileSync({
+        ...options,
+        parse: (raw) => JSON.parse(raw),
+    });
+}
+export function readRootJsonObjectSync(options) {
+    return readRootStructuredFileSync({
+        ...options,
+        parse: (raw) => JSON.parse(raw),
+        validate: isRecord,
+        invalidMessage: (relativePath) => `${relativePath} must contain a JSON object`,
+    });
+}
 export async function tryReadJson(filePath) {
     try {
         const raw = (await readRegularFile({ filePath })).buffer.toString("utf8");
@@ -194,5 +260,6 @@ export async function writeJson(filePath, value, options) {
         mode: options?.mode,
         dirMode: options?.dirMode,
         trailingNewline: options?.trailingNewline,
+        durable: options?.durable,
     });
 }

package/dist/local-roots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAMA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AA0FF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CA6B7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAgCtC"}
+{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAMA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAmGF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CA6B7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAqCtC"}

package/dist/local-roots.js

@@ -52,8 +52,10 @@ function resolveRootRealSync(rootDir) {
     }
 }
 function resolveCandidateCanonicalSync(filePath) {
+    let sawExistingLeaf = false;
     try {
         const stat = fsSync.lstatSync(filePath);
+        sawExistingLeaf = true;
         return {
             exists: true,
             canonicalPath: fsSync.realpathSync(filePath),
@@ -65,6 +67,11 @@ function resolveCandidateCanonicalSync(filePath) {
             throw err;
         }
     }
+    if (sawExistingLeaf) {
+        // lstat succeeded but realpath failed: this is an existing dangling
+        // symlink, not a missing path callers may safely create through.
+        throw new FsSafeError("symlink", "local roots candidate is a dangling symlink");
+    }
     let cursor = filePath;
     const missingSegments = [];
     while (true) {
@@ -84,6 +91,8 @@ function resolveCandidateCanonicalSync(filePath) {
         }
         catch (err) {
             if (err.code !== "ENOENT") {
+                // Existing ancestors that cannot be canonicalized are symlink/error
+                // terrain; do not reconstruct a trusted missing path through them.
                 throw err;
             }
         }
@@ -134,12 +143,17 @@ export async function readLocalFileFromRoots(options) {
             continue;
         }
         try {
-            const result = await scopedRoot.read(relativePath, {
+            const readOptions = {
                 hardlinks: options.hardlinks,
-                maxBytes: options.maxBytes,
                 nonBlockingRead: options.nonBlockingRead,
                 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 (options.maxBytes !== undefined) {
+                readOptions.maxBytes = options.maxBytes;
+            }
+            const result = await scopedRoot.read(relativePath, readOptions);
             return { ...result, root: scopedRoot.rootReal };
         }
         catch {

package/dist/lock-config.d.ts

@@ -0,0 +1,10 @@
+import type { SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export type FsSafeLockConfig = {
+    staleRecovery: SidecarLockStaleRecovery;
+    staleMs?: number;
+    timeoutMs?: number;
+    retry?: SidecarLockRetryOptions;
+};
+export declare function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
+export declare function getFsSafeLockConfig(): FsSafeLockConfig;
+//# sourceMappingURL=lock-config.d.ts.map

package/dist/lock-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-config.d.ts","sourceRoot":"","sources":["../src/lock-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE3F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,EAAE,wBAAwB,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAQF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAI5E;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD"}

package/dist/lock-config.js

@@ -0,0 +1,12 @@
+const DEFAULT_LOCK_CONFIG = {
+    staleRecovery: "fail-closed",
+};
+let lockConfig = { ...DEFAULT_LOCK_CONFIG };
+export function configureFsSafeLocks(config) {
+    // Process defaults only fill lock options after a caller explicitly enables
+    // locking for a resource; this must never turn sidecar locks on globally.
+    lockConfig = { ...lockConfig, ...config };
+}
+export function getFsSafeLockConfig() {
+    return { ...lockConfig, retry: lockConfig.retry ? { ...lockConfig.retry } : undefined };
+}

package/dist/move-path.d.ts

@@ -1,5 +1,6 @@
 export type MovePathWithCopyFallbackOptions = {
     from: string;
+    sourceHardlinks?: "allow" | "reject";
     to: string;
 };
 export declare function movePathWithCopyFallback(options: MovePathWithCopyFallbackOptions): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAef"}
+{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAqPF,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/move-path.js

@@ -1,7 +1,186 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
+import path from "node:path";
+import { guardedRename } from "./guarded-mutation.js";
+function entryIdentity(stat) {
+    return {
+        ctimeMs: stat.ctimeMs,
+        dev: stat.dev,
+        ino: stat.ino,
+        mode: stat.mode,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+    };
+}
+function sameIdentity(a, b) {
+    return (a.dev === b.dev &&
+        a.ino === b.ino &&
+        a.mode === b.mode &&
+        a.size === b.size &&
+        a.mtimeMs === b.mtimeMs &&
+        a.ctimeMs === b.ctimeMs);
+}
+function sameDirectoryNode(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+function modeBits(mode) {
+    return mode & 0o777;
+}
+function sourceChangedError(sourcePath) {
+    return Object.assign(new Error(`Source changed during move fallback: ${sourcePath}`), {
+        code: "ESTALE",
+    });
+}
+async function assertSourceStillMatches(sourcePath, identity) {
+    if (!sameIdentity(identity, entryIdentity(await fs.lstat(sourcePath)))) {
+        throw sourceChangedError(sourcePath);
+    }
+}
+function regularReadFlags() {
+    return (fsConstants.O_RDONLY |
+        (typeof fsConstants.O_NOFOLLOW === "number" && process.platform !== "win32"
+            ? fsConstants.O_NOFOLLOW
+            : 0));
+}
+async function writeAll(handle, buffer, bytesRead) {
+    let offset = 0;
+    while (offset < bytesRead) {
+        const { bytesWritten } = await handle.write(buffer, offset, bytesRead - offset);
+        offset += bytesWritten;
+    }
+}
+async function copyRegularFilePinned(params) {
+    let destinationCreated = false;
+    let sourceHandle;
+    try {
+        sourceHandle = await fs.open(params.from, regularReadFlags());
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ELOOP" || code === "ENOENT" || code === "ENOTDIR") {
+            throw sourceChangedError(params.from);
+        }
+        throw error;
+    }
+    try {
+        const openedStat = await sourceHandle.stat();
+        if (!openedStat.isFile() || !sameIdentity(params.identity, entryIdentity(openedStat))) {
+            throw sourceChangedError(params.from);
+        }
+        const destinationHandle = await fs.open(params.to, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, modeBits(params.mode) || 0o666);
+        destinationCreated = true;
+        try {
+            const scratch = Buffer.allocUnsafe(64 * 1024);
+            while (true) {
+                const { bytesRead } = await sourceHandle.read(scratch, 0, scratch.length, null);
+                if (bytesRead === 0) {
+                    break;
+                }
+                await writeAll(destinationHandle, scratch, bytesRead);
+            }
+        }
+        finally {
+            await destinationHandle.close();
+        }
+        // Re-check the opened handle before the staged tree can be committed. If
+        // the source changed while we copied, the caller should retry the move.
+        if (!sameIdentity(params.identity, entryIdentity(await sourceHandle.stat()))) {
+            throw sourceChangedError(params.from);
+        }
+        await fs.chmod(params.to, modeBits(params.mode)).catch(() => undefined);
+    }
+    catch (error) {
+        if (destinationCreated) {
+            await fs.rm(params.to, { force: true }).catch(() => undefined);
+        }
+        throw error;
+    }
+    finally {
+        await sourceHandle.close();
+    }
+}
+async function copyEntryWithManifest(from, to, options) {
+    const sourceStat = await fs.lstat(from);
+    const identity = entryIdentity(sourceStat);
+    if (sourceStat.isSymbolicLink()) {
+        await fs.symlink(await fs.readlink(from), to);
+        // readlink() is path-based; verify the symlink we copied is still the one
+        // we inspected before letting the staged destination become visible.
+        await assertSourceStillMatches(from, identity);
+        return { ...identity, kind: "leaf" };
+    }
+    if (sourceStat.isDirectory()) {
+        await fs.mkdir(to, { mode: modeBits(sourceStat.mode) || 0o755 });
+        const children = [];
+        for (const child of await fs.readdir(from)) {
+            children.push({
+                name: child,
+                manifest: await copyEntryWithManifest(path.join(from, child), path.join(to, child), options),
+            });
+        }
+        // Directory traversal is path-based in Node. Treat a changed parent as a
+        // stale move before committing so swapped-in outside trees are not imported.
+        await assertSourceStillMatches(from, identity);
+        // mkdir() honors process umask. Restore the source mode before commit so
+        // EXDEV fallback preserves directory permissions like fs.cp did.
+        await fs.chmod(to, modeBits(sourceStat.mode));
+        return { ...identity, children, kind: "directory" };
+    }
+    if (!sourceStat.isFile()) {
+        throw new Error(`Refusing to move non-file path with copy fallback: ${from}`);
+    }
+    if (options.sourceHardlinks === "reject" && sourceStat.nlink > 1) {
+        throw new Error(`Refusing to move hardlinked file with copy fallback: ${from}`);
+    }
+    await copyRegularFilePinned({ from, identity, mode: sourceStat.mode, to });
+    return { ...identity, kind: "leaf" };
+}
+function mergeCleanupResults(a, b) {
+    return a === "stale" || b === "stale" ? "stale" : "removed";
+}
+async function cleanupCopiedEntry(sourcePath, manifest) {
+    let currentStat;
+    try {
+        currentStat = await fs.lstat(sourcePath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            return "removed";
+        }
+        throw error;
+    }
+    if (manifest.kind === "directory") {
+        if (!currentStat.isDirectory() || !sameDirectoryNode(manifest, entryIdentity(currentStat))) {
+            return "stale";
+        }
+        // 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";
+        for (const child of manifest.children) {
+            result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest));
+        }
+        try {
+            await fs.rmdir(sourcePath);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === "ENOTEMPTY" || code === "EEXIST") {
+                return "stale";
+            }
+            throw error;
+        }
+        return result;
+    }
+    if (!sameIdentity(manifest, entryIdentity(currentStat))) {
+        return "stale";
+    }
+    await fs.unlink(sourcePath);
+    return "removed";
+}
 export async function movePathWithCopyFallback(options) {
     try {
-        await fs.rename(options.from, options.to);
+        await guardedRename({ from: options.from, to: options.to });
         return;
     }
     catch (error) {
@@ -9,10 +188,19 @@ export async function movePathWithCopyFallback(options) {
             throw error;
         }
     }
-    await fs.cp(options.from, options.to, {
-        recursive: true,
-        force: true,
-        dereference: false,
-    });
-    await fs.rm(options.from, { recursive: true, force: true });
+    const targetDir = path.dirname(path.resolve(options.to));
+    const staged = path.join(targetDir, `.fs-safe-move-${process.pid}-${randomUUID()}.tmp`);
+    try {
+        const manifest = await copyEntryWithManifest(options.from, staged, {
+            sourceHardlinks: options.sourceHardlinks ?? "allow",
+        });
+        await guardedRename({ from: staged, to: options.to });
+        const cleanupResult = await cleanupCopiedEntry(options.from, manifest);
+        if (cleanupResult === "stale") {
+            throw sourceChangedError(options.from);
+        }
+    }
+    finally {
+        await fs.rm(staged, { recursive: true, force: true }).catch(() => undefined);
+    }
 }