@openclaw/fs-safe 0.1.2 → 0.2.0

package/dist/file-store.js

@@ -2,12 +2,18 @@ import { randomUUID } from "node:crypto";
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { createSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { pruneExpiredStoreEntries, } from "./file-store-prune.js";
 import { assertSyncDirectoryGuard, ensureParentInRoot, ensureParentSync, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { readFileStoreCopySource } from "./file-store-source.js";
 import { createJsonStore } from "./json-document-store.js";
 import { isPathInside, resolveSafeRelativePath } from "./path.js";
 import { root } from "./root.js";
+import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
+import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
 import { writeSecretFileAtomic } from "./secret-file.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 function assertRelativePath(relativePath) {
     const raw = relativePath.trim();
     if (!raw) {
@@ -29,11 +35,38 @@ function assertMaxBytes(size, maxBytes) {
     }
 }
 function isNotFound(error) {
+    if (!error) {
+        return false;
+    }
     return error instanceof FsSafeError
         ? error.code === "not-found"
         : error.code === "ENOENT" ||
             error.code === "ENOTDIR";
 }
+function handleSyncStoreReadOpenFailure(opened) {
+    return matchRootFileOpenFailure(opened, {
+        path: (failure) => {
+            if (isNotFound(failure.error)) {
+                return null;
+            }
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        validation: (failure) => {
+            // Validation failures mean the path existed but violated store policy
+            // (directory, hardlink, symlink race). Do not report them as missing.
+            throw new FsSafeError("path-mismatch", "store target failed read validation", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        fallback: (failure) => {
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+    });
+}
 async function copyIntoRoot(params) {
     const relativePath = assertRelativePath(params.relativePath);
     const destination = resolveStorePath(params.rootDir, relativePath);
@@ -101,7 +134,7 @@ export function fileStore(options) {
         writeStream: async (relativePath, stream, writeOptions) => {
             const safeRelativePath = assertRelativePath(relativePath);
             const destination = resolveStorePath(rootDir, safeRelativePath);
-            const limit = writeOptions?.maxBytes ?? maxBytes;
+            const limit = writeOptions?.maxBytes ?? maxBytes ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
             if (privateMode) {
                 const chunks = [];
                 let total = 0;
@@ -143,12 +176,11 @@ export function fileStore(options) {
         },
         copyIn: async (relativePath, sourcePath, writeOptions) => privateMode
             ? await (async () => {
-                const sourceStat = await fs.lstat(sourcePath);
-                if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-                    throw new FsSafeError("not-file", "source path is not a file");
-                }
-                assertMaxBytes(sourceStat.size, writeOptions?.maxBytes ?? maxBytes);
-                return await write(relativePath, await fs.readFile(sourcePath), writeOptions);
+                const buffer = await readFileStoreCopySource({
+                    sourcePath,
+                    maxBytes: writeOptions?.maxBytes ?? maxBytes ?? DEFAULT_ROOT_MAX_BYTES,
+                });
+                return await write(relativePath, buffer, writeOptions);
             })()
             : await copyIntoRoot({
                 rootDir,
@@ -226,37 +258,7 @@ export function fileStore(options) {
             }, jsonOptions);
         },
         pruneExpired: async (pruneOptions) => {
-            const now = Date.now();
-            const recursive = pruneOptions.recursive ?? false;
-            const maxDepth = pruneOptions.maxDepth;
-            const pruneEmptyDirs = (recursive || maxDepth !== undefined) && (pruneOptions.pruneEmptyDirs ?? false);
-            async function pruneDir(dir, depth) {
-                const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
-                for (const entry of entries) {
-                    const fullPath = path.join(dir, entry.name);
-                    const stat = await fs.lstat(fullPath).catch(() => null);
-                    if (!stat || stat.isSymbolicLink()) {
-                        continue;
-                    }
-                    if (stat.isDirectory()) {
-                        const shouldDescend = maxDepth !== undefined ? depth < maxDepth : recursive;
-                        if (shouldDescend && (await pruneDir(fullPath, depth + 1))) {
-                            await fs.rmdir(fullPath).catch(() => undefined);
-                        }
-                        continue;
-                    }
-                    if (stat.isFile() && now - stat.mtimeMs > pruneOptions.ttlMs) {
-                        await fs.rm(fullPath, { force: true }).catch(() => undefined);
-                    }
-                }
-                if (!pruneEmptyDirs) {
-                    return false;
-                }
-                const remaining = await fs.readdir(dir).catch(() => null);
-                return remaining !== null && remaining.length === 0;
-            }
-            await fs.mkdir(rootDir, { recursive: true, mode: dirMode });
-            await pruneDir(rootDir, 0);
+            await pruneExpiredStoreEntries({ rootDir, dirMode, options: pruneOptions });
         },
     };
 }
@@ -302,13 +304,16 @@ function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
             // Best-effort on platforms that do not enforce POSIX modes.
         }
     }
+    const guard = createSyncDirectoryGuard(target);
+    assertSyncDirectoryGuard(guard);
+    return guard;
 }
 function writeFileSyncAtomic(params) {
     const filePath = path.resolve(params.filePath);
     assertStoreFilePath(params.rootDir, filePath);
     let parentGuard;
     if (params.privateMode) {
-        ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
+        parentGuard = ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
         try {
             const stat = syncFs.lstatSync(filePath);
             if (stat.isSymbolicLink() || !stat.isFile()) {
@@ -331,6 +336,7 @@ function writeFileSyncAtomic(params) {
     const tempPath = path.join(parentGuard?.dir ?? path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
     let tempExists = false;
     try {
+        getFsSafeTestHooks()?.beforeFileStoreSyncPrivateWrite?.(filePath);
         if (parentGuard) {
             assertSyncDirectoryGuard(parentGuard);
         }
@@ -393,22 +399,23 @@ export function fileStoreSync(options) {
         path: (relativePath) => resolveStorePath(rootDir, relativePath),
         readTextIfExists: (relativePath, readOptions) => {
             const targetPath = resolveStorePath(rootDir, relativePath);
+            const opened = openRootFileSync({
+                absolutePath: targetPath,
+                rootPath: rootDir,
+                boundaryLabel: "store root",
+                rejectHardlinks: privateMode,
+            });
+            if (!opened.ok) {
+                return handleSyncStoreReadOpenFailure(opened);
+            }
             try {
-                const stat = syncFs.lstatSync(targetPath);
-                if (stat.isSymbolicLink() || !stat.isFile()) {
-                    throw new FsSafeError("not-file", "store target is not a file");
-                }
-                assertMaxBytes(stat.size, readOptions?.maxBytes ?? maxBytes);
-                if (privateMode && stat.nlink > 1) {
-                    throw new FsSafeError("hardlink", "private store target must not be hardlinked");
-                }
-                return syncFs.readFileSync(targetPath, "utf8");
+                assertMaxBytes(opened.stat.size, readOptions?.maxBytes ?? maxBytes);
+                const raw = syncFs.readFileSync(opened.fd, "utf8");
+                assertMaxBytes(Buffer.byteLength(raw, "utf8"), readOptions?.maxBytes ?? maxBytes);
+                return raw;
             }
-            catch (error) {
-                if (isNotFound(error)) {
-                    return null;
-                }
-                throw error;
+            finally {
+                syncFs.closeSync(opened.fd);
             }
         },
         readJsonIfExists: (relativePath, readOptions) => {

package/dist/guarded-mkdir.d.ts

@@ -0,0 +1,6 @@
+export declare function mkdirPathComponentsWithGuards(params: {
+    rootReal: string;
+    targetPath: string;
+    beforeComponent?: (componentPath: string) => Promise<void> | void;
+}): Promise<void>;
+//# sourceMappingURL=guarded-mkdir.d.ts.map

package/dist/guarded-mkdir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAaA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiChB"}

package/dist/guarded-mkdir.js

@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+function isSameOrChildPath(candidate, parent) {
+    return candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
+}
+function isPathEscape(relativePath) {
+    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+}
+export async function mkdirPathComponentsWithGuards(params) {
+    const root = path.resolve(params.rootReal);
+    const target = path.resolve(params.targetPath);
+    const relative = path.relative(root, target);
+    if (isPathEscape(relative)) {
+        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
+    }
+    let current = root;
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        const next = path.join(current, part);
+        const parentGuard = await createAsyncDirectoryGuard(current);
+        await params.beforeComponent?.(next);
+        await assertAsyncDirectoryGuard(parentGuard);
+        try {
+            await fs.mkdir(next);
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+        const stat = await fs.lstat(next);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new FsSafeError("not-file", "directory component must be a directory");
+        }
+        // Node's recursive mkdir follows symlinks in missing components. Build one
+        // segment at a time and realpath-check each segment before descending.
+        if (!isSameOrChildPath(path.resolve(await fs.realpath(next)), root)) {
+            throw new FsSafeError("outside-workspace", "directory escaped workspace root");
+        }
+        await createAsyncDirectoryGuard(next);
+        await assertAsyncDirectoryGuard(parentGuard);
+        current = next;
+    }
+}

package/dist/guarded-mutation.d.ts

@@ -0,0 +1,33 @@
+import { type AsyncDirectoryGuard, type SyncDirectoryGuard } from "./directory-guard.js";
+export declare function withAsyncDirectoryGuards<T>(guards: readonly AsyncDirectoryGuard[], mutate: () => Promise<T>, options?: {
+    verifyAfter?: boolean;
+    onPostGuardFailure?: (result: T, error: unknown) => Promise<void> | void;
+}): Promise<T>;
+export declare function withSyncDirectoryGuards<T>(guards: readonly SyncDirectoryGuard[], mutate: () => T, options?: {
+    verifyAfter?: boolean;
+}): T;
+export declare function guardedRename(params: {
+    from: string;
+    to: string;
+    targetRoot?: string;
+    verifyAfter?: boolean;
+}): Promise<void>;
+export declare function guardedRenameSync(params: {
+    from: string;
+    to: string;
+    targetRoot?: string;
+    verifyAfter?: boolean;
+}): void;
+export declare function guardedRm(params: {
+    target: string;
+    recursive?: boolean;
+    force?: boolean;
+    verifyAfter?: boolean;
+}): Promise<void>;
+export declare function guardedRmSync(params: {
+    target: string;
+    recursive?: boolean;
+    force?: boolean;
+    verifyAfter?: boolean;
+}): void;
+//# sourceMappingURL=guarded-mutation.d.ts.map

package/dist/guarded-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}

package/dist/guarded-mutation.js

@@ -0,0 +1,76 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, createNearestExistingSyncDirectoryGuard, createSyncDirectoryGuard, } from "./directory-guard.js";
+export async function withAsyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        await assertAsyncDirectoryGuard(guard);
+    }
+    const result = await mutate();
+    if (options.verifyAfter !== false) {
+        try {
+            for (const guard of guards) {
+                await assertAsyncDirectoryGuard(guard);
+            }
+        }
+        catch (error) {
+            if (options.onPostGuardFailure) {
+                try {
+                    // The mutation may have returned an owned resource before the post-guard
+                    // check detected a swapped directory. Give callers one chance to close
+                    // handles without letting cleanup hide the boundary failure.
+                    await options.onPostGuardFailure(result, error);
+                }
+                catch {
+                    // Preserve the boundary failure. Cleanup is best-effort.
+                }
+            }
+            throw error;
+        }
+    }
+    return result;
+}
+export function withSyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        assertSyncDirectoryGuard(guard);
+    }
+    const result = mutate();
+    if (options.verifyAfter !== false) {
+        for (const guard of guards) {
+            assertSyncDirectoryGuard(guard);
+        }
+    }
+    return result;
+}
+export async function guardedRename(params) {
+    const sourceGuard = await createAsyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = params.targetRoot
+        ? await createNearestExistingDirectoryGuard(params.targetRoot, path.dirname(params.to))
+        : await createAsyncDirectoryGuard(path.dirname(params.to));
+    await withAsyncDirectoryGuards([sourceGuard, targetGuard], async () => {
+        await fs.rename(params.from, params.to);
+    }, { verifyAfter: params.verifyAfter });
+}
+export function guardedRenameSync(params) {
+    const sourceGuard = createSyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = params.targetRoot
+        ? createNearestExistingSyncDirectoryGuard(params.targetRoot, path.dirname(params.to))
+        : createSyncDirectoryGuard(path.dirname(params.to));
+    withSyncDirectoryGuards([sourceGuard, targetGuard], () => fsSync.renameSync(params.from, params.to), { verifyAfter: params.verifyAfter });
+}
+export async function guardedRm(params) {
+    const guard = await createAsyncDirectoryGuard(path.dirname(params.target));
+    await withAsyncDirectoryGuards([guard], async () => {
+        await fs.rm(params.target, {
+            ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+            ...(params.force !== undefined ? { force: params.force } : {}),
+        });
+    }, { verifyAfter: params.verifyAfter });
+}
+export function guardedRmSync(params) {
+    const guard = createSyncDirectoryGuard(path.dirname(params.target));
+    withSyncDirectoryGuards([guard], () => fsSync.rmSync(params.target, {
+        ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+        ...(params.force !== undefined ? { force: params.force } : {}),
+    }), { verifyAfter: params.verifyAfter });
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, } from "./errors.js";
 export { DEFAULT_ROOT_MAX_BYTES, root, type HardlinkPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
 export { configureFsSafePython, getFsSafePythonConfig, type FsSafePythonConfig, type FsSafePythonMode, } from "./pinned-python-config.js";
+export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
 export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
 export { DEFAULT_ROOT_MAX_BYTES, root, } from "./root.js";
 export { configureFsSafePython, getFsSafePythonConfig, } from "./pinned-python-config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/dist/json-document-store.d.ts

@@ -1,8 +1,10 @@
 import type { FileLockRetryOptions } from "./file-lock.js";
+import type { SidecarLockStaleRecovery } from "./sidecar-lock.js";
 export type JsonStoreLockOptions = {
     staleMs?: number;
     timeoutMs?: number;
     retry?: FileLockRetryOptions;
+    staleRecovery?: SidecarLockStaleRecovery;
     managerKey?: string;
 };
 export type JsonFileStoreOptions = {

package/dist/json-document-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AAyBF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CA0Dd"}
+{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AA2BF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CA2Dd"}

package/dist/json-document-store.js

@@ -1,3 +1,4 @@
+import { getFsSafeLockConfig } from "./lock-config.js";
 import { createSidecarLockManager } from "./sidecar-lock.js";
 function cloneFallback(value) {
     if (value && typeof value === "object") {
@@ -10,11 +11,13 @@ function resolveLockOptions(filePath, options) {
         return null;
     }
     const lockOptions = options.lock === true ? {} : options.lock;
+    const defaults = getFsSafeLockConfig();
     return {
         managerKey: lockOptions.managerKey ?? `fs-safe.json-store:${filePath}`,
-        retry: lockOptions.retry ?? {},
-        staleMs: lockOptions.staleMs ?? 30_000,
-        timeoutMs: lockOptions.timeoutMs ?? 30_000,
+        retry: lockOptions.retry ?? defaults.retry ?? {},
+        staleMs: lockOptions.staleMs ?? defaults.staleMs ?? 30_000,
+        staleRecovery: lockOptions.staleRecovery ?? defaults.staleRecovery,
+        timeoutMs: lockOptions.timeoutMs ?? defaults.timeoutMs ?? 30_000,
     };
 }
 export function createJsonStore(adapter, options = {}) {
@@ -40,6 +43,7 @@ export function createJsonStore(adapter, options = {}) {
             staleMs: lockOptions.staleMs,
             timeoutMs: lockOptions.timeoutMs,
             retry: lockOptions.retry,
+            staleRecovery: lockOptions.staleRecovery,
             allowReentrant: true,
             payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
         }, run);

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