8828edf647
Replace prop drilling with React context providers. App.tsx shrinks from 427 lines to ~80 lines of pure layout. Components consume shared state directly via 7 context providers instead of threading 50+ props. Key changes: - 7 context providers wrapping existing hooks (encounter, bestiary, player characters, side panel, theme, bulk import, initiative rolls) - 2 coordinating hooks extracted from App.tsx (useInitiativeRolls, useAutoStatBlock) - All 9 affected components refactored from prop-based to context-based - 6 test files updated to use providers or context mocks - Prop count enforcement script (max 8 per component interface) - Constitution principle II-A added (context-based state flow) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
134 lines
8.0 KiB
Markdown
134 lines
8.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
pnpm check # Merge gate — must pass before every commit (audit + knip + biome + oxlint + typecheck + test/coverage + jscpd)
|
|
pnpm oxlint # Type-aware linting (oxlint — complements Biome)
|
|
pnpm knip # Unused code detection (Knip)
|
|
pnpm test # Run all tests (Vitest)
|
|
pnpm test:watch # Tests in watch mode
|
|
pnpm typecheck # tsc --build (project references)
|
|
pnpm lint # Biome lint
|
|
pnpm format # Biome format (writes)
|
|
pnpm check:props # Component prop count enforcement (max 8)
|
|
pnpm --filter web dev # Vite dev server (localhost:5173)
|
|
pnpm --filter web build # Production build
|
|
```
|
|
|
|
Run a single test file: `pnpm vitest run packages/domain/src/__tests__/advance-turn.test.ts`
|
|
|
|
## Architecture
|
|
|
|
Strict layered architecture with ports/adapters and enforced dependency direction:
|
|
|
|
```
|
|
apps/web (React 19 + Vite) → packages/application (use cases) → packages/domain (pure logic)
|
|
```
|
|
|
|
- **Domain** — Pure functions, no I/O, no framework imports. All state transitions are deterministic. Errors returned as values (`DomainError`), never thrown. Adapters may throw only for programmer errors.
|
|
- **Application** — Orchestrates domain calls via port interfaces (`EncounterStore`, `BestiarySourceCache`). No business logic here.
|
|
- **Web** — React adapter. Implements ports using hooks/state. All UI components, routing, and user interaction live here.
|
|
|
|
Layer boundaries are enforced by `scripts/check-layer-boundaries.mjs`, which runs as a Vitest test. Domain and application must never import from React, Vite, or upper layers.
|
|
|
|
### Data & Storage
|
|
|
|
- **localStorage** — encounter persistence (adapter layer, JSON serialization)
|
|
- **IndexedDB** — bestiary source cache (`apps/web/src/adapters/bestiary-cache.ts`, via `idb` wrapper)
|
|
- **`data/bestiary/index.json`** — pre-built search index for creature lookup, generated by `scripts/generate-bestiary-index.mjs`
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
apps/web/ React app — components, hooks, adapters
|
|
packages/domain/src/ Pure state transitions, types, validation
|
|
packages/application/src/ Use cases, port interfaces
|
|
data/bestiary/ Bestiary search index
|
|
scripts/ Build tooling (layer checks, index generation)
|
|
specs/NNN-feature-name/ Feature specs (spec.md, plan.md, tasks.md)
|
|
.specify/ Speckit config (templates, scripts, constitution)
|
|
docs/agents/ RPI skill artifacts (research reports, plans)
|
|
.claude/skills/ Agent skills (rpi-research, rpi-plan, rpi-implement)
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
- TypeScript 5.8 (strict mode, `verbatimModuleSyntax`)
|
|
- React 19, Vite 6, Tailwind CSS v4
|
|
- Lucide React (icons)
|
|
- `idb` (IndexedDB wrapper for bestiary cache)
|
|
- Biome 2.4 (formatting + linting), oxlint (type-aware linting), Knip (unused code), jscpd (copy-paste detection)
|
|
- Vitest (testing, v8 coverage), Lefthook (pre-commit hooks)
|
|
|
|
## Conventions
|
|
|
|
- **Biome 2.4** for formatting and linting (no Prettier, no ESLint). Tab indentation, 80-char lines. Imports are auto-organized alphabetically.
|
|
- **oxlint** for type-aware linting that Biome can't do (unnecessary type assertions, deprecated APIs, `replaceAll` preference, `String.raw`). Configured in `.oxlintrc.json`.
|
|
- **TypeScript strict mode** with `verbatimModuleSyntax`. Use `.js` extensions in relative imports when required by the repo's ESM settings (e.g., `./types.js`).
|
|
- **Branded types** for identity values (e.g., `CombatantId`). Prefer immutability/`readonly` where practical.
|
|
- **Domain events** are plain data objects with a `type` discriminant — no classes.
|
|
- **Tests** live in `packages/*/src/__tests__/*.test.ts`. Test pure functions directly; map acceptance scenarios and invariants from specs to individual `it()` blocks.
|
|
- **Feature specs** live in `specs/NNN-feature-name/` with spec.md (and optionally plan.md, tasks.md for new work). Specs describe features, not individual changes. The project constitution is at `.specify/memory/constitution.md`.
|
|
- **Component props** — max 8 explicitly declared props per component interface (enforced by `scripts/check-component-props.mjs`). Use React context for shared state; reserve props for per-instance config (data items, layout variants, refs).
|
|
- **Quality gates** are enforced at pre-commit via Lefthook's `pnpm check` — the project's single earliest enforcement point. No gate may exist only as a CI step or manual process.
|
|
|
|
## Self-Review Checklist
|
|
|
|
Before finishing a change, consider:
|
|
- Is this the simplest approach that solves the current problem?
|
|
- Is there duplication that hurts readability? (But don't abstract prematurely.)
|
|
- Are errors handled correctly and communicated sensibly to the user?
|
|
- Does the UI follow modern patterns and feel intuitive to interact with?
|
|
|
|
## Speckit Workflow
|
|
|
|
Speckit (`/speckit.*` skills) manages the spec-driven development pipeline. Specs are **living documents** that describe features, not individual changes.
|
|
|
|
### Issue-driven workflow
|
|
- `/write-issue` — create a well-structured Gitea issue via interactive interview
|
|
- `/integrate-issue <number>` — fetch an issue, route it to the right spec, and update the spec with the new/changed requirements. Then implement directly.
|
|
- `/sync-issue <number>` — push acceptance criteria from the spec back to the Gitea issue
|
|
|
|
### RPI skills (Research → Plan → Implement)
|
|
- `rpi-research` — deep codebase research producing a written report in `docs/agents/research/`
|
|
- `rpi-plan` — interactive phased implementation plan in `docs/agents/plans/`
|
|
- `rpi-implement` — execute a plan file phase by phase with automated + manual verification
|
|
|
|
### Choosing the right workflow by scope
|
|
|
|
| Scope | Workflow |
|
|
|---|---|
|
|
| Bug fix / CSS tweak | Just fix it, commit |
|
|
| Small change to existing feature | `/integrate-issue` → implement → commit |
|
|
| Larger addition to existing feature | `/integrate-issue` → `rpi-research` → `rpi-plan` → `rpi-implement` |
|
|
| New feature | `/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement` |
|
|
|
|
Speckit manages **what** to build (specs as living documents). RPI manages **how** to build it (research, planning, execution). The full speckit pipeline is for new features. For changes to existing features, update the spec via `/integrate-issue`, then use RPI skills if the change is non-trivial.
|
|
|
|
### Current feature specs
|
|
- `specs/001-combatant-management/` — CRUD, persistence, clear, batch add, confirm buttons
|
|
- `specs/002-turn-tracking/` — rounds, turn order, advance/retreat, top bar
|
|
- `specs/003-combatant-state/` — HP, AC, conditions, concentration, initiative
|
|
- `specs/004-bestiary/` — search index, stat blocks, source management, panel UX
|
|
- `specs/005-player-characters/` — persistent player character templates (CRUD), search & add to encounters, color/icon visual distinction, `PlayerCharacterStore` port
|
|
|
|
## Constitution (key principles)
|
|
|
|
The constitution (`.specify/memory/constitution.md`) governs all feature work:
|
|
|
|
1. **Deterministic Domain Core** — Pure state transitions only; no I/O, randomness, or clocks in domain.
|
|
2. **Layered Architecture** — Domain → Application → Adapters. Never skip layers or reverse dependencies.
|
|
3. **Clarification-First** — Ask before making non-trivial assumptions.
|
|
4. **MVP Baseline** — Say "MVP baseline does not include X", never permanent bans.
|
|
5. **Spec-driven features** — Features are described in living specs; evolve existing specs via `/integrate-issue`, create new ones via `/speckit.specify`. Bug fixes and tooling changes do not require specs.
|
|
|
|
## Active Technologies
|
|
- TypeScript 5.8 (strict mode, `verbatimModuleSyntax`) + React 19, Vite 6, Tailwind CSS v4, Lucide Reac (005-player-characters)
|
|
- localStorage (new key `"initiative:player-characters"`) (005-player-characters)
|
|
|
|
## Recent Changes
|
|
- 005-player-characters: Added TypeScript 5.8 (strict mode, `verbatimModuleSyntax`) + React 19, Vite 6, Tailwind CSS v4, Lucide Reac
|