diff --git a/.roo/rules-architect/AGENTS.md b/.roo/rules-architect/AGENTS.md index 303c4039a5..e17aa06e25 100644 --- a/.roo/rules-architect/AGENTS.md +++ b/.roo/rules-architect/AGENTS.md @@ -1,42 +1,10 @@ # Architect Mode Rules -## Design Principles +## Non-Obvious Architecture Constraints -- **VSCode Extension Architecture**: Work within VSCode's webview + extension host model -- **Monorepo Organization**: Maintain clear separation between packages -- **Provider Pattern**: New AI providers must follow existing interface patterns -- **State Management**: React hooks for UI, VSCode context for extension state - -## Package Structure Requirements - -- New packages go in `packages/` directory -- Must include proper TypeScript configuration extending base -- Shared types belong in `packages/types/src/` -- Follow existing naming conventions (e.g., @roo-code/package-name) - -## API Design - -- All providers implement Provider interface from packages/types -- IPC messages must be strongly typed -- Backwards compatibility required for existing provider contracts -- Error handling must include proper error types and recovery - -## Performance Considerations - -- Large JSON operations must use streaming (see safeWriteJson) -- Webview content should lazy-load heavy components -- Code indexing happens asynchronously in background -- Terminal operations should not block UI - -## Evals Database & Migrations - -- Evals database schemas in `packages/evals/src/db/` -- Migrations required for schema changes -- Use proper transaction handling for data consistency - -## Security Patterns - -- Never expose sensitive data in webview -- API keys stored in VSCode SecretStorage -- File operations must validate paths -- Command execution requires user approval +- Providers MUST be stateless - hidden caching layer assumes this +- Webview and extension communicate through specific IPC channel patterns only +- React hooks required because external state libraries break webview isolation +- Large JSON operations must use `safeWriteJson()` for streaming (prevents memory issues) +- TypeScript `noUncheckedIndexedAccess: true` - array/object access may return undefined +- Import paths in packages/ require `.js` extensions despite TypeScript source diff --git a/.roo/rules-ask/AGENTS.md b/.roo/rules-ask/AGENTS.md index 794ffea27d..38b89b6f3a 100644 --- a/.roo/rules-ask/AGENTS.md +++ b/.roo/rules-ask/AGENTS.md @@ -1,39 +1,8 @@ # Ask Mode Rules -## Documentation Sources +## Non-Obvious Documentation Context -- Main documentation: README.md, CONTRIBUTING.md, CHANGELOG.md -- API docs: Check provider implementations in `src/api/providers/` -- UI patterns: Reference `webview-ui/src/components/` for React components -- Types: Refer to `packages/types/src/` for TypeScript interfaces - -## Code Examples - -- Provider examples: Each provider in `src/api/providers/` shows implementation patterns -- Test examples: `src/__tests__/` and `webview-ui/src/**/*.test.tsx` -- IPC patterns: `packages/ipc/src/` for communication examples -- Custom modes: Check `.roo/rules-*/` directories for mode-specific patterns - -## Architecture Explanations - -- **Monorepo Structure**: - - `src/` - VSCode extension backend - - `webview-ui/` - React frontend - - `packages/` - Shared libraries - - `apps/` - Additional applications -- **Webview Architecture**: VSCode extension hosts React app via webview API -- **Provider Pattern**: All AI providers implement common interface for consistency -- **IPC Communication**: Typed messages between extension and webview - -## Command References - -- Build commands: See `package.json` scripts section -- Test commands: Must run from workspace directory with package.json -- Development: F5 launches extension in new VSCode window -- VSIX packaging: `pnpm vsix` creates installable package - -## Localization - -- i18n files in `locales/` directory -- Extension uses vscode.l10n API for translations -- Webview uses i18next for React component translations +- `src/` contains VSCode extension code, NOT generic source (counterintuitive naming) +- Two separate i18n systems: root `locales/` for extension, `webview-ui/src/i18n/` for UI +- Provider examples in `src/api/providers/` are canonical reference (docs may be outdated) +- Webview runs in VSCode context with restrictions (no localStorage, limited browser APIs) diff --git a/.roo/rules-code/AGENTS.md b/.roo/rules-code/AGENTS.md index ee1d428265..080bac7be0 100644 --- a/.roo/rules-code/AGENTS.md +++ b/.roo/rules-code/AGENTS.md @@ -1,39 +1,10 @@ # Code Mode Rules -## JSON File Operations +## Critical Non-Obvious Patterns -- **MANDATORY**: Use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes -- Never use `JSON.stringify` with direct file writes - always use `safeWriteJson` -- `safeWriteJson` handles directory creation, atomic writes, and locking automatically - -## Provider Implementation - -- All new providers MUST implement the Provider interface from `packages/types/src/` -- Provider implementations go in `src/api/providers/` -- Each provider needs proper error handling and retry mechanisms - -## UI Component Guidelines - -- Use Tailwind CSS classes exclusively - no inline styles +- **MANDATORY**: Use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes (prevents corruption via atomic writes with locking) +- Tests MUST run from workspace directory: `cd src && npx vitest run` (NOT from root) - VSCode CSS variables must be added to `webview-ui/src/index.css` before use -- React components use functional components with hooks -- State management via React hooks, not external state libraries - -## Testing Requirements - -- All new features require test coverage -- Tests use vitest framework (vi, describe, test, it are global) -- Run tests from workspace directory: `cd src && npx vitest run` -- Never run tests from project root - -## IPC Communication - -- Use packages/ipc for webview ↔ extension communication -- Messages must be typed using interfaces from packages/types -- Handle all async operations with proper error boundaries - -## File Restrictions - -- Code mode can edit all file types -- Always verify file exists before operations -- Use proper file locking for concurrent access safety +- State management via React hooks only (external state libraries break webview isolation) +- Providers MUST be stateless (hidden caching layer assumes this) +- Import paths in packages/ require `.js` extensions despite TypeScript source diff --git a/.roo/rules-debug/AGENTS.md b/.roo/rules-debug/AGENTS.md index 645eb93b2b..ba25e01efc 100644 --- a/.roo/rules-debug/AGENTS.md +++ b/.roo/rules-debug/AGENTS.md @@ -1,40 +1,13 @@ # Debug Mode Rules -## Debugging Entry Points +## Non-Obvious Debug Access -- VSCode Debug Console shows extension logs via `outputChannel` -- Webview DevTools accessible via Command Palette → "Developer: Open Webview Developer Tools" -- Extension host debugging: Press F5 to launch new VSCode window with extension loaded +- Webview DevTools: Command Palette → "Developer: Open Webview Developer Tools" (NOT F12) +- Extension logs: VSCode Output panel → "Roo Code" channel +- Extension Host output channel shows different logs than Debug Console -## Common Debug Patterns +## Critical Debug Patterns -- Provider issues: Check `src/api/providers/__tests__/` for test patterns -- IPC communication: Review `packages/ipc/src/` for message flow -- Webview state issues: Check React DevTools in webview developer tools -- Extension activation: Review `src/extension.ts` and `src/activate/` - -## Log Locations - -- Extension logs: VSCode Output panel → "Roo Code" -- Terminal command logs: Check TerminalRegistry in `src/integrations/terminal/` -- MCP server logs: Check McpServerManager output -- Cloud service logs: Check CloudService initialization in extension.ts - -## Testing Debug Workflow - -1. Add console.log or debugger statements -2. Run tests with: `cd src && npx vitest run --reporter=verbose` -3. For UI tests: `cd webview-ui && npx vitest run --reporter=verbose` -4. Use VSCode's built-in debugger for stepping through code - -## Performance Debugging - -- Memory issues: Check for proper cleanup in `deactivate()` function -- Slow operations: Profile with Chrome DevTools for webview -- Extension performance: Use VSCode's Extension Host profiler - -## Error Handling - -- All async operations should have try-catch blocks -- Errors should be logged to outputChannel -- Critical errors should provide user-friendly messages via vscode.window.showErrorMessage +- IPC messages fail silently without try/catch in `packages/ipc/src/` +- Tests MUST run from workspace directory: `cd src && npx vitest run` +- Webview runs in restricted context (no localStorage, limited browser APIs) diff --git a/AGENTS.md b/AGENTS.md index 53e901fd09..e575973371 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,64 +2,20 @@ This file provides guidance to agents when working with code in this repository. -## Project Overview +## Critical Non-Obvious Patterns -Roo Code - AI-powered autonomous coding agent VSCode extension with React webview UI, supporting multiple AI providers and custom modes. +- **JSON Writes**: MUST use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes (atomic writes with locking, handles streaming) +- **Test Execution**: Tests MUST run from workspace directory: `cd src && npx vitest run` or `cd webview-ui && npx vitest run` (NOT from root) +- **Import Extensions**: Use `.js` extensions in packages/ imports despite TypeScript source files +- **Bootstrap**: `pnpm install` auto-bootstraps via `scripts/bootstrap.mjs` if pnpm not found +- **Webview DevTools**: Access via Command Palette → "Developer: Open Webview Developer Tools" (not F12) +- **VSCode CSS Variables**: Must be added to `webview-ui/src/index.css` before use in components +- **React Hooks Required**: External state libraries break webview isolation - use React hooks only +- **noUncheckedIndexedAccess**: TypeScript strict mode with this enabled - array/object access may return undefined -## Build/Test/Lint Commands +## Architecture Gotchas -```bash -# Install dependencies (from root) -pnpm install - -# Build entire project -pnpm build - -# Run tests (CRITICAL: run from workspace directory containing package.json) -cd src && npx vitest run tests/user.test.ts # Backend tests -cd webview-ui && npx vitest run src/components/Button.test.tsx # UI tests - -# Lint/format -pnpm lint -pnpm format -``` - -## Code Style - -- **Formatting**: Tabs (4 width), 120 char lines, no semicolons, bracket same line -- **Imports**: ESM modules, use `.js` extensions in packages/ -- **Types**: TypeScript strict mode, `noUncheckedIndexedAccess: true` -- **Naming**: camelCase functions/variables, PascalCase components/classes -- **UI**: Tailwind CSS classes only (no inline styles), VSCode CSS vars via webview-ui/src/index.css - -## Architecture - -``` -src/ # VSCode extension backend (TypeScript) -├── extension.ts # Entry point, registers providers & commands -├── api/providers/ # AI provider implementations -├── core/webview/ # Webview provider & IPC -└── utils/ # Utilities (MUST use safeWriteJson for JSON writes) - -webview-ui/ # React frontend -├── src/components/ # React components with Tailwind CSS -└── src/hooks/ # Custom React hooks - -packages/ # Shared packages -├── types/ # Shared TypeScript types -├── ipc/ # IPC communication layer -└── evals/ # Evaluation framework -``` - -## Critical Patterns - -- **JSON Writes**: ALWAYS use `safeWriteJson()` from src/utils/safeWriteJson.ts (atomic writes with locking) -- **Testing**: Run vitest from workspace directory containing package.json, NOT from project root -- **Providers**: Implement Provider interface from packages/types/src/ -- **Webview**: VSCode webview architecture with IPC messaging between extension and UI - -## Development - -- **Debug**: Press F5 in VSCode to launch extension host -- **Hot Reload**: Webview changes appear immediately, core changes auto-reload in dev mode -- **VSIX**: `pnpm vsix` to build, `pnpm install:vsix` to install locally +- `src/` contains VSCode extension backend (not generic source) +- `webview-ui/` is React frontend in VSCode webview (restricted APIs, no localStorage) +- IPC messages between extension/webview must use typed interfaces from `packages/types` +- Provider implementations must be stateless (hidden caching layer assumes this)