docs: add README and AGENTS.md documentation

2026-02-05 15:51:50 -08:00
parent d2a597d49d
commit b913941e4f
2 changed files with 292 additions and 0 deletions
@@ -0,0 +1,87 @@
+# Flynn AGENTS.md
+
+## Build, Lint, and Test Commands
+
+```bash
+# Build
+pnpm build                    # Compile TypeScript to dist/
+
+# Development
+pnpm dev                      # Run daemon with watch mode
+pnpm tui                      # Run TUI in minimal mode (readline)
+pnpm tui:fs                   # Run TUI in fullscreen mode (React/Ink)
+pnpm tui:dev                  # Run TUI with watch mode
+
+# Run
+pnpm start                    # Start production build
+
+# Testing
+pnpm test                     # Run tests in watch mode
+pnpm test:run                 # Run tests once (no watch)
+
+# Linting and Type Checking
+pnpm lint                     # Run ESLint
+pnpm typecheck                # Run TypeScript compiler (no emit)
+```
+
+## Code Style Guidelines
+
+### Imports
+
+- Use `.js` extensions for imports (e.g., `import { readFileSync } from 'fs';`)
+- Use `type` keyword for type-only imports: `import type { Config } from './schema.js';`
+- Group imports: stdlib → third-party → local
+- Export all public APIs from `index.ts`
+
+### Naming Conventions
+
+- **Classes/Interfaces/Types**: PascalCase (`AnthropicClient`, `NativeAgentConfig`)
+- **Functions**: camelCase (`loadConfig`, `expandEnvVars`)
+- **Private fields**: camelCase with underscore (`_client`, `_model`)
+- **Files**: camelCase for .ts files, PascalCase for .tsx files
+- **Test files**: `*.test.ts` suffix
+
+### TypeScript Configuration
+
+- `tsconfig.json` uses strict mode
+- Target: ES2022
+- Module resolution: NodeNext
+- Module format: NodeNext
+- Enables `declaration`, `declarationMap`, and `sourceMap` for all builds
+
+### Error Handling
+
+- Throw errors with descriptive messages
+- Check for undefined/null with context: `throw new Error('Environment variable ${envVar} is not set')`
+- In stream handlers, wrap errors in try-catch and yield error events
+- Use `instanceof Error` for error type checking: `error instanceof Error ? error.message : 'Unknown error'`
+- Catch errors and convert to appropriate error types with context
+
+### React/Ink Patterns
+
+- Use `useCallback` for event handlers to prevent unnecessary re-renders
+- Use `useRef` for mutable values that don't trigger re-renders
+- Define interface props explicitly
+- Event handlers receive `(inputChar: string, key: KeyInfo)` as arguments
+
+### Project Structure
+
+```
+src/
+├── config/          # YAML config + validation
+├── models/          # Model providers + router
+├── session/         # SQLite persistence
+├── hooks/           # Confirmation engine
+├── daemon/          # Lifecycle management
+├── frontends/       # Telegram bot, TUI
+└── backends/native/ # Agent implementation
+```
+
+## Testing
+
+- Use Vitest for testing
+- Follow `describe`/`it` pattern
+- Use `expect()` for assertions
+- Test both success and failure cases
+- Clean up test resources (files, dirs) in `afterEach` or `it` cleanup blocks
+- Mock file system and environment variables when needed