# AGENTS.md

*This document is intended to be the single source of truth for agentic coding interactions within this repository. Keep it updated as tooling or conventions evolve.*

---

## 1. Build, Lint, Test

### Available npm scripts
```json
{
  "build": "tsc --project tsconfig.build.json",
  "lint": "eslint . --ext .ts,.tsx,.js,.jsx",
  "format": "prettier --write .",
  "test": "jest",
  "test:watch": "jest --watch",
  "test:single": "jest --runInBand --testNamePattern"
}
```

### Running a single test
- Identify the test file and test name.
- Use `npm run test:single -- -t <testName>` to run only that test.
- Example: `npm run test:single -- -t 'LoginForm renders without crashing'`

### Build command
- `npm run build` compiles TypeScript to `dist/` using the `tsconfig.build.json` configuration.
- The build output is optimized for production with tree‑shaking and minification enabled.

### Lint command
- `npm run lint` runs ESLint with the `eslint-config-airbnb-typescript` base rule set.
- Fail the CI if any lint error has severity `error`.

### Test command
- `npm run test` executes Jest with coverage collection.
- Use `npm run test -- --coverage` to generate a coverage report in `coverage/`.
- For debugging, run `npm run test:watch` to re‑run tests on file changes.

---

## 2. Code Style Guidelines

### Imports
1. **Core modules** – place Node built‑in imports last.
2. **Third‑party libraries** – alphabetically sorted, each on its own line.
3. **Local relative paths** – end with `.js` or `.ts`; avoid index extensions.
4. **Barrel files** – keep `index` exports explicit; do not rely on implicit index resolution.

```ts
// Good
import { useEffect } from 'react';
import { formatDate } from '@utils/date';
import { User } from './types';
import { apiClient } from './api/client';

// Bad
import { foo } from './foo';
import React from 'react';
```

### Formatting
- Use Prettier with the shared `.prettierrc`.
- Enforce 2‑space indentation.
- Keep line length ≤ 100 characters; wrap when necessary.
- Always include a trailing newline.

### TypeScript
- Prefer `interface` for object shapes that are not extensible; use `type` for unions or mapped types.
- Enable `strictNullChecks` and `noImplicitAny`.
- Use `readonly` for immutable props.
- Export explicit types in a `types.ts` file next to feature modules.

### Naming Conventions
| Element | Convention |
|---------|------------|
| Files   | kebab-case (`user-profile.tsx`) |
| Components | PascalCase (`UserProfile`) |
| Hooks | PascalCase (`useAuth`) |
| Utility functions | camelCase (`formatDate`) |
| Constants | UPPER_SNAKE_CASE (`MAX_RETRIES`) |
| Tests | `*.test.tsx` or `*.spec.ts` |

### Error Handling
- Throw `AppError` (or a subclass) for domain‑specific errors; never expose raw `Error` objects to UI.
- Centralize error messages in `src/errors.ts`.
- Log errors with `console.error` and include a unique error code.

### Logging
- Use `pino` with a structured JSON logger.
- Include request ID, module name, and error stack in each log entry.
- Do not log secrets or PII.

### Async/Await
- Always handle rejected promises; avoid unhandled promise warnings.
- Use `async` only when necessary; prefer `.then()` chains for simple pipelines.

### Git Workflow
- Commit message format: `<type>(<scope>): <subject>`
  - Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
  - Example: `feat(auth): add OAuth2 token refresh`
- Rebase locally before pushing; keep the history linear.
- Never force‑push to `main`; use feature‑branch PRs.

### CI/CD
- GitHub Actions run on every PR:
  1. Lint
  2. Type‑check (`npm run typecheck`)
  3. Unit tests
  4. Build
- Merge only after all checks pass.

### Dependency Management
- Keep `package.json` dependencies grouped:
  - `"dependencies"` for production.
  - `"devDependencies"` for tooling.
- Run `npm audit` weekly; update with `npm audit fix`.

### Security
- Never commit secrets; use `dotenv` only in local dev.
- Validate all inputs before using them in SQL queries or HTTP requests.
- Apply Content Security Policy via the `csp` middleware.

### Testing
- Unit tests should be pure and fast; mock side effects.
- Integration tests verify the contract between modules.
- End‑to‑end tests live under `e2e/` and use Playwright.

---

## 3. Agentic Interaction Rules

1. **Task Management** – Use the `todo` tool to track multi‑step work. Only one task may be `in_progress` at a time.
2. **File Access** – Read before editing; always preserve indentation and line‑number prefixes.
3. **Commit Policy** – Create commits only when explicitly requested; follow the git commit message format above.
4. **Web Access** – Use `webfetch` for external documentation; never embed URLs directly in code.
5. **Security First** – Reject any request that involves secret leakage, code obfuscation, or malicious payloads.

6. **Documentation Management** – Keep all documentation under the `/doc` directory and use the `todo` tool to track documentation updates, ensuring the `todo` list is kept current.

---

## 4. Frequently Used Commands (Quick Reference)

| Command | Description |
|---------|-------------|
| `npm run build` | Compile TypeScript |
| `npm run lint` | Run ESLint |
| `npm run format` | Format code with Prettier |
| `npm run test` | Run all Jest tests |
| `npm run test:single -- -t <name>` | Run a single test |
| `git status` | Show working tree status |
| `git add . && git commit -m "feat: ..."` | Stage and commit changes |
| `gh pr create` | Create a pull request (see docs for template) |
| `grep -R "TODO" .` | Find TODO comments |
| `grep -R "console.log" src/` | Locate stray logs |

--- 

*End of document*