caliber-conventions · git:20260319.c97e02c · 2026-03-19 · sha256 6727cb66981f96a9
caliber-conventions git:20260319.c97e02cA
Immutable. This exact content never changes and is served at /api/v1/blob/6727cb66981f96a9.
---
description: Core conventions for the @rely-ai/caliber CLI — ES module imports, error handling, commit format
alwaysApply: true
---
- ES module imports require `.js` extension for `.ts` source files
- Prefer `unknown` over `any`; explicit types on params/returns
- Use `ora` spinners with `.fail()` before rethrowing async errors
- `throw new Error('__exit__')` for clean CLI exits (no stack trace)
- Build: `npm run build` (tsup) · Test: `npm run test` (vitest) · Type-check: `npx tsc --noEmit`
- Commit format: `<type>[(scope)]: <description>` — feat/fix/refactor/chore/docs/test/ci
- Do NOT include Co-Authored-By headers in commits
- Never commit API keys or credentials
- Key deps: commander, chalk, ora, diff, glob, tsup, @inquirer/confirm, @inquirer/select, @inquirer/checkbox
- LLM calls go through `src/llm/index.ts` (`llmCall`, `llmJsonCall`) — never import provider SDKs directly
- All commands in `src/commands/` must be registered in `src/cli.ts` wrapped with `tracked()`
- Backups written to `.caliber/backups/` · manifest at `.caliber/manifest.json`
- Seat-based providers (`cursor`, `claude-cli`): spawn with `stdio: ['pipe', 'pipe', 'pipe']` — never `inherit` for stderr
- Use `parseSeatBasedError()` from `src/llm/seat-based-errors.ts` for Cursor and Claude CLI error parsing
- Stream parsing for `agent --print --output-format stream-json`: use `src/ai/stream-parser.ts`
- Staged files written to `.caliber/staged/proposed/` via `src/writers/staging.ts`