@prmichaelsen/acp-visualizer 0.1.0

package/agent/design/local.dashboard-layout-routing.md

@@ -0,0 +1,288 @@
+# Dashboard Layout & Routing
+
+**Concept**: Root layout structure, navigation, routing, and visual design system for the admin dashboard
+**Created**: 2026-03-14
+**Status**: Design Specification
+
+---
+
+## Overview
+
+Defines the application shell — root layout, sidebar navigation, header, routing structure, and the visual design tokens (colors, typography, spacing) that create a cohesive Linear/Vercel-style admin dashboard. This design establishes the container that all view components render within.
+
+---
+
+## Problem Statement
+
+The visualizer needs:
+- A persistent navigation structure for switching between views (dashboard, milestones, tasks, search)
+- Consistent visual language across all pages
+- Information-dense layout optimized for desktop developer use
+- Clear visual hierarchy for status indicators (completed/in-progress/not-started)
+
+Without a defined layout system, views would be implemented ad-hoc with inconsistent spacing, typography, and navigation patterns.
+
+---
+
+## Solution
+
+A minimal sidebar + content area layout with:
+1. Fixed left sidebar for navigation
+2. Content area with page-specific views
+3. Shared design tokens via Tailwind CSS configuration
+4. TanStack Router file-based routing
+
+---
+
+## Implementation
+
+### Route Structure
+
+```
+app/routes/
+├── __root.tsx              # Root layout (sidebar + content shell)
+├── index.tsx               # Dashboard home (project overview + summary)
+├── milestones.tsx           # Milestone views (table/tree toggle)
+├── milestones.$id.tsx       # Single milestone detail (tasks list)
+├── tasks.tsx                # All tasks view
+├── activity.tsx             # Recent work timeline (P1)
+└── search.tsx               # Global search results
+```
+
+### Root Layout
+
+```tsx
+// app/routes/__root.tsx
+
+export const Route = createRootRoute({
+  component: RootLayout,
+});
+
+function RootLayout() {
+  return (
+    <div className="flex h-screen bg-gray-950 text-gray-100">
+      <Sidebar />
+      <main className="flex-1 overflow-auto">
+        <Header />
+        <div className="p-6">
+          <Outlet />
+        </div>
+      </main>
+    </div>
+  );
+}
+```
+
+### Sidebar
+
+```tsx
+// app/components/Sidebar.tsx
+
+const navItems = [
+  { to: '/', icon: LayoutDashboard, label: 'Overview' },
+  { to: '/milestones', icon: Flag, label: 'Milestones' },
+  { to: '/tasks', icon: CheckSquare, label: 'Tasks' },
+  { to: '/activity', icon: Clock, label: 'Activity' },  // P1
+];
+
+function Sidebar() {
+  return (
+    <nav className="w-56 border-r border-gray-800 bg-gray-950 flex flex-col">
+      <div className="p-4 border-b border-gray-800">
+        <span className="text-sm font-semibold text-gray-300 tracking-wide">
+          ACP Visualizer
+        </span>
+      </div>
+      <div className="flex-1 py-2">
+        {navItems.map(item => (
+          <NavLink key={item.to} {...item} />
+        ))}
+      </div>
+      <div className="p-4 border-t border-gray-800">
+        <SearchTrigger />
+      </div>
+    </nav>
+  );
+}
+```
+
+### Header
+
+Displays current project name, version, status badge, and overall progress:
+
+```tsx
+// app/components/Header.tsx
+
+function Header() {
+  // Project metadata from route loader
+  return (
+    <header className="h-14 border-b border-gray-800 flex items-center px-6 gap-4">
+      <h1 className="text-sm font-medium text-gray-200">{project.name}</h1>
+      <span className="text-xs text-gray-500">v{project.version}</span>
+      <StatusBadge status={project.status} />
+      <div className="ml-auto">
+        <ProgressBar value={progress.overall} size="sm" />
+      </div>
+    </header>
+  );
+}
+```
+
+### Design Tokens (Tailwind Config)
+
+```typescript
+// tailwind.config.ts
+
+export default {
+  theme: {
+    extend: {
+      colors: {
+        status: {
+          completed: '#22c55e',      // green-500
+          in_progress: '#3b82f6',    // blue-500
+          not_started: '#6b7280',    // gray-500
+        },
+      },
+      fontFamily: {
+        mono: ['JetBrains Mono', 'Fira Code', 'monospace'],
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+      },
+    },
+  },
+};
+```
+
+### Visual Design Rules
+
+| Element | Style |
+|---------|-------|
+| Background | `gray-950` (near-black) |
+| Surface/cards | `gray-900` with `gray-800` borders |
+| Primary text | `gray-100` |
+| Secondary text | `gray-400` |
+| Data values | Monospace font (`font-mono`) |
+| Status: completed | Green badge/dot |
+| Status: in_progress | Blue badge/dot |
+| Status: not_started | Gray badge/dot |
+| Interactive hover | `gray-800` background |
+| Spacing | 4px grid (Tailwind default) |
+
+### StatusBadge Component
+
+```tsx
+// app/components/StatusBadge.tsx
+
+const statusStyles = {
+  completed: 'bg-green-500/15 text-green-400 border-green-500/20',
+  in_progress: 'bg-blue-500/15 text-blue-400 border-blue-500/20',
+  not_started: 'bg-gray-500/15 text-gray-500 border-gray-500/20',
+};
+
+const statusLabels = {
+  completed: 'Completed',
+  in_progress: 'In Progress',
+  not_started: 'Not Started',
+};
+
+export function StatusBadge({ status }: { status: Status }) {
+  return (
+    <span className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs border ${statusStyles[status]}`}>
+      {statusLabels[status]}
+    </span>
+  );
+}
+```
+
+### ProgressBar Component
+
+```tsx
+// app/components/ProgressBar.tsx
+
+export function ProgressBar({ value, size = 'md' }: { value: number; size?: 'sm' | 'md' }) {
+  const height = size === 'sm' ? 'h-1.5' : 'h-2.5';
+  return (
+    <div className={`w-full bg-gray-800 rounded-full ${height} overflow-hidden`}>
+      <div
+        className={`${height} rounded-full transition-all duration-300 ${
+          value === 100 ? 'bg-green-500' : 'bg-blue-500'
+        }`}
+        style={{ width: `${Math.min(100, Math.max(0, value))}%` }}
+      />
+    </div>
+  );
+}
+```
+
+### Dashboard Home (Overview Page)
+
+The index route shows a single-page summary:
+- Project metadata card (name, version, status, dates)
+- Overall progress bar
+- Milestone summary (compact list with progress bars)
+- Next steps list
+- Current blockers (if any)
+
+---
+
+## Benefits
+
+- **Consistent**: All pages share the same visual language
+- **Information-dense**: Compact layout maximizes data visibility
+- **Navigable**: Sidebar provides constant orientation
+- **Extensible**: Adding new routes/views follows established patterns
+
+---
+
+## Trade-offs
+
+- **Desktop-only**: Fixed sidebar layout doesn't collapse for mobile (acceptable per requirements)
+- **Dark theme only**: No light mode toggle in P0 (future consideration)
+- **Minimal branding**: Intentionally plain — data is the focus
+
+---
+
+## Applicable Patterns
+
+| Pattern | How It Applies |
+|---------|----------------|
+| [`tanstack-cloudflare.unified-header`](../patterns/tanstack-cloudflare.unified-header.md) | Adopt the fixed header + content offset pattern. Use `pt-14` on main content. For view switching (table/tree), use `SubHeaderTabs` rendered as children of the header. Adapt for sidebar layout: the pattern's `max-w-3xl` centering shifts to sidebar + full-width content area, but the fixed positioning, safe-area handling, and tab structure apply directly. |
+| [`tanstack-cloudflare.nextjs-to-tanstack-routing`](../patterns/tanstack-cloudflare.nextjs-to-tanstack-routing.md) | Reference for TanStack Router file-based routing conventions: `$id` for dynamic params, `__root.tsx` for layout, `beforeLoad` for data, `meta()` for page metadata. Ensures routes follow established patterns. |
+| [`tanstack-cloudflare.card-and-list`](../patterns/tanstack-cloudflare.card-and-list.md) | Adopt consistent card styling for dashboard summary cards: `bg-gray-900/50 backdrop-blur-sm border border-gray-800 rounded-xl p-4`. Text hierarchy: title `text-white font-semibold`, secondary `text-gray-400 text-sm`, meta `text-gray-500 text-xs`. |
+| [`tanstack-cloudflare.toast-system`](../patterns/tanstack-cloudflare.toast-system.md) | Use for error feedback (YAML parse errors, file-not-found) and auto-refresh status notifications. `useToast()` for direct calls, `StandaloneToastContainer` at z-60 in root layout. |
+
+---
+
+## Dependencies
+
+- Tailwind CSS
+- TanStack Router (file-based routing)
+- lucide-react for icons (lightweight, tree-shakeable)
+
+---
+
+## Testing Strategy
+
+- **Component tests**: Sidebar renders correct nav items, StatusBadge renders correct colors
+- **Visual regression**: Screenshot tests for layout at standard viewport sizes
+- **Route tests**: Each route resolves and renders without errors
+
+---
+
+## Migration Path
+
+N/A — greenfield project.
+
+---
+
+## Future Considerations
+
+- **Dark/light mode toggle**: Add theme context and Tailwind dark mode classes
+- **Collapsible sidebar**: Icon-only mode for more content space
+- **Breadcrumbs**: For nested routes (milestone → task detail)
+- **Keyboard navigation**: `Cmd+K` for search, arrow keys for nav
+
+---
+
+**Status**: Design Specification
+**Recommendation**: Implement alongside or immediately after server API — provides the shell for all views
+**Related Documents**: local.visualizer-requirements.md, tanstack-cloudflare.unified-header, tanstack-cloudflare.nextjs-to-tanstack-routing, tanstack-cloudflare.card-and-list, tanstack-cloudflare.toast-system

package/agent/design/local.data-model-yaml-parsing.md

@@ -0,0 +1,310 @@
+# Data Model & YAML Parsing
+
+**Concept**: TypeScript data model for progress.yaml and YAML-to-structured-data parsing pipeline
+**Created**: 2026-03-14
+**Status**: Design Specification
+
+---
+
+## Overview
+
+Defines the TypeScript interfaces that represent ACP `progress.yaml` data and the parsing pipeline that converts raw YAML into typed, normalized structures suitable for rendering in the visualizer's views. This is the foundational data layer that all views, search, and filtering depend on.
+
+---
+
+## Problem Statement
+
+ACP `progress.yaml` files are large (1800+ lines), loosely structured YAML **maintained by AI agents, not programmatic YAML operations**. This means:
+- Fields may be missing, renamed, or added ad-hoc by different agents
+- Unexpected/custom properties may appear at any level (e.g., an agent adds `priority: high` to a task)
+- Key names may drift slightly (e.g., `estimated_hours` vs `est_hours` vs `hours`)
+- Structural variations exist across projects (arrays vs objects, nested vs flat)
+
+The visualizer needs:
+- Strong TypeScript types for compile-time safety across all views
+- **Lenient parsing** that extracts known fields without crashing on unknown ones
+- **Passthrough of unrecognized properties** so they can be displayed in a "raw data" fallback
+- Normalization of optional/missing fields to prevent runtime errors
+- Consistent ID generation for entities that don't have explicit IDs in YAML
+- Computed fields (e.g., task counts, completion percentages) derived from raw data
+
+Without a well-defined but flexible data model, the visualizer would either crash on real-world YAML or silently lose agent-added context.
+
+---
+
+## Solution
+
+Create a `yaml-loader.ts` module in `app/lib/` that:
+
+1. Accepts raw YAML string input
+2. Parses via `js-yaml` into untyped JavaScript objects
+3. Validates and normalizes into strongly-typed TypeScript interfaces
+4. Computes derived fields (progress percentages, task counts)
+5. Returns a single `ProgressData` object consumed by all views
+
+---
+
+## Implementation
+
+### TypeScript Interfaces
+
+```typescript
+// app/lib/types.ts
+
+export type Status = 'completed' | 'in_progress' | 'not_started';
+
+export interface ProgressData {
+  project: ProjectMetadata;
+  milestones: Milestone[];
+  tasks: Record<string, Task[]>;  // keyed by milestone_id
+  recent_work: WorkEntry[];
+  next_steps: string[];
+  notes: string[];
+  current_blockers: string[];
+  documentation: DocumentationStats;
+  progress: ProgressSummary;
+}
+
+// Unknown properties from agent-maintained YAML are preserved here
+// so views can display them in raw/debug panels without data loss.
+export type ExtraFields = Record<string, unknown>;
+
+export interface ProjectMetadata {
+  name: string;
+  version: string;
+  started: string;
+  status: Status;
+  current_milestone?: string;
+  description: string;
+  extra: ExtraFields;          // any unrecognized project-level fields
+}
+
+export interface Milestone {
+  id: string;
+  name: string;
+  status: Status;
+  progress: number;            // 0-100
+  started: string | null;
+  completed: string | null;
+  estimated_weeks: string;
+  tasks_completed: number;
+  tasks_total: number;
+  notes: string;
+  extra: ExtraFields;
+}
+
+export interface Task {
+  id: string;
+  name: string;
+  status: Status;
+  milestone_id: string;
+  file: string;
+  estimated_hours: string;
+  completed_date: string | null;
+  notes: string;
+  extra: ExtraFields;
+}
+
+export interface WorkEntry {
+  date: string;
+  description: string;
+  items: string[];
+  extra: ExtraFields;
+}
+
+export interface DocumentationStats {
+  design_documents: number;
+  milestone_documents: number;
+  pattern_documents: number;
+  task_documents: number;
+}
+
+export interface ProgressSummary {
+  planning: number;
+  implementation: number;
+  overall: number;
+}
+```
+
+### YAML Parsing & Normalization
+
+The parser follows a "extract known, preserve unknown" strategy:
+
+```typescript
+// app/lib/yaml-loader.ts
+
+import yaml from 'js-yaml';
+import type { ProgressData, Milestone, Task, Status, ExtraFields } from './types';
+
+export function parseProgressYaml(raw: string): ProgressData {
+  const doc = yaml.load(raw) as Record<string, unknown>;
+
+  const project = normalizeProject(doc.project);
+  const milestones = normalizeMilestones(doc.milestones);
+  const tasks = normalizeTasks(doc.tasks, milestones);
+
+  return {
+    project,
+    milestones,
+    tasks,
+    recent_work: normalizeWorkEntries(doc.recent_work),
+    next_steps: normalizeStringArray(doc.next_steps),
+    notes: normalizeStringArray(doc.notes),
+    current_blockers: normalizeStringArray(doc.current_blockers),
+    documentation: normalizeDocStats(doc.documentation),
+    progress: normalizeProgress(doc.progress),
+  };
+}
+
+// --- Core extraction helpers ---
+
+/** Extract known keys from an object, return the rest as ExtraFields */
+function extractKnown<T extends Record<string, unknown>>(
+  obj: Record<string, unknown>,
+  knownKeys: string[],
+): { known: Partial<T>; extra: ExtraFields } {
+  const known: Record<string, unknown> = {};
+  const extra: ExtraFields = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (knownKeys.includes(key)) {
+      known[key] = value;
+    } else {
+      extra[key] = value;
+    }
+  }
+  return { known: known as Partial<T>, extra };
+}
+
+function normalizeStatus(value: unknown): Status {
+  const s = String(value || 'not_started')
+    .toLowerCase()
+    .replace(/[\s-]/g, '_');       // handle "in progress", "in-progress"
+  if (s === 'completed' || s === 'done' || s === 'complete') return 'completed';
+  if (s === 'in_progress' || s === 'active' || s === 'wip') return 'in_progress';
+  return 'not_started';
+}
+
+function normalizeStringArray(value: unknown): string[] {
+  if (!value) return [];
+  if (typeof value === 'string') return [value];  // agent wrote a single string instead of array
+  if (!Array.isArray(value)) return [];
+  return value.map(String);
+}
+
+function safeString(value: unknown, fallback = ''): string {
+  if (value == null) return fallback;
+  return String(value);
+}
+
+function safeNumber(value: unknown, fallback = 0): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+```
+
+### Handling Agent-Maintained YAML Drift
+
+Since progress.yaml files are written and updated by AI agents (not schema-validated tooling), the parser must handle common drift patterns:
+
+| Drift Pattern | Example | Handling |
+|---|---|---|
+| Unknown properties | `priority: high` on a task | Preserved in `extra` field, available for display |
+| Variant key names | `est_hours` instead of `estimated_hours` | Alias map checked during normalization |
+| Status value variants | `"done"`, `"active"`, `"wip"` | Fuzzy-matched to canonical Status enum |
+| String-for-array | `notes: "some note"` instead of `notes: ["some note"]` | Wrapped in array automatically |
+| Missing sections | No `milestones` key at all | Defaults to empty array |
+| Unexpected nesting | Tasks as nested objects vs flat arrays | Both structures accepted |
+| Extra top-level keys | `custom_metrics:` section | Ignored gracefully (not in ProgressData but no crash) |
+
+**Key alias map** (checked in normalizers):
+```typescript
+const TASK_ALIASES: Record<string, string> = {
+  est_hours: 'estimated_hours',
+  hours: 'estimated_hours',
+  estimate: 'estimated_hours',
+  completed: 'completed_date',
+  done_date: 'completed_date',
+  filename: 'file',
+  path: 'file',
+};
+```
+
+### Computed Fields
+
+The parser computes:
+- `milestone.progress` from task completion ratios when not explicitly set
+- `milestone.tasks_completed` / `tasks_total` from the tasks map
+- `progress.overall` from milestone-level progress if not set
+
+### Error Handling
+
+- Missing top-level keys default to empty arrays/objects
+- Invalid status values fuzzy-match to nearest canonical value, fallback to `'not_started'`
+- Missing dates normalize to `null`
+- Numeric fields default to `0`
+- Unknown properties are preserved in `extra` fields, never discarded silently
+- Entire parse is wrapped in try/catch — on total failure, returns a minimal ProgressData with error metadata
+
+---
+
+## Benefits
+
+- **Type safety**: All view components get compile-time guarantees
+- **Single source of truth**: One parsing function, consistent across all views
+- **Defensive**: Gracefully handles incomplete or malformed YAML
+- **Testable**: Pure function with no side effects
+
+---
+
+## Trade-offs
+
+- **Extra fields add payload**: Preserving unknown properties increases data size, but keeps agent context available for display
+- **Alias map maintenance**: New agent drift patterns may require adding aliases over time
+- **Upfront parsing cost**: Entire file is parsed on each load (mitigated by small file sizes, typically <100KB)
+
+---
+
+## Applicable Patterns
+
+| Pattern | How It Applies |
+|---------|----------------|
+| [`tanstack-cloudflare.zod-schema-validation`](../patterns/tanstack-cloudflare.zod-schema-validation.md) | Defines how to structure schemas as single source of truth. Use `z.infer<>` for derived types. For this project: Zod schemas could optionally validate known fields via `safeParse` while the `extractKnown` helper preserves extras — a hybrid approach that gets runtime validation on known fields without rejecting agent drift. Place schemas in `app/lib/schemas/`. |
+| [`tanstack-cloudflare.library-services`](../patterns/tanstack-cloudflare.library-services.md) | YAML parsing should be encapsulated in a service class (`ProgressDataService`) rather than called directly from components or routes. The service provides `getProgressData()` which handles file reading, parsing, normalization, and error handling. Components never import `yaml-loader.ts` directly. |
+
+---
+
+## Dependencies
+
+- `js-yaml` — YAML parsing library
+- `zod` — optional runtime validation for known fields (see Applicable Patterns)
+- No other external dependencies
+
+---
+
+## Testing Strategy
+
+- **Unit tests**: Parse sample progress.yaml files with various completeness levels
+- **Drift tests**: YAML with unknown fields, variant key names, status aliases — verify `extra` preservation and alias resolution
+- **Edge cases**: Empty milestones array, missing tasks key, null dates, unknown status values, string-for-array, completely empty file
+- **Snapshot tests**: Known YAML input → expected ProgressData output
+- **Real-world tests**: Parse actual progress.yaml files from ACP core and other projects to catch unexpected structures
+
+---
+
+## Migration Path
+
+N/A — greenfield project.
+
+---
+
+## Future Considerations
+
+- Zod schema validation for runtime type checking (could replace manual normalization)
+- Support for progress.yaml schema versioning if ACP introduces breaking changes
+- Streaming parser for extremely large files (unlikely to be needed)
+
+---
+
+**Status**: Design Specification
+**Recommendation**: Implement as first task — all other features depend on this
+**Related Documents**: local.visualizer-requirements.md, tanstack-cloudflare.zod-schema-validation, tanstack-cloudflare.library-services