260 lines
8 KiB
Markdown
260 lines
8 KiB
Markdown
# BeadBoard Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Build a Windows-native Beads dashboard that reads `.beads/issues.jsonl` directly and performs all mutations through `bd.exe`.
|
|
|
|
**Architecture:** The app uses Next.js App Router APIs for filesystem reads, project scanning, watcher lifecycle, SSE broadcasting, and CLI mutation bridging. Frontend uses React Query for server-state synchronization and Zustand for UI-local state plus optimistic transition coordination. Windows path normalization is centralized and enforced at all boundaries to prevent cross-drive and casing inconsistencies.
|
|
|
|
**Tech Stack:** Next.js 15, React 19, TypeScript (strict), Tailwind CSS, Zustand, TanStack Query, chokidar, React Flow, `child_process.execFile`.
|
|
|
|
---
|
|
|
|
### Task 1: Repository Bootstrap and Runtime Guardrails
|
|
|
|
**Files:**
|
|
- Create: `package.json`
|
|
- Create: `tsconfig.json`
|
|
- Create: `next.config.ts`
|
|
- Create: `LICENSE`
|
|
- Create: `src/app/layout.tsx`
|
|
- Create: `src/app/page.tsx`
|
|
|
|
**Step 1: Write failing environment checks**
|
|
- Add a smoke test placeholder for app boot and runtime config verification.
|
|
|
|
**Step 2: Run verification to confirm missing implementation**
|
|
- Run: `npm run test` (expected to fail before setup).
|
|
|
|
**Step 3: Implement minimal app bootstrap**
|
|
- Initialize Next.js 15 + React 19 + TypeScript strict setup.
|
|
- Add MIT license file.
|
|
|
|
**Step 4: Re-run checks**
|
|
- Run: `npm run lint` and `npm run typecheck`.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `chore: bootstrap beadboard foundation`
|
|
|
|
### Task 2: Canonical Types and JSONL Parser
|
|
|
|
**Files:**
|
|
- Create: `src/lib/types.ts`
|
|
- Create: `src/lib/parser.ts`
|
|
- Create: `tests/lib/parser.test.ts`
|
|
|
|
**Step 1: Write failing parser tests**
|
|
- Cover defaults, malformed lines, tombstone filtering, `priority=0` preservation.
|
|
|
|
**Step 2: Run targeted test**
|
|
- Run: `npm run test -- tests/lib/parser.test.ts` (expected fail).
|
|
|
|
**Step 3: Implement parser + DTO normalization**
|
|
- Parse one JSON object per line, skip malformed lines, apply defaults.
|
|
|
|
**Step 4: Run tests**
|
|
- Run parser tests and full typecheck.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `feat: add beads schema and robust jsonl parser`
|
|
|
|
### Task 3: Windows Pathing + Project Registry
|
|
|
|
**Files:**
|
|
- Create: `src/lib/pathing.ts`
|
|
- Create: `src/lib/projects-registry.ts`
|
|
- Create: `src/app/api/projects/route.ts`
|
|
- Test: `tests/lib/pathing.test.ts`
|
|
|
|
**Step 1: Write failing path tests**
|
|
- Validate canonicalization for `C:\` and `D:\`, stable key generation.
|
|
|
|
**Step 2: Implement path utility + registry persistence**
|
|
- Use `%USERPROFILE%\\.beadboard\\projects.json` as registry location.
|
|
|
|
**Step 3: Implement API route**
|
|
- Support add/list/remove with validation and normalized identity.
|
|
|
|
**Step 4: Verify**
|
|
- Run path tests + API handler tests.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `feat: add windows path normalization and project registry`
|
|
|
|
### Task 4: Read API and Multi-Project Aggregation
|
|
|
|
**Files:**
|
|
- Create: `src/app/api/beads/route.ts`
|
|
- Create: `src/lib/read-service.ts`
|
|
- Test: `tests/api/beads-route.test.ts`
|
|
|
|
**Step 1: Write failing API tests**
|
|
- Single project read, aggregate read, filter params, error behavior.
|
|
|
|
**Step 2: Implement read service**
|
|
- Read `.beads/issues.jsonl` directly via `fs`.
|
|
|
|
**Step 3: Implement route layer**
|
|
- Query support for project, status, type, priority, assignee, label.
|
|
|
|
**Step 4: Verify**
|
|
- Run route tests and typecheck.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `feat: add beads read api for single and aggregate views`
|
|
|
|
### Task 5: Scanner and Discovery Controls
|
|
|
|
**Files:**
|
|
- Create: `src/lib/scanner.ts`
|
|
- Create: `src/app/api/scan/route.ts`
|
|
- Test: `tests/lib/scanner.test.ts`
|
|
|
|
**Step 1: Write failing scanner tests**
|
|
- Depth limits, ignore patterns, profile-root default behavior.
|
|
|
|
**Step 2: Implement scanner**
|
|
- Default root `%USERPROFILE%`, plus user-added roots.
|
|
- Add explicit full-drive mode action.
|
|
|
|
**Step 3: Implement scan API**
|
|
- Trigger scan + return discovered project candidates.
|
|
|
|
**Step 4: Verify**
|
|
- Run scanner tests.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `feat: add windows-safe project scanner and scan api`
|
|
|
|
### Task 6: Watcher + SSE Event Bus
|
|
|
|
**Files:**
|
|
- Create: `src/lib/watcher.ts`
|
|
- Create: `src/lib/sse-bus.ts`
|
|
- Create: `src/app/api/events/route.ts`
|
|
- Test: `tests/lib/watcher.test.ts`
|
|
|
|
**Step 1: Write failing watcher tests**
|
|
- Debounced change emission, lock retry behavior, multi-project handling.
|
|
|
|
**Step 2: Implement watcher manager**
|
|
- Chokidar watchers for registered projects.
|
|
|
|
**Step 3: Implement SSE endpoint**
|
|
- Heartbeat, reconnect-safe events, project-scoped payloads.
|
|
|
|
**Step 4: Verify**
|
|
- Run watcher/event tests.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `feat: add live file watching and sse updates`
|
|
|
|
### Task 7: bd.exe Mutation Bridge + API
|
|
|
|
**Files:**
|
|
- Create: `src/lib/bd-bridge.ts`
|
|
- Create: `src/app/api/mutate/route.ts`
|
|
- Test: `tests/lib/bd-bridge.test.ts`
|
|
|
|
**Step 1: Write failing bridge tests**
|
|
- Command invocation, cwd routing, stdout/stderr error mapping.
|
|
|
|
**Step 2: Implement execFile bridge**
|
|
- Resolve `bd.exe` from PATH, enforce project CWD, parse outputs.
|
|
|
|
**Step 3: Implement mutate API**
|
|
- `create`, `update`, `close`, `reopen`, `comment` actions.
|
|
|
|
**Step 4: Verify**
|
|
- Run bridge tests and mutation route tests.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `feat: add bd cli mutation bridge and api`
|
|
|
|
### Task 8: Frontend State and Realtime Sync
|
|
|
|
**Files:**
|
|
- Create: `src/lib/query-client.ts`
|
|
- Create: `src/lib/store.ts`
|
|
- Create: `src/lib/sse-client.ts`
|
|
- Modify: `src/app/layout.tsx`
|
|
|
|
**Step 1: Write failing state tests**
|
|
- Query invalidation + optimistic rollback cases.
|
|
|
|
**Step 2: Implement Query + Zustand providers**
|
|
- Distinguish server cache from UI-local state.
|
|
|
|
**Step 3: Implement SSE client integration**
|
|
- Auto reconnect and scoped invalidation for changed projects.
|
|
|
|
**Step 4: Verify**
|
|
- Run state/integration tests.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `feat: wire react-query zustand and realtime invalidation`
|
|
|
|
### Task 9: Feature Views (Kanban, Graph, Timeline, Sessions)
|
|
|
|
**Files:**
|
|
- Create: `src/components/kanban/*`
|
|
- Create: `src/components/graph/*`
|
|
- Create: `src/components/timeline/*`
|
|
- Create: `src/components/agents/*`
|
|
- Create: `src/app/graph/page.tsx`
|
|
- Create: `src/app/timeline/page.tsx`
|
|
- Create: `src/app/agents/page.tsx`
|
|
|
|
**Step 1: Write failing UI tests**
|
|
- Column rendering, card detail open, graph node interaction, timeline grouping.
|
|
|
|
**Step 2: Implement Kanban baseline**
|
|
- Columns, card metadata, details panel, filters/stats.
|
|
|
|
**Step 3: Implement Graph with React Flow**
|
|
- Edges from dependencies, pan/zoom/select, blocked-chain highlighting.
|
|
|
|
**Step 4: Implement Timeline + Session views**
|
|
- Derived activity and session grouping/metrics.
|
|
|
|
**Step 5: Verify**
|
|
- Run component tests and visual smoke check.
|
|
|
|
**Step 6: Commit**
|
|
- Commit message: `feat: deliver dashboard views for kanban graph timeline and sessions`
|
|
|
|
### Task 10: Quality Gates and Boundary Enforcement
|
|
|
|
**Files:**
|
|
- Create: `tests/guards/no-direct-jsonl-write.test.ts`
|
|
- Create: `docs/architecture/read-write-boundary.md`
|
|
- Modify: `package.json`
|
|
|
|
**Step 1: Write failing guard test**
|
|
- Detect direct writes to `.beads/issues.jsonl` in application code.
|
|
|
|
**Step 2: Implement boundary guard tooling**
|
|
- Add CI script and local verification command.
|
|
|
|
**Step 3: Add performance checks**
|
|
- Parser benchmark and SSE latency smoke measurements.
|
|
|
|
**Step 4: Verify full pipeline**
|
|
- Run `npm run lint && npm run typecheck && npm run test`.
|
|
|
|
**Step 5: Commit**
|
|
- Commit message: `chore: enforce read-write boundaries and quality gates`
|
|
|
|
## Execution Sequence and Parallelization
|
|
- Sequential core chain: Task 1 -> Task 2 -> Task 3 -> Task 4 -> Task 6 -> Task 7 -> Task 8
|
|
- Parallel branch A (after Task 3): Task 5
|
|
- Parallel branch B (after Task 4 and Task 8): Task 9
|
|
- Final gate: Task 10
|
|
|
|
## Completion Criteria
|
|
- Windows-native workflow validated in PowerShell/CMD
|
|
- Reads from JSONL only
|
|
- Mutations executed only via `bd.exe`
|
|
- Real-time updates delivered via SSE
|
|
- Kanban, Graph, Timeline, Agent Session views functional
|
|
- Boundary guard test prevents direct JSONL writes
|