Contributing

The fs-safe repo lives at github.com/openclaw/fs-safe. Contributions welcome — issues, bug reports, focused PRs.

#Local setup

git clone https://github.com/openclaw/fs-safe.git
cd fs-safe
pnpm install

Node 22 or newer. The dev toolchain and lockfile use pnpm; use the package manager version declared in package.json.

#Build

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

pnpm test

Vitest. Tests live in test/ and follow *.test.ts. Run a single file with:

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 for the rare cases where you need to inject a TOCTOU race deterministically.

#Checks

Run the complete repository gate before handoff:

pnpm check

This runs the filesystem boundary checks, build, tests, and package tarball/import validation.

#Docs

The docs site is rendered from docs/*.md by scripts/build-docs-site.mjs. Build locally to preview:

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:

Create docs/<page>.md. Use a leading # Title heading.
Add the page to the appropriate section in scripts/build-docs-site.mjs (sections array near the top).
Cross-link from docs/index.md if it's a major surface.
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

Maintainers publish from a protected vX.Y.Z tag on main through .github/workflows/release.yml. The workflow requires the package version and a dated CHANGELOG.md section to match the tag, then publishes with npm trusted publishing and provenance before creating the GitHub release.

External contributors do not need to do anything beyond getting the pull request merged. Maintainers must not publish locally or add npm automation tokens.

#Reporting security issues

Suspected security issues belong in private disclosure first. See 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.