@openclaw/fs-safe 0.1.0 → 0.1.2

package/docs/advanced.md

@@ -0,0 +1,100 @@
+---
+title: Advanced
+description: "Lower-level composition helpers under @openclaw/fs-safe/advanced. Less stable than focused public subpaths."
+---
+
+# `@openclaw/fs-safe/advanced`
+
+Composition primitives that OpenClaw uses to build higher-level APIs. They are public — semver applies — but treated as a less stable surface than the focused subpaths (`root`, `json`, `store`, `temp`, `archive`, `errors`). Reach for them only when you are building a primitive of your own and the focused subpaths do not cover it.
+
+```ts
+import {
+  pathScope,
+  withTimeout,
+  pathExists,
+  sanitizeUntrustedFileName,
+  // …
+} from "@openclaw/fs-safe/advanced";
+```
+
+## What lives here
+
+The exports group into a handful of themes. Each documented helper has its own page; everything else is reference-only and tracked here.
+
+### Path scopes and root paths
+
+| Export | Page | Notes |
+|---|---|---|
+| `pathScope`, `PathScope`, `PathScopeOptions`, `PathScopeResolveOptions` | [path-scope.md](path-scope.md) | Absolute-path boundary helper with `Result`-shaped returns. |
+| `ensureDirectoryWithinRoot` | – | Create a directory while enforcing the root boundary. |
+| `resolvePathWithinRoot`, `resolvePathsWithinRoot` | – | Resolve one or many relative paths against a trusted root. |
+| `resolveExistingPathsWithinRoot`, `resolveStrictExistingPathsWithinRoot` | – | Same, but require the targets to exist. |
+| `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
+| `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
+| `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
+
+### Absolute path helpers
+
+| Export | Page | Notes |
+|---|---|---|
+| `assertAbsolutePathInput` | – | Validate a caller-supplied absolute path string. |
+| `canonicalPathFromExistingAncestor`, `findExistingAncestor` | – | Canonicalize without requiring the leaf to exist. |
+| `resolveAbsolutePathForRead`, `resolveAbsolutePathForWrite`, `ResolvedAbsolutePath`, `ResolvedWritableAbsolutePath`, `AbsolutePathSymlinkPolicy` | – | Validate an absolute path against a symlink policy before opening. |
+
+### Files and identity
+
+| Export | Page | Notes |
+|---|---|---|
+| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level no-follow open routed through the root-file path. |
+| `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
+| `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
+| `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
+| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
+| `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
+
+### Local roots and file URLs
+
+| Export | Page | Notes |
+|---|---|---|
+| `resolveLocalPathFromRootsSync`, `readLocalFileFromRoots`, related options/result types | [local-roots.md](local-roots.md) | Resolve a path against a list of allowed local roots. |
+| `assertNoWindowsNetworkPath`, `basenameFromMediaSource`, `hasEncodedFileUrlSeparator`, `isWindowsDriveLetterPath`, `isWindowsNetworkPath`, `safeFileURLToPath`, `trySafeFileURLToPath` | – | Defensive helpers around Windows paths and `file://` URLs. |
+
+### Install paths and filenames
+
+| Export | Page | Notes |
+|---|---|---|
+| `safeDirName`, `safePathSegmentHashed`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories from caller-supplied identifiers. |
+| `sanitizeUntrustedFileName` | [filename.md](filename.md) | Coerce an untrusted string into a safe filename. |
+| `resolveHomeRelativePath` | – | Expand `~`-prefixed paths. |
+
+### Temp targets and sibling-temp writes
+
+| Export | Page | Notes |
+|---|---|---|
+| `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.md) | One-file temp primitive; prefer `tempWorkspace` from `@openclaw/fs-safe/temp` for the stable surface. |
+| `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Sibling-temp write building block used by `replaceFileAtomic`. |
+
+### Permissions
+
+| Export | Page | Notes |
+|---|---|---|
+| `formatPosixMode` | [permissions.md](permissions.md) | Format a POSIX mode bitmask. |
+| `inspectWindowsAcl`, `summarizeWindowsAcl`, `formatWindowsAclSummary`, `parseIcaclsOutput`, `resolveWindowsUserPrincipal`, `createIcaclsResetCommand`, `formatIcaclsResetCommand`, `IcaclsResetCommandOptions`, `PermissionExec`, `WindowsAclEntry`, `WindowsAclSummary` | [permissions.md](permissions.md) | Windows ACL inspection and remediation. |
+
+### Concurrency, timing, trash
+
+| Export | Page | Notes |
+|---|---|---|
+| `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
+| `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `FsSafeError("timeout")`. |
+| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. |
+
+## Stability
+
+Items in this surface can change shape between minor versions if a higher-level primitive needs them to. Pin to a minor version if you depend on a specific helper, or open an issue at the [GitHub repo](https://github.com/openclaw/fs-safe) and we will discuss promoting it to a focused subpath.
+
+## Related pages
+
+- [Root API](root.md) — built on top of these helpers.
+- [Errors](errors.md) — every helper here surfaces failures as `FsSafeError`.
+- [Security model](security-model.md) — what the underlying boundary checks promise.

package/docs/archive.md

@@ -0,0 +1,199 @@
+# Archive extraction
+
+`@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. Extraction stages into a private directory and merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
+
+Archive extraction uses optional runtime dependencies: `jszip` for ZIP and `tar`
+for TAR. Installs that omit optional dependencies can still import this subpath,
+inspect archive kinds, and use pure path/limit helpers, but extraction or ZIP
+loading fails with a clear message until the matching optional dependency is
+installed.
+
+Some package managers and CI installs skip optional dependencies
+(`--no-optional`, `--omit=optional`, or equivalent). If an archive helper throws
+that an optional archive dependency is not installed, install `jszip` and/or
+`tar` explicitly in the consuming package.
+
+```ts
+import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
+```
+
+## `extractArchive`
+
+```ts
+await extractArchive({
+  archivePath: "/srv/uploads/plugin.zip",
+  destDir: "/srv/workspace/plugins/plugin",
+  kind: "zip",                        // optional; resolveArchiveKind() can infer
+  timeoutMs: 15_000,                  // hard ceiling for the whole extraction
+  stripComponents: 0,                 // tar-style strip-leading-dirs
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+  },
+});
+```
+
+### Parameters
+
+```ts
+type ExtractArchiveParams = {
+  archivePath: string;          // absolute path to the archive
+  destDir: string;              // absolute destination directory; must already exist
+  timeoutMs: number;            // wall-clock cap; throws on overrun
+  kind?: ArchiveKind;           // "zip" | "tar"; inferred from filename when omitted
+  stripComponents?: number;     // strip N leading dirs from entry paths
+  tarGzip?: boolean;            // when archive is .tar.gz/.tgz
+  limits?: ArchiveExtractLimits;
+  logger?: ArchiveLogger;       // { info?, warn? }
+};
+```
+
+If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names).
+
+### Limits
+
+```ts
+type ArchiveExtractLimits = {
+  maxArchiveBytes?: number;     // refuse if archivePath stat'd size exceeds this
+  maxEntries?: number;          // refuse before extracting if entry count > this
+  maxExtractedBytes?: number;   // refuse mid-stream if total extracted bytes > this
+  maxEntryBytes?: number;       // refuse a single entry larger than this
+};
+```
+
+Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`). They are conservative — pass explicit values when you know your domain's actual ceiling.
+
+A limit violation throws `ArchiveLimitError`. The error's code is one of:
+
+```ts
+ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_BYTES_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.ENTRY_BYTES_EXCEEDS_LIMIT
+```
+
+Catch and branch on the code to surface a meaningful response to the caller.
+
+## What it defends against
+
+- **Path traversal:** entries with `..`, absolute paths, or Windows drive prefixes are rejected (`ArchiveSecurityError`).
+- **Symlink/hardlink entries:** rejected by default. Some archives ship symlink/hardlink entries that point outside the destination once resolved; `extractArchive` does not follow them.
+- **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. A symlink swap in the destination tree mid-merge is caught.
+- **Zip bombs:** `maxExtractedBytes` and `maxEntryBytes` apply to *post-decompression* bytes, so highly-compressed payloads hit the cap before they exhaust disk.
+- **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget. Extraction is aborted on overrun.
+
+## `resolveArchiveKind`
+
+```ts
+import { resolveArchiveKind, type ArchiveKind } from "@openclaw/fs-safe/archive";
+
+const kind = resolveArchiveKind("upload.zip"); // "zip"
+const tar = resolveArchiveKind("upload.tar.gz"); // "tar"
+const unknown = resolveArchiveKind("upload.bin"); // undefined
+```
+
+Recognizes:
+
+- `*.zip` → `"zip"`
+- `*.tar`, `*.tar.gz`, `*.tgz`, `*.tar.bz2`, `*.tbz`, `*.tbz2` → `"tar"`
+
+Returns `undefined` for unknown extensions; check the result before calling `extractArchive` if the filename is caller-controlled.
+
+## Lower-level building blocks
+
+The archive subpath also exports the helpers `extractArchive` is built on. Most callers will not need them, but they are stable and documented:
+
+| Function | Purpose |
+|---|---|
+| `withStagedArchiveDestination(opts)` | Creates a private staging dir outside the destination, calls your `run(stagingDir)`, then cleans it up. |
+| `mergeExtractedTreeIntoDestination(opts)` | The merge step alone — staged tree → destination through boundary checks. |
+| `prepareArchiveDestinationDir(destDir)` | Canonicalizes and asserts the destination directory. |
+| `prepareArchiveOutputPath(opts)` | Resolves a single entry's output path against the staging dir. |
+| `loadZipArchiveWithPreflight(opts)` | Loads a JSZip with size/entry-count preflight before unzipping. |
+| `readZipCentralDirectoryEntryCount(path)` | Returns the entry count from a ZIP's central directory without reading any payloads. |
+| `createTarEntryPreflightChecker(opts)` | Returns a per-entry checker for use as a `tar.x` `onReadEntry` hook. |
+
+These let you build custom extractors that share the same safety machinery — for example, a streaming uploader that wants to refuse archives with too many entries before reading any payloads.
+
+## Path helpers
+
+`archive-entry` exports a handful of low-level helpers for entry-path normalization:
+
+```ts
+import {
+  isWindowsDrivePath,
+  normalizeArchiveEntryPath,
+  resolveArchiveOutputPath,
+  stripArchivePath,
+  validateArchiveEntryPath,
+} from "@openclaw/fs-safe/archive";
+```
+
+- `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, drive-prefixed, or otherwise unsafe entry paths.
+- `normalizeArchiveEntryPath(raw)` — POSIX-normalizes the entry path (forward slashes, no `.` segments).
+- `stripArchivePath(entryPath, n)` — strip the leading N path components, returning `null` if not enough remain.
+- `resolveArchiveOutputPath({ destDir, entryPath })` — combines the entry path with the destination, after validation.
+- `isWindowsDrivePath(value)` — detects `C:\…` style entries that should be rejected.
+
+## Common patterns
+
+### Extract an upload, surface budget violations
+
+```ts
+import { extractArchive, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE } from "@openclaw/fs-safe/archive";
+
+try {
+  await extractArchive({
+    archivePath: upload.path,
+    destDir: targetDir,
+    kind: "zip",
+    timeoutMs: 30_000,
+    limits: {
+      maxArchiveBytes: 100 * 1024 * 1024,
+      maxEntries: 10_000,
+      maxExtractedBytes: 200 * 1024 * 1024,
+      maxEntryBytes: 50 * 1024 * 1024,
+    },
+  });
+} catch (err) {
+  if (err instanceof ArchiveLimitError) {
+    return reply(413, { code: err.code, message: err.message });
+  }
+  throw err;
+}
+```
+
+### Decide kind from MIME, not filename
+
+```ts
+const kind: ArchiveKind = mime === "application/zip" ? "zip" : "tar";
+await extractArchive({ archivePath, destDir, kind, timeoutMs: 10_000 });
+```
+
+### Stage to private dir, then commit as a directory
+
+```ts
+import { withTempWorkspace } from "@openclaw/fs-safe/temp";
+import { replaceDirectoryAtomic } from "@openclaw/fs-safe/atomic";
+
+await withTempWorkspace({ rootDir: "/srv/site/tmp", prefix: "extract-" }, async (ws) => {
+  await extractArchive({
+    archivePath: upload.path,
+    destDir: ws.dir,
+    timeoutMs: 30_000,
+  });
+  await replaceDirectoryAtomic({
+    stagedDir: ws.dir,
+    targetDir: "/srv/site/plugin",
+  });
+});
+```
+
+## See also
+
+- [Atomic writes](atomic.md) — `replaceDirectoryAtomic` for staged directory replacement.
+- [Temp workspaces](temp.md) — extract into a private workspace and commit as one step.
+- [Errors](errors.md) — `FsSafeError` codes the underlying writes can raise.
+- [`extractArchive` source](https://github.com/openclaw/fs-safe/blob/main/src/archive.ts).

package/docs/atomic.md

@@ -0,0 +1,163 @@
+# Atomic writes
+
+`@openclaw/fs-safe/atomic` re-exports the lower-level helpers that `root()`'s write methods are built on. Reach for them when you have an absolute path you trust and want sibling-temp + rename without setting up a `Root`, or when you need finer control over `fsync`, mode preservation, or pre-rename hooks.
+
+```ts
+import {
+  replaceFileAtomic,
+  replaceFileAtomicSync,
+  writeTextAtomic,
+  replaceDirectoryAtomic,
+  movePathWithCopyFallback,
+} from "@openclaw/fs-safe/atomic";
+```
+
+## `replaceFileAtomic` / `replaceFileAtomicSync`
+
+Write `content` to a sibling temp file in the destination directory, optionally `fsync` the temp file, optionally `fsync` the parent directory after rename, then atomically rename over the destination.
+
+Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
+
+```ts
+import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceFileAtomic({
+  filePath: "/srv/workspace/state.json",
+  content: JSON.stringify(state, null, 2),
+  mode: 0o600,
+  syncTempFile: true,
+  syncParentDir: true,
+});
+```
+
+### Options
+
+```ts
+type ReplaceFileAtomicOptions = {
+  filePath: string;                 // destination
+  content: string | Uint8Array;
+  dirMode?: number;                 // mode for parent dirs created by the helper
+  mode?: number;                    // explicit mode for the new file (e.g. 0o600)
+  preserveExistingMode?: boolean;   // copy mode from existing destination, when present
+  tempPrefix?: string;
+  renameMaxRetries?: number;
+  renameRetryBaseDelayMs?: number;
+  copyFallbackOnPermissionError?: boolean;
+  syncTempFile?: boolean;           // fsync(temp) before rename
+  syncParentDir?: boolean;          // fsync(parent) after rename (POSIX only)
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
+};
+```
+
+### `beforeRename`
+
+Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer:
+
+```ts
+await replaceFileAtomic({
+  filePath: "/srv/workspace/config.toml",
+  content: rendered,
+  beforeRename: async ({ filePath }) => {
+    await fs.copyFile(filePath, `${filePath}.bak`); // snapshot existing
+  },
+});
+```
+
+If `beforeRename` throws, the rename is skipped and the temp file is removed — the destination is unchanged.
+
+### `EPERM` and copy fallback
+
+On systems where `rename` fails with `EPERM`/`EEXIST`, pass `copyFallbackOnPermissionError: true` to fall back to copy + unlink. The fallback refuses symlink destinations before copying so it does not write through a replaced destination link.
+
+### Sync variant
+
+`replaceFileAtomicSync` accepts the same options shape, with the obvious removal of the async-only hooks. Use it inside synchronous boot paths or test setup code.
+
+## `replaceDirectoryAtomic`
+
+Atomically swap one directory's contents with another, using a temporary backup during the swap.
+
+```ts
+import { replaceDirectoryAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceDirectoryAtomic({
+  stagedDir: "/srv/workspace/staging/snapshot-2026-05-05",
+  targetDir: "/srv/workspace/snapshot",
+});
+```
+
+The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
+
+Use it when callers must see a whole staged tree at the target path. For single-file replacement, `replaceFileAtomic` is the right tool.
+
+## `writeTextAtomic`
+
+Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
+temp file, temp fsync, rename, parent fsync, and final chmod best-effort.
+It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
+you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
+or custom copy-fallback policy.
+
+```ts
+import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
+
+await writeTextAtomic("/srv/workspace/rendered.md", rendered, {
+  mode: 0o600,
+  dirMode: 0o700,
+  trailingNewline: true,
+});
+```
+
+## `movePathWithCopyFallback`
+
+Rename a path. If the rename fails with `EXDEV` (cross-device) or `EPERM`, fall back to copy + remove. Preserves atomicity at the destination by writing the copy through `replaceFileAtomic` (for files) or staged-rename (for directories).
+
+```ts
+import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
+
+await movePathWithCopyFallback({
+  source: "/srv/cache/blob.bin",
+  destination: "/srv/persistent/blob.bin",
+  overwrite: true,
+});
+```
+
+Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+
+## Difference from `root()`
+
+| `Root` methods | `atomic` helpers |
+|---|---|
+| Take relative paths, bound to a `rootDir`. | Take absolute paths, no boundary. |
+| Throw `FsSafeError` with `code`. | Throw `FsSafeError` *or* the underlying `NodeJS.ErrnoException`, depending on failure point. |
+| Atomicity, mode, hooks, fsync are sane defaults. | Caller controls all of the above. |
+| `mkdir`, identity check, hardlink reject built in. | No identity check, no hardlink reject — pair with [path helpers](path.md) if you need them. |
+
+Use `Root` when the path is caller-controlled. Use `atomic` when the path is fully under your control and you want explicit knobs.
+
+## Test injection
+
+Both `replaceFileAtomic` and `replaceFileAtomicSync` accept a `fileSystem` option that overrides the small set of `fs` calls they make. Pass a stub in unit tests to assert order, simulate `EPERM`, or capture the temp filename:
+
+```ts
+const ops: string[] = [];
+await replaceFileAtomic({
+  filePath: "/tmp/x",
+  content: "hi",
+  fileSystem: {
+    promises: {
+      ...realFs,
+      writeFile: async (...args) => { ops.push("write"); return realFs.writeFile(...args); },
+      rename: async (...args) => { ops.push("rename"); return realFs.rename(...args); },
+    },
+  },
+});
+```
+
+## See also
+
+- [`root()`](root.md) — when you want method-style writes with the boundary baked in.
+- [JSON files](json.md) — JSON/text helpers built on sibling-temp replacement.
+- [Temp workspaces](temp.md) — for staging-then-swap directory builds.
+- [Errors](errors.md) — code union for failures.

package/docs/config.md

@@ -0,0 +1,65 @@
+---
+title: Config
+description: "Process-global configuration for the optional Python helper used by fs-safe on POSIX."
+---
+
+# `@openclaw/fs-safe/config`
+
+Process-global configuration knobs for the optional persistent Python helper that backs POSIX fd-relative operations in `root()`. The whole helper policy is described in the [Python helper policy](python-helper.md); this page is the API reference.
+
+```ts
+import {
+  configureFsSafePython,
+  getFsSafePythonConfig,
+  type FsSafePythonConfig,
+  type FsSafePythonMode,
+} from "@openclaw/fs-safe/config";
+```
+
+`configureFsSafePython` is also re-exported from the main entry point, so `import { configureFsSafePython } from "@openclaw/fs-safe"` works too. Prefer the subpath when you only need helper configuration and want the smallest import surface.
+
+## `configureFsSafePython(config)`
+
+```ts
+function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
+
+type FsSafePythonConfig = {
+  mode: FsSafePythonMode;
+  pythonPath?: string;
+};
+
+type FsSafePythonMode = "auto" | "off" | "require";
+```
+
+Set the process-global policy. Calls merge into the existing override config, so passing `{ pythonPath: "/usr/bin/python3" }` keeps any previously set `mode`. Configure once at startup, before the first `root()` call — switching modes mid-process is supported but the helper may already be running.
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Default. Use the helper when it starts; fall back to Node-only behavior if Python is missing or fails to start. |
+| `off` | Never spawn the helper. Read/write/move use Node fallbacks plus pre/post identity checks. |
+| `require` | Fail closed if the helper cannot start. Operations that need the helper raise `FsSafeError("helper-unavailable")`. |
+
+## `getFsSafePythonConfig()`
+
+```ts
+function getFsSafePythonConfig(): FsSafePythonConfig;
+```
+
+Return the effective configuration: programmatic overrides win, then env vars, then the package default (`auto`).
+
+## Environment variables
+
+The same policy can be set without code:
+
+```bash
+FS_SAFE_PYTHON_MODE=auto      # auto | off | require | true | false | on | off | 1 | 0 | never | required
+FS_SAFE_PYTHON=/usr/bin/python3
+```
+
+OpenClaw compatibility aliases are accepted: `OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`, `OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON`. Programmatic overrides via `configureFsSafePython` always win.
+
+## Related pages
+
+- [Python helper policy](python-helper.md) — when to pick `auto`, `off`, or `require`, and what each mode protects.
+- [Root API](root.md) — the API whose POSIX hardening the helper backs.
+- [Errors](errors.md) — `helper-unavailable` and `helper-failed`.

package/docs/contributing.md

@@ -0,0 +1,80 @@
+# Contributing
+
+The `fs-safe` repo lives at [github.com/openclaw/fs-safe](https://github.com/openclaw/fs-safe). Contributions welcome — issues, bug reports, focused PRs.
+
+## Local setup
+
+```bash
+git clone https://github.com/openclaw/fs-safe.git
+cd fs-safe
+pnpm install
+```
+
+Node 20.11 or newer. The dev toolchain uses pnpm; `npm install` works too but pnpm is what the lockfile is keyed against.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Runs `tsc -p tsconfig.json`. Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
+
+## Test
+
+```bash
+pnpm test
+```
+
+Vitest. Tests live in `test/` and follow `*.test.ts`. Run a single file with:
+
+```bash
+pnpm test test/archive.test.ts
+```
+
+Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
+
+## Format and types
+
+The repo doesn't ship a separate lint config; `tsc --noEmit` (run by `pnpm build`) is the type gate. Format with your editor's TypeScript Language Server defaults — keep diffs tight.
+
+## Docs
+
+The docs site is rendered from `docs/*.md` by `scripts/build-docs-site.mjs`. Build locally to preview:
+
+```bash
+node scripts/build-docs-site.mjs
+open dist/docs-site/index.html
+```
+
+The build validates internal links and embedded anchors. Broken links fail the build — fix them before pushing.
+
+Adding a new doc page:
+
+1. Create `docs/<page>.md`. Use a leading `# Title` heading.
+2. Add the page to the appropriate section in `scripts/build-docs-site.mjs` (`sections` array near the top).
+3. Cross-link from `docs/index.md` if it's a major surface.
+4. Re-run the local build.
+
+Internal links use relative `*.md` paths — the builder rewrites them to the rendered HTML. Code fences support GitHub-flavored markdown.
+
+## PRs
+
+Small, focused PRs land faster. The general shape:
+
+- One concern per PR. Bug fixes separate from new APIs.
+- A regression test for every bug fix where the test framework can express it.
+- A changelog entry under `## Unreleased` when behavior visibly changes.
+- For new public APIs: a docs page in `docs/` plus a sidebar entry.
+
+## Releases
+
+Release process lives in the maintainer's runbook. External contributors don't need to do anything beyond getting the PR merged.
+
+## Reporting security issues
+
+Suspected security issues belong in private disclosure first. See [`SECURITY.md`](https://github.com/openclaw/fs-safe/blob/main/SECURITY.md) in the repo for the current contact path. Don't open a public issue for a credential-stealing or sandbox-escape bug — coordinate the disclosure first.
+
+## License
+
+By contributing you agree that your contributions are licensed under the project's [MIT license](https://github.com/openclaw/fs-safe/blob/main/LICENSE).