@prmichaelsen/acp-visualizer 0.1.0

package/agent/scripts/acp.yaml-validate.sh

@@ -0,0 +1,205 @@
+#!/bin/bash
+# ACP YAML Schema Validator
+# Pure bash YAML validation against schema definitions
+# Zero external dependencies
+
+# Source YAML parser (using new generic AST-based parser)
+SCRIPT_DIR="$(dirname "$0")"
+. "${SCRIPT_DIR}/acp.yaml-parser.sh"
+. "${SCRIPT_DIR}/acp.common.sh"
+
+# Initialize colors
+init_colors
+
+# Validation error tracking
+VALIDATION_ERRORS=0
+VALIDATION_WARNINGS=0
+
+# Add validation error
+# Usage: add_error "Error message"
+add_error() {
+    echo "${RED}❌ $1${NC}" >&2
+    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
+}
+
+# Add validation warning
+# Usage: add_warning "Warning message"
+add_warning() {
+    echo "${YELLOW}⚠️  $1${NC}" >&2
+    VALIDATION_WARNINGS=$((VALIDATION_WARNINGS + 1))
+}
+
+# Validate field exists
+# Usage: validate_field_exists "file.yaml" "field.path"
+validate_field_exists() {
+    local yaml_file="$1"
+    local field_path="$2"
+    
+    if ! yaml_has_key "$yaml_file" "$field_path"; then
+        return 1
+    fi
+    return 0
+}
+
+# Validate string pattern (regex)
+# Usage: validate_pattern "value" "pattern" "field_name"
+validate_pattern() {
+    local value="$1"
+    local pattern="$2"
+    local field_name="$3"
+    
+    if ! echo "$value" | grep -qE "$pattern"; then
+        return 1
+    fi
+    return 0
+}
+
+# Validate string length
+# Usage: validate_length "value" min max "field_name"
+validate_length() {
+    local value="$1"
+    local min="$2"
+    local max="$3"
+    local field_name="$4"
+    
+    local length=${#value}
+    
+    if [ -n "$min" ] && [ "$length" -lt "$min" ]; then
+        add_error "Field '$field_name': Too short (minimum $min characters, got $length)"
+        return 1
+    fi
+    
+    if [ -n "$max" ] && [ "$length" -gt "$max" ]; then
+        add_error "Field '$field_name': Too long (maximum $max characters, got $length)"
+        return 1
+    fi
+    
+    return 0
+}
+
+# Validate package.yaml file
+# Usage: validate_package_yaml "package.yaml"
+# Returns: 0 if valid, 1 if invalid
+validate_package_yaml() {
+    local yaml_file="$1"
+    
+    if [ ! -f "$yaml_file" ]; then
+        add_error "File not found: $yaml_file"
+        return 1
+    fi
+    
+    echo "${BLUE}Validating $yaml_file...${NC}"
+    echo ""
+    
+    # Check YAML syntax (try to parse)
+    if ! yaml_get "$yaml_file" "name" >/dev/null 2>&1; then
+        add_error "Invalid YAML syntax in $yaml_file"
+        return 1
+    fi
+    
+    # Validate required fields
+    local required_fields="name version description author license repository"
+    for field in $required_fields; do
+        if ! validate_field_exists "$yaml_file" "$field"; then
+            add_error "Required field missing: '$field'"
+        fi
+    done
+    
+    # Validate name field
+    if validate_field_exists "$yaml_file" "name"; then
+        local name=$(yaml_get "$yaml_file" "name")
+        if ! validate_pattern "$name" "^[a-z0-9-]+$" "name"; then
+            add_error "Field 'name': Must be lowercase letters, numbers, and hyphens only (got: '$name')"
+        fi
+        
+        # Check reserved names
+        case "$name" in
+            acp|local|core|system|global)
+                add_error "Field 'name': '$name' is a reserved package name"
+                ;;
+        esac
+    fi
+    
+    # Validate version field
+    if validate_field_exists "$yaml_file" "version"; then
+        local version=$(yaml_get "$yaml_file" "version")
+        if ! validate_pattern "$version" "^[0-9]+\\.[0-9]+\\.[0-9]+$" "version"; then
+            add_error "Field 'version': Must be semantic version format X.Y.Z (got: '$version')"
+        fi
+    fi
+    
+    # Validate description field
+    if validate_field_exists "$yaml_file" "description"; then
+        local description=$(yaml_get "$yaml_file" "description")
+        validate_length "$description" 10 200 "description"
+    fi
+    
+    # Validate author field
+    if validate_field_exists "$yaml_file" "author"; then
+        local author=$(yaml_get "$yaml_file" "author")
+        validate_length "$author" 2 "" "author"
+    fi
+    
+    # Validate repository field
+    if validate_field_exists "$yaml_file" "repository"; then
+        local repository=$(yaml_get "$yaml_file" "repository")
+        if ! validate_pattern "$repository" "^https?://.*\\.git$" "repository"; then
+            add_error "Field 'repository': Must be a git URL ending with .git (got: '$repository')"
+        fi
+    fi
+    
+    # Validate homepage field (optional)
+    if validate_field_exists "$yaml_file" "homepage"; then
+        local homepage=$(yaml_get "$yaml_file" "homepage")
+        if ! validate_pattern "$homepage" "^https?://.*" "homepage"; then
+            add_error "Field 'homepage': Must be a valid HTTP/HTTPS URL (got: '$homepage')"
+        fi
+    fi
+    
+    # Validate contents field (required) - use grep since yaml_has_key may not work for nested objects
+    if ! grep -q "^contents:" "$yaml_file"; then
+        add_error "Required field missing: 'contents'"
+    fi
+    
+    # Validate requires.acp field (optional)
+    if validate_field_exists "$yaml_file" "requires.acp"; then
+        local acp_version=$(yaml_get "$yaml_file" "requires.acp")
+        if ! validate_pattern "$acp_version" "^>=?[0-9]+\\.[0-9]+\\.[0-9]+$" "requires.acp"; then
+            add_error "Field 'requires.acp': Must be version constraint like '>=2.0.0' (got: '$acp_version')"
+        fi
+    fi
+    
+    # Report results
+    echo ""
+    if [ "$VALIDATION_ERRORS" -eq 0 ]; then
+        echo "${GREEN}✅ Validation passed${NC}"
+        if [ "$VALIDATION_WARNINGS" -gt 0 ]; then
+            echo "${YELLOW}⚠️  $VALIDATION_WARNINGS warning(s)${NC}"
+        fi
+        return 0
+    else
+        echo "${RED}❌ Validation failed${NC}"
+        echo "${RED}   $VALIDATION_ERRORS error(s)${NC}"
+        if [ "$VALIDATION_WARNINGS" -gt 0 ]; then
+            echo "${YELLOW}   $VALIDATION_WARNINGS warning(s)${NC}"
+        fi
+        return 1
+    fi
+}
+
+# Main function for standalone execution
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+    # Script is being executed directly
+    if [ $# -eq 0 ]; then
+        echo "Usage: $0 <yaml-file>"
+        echo ""
+        echo "Example:"
+        echo "  $0 package.yaml"
+        exit 1
+    fi
+    
+    validate_package_yaml "$1"
+    exit $?
+fi
+
+# Script is being sourced, functions are available

package/agent/tasks/milestone-1-project-scaffold-data-pipeline/task-1-initialize-tanstack-start-project.md

@@ -0,0 +1,210 @@
+# Task 1: Initialize TanStack Start Project
+
+**Milestone**: [M1 - Project Scaffold & Data Pipeline](../../milestones/milestone-1-project-scaffold-data-pipeline.md)
+**Design Reference**: [Dashboard Layout & Routing](../../design/local.dashboard-layout-routing.md)
+**Estimated Time**: 2 hours
+**Dependencies**: None
+**Status**: Not Started
+
+---
+
+## Objective
+
+Scaffold a TanStack Start project with Vite, React, TanStack Router, and Tailwind CSS. Configure design tokens for the admin dashboard theme. This establishes the foundational build toolchain and styling system that all subsequent tasks build upon.
+
+---
+
+## Context
+
+The ACP Progress Visualizer is a TanStack Start application that renders progress.yaml data as an interactive admin dashboard. This first task creates the project skeleton with all P0 dependencies installed and Tailwind configured with the project's design token palette (status colors, typography, dark theme). Without this foundation, no UI or data pipeline work can proceed.
+
+---
+
+## Steps
+
+### 1. Scaffold the TanStack Start project
+
+Run the TanStack Start scaffolding tool or manually initialize the project structure:
+
+```bash
+npm create @tanstack/start@latest
+```
+
+If scaffolding manually, create a `package.json` with the project name and set `"type": "module"`.
+
+### 2. Install dependencies
+
+Install all P0 dependencies required for the visualizer:
+
+```bash
+npm install @tanstack/react-router @tanstack/react-start @tanstack/react-table react react-dom
+npm install tailwindcss postcss autoprefixer lucide-react js-yaml fuse.js
+npm install -D @types/react @types/react-dom @types/js-yaml typescript vite
+```
+
+### 3. Configure Tailwind with custom design tokens
+
+Initialize Tailwind and configure the theme in `tailwind.config.ts`:
+
+```bash
+npx tailwindcss init -p --ts
+```
+
+Add custom design tokens to the Tailwind config:
+
+```typescript
+// tailwind.config.ts
+import type { Config } from "tailwindcss";
+
+export default {
+  content: ["./app/**/*.{ts,tsx}"],
+  darkMode: "class",
+  theme: {
+    extend: {
+      colors: {
+        status: {
+          completed: "#22c55e",   // green-500
+          in_progress: "#3b82f6", // blue-500
+          not_started: "#6b7280", // gray-500
+          blocked: "#ef4444",     // red-500
+          skipped: "#a855f7",     // purple-500
+        },
+      },
+      fontFamily: {
+        sans: ["Inter", "system-ui", "sans-serif"],
+        mono: ["JetBrains Mono", "monospace"],
+      },
+    },
+  },
+  plugins: [],
+} satisfies Config;
+```
+
+### 4. Create the root layout
+
+Create `app/routes/__root.tsx` with a minimal root layout that includes the dark theme class and global styles:
+
+```typescript
+// app/routes/__root.tsx
+import { createRootRoute, Outlet } from "@tanstack/react-router";
+
+export const Route = createRootRoute({
+  component: RootLayout,
+});
+
+function RootLayout() {
+  return (
+    <div className="dark min-h-screen bg-gray-950 text-gray-100">
+      <Outlet />
+    </div>
+  );
+}
+```
+
+### 5. Create the index route
+
+Create `app/routes/index.tsx` with placeholder content to verify the app renders:
+
+```typescript
+// app/routes/index.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/")({
+  component: HomePage,
+});
+
+function HomePage() {
+  return (
+    <div className="p-8">
+      <h1 className="text-2xl font-bold font-sans">
+        ACP Progress Visualizer
+      </h1>
+      <p className="mt-2 text-gray-400 font-mono text-sm">
+        Dashboard loading...
+      </p>
+    </div>
+  );
+}
+```
+
+### 6. Create TanStack Start configuration
+
+Create `app.config.ts` for TanStack Start:
+
+```typescript
+// app.config.ts
+import { defineConfig } from "@tanstack/react-start/config";
+import viteTsConfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  vite: {
+    plugins: [viteTsConfigPaths()],
+  },
+});
+```
+
+### 7. Verify dev server starts
+
+Run the development server and confirm the app loads without errors:
+
+```bash
+npm run dev
+```
+
+Open the browser to the local dev URL and verify the placeholder content renders with correct fonts and dark theme styling.
+
+---
+
+## Verification
+
+- [ ] `package.json` exists with all P0 dependencies listed
+- [ ] `tailwind.config.ts` exists and contains status color tokens (completed, in_progress, not_started, blocked, skipped)
+- [ ] `tailwind.config.ts` specifies Inter for sans and JetBrains Mono for mono font families
+- [ ] `app/routes/__root.tsx` exists with dark theme wrapper and `<Outlet />`
+- [ ] `app/routes/index.tsx` exists with placeholder content
+- [ ] `app.config.ts` exists with TanStack Start configuration
+- [ ] `npm run dev` starts without errors
+- [ ] Root route renders in the browser with dark background and light text
+
+---
+
+## Expected Output
+
+**File Structure**:
+```
+project-root/
+├── app/
+│   ├── routes/
+│   │   ├── __root.tsx
+│   │   └── index.tsx
+│   └── styles/
+│       └── globals.css
+├── app.config.ts
+├── tailwind.config.ts
+├── postcss.config.js
+├── tsconfig.json
+├── package.json
+└── package-lock.json
+```
+
+**Key Files Created**:
+- `package.json`: Project manifest with all P0 dependencies
+- `tailwind.config.ts`: Tailwind configuration with status colors and typography tokens
+- `app/routes/__root.tsx`: Root layout with dark theme wrapper
+- `app/routes/index.tsx`: Index route with placeholder content
+- `app.config.ts`: TanStack Start build configuration
+
+---
+
+## Notes
+
+- Dark theme is the default and only theme for this project; no light mode toggle is planned
+- The `lucide-react` icon library is installed now but used in later tasks for sidebar and status icons
+- `fuse.js` and `@tanstack/react-table` are installed now to avoid dependency churn in later milestones
+- If `npm create @tanstack/start@latest` output differs from expected, adjust file locations to match the scaffolding output
+
+---
+
+**Next Task**: [Task 2: Implement Data Model & YAML Parser](./task-2-implement-data-model-yaml-parser.md)
+**Related Design Docs**: [Dashboard Layout & Routing](../../design/local.dashboard-layout-routing.md)
+**Estimated Completion Date**: TBD

package/agent/tasks/milestone-1-project-scaffold-data-pipeline/task-2-implement-data-model-yaml-parser.md

@@ -0,0 +1,294 @@
+# Task 2: Implement Data Model & YAML Parser
+
+**Milestone**: [M1 - Project Scaffold & Data Pipeline](../../milestones/milestone-1-project-scaffold-data-pipeline.md)
+**Design Reference**: [Data Model & YAML Parsing](../../design/local.data-model-yaml-parsing.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Task 1
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create TypeScript interfaces for progress.yaml data and a lenient YAML parser that handles agent-maintained YAML with drift tolerance. The parser must gracefully handle missing fields, unknown keys, status aliases, and type coercion so the dashboard never crashes on imperfect YAML.
+
+---
+
+## Context
+
+The progress.yaml file is maintained by AI agents and tends to drift from a strict schema over time. Fields get renamed, statuses use informal terms ("done" instead of "completed"), single strings appear where arrays are expected, and unknown fields accumulate. The parser must be maximally tolerant: extract what it can, preserve unknown fields in an `extra` bag, normalize statuses and field names, and return safe defaults for anything missing. This approach ensures the dashboard always renders something useful rather than crashing on schema violations.
+
+---
+
+## Steps
+
+### 1. Create TypeScript interfaces
+
+Create `app/lib/types.ts` with all data model interfaces:
+
+```typescript
+// app/lib/types.ts
+
+export type Status = "completed" | "in_progress" | "not_started" | "blocked" | "skipped";
+
+export interface ExtraFields {
+  [key: string]: unknown;
+}
+
+export interface ProjectMetadata {
+  name: string;
+  description: string;
+  version: string;
+  repository: string;
+  extra: ExtraFields;
+}
+
+export interface WorkEntry {
+  date: string;
+  task: string;
+  hours: number;
+  notes: string;
+  extra: ExtraFields;
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  status: Status;
+  estimated_hours: number;
+  actual_hours: number;
+  dependencies: string[];
+  tags: string[];
+  notes: string;
+  extra: ExtraFields;
+}
+
+export interface Milestone {
+  id: string;
+  title: string;
+  status: Status;
+  target_date: string;
+  tasks: Task[];
+  extra: ExtraFields;
+}
+
+export interface DocumentationStats {
+  design_docs: number;
+  task_docs: number;
+  patterns: number;
+  clarifications: number;
+  extra: ExtraFields;
+}
+
+export interface ProgressSummary {
+  total_tasks: number;
+  completed_tasks: number;
+  completion_percentage: number;
+  total_hours_estimated: number;
+  total_hours_actual: number;
+  extra: ExtraFields;
+}
+
+export interface ProgressData {
+  project: ProjectMetadata;
+  milestones: Milestone[];
+  work_entries: WorkEntry[];
+  documentation: DocumentationStats;
+  progress: ProgressSummary;
+  extra: ExtraFields;
+}
+```
+
+### 2. Create the YAML loader module
+
+Create `app/lib/yaml-loader.ts` with the main `parseProgressYaml` function:
+
+```typescript
+// app/lib/yaml-loader.ts
+import yaml from "js-yaml";
+import type { ProgressData } from "./types";
+
+export function parseProgressYaml(raw: string): ProgressData {
+  // Implementation in subsequent steps
+}
+```
+
+### 3. Implement the `extractKnown` helper
+
+This utility separates known fields from extras, which is the foundation of drift tolerance:
+
+```typescript
+function extractKnown<T extends Record<string, unknown>>(
+  obj: Record<string, unknown>,
+  knownKeys: string[]
+): { known: Partial<T>; extra: Record<string, unknown> } {
+  const known: Record<string, unknown> = {};
+  const extra: Record<string, unknown> = {};
+  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 };
+}
+```
+
+### 4. Implement `normalizeStatus`
+
+Map informal status strings to canonical Status values using fuzzy matching:
+
+```typescript
+function normalizeStatus(raw: unknown): Status {
+  if (typeof raw !== "string") return "not_started";
+  const s = raw.toLowerCase().trim().replace(/[\s-]/g, "_");
+  const aliases: Record<string, Status> = {
+    done: "completed",
+    complete: "completed",
+    completed: "completed",
+    finished: "completed",
+    active: "in_progress",
+    wip: "in_progress",
+    in_progress: "in_progress",
+    working: "in_progress",
+    started: "in_progress",
+    pending: "not_started",
+    not_started: "not_started",
+    todo: "not_started",
+    queued: "not_started",
+    blocked: "blocked",
+    stuck: "blocked",
+    waiting: "blocked",
+    skipped: "skipped",
+    dropped: "skipped",
+    deferred: "skipped",
+  };
+  return aliases[s] ?? "not_started";
+}
+```
+
+### 5. Implement key alias maps
+
+Create alias maps so renamed fields still parse correctly:
+
+```typescript
+const TASK_KEY_ALIASES: Record<string, string> = {
+  est_hours: "estimated_hours",
+  estimated: "estimated_hours",
+  actual: "actual_hours",
+  act_hours: "actual_hours",
+  deps: "dependencies",
+  depends_on: "dependencies",
+  name: "title",
+};
+
+const MILESTONE_KEY_ALIASES: Record<string, string> = {
+  name: "title",
+  target: "target_date",
+  due_date: "target_date",
+  deadline: "target_date",
+};
+```
+
+### 6. Implement `normalizeStringArray`
+
+Handle cases where a single string appears instead of an array:
+
+```typescript
+function normalizeStringArray(raw: unknown): string[] {
+  if (Array.isArray(raw)) return raw.map(String);
+  if (typeof raw === "string") return [raw];
+  return [];
+}
+```
+
+### 7. Implement entity normalizers
+
+Create normalizer functions for each entity type:
+
+- `normalizeProject(raw: unknown): ProjectMetadata` — extracts name, description, version, repository with string defaults
+- `normalizeMilestones(raw: unknown): Milestone[]` — iterates array, applies key aliases, normalizes status and tasks
+- `normalizeTasks(raw: unknown): Task[]` — iterates array, applies key aliases, normalizes status, coerces string arrays for deps/tags
+- `normalizeWorkEntries(raw: unknown): WorkEntry[]` — iterates array, coerces hours to number, defaults date/task/notes
+- `normalizeDocStats(raw: unknown): DocumentationStats` — extracts numeric counts with 0 defaults
+- `normalizeProgress(raw: unknown): ProgressSummary` — extracts numeric summary fields with 0 defaults
+
+Each normalizer should use `extractKnown` to separate known fields from extras.
+
+### 8. Implement top-level parser with fallback
+
+Wire up `parseProgressYaml`:
+
+```typescript
+export function parseProgressYaml(raw: string): ProgressData {
+  try {
+    const doc = yaml.load(raw) as Record<string, unknown> | null;
+    if (!doc || typeof doc !== "object") {
+      return emptyProgressData();
+    }
+    return {
+      project: normalizeProject(doc.project),
+      milestones: normalizeMilestones(doc.milestones),
+      work_entries: normalizeWorkEntries(doc.work_entries ?? doc.work_log),
+      documentation: normalizeDocStats(doc.documentation ?? doc.docs),
+      progress: normalizeProgress(doc.progress ?? doc.summary),
+      extra: extractTopLevelExtra(doc),
+    };
+  } catch {
+    return emptyProgressData();
+  }
+}
+```
+
+### 9. Write unit tests
+
+Create `app/lib/__tests__/yaml-loader.test.ts` with tests covering:
+
+- Complete valid YAML parses correctly
+- Missing sections default gracefully (empty arrays, zero counts)
+- Unknown fields preserved in `extra`
+- Status aliases resolve correctly (`"done"` becomes `"completed"`, `"wip"` becomes `"in_progress"`)
+- Single string coerced to array for dependencies and tags
+- Key aliases work (`est_hours` becomes `estimated_hours`)
+- Completely invalid YAML returns empty ProgressData (no crash)
+- Empty string input returns empty ProgressData
+
+---
+
+## Verification
+
+- [ ] `app/lib/types.ts` exports all interfaces: Status, ExtraFields, ProgressData, ProjectMetadata, Milestone, Task, WorkEntry, DocumentationStats, ProgressSummary
+- [ ] `app/lib/yaml-loader.ts` exports `parseProgressYaml` function
+- [ ] Parser handles complete YAML and returns fully populated ProgressData
+- [ ] Parser handles incomplete YAML with missing sections (defaults to empty arrays/zero counts)
+- [ ] Unknown fields are preserved in `extra` objects at every level
+- [ ] Status aliases resolve correctly (done, wip, active, pending, stuck, etc.)
+- [ ] Single string values coerced to arrays for dependencies and tags
+- [ ] Key aliases resolve correctly (est_hours, deps, name, etc.)
+- [ ] Completely invalid YAML returns empty ProgressData without throwing
+- [ ] All unit tests pass
+
+---
+
+## Expected Output
+
+**Key Files Created**:
+- `app/lib/types.ts`: TypeScript interfaces for the entire progress.yaml data model
+- `app/lib/yaml-loader.ts`: Lenient YAML parser with drift tolerance
+- `app/lib/__tests__/yaml-loader.test.ts`: Unit tests for the parser
+
+---
+
+## Notes
+
+- The parser is intentionally lenient; it should never throw. Any error results in a fallback empty ProgressData
+- The `extra` field pattern is critical: it allows the dashboard to display fields the schema does not yet know about, which is essential for agent-maintained YAML that evolves over time
+- Status normalization covers common agent shorthand; new aliases can be added as they are discovered
+- Key alias maps should be extended if agents consistently use non-standard field names
+
+---
+
+**Next Task**: [Task 3: Build Server API & Data Loading](./task-3-build-server-api-data-loading.md)
+**Related Design Docs**: [Data Model & YAML Parsing](../../design/local.data-model-yaml-parsing.md)
+**Estimated Completion Date**: TBD