Skip to content
TypeScript
1.9 KB
Raw Blame

Contributing to theseus

Thanks for helping compare the planks. A few ground rules keep the ship afloat.

Setup

npm install          # Node ≥ 20; better-sqlite3/ink/react are optional deps
npm run typecheck && npm run lint && npm test && npm run build

Everything runs offline: the deterministic mock runner exercises the full pipeline (theseus --runner mock …), so no API keys or paid calls are needed for development.

Invariants (do not break)

These are asserted by tests and documented in the PRD (docs/):

  • Sort key subagentCount → totalTokens → wallTimeMs — the canonical, reproducible row order.
  • No single score by default — perspective winners + Pareto frontier; --score is opt-in.
  • Determinism — task subsets via sha256; no Math.random in selection paths.
  • Fail-soft — no silent drops; success ≠ resolved; excluded combos carry a reason.
  • null = not collected — never zero-fill unknown values.
  • Self-contained HTML — report.html/graph.html must have zero <script>, src=, <link>, or CDN references (tests enforce this; interactivity is CSS-only).
  • Harnesses apply per-run — never mutate global state (~/.claude, ~/.codex).
  • i18n — user-visible strings go through src/i18n.ts (en/kr/ja/zh).

Workflow

  1. Branch from main; keep PRs focused.
  2. npm run typecheck && npm run lint && npm test must pass (CI runs them on Node 20 and 22).
  3. New behavior needs a test — offline (mock runner), no network.
  4. User-visible strings: add all four languages in src/i18n.ts.
  5. Update NOTES.md with an AS-IS → TO-BE entry for non-trivial changes.

Reporting bugs

Open an issue with: the command you ran, expected vs actual, and — when relevant — the run directory's meta.json/results.jsonl (they contain no secrets; scrub task content if private).