@openclaw/fs-safe 0.2.3 → 0.2.5

package/docs/sidecar-lock.md

@@ -51,7 +51,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   staleMs?: number;                      // default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
-  staleRecovery?: "fail-closed";         // default
+  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
   allowReentrant?: boolean;              // if this process already holds it, increment a count instead of failing
   payload: () => TPayload | Promise<TPayload>;
   shouldReclaim?: (params: {
@@ -62,6 +62,12 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     nowMs: number;
     heldByThisProcess: boolean;
   }) => boolean | Promise<boolean>;
+  shouldRemoveStaleLock?: (snapshot: {
+    lockPath: string;
+    normalizedTargetPath: string;
+    raw: string;
+    payload: Record<string, unknown> | null;
+  }) => boolean | Promise<boolean>;
   metadata?: Record<string, unknown>;    // attached to heldEntries() output for diagnostics
 };
 
@@ -101,7 +107,7 @@ try {
 }
 ```
 
-If your process dies before `release()` runs and skips the exit handler, the sidecar remains. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed instead of deleting by path, because Node cannot atomically bind that deletion to the file that was inspected.
+If your process dies before `release()` runs and skips the exit handler, the sidecar remains. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed by default instead of deleting by path.
 
 ## `withFileLock` — common shape made one-liner
 
@@ -164,18 +170,40 @@ const handle = await acquireFileLock(targetPath, {
 });
 ```
 
-`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result does not delete the sidecar; it lets the acquire loop stop waiting once the retry/timeout policy says to give up.
+`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or tries caller-approved removal.
+
+## Stale recovery: `remove-if-unchanged`
+
+The default `staleRecovery: "fail-closed"` never removes third-party sidecars. Use `staleRecovery: "remove-if-unchanged"` only when your app has a reliable owner-liveness policy and can prove a stale owner cannot still be writing.
+
+```ts
+const handle = await acquireFileLock(targetPath, {
+  staleMs: 60_000,
+  staleRecovery: "remove-if-unchanged",
+  payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+  shouldReclaim: ({ payload }) => {
+    const pid = Number(payload?.pid);
+    return Number.isInteger(pid) && pid > 0 && ownerIsDefinitelyDead(pid);
+  },
+  shouldRemoveStaleLock: ({ payload }) => {
+    const pid = Number(payload?.pid);
+    return Number.isInteger(pid) && pid > 0 && ownerIsDefinitelyDead(pid);
+  },
+});
+```
+
+`shouldRemoveStaleLock` receives the exact lock snapshot that `fs-safe` inspected. `fs-safe` re-reads the sidecar and removes it only if the raw content and file identity are unchanged. If the callback is missing, returns false, or the file changed, acquisition fails closed or keeps retrying according to the normal retry policy.
 
 ## What sidecar locks defend against
 
 - **Two processes writing the same file at once.** `acquire` serializes the critical section.
-- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks fail closed because safe compare-and-unlink is not available through Node's path APIs.
+- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks fail closed by default. Opt-in removal rechecks the observed snapshot before unlinking.
 - **Race between simultaneous acquire attempts.** `O_CREAT | O_EXCL` ensures one wins.
 
 ## What they do **not** defend against
 
 - **Misbehaving holders that ignore the lock.** Locks are advisory — only callers that go through `acquire` are bound.
-- **Automatic stale lock deletion.** If a process crashes, use the payload and your own supervisor/process table to decide when to remove the sidecar.
+- **Automatic stale lock deletion.** If a process crashes, use the payload and your own supervisor/process table to decide when removal is safe, then opt into `remove-if-unchanged`.
 - **Multi-host coordination over network filesystems.** Behavior depends on the underlying filesystem's `O_EXCL` semantics; treat as best-effort.
 
 ## Common patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {
@@ -99,7 +99,7 @@
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
     "prepack": "node scripts/prepack-build.mjs",
@@ -115,9 +115,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.15.19",
-    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/coverage-v8": "4.1.6",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.4"
+    "vitest": "^4.1.6"
   },
   "engines": {
     "node": ">=20.11"

package/dist/path-scope.d.ts

@@ -1,2 +0,0 @@
-export { pathScope, type PathScope, type PathScopeOptions, type PathScopeResolveOptions, } from "./root-paths.js";
-//# sourceMappingURL=path-scope.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"path-scope.d.ts","sourceRoot":"","sources":["../src/path-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC"}

package/dist/path-scope.js

@@ -1 +0,0 @@
-export { pathScope, } from "./root-paths.js";

package/dist/private-file-store.d.ts

@@ -1,58 +0,0 @@
-export type PrivateFileStore = {
-    rootDir: string;
-    path(relativePath: string): string;
-    readText(relativePath: string, options?: {
-        maxBytes?: number;
-    }): Promise<string | null>;
-    readJson<T = unknown>(relativePath: string, options?: {
-        maxBytes?: number;
-    }): Promise<T | null>;
-    writeText(relativePath: string, content: string | Uint8Array): Promise<void>;
-    writeJson(relativePath: string, value: unknown, options?: {
-        trailingNewline?: boolean;
-    }): Promise<void>;
-};
-export declare function writePrivateTextAtomic(params: {
-    rootDir: string;
-    filePath: string;
-    content: string | Uint8Array;
-}): Promise<void>;
-export declare function readPrivateText(params: {
-    rootDir: string;
-    filePath: string;
-    maxBytes?: number;
-}): Promise<string | null>;
-export declare function readPrivateTextSync(params: {
-    rootDir: string;
-    filePath: string;
-    maxBytes?: number;
-}): string | null;
-export declare function readPrivateJson<T = unknown>(params: {
-    rootDir: string;
-    filePath: string;
-    maxBytes?: number;
-}): Promise<T | null>;
-export declare function readPrivateJsonSync<T = unknown>(params: {
-    rootDir: string;
-    filePath: string;
-    maxBytes?: number;
-}): T | null;
-export declare function writePrivateTextAtomicSync(params: {
-    rootDir: string;
-    filePath: string;
-    content: string | Uint8Array;
-}): void;
-export declare function writePrivateJsonAtomic(params: {
-    rootDir: string;
-    filePath: string;
-    value: unknown;
-    trailingNewline?: boolean;
-}): Promise<void>;
-export declare function writePrivateJsonAtomicSync(params: {
-    rootDir: string;
-    filePath: string;
-    value: unknown;
-    trailingNewline?: boolean;
-}): void;
-export declare function privateFileStore(rootDir: string): PrivateFileStore;
-//# sourceMappingURL=private-file-store.d.ts.map

package/dist/private-file-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"private-file-store.d.ts","sourceRoot":"","sources":["../src/private-file-store.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxF,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG,CAAC;AAgBF,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBzB;AAoBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,IAAI,CAiBhB;AAED,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAGpB;AAED,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC,GAAG,IAAI,CAGX;AAoCD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,IAAI,CA4CP;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,IAAI,CAOP;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAiClE"}

package/dist/private-file-store.js

@@ -1,220 +0,0 @@
-import { randomUUID } from "node:crypto";
-import path from "node:path";
-import fs from "node:fs";
-import { FsSafeError } from "./errors.js";
-import { isPathInside } from "./path.js";
-import { readRegularFileSync } from "./regular-file.js";
-import { root } from "./root.js";
-import { writePrivateSecretFileAtomic } from "./secret-file.js";
-function resolvePrivateStorePath(rootDir, relativePath) {
-    const root = path.resolve(rootDir);
-    const raw = relativePath.trim();
-    if (!raw || path.isAbsolute(raw) || raw.includes("\0")) {
-        throw new Error("Private file path must be a relative path.");
-    }
-    const resolved = path.resolve(root, raw);
-    const rel = path.relative(root, resolved);
-    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
-        throw new Error("Private file path must stay under the private store root.");
-    }
-    return resolved;
-}
-export async function writePrivateTextAtomic(params) {
-    await writePrivateSecretFileAtomic(params);
-}
-export async function readPrivateText(params) {
-    const rootDir = path.resolve(params.rootDir);
-    const filePath = path.resolve(params.filePath);
-    const relative = path.relative(rootDir, filePath);
-    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new Error("Private file path must stay under the private store root.");
-    }
-    try {
-        const storeRoot = await root(rootDir, { hardlinks: "reject", maxBytes: params.maxBytes });
-        const result = await storeRoot.read(relative);
-        return result.buffer.toString("utf8");
-    }
-    catch (err) {
-        if (err instanceof FsSafeError && err.code === "not-found") {
-            return null;
-        }
-        throw err;
-    }
-}
-function assertPrivateReadPathSync(params) {
-    const rootDir = path.resolve(params.rootDir);
-    const filePath = path.resolve(params.filePath);
-    const relative = path.relative(rootDir, filePath);
-    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new Error("Private file path must stay under the private store root.");
-    }
-    const rootStat = fs.lstatSync(rootDir);
-    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-        throw new Error(`Private file root must be a directory: ${rootDir}`);
-    }
-    const rootReal = fs.realpathSync(rootDir);
-    const fileReal = fs.realpathSync(filePath);
-    if (!isPathInside(rootReal, fileReal)) {
-        throw new Error("Private file path must stay under the private store root.");
-    }
-}
-export function readPrivateTextSync(params) {
-    try {
-        assertPrivateReadPathSync(params);
-        const result = readRegularFileSync({
-            filePath: path.resolve(params.filePath),
-            maxBytes: params.maxBytes,
-        });
-        if (result.stat.nlink > 1) {
-            throw new Error(`Private file target must not be hardlinked: ${params.filePath}`);
-        }
-        return result.buffer.toString("utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            return null;
-        }
-        throw err;
-    }
-}
-export async function readPrivateJson(params) {
-    const raw = await readPrivateText(params);
-    return raw === null ? null : JSON.parse(raw);
-}
-export function readPrivateJsonSync(params) {
-    const raw = readPrivateTextSync(params);
-    return raw === null ? null : JSON.parse(raw);
-}
-function ensurePrivateDirectorySync(rootDir, targetDir) {
-    const root = path.resolve(rootDir);
-    const target = path.resolve(targetDir);
-    const relative = path.relative(root, target);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new Error("Private file directory must stay under the private store root.");
-    }
-    let current = root;
-    fs.mkdirSync(current, { recursive: true, mode: 0o700 });
-    const rootStat = fs.lstatSync(current);
-    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-        throw new Error(`Private file root must be a directory: ${current}`);
-    }
-    for (const segment of relative.split(path.sep).filter(Boolean)) {
-        current = path.join(current, segment);
-        try {
-            const stat = fs.lstatSync(current);
-            if (stat.isSymbolicLink() || !stat.isDirectory()) {
-                throw new Error(`Private file directory component must be a directory: ${current}`);
-            }
-        }
-        catch (err) {
-            if (err.code !== "ENOENT") {
-                throw err;
-            }
-            fs.mkdirSync(current, { mode: 0o700 });
-        }
-        try {
-            fs.chmodSync(current, 0o700);
-        }
-        catch {
-            // Best-effort on platforms that do not enforce POSIX modes.
-        }
-    }
-}
-export function writePrivateTextAtomicSync(params) {
-    const root = path.resolve(params.rootDir);
-    const filePath = path.resolve(params.filePath);
-    const relative = path.relative(root, filePath);
-    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new Error("Private file path must stay under the private store root.");
-    }
-    ensurePrivateDirectorySync(root, path.dirname(filePath));
-    try {
-        const stat = fs.lstatSync(filePath);
-        if (stat.isSymbolicLink() || !stat.isFile()) {
-            throw new Error(`Private file target must be a regular file: ${filePath}`);
-        }
-    }
-    catch (err) {
-        if (err.code !== "ENOENT") {
-            throw err;
-        }
-    }
-    const tempPath = path.join(path.dirname(filePath), `.tmp-${process.pid}-${randomUUID()}`);
-    let created = false;
-    try {
-        fs.writeFileSync(tempPath, params.content, { mode: 0o600, flag: "wx" });
-        created = true;
-        try {
-            fs.chmodSync(tempPath, 0o600);
-        }
-        catch {
-            // Best-effort on platforms that do not enforce POSIX modes.
-        }
-        fs.renameSync(tempPath, filePath);
-        created = false;
-        try {
-            fs.chmodSync(filePath, 0o600);
-        }
-        catch {
-            // Best-effort on platforms that do not enforce POSIX modes.
-        }
-    }
-    finally {
-        if (created) {
-            try {
-                fs.unlinkSync(tempPath);
-            }
-            catch {
-                // The temp file is best-effort cleanup after write failure.
-            }
-        }
-    }
-}
-export async function writePrivateJsonAtomic(params) {
-    const json = JSON.stringify(params.value, null, 2);
-    await writePrivateSecretFileAtomic({
-        rootDir: params.rootDir,
-        filePath: params.filePath,
-        content: params.trailingNewline && !json.endsWith("\n") ? `${json}\n` : json,
-    });
-}
-export function writePrivateJsonAtomicSync(params) {
-    const json = JSON.stringify(params.value, null, 2);
-    writePrivateTextAtomicSync({
-        rootDir: params.rootDir,
-        filePath: params.filePath,
-        content: params.trailingNewline && !json.endsWith("\n") ? `${json}\n` : json,
-    });
-}
-export function privateFileStore(rootDir) {
-    const root = path.resolve(rootDir);
-    return {
-        rootDir: root,
-        path: (relativePath) => resolvePrivateStorePath(root, relativePath),
-        readText: async (relativePath, options) => await readPrivateText({
-            rootDir: root,
-            filePath: resolvePrivateStorePath(root, relativePath),
-            maxBytes: options?.maxBytes,
-        }),
-        readJson: async (relativePath, options) => await readPrivateJson({
-            rootDir: root,
-            filePath: resolvePrivateStorePath(root, relativePath),
-            maxBytes: options?.maxBytes,
-        }),
-        writeText: async (relativePath, content) => {
-            await writePrivateTextAtomic({
-                rootDir: root,
-                filePath: resolvePrivateStorePath(root, relativePath),
-                content,
-            });
-        },
-        writeJson: async (relativePath, value, options) => {
-            await writePrivateJsonAtomic({
-                rootDir: root,
-                filePath: resolvePrivateStorePath(root, relativePath),
-                value,
-                trailingNewline: options?.trailingNewline,
-            });
-        },
-    };
-}