create-claude-webapp 1.0.0 → 1.0.1

package/.claude/skills/fullstack-integration/SKILL.md

@@ -0,0 +1,466 @@
+---
+name: fullstack-integration
+description: Cross-service integration patterns for Supabase, Vercel, and Stack-auth. Use when designing full-stack architecture or connecting services.
+---
+
+# Fullstack Integration
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Client (Browser)                         │
+└─────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Vercel Edge (Middleware)                      │
+│  • Route protection                                              │
+│  • Geo-routing                                                   │
+│  • Rate limiting                                                 │
+└─────────────────────────────────────────────────────────────────┘
+                                  │
+                    ┌─────────────┴─────────────┐
+                    ▼                           ▼
+┌──────────────────────────────┐   ┌──────────────────────────────┐
+│        Stack-auth            │   │         Supabase             │
+│  • User authentication       │   │  • PostgreSQL database       │
+│  • Session management        │   │  • Row Level Security        │
+│  • OAuth providers           │   │  • Realtime subscriptions    │
+│  • User profiles             │   │  • Edge Functions            │
+└──────────────────────────────┘   └──────────────────────────────┘
+                    │                           │
+                    └─────────────┬─────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Vercel Serverless Functions                   │
+│  • Business logic                                                │
+│  • Auth verification                                             │
+│  • Database operations                                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Authentication Flow Integration
+
+### Complete Sign-In Flow
+```typescript
+// 1. User signs in with Stack-auth
+// 2. Get Stack-auth user ID
+// 3. Sync/lookup user in Supabase
+// 4. Use Supabase with user context
+
+// lib/auth-integration.ts
+import { stackServerApp } from '@/lib/stack'
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '@/types/database.types'
+
+const supabaseAdmin = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!
+)
+
+export async function getAuthenticatedContext() {
+  // Get Stack-auth user
+  const stackUser = await stackServerApp.getUser()
+
+  if (!stackUser) {
+    return { user: null, supabaseUserId: null }
+  }
+
+  // Get or create Supabase user
+  let { data: supabaseUser } = await supabaseAdmin
+    .from('users')
+    .select('id')
+    .eq('stack_auth_id', stackUser.id)
+    .single()
+
+  if (!supabaseUser) {
+    const { data: newUser, error } = await supabaseAdmin
+      .from('users')
+      .insert({
+        stack_auth_id: stackUser.id,
+        email: stackUser.primaryEmail,
+        display_name: stackUser.displayName,
+        avatar_url: stackUser.profileImageUrl,
+      })
+      .select('id')
+      .single()
+
+    if (error) throw error
+    supabaseUser = newUser
+  }
+
+  return {
+    user: stackUser,
+    supabaseUserId: supabaseUser.id,
+  }
+}
+```
+
+### Protected API Route Pattern
+```typescript
+// app/api/data/route.ts
+import { NextResponse } from 'next/server'
+import { getAuthenticatedContext } from '@/lib/auth-integration'
+import { createSupabaseWithUserContext } from '@/lib/supabase'
+
+export async function GET() {
+  const { user, supabaseUserId } = await getAuthenticatedContext()
+
+  if (!user || !supabaseUserId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  // Create Supabase client with user context for RLS
+  const supabase = createSupabaseWithUserContext(supabaseUserId)
+
+  const { data, error } = await supabase
+    .from('user_data')
+    .select('*')
+
+  if (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 })
+  }
+
+  return NextResponse.json({ data })
+}
+```
+
+## Environment Configuration
+
+### Development (.env.local)
+```env
+# Stack-auth
+NEXT_PUBLIC_STACK_PROJECT_ID=dev-project
+NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=pk_test_...
+STACK_SECRET_SERVER_KEY=sk_test_...
+
+# Supabase (local)
+NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...local...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...local...
+
+# App
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+```
+
+### Production (Vercel Environment Variables)
+```env
+# Stack-auth
+NEXT_PUBLIC_STACK_PROJECT_ID=prod-project
+NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=pk_live_...
+STACK_SECRET_SERVER_KEY=sk_live_...
+
+# Supabase (cloud)
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+
+# App
+NEXT_PUBLIC_APP_URL=https://your-app.vercel.app
+```
+
+### Environment Validation
+```typescript
+// lib/env.ts
+const requiredEnvVars = [
+  'NEXT_PUBLIC_STACK_PROJECT_ID',
+  'NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY',
+  'STACK_SECRET_SERVER_KEY',
+  'NEXT_PUBLIC_SUPABASE_URL',
+  'NEXT_PUBLIC_SUPABASE_ANON_KEY',
+  'SUPABASE_SERVICE_ROLE_KEY',
+] as const
+
+export function validateEnv() {
+  const missing = requiredEnvVars.filter(
+    (key) => !process.env[key]
+  )
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required environment variables: ${missing.join(', ')}`
+    )
+  }
+}
+
+// Call at app startup
+// app/layout.tsx or next.config.js
+validateEnv()
+```
+
+## Error Handling Patterns
+
+### Unified Error Response
+```typescript
+// lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number = 500,
+    public code?: string
+  ) {
+    super(message)
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 401, 'UNAUTHORIZED')
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = 'Not found') {
+    super(message, 404, 'NOT_FOUND')
+  }
+}
+
+// API error handler
+export function handleApiError(error: unknown) {
+  console.error('API Error:', error)
+
+  if (error instanceof AppError) {
+    return NextResponse.json(
+      { error: error.message, code: error.code },
+      { status: error.statusCode }
+    )
+  }
+
+  if (error instanceof Error) {
+    // Don't leak internal error details
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+
+  return NextResponse.json(
+    { error: 'Unknown error' },
+    { status: 500 }
+  )
+}
+```
+
+### Error Boundary Pattern
+```typescript
+// components/error-boundary.tsx
+'use client'
+
+import { useEffect } from 'react'
+
+export function ErrorBoundary({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  useEffect(() => {
+    // Log to error reporting service
+    console.error('Error boundary caught:', error)
+  }, [error])
+
+  return (
+    <div className="error-container">
+      <h2>Something went wrong!</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )
+}
+```
+
+## Performance Patterns
+
+### Parallel Data Fetching
+```typescript
+// app/dashboard/page.tsx
+import { getAuthenticatedContext } from '@/lib/auth-integration'
+import { supabaseAdmin } from '@/lib/supabase-admin'
+
+export default async function DashboardPage() {
+  const { user, supabaseUserId } = await getAuthenticatedContext()
+
+  if (!user || !supabaseUserId) {
+    redirect('/sign-in')
+  }
+
+  // Fetch data in parallel
+  const [userStats, recentPosts, notifications] = await Promise.all([
+    supabaseAdmin
+      .from('user_stats')
+      .select('*')
+      .eq('user_id', supabaseUserId)
+      .single(),
+    supabaseAdmin
+      .from('posts')
+      .select('id, title, created_at')
+      .eq('user_id', supabaseUserId)
+      .order('created_at', { ascending: false })
+      .limit(5),
+    supabaseAdmin
+      .from('notifications')
+      .select('*')
+      .eq('user_id', supabaseUserId)
+      .eq('read', false)
+      .limit(10),
+  ])
+
+  return (
+    <Dashboard
+      stats={userStats.data}
+      recentPosts={recentPosts.data}
+      notifications={notifications.data}
+    />
+  )
+}
+```
+
+### Caching Strategy
+```typescript
+// lib/cache.ts
+import { unstable_cache } from 'next/cache'
+
+export const getCachedUserStats = unstable_cache(
+  async (userId: string) => {
+    const { data } = await supabaseAdmin
+      .from('user_stats')
+      .select('*')
+      .eq('user_id', userId)
+      .single()
+
+    return data
+  },
+  ['user-stats'],
+  {
+    revalidate: 60, // Revalidate every minute
+    tags: ['user-stats'],
+  }
+)
+
+// Invalidate cache
+import { revalidateTag } from 'next/cache'
+revalidateTag('user-stats')
+```
+
+### Optimistic Updates
+```typescript
+// hooks/use-optimistic-mutation.ts
+'use client'
+
+import { useState, useTransition } from 'react'
+
+export function useOptimisticMutation<T>(
+  currentData: T,
+  mutationFn: (newData: T) => Promise<T>
+) {
+  const [optimisticData, setOptimisticData] = useState(currentData)
+  const [isPending, startTransition] = useTransition()
+
+  const mutate = async (newData: T) => {
+    // Optimistically update
+    setOptimisticData(newData)
+
+    startTransition(async () => {
+      try {
+        const result = await mutationFn(newData)
+        setOptimisticData(result)
+      } catch (error) {
+        // Revert on error
+        setOptimisticData(currentData)
+        throw error
+      }
+    })
+  }
+
+  return { data: optimisticData, mutate, isPending }
+}
+```
+
+## Database Schema Pattern
+
+### Users Table with Stack-auth Integration
+```sql
+-- supabase/migrations/20240101000000_create_users.sql
+
+CREATE TABLE public.users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  stack_auth_id TEXT UNIQUE NOT NULL,
+  email TEXT UNIQUE NOT NULL,
+  display_name TEXT,
+  avatar_url TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Enable RLS
+ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;
+
+-- Index for Stack-auth lookups
+CREATE INDEX idx_users_stack_auth_id ON public.users(stack_auth_id);
+
+-- Trigger for updated_at
+CREATE TRIGGER update_users_updated_at
+  BEFORE UPDATE ON public.users
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at();
+
+-- RLS Policies
+CREATE POLICY "Users can view own profile"
+  ON public.users FOR SELECT
+  USING (stack_auth_id = current_setting('app.stack_auth_id', true));
+
+CREATE POLICY "Users can update own profile"
+  ON public.users FOR UPDATE
+  USING (stack_auth_id = current_setting('app.stack_auth_id', true))
+  WITH CHECK (stack_auth_id = current_setting('app.stack_auth_id', true));
+```
+
+### Setting User Context for RLS
+```typescript
+// lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '@/types/database.types'
+
+export function createSupabaseWithUserContext(stackAuthId: string) {
+  const supabase = createClient<Database>(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.SUPABASE_SERVICE_ROLE_KEY!
+  )
+
+  // Set user context for RLS
+  supabase.rpc('set_config', {
+    setting: 'app.stack_auth_id',
+    value: stackAuthId,
+  })
+
+  return supabase
+}
+```
+
+## Deployment Checklist
+
+### Pre-Deployment
+- [ ] All environment variables set in Vercel
+- [ ] Supabase migrations applied to production
+- [ ] Stack-auth production project configured
+- [ ] OAuth redirect URLs updated for production domain
+- [ ] RLS policies tested
+
+### Post-Deployment
+- [ ] Verify authentication flow works
+- [ ] Test protected routes
+- [ ] Verify Supabase connections
+- [ ] Check error logging
+- [ ] Monitor initial traffic
+
+## Common Integration Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| CORS errors | Missing headers | Configure CORS in Supabase and Vercel |
+| Auth not persisting | Cookie settings | Check sameSite and secure flags |
+| RLS blocking queries | Missing user context | Set `app.stack_auth_id` before queries |
+| Type mismatches | Outdated types | Regenerate Supabase types |
+| Slow queries | Missing indexes | Add indexes for foreign keys |

package/.claude/skills/implementation-approach/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: implementation-approach
+description: Selects implementation strategy (vertical slice, horizontal, or hybrid) with risk assessment. Use when planning feature implementation.
+---
+
+# Implementation Strategy Selection Framework (Meta-cognitive Approach)
+
+## Meta-cognitive Strategy Selection Process
+
+### Phase 1: Comprehensive Current State Analysis
+
+**Core Question**: "What does the existing implementation look like?"
+
+#### Analysis Framework
+```yaml
+Architecture Analysis: Responsibility separation, data flow, dependencies, technical debt
+Implementation Quality Assessment: Code quality, test coverage, performance, security
+Historical Context Understanding: Current form rationale, past decision validity, constraint changes, requirement evolution
+```
+
+#### Meta-cognitive Question List
+- What is the true responsibility of this implementation?
+- Which parts are business essence and which derive from technical constraints?
+- What dependencies or implicit preconditions are unclear from the code?
+- What benefits and constraints does the current design bring?
+
+### Phase 2: Strategy Exploration and Creation
+
+**Core Question**: "When determining before -> after, what implementation patterns or strategies should be referenced?"
+
+#### Strategy Discovery Process
+```yaml
+Research and Exploration: Tech stack examples (WebSearch), similar projects, OSS references, literature/blogs
+Creative Thinking: Strategy combinations, constraint-based design, phase division, extension point design
+```
+
+#### Reference Strategy Patterns (Creative Combinations Encouraged)
+
+**Legacy Handling Strategies**:
+- Strangler Pattern: Gradual migration through phased replacement
+- Facade Pattern: Complexity hiding through unified interface
+- Adapter Pattern: Bridge with existing systems
+
+**New Development Strategies**:
+- Feature-driven Development: Vertical implementation prioritizing user value
+- Foundation-driven Development: Foundation-first construction prioritizing stability
+- Risk-driven Development: Prioritize addressing maximum risk elements
+
+**Integration/Migration Strategies**:
+- Proxy Pattern: Transparent feature extension
+- Decorator Pattern: Phased enhancement of existing features
+- Bridge Pattern: Flexibility through abstraction
+
+**Important**: The optimal solution is discovered through creative thinking according to each project's context.
+
+### Phase 3: Risk Assessment and Control
+
+**Core Question**: "What risks arise when applying this to existing implementation, and what's the best way to control them?"
+
+#### Risk Analysis Matrix
+```yaml
+Technical Risks: System impact, data consistency, performance degradation, integration complexity
+Operational Risks: Service availability, deployment downtime, process changes, rollback procedures
+Project Risks: Schedule delays, learning costs, quality achievement, team coordination
+```
+
+#### Risk Control Strategies
+```yaml
+Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup
+Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures
+```
+
+### Phase 4: Constraint Compatibility Verification
+
+**Core Question**: "What are this project's constraints?"
+
+#### Constraint Checklist
+```yaml
+Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets
+Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods
+Resource Constraints: Team/skills, work hours/systems, budget, external contracts
+Business Constraints: Market launch timing, customer impact, regulatory compliance
+```
+
+### Phase 5: Implementation Approach Decision
+
+Select optimal solution from basic implementation approaches (creative combinations encouraged):
+
+#### Vertical Slice (Feature-driven)
+**Characteristics**: Vertical implementation across all layers by feature unit
+**Application Conditions**: Low inter-feature dependencies, output in user-usable form, changes needed across all architecture layers
+**Verification Method**: End-user value delivery at each feature completion
+
+#### Horizontal Slice (Foundation-driven)
+**Characteristics**: Phased construction by architecture layer
+**Application Conditions**: Foundation system stability important, multiple features depend on common foundation, layer-by-layer verification effective
+**Verification Method**: Integrated operation verification when all foundation layers complete
+
+#### Hybrid (Creative Combination)
+**Characteristics**: Flexible combination according to project characteristics
+**Application Conditions**: Unclear requirements, need to change approach per phase, transition from prototyping to full implementation
+**Verification Method**: Verify at appropriate L1/L2/L3 levels according to each phase's goals
+
+### Phase 6: Decision Rationale Documentation
+
+**Design Doc Documentation**: Clearly specify implementation strategy selection reasons and rationale.
+
+## Verification Level Definitions
+
+Priority for completion verification of each task:
+
+- **L1: Functional Operation Verification** - Operates as end-user feature (e.g., search executable)
+- **L2: Test Operation Verification** - New tests added and passing (e.g., type definition tests)
+- **L3: Build Success Verification** - No compile errors (e.g., interface definitions)
+
+**Priority**: L1 > L2 > L3 in order of verifiability importance
+
+## Integration Point Definitions
+
+Define integration points according to selected strategy:
+- **Strangler-based**: When switching between old and new systems for each feature
+- **Feature-driven**: When users can actually use the feature
+- **Foundation-driven**: When all architecture layers are ready and E2E tests pass
+- **Hybrid**: When individual goals defined for each phase are achieved
+
+## Anti-patterns
+
+- **Pattern Fixation**: Selecting only from listed strategies without considering unique combinations
+- **Insufficient Analysis**: Skipping Phase 1 analysis framework before strategy selection
+- **Risk Neglect**: Starting implementation without Phase 3 risk analysis matrix
+- **Constraint Ignorance**: Deciding strategy without checking Phase 4 constraint checklist
+- **Rationale Omission**: Selecting strategy without using Phase 6 documentation template
+
+## Guidelines for Meta-cognitive Execution
+
+1. **Leverage Known Patterns**: Use as starting point, explore creative combinations
+2. **Active WebSearch Use**: Research implementation examples from similar tech stacks
+3. **Apply 5 Whys**: Pursue root causes to grasp essence
+4. **Multi-perspective Evaluation**: Comprehensively evaluate from each Phase 1-4 perspective
+5. **Creative Thinking**: Consider sequential application of multiple strategies and designs leveraging project-specific constraints
+6. **Clarify Decision Rationale**: Make strategy selection rationale explicit in design documents