anvil-dev-framework 0.1.8 → 0.1.9

package/project/templates/saas/CLAUDE.md

@@ -0,0 +1,478 @@
+# [Project Name]
+
+> [One-line description of the project]
+
+---
+
+## Project Overview
+
+[2-3 sentences describing what this project is and who it's for]
+
+**Status**: [Active Development / Maintenance / Beta / etc.]
+**Repository**: [URL]
+**Live URL**: [URL if applicable]
+
+---
+
+## Tech Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Framework | Next.js (App Router) | 14.x |
+| Language | TypeScript | 5.x |
+| Database | Supabase (PostgreSQL) | — |
+| Auth | Supabase Auth | — |
+| Styling | Tailwind CSS + shadcn/ui | 3.x |
+| State | React Query + Zustand | — |
+| Testing | Vitest + Testing Library | 1.x |
+| Deployment | Vercel | — |
+
+### Optional Integrations
+- **Payments**: Stripe (if applicable)
+- **Email**: Resend or Postmark
+- **Analytics**: Vercel Analytics or PostHog
+
+---
+
+## Architecture
+
+### Directory Structure
+```
+src/
+├── app/                    # Next.js App Router
+│   ├── (auth)/            # Auth-related routes (login, signup)
+│   ├── (dashboard)/       # Protected dashboard routes
+│   ├── api/               # API routes
+│   └── layout.tsx         # Root layout
+├── components/
+│   ├── ui/                # shadcn/ui components
+│   ├── forms/             # Form components
+│   └── [feature]/         # Feature-specific components
+├── lib/
+│   ├── supabase/          # Supabase client & helpers
+│   │   ├── client.ts      # Browser client
+│   │   ├── server.ts      # Server client
+│   │   └── middleware.ts  # Auth middleware
+│   ├── utils.ts           # Utility functions
+│   └── constants.ts       # App constants
+├── services/              # Business logic layer
+├── hooks/                 # Custom React hooks
+├── types/                 # TypeScript type definitions
+└── styles/                # Global styles
+```
+
+### Key Patterns
+
+**Server vs Client Components**
+- Default to Server Components for data fetching
+- Use `'use client'` only for interactivity (forms, state, effects)
+- Fetch data in Server Components, pass to Client Components as props
+
+**Data Fetching**
+- Server Components: Direct Supabase queries
+- Client Components: React Query with Supabase client
+- Mutations: Server Actions or API routes
+
+**Authentication Flow**
+```
+middleware.ts → Check session → Redirect if needed
+                    ↓
+             Supabase Auth
+                    ↓
+         RLS policies enforce access
+```
+
+**State Management**
+- Server state: React Query (caching, revalidation)
+- Client state: Zustand (UI state, preferences)
+- Form state: React Hook Form + Zod validation
+
+---
+
+## Agent Approach
+
+### Session Startup
+```
+1. /orient           → Check handoffs, understand context
+2. /ready            → See unblocked work
+3. /validate         → Ensure clean environment
+4. Await direction   → Don't start work without confirmation
+```
+
+### Implementation Flow
+```
+1. /explore          → Discovery before any new feature
+2. /spec             → Formal specification (if needed)
+3. /plan             → Implementation plan
+4. /tasks            → Linear issues from plan
+5. [implement]       → Do the work
+6. /evidence         → Capture quality proof
+7. /handoff          → Session continuity
+```
+
+### During Work
+- Read existing code before writing new code
+- Cite file paths and line numbers as evidence
+- File discovered work immediately with `/discover`
+- Update Linear status at phase transitions
+- Stop and report if stuck >5 minutes
+
+### Anti-Patterns to Avoid
+
+Before implementing, verify you're NOT doing:
+
+| Anti-Pattern | Check |
+|--------------|-------|
+| Premature abstraction | Is this the 3rd instance? (Rule of Three) |
+| Adding files without need | Can this be added to existing file? |
+| Over-engineering | Is this the simplest solution? |
+| Ignoring existing patterns | Did I check examples first? |
+| Large PRs | Can I break this into smaller chunks? |
+| Skipping exploration | Did I run `/explore` first? |
+| Committing without branch verification | Did I run `git branch --show-current`? |
+| Post-edit without git diff | Did I run `git diff` to verify edits persisted? |
+| Addressing merged PR feedback | Did I run `gh pr view --json state` before committing? |
+| Implementing consumer without verifying producer | Did I trace the full data flow? |
+
+### Project-Learned Patterns
+
+> Patterns discovered from retrospectives. Updated via `/insights`.
+
+| Pattern | Evidence | Added |
+|---------|----------|-------|
+| *Example: Verify Before Edit* | *ISSUE-1, branch-fix* | *YYYY-MM-DD* |
+
+*Replace with patterns discovered from your project's retrospectives. Run `/insights` to update.*
+
+**Pre-Implementation Checklist**
+
+Before building something new, search for existing infrastructure:
+
+```bash
+# Check for existing services
+grep -r "function.*[FeatureName]" src/services/
+
+# Check for existing hooks
+grep -r "use[FeatureName]" src/hooks/
+
+# Check for existing components
+grep -r "export.*function.*[ComponentName]" src/components/
+
+# Check for existing utilities
+grep -r "[utility-name]" src/lib/
+
+# Check for existing API routes
+ls -la src/app/api/
+```
+
+*Customize these commands based on patterns discovered in retros.*
+
+### Confidence Checkpoints
+
+Rate your confidence at each stage (1-10):
+
+| Confidence | Action |
+|------------|--------|
+| 8-10 | Proceed normally |
+| 5-7 | Document uncertainty, proceed cautiously, note assumptions |
+| 1-4 | **STOP**. Explain the uncertainty. Ask for guidance. |
+
+**Escalation rule**: After 2 failed attempts at the same task → Stop. Reassess. Ask for help.
+
+---
+
+## Slash Commands
+
+### Session Commands
+| Command | Purpose |
+|---------|---------|
+| `/orient` | Session startup orientation |
+| `/ready` | Calculate ready work |
+| `/sprint` | Quick session prioritization |
+| `/handoff` | Generate session continuity doc |
+
+### Workflow Commands
+| Command | Purpose |
+|---------|---------|
+| `/explore` | Discovery phase |
+| `/spec` | Generate specification |
+| `/plan` | Create implementation plan |
+| `/tasks` | Create Linear issues |
+| `/change` | Brownfield change proposal |
+| `/discover` | File discovered work |
+
+### Quality Commands
+| Command | Purpose |
+|---------|---------|
+| `/validate` | Environment validation |
+| `/evidence` | Capture quality proof |
+
+### Maintenance Commands
+| Command | Purpose |
+|---------|---------|
+| `/retro` | Write retrospective |
+| `/insights` | Synthesize learnings |
+
+---
+
+## Linear Workflow
+
+### Issue States
+| State | Meaning |
+|-------|---------|
+| Backlog | Not yet prioritized |
+| Todo | Prioritized, ready to start |
+| In Progress | Actively being worked on |
+| In Review | PR created, awaiting review |
+| Done | Merged and deployed |
+
+### Labels
+- `bug` — Something isn't working
+- `feature` — New functionality
+- `chore` — Maintenance task
+- `discovered` — Found during other work
+- `blocked` — Cannot proceed
+
+### Priorities
+- **P0 (Urgent)**: Drop everything, fix now
+- **P1 (High)**: Next up after current task
+- **P2 (Medium)**: This sprint
+- **P3 (Low)**: Backlog
+
+---
+
+## File Conventions
+
+### Naming
+- **Components**: PascalCase (`UserProfile.tsx`)
+- **Hooks**: camelCase with `use` prefix (`useAuth.ts`)
+- **Utilities**: camelCase (`formatDate.ts`)
+- **Types**: PascalCase (`User.ts`)
+- **API Routes**: `route.ts` in appropriate directory
+- **Directories**: kebab-case (`user-settings/`)
+
+### Component Structure
+```typescript
+// Imports (external, then internal)
+import { useState } from 'react'
+import { Button } from '@/components/ui/button'
+
+// Types
+interface Props {
+  user: User
+  onUpdate: (user: User) => void
+}
+
+// Component
+export function UserProfile({ user, onUpdate }: Props) {
+  // Hooks first
+  const { data, isLoading } = useUserData(user.id)
+
+  // State second
+  const [isEditing, setIsEditing] = useState(false)
+
+  // Effects third (minimize usage)
+
+  // Handlers fourth
+  const handleSave = async () => {
+    // ...
+  }
+
+  // Render last
+  if (isLoading) return <Skeleton />
+
+  return (
+    <div className="space-y-4">
+      {/* Component JSX */}
+    </div>
+  )
+}
+```
+
+### Server Action Pattern
+```typescript
+// src/app/actions/user.ts
+'use server'
+
+import { createClient } from '@/lib/supabase/server'
+import { revalidatePath } from 'next/cache'
+
+export async function updateUser(formData: FormData) {
+  const supabase = await createClient()
+
+  const { error } = await supabase
+    .from('users')
+    .update({ name: formData.get('name') })
+    .eq('id', formData.get('id'))
+
+  if (error) throw new Error(error.message)
+
+  revalidatePath('/dashboard')
+}
+```
+
+---
+
+## Database Patterns
+
+### Supabase Client Setup
+```typescript
+// src/lib/supabase/client.ts (browser)
+import { createBrowserClient } from '@supabase/ssr'
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  )
+}
+
+// src/lib/supabase/server.ts (server)
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+
+export async function createClient() {
+  const cookieStore = await cookies()
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return cookieStore.getAll() },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value, options }) =>
+            cookieStore.set(name, value, options)
+          )
+        },
+      },
+    }
+  )
+}
+```
+
+### RLS Policy Pattern
+```sql
+-- Enable RLS
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+
+-- Users can only see their own posts
+CREATE POLICY "Users can view own posts"
+ON posts FOR SELECT
+USING (auth.uid() = user_id);
+
+-- Users can only insert their own posts
+CREATE POLICY "Users can insert own posts"
+ON posts FOR INSERT
+WITH CHECK (auth.uid() = user_id);
+```
+
+---
+
+## Error Handling
+
+### AppError Class
+```typescript
+// src/lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public statusCode: number = 400,
+    public cause?: unknown
+  ) {
+    super(message)
+    this.name = 'AppError'
+  }
+}
+
+// Usage
+throw new AppError('NOT_FOUND', 'User not found', 404)
+```
+
+### API Route Error Handling
+```typescript
+// src/app/api/users/route.ts
+import { NextResponse } from 'next/server'
+import { AppError } from '@/lib/errors'
+
+export async function GET() {
+  try {
+    // ... operation
+    return NextResponse.json(data)
+  } catch (error) {
+    if (error instanceof AppError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.statusCode }
+      )
+    }
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+}
+```
+
+### Error Codes
+| Code | Meaning |
+|------|---------|
+| `AUTH_REQUIRED` | User must be logged in |
+| `NOT_FOUND` | Resource doesn't exist |
+| `VALIDATION_ERROR` | Invalid input data |
+| `PERMISSION_DENIED` | User lacks permission |
+| `RATE_LIMITED` | Too many requests |
+
+---
+
+## Key Files Reference
+
+| Purpose | Location |
+|---------|----------|
+| Project config | `CLAUDE.md` (this file) |
+| Non-negotiables | `.claude/constitution.md` |
+| Product definition | `.claude/product.md` |
+| Active specs | `.claude/specs/current/` |
+| Handoffs | `.claude/handoffs/` |
+| Convention examples | `.claude/examples/` |
+
+---
+
+## Environment Setup
+
+### Required Environment Variables
+```bash
+# .env.local
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...  # Server-side only
+
+# Optional
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+```
+
+### Local Development
+```bash
+pnpm install         # Install dependencies
+pnpm dev             # Start dev server (localhost:3000)
+pnpm build           # Production build
+pnpm test            # Run tests
+pnpm lint            # Run linter
+pnpm typecheck       # Check types
+```
+
+### Supabase Local Development
+```bash
+supabase start       # Start local Supabase
+supabase db reset    # Reset database with migrations
+supabase gen types   # Generate TypeScript types
+```
+
+### Deployment (Vercel)
+- Push to main branch triggers automatic deployment
+- Preview deployments for PRs
+- Environment variables set in Vercel dashboard
+
+---
+
+*Update this file as the project evolves. This is your project's source of truth for AI assistance.*

package/project/tests/README.md

@@ -0,0 +1,140 @@
+# Anvil Test Harnesses
+
+Reusable test harnesses for testing Anvil framework scripts.
+
+## Why Test Harnesses?
+
+Testing bash scripts and Python hooks that process JSON input is error-prone due to shell escaping issues. These harnesses use **heredocs** to define JSON fixtures, eliminating escaping problems entirely.
+
+## Quick Start
+
+```bash
+# Run all statusline tests
+./test-statusline.sh
+
+# Run all hook tests
+./test-hooks.sh
+
+# Run specific hook tests
+./test-hooks.sh pre_tool_use
+./test-hooks.sh session_start
+```
+
+## Available Test Harnesses
+
+| Script | Tests | Purpose |
+|--------|-------|---------|
+| `test-statusline.sh` | 7 tests | StatusLine hook JSON processing |
+| `test-hooks.sh` | 8 tests | Pre-tool-use safety, session hooks |
+| `test-lib.sh` | (library) | Shared test utilities |
+
+## Writing Custom Tests
+
+### 1. Source the test library
+
+```bash
+#!/bin/bash
+source "$(dirname "$0")/test-lib.sh"
+```
+
+### 2. Define JSON fixtures using heredocs
+
+```bash
+# Heredocs avoid ALL shell escaping issues
+read -r -d '' MY_FIXTURE << 'EOF' || true
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "echo 'hello world'"
+  }
+}
+EOF
+```
+
+### 3. Write test functions
+
+```bash
+test_my_feature() {
+    local output
+    output=$(echo "$MY_FIXTURE" | python3 "$HOOK" 2>&1)
+
+    # Use assertion helpers
+    assert_contains "$output" "expected pattern" "Should contain pattern"
+    assert_exit_code 0 echo "$MY_FIXTURE" | python3 "$HOOK"
+}
+```
+
+### 4. Run tests with `run_test`
+
+```bash
+run_test "my_feature_works" test_my_feature
+print_summary
+```
+
+## Assertion Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `assert_contains` | Check output contains pattern | `assert_contains "$out" "OK"` |
+| `assert_not_contains` | Check output doesn't contain | `assert_not_contains "$out" "ERROR"` |
+| `assert_equals` | Check values are equal | `assert_equals "$a" "$b"` |
+| `assert_exit_code` | Check command exit code | `assert_exit_code 0 ./script.sh` |
+
+## Test Environment Functions
+
+| Function | Description |
+|----------|-------------|
+| `setup_test_env` | Create temp dir, set mock env vars |
+| `cleanup_test_env` | Remove temp dir, unset env vars |
+| `print_summary` | Print pass/fail counts |
+
+## Example Output
+
+```
+Hook Test Harness
+=================
+Hooks Dir: /path/to/project/hooks
+
+Testing: pre_tool_use.py
+------------------------
+✅ safe_bash_allowed
+✅ blocks_rm_rf_root
+✅ blocks_rm_rf_home
+✅ blocks_env_read
+✅ allows_env_sample
+✅ allows_normal_edit
+✅ performance
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Test Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Total:  7
+Passed: 7
+Failed: 0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Best Practices
+
+1. **Always use heredocs for JSON** - Never inline JSON with quotes
+2. **One assertion per test** - Makes failures easier to debug
+3. **Test both success and failure** - Verify blocked commands are blocked
+4. **Include performance tests** - Hooks should complete in <100ms
+5. **Use descriptive test names** - `blocks_rm_rf_root` not `test1`
+
+## Adding New Hook Tests
+
+1. Add JSON fixture with descriptive name
+2. Write test function that checks behavior
+3. Add `run_test` call in appropriate section
+4. Run full test suite to verify
+
+## Integration with Anvil
+
+These test harnesses are copied to new projects via `anvil init`:
+
+```bash
+anvil init  # Creates .claude/tests/ with these files
+```
+
+Test your hooks locally before committing changes to `project/hooks/`.

package/project/tests/fixtures/sample-transcript.jsonl

@@ -0,0 +1,21 @@
+{"type": "tool_use", "tool_use_id": "tool_001", "name": "Read", "input": {"file_path": "/Users/test/project/src/auth.ts"}, "timestamp": "2026-01-04T10:00:00Z"}
+{"type": "tool_result", "tool_use_id": "tool_001", "content": "file contents...", "is_error": false, "timestamp": "2026-01-04T10:00:01Z"}
+{"type": "tool_use", "tool_use_id": "tool_002", "name": "Edit", "input": {"file_path": "/Users/test/project/src/auth.ts", "old_string": "foo", "new_string": "bar"}, "timestamp": "2026-01-04T10:00:02Z"}
+{"type": "tool_result", "tool_use_id": "tool_002", "content": "success", "is_error": false, "timestamp": "2026-01-04T10:00:03Z"}
+{"type": "tool_use", "tool_use_id": "tool_003", "name": "TodoWrite", "input": {"todos": [{"content": "Read existing auth code", "status": "completed", "activeForm": "Reading auth code"}, {"content": "Implement OAuth flow", "status": "in_progress", "activeForm": "Implementing OAuth"}, {"content": "Add tests", "status": "pending", "activeForm": "Adding tests"}, {"content": "Update docs", "status": "pending", "activeForm": "Updating docs"}]}, "timestamp": "2026-01-04T10:00:04Z"}
+{"type": "tool_result", "tool_use_id": "tool_003", "content": "Todos updated", "is_error": false, "timestamp": "2026-01-04T10:00:04Z"}
+{"type": "tool_use", "tool_use_id": "tool_004", "name": "Bash", "input": {"command": "npm run test"}, "timestamp": "2026-01-04T10:00:05Z"}
+{"type": "tool_result", "tool_use_id": "tool_004", "content": "All tests passed", "is_error": false, "timestamp": "2026-01-04T10:00:10Z"}
+{"type": "tool_use", "tool_use_id": "tool_005", "name": "Edit", "input": {"file_path": "/Users/test/project/src/login.ts", "old_string": "x", "new_string": "y"}, "timestamp": "2026-01-04T10:00:11Z"}
+{"type": "tool_result", "tool_use_id": "tool_005", "content": "success", "is_error": false, "timestamp": "2026-01-04T10:00:12Z"}
+{"type": "tool_use", "tool_use_id": "tool_006", "name": "Read", "input": {"file_path": "/Users/test/project/src/utils.ts"}, "timestamp": "2026-01-04T10:00:13Z"}
+{"type": "tool_result", "tool_use_id": "tool_006", "content": "utils content", "is_error": false, "timestamp": "2026-01-04T10:00:14Z"}
+{"type": "tool_use", "tool_use_id": "tool_007", "name": "Grep", "input": {"pattern": "TODO", "path": "/Users/test/project/src"}, "timestamp": "2026-01-04T10:00:15Z"}
+{"type": "tool_result", "tool_use_id": "tool_007", "content": "Found 3 matches", "is_error": false, "timestamp": "2026-01-04T10:00:16Z"}
+{"type": "tool_use", "tool_use_id": "tool_008", "name": "Edit", "input": {"file_path": "/Users/test/project/src/auth.ts", "old_string": "a", "new_string": "b"}, "timestamp": "2026-01-04T10:00:17Z"}
+{"type": "tool_result", "tool_use_id": "tool_008", "content": "Failed to edit", "is_error": true, "timestamp": "2026-01-04T10:00:18Z"}
+{"type": "tool_use", "tool_use_id": "tool_009", "name": "Edit", "input": {"file_path": "/Users/test/project/src/auth.ts", "old_string": "c", "new_string": "d"}, "timestamp": "2026-01-04T10:00:19Z"}
+{"type": "tool_result", "tool_use_id": "tool_009", "content": "success", "is_error": false, "timestamp": "2026-01-04T10:00:20Z"}
+{"type": "tool_use", "tool_use_id": "tool_010", "name": "TodoWrite", "input": {"todos": [{"content": "Read existing auth code", "status": "completed", "activeForm": "Reading auth code"}, {"content": "Implement OAuth flow", "status": "completed", "activeForm": "Implementing OAuth"}, {"content": "Add tests", "status": "in_progress", "activeForm": "Adding tests"}, {"content": "Update docs", "status": "pending", "activeForm": "Updating docs"}]}, "timestamp": "2026-01-04T10:00:21Z"}
+{"type": "tool_result", "tool_use_id": "tool_010", "content": "Todos updated", "is_error": false, "timestamp": "2026-01-04T10:00:21Z"}
+{"type": "tool_use", "tool_use_id": "tool_011", "name": "Read", "input": {"file_path": "/Users/test/project/tests/auth.test.ts"}, "timestamp": "2026-01-04T10:00:22Z"}