Contributing
Contributions are welcome. The full contributor guide lives in the repo alongside the code:
- CONTRIBUTING.md — dev setup, design constraints, tests, releases.
- CLA.md — the Coralogix Contributor License Agreement, enforced by CLA Assistant on your first pull request.
- SECURITY.md — reporting vulnerabilities responsibly.
Quick dev loop
bash
npm install
npm test # vitest, the whole suite
npm run typecheck # tsc --noEmit
npm run build # tsup -> dist/
npm run check:pkg # publint + are-the-types-wrong, against a real npm pack
npm run check:scrub # blocks internal names, tickets and credentials
npm run license:check # every source file carries the Apache headerAll six run in CI, plus a three-OS test matrix and an install matrix covering npm, pnpm, yarn (node-modules and PnP) and bun.
npm run license:fix adds any missing headers for you.
Design constraints
These are not style preferences. Breaking one is a bug even if the tests pass.
- Zero runtime dependencies. Anything in
dependenciesis a defect. - Nothing may take a dev server down. Staghorn wraps someone's working dev server; a failure degrades a rung and warns, it never throws into the wrapped process.
- Everything is injected — clock, logger, paths, liveness checks, the port prober. That is what makes the suite runnable without sockets or daemons.
- No test binds a privileged port. The listen address is configuration, so every case runs unprivileged on every platform.
- Never touch a daemon you do not own. Anything answering the control port that is not Staghorn is left strictly alone.
The docs site
bash
npm run docs:dev # local preview with hot reload
npm run docs:build # what CI publishesThe site is published to GitHub Pages by running the Docs workflow from main.