cli-continues copilot-instructions.md

continues — Code Review Standards

Read-Only Semantics

• Session data is NEVER modified. Any PR that writes to ~/.claude/, ~/.codex/, ~/.copilot/, ~/.gemini/, ~/.factory/, ~/.cursor/, or ~/.local/share/opencode/ is a critical bug.
• Handoff files (.continues-handoff.md) write only to the project's own working directory — never to tool storage paths.

ESM Conventions

• All local imports must use .js extensions, even for .ts source files: import { foo } from './bar.js'
• Never use require() — this is an ESM-only codebase ("type": "module" in package.json)
• Use process.exitCode = N instead of process.exit(N) — allows cleanup handlers to run

Error Handling

• Use typed errors from src/errors.ts (ParseError, SessionNotFoundError, ToolNotAvailableError) for user-facing error paths — not bare throw new Error()
• Parsers must silently skip malformed session data with catch {} — never propagate parse errors to the caller

Registry Completeness

• Every SessionSource member in src/types/tool-names.ts must have a registered ToolAdapter in src/parsers/registry.ts
• The completeness assertion at the bottom of registry.ts throws at module load if any adapter is missing — a missing entry crashes the CLI at startup
• Adding a tool to TOOL_NAMES without a registry entry is always a bug; changes to SessionSource require coordinated updates in the registry, fixtures, and tests

Code Quality

• Biome handles all formatting and style — do not introduce ESLint, Prettier, or TSLint configs
• No synchronous file I/O (readFileSync, writeFileSync) in parser code — blocks the event loop when scanning large session directories
• Shared helpers cleanSummary, extractRepoFromCwd, and homeDir live in src/utils/parser-helpers.ts — do not duplicate them in individual parsers

Performance

• Parsers run in parallel via Promise.allSettled in the session index builder — a slow parser delays only its own results
• The session index uses a 5-minute TTL cache at ~/.continues/sessions.jsonl — cache bypasses should be explicitly justified