create-claude-webapp 1.0.0 → 1.0.1

package/.claude/skills/supabase-testing/SKILL.md

@@ -0,0 +1,513 @@
+---
+name: supabase-testing
+description: Testing Supabase with Vitest. Use when writing tests for Supabase queries, RLS policies, or database operations.
+---
+
+# Supabase Testing
+
+## Test Database Setup
+
+### Local Testing Configuration
+```typescript
+// tests/setup/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '@/types/database.types'
+
+// Use local Supabase for tests
+const SUPABASE_URL = process.env.SUPABASE_URL ?? 'http://127.0.0.1:54321'
+const SUPABASE_ANON_KEY = process.env.SUPABASE_ANON_KEY ?? 'your-local-anon-key'
+const SUPABASE_SERVICE_ROLE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY ?? 'your-local-service-role-key'
+
+// Client for authenticated user tests
+export const createTestClient = (accessToken?: string) =>
+  createClient<Database>(SUPABASE_URL, SUPABASE_ANON_KEY, {
+    global: {
+      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
+    },
+  })
+
+// Admin client for setup/teardown (bypasses RLS)
+export const supabaseAdmin = createClient<Database>(
+  SUPABASE_URL,
+  SUPABASE_SERVICE_ROLE_KEY
+)
+```
+
+### Vitest Configuration
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: ['./tests/setup/global.ts'],
+    include: ['tests/**/*.test.ts'],
+    // Run database tests sequentially to avoid conflicts
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+})
+```
+
+### Global Test Setup
+```typescript
+// tests/setup/global.ts
+import { supabaseAdmin } from './supabase'
+import { beforeAll, afterAll, afterEach } from 'vitest'
+
+// Ensure local Supabase is running
+beforeAll(async () => {
+  const { error } = await supabaseAdmin.from('_test_health').select('*').limit(1)
+  if (error && !error.message.includes('does not exist')) {
+    throw new Error('Supabase is not running. Run: supabase start')
+  }
+})
+
+// Clean up test data after each test
+afterEach(async () => {
+  // Delete test data created during tests
+  // Use specific test user IDs or prefixes to identify test data
+})
+```
+
+## Mocking Strategies
+
+### Mocking Supabase Client
+```typescript
+// tests/mocks/supabase.ts
+import { vi } from 'vitest'
+
+export const mockSupabaseClient = {
+  from: vi.fn(() => mockSupabaseClient),
+  select: vi.fn(() => mockSupabaseClient),
+  insert: vi.fn(() => mockSupabaseClient),
+  update: vi.fn(() => mockSupabaseClient),
+  delete: vi.fn(() => mockSupabaseClient),
+  eq: vi.fn(() => mockSupabaseClient),
+  single: vi.fn(() => Promise.resolve({ data: null, error: null })),
+  auth: {
+    getUser: vi.fn(() => Promise.resolve({ data: { user: null }, error: null })),
+    signInWithPassword: vi.fn(),
+    signOut: vi.fn(),
+  },
+}
+
+// Reset mocks between tests
+export const resetSupabaseMocks = () => {
+  Object.values(mockSupabaseClient).forEach((mock) => {
+    if (typeof mock === 'function' && 'mockReset' in mock) {
+      mock.mockReset()
+    }
+  })
+}
+```
+
+### Using Mocks in Unit Tests
+```typescript
+// tests/unit/user-service.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mockSupabaseClient, resetSupabaseMocks } from '../mocks/supabase'
+
+// Mock the module
+vi.mock('@/lib/supabase', () => ({
+  supabase: mockSupabaseClient,
+}))
+
+import { getUserById } from '@/services/user-service'
+
+describe('UserService', () => {
+  beforeEach(() => {
+    resetSupabaseMocks()
+  })
+
+  it('should fetch user by ID', async () => {
+    const mockUser = { id: '123', email: 'test@example.com', name: 'Test' }
+
+    mockSupabaseClient.single.mockResolvedValueOnce({
+      data: mockUser,
+      error: null,
+    })
+
+    const result = await getUserById('123')
+
+    expect(mockSupabaseClient.from).toHaveBeenCalledWith('users')
+    expect(mockSupabaseClient.eq).toHaveBeenCalledWith('id', '123')
+    expect(result).toEqual(mockUser)
+  })
+
+  it('should handle errors', async () => {
+    mockSupabaseClient.single.mockResolvedValueOnce({
+      data: null,
+      error: { message: 'Not found' },
+    })
+
+    await expect(getUserById('invalid')).rejects.toThrow('Not found')
+  })
+})
+```
+
+## RLS Testing
+
+### Testing RLS with Different User Contexts
+
+```typescript
+// tests/integration/rls.test.ts
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { supabaseAdmin, createTestClient } from '../setup/supabase'
+
+describe('RLS Policies', () => {
+  const testUserId1 = 'd0d8c4c0-0000-0000-0000-000000000001'
+  const testUserId2 = 'd0d8c4c0-0000-0000-0000-000000000002'
+  let user1Token: string
+  let user2Token: string
+
+  beforeAll(async () => {
+    // Create test users
+    await supabaseAdmin.auth.admin.createUser({
+      email: 'user1@test.com',
+      password: 'password123',
+      user_metadata: { id: testUserId1 },
+      email_confirm: true,
+    })
+
+    await supabaseAdmin.auth.admin.createUser({
+      email: 'user2@test.com',
+      password: 'password123',
+      user_metadata: { id: testUserId2 },
+      email_confirm: true,
+    })
+
+    // Get tokens
+    const { data: session1 } = await supabaseAdmin.auth.signInWithPassword({
+      email: 'user1@test.com',
+      password: 'password123',
+    })
+    user1Token = session1.session!.access_token
+
+    const { data: session2 } = await supabaseAdmin.auth.signInWithPassword({
+      email: 'user2@test.com',
+      password: 'password123',
+    })
+    user2Token = session2.session!.access_token
+
+    // Create test data
+    await supabaseAdmin.from('posts').insert([
+      { id: 'post-1', user_id: testUserId1, title: 'User 1 Post', content: 'Content' },
+      { id: 'post-2', user_id: testUserId2, title: 'User 2 Post', content: 'Content' },
+    ])
+  })
+
+  afterAll(async () => {
+    // Cleanup
+    await supabaseAdmin.from('posts').delete().in('id', ['post-1', 'post-2'])
+    await supabaseAdmin.auth.admin.deleteUser(testUserId1)
+    await supabaseAdmin.auth.admin.deleteUser(testUserId2)
+  })
+
+  it('users can only read their own posts', async () => {
+    const user1Client = createTestClient(user1Token)
+    const user2Client = createTestClient(user2Token)
+
+    // User 1 can read their own post
+    const { data: user1Posts } = await user1Client.from('posts').select('*')
+    expect(user1Posts).toHaveLength(1)
+    expect(user1Posts![0].id).toBe('post-1')
+
+    // User 2 can only read their own post
+    const { data: user2Posts } = await user2Client.from('posts').select('*')
+    expect(user2Posts).toHaveLength(1)
+    expect(user2Posts![0].id).toBe('post-2')
+  })
+
+  it('users cannot update other users posts', async () => {
+    const user1Client = createTestClient(user1Token)
+
+    const { error } = await user1Client
+      .from('posts')
+      .update({ title: 'Hacked!' })
+      .eq('id', 'post-2')
+
+    // Update should fail or affect 0 rows
+    expect(error).toBeDefined()
+  })
+
+  it('users cannot delete other users posts', async () => {
+    const user1Client = createTestClient(user1Token)
+
+    const { error } = await user1Client
+      .from('posts')
+      .delete()
+      .eq('id', 'post-2')
+
+    expect(error).toBeDefined()
+  })
+
+  it('unauthenticated users cannot access posts', async () => {
+    const anonClient = createTestClient() // No token
+
+    const { data, error } = await anonClient.from('posts').select('*')
+
+    expect(data).toHaveLength(0) // or expect error
+  })
+})
+```
+
+### Testing Organization-Based RLS
+
+```typescript
+describe('Organization RLS Policies', () => {
+  it('org members can access org resources', async () => {
+    // Setup: Create org, add member
+    const orgId = 'test-org-1'
+    const memberId = testUserId1
+    const nonMemberId = testUserId2
+
+    await supabaseAdmin.from('organizations').insert({ id: orgId, name: 'Test Org' })
+    await supabaseAdmin.from('org_members').insert({ org_id: orgId, user_id: memberId })
+    await supabaseAdmin.from('org_resources').insert({
+      id: 'resource-1',
+      org_id: orgId,
+      name: 'Secret Doc',
+    })
+
+    // Member can access
+    const memberClient = createTestClient(user1Token)
+    const { data: memberData } = await memberClient
+      .from('org_resources')
+      .select('*')
+      .eq('org_id', orgId)
+
+    expect(memberData).toHaveLength(1)
+
+    // Non-member cannot access
+    const nonMemberClient = createTestClient(user2Token)
+    const { data: nonMemberData } = await nonMemberClient
+      .from('org_resources')
+      .select('*')
+      .eq('org_id', orgId)
+
+    expect(nonMemberData).toHaveLength(0)
+  })
+})
+```
+
+## Integration Test Patterns
+
+### Testing Database Operations
+```typescript
+// tests/integration/posts.test.ts
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { supabaseAdmin, createTestClient } from '../setup/supabase'
+
+describe('Posts CRUD', () => {
+  const testUserId = 'd0d8c4c0-0000-0000-0000-000000000001'
+  let userToken: string
+  const createdPostIds: string[] = []
+
+  beforeEach(async () => {
+    // Setup authenticated user
+    const { data } = await supabaseAdmin.auth.signInWithPassword({
+      email: 'testuser@example.com',
+      password: 'password123',
+    })
+    userToken = data.session!.access_token
+  })
+
+  afterEach(async () => {
+    // Cleanup created posts
+    if (createdPostIds.length > 0) {
+      await supabaseAdmin.from('posts').delete().in('id', createdPostIds)
+      createdPostIds.length = 0
+    }
+  })
+
+  it('should create a post', async () => {
+    const client = createTestClient(userToken)
+
+    const { data, error } = await client
+      .from('posts')
+      .insert({
+        title: 'Test Post',
+        content: 'Test content',
+        user_id: testUserId,
+      })
+      .select()
+      .single()
+
+    expect(error).toBeNull()
+    expect(data).toMatchObject({
+      title: 'Test Post',
+      content: 'Test content',
+    })
+
+    createdPostIds.push(data!.id)
+  })
+
+  it('should update a post', async () => {
+    const client = createTestClient(userToken)
+
+    // Create
+    const { data: created } = await client
+      .from('posts')
+      .insert({ title: 'Original', content: 'Content', user_id: testUserId })
+      .select()
+      .single()
+
+    createdPostIds.push(created!.id)
+
+    // Update
+    const { data: updated, error } = await client
+      .from('posts')
+      .update({ title: 'Updated' })
+      .eq('id', created!.id)
+      .select()
+      .single()
+
+    expect(error).toBeNull()
+    expect(updated!.title).toBe('Updated')
+  })
+})
+```
+
+## CI/CD Integration
+
+### GitHub Actions Workflow
+```yaml
+# .github/workflows/test.yml
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Supabase CLI
+        uses: supabase/setup-cli@v1
+        with:
+          version: latest
+
+      - name: Start Supabase
+        run: supabase start
+
+      - name: Run migrations
+        run: supabase db reset
+
+      - name: Generate types
+        run: supabase gen types typescript --local > src/types/database.types.ts
+
+      - name: Run tests
+        run: npm test
+        env:
+          SUPABASE_URL: http://127.0.0.1:54321
+          SUPABASE_ANON_KEY: ${{ secrets.LOCAL_ANON_KEY }}
+          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.LOCAL_SERVICE_ROLE_KEY }}
+
+      - name: Stop Supabase
+        if: always()
+        run: supabase stop
+```
+
+## Test Utilities
+
+### Factory Functions
+```typescript
+// tests/factories/user.ts
+import { supabaseAdmin } from '../setup/supabase'
+
+export const createTestUser = async (overrides: Partial<{
+  email: string
+  password: string
+  metadata: Record<string, unknown>
+}> = {}) => {
+  const email = overrides.email ?? `test-${Date.now()}@example.com`
+  const password = overrides.password ?? 'password123'
+
+  const { data, error } = await supabaseAdmin.auth.admin.createUser({
+    email,
+    password,
+    email_confirm: true,
+    user_metadata: overrides.metadata ?? {},
+  })
+
+  if (error) throw error
+
+  return {
+    user: data.user,
+    cleanup: async () => {
+      await supabaseAdmin.auth.admin.deleteUser(data.user.id)
+    },
+  }
+}
+
+// tests/factories/post.ts
+export const createTestPost = async (userId: string, overrides: Partial<{
+  title: string
+  content: string
+  published: boolean
+}> = {}) => {
+  const { data, error } = await supabaseAdmin
+    .from('posts')
+    .insert({
+      title: overrides.title ?? 'Test Post',
+      content: overrides.content ?? 'Test content',
+      user_id: userId,
+      published: overrides.published ?? false,
+    })
+    .select()
+    .single()
+
+  if (error) throw error
+
+  return {
+    post: data,
+    cleanup: async () => {
+      await supabaseAdmin.from('posts').delete().eq('id', data.id)
+    },
+  }
+}
+```
+
+### Using Factories in Tests
+```typescript
+describe('Post visibility', () => {
+  it('published posts are visible to all', async () => {
+    const { user, cleanup: cleanupUser } = await createTestUser()
+    const { post, cleanup: cleanupPost } = await createTestPost(user.id, {
+      published: true,
+    })
+
+    try {
+      const anonClient = createTestClient()
+      const { data } = await anonClient
+        .from('posts')
+        .select('*')
+        .eq('id', post.id)
+        .single()
+
+      expect(data).toBeDefined()
+      expect(data!.id).toBe(post.id)
+    } finally {
+      await cleanupPost()
+      await cleanupUser()
+    }
+  })
+})
+```

package/.claude/skills/task-analyzer/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: task-analyzer
+description: Analyzes task essence and selects appropriate skills. Returns scale estimates and metadata. Use when starting tasks or selecting skills.
+---
+
+# Task Analyzer
+
+Provides metacognitive task analysis and skill selection guidance.
+
+## Skills Index
+
+See **[skills-index.yaml](references/skills-index.yaml)** for available skills metadata.
+
+## Task Analysis Process
+
+### 1. Understand Task Essence
+
+Identify the fundamental purpose beyond surface-level work:
+
+| Surface Work | Fundamental Purpose |
+|--------------|---------------------|
+| "Fix this bug" | Problem solving, root cause analysis |
+| "Implement this feature" | Feature addition, value delivery |
+| "Refactor this code" | Quality improvement, maintainability |
+| "Update this file" | Change management, consistency |
+
+**Key Questions:**
+- What problem are we really solving?
+- What is the expected outcome?
+- What could go wrong if we approach this superficially?
+
+### 2. Estimate Task Scale
+
+| Scale | File Count | Indicators |
+|-------|------------|------------|
+| Small | 1-2 | Single function/component change |
+| Medium | 3-5 | Multiple related components |
+| Large | 6+ | Cross-cutting concerns, architecture impact |
+
+**Scale affects skill priority:**
+- Larger scale → process/documentation skills more important
+- Smaller scale → implementation skills more focused
+
+### 3. Identify Task Type
+
+| Type | Characteristics | Key Skills |
+|------|-----------------|------------|
+| Implementation | New code, features | coding-standards, typescript-testing |
+| Fix | Bug resolution | coding-standards, typescript-testing |
+| Refactoring | Structure improvement | coding-standards, implementation-approach |
+| Design | Architecture decisions | documentation-criteria, implementation-approach |
+| Quality | Testing, review | typescript-testing, integration-e2e-testing |
+
+### 4. Tag-Based Skill Matching
+
+Extract relevant tags from task description and match against skills-index.yaml:
+
+```yaml
+Task: "Implement user authentication with tests"
+Extracted tags: [implementation, testing, security]
+Matched skills:
+  - coding-standards (implementation, security)
+  - typescript-testing (testing)
+  - typescript-rules (implementation)
+```
+
+### 5. Implicit Relationships
+
+Consider hidden dependencies:
+
+| Task Involves | Also Include |
+|---------------|--------------|
+| Error handling | debugging, testing |
+| New features | design, implementation, documentation |
+| Performance | profiling, optimization, testing |
+| Frontend | typescript-rules, typescript-testing |
+| API/Integration | integration-e2e-testing |
+
+## Output Format
+
+Return structured analysis with skill metadata from skills-index.yaml:
+
+```yaml
+taskAnalysis:
+  essence: <string>  # Fundamental purpose identified
+  type: <implementation|fix|refactoring|design|quality>
+  scale: <small|medium|large>
+  estimatedFiles: <number>
+  tags: [<string>, ...]  # Extracted from task description
+
+selectedSkills:
+  - skill: <skill-name>  # From skills-index.yaml
+    priority: <high|medium|low>
+    reason: <string>  # Why this skill was selected
+    # Pass through metadata from skills-index.yaml
+    tags: [...]
+    typical-use: <string>
+    size: <small|medium|large>
+    sections: [...]  # All sections from yaml, unfiltered
+```
+
+**Note**: Section selection (choosing which sections are relevant) is done separately after reading the actual SKILL.md files.
+
+## Skill Selection Priority
+
+1. **Essential** - Directly related to task type
+2. **Quality** - Testing and quality assurance
+3. **Process** - Workflow and documentation
+4. **Supplementary** - Reference and best practices
+
+## Metacognitive Question Design
+
+Generate 3-5 questions according to task nature:
+
+| Task Type | Question Focus |
+|-----------|----------------|
+| Implementation | Design validity, edge cases, performance |
+| Fix | Root cause (5 Whys), impact scope, regression testing |
+| Refactoring | Current problems, target state, phased plan |
+| Design | Requirement clarity, future extensibility, trade-offs |
+
+## Warning Patterns
+
+Detect and flag these patterns:
+
+| Pattern | Warning | Mitigation |
+|---------|---------|------------|
+| Large change at once | High risk | Split into phases |
+| Implementation without tests | Quality risk | Follow TDD |
+| Immediate fix on error | Root cause missed | Pause, analyze |
+| Coding without plan | Scope creep | Plan first |