Peter Steinberger a559283ac5

- 25 markdown guides covering every public primitive: root(), pathScope(),
  reading/writing, atomic writes, JSON, temp workspaces, archive extraction,
  secret files, sidecar locks, pinned open, local roots, path/filename helpers,
  install paths, errors, types, testing, timing, contributing.
- Custom Node-based static site generator (scripts/build-docs-site.mjs) with
  link validation, dark mode, mobile nav, search, copy buttons.
- GitHub Actions workflow deploys to Pages on docs/script changes.
- CNAME points to fs-safe.io (DNS already configured to GitHub Pages IPs).

To activate: switch repo Pages source from legacy/branch to workflow.

2026-05-05 17:57:31 +01:00

2.9 KiB

Raw Permalink Blame History

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 20.11 or newer. The dev toolchain uses pnpm; npm install works too but pnpm is what the lockfile is keyed against.

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.

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:

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

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 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.

2.9 KiB Raw Permalink Blame History