@prmichaelsen/acp-visualizer 0.1.0

package/agent/design/local.search-filtering.md

@@ -0,0 +1,331 @@
+# Search & Filtering
+
+**Concept**: Fuse.js-powered fuzzy search and status-based filtering across milestones and tasks
+**Created**: 2026-03-14
+**Status**: Design Specification
+
+---
+
+## Overview
+
+Defines the search and filtering system that lets users quickly find milestones and tasks by name/content (via fuse.js fuzzy search) and narrow results by status. Search and filter state is global — it persists across view switches (table ↔ tree) and is accessible from the sidebar.
+
+---
+
+## Problem Statement
+
+With 10+ milestones and 50+ tasks, users need to:
+- Find a specific milestone or task by name or keyword
+- Focus on only in-progress items without scrolling past completed work
+- Combine search and filter (e.g., "auth" tasks that are in-progress)
+
+Without search/filter, users are back to mentally parsing a long list — defeating the purpose of a visual dashboard.
+
+---
+
+## Solution
+
+1. **Fuse.js search index** built from milestones and tasks on data load
+2. **Status filter** (all / not_started / in_progress / completed) applied as a pre-filter
+3. **FilterContext** React context providing shared state across all views
+4. **SearchBar** component in sidebar for global access
+5. **FilterBar** component on milestone/task pages for quick status toggles
+
+---
+
+## Implementation
+
+### Search Index
+
+```typescript
+// app/lib/search.ts
+
+import Fuse from 'fuse.js';
+import type { ProgressData, Milestone, Task } from './types';
+
+export type SearchResult = {
+  type: 'milestone' | 'task';
+  milestone: Milestone;
+  task?: Task;
+  score: number;
+};
+
+export function buildSearchIndex(data: ProgressData) {
+  const items: Array<{
+    type: 'milestone' | 'task';
+    milestone: Milestone;
+    task?: Task;
+    name: string;
+    notes: string;
+    extra: string;   // stringified extra fields for search coverage
+  }> = [];
+
+  for (const milestone of data.milestones) {
+    items.push({
+      type: 'milestone',
+      milestone,
+      name: milestone.name,
+      notes: milestone.notes,
+      extra: JSON.stringify(milestone.extra),
+    });
+
+    const tasks = data.tasks[milestone.id] || [];
+    for (const task of tasks) {
+      items.push({
+        type: 'task',
+        milestone,
+        task,
+        name: task.name,
+        notes: task.notes,
+        extra: JSON.stringify(task.extra),
+      });
+    }
+  }
+
+  return new Fuse(items, {
+    keys: [
+      { name: 'name', weight: 2 },
+      { name: 'notes', weight: 1 },
+      { name: 'extra', weight: 0.5 },
+    ],
+    threshold: 0.4,           // moderate fuzziness
+    includeScore: true,
+    ignoreLocation: true,     // match anywhere in string
+  });
+}
+```
+
+### Filter Context
+
+```tsx
+// app/lib/filter-context.tsx
+
+import { createContext, useContext, useState, useMemo } from 'react';
+import type { ProgressData, Status } from './types';
+
+interface FilterState {
+  status: Status | 'all';
+  search: string;
+}
+
+interface FilterContextValue {
+  filters: FilterState;
+  setStatus: (status: Status | 'all') => void;
+  setSearch: (query: string) => void;
+  filteredData: ProgressData;
+}
+
+const FilterContext = createContext<FilterContextValue>(null!);
+
+export function FilterProvider({ data, children }: { data: ProgressData; children: React.ReactNode }) {
+  const [filters, setFilters] = useState<FilterState>({ status: 'all', search: '' });
+
+  const filteredData = useMemo(() => {
+    let milestones = data.milestones;
+    let tasks = { ...data.tasks };
+
+    // Status filter
+    if (filters.status !== 'all') {
+      milestones = milestones.filter(m => m.status === filters.status);
+      tasks = Object.fromEntries(
+        Object.entries(tasks).map(([id, ts]) => [
+          id,
+          ts.filter(t => t.status === filters.status),
+        ])
+      );
+    }
+
+    // Search filter (if query present, intersect with search results)
+    if (filters.search.trim()) {
+      const index = buildSearchIndex(data);
+      const results = index.search(filters.search);
+      const matchedMilestoneIds = new Set(
+        results.map(r => r.item.milestone.id)
+      );
+      const matchedTaskIds = new Set(
+        results.filter(r => r.item.task).map(r => r.item.task!.id)
+      );
+      milestones = milestones.filter(m => matchedMilestoneIds.has(m.id));
+      tasks = Object.fromEntries(
+        Object.entries(tasks).map(([id, ts]) => [
+          id,
+          ts.filter(t => matchedTaskIds.has(t.id) || matchedMilestoneIds.has(id)),
+        ])
+      );
+    }
+
+    return { ...data, milestones, tasks };
+  }, [data, filters]);
+
+  return (
+    <FilterContext.Provider value={{
+      filters,
+      setStatus: (status) => setFilters(f => ({ ...f, status })),
+      setSearch: (search) => setFilters(f => ({ ...f, search })),
+      filteredData,
+    }}>
+      {children}
+    </FilterContext.Provider>
+  );
+}
+
+export const useFilters = () => useContext(FilterContext);
+```
+
+### FilterBar Component
+
+Status toggle buttons displayed above milestone/task views:
+
+```tsx
+// app/components/FilterBar.tsx
+
+const statusOptions: Array<{ value: Status | 'all'; label: string }> = [
+  { value: 'all', label: 'All' },
+  { value: 'in_progress', label: 'In Progress' },
+  { value: 'not_started', label: 'Not Started' },
+  { value: 'completed', label: 'Completed' },
+];
+
+function FilterBar() {
+  const { filters, setStatus } = useFilters();
+
+  return (
+    <div className="flex gap-1 mb-4">
+      {statusOptions.map(opt => (
+        <button
+          key={opt.value}
+          onClick={() => setStatus(opt.value)}
+          className={`px-3 py-1 text-xs rounded-full border transition-colors ${
+            filters.status === opt.value
+              ? 'bg-gray-700 border-gray-600 text-gray-100'
+              : 'bg-transparent border-gray-800 text-gray-500 hover:text-gray-300'
+          }`}
+        >
+          {opt.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### SearchBar Component
+
+Located in the sidebar footer, accessible from any page:
+
+```tsx
+// app/components/SearchBar.tsx
+
+function SearchBar() {
+  const { filters, setSearch } = useFilters();
+
+  return (
+    <div className="relative">
+      <SearchIcon className="absolute left-2 top-2 w-4 h-4 text-gray-500" />
+      <input
+        type="text"
+        value={filters.search}
+        onChange={e => setSearch(e.target.value)}
+        placeholder="Search..."
+        className="w-full bg-gray-900 border border-gray-800 rounded-md pl-8 pr-3 py-1.5 text-sm text-gray-200 placeholder-gray-600 focus:outline-none focus:border-gray-600"
+      />
+    </div>
+  );
+}
+```
+
+### Search Results Page
+
+Dedicated `/search` route for viewing detailed search results when triggered from sidebar:
+
+```tsx
+// app/routes/search.tsx
+
+function SearchPage() {
+  const { filteredData, filters } = useFilters();
+
+  if (!filters.search.trim()) {
+    return <p className="text-gray-500 text-sm">Type to search milestones and tasks</p>;
+  }
+
+  return (
+    <div className="space-y-4">
+      <h2 className="text-sm text-gray-400">
+        Results for "{filters.search}"
+      </h2>
+      {/* Grouped by milestones, then tasks */}
+      {filteredData.milestones.map(m => (
+        <SearchResultCard key={m.id} milestone={m} tasks={filteredData.tasks[m.id]} />
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Benefits
+
+- **Fast**: Fuse.js search is client-side, instant feedback
+- **Fuzzy**: Typo-tolerant matching (threshold 0.4)
+- **Combined**: Search + status filter work together naturally
+- **Global**: Shared state persists across view switches
+- **Extra fields searchable**: Agent-added properties are included in the search index
+
+---
+
+## Trade-offs
+
+- **Client-side only**: Search index is rebuilt on each data load (acceptable for <100KB data)
+- **No server-side search**: All data is loaded upfront (fine for single-project P0)
+- **Fuse.js bundle size**: ~15KB gzipped (acceptable for admin dashboard)
+
+---
+
+## Applicable Patterns
+
+| Pattern | How It Applies |
+|---------|----------------|
+| [`tanstack-cloudflare.global-search-context`](../patterns/tanstack-cloudflare.global-search-context.md) | Adopt the lightweight pub/sub `useRef` store for cross-component search/filter state instead of heavy React Context re-renders. `useGlobalSearch(key)` returns `[value, setValue]` and only re-renders subscribers of that key. Key convention: `milestones:search`, `milestones:status`. Wrap app in `<GlobalSearchProvider>` in root layout. This replaces the FilterContext approach in the implementation section — the GlobalSearchContext pattern is more performant for string-based filter state. |
+| [`tanstack-cloudflare.pill-input`](../patterns/tanstack-cloudflare.pill-input.md) | Provides the proven fuse.js configuration: `threshold: 0.4`, `ignoreLocation: true`, keyboard navigation (arrows, Enter, Escape). The PillInput pattern's fuzzy matching config should be adopted for the search index. Also demonstrates combining predefined options with custom entries — applicable to filter presets. |
+| [`tanstack-cloudflare.searchable-settings`](../patterns/tanstack-cloudflare.searchable-settings.md) | The registry-based AND-logic search pattern applies to multi-field filtering. Each searchable item has `name`, `description`, `keywords` — map to milestone/task names, notes, and extra field values. Hash-based scroll navigation could enable direct linking to search results. |
+| [`tanstack-cloudflare.form-controls`](../patterns/tanstack-cloudflare.form-controls.md) | ToggleSwitch component (iOS-style, ARIA-accessible) for boolean filter controls. Could be used for "show completed" toggle. Fully keyboard-accessible with proper ARIA labels. |
+| [`tanstack-cloudflare.unified-header`](../patterns/tanstack-cloudflare.unified-header.md) | FilterTabs component (inline pill-style filter controls): `flex gap-1 mb-4 p-1 bg-gray-800/50 rounded-lg`. Active button gets gradient background, inactive gets gray text with hover. Adopt this exact styling for the status filter bar rather than custom implementation. |
+
+---
+
+## Dependencies
+
+- `fuse.js` — fuzzy search library
+- React context API (or GlobalSearchContext pub/sub — see Applicable Patterns)
+
+---
+
+## Testing Strategy
+
+- **Unit tests**: `buildSearchIndex` returns correct results for known queries
+- **Fuzzy matching**: Typos still find results (e.g., "infrastrcture" → "infrastructure")
+- **Filter tests**: Status filter correctly narrows milestone/task lists
+- **Combined tests**: Search + filter intersection works correctly
+- **Empty states**: No results shows appropriate message
+
+---
+
+## Migration Path
+
+N/A — greenfield project.
+
+---
+
+## Future Considerations
+
+- **Keyboard shortcut**: `Cmd+K` to focus search bar
+- **Search history**: Recent searches stored in localStorage
+- **Advanced filters**: Filter by date range, estimated hours, completion percentage
+- **P1: Recent work search**: Include WorkEntry items in search index
+
+---
+
+**Status**: Design Specification
+**Recommendation**: Implement alongside views — search/filter enhances all view components
+**Related Documents**: local.visualizer-requirements.md, local.table-tree-views.md, tanstack-cloudflare.global-search-context, tanstack-cloudflare.pill-input, tanstack-cloudflare.searchable-settings, tanstack-cloudflare.form-controls, tanstack-cloudflare.unified-header

package/agent/design/local.server-api-auto-refresh.md

@@ -0,0 +1,235 @@
+# Server API & Auto-Refresh
+
+**Concept**: TanStack Start server routes for loading progress.yaml and SSE-based auto-refresh
+**Created**: 2026-03-14
+**Status**: Design Specification
+
+---
+
+## Overview
+
+Defines the server-side architecture for loading `progress.yaml` from the local filesystem and pushing updates to the browser in real time when the file changes. Uses TanStack Start server functions and Server-Sent Events (SSE) for a simple, reliable auto-refresh mechanism.
+
+---
+
+## Problem Statement
+
+The visualizer needs to:
+- Read `progress.yaml` from a configurable filesystem path
+- Serve parsed data to the React frontend
+- Automatically refresh the dashboard when agents modify `progress.yaml` during work
+- Handle file-not-found and parse errors gracefully
+
+A simple "refresh the page" approach is insufficient — agents may update progress.yaml dozens of times during a session, and the dashboard should reflect changes without manual intervention.
+
+---
+
+## Solution
+
+1. **Server function**: TanStack Start `createServerFn` that reads and parses `progress.yaml`
+2. **SSE endpoint**: Watches the file for changes and pushes notifications to connected clients
+3. **Client hook**: `useAutoRefresh()` React hook that listens for SSE events and triggers re-fetch
+
+---
+
+## Implementation
+
+### Configuration
+
+The path to `progress.yaml` is resolved from (in order):
+1. `PROGRESS_YAML_PATH` environment variable (absolute path)
+2. CLI argument: `npm run dev -- --progress /path/to/progress.yaml`
+3. Default: `./agent/progress.yaml` (relative to cwd)
+
+```typescript
+// app/lib/config.ts
+
+export function getProgressYamlPath(): string {
+  return (
+    process.env.PROGRESS_YAML_PATH ||
+    process.argv.find((_, i, a) => a[i - 1] === '--progress') ||
+    './agent/progress.yaml'
+  );
+}
+```
+
+### Server Function
+
+```typescript
+// app/lib/data-source.ts
+
+import { createServerFn } from '@tanstack/react-start';
+import { readFileSync } from 'fs';
+import { parseProgressYaml } from './yaml-loader';
+import { getProgressYamlPath } from './config';
+
+export const getProgressData = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    const filePath = getProgressYamlPath();
+    const raw = readFileSync(filePath, 'utf-8');
+    return parseProgressYaml(raw);
+  });
+```
+
+### File Watcher & SSE
+
+```typescript
+// server/routes/api/watch.ts
+
+import { watch } from 'fs';
+import { getProgressYamlPath } from '../../app/lib/config';
+
+export function createFileWatcher() {
+  const filePath = getProgressYamlPath();
+  const clients = new Set<ReadableStreamDefaultController>();
+
+  watch(filePath, (eventType) => {
+    if (eventType === 'change') {
+      for (const controller of clients) {
+        controller.enqueue(`data: refresh\n\n`);
+      }
+    }
+  });
+
+  return {
+    addClient(controller: ReadableStreamDefaultController) {
+      clients.add(controller);
+    },
+    removeClient(controller: ReadableStreamDefaultController) {
+      clients.delete(controller);
+    },
+  };
+}
+```
+
+### SSE API Route
+
+```typescript
+// app/routes/api/watch.ts
+
+import { createAPIFileRoute } from '@tanstack/react-start/api';
+
+let watcher: ReturnType<typeof createFileWatcher> | null = null;
+
+export const APIRoute = createAPIFileRoute('/api/watch')({
+  GET: async () => {
+    if (!watcher) {
+      watcher = createFileWatcher();
+    }
+
+    const stream = new ReadableStream({
+      start(controller) {
+        watcher!.addClient(controller);
+      },
+      cancel(controller) {
+        watcher!.removeClient(controller);
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+      },
+    });
+  },
+});
+```
+
+### Client Hook
+
+```typescript
+// app/lib/useAutoRefresh.ts
+
+import { useRouter } from '@tanstack/react-router';
+import { useEffect } from 'react';
+
+export function useAutoRefresh() {
+  const router = useRouter();
+
+  useEffect(() => {
+    const eventSource = new EventSource('/api/watch');
+
+    eventSource.onmessage = () => {
+      router.invalidate();
+    };
+
+    eventSource.onerror = () => {
+      // Reconnect handled automatically by EventSource
+    };
+
+    return () => eventSource.close();
+  }, [router]);
+}
+```
+
+### Error Handling
+
+- **File not found**: Server function returns a structured error object with `{ error: 'FILE_NOT_FOUND', path }`. Frontend shows a configuration prompt.
+- **Parse error**: Returns `{ error: 'PARSE_ERROR', message }`. Frontend shows the error with the raw YAML path.
+- **File watcher failure**: Falls back to manual refresh. Log warning to console.
+
+---
+
+## Benefits
+
+- **Real-time updates**: Dashboard reflects changes within ~100ms of file save
+- **Low overhead**: SSE is lightweight compared to WebSocket for one-way push
+- **Simple client**: `EventSource` API handles reconnection automatically
+- **No polling**: File watcher is event-driven, not interval-based
+
+---
+
+## Trade-offs
+
+- **Local only**: `fs.watch` only works for local development (P1 GitHub source uses polling instead)
+- **Single file**: Watches one progress.yaml path — no multi-project support in P0
+- **SSE limitations**: One-way communication only (sufficient for refresh notifications)
+
+---
+
+## Applicable Patterns
+
+| Pattern | How It Applies |
+|---------|----------------|
+| [`tanstack-cloudflare.ssr-preload`](../patterns/tanstack-cloudflare.ssr-preload.md) | Progress data should be loaded server-side via `beforeLoad` (not `loader`), passed through route context, and accessed via `Route.useRouteContext()`. Components initialize state with SSR data and skip client fetch if present. Error handling must be graceful — `try/catch` with empty-data fallback, never fail the page load. |
+| [`tanstack-cloudflare.api-route-handlers`](../patterns/tanstack-cloudflare.api-route-handlers.md) | The SSE `/api/watch` endpoint and any future REST endpoints should use `createFileRoute` with `server.handlers` returning Web Standard `Response` objects. Consistent error response format: `{ error, message }`. No auth needed for P0 (local dev tool). |
+| [`tanstack-cloudflare.library-services`](../patterns/tanstack-cloudflare.library-services.md) | File reading and YAML parsing must go through a `ProgressDatabaseService` (server-side) — never call `readFileSync` directly in routes or `beforeLoad`. The service handles path resolution, file reading, parsing, and error wrapping. |
+| [`tanstack-cloudflare.websocket-manager`](../patterns/tanstack-cloudflare.websocket-manager.md) | While we use SSE (not WebSocket) for P0, the reconnection and lifecycle patterns apply: exponential backoff on connection loss, page visibility recovery (reconnect on tab focus), and clean teardown in `useEffect` cleanup. `EventSource` handles reconnection natively but visibility recovery should still be explicit. |
+
+---
+
+## Dependencies
+
+- Node.js `fs` module (built-in)
+- TanStack Start server functions
+- No additional npm packages needed
+
+---
+
+## Testing Strategy
+
+- **Unit tests**: `getProgressYamlPath()` resolution order
+- **Integration tests**: Server function reads real YAML file, returns typed data
+- **Manual testing**: Modify progress.yaml while dashboard is open, verify auto-refresh
+
+---
+
+## Migration Path
+
+N/A — greenfield project.
+
+---
+
+## Future Considerations
+
+- **P1: GitHub remote source** — Replace `readFileSync` with GitHub API fetch, replace SSE with configurable polling interval
+- **P1: Multi-project** — Watch multiple progress.yaml paths, route by project
+- **WebSocket upgrade** — If bidirectional communication needed in future (unlikely for read-only dashboard)
+
+---
+
+**Status**: Design Specification
+**Recommendation**: Implement after data model — provides the data pipeline for all views
+**Related Documents**: local.visualizer-requirements.md, local.data-model-yaml-parsing.md, tanstack-cloudflare.ssr-preload, tanstack-cloudflare.api-route-handlers, tanstack-cloudflare.library-services, tanstack-cloudflare.websocket-manager