@prmichaelsen/acp-visualizer 0.1.0

package/agent/tasks/milestone-2-dashboard-views-interaction/task-9-implement-search-filtering.md

@@ -0,0 +1,233 @@
+# Task 9: Implement Search & Filtering
+
+**Milestone**: [M2 - Dashboard Views & Interaction](../../milestones/milestone-2-dashboard-views-interaction.md)
+**Design Reference**: [Search & Filtering](../../design/local.search-filtering.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Task 7, Task 8
+**Status**: Not Started
+
+---
+
+## Objective
+
+Add fuse.js fuzzy search and status-based filtering across milestones and tasks, with shared state via GlobalSearchContext. This enables users to quickly find specific milestones or tasks by name and narrow results by status.
+
+---
+
+## Context
+
+As the progress.yaml data grows (real-world files can be 1800+ lines), users need efficient ways to find specific items. This task adds two complementary features: fuzzy search (powered by fuse.js) that matches against milestone and task names/notes, and status filters that narrow the view to items matching a selected status. Both features share state through a global context so the search query persists across navigation. The search and filter logic is encapsulated in reusable hooks that the table, tree, and search page views can all consume.
+
+---
+
+## Steps
+
+### 1. Create `app/lib/search.ts`
+
+Build the search index and query functions using fuse.js:
+
+```typescript
+import Fuse from "fuse.js";
+
+const fuseOptions: Fuse.IFuseOptions<SearchableItem> = {
+  threshold: 0.4,
+  ignoreLocation: true,
+  keys: [
+    { name: "name", weight: 2 },
+    { name: "notes", weight: 1 },
+    { name: "extra", weight: 0.5 },
+  ],
+};
+
+export function buildSearchIndex(data: ProgressData): Fuse<SearchableItem> {
+  // Flatten milestones and tasks into searchable items
+  // Each item includes: name, notes, extra fields, type (milestone/task), parentMilestone
+  // ...
+}
+```
+
+- Flatten milestones and tasks into a unified searchable array
+- Each searchable item carries metadata about its type and parent milestone
+- Threshold of 0.4 allows fuzzy matching (typos still return results)
+- `ignoreLocation: true` matches anywhere in the string, not just near the start
+
+### 2. Create `app/contexts/GlobalSearchContext.tsx`
+
+Build a global search state context using useRef-based pub/sub:
+
+```typescript
+interface GlobalSearchState {
+  query: string;
+  statusFilter: string | null; // null = all, or "completed" | "in_progress" | "not_started"
+}
+
+export function GlobalSearchProvider({ children }: { children: React.ReactNode }) {
+  // useRef-based store for performance (avoids re-rendering entire tree)
+  // Subscribers register with useGlobalSearch(key) hook
+}
+
+export function useGlobalSearch(key: keyof GlobalSearchState) {
+  // Returns [value, setValue] for the specified key
+  // Only re-renders when the subscribed key changes
+}
+```
+
+- Uses useRef internally to store state, with a subscriber pattern to notify consumers
+- Avoids re-rendering the entire component tree when search state changes
+- Provides both the query string and status filter as separate subscribable keys
+
+### 3. Create `app/lib/useFilteredData.ts`
+
+Build a hook that applies both search and status filter to progress data:
+
+```typescript
+export function useFilteredData(data: ProgressData): ProgressData {
+  const [query] = useGlobalSearch("query");
+  const [statusFilter] = useGlobalSearch("statusFilter");
+
+  return useMemo(() => {
+    let filtered = data;
+
+    // Apply status filter
+    if (statusFilter) {
+      filtered = filterByStatus(filtered, statusFilter);
+    }
+
+    // Apply search query
+    if (query) {
+      filtered = filterBySearch(filtered, query);
+    }
+
+    return filtered;
+  }, [data, query, statusFilter]);
+}
+```
+
+- Returns a filtered copy of ProgressData (does not mutate original)
+- Status filter narrows milestones and tasks to matching status
+- Search filter uses the fuse.js index to match by name/notes
+- Filters compose: status filter + search query both apply simultaneously
+
+### 4. Create `app/components/FilterBar.tsx`
+
+Build the pill-style status filter toggle:
+
+- Renders toggle buttons: All, In Progress, Not Started, Completed
+- Active filter pill is highlighted (`bg-blue-500/20 text-blue-400 border-blue-500/50`)
+- Inactive pills are subtle (`bg-gray-800 text-gray-400 border-gray-700`)
+- Clicking a pill updates the statusFilter in GlobalSearchContext
+- Clicking the active pill deselects it (returns to "All")
+- Styled as inline-flex with gap between pills
+
+### 5. Create `app/components/SearchBar.tsx`
+
+Build the search input for the sidebar:
+
+- Search icon (Search from lucide-react) on the left
+- Text input with placeholder "Search milestones & tasks..."
+- Connected to GlobalSearchContext query state
+- Debounced input (300ms) to avoid excessive re-filtering
+- Styled to match sidebar: `bg-gray-900 border border-gray-800 rounded-lg`
+- Pressing Escape clears the search
+- Pressing Enter navigates to `/search` for full results page
+
+### 6. Add GlobalSearchProvider to root layout
+
+Update `app/routes/__root.tsx` to wrap the app with the GlobalSearchProvider:
+
+```typescript
+function RootLayout() {
+  return (
+    <GlobalSearchProvider>
+      <div className="dark min-h-screen bg-gray-950 text-gray-100 flex">
+        <Sidebar />
+        {/* ... */}
+      </div>
+    </GlobalSearchProvider>
+  );
+}
+```
+
+### 7. Update milestones.tsx to use useFilteredData
+
+Wire the filter and search hooks into the milestones page:
+
+- Add FilterBar above the table/tree views
+- Use `useFilteredData` to get filtered milestones
+- Pass filtered data to MilestoneTable and MilestoneTree
+- When filters result in empty data, show "No milestones match your filters" message
+
+### 8. Update `app/routes/search.tsx`
+
+Build the dedicated search results page:
+
+- Shows search results grouped by milestone
+- Each group shows the milestone name as a header, with matching tasks listed below
+- Highlights which part of the result matched (milestone name vs task name/notes)
+- Shows total result count
+- Empty state: "No results found for '{query}'" with suggestion to try different terms
+- Links to navigate to the milestone/task in the main views
+
+---
+
+## Verification
+
+- [ ] Search finds milestones by name (exact and partial match)
+- [ ] Search finds tasks by name (exact and partial match)
+- [ ] Fuzzy matching works (typos like "milstone" still match "milestone")
+- [ ] Status filter narrows results to only matching status items
+- [ ] Combined search + filter works (e.g., search "auth" + filter "in_progress")
+- [ ] Filter state persists when switching between table and tree views
+- [ ] Search query persists when navigating between routes
+- [ ] SearchBar in sidebar is debounced (no lag while typing)
+- [ ] Pressing Escape in SearchBar clears the query
+- [ ] Search results page shows grouped results by milestone
+- [ ] Empty state shows appropriate message when no results found
+- [ ] GlobalSearchProvider wraps the entire app in root layout
+
+---
+
+## Expected Output
+
+**File Structure**:
+```
+app/
+├── components/
+│   ├── FilterBar.tsx (new)
+│   └── SearchBar.tsx (new)
+├── contexts/
+│   └── GlobalSearchContext.tsx (new)
+├── lib/
+│   ├── search.ts (new)
+│   └── useFilteredData.ts (new)
+├── routes/
+│   ├── __root.tsx (updated)
+│   ├── milestones.tsx (updated)
+│   └── search.tsx (updated)
+```
+
+**Key Files Created/Modified**:
+- `app/lib/search.ts`: Fuse.js search index builder and query functions
+- `app/contexts/GlobalSearchContext.tsx`: Global search state with pub/sub pattern
+- `app/lib/useFilteredData.ts`: Hook composing status filter and search query
+- `app/components/FilterBar.tsx`: Pill-style status toggle buttons
+- `app/components/SearchBar.tsx`: Search input for sidebar with debounce
+- `app/routes/__root.tsx`: Updated to include GlobalSearchProvider
+- `app/routes/milestones.tsx`: Updated to use useFilteredData and FilterBar
+- `app/routes/search.tsx`: Updated with grouped search results page
+
+---
+
+## Notes
+
+- fuse.js should already be installed from Task 1; verify with `npm ls fuse.js`
+- The 300ms debounce on SearchBar prevents excessive re-filtering on every keystroke
+- GlobalSearchContext uses useRef-based pub/sub (not useState in context) to avoid re-rendering the entire tree when search state changes — only subscribed components re-render
+- The search index is rebuilt when progress data changes (e.g., on auto-refresh)
+- Status filter values must match the status strings in progress.yaml exactly
+
+---
+
+**Next Task**: [Task 10: Polish & Integration Testing](./task-10-polish-integration-testing.md)
+**Related Design Docs**: [Search & Filtering](../../design/local.search-filtering.md)
+**Estimated Completion Date**: TBD

package/agent/tasks/task-1-{title}.template.md

@@ -0,0 +1,244 @@
+# Task {N}: {Descriptive Task Name}
+
+**Milestone**: [M{N} - Milestone Name](../milestones/milestone-{N}-{name}.md)
+**Design Reference**: [{Design Name}](../design/{namespace}.{design-name}.md) | None
+**Estimated Time**: [e.g., "2 hours", "4 hours", "1 day"]
+**Dependencies**: [List prerequisite tasks, or "None"]
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Objective
+
+[Clearly state what this task accomplishes. Be specific and focused on a single, achievable goal.]
+
+**Example**: "Create the basic project structure with all necessary configuration files and directory organization for a TypeScript-based MCP server."
+
+---
+
+## Context
+
+[Provide background information that helps understand why this task is necessary and how it fits into the larger milestone.]
+
+**Example**: "This task establishes the foundation for the project. Without proper structure and configuration, subsequent development tasks cannot proceed. The structure follows industry best practices for TypeScript projects and MCP server organization."
+
+---
+
+## Steps
+
+[Provide a detailed, sequential list of actions to complete this task. Each step should be concrete and actionable.]
+
+### 1. [Step Category or Action]
+[Detailed description of what to do]
+
+```bash
+# Command examples if applicable
+command --with-flags
+```
+
+```typescript
+// Code examples if applicable
+const example = "code";
+```
+
+### 2. [Next Step]
+[Detailed description]
+
+### 3. [Next Step]
+[Detailed description]
+
+**Example**:
+
+### 1. Create Project Directory
+Create the root directory for the project and navigate into it:
+
+```bash
+mkdir -p my-project
+cd my-project
+```
+
+### 2. Initialize npm Project
+Initialize a new npm project with default settings:
+
+```bash
+npm init -y
+```
+
+### 3. Update package.json
+Edit the generated package.json to include proper metadata and scripts:
+
+```json
+{
+  "name": "my-project",
+  "version": "0.1.0",
+  "description": "Description of what this project does",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "node esbuild.build.js",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["mcp", "relevant", "keywords"],
+  "author": "Your Name",
+  "license": "MIT"
+}
+```
+
+### 4. Create Directory Structure
+Create all necessary directories:
+
+```bash
+mkdir -p src/{types,utils,tools}
+mkdir -p tests/{unit,integration}
+mkdir -p agent/{design,milestones,patterns,tasks}
+```
+
+### 5. Create Configuration Files
+Create TypeScript configuration, build scripts, and other config files.
+
+**tsconfig.json**:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+[Continue with other config files...]
+
+---
+
+## Verification
+
+[Provide a checklist of items to verify the task is complete. Each item should be objectively verifiable.]
+
+- [ ] Verification item 1: [Specific condition to check]
+- [ ] Verification item 2: [Specific condition to check]
+- [ ] Verification item 3: [Specific condition to check]
+- [ ] Verification item 4: [Specific condition to check]
+- [ ] Verification item 5: [Specific condition to check]
+
+**Example**:
+- [ ] Project directory created and contains expected subdirectories
+- [ ] package.json exists and contains correct metadata
+- [ ] tsconfig.json exists and is valid JSON
+- [ ] All configuration files created (.gitignore, .env.example, etc.)
+- [ ] Directory structure matches specification
+- [ ] No syntax errors in configuration files
+
+---
+
+## Expected Output
+
+[Describe what the project should look like after this task is complete.]
+
+**File Structure**:
+```
+project-root/
+├── file1
+├── file2
+└── directory/
+    └── file3
+```
+
+**Key Files Created**:
+- `file1`: [Purpose]
+- `file2`: [Purpose]
+- `directory/file3`: [Purpose]
+
+---
+
+## Key Design Decisions (Optional)
+
+<!-- This section is populated by @acp.clarification-capture when
+     create commands are invoked with --from-clar, --from-chat, or
+     --from-context. It can also be manually authored.
+     Omit this section entirely if no decisions to capture.
+
+     Group decisions by agent-inferred category using tables:
+
+### {Category}
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| {decision} | {choice} | {rationale} |
+-->
+
+---
+
+## Common Issues and Solutions
+
+[Document potential problems and how to resolve them:]
+
+### Issue 1: [Problem description]
+**Symptom**: [What the user will see]
+**Solution**: [How to fix it]
+
+### Issue 2: [Problem description]
+**Symptom**: [What the user will see]
+**Solution**: [How to fix it]
+
+**Example**:
+
+### Issue 1: npm init fails
+**Symptom**: Error message about permissions or missing npm
+**Solution**: Ensure Node.js and npm are installed correctly. Run `node --version` and `npm --version` to verify.
+
+### Issue 2: TypeScript configuration errors
+**Symptom**: tsc complains about invalid configuration
+**Solution**: Validate JSON syntax in tsconfig.json. Ensure all required fields are present.
+
+---
+
+## Resources
+
+[Link to relevant documentation, examples, or references:]
+
+- [Resource 1 Name](URL): Description
+- [Resource 2 Name](URL): Description
+- [Resource 3 Name](URL): Description
+
+**Example**:
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/): Official TypeScript documentation
+- [esbuild Documentation](https://esbuild.github.io/): Build tool documentation
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk): MCP protocol reference
+
+---
+
+## Notes
+
+[Any additional context, warnings, or considerations:]
+
+- Note 1: [Important information]
+- Note 2: [Important information]
+- Note 3: [Important information]
+
+**Example**:
+- This task creates the foundation for all subsequent work
+- Configuration files may need adjustment based on specific project requirements
+- Keep .env files out of version control (ensure .gitignore is correct)
+
+---
+
+**Next Task**: [Link to next task: task-{N+1}-{name}.md]
+**Related Design Docs**: [Links to relevant design documents]
+**Estimated Completion Date**: [YYYY-MM-DD or "TBD"]

package/bin/visualize.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from 'path'
+import { existsSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { spawn } from 'child_process'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(__dirname, '..')
+
+// Parse args
+const args = process.argv.slice(2)
+let progressPath = null
+let port = '3400'
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--port' || args[i] === '-p') {
+    port = args[++i]
+  } else if (args[i] === '--help' || args[i] === '-h') {
+    console.log(`
+  ACP Progress Visualizer
+
+  Usage:
+    npx @prmichaelsen/acp-visualizer [options] [path]
+
+  Arguments:
+    path                  Path to progress.yaml (default: ./agent/progress.yaml)
+
+  Options:
+    -p, --port <port>     Port to run on (default: 3400)
+    -h, --help            Show this help message
+
+  Examples:
+    npx @prmichaelsen/acp-visualizer
+    npx @prmichaelsen/acp-visualizer ./agent/progress.yaml
+    npx @prmichaelsen/acp-visualizer --port 4000
+    npx @prmichaelsen/acp-visualizer /path/to/other/progress.yaml
+`)
+    process.exit(0)
+  } else if (!args[i].startsWith('-')) {
+    progressPath = args[i]
+  }
+}
+
+// Resolve progress.yaml path
+if (!progressPath) {
+  progressPath = resolve(process.cwd(), 'agent/progress.yaml')
+} else {
+  progressPath = resolve(process.cwd(), progressPath)
+}
+
+if (!existsSync(progressPath)) {
+  console.error(`\n  Error: progress.yaml not found at: ${progressPath}\n`)
+  console.error(`  Make sure you're in an ACP project directory, or pass the path explicitly:\n`)
+  console.error(`    npx @prmichaelsen/acp-visualizer /path/to/agent/progress.yaml\n`)
+  process.exit(1)
+}
+
+console.log(`\n  ACP Progress Visualizer`)
+console.log(`  Loading: ${progressPath}`)
+console.log(`  Port:    ${port}\n`)
+
+// Start vite dev server from the package directory
+const child = spawn('npx', ['vite', 'dev', '--port', port, '--host'], {
+  cwd: packageRoot,
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    PROGRESS_YAML_PATH: progressPath,
+  },
+})
+
+child.on('error', (err) => {
+  console.error('Failed to start dev server:', err.message)
+  process.exit(1)
+})
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0)
+})
+
+// Forward signals for clean shutdown
+process.on('SIGINT', () => child.kill('SIGINT'))
+process.on('SIGTERM', () => child.kill('SIGTERM'))

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@prmichaelsen/acp-visualizer",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Browser-based dashboard for visualizing ACP progress.yaml data",
+  "bin": {
+    "acp-visualizer": "./bin/visualize.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "agent/",
+    "vite.config.ts",
+    "tsconfig.json",
+    "vitest.config.ts"
+  ],
+  "scripts": {
+    "dev": "vite dev --port 3400 --host",
+    "build": "vite build",
+    "serve": "vite preview",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.0.6",
+    "@tanstack/react-router": "^1.132.0",
+    "@tanstack/react-start": "^1.132.0",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/router-plugin": "^1.132.0",
+    "fuse.js": "^7.1.0",
+    "js-yaml": "^4.1.0",
+    "lucide-react": "^0.544.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.6",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^5.0.4",
+    "typescript": "^5.7.2",
+    "vite": "^7.1.7",
+    "vitest": "^4.0.18"
+  }
+}

package/src/components/ExtraFieldsBadge.tsx

@@ -0,0 +1,15 @@
+import type { ExtraFields } from '@/lib/types'
+
+export function ExtraFieldsBadge({ fields }: { fields: ExtraFields }) {
+  const count = Object.keys(fields).length
+  if (count === 0) return null
+
+  return (
+    <span
+      className="text-xs text-gray-600 bg-gray-800 px-1.5 py-0.5 rounded cursor-help"
+      title={JSON.stringify(fields, null, 2)}
+    >
+      +{count}
+    </span>
+  )
+}

package/src/components/FilterBar.tsx

@@ -0,0 +1,33 @@
+import type { Status } from '@/lib/types'
+
+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' },
+]
+
+interface FilterBarProps {
+  status: Status | 'all'
+  onStatusChange: (status: Status | 'all') => void
+}
+
+export function FilterBar({ status, onStatusChange }: FilterBarProps) {
+  return (
+    <div className="flex gap-1 p-1 bg-gray-800/50 rounded-lg">
+      {statusOptions.map((opt) => (
+        <button
+          key={opt.value}
+          onClick={() => onStatusChange(opt.value)}
+          className={`px-3 py-1 text-xs rounded-md transition-colors ${
+            status === opt.value
+              ? 'bg-gray-700 text-gray-100 shadow-sm'
+              : 'text-gray-500 hover:text-gray-300'
+          }`}
+        >
+          {opt.label}
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/components/Header.tsx

@@ -0,0 +1,23 @@
+import { StatusBadge } from './StatusBadge'
+import { ProgressBar } from './ProgressBar'
+import type { ProgressData } from '@/lib/types'
+
+interface HeaderProps {
+  data: ProgressData | null
+}
+
+export function Header({ data }: HeaderProps) {
+  if (!data) return null
+
+  return (
+    <header className="h-14 border-b border-gray-800 flex items-center px-6 gap-4 shrink-0">
+      <h1 className="text-sm font-medium text-gray-200">{data.project.name}</h1>
+      <span className="text-xs text-gray-500 font-mono">v{data.project.version}</span>
+      <StatusBadge status={data.project.status} />
+      <div className="ml-auto flex items-center gap-3 w-48">
+        <ProgressBar value={data.progress.overall} size="sm" />
+        <span className="text-xs text-gray-400 font-mono">{data.progress.overall}%</span>
+      </div>
+    </header>
+  )
+}