@prmichaelsen/acp-visualizer 0.1.0 → 0.1.2

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

@@ -1,331 +0,0 @@
-# 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

@@ -1,235 +0,0 @@
-# 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