@prmichaelsen/acp-visualizer 0.1.0

package/agent/patterns/tanstack-cloudflare.zod-schema-validation.md

@@ -0,0 +1,336 @@
+# Zod Schema Validation Pattern
+
+**Category**: Architecture
+**Applicable To**: TanStack Start + Cloudflare Workers applications with typed data models
+**Status**: Stable
+
+---
+
+## Overview
+
+All data models are defined as Zod schemas in a centralized `src/schemas/` directory. Schemas serve as the single source of truth for data shape, validation, and TypeScript types. Types are derived from schemas using `z.infer<>`, ensuring runtime validation and compile-time types are always in sync.
+
+This pattern ensures data integrity at every boundary: API request bodies are validated on entry, database documents are validated on read, and all types flow from the schema definitions.
+
+---
+
+## When to Use This Pattern
+
+✅ **Use this pattern when:**
+- Building applications with structured data models
+- Need runtime validation at system boundaries (API inputs, database reads)
+- Want TypeScript types derived from a single source of truth
+- Working with Firestore or other schemaless databases
+- Need separate schemas for create, update, and read operations
+
+❌ **Don't use this pattern when:**
+- Working with trivial data (single primitive values)
+- Using an ORM that handles validation (Prisma, Drizzle)
+- Performance-critical hot paths where validation overhead matters
+
+---
+
+## Core Principles
+
+1. **Single Source of Truth**: Zod schemas define data shape; TypeScript types are derived, not hand-written
+2. **Centralized Schemas Directory**: All schemas live in `src/schemas/`, organized by domain
+3. **Separate CRUD Schemas**: Separate schemas for create input, update input, and full entity
+4. **Path-Based Documentation**: Schema files document where data is stored (Firestore path in JSDoc)
+5. **Safe Parse in Services**: Use `safeParse` (not `parse`) in services to handle invalid data gracefully
+6. **No Redundant Fields**: Schemas for user-scoped data don't include `user_id` (it's in the path)
+
+---
+
+## Implementation
+
+### Structure
+
+```
+src/schemas/
+├── profile.ts               # UserProfile, UpdateProfileInput
+├── relationship.ts          # Relationship, RelationshipFlags
+├── group-conversation.ts    # GroupConversation, MemberPermissions
+├── dm-conversation.ts       # DMConversation
+├── credentials.ts           # InstagramCredentials, etc.
+├── oauth-integration.ts     # OAuthIntegration
+└── mcp-integration.ts       # MCPIntegration
+```
+
+### Code Example
+
+#### Step 1: Define Entity Schema
+
+```typescript
+// src/schemas/profile.ts
+import { z } from 'zod'
+
+/**
+ * User Profile Schema
+ *
+ * Stored at: {BASE}.users/{userId}/profile/default
+ * Each user has exactly one profile document.
+ */
+export const UserProfileSchema = z.object({
+  user_id: z.string(),
+  display_name: z.string(),
+  short_bio: z.string().optional(),
+  profile_picture_path: z.string().optional(),
+  banner_path: z.string().optional(),
+  friend_count: z.number().int().min(0),
+  created_at: z.number(),
+  updated_at: z.number(),
+})
+
+// Derive TypeScript type from schema
+export type UserProfile = z.infer<typeof UserProfileSchema>
+```
+
+#### Step 2: Define Separate Update Schema
+
+```typescript
+// src/schemas/profile.ts (continued)
+
+/**
+ * Update Profile Schema — only mutable fields
+ */
+export const UpdateProfileSchema = z.object({
+  display_name: z.string().optional(),
+  short_bio: z.string().optional(),
+  profile_picture_path: z.string().optional(),
+  banner_path: z.string().optional(),
+})
+
+export type UpdateProfileInput = z.infer<typeof UpdateProfileSchema>
+```
+
+#### Step 3: Complex Schema with Nested Types
+
+```typescript
+// src/schemas/group-conversation.ts
+import { z } from 'zod'
+
+// Nested permission schema
+export const MemberPermissionsSchema = z.object({
+  auth_level: z.number().int().min(0),
+  can_read: z.boolean(),
+  can_publish: z.boolean(),
+  can_revise: z.boolean(),
+  can_propose: z.boolean(),
+  can_overwrite: z.boolean(),
+  can_comment: z.boolean(),
+  can_retract_own: z.boolean(),
+  can_retract_any: z.boolean(),
+  can_manage_members: z.boolean(),
+  can_update_properties: z.boolean(),
+  can_moderate: z.boolean(),
+  can_kick: z.boolean(),
+  can_mute: z.boolean(),
+  can_ban: z.boolean(),
+})
+
+export type MemberPermissions = z.infer<typeof MemberPermissionsSchema>
+
+// Permission presets
+export const OWNER_PRESET: MemberPermissions = {
+  auth_level: 0,
+  can_read: true, can_publish: true, can_revise: true,
+  can_propose: true, can_overwrite: true, can_comment: true,
+  can_retract_own: true, can_retract_any: true, can_manage_members: true,
+  can_update_properties: true, can_moderate: true,
+  can_kick: true, can_mute: true, can_ban: true,
+}
+
+export const MEMBER_PRESET: MemberPermissions = {
+  auth_level: 5,
+  can_read: true, can_publish: true, can_revise: false,
+  can_propose: true, can_overwrite: false, can_comment: true,
+  can_retract_own: true, can_retract_any: false, can_manage_members: false,
+  can_update_properties: false, can_moderate: false,
+  can_kick: false, can_mute: false, can_ban: false,
+}
+
+// Full entity schema
+export const GroupConversationSchema = z.object({
+  id: z.string(),
+  type: z.literal('group'),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  owner_user_id: z.string(),
+  participant_user_ids: z.array(z.string()),
+  member_permissions: z.record(z.string(), MemberPermissionsSchema),
+  last_message_at: z.string().datetime().nullable().optional(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+})
+
+export type GroupConversation = z.infer<typeof GroupConversationSchema>
+
+// Update schema (only mutable fields)
+export const UpdateGroupConversationSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  last_message_at: z.string().datetime().optional(),
+})
+
+export type UpdateGroupConversationInput = z.infer<typeof UpdateGroupConversationSchema>
+```
+
+#### Step 4: Use safeParse in Services
+
+```typescript
+// src/services/profile-database.service.ts
+import { UserProfileSchema, type UserProfile } from '@/schemas/profile'
+
+export class ProfileDatabaseService {
+  static async getProfile(userId: string): Promise<UserProfile | null> {
+    const doc = await getDocument(getUserProfile(userId), 'default')
+    if (!doc) return null
+
+    // Validate data from schemaless database
+    const result = UserProfileSchema.safeParse(doc)
+    if (!result.success) {
+      console.error('Invalid profile data:', result.error)
+      return null  // Don't crash on invalid data
+    }
+
+    return result.data
+  }
+}
+```
+
+#### Step 5: Validate API Request Bodies
+
+```typescript
+// src/routes/api/groups/create.tsx
+import { CreateGroupSchema } from '@/schemas/group-conversation'
+
+POST: async ({ request }) => {
+  const body = await request.json()
+  const parsed = CreateGroupSchema.safeParse(body)
+
+  if (!parsed.success) {
+    return new Response(JSON.stringify({
+      error: 'Validation error',
+      details: parsed.error.issues,
+    }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+
+  // Use parsed.data (fully typed and validated)
+  const group = await service.create(user.uid, parsed.data)
+}
+```
+
+---
+
+## Schema Naming Conventions
+
+| Schema | Type | Purpose |
+|--------|------|---------|
+| `{Entity}Schema` | `z.object(...)` | Full entity (read from DB) |
+| `Create{Entity}Schema` | `z.object(...)` | Input for creation (fewer fields) |
+| `Update{Entity}Schema` | `z.object(...)` | Input for update (all optional) |
+| `{Entity}` | `z.infer<>` | TypeScript type for full entity |
+| `Create{Entity}Input` | `z.infer<>` | TypeScript type for creation |
+| `Update{Entity}Input` | `z.infer<>` | TypeScript type for update |
+
+---
+
+## Benefits
+
+### 1. Runtime + Compile-Time Safety
+Zod validates at runtime; `z.infer<>` provides compile-time types. Both from one definition.
+
+### 2. Self-Documenting
+Schemas serve as documentation for data models, including optional fields, constraints, and defaults.
+
+### 3. Schemaless DB Safety
+Firestore doesn't enforce schemas — Zod catches invalid or corrupted data on read.
+
+### 4. API Input Validation
+`safeParse` provides detailed validation errors (field-level) returned to clients.
+
+---
+
+## Trade-offs
+
+### 1. Validation Overhead
+**Downside**: Parsing every database read adds CPU time.
+**Mitigation**: Only `safeParse` at boundaries. Internal data passed between services is already validated.
+
+### 2. Schema Duplication
+**Downside**: Separate create/update/read schemas can feel repetitive.
+**Mitigation**: Use Zod utilities: `.pick()`, `.omit()`, `.partial()` to derive schemas from the base.
+
+---
+
+## Anti-Patterns
+
+### ❌ Anti-Pattern 1: Hand-Written Types Alongside Schemas
+
+```typescript
+// ❌ BAD: Types defined separately — can drift from schema
+const ProfileSchema = z.object({ display_name: z.string() })
+interface Profile { displayName: string }  // Mismatch!
+
+// ✅ GOOD: Derive types from schema
+const ProfileSchema = z.object({ display_name: z.string() })
+type Profile = z.infer<typeof ProfileSchema>
+```
+
+### ❌ Anti-Pattern 2: Using parse Instead of safeParse
+
+```typescript
+// ❌ BAD: parse throws on invalid data — crashes the service
+const profile = ProfileSchema.parse(doc)  // Throws ZodError!
+
+// ✅ GOOD: safeParse returns result object
+const result = ProfileSchema.safeParse(doc)
+if (!result.success) {
+  console.error('Invalid data:', result.error)
+  return null
+}
+return result.data
+```
+
+### ❌ Anti-Pattern 3: Schemas Outside schemas/ Directory
+
+```typescript
+// ❌ BAD: Schema defined inline in service file
+// src/services/profile.service.ts
+const ProfileSchema = z.object({ ... })  // Not discoverable
+
+// ✅ GOOD: Schema in centralized directory
+// src/schemas/profile.ts — discoverable, importable, documented
+```
+
+---
+
+## Related Patterns
+
+- **[Library Services Pattern](./tanstack-cloudflare.library-services.md)**: Services use Zod schemas for validation
+- **[API Route Handlers](./tanstack-cloudflare.api-route-handlers.md)**: API routes validate request bodies with schemas
+- **[User-Scoped Collections](./tanstack-cloudflare.user-scoped-collections.md)**: Schemas document Firestore storage paths
+
+---
+
+## Checklist for Implementation
+
+- [ ] All data models defined as Zod schemas in `src/schemas/`
+- [ ] TypeScript types derived with `z.infer<>`, not hand-written
+- [ ] Separate schemas for create, update, and full entity
+- [ ] JSDoc comments document Firestore storage path
+- [ ] Services use `safeParse` (not `parse`) for database reads
+- [ ] API routes use `safeParse` for request body validation
+- [ ] 400 responses include `details: zodError.issues`
+- [ ] Permission presets defined alongside schemas
+- [ ] No `user_id` field in user-scoped document schemas
+
+---
+
+**Status**: Stable - Core data integrity pattern
+**Recommendation**: Use for all applications with structured data models
+**Last Updated**: 2026-02-28
+**Contributors**: Patrick Michaelsen

package/agent/progress.template.yaml

@@ -0,0 +1,161 @@
+# Project Progress Tracking
+# This file tracks the overall progress of the project, including milestones, tasks, and recent work.
+# Update this file regularly as work progresses.
+
+project:
+  name: project-name                    # Replace with your project name
+  version: 0.1.0                        # Current version (semantic versioning)
+  started: YYYY-MM-DD                   # Date project started
+  status: not_started                   # not_started | in_progress | completed
+  current_milestone: M1                 # Current milestone identifier
+  description: |                        # Brief project description
+    A short description of what this project does and its main purpose.
+
+# Milestones represent major phases of the project
+milestones:
+  - id: M1                              # Unique milestone identifier
+    name: Milestone Name                # Descriptive name
+    status: not_started                 # not_started | in_progress | completed
+    progress: 0                         # Percentage complete (0-100)
+    started: null                       # YYYY-MM-DD when started, null if not started
+    completed: null                     # YYYY-MM-DD when completed, null if not completed
+    estimated_weeks: 2                  # Estimated duration in weeks
+    tasks_completed: 0                  # Number of tasks completed
+    tasks_total: 5                      # Total number of tasks in this milestone
+    notes: |                            # Progress notes and observations
+      Notes about this milestone's progress, blockers, or important decisions.
+  
+  - id: M2
+    name: Second Milestone Name
+    status: not_started
+    progress: 0
+    started: null
+    completed: null
+    estimated_weeks: 3
+    tasks_completed: 0
+    tasks_total: 7
+    notes: |
+      This milestone depends on M1 completion.
+
+# Tasks are granular work items within milestones
+tasks:
+  milestone_1:                          # Group tasks by milestone
+    - id: task-1                        # Unique task identifier
+      name: Task Name                   # Descriptive task name
+      status: not_started               # not_started | in_progress | completed
+      file: agent/tasks/task-1-name.md  # Path to task document
+      estimated_hours: 4                # Estimated time in hours
+      actual_hours: null                # Actual time spent (null until completed)
+      completed_date: null              # YYYY-MM-DD when completed, null if not completed
+      notes: |                          # Task-specific notes
+        Any important notes about this task.
+    
+    - id: task-2
+      name: Second Task Name
+      status: not_started
+      file: agent/tasks/task-2-name.md
+      estimated_hours: 2
+      actual_hours: null
+      completed_date: null
+      notes: |
+        Depends on task-1 completion.
+  
+  milestone_2:
+    - id: task-3
+      name: Third Task Name
+      status: not_started
+      file: agent/tasks/task-3-name.md
+      estimated_hours: 6
+      actual_hours: null
+      completed_date: null
+      notes: |
+        First task of second milestone.
+
+# Documentation tracking
+documentation:
+  design_documents: 0                   # Number of design documents created
+  milestone_documents: 0                # Number of milestone documents
+  pattern_documents: 0                  # Number of pattern documents
+  task_documents: 0                     # Number of task documents
+  last_updated: YYYY-MM-DD              # Last documentation update date
+
+# Overall progress metrics
+progress:
+  planning: 0                           # Planning phase completion (0-100%)
+  implementation: 0                     # Implementation phase completion (0-100%)
+  testing: 0                            # Testing phase completion (0-100%)
+  documentation: 0                      # Documentation completion (0-100%)
+  overall: 0                            # Overall project completion (0-100%)
+
+# Recent work log (most recent first)
+recent_work:
+  - date: YYYY-MM-DD                    # Date of work
+    description: |                      # Description of what was done
+      Brief description of work completed on this date.
+    items:                              # Specific items completed
+      - ✅ Completed item 1
+      - ✅ Completed item 2
+      - ⚠️  Warning or note about something
+      - 📋 Pending item or follow-up needed
+  
+  - date: YYYY-MM-DD
+    description: |
+      Earlier work session description.
+    items:
+      - ✅ Another completed item
+      - 📋 Something to revisit
+
+# Next steps (prioritized list)
+next_steps:
+  - Next action item 1 (highest priority)
+  - Next action item 2
+  - Next action item 3
+  - Future consideration or enhancement
+
+# General notes and observations
+notes:
+  - Important note 1 about the project
+  - Important note 2 about architectural decisions
+  - Important note 3 about dependencies or constraints
+
+# Current blockers (remove when resolved)
+current_blockers:
+  - Blocker 1: Description of what's blocking progress
+  - Blocker 2: Another blocker and potential resolution
+
+# Team and contributors (if applicable)
+team:
+  - role: Lead Developer              # Role or responsibility
+    name: Name or "Agent"             # Name or identifier
+    focus: |                          # Current focus area
+      What this person/agent is currently working on
+  
+  - role: Documentation
+    name: Name or "Agent"
+    focus: |
+      Maintaining documentation and patterns
+
+# Dependencies and integrations
+dependencies:
+  external_services:                  # External services this project depends on
+    - name: Service Name
+      status: configured | pending | blocked
+      notes: |
+        Notes about this dependency
+  
+  libraries:                          # Key library dependencies
+    - name: Library Name
+      version: 1.0.0
+      purpose: |
+        Why this library is used
+  
+  infrastructure:                     # Infrastructure requirements
+    - name: Infrastructure Component
+      status: ready | pending | blocked
+      notes: |
+        Notes about this infrastructure
+
+# Quality metrics (optional)
+quality:
+  test_coverage: 0                    # Percentage (0-100)
+  code_review_status: pending         # pending | in

package/agent/progress.yaml

@@ -0,0 +1,145 @@
+project:
+  name: agent-context-protocol-visualizer
+  version: 0.1.0
+  started: 2026-03-14
+  status: completed
+  current_milestone: milestone_2
+  description: |
+    Browser-based read-only dashboard for visualizing ACP progress.yaml data.
+    TanStack Start app with table/tree/kanban views, search, filtering, and auto-refresh.
+
+milestones:
+  - id: milestone_1
+    name: Project Scaffold & Data Pipeline
+    status: completed
+    progress: 100
+    started: "2026-03-14"
+    completed: "2026-03-14"
+    estimated_weeks: "1"
+    tasks_completed: 4
+    tasks_total: 4
+    notes: Foundation milestone — all subsequent work depends on this data pipeline
+
+  - id: milestone_2
+    name: Dashboard Views & Interaction
+    status: completed
+    progress: 100
+    started: "2026-03-14"
+    completed: "2026-03-14"
+    estimated_weeks: "1.5"
+    tasks_completed: 6
+    tasks_total: 6
+    notes: P0 dashboard UI — table, tree, search, filtering
+
+tasks:
+  milestone_1:
+    - id: task_1
+      name: Initialize TanStack Start Project
+      status: completed
+      file: agent/tasks/milestone-1-project-scaffold-data-pipeline/task-1-initialize-tanstack-start-project.md
+      estimated_hours: "2"
+      completed_date: "2026-03-14"
+      notes: Scaffold project with Vite, Tailwind, all P0 deps
+
+    - id: task_2
+      name: Implement Data Model & YAML Parser
+      status: completed
+      file: agent/tasks/milestone-1-project-scaffold-data-pipeline/task-2-implement-data-model-yaml-parser.md
+      estimated_hours: "3"
+      completed_date: "2026-03-14"
+      notes: Types, lenient parsing, agent-drift handling
+
+    - id: task_3
+      name: Build Server API & Data Loading
+      status: completed
+      file: agent/tasks/milestone-1-project-scaffold-data-pipeline/task-3-build-server-api-data-loading.md
+      estimated_hours: "2"
+      completed_date: "2026-03-14"
+      notes: ProgressDatabaseService, beforeLoad SSR
+
+    - id: task_4
+      name: Add Auto-Refresh via SSE
+      status: completed
+      file: agent/tasks/milestone-1-project-scaffold-data-pipeline/task-4-add-auto-refresh-sse.md
+      estimated_hours: "2"
+      completed_date: "2026-03-14"
+      notes: File watcher, SSE endpoint, useAutoRefresh hook
+
+  milestone_2:
+    - id: task_5
+      name: Build Dashboard Layout & Routing
+      status: completed
+      file: agent/tasks/milestone-2-dashboard-views-interaction/task-5-build-dashboard-layout-routing.md
+      estimated_hours: "3"
+      completed_date: "2026-03-14"
+      notes: Root layout, sidebar, header, design tokens
+
+    - id: task_6
+      name: Build Overview Page
+      status: completed
+      file: agent/tasks/milestone-2-dashboard-views-interaction/task-6-build-overview-page.md
+      estimated_hours: "2"
+      completed_date: "2026-03-14"
+      notes: Project summary dashboard
+
+    - id: task_7
+      name: Implement Milestone Table View
+      status: completed
+      file: agent/tasks/milestone-2-dashboard-views-interaction/task-7-implement-milestone-table-view.md
+      estimated_hours: "3"
+      completed_date: "2026-03-14"
+      notes: "@tanstack/react-table with sorting, row expansion"
+
+    - id: task_8
+      name: Implement Milestone Tree View
+      status: completed
+      file: agent/tasks/milestone-2-dashboard-views-interaction/task-8-implement-milestone-tree-view.md
+      estimated_hours: "2"
+      completed_date: "2026-03-14"
+      notes: Expandable hierarchy, useCollapse animation
+
+    - id: task_9
+      name: Implement Search & Filtering
+      status: completed
+      file: agent/tasks/milestone-2-dashboard-views-interaction/task-9-implement-search-filtering.md
+      estimated_hours: "3"
+      completed_date: "2026-03-14"
+      notes: Fuse.js, FilterBar, SearchInput, useFilteredData
+
+    - id: task_10
+      name: Polish & Integration Testing
+      status: completed
+      file: agent/tasks/milestone-2-dashboard-views-interaction/task-10-polish-integration-testing.md
+      estimated_hours: "2"
+      completed_date: "2026-03-14"
+      notes: Error states, empty states, end-to-end verification
+
+documentation:
+  design_documents: 6
+  milestone_documents: 2
+  pattern_documents: 42
+  task_documents: 10
+
+progress:
+  planning: 100
+  implementation: 100
+  overall: 100
+
+recent_work:
+  - date: "2026-03-14"
+    description: Project planning complete
+    items:
+      - Created requirements document (local.visualizer-requirements.md)
+      - Created 5 functional design documents with pattern references
+      - Installed tanstack-cloudflare package (42 patterns)
+      - Planned 2 milestones with 10 tasks
+      - Created milestone and task documents
+
+next_steps:
+  - "P0 complete — test with other ACP project progress.yaml files"
+  - "Point visualizer at remember-core via PROGRESS_YAML_PATH env var"
+  - "Plan P1 features: kanban view, activity timeline, GitHub remote loading"
+
+notes: []
+
+current_blockers: []