# CLAUDE.md

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

## Common Development Commands

### Build & Development

- `npm install` - Install dependencies
- `npm run compile` - Compile TypeScript to JavaScript (outputs to dist/)
- `npm run watch` - Watch mode for TypeScript compilation
- `npm run clean` - Clean build artifacts

### Testing & Quality

- `npm test` - Run all tests (includes linting and compilation)
- `npm run lint` - Run ESLint on TypeScript source files
- `npm run fmt` - Format code with Prettier
- `mocha dist/**/*.spec.js` - Run specific test files after compilation
- `npx mocha --require tsx src/Object.spec.ts` - Run individual tests like this

### Documentation

- `npm run docs` - Generate and serve TypeDoc documentation

## Architecture Overview

This library manages clusters of child processes to efficiently handle batch operations through stdin/stdout communication. Key architectural concepts:

### Core Components

1. **BatchCluster** (`src/BatchCluster.ts`) - Main entry point that manages a pool of child processes
   - Handles process lifecycle, task queuing, and load balancing
   - Monitors process health and automatically recycles processes
   - Emits events for monitoring and debugging

2. **BatchProcess** (`src/BatchProcess.ts`) - Wrapper around individual child processes
   - Manages communication with a single child process
   - Tracks process state, health, and task processing
   - Handles process recycling based on task count or runtime

3. **Task** (`src/Task.ts`) - Represents a unit of work to be processed
   - Contains the command to send to child process
   - Includes parser for processing responses
   - Manages timeouts and completion promises

### Key Patterns

- **Parser Interface** - Consumers must implement parsers to handle child process output
- **Deferred Pattern** - Used extensively for promise-based task completion
- **Rate Monitoring** - Tracks error rates to prevent runaway failures
- **Process Recycling** - Automatic process replacement after N tasks or N seconds

### Testing Approach

The test suite uses a custom test script (`src/test.ts`) that simulates a batch-mode command-line tool with configurable failure rates. Tests can control:

- `failrate` - Probability of task failure
- `rngseed` - Seed for deterministic randomness
- `ignoreExit` - Whether to ignore termination signals

## TypeScript Configuration

- Strict mode enabled with all strict checks
- Targets ES2019, CommonJS modules
- Outputs to `dist/` with source maps and declarations
- No implicit any, strict null checks, no unchecked indexed access

## Code Style Guidelines

- **Null checks**: Always use explicit `x == null` or `x != null` checks. Do not use falsy/truthy checks for nullish values.
  - Good: `if (value != null)`, `if (value == null)`
  - Bad: `if (value)`, `if (!value)`

## Technical Project Plans (TPP)

Use TPPs for non-trivial work. Before starting any TPP, read:

- **[doc/TPP-GUIDE.md](doc/TPP-GUIDE.md)** — How to write and execute TPPs
- **[doc/SIMPLE-DESIGN.md](doc/SIMPLE-DESIGN.md)** — Kent Beck's Four Rules of Simple Design
- **[doc/TDD.md](doc/TDD.md)** — Bug fixes must start with a failing test

TPP workflow:

- Active TPPs live in `doc/todo/` (e.g., `P01-fix-task-timeout.md`)
- Completed TPPs move to `doc/done/` with date prefix (e.g., `20260208-P01-fix-timeout.md`)
- Use `/tpp <path>` to resume work on a TPP
- Use `/handoff [path]` to save progress before ending a session

## Verification Requirements

**CRITICAL**: Never reference URLs, APIs, features, libraries, or external resources without verification. Always:

1. **Verify before including**: Use web search and authoritative documentation to confirm that URLs, API endpoints, issue references, and feature names actually exist
2. **Check the codebase**: Read relevant source files to verify that features, methods, or properties are actually implemented
3. **When in doubt, omit**: If you cannot verify a reference, leave it out rather than including potentially incorrect information
4. **Question existing content**: Don't blindly preserve URLs or references from existing files - verify they are correct before keeping them

This applies to:

- GitHub issue URLs and references
- API documentation links
- Feature names and capabilities
- Library versions and compatibility claims
- External service endpoints
