Skip to content

CONTRIBUTOR_RUNBOOK.md

Latest commit

 

History

History
60 lines (44 loc) · 2.47 KB

CONTRIBUTOR_RUNBOOK.md

File metadata and controls

60 lines (44 loc) · 2.47 KB

Contributor Runbook

Audience: engineers touching code; use as the day-one checklist.
Nav: Docs index · Quickstart · Tools Reference · Safety

0. Clone & Install

  • bun install (workspace-aware)
  • Node is pinned via .node-version (and .nvmrc for nvm users).
  • Keys: export provider keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) or place in ~/.maestro/keys.json.

1. Build & Verify (fresh repo)

npx nx run maestro:build --skip-nx-cache           # CLI fast path
npm run smoke:local-e2e                            # help/version/headless/mock-agent local smoke
npx nx run maestro:build:all --skip-nx-cache       # CLI + TUI + Web
bun run bun:lint                                   # Biome + eval verifier
npx nx run maestro:test --skip-nx-cache            # Builds TUI/Web, then Vitest
npx nx run maestro:evals --skip-nx-cache           # Scenario runner

Expected: all commands succeed; dist artifacts appear under dist/. smoke:local-e2e is credential-free after build and exercises deterministic mock-agent read, write/read, search/read, and edit/read flows.

2. Inner Loop

  • bun run dev — TS watch (rebuilds dist/).
  • TUI: bun run cli -- --provider anthropic --model claude-opus-4-6 "hi".
  • Web: bun run web:dev (server on :8080, Vite on :3000).
  • Package builds: bun run --filter @evalops/tui build, bun run --filter @evalops/maestro-web build.

3. Safety Checks

  • Approvals/firewall: see docs/SAFETY.md; web server defaults to auto-approval—use Docker or auth if exposed.
  • Guardian: scripts/guardian.sh --staged (or /guardian in TUI) before commits.

4. Docs & References

  • TUI/CLI UX: docs/FEATURES.md
  • Web parity: docs/WEB_UI.md (single parity source)
  • Tool behaviors: docs/TOOLS_REFERENCE.md
  • Model/registry: docs/MODELS.md + packages/ai/README.md
  • Types/contracts: packages/contracts/README.md
  • Patterns: docs/patterns/INDEX.md

5. Pre-PR Checklist

  • bun run bun:lint
  • npx nx run maestro:test --skip-nx-cache
  • Build touched packages (e.g., npx nx run tui:build, npx nx run maestro-web:build)
  • Ensure docs updated if flags/options changed (source-of-truth notes above)

6. Troubleshooting Quickies

  • Missing keys → maestro --diag
  • Approval blocks → check firewall notes in SAFETY.md
  • Web tooling stuck → curl http://localhost:8080/api/models to validate server
  • Session issues → docs/SESSIONS.md for cleanup and flags