winterfail/AGENTS.md

# AGENTS.md

## 1. Build, Lint, and Test Commands

### 1.1 Build
- **Development build**: `npm run build:dev`
  - Compiles source files with source maps enabled.
  - Output directory: `dist/`.
- **Production build**: `npm run build:prod`
  - Optimized bundle, minified assets, no source maps.
  - Output directory: `dist/`.
- **Watch mode**: `npm run build:watch`
  - Rebuilds on file changes; useful during active development.

### 1.2 Lint
- **ESLint**: `npm run lint`
  - Runs ESLint over all `src/**/*.js` and `src/**/*.ts`.
  - Fails on any error with exit code `1`.
- **Prettier**: `npm run format`
  - Checks for formatting violations without fixing them.
  - Use `npm run format:fix` to automatically format all files.

### 1.3 Test
- **Full test suite**: `npm test`
  - Executes all Jest test files (`**/__tests__/**/*.js`).
- **Run a single test**: `npm test -- <testFilePath>`
  - Example: `npm test -- src/__tests__/utils/format.test.js`
  - Runs only the specified test file, preserving test isolation.
- **Coverage**: `npm run coverage`
  - Generates an Istanbul coverage report in `coverage/`.

### 1.4 Common npm Scripts (add to `package.json` if missing)
```json
{
  "scripts": {
    "build:dev": "webpack --mode development",
    "build:prod": "webpack --mode production",
    "build:watch": "webpack --watch",
    "lint": "eslint src/**/*.js",
    "format": "prettier --check src/**/*.js",
    "format:fix": "prettier --write src/**/*.js",
    "test": "jest",
    "coverage": "jest --coverage"
  }
}
```

---

## 2. Code Style Guidelines

### 2.1 File Organization
- Keep related components, utilities, and hooks in feature‑specific directories.
- Use index files (`index.js`) to re‑export public APIs from each folder.

### 2.2 Imports
- **Named imports only** when possible:
  ```js
  import { foo, bar } from './utils';
  ```
- **Default imports** only for modules that expose a default export:
  ```js
  import defaultFn from './default';
  ```
- **Relative paths** (`./`, `../`) must be used; no root‑path shortcuts.

### 2.3 Formatting
- **Indent**: 2 spaces, no tabs.
- **Quotes**: Prefer single quotes (`'`) for strings.
- **Semicolons**: Optional but encouraged for consistency.
- **Line length**: Limit to 100 characters; wrap when exceeded.
- **Trailing commas**: Use in object/array literals.

### 2.4 Naming Conventions
- **Variables / Functions**: `camelCase`.
- **Classes**: `PascalCase`.
- **Constants**: `UPPER_SNAKE_CASE`.
- **File names**: kebab-case for CSS, snake_case for utility modules.
- **Test files**: suffix with `.test.js` or `.spec.js`.

### 2.5 TypeScript (if used)
- Enable `strict` mode in `tsconfig.json`.
- Prefer `interface` for object shapes; use `type` only for unions or conditional types.
- Export types explicitly when they are part of a public API.

### 2.6 Error Handling
- **Synchronous**: Throw descriptive `Error` objects.
- **Asynchronous**: Return rejected promises or use `try/catch` with custom error classes.
- **Logging**: Use `console.error` for runtime errors; include context (e.g., `error.message + ' at ' + stack`).

### 2.7 Async/Await
- Always handle rejected promises; avoid unhandled promise warnings.
- Prefer `await` over `.then()` chains for readability.

### 2.8 Dependency Management
- Keep third‑party imports at the top of the file.
- Avoid direct use of global Node APIs (`process`, `__dirname`) unless wrapped in utility functions.
- Pin versions in `package.json`; run `npm audit` regularly.

### 2.9 Testing Conventions
- **Arrange**: Setup → Exercise → Verify.
- **Describe**: Use `describe` blocks for logical groups.
- **It**: Use `it` with a clear, past‑tense description.
- **BeforeEach / AfterEach**: Clean up mocks and state.

---

## 3. Project‑Specific Rules

### 3.1 Cursor Rules
- No `.cursor` configuration detected in the repository. If you add a `.cursor` folder, include:
  - `cursor.json` with `"maxLineLength": 100`
  - `"preferTabs": false`
  - `"tabWidth": 2`

### 3.2 Copilot Instructions
- No `.github/copilot-instructions.md` found. If you create one, place:
  - `rules` section outlining PR checklist.
  - `codeowners` snippet if needed.

### 3.3 Commit Message Style
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, etc.).
- Body should explain **why** the change was made, not just **what**.

### 3.4 Dependency Updates
- Run `npm outdated` before any major version bump.
- Update `package-lock.json` and run `npm install` to ensure reproducibility.

---

## 4. Utility Scripts

### 4.1 Clean Build Artifacts
```bash
# Remove generated files
rm -rf dist/ coverage/ node_modules/
```

### 4.2 Reset Lint Cache
```bash
# Clear ESLint cache to force re‑lint
rm -rf .eslintcache
```

### 4.3 Generate Documentation (if used)
```bash
# Assuming JSDoc is configured
jsdoc -c jsdoc.conf.json -r src/ -o docs/
```

---

## 5. FAQ

**Q:** *How do I run a single test without the whole suite?*  
**A:** `npm test -- path/to/single.test.js`

**Q:** *Where should I add new utility functions?*  
**A:** Place them in `src/utils/` with a descriptive filename and export via `index.js`.

**Q:** *What is the preferred way to handle environment variables?*  
**A:** Store them in `.env.local` and access via `process.env.VAR_NAME`. Do not commit `.env*` files.

---

*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.*