@openclaw/fs-safe 0.3.0 → 0.4.1

package/docs/walk.md

@@ -25,6 +25,7 @@ type WalkDirectoryResult = {
   entries: WalkDirectoryEntry[];
   scannedEntryCount: number;
   truncated: boolean;
+  failedDirs?: WalkDirectoryFailure[];
 };
 
 type WalkDirectoryEntry = {
@@ -35,10 +36,19 @@ type WalkDirectoryEntry = {
   kind: "file" | "directory" | "symlink" | "other";
   dirent: import("node:fs").Dirent;
 };
+
+type WalkDirectoryFailure = {
+  path: string;
+  relativePath: string;
+  depth: number;
+  error: unknown;
+};
 ```
 
 `depth` starts at `1` for direct children of `rootDir`. `relativePath` is always relative to the supplied root. `scannedEntryCount` counts directory entries examined, including entries filtered out by `include`.
 
+`walkDirectory()` and `walkDirectorySync()` always return `failedDirs`; the property remains optional on the exported `WalkDirectoryResult` type so existing callers that manually construct the legacy result shape remain source-compatible. It lists every directory whose `realpath`/`readdir` threw, so its contents are absent from `entries`. `error` is the thrown value (a `NodeJS.ErrnoException` at runtime), so callers can distinguish a benign missing-directory race (`ENOENT`) from a real read failure (`EACCES`, `EIO`, `ESTALE`, …). The walk-root failure has an empty `relativePath` and `depth: 0`. Failures resolving a symlink's target kind are not reported here.
+
 ## Options
 
 ```ts
@@ -55,7 +65,7 @@ type WalkDirectoryOptions = {
 
 `include` controls which entries are returned. `descend` controls which directory entries are traversed. A skipped directory can still be returned if `include` accepts it.
 
-Unreadable directories are skipped. This makes the helper suitable for best-effort inventories and pruning jobs; use a stricter root-bounded operation when every entry must be accounted for.
+Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
 
 ## See also
 

package/docs/writing.md

@@ -93,14 +93,14 @@ type RootWriteJsonOptions = {
 
 ### `fs.append(rel, data, options?)`
 
-Open in append mode, write, close. Honors `mkdir` for the parent directory. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
+Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
 
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);
 await fs.append("notes/scratch.md", "* new bullet", { prependNewlineIfNeeded: true });
 ```
 
-For high-volume logging, consider [`openWritable`](#openwritable) and a long-lived append handle.
+For high-volume logging, consider [`openWritable`](#openwritable) and a long-lived append handle. Direct append-mode writes preserve kernel append semantics, but they are not atomic against external rotators that rename or unlink the target.
 
 ### `fs.copyIn(rel, sourceAbsPath, options?)`
 
@@ -192,7 +192,7 @@ await fs.write("data/blob.bin", buffer, { mkdir: false }); // override
 | `not-found` | Parent does not exist and `mkdir` is false. |
 | `not-empty` | `remove()` on a non-empty directory. |
 | `not-removable` | `remove()` could not unlink/rmdir (typically permissions or device busy). |
-| `path-mismatch` | Post-write fd identity check did not match. Almost always a parallel writer. |
+| `path-mismatch` | Post-write fd identity check did not match. Almost always a parallel writer, or a FUSE mount with unstable inode numbers — see `renameIdentity` below. |
 | `too-large` | `copyIn()` source exceeded `maxBytes`. |
 | `symlink` | A path component is a symlink and policy is `reject`. |
 | `hardlink` | `sourceHardlinks: "reject"` saw `nlink > 1`. |
@@ -232,6 +232,26 @@ try {
 await fs.append(today, line);
 ```
 
+## FUSE mounts and unstable inode numbers
+
+Some FUSE mounts — rclone is a confirmed example — assign the destination a different inode number from the source temp file as a result of rename, even within a single process with zero concurrency. Repeated stats of an unchanged destination remain stable, but the source-to-destination `(dev, ino)` comparison always fails with `path-mismatch`.
+
+Set `renameIdentity: "verify-content-with-lock"` on the root (or per call) to use a SHA-256 content comparison under a cooperative sidecar lock instead:
+
+```ts
+const fs = await root("/mnt/rclone-workspace", {
+  renameIdentity: "verify-content-with-lock",
+});
+
+await fs.write("state.json", body); // succeeds on rclone FUSE
+```
+
+**How it works.** The full write runs under an exclusive per-target lock named `.fs-safe-write-<sha256>.lock` in the root. Keeping the lock in the already-canonical root avoids creating an unguarded lock path through a missing or raced target parent. The guarded Node fallback accepts the source-temp-to-destination inode mismatch only when the SHA-256 of the re-read bytes matches the SHA-256 of the bytes written. Subsequent path identity checks remain strict, so this mode requires an unchanged destination path to report stable identity. It deliberately bypasses the stricter fd-relative Python helper because that helper requires rename to preserve inode identity. The lock is released before the call returns.
+
+**Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain the Python helper's fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
+
+Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Remove a stale sidecar only after proving that its holder can no longer write, using the application-owned recovery guidance in [File lock](sidecar-lock.md#stale-recovery-remove-if-unchanged).
+
 ## See also
 
 - [Atomic writes](atomic.md) — the lower-level `replaceFileAtomic` and friends.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {
@@ -97,29 +97,35 @@
       "default": "./dist/test-hooks.js"
     }
   },
+  "optionalDependencies": {
+    "jszip": "^3.10.1",
+    "tar": "7.5.19"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "@vitest/coverage-v8": "4.1.9",
+    "typescript": "^5.9.3",
+    "vite": "7.3.5",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
     "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",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
     "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm test",
-    "docs:site": "node scripts/build-docs-site.mjs"
-  },
-  "optionalDependencies": {
-    "jszip": "^3.10.1",
-    "tar": "7.5.13"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.19",
-    "@vitest/coverage-v8": "4.1.6",
-    "typescript": "^5.8.3",
-    "vitest": "^4.1.6"
-  },
-  "engines": {
-    "node": ">=20.11"
+    "docs:site": "node scripts/build-docs-site.mjs",
+    "check:changed": "pnpm run check",
+    "test:changed": "pnpm run test",
+    "crabbox:hydrate": "crabbox actions hydrate",
+    "crabbox:run": "crabbox run",
+    "crabbox:stop": "crabbox stop",
+    "crabbox:warmup": "crabbox warmup"
   }
-}
+}