# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Quick Start

```bash
grunt              # Development build
grunt prod         # Production build
npm test           # Run all tests (unit + integration)
grunt eslint       # Lint code (run after completing tasks)
grunt eslint --fix # Auto-fix linting issues
```

## Command Reference

### Build & Distribution
| Command | Description | Output |
|---------|-------------|--------|
| `grunt` | Development build | `build/` |
| `grunt prod` | Production build | `build/` |
| `grunt watch` | Auto-rebuild on changes | `build/` |
| `grunt clean` | Clean build directories | - |
| `grunt dist-cr` | Chrome extension package | `dist/mailvelope.chrome.zip` |
| `grunt dist-ff` | Firefox extension package | `dist/mailvelope.firefox.zip` |

### Testing
| Command | Description |
|---------|-------------|
| `npm test` | Run all tests |
| `npm run test:unit` | Jest unit tests only |
| `npm run test:integration` | Puppeteer integration tests |
| `npm run test:jest:watch` | Watch mode |
| `npm run test:jest:coverage` | Coverage report |

### Test Execution Examples
```bash
# Specific test file
npm test -- path/to/test.js

# Pattern matching
npm test -- --testNamePattern="should render"
npm test -- --testPathPatterns="unit/components"
```

## Project Structure

### Core Directories
- `src/` - Source code
  - `background.js` - Extension entry point (Chrome: service worker)
  - `controller/` - MVC controllers (inherit from `sub.controller.js`)
  - `content-scripts/` - Page injection scripts
  - `modules/` - Core modules (keyring, pgpModel)
  - `components/` - React UI components
  - `client-API/` - Public API for web apps
  - `lib/offscreen/` - Chrome service worker workarounds
- `config/` - Webpack & build configurations
- `test/` - Test suites (unit, integration, legacy)
- `locales/` - i18n files (14 languages)

### Build Outputs
- `build/chrome/`, `build/firefox/` - Development builds
- `dist/` - Production packages (.zip files)

## Completion Criteria

**A task is only completed when:**
1. All tests pass (`npm test`)
2. No ESLint errors or warnings (`grunt eslint`)

If either fails, the task is incomplete.

## Architecture Overview

### Communication Pattern
- **Port-based messaging** between extension contexts
- **EventHandler** module manages cross-component communication
- **Frame isolation** for security (UI components in iframes)

### Key Components
1. **Background Script** - Main extension logic, keyring management
2. **Controllers** - Feature-specific controllers with permission checks
3. **Content Scripts** - Web page integration and frame injection
4. **React Components** - UI with Bootstrap 4.6.2 styling

### Build System
- **Grunt** orchestrates the build process
- **Webpack** multi-config for different contexts
- Separate manifests for Chrome/Firefox

## Coding Standards

### JavaScript Style
- ES2022 features preferred
- `async/await` over Promise chains
- Arrow functions for anonymous functions
- Optional chaining (`?.`) and nullish coalescing (`??`)
- `for...of` loops preferred
- Method shorthand in objects
- NO trailing spaces
- NO empty lines inside function bodies
- File must end with newline

### EditorConfig Requirements
- Line endings: Unix (LF)
- Encoding: UTF-8
- Indentation: 2 spaces
- Final newline: required

### Code Quality
- Remove unused variables
- Function declarations for top-level functions
- Prefer `!` for nullish/falsy checks
- Follow existing patterns and conventions

## Critical Patterns

### Security Requirements
- Never expose or log secrets/keys
- Never commit secrets to repository
- Strict CSP implementation
- Permission checks in controller factory

### Chrome Service Worker
Background script runs in service worker context with limitations. Use offscreen document pattern when needed.

## Common Pitfalls

1. **Missing async/await** - Always use for asynchronous operations
3. **Forgetting lint** - Always run `grunt eslint` before completion
4. **Creating new files** - Prefer editing existing files

## Testing
Refer to `./test/CLAUDE.md` for comprehensive testing guidelines.

## Additional Resources
- Node.js 20+ and npm 10+ required
