CONTRIBUTING.md

Contributing

Development

bun install
bun run check

bun run check runs typecheck, lint, format check and unit tests. bun run format rewrites the tree.

Contributors sign the CLA on their first PR; the CLA bot explains how.

Unit tests sit next to the code in src/; end-to-end tests live in e2e/. e2e/live.test.ts calls the ChatGPT Codex backend and runs only when CODEX_LIVE_ACCESS_TOKEN is set:

CODEX_LIVE_ACCESS_TOKEN=<access token> CODEX_LIVE_ACCOUNT_ID=<account id> \
bun run test:e2e

CODEX_LIVE_MODEL is optional (default gpt-5.5).

Commit messages

Commit subjects and PR titles follow Conventional Commits: feat, fix, refactor, test, docs, build, ci, perf, and chore(release): x.y.z for releases. Add ! only for public API breaks: removed or renamed exports, changed signatures, newly required params. Peer and dependency range changes are build(deps): with no !. Keep subjects imperative, lowercase after the colon, 72 characters or less, and free of ticket IDs. Every PR links its issue with a Closes <issue id> line in the PR body.

Releasing

Releases are manual. On a clean, up-to-date main:

npm version <patch|minor> -m "chore(release): %s"
git push --follow-tags
gh release create "v$(node -p 'require("./package.json").version')" --generate-notes
npm publish

Bump minor only for breaking API changes; everything else is a patch. prepack builds dist/ from the tagged commit.