@openclaw/fs-safe 0.1.1 → 0.2.0

package/dist/json-durable-queue.d.ts

@@ -0,0 +1,45 @@
+export type JsonDurableQueueEntryPaths = {
+    jsonPath: string;
+    deliveredPath: string;
+};
+export type JsonDurableQueueReadResult<T> = {
+    entry: T;
+    migrated?: boolean;
+};
+export type JsonDurableQueueLoadOptions<T> = {
+    queueDir: string;
+    tempPrefix: string;
+    read?: (entry: T, filePath: string) => Promise<JsonDurableQueueReadResult<T>>;
+    cleanupTmpMaxAgeMs?: number;
+    maxBytes?: number;
+};
+export declare const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES: number;
+export declare function unlinkBestEffort(filePath: string): Promise<void>;
+export declare function jsonDurableQueueEntryExists(filePath: string): Promise<boolean>;
+export declare function resolveJsonDurableQueueEntryPaths(queueDir: string, id: string): JsonDurableQueueEntryPaths;
+export declare function ensureJsonDurableQueueDirs(params: {
+    queueDir: string;
+    failedDir: string;
+}): Promise<void>;
+export declare function writeJsonDurableQueueEntry(params: {
+    filePath: string;
+    entry: unknown;
+    tempPrefix: string;
+}): Promise<void>;
+export declare function readJsonDurableQueueEntry<T>(filePath: string, options?: {
+    maxBytes?: number;
+}): Promise<T>;
+export declare function ackJsonDurableQueueEntry(paths: JsonDurableQueueEntryPaths): Promise<void>;
+export declare function loadJsonDurableQueueEntry<T>(params: {
+    paths: JsonDurableQueueEntryPaths;
+    tempPrefix: string;
+    read?: (entry: T, filePath: string) => Promise<JsonDurableQueueReadResult<T>>;
+    maxBytes?: number;
+}): Promise<T | null>;
+export declare function loadPendingJsonDurableQueueEntries<T>(options: JsonDurableQueueLoadOptions<T>): Promise<T[]>;
+export declare function moveJsonDurableQueueEntryToFailed(params: {
+    queueDir: string;
+    failedDir: string;
+    id: string;
+}): Promise<void>;
+//# sourceMappingURL=json-durable-queue.d.ts.map

package/dist/json-durable-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAY3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAM5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhB;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAiDD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB"}

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"}