winterfail/AGENTS.md

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

{
  "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.

// 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