@openclaw/fs-safe 0.7.2 → 0.8.1

package/docs/writing.md

@@ -1,8 +1,16 @@
 # Writing
 
 The `Root` handle exposes a tight set of mutation verbs. Replacement writes
-(`write`, `create`, `writeJson`, `createJson`, and `copyIn`) publish with a
-sibling-temp commit so no half-written replacement appears at the destination.
+(`write`, `writeJson`, and `copyIn`) publish with a sibling-temp commit so no
+half-written replacement appears at the destination. Create-only writes
+(`create`, `createJson`, and `write` with `overwrite: false`) use sibling-temp
+staging with an atomic no-replace rename only on backends that provide one —
+the native binding, which `require` mode guarantees and `auto` mode uses when
+the binding loads. The pure-JavaScript fallback has no atomic no-clobber
+rename and does not stage: it claims the final name exclusively with `O_EXCL`
+and writes content in place, so a concurrent observer can see the new file
+before its content is complete. Use `require` mode when that visibility window
+matters.
 `append` and `openWritable` intentionally modify an opened file in place;
 `move`, `remove`, and `mkdir` mutate directory entries rather than file bytes.
 Each verb applies the boundary checks appropriate to its operation.
@@ -91,7 +99,13 @@ alone is never proof that the name still refers to the expected file.
 Don't-clobber variant of `write()`. Throws `already-exists` if the target is there.
 Create-only preflight preserves boundary, alias, hardlink, and type checks without
 opening an existing target to inherit its mode; a fresh file uses the requested
-mode or the normal new-file default.
+mode or the normal new-file default. When the native binding is in use
+(`require` mode, or `auto` mode with a successfully loaded binding), content is
+staged privately and published with an atomic no-replace rename, so the name
+never appears before its bytes. In the pure-JavaScript fallback the name is
+claimed exclusively first and content is written afterward, so observers can
+briefly see an empty file; failure cleanup removes a claimed file only when its
+identity is unchanged.
 
 ```ts
 try {
@@ -207,6 +221,13 @@ destination — there is no atomic-rename step. If you need both streaming and
 atomicity, write to a sibling temp yourself and rename when done; the
 [`atomic`](atomic.md) helpers can do this for you.
 
+On POSIX, existing-target opens use `O_NONBLOCK` as an admission safeguard so
+a no-reader FIFO cannot stall regular-file validation. This does not change
+ordinary regular-file write semantics. `replace` and `update` remain write-only
+opens, including for mode `0o200` files; replacement truncation happens only
+after type, identity, and boundary checks pass. Rejected existing paths are
+never cleanup-owned or unlinked.
+
 ## Write defaults vs per-call options
 
 Set `mkdir: true` once on `root()`; pass text encodings per call when needed:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -93,6 +93,10 @@
       "types": "./dist/temp.d.ts",
       "default": "./dist/temp.js"
     },
+    "./secure-temp-root": {
+      "types": "./dist/secure-temp-dir.d.ts",
+      "default": "./dist/secure-temp-dir.js"
+    },
     "./atomic": {
       "types": "./dist/atomic.d.ts",
       "default": "./dist/atomic.js"
@@ -149,20 +153,20 @@
     "crabbox:warmup": "crabbox warmup"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.7.2",
-    "@openclaw/fs-safe-darwin-x64": "0.7.2",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.7.2",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.7.2",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.7.2",
-    "@openclaw/fs-safe-linux-x64-musl": "0.7.2",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.7.2",
+    "@openclaw/fs-safe-darwin-arm64": "0.8.1",
+    "@openclaw/fs-safe-darwin-x64": "0.8.1",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.1",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.8.1",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.8.1",
+    "@openclaw/fs-safe-linux-x64-musl": "0.8.1",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.8.1",
     "jszip": "^3.10.1",
     "tar": "7.5.22"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.4",
     "@napi-rs/cli": "3.8.6",
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.4.1",
     "@vitest/coverage-v8": "4.1.11",
     "fast-check": "^4.9.0",
     "istanbul-lib-coverage": "3.2.2",
@@ -176,5 +180,5 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.24.0"
+  "packageManager": "pnpm@11.25.0"
 }