Skip to main content
Issues and pull requests are welcome. Before opening a PR, run the full local checks.

Local checks

The test suite is the contract. Add or update tests for any behavior change.

Invariants to keep

These mirror the security invariants.
  • argv-only. Never pass user input through a host shell. Every sbx invocation goes through src/sbx.ts with spawn(bin, args, { shell: false }); only that module may import child_process (a test guards this).
  • Containment. All path checks go through the shared helper. Do not hand-roll containment or sanitization at call sites.
  • Policy. Do not weaken the bot-enforced permission policy or the re-assert-after-wake behavior.
  • No secrets. Never commit tokens, passwords, or .env files. Provider credentials belong in sbx secret, not in code or test fixtures.

Host-only checks

Two host-only scripts exercise the real sbx chain. They are not run by the Linux test suite:
Run npm run build first; the scripts import from dist/. See the spike notes in the repository for recorded results and open items.

Changesets

Every pull request that changes behavior should add a changeset:
Pick the bump with this rubric (pre-1.0, so we version for users, not API stability):
  • patch — bug fixes, refactors, dependency/tooling/docs changes, performance, formatting, and single features that slot into the existing model (a new command, flag, or input type).
  • minor — a feature set or a change to the model or policy: a new subsystem, a new install or run path, a permission/security-policy change, a default-behavior change, or a config/data-format change.
  • major — reserved for 1.0+ breaking changes.
changeset version takes the highest pending bump, so several minors in one release still produce a single minor bump; extra entries only add changelog lines. Changesets live in .changeset/. On release, npm run changeset:version bumps the version, updates CHANGELOG.md, and regenerates the changelog page from it (npm run changelog:sync).

Docs

The documentation site lives in docs-site/. Preview and validate it locally:
Any change that alters behavior, configuration, commands, environment variables, or security must also update the affected page here and the README, and add a changeset. The canonical limitations live in Limitations. AGENTS.md states the definition of done and CI enforces it (the meta job).