98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# AGENTS.md
|
|
|
|
## Build, Lint, and Test Commands
|
|
|
|
### Development
|
|
- `bun start` - Run the application
|
|
- `bun run dev` - Run with hot reload (watch mode)
|
|
|
|
### Build
|
|
- `bun run build` - Build JavaScript bundle to `dist/`
|
|
- `bun run build:native` - Build native libraries (requires `scripts/build-cavacore.sh`)
|
|
|
|
### Testing
|
|
- `bun test` - Run all tests
|
|
- `bun tests/cavacore-smoke.ts` - Run specific native library smoke test
|
|
|
|
### Linting
|
|
- `bun run lint` - Run ESLint with TypeScript rules
|
|
|
|
## Code Style Guidelines
|
|
|
|
### TypeScript Configuration
|
|
- Target: ESNext with bundler module resolution
|
|
- Strict mode enabled
|
|
- Path alias: `@/*` maps to `src/*`
|
|
- JSX: Use `@opentui/solid` as import source
|
|
|
|
### Import Organization
|
|
1. Third-party framework imports (solid-js, @opentui/solid)
|
|
2. Local utility imports
|
|
3. Type imports (separate from value imports)
|
|
|
|
### Naming Conventions
|
|
- **Components**: PascalCase (e.g., `FeedPage`, `Player`)
|
|
- **Hooks**: `use*` prefix (e.g., `useAudio`, `useAppKeyboard`)
|
|
- **Stores**: `create*` factory + `use*` accessor (e.g., `createFeedStore`, `useFeedStore`)
|
|
- **Utilities**: camelCase (e.g., `parseRSSFeed`, `detectPlayers`)
|
|
- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_EPISODES_REFRESH`)
|
|
- **Types/interfaces**: PascalCase (e.g., `Feed`, `AudioBackend`)
|
|
- **Enums**: PascalCase (e.g., `FeedVisibility`)
|
|
|
|
### Code Structure
|
|
- **Section Dividers**: Use `// ── Section Name ────────────────────────────────────────────────────────────` format
|
|
- **Helper Functions**: Define before main logic
|
|
- **Factory Functions**: Use for store creation (return object with state, computed, actions)
|
|
- **Singleton Pattern**: Stores use module-level singleton with `use*` accessor
|
|
|
|
### Type Definitions
|
|
- Use `interface` for object shapes
|
|
- Use `type` for unions, intersections, and complex types
|
|
- Use `enum` for constant sets
|
|
- Export types from `src/types/` directory
|
|
- Include JSDoc comments for complex types
|
|
|
|
### Error Handling
|
|
- Use `try/catch` for async operations
|
|
- For expected failures, use `.catch(() => {})` to suppress errors
|
|
- Return default values on failure (e.g., `return []` or `return null`)
|
|
- Use `catch` blocks with descriptive comments for unexpected errors
|
|
- For UI components, wrap in `ErrorBoundary` with clear fallback
|
|
|
|
### Async Patterns
|
|
- Fire-and-forget async operations: `.catch(() => {})` with comment
|
|
- Async store initialization: IIFE `(async () => { ... })()`
|
|
- Promise handling: Use `.catch()` to return defaults
|
|
|
|
### Comments
|
|
- **File headers**: Brief description of file purpose
|
|
- **Complex functions**: JSDoc-style comments explaining behavior
|
|
- **Section dividers**: Visual separators for code organization
|
|
- **Inline comments**: Explain non-obvious logic, especially async patterns
|
|
|
|
### Code Formatting
|
|
- 2-space indentation
|
|
- No semicolons (Bun style)
|
|
- Arrow functions with implicit return where appropriate
|
|
- Object shorthand where possible
|
|
- Prefer `const` over `let`
|
|
|
|
### Reactivity (Solid.js)
|
|
- Use `createSignal` for primitive state
|
|
- Use `createMemo` for computed values
|
|
- Use `createEffect` for side effects
|
|
- Component functions return JSX
|
|
- Store functions return plain objects with state, computed, and actions
|
|
|
|
### Persistence
|
|
- Async persistence operations fire-and-forget
|
|
- Use `.catch(() => {})` to suppress errors
|
|
- Update state synchronously, persist asynchronously
|
|
- Use `setFeeds()` pattern to update state and trigger save
|
|
|
|
### Testing
|
|
- Test files in `tests/` directory
|
|
- Use Bun's test framework
|
|
- Include JSDoc comments explaining test purpose
|
|
- Native library tests use `bun:ffi` for FFI calls
|