Copilot instructions

1---
2applyTo: "**/*.ts"
3---
4 
5# TypeScript Review Guidelines
6 
7## Type Safety
8 
9- Avoid `any` — use `unknown` for external data (JSON.parse results, JSONL lines), then narrow with type guards
10- Define interfaces for all object shapes that cross module boundaries — not inline object literals
11- Use `as const` for literal arrays like `TOOL_NAMES` to get narrower inferred types
12 
13```typescript
14// Avoid
15const parsed = JSON.parse(line) as any;
16return parsed.type;
17 
18// Prefer
19const parsed = JSON.parse(line) as unknown;
20if (typeof parsed !== 'object' || parsed === null || !('type' in parsed)) return;
21// Narrowed — safe to access (parsed as Record<string, unknown>)
22```
23 
24## Discriminated Unions
25 
26- Use `switch (d.category)` for narrowing `StructuredToolSample` — not `instanceof` checks
27- New tool sample types must be added to the `StructuredToolSample` union in `src/types/index.ts`
28- The `category` field is the discriminant — never use string-equality checks outside of switch
29 
30## Async Patterns
31 
32- All file I/O must be async: use `fs.promises.*` not `fs.readFileSync` / `fs.writeFileSync`
33- JSONL files must be streamed with `readline.createInterface` — never loaded into memory wholesale
34- Avoid blocking the event loop in parsers — they run in parallel via `Promise.allSettled`
35 
36## Import Rules
37 
38- Local imports must end in `.js`: `import { foo } from './bar.js'` — required for Node.js ESM module resolution
39- Never import from `dist/` in source files
40- Prefer named exports over default exports for better refactoring support
41 
42## Defensive Patterns
43 
44- Use optional chaining (`?.`) and nullish coalescing (`??`) for optional fields from parsed session data
45- Sessions returned from parsers must be sorted by `updatedAt` descending (newest first)
46- Use `process.exitCode = N` over `process.exit(N)` to allow SIGTERM/SIGINT handlers to run
47