create-claude-webapp 1.0.0 → 1.0.2

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

@@ -0,0 +1,155 @@
+---
+name: typescript-testing
+description: Applies Vitest test design and quality standards. Provides coverage requirements and mock usage guides. Use when writing unit tests.
+---
+
+# TypeScript Testing Rules
+
+## Test Framework
+
+- **Vitest**: This project uses Vitest
+- Test imports: `import { describe, it, expect, beforeEach, vi } from 'vitest'`
+- Mock creation: Use `vi.mock()`
+
+## Basic Testing Policy
+
+### Quality Requirements
+- **Coverage**: Unit test coverage must be 70% or higher
+- **Independence**: Each test can run independently without depending on other tests
+- **Reproducibility**: Tests are environment-independent and always return the same results
+- **Readability**: Test code maintains the same quality as production code
+
+### Coverage Requirements
+**Mandatory**: Unit test coverage must be 70% or higher
+**Metrics**: Statements, Branches, Functions, Lines
+
+### Test Types and Scope
+1. **Unit Tests**
+   - Verify behavior of individual functions or classes
+   - Mock all external dependencies
+   - Most numerous, implemented with fine granularity
+
+2. **Integration Tests**
+   - Verify coordination between multiple components
+   - Use actual dependencies (DB, API, etc.)
+   - Verify major functional flows
+
+3. **Cross-functional Verification in E2E Tests**
+   - Mandatory verification of impact on existing features when adding new features
+   - Cover integration points with "High" and "Medium" impact levels from Design Doc's "Integration Point Map"
+   - Verification pattern: Existing feature operation -> Enable new feature -> Verify continuity of existing features
+   - Success criteria: No change in response content, processing time within 5 seconds
+   - Designed for automatic execution in CI/CD pipelines
+
+## Test Implementation Conventions
+
+### Directory Structure
+```
+src/
+└── application/
+    └── services/
+        ├── __tests__/
+        │   ├── service.test.ts      # Unit tests
+        │   └── service.int.test.ts  # Integration tests
+        └── service.ts
+```
+
+### Naming Conventions
+- Test files: `{target-file-name}.test.ts`
+- Integration test files: `{target-file-name}.int.test.ts`
+- Test suites: Names describing target features or situations
+- Test cases: Names describing expected behavior
+
+### Test Code Quality Rules
+
+**Recommended: Keep all tests always active**
+- Merit: Guarantees test suite completeness
+- Practice: Fix problematic tests and activate them
+
+**Avoid: test.skip() or commenting out**
+- Reason: Creates test gaps and incomplete quality checks
+- Solution: Completely delete unnecessary tests
+
+## Test Quality Criteria
+
+### Boundary and Error Case Coverage
+Include boundary values and error cases alongside happy paths.
+```typescript
+it('returns 0 for empty array', () => expect(calc([])).toBe(0))
+it('throws on negative price', () => expect(() => calc([{price: -1}])).toThrow())
+```
+
+### Literal Expected Values
+Use literal values for assertions. Do not replicate implementation logic.
+**Valid test**: Expected value != Mock return value (implementation transforms/processes data)
+```typescript
+expect(calcTax(100)).toBe(10)  // not: 100 * TAX_RATE
+```
+
+### Result-Based Verification
+Verify results, not invocation order or count.
+```typescript
+expect(mock).toHaveBeenCalledWith('a')  // not: toHaveBeenNthCalledWith
+```
+
+### Meaningful Assertions
+Each test must include at least one verification.
+```typescript
+it('creates user', async () => {
+  const user = await createUser({name: 'test'})
+  expect(user.id).toBeDefined()
+})
+```
+
+### Appropriate Mock Scope
+Mock only direct external I/O dependencies. Use real implementations for indirect dependencies.
+```typescript
+vi.mock('./database')  // external I/O only
+```
+
+### Property-based Testing (fast-check)
+Use fast-check when verifying invariants or properties.
+```typescript
+import fc from 'fast-check'
+
+it('reverses twice equals original', () => {
+  fc.assert(fc.property(fc.array(fc.integer()), (arr) => {
+    return JSON.stringify(arr.reverse().reverse()) === JSON.stringify(arr)
+  }))
+})
+```
+
+**Usage condition**: Use when Property annotations are assigned to ACs in Design Doc.
+
+## Mock Type Safety Enforcement
+
+### Minimal Type Definition Requirements
+```typescript
+// Only required parts
+type TestRepo = Pick<Repository, 'find' | 'save'>
+const mock: TestRepo = { find: vi.fn(), save: vi.fn() }
+
+// Only when absolutely necessary, with clear justification
+const sdkMock = {
+  call: vi.fn()
+} as unknown as ExternalSDK // Complex external SDK type structure
+```
+
+## Basic Vitest Example
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+
+vi.mock('./userService', () => ({
+  getUserById: vi.fn(),
+  updateUser: vi.fn()
+}))
+
+describe('ComponentName', () => {
+  it('should follow AAA pattern', () => {
+    const input = 'test'
+    const result = someFunction(input)
+    expect(result).toBe('expected')
+  })
+})
+```

package/.claude/skills/vercel-deployment/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: vercel-deployment
+description: Vercel configuration, environment variables, and deployments. Use when deploying to Vercel, configuring builds, or managing environment variables.
+---
+
+# Vercel Deployment
+
+## Configuration
+
+### vercel.json Structure
+```json
+{
+  "framework": "nextjs",
+  "buildCommand": "npm run build",
+  "installCommand": "npm install",
+  "outputDirectory": ".next",
+  "regions": ["iad1"],
+  "functions": {
+    "api/**/*.ts": {
+      "memory": 1024,
+      "maxDuration": 10
+    }
+  },
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "Cache-Control", "value": "no-store" }
+      ]
+    }
+  ],
+  "rewrites": [
+    { "source": "/api/health", "destination": "/api/health-check" }
+  ],
+  "redirects": [
+    { "source": "/old-path", "destination": "/new-path", "permanent": true }
+  ]
+}
+```
+
+### Framework Detection
+Vercel auto-detects frameworks. Override if needed:
+```json
+{
+  "framework": "nextjs" | "vite" | "remix" | "astro" | null
+}
+```
+
+## Environment Variables
+
+### Naming Conventions
+
+| Prefix | Exposure | Use Case |
+|--------|----------|----------|
+| `NEXT_PUBLIC_` | Browser + Server | Public API URLs, feature flags |
+| No prefix | Server only | API keys, secrets, database URLs |
+
+### Setting Environment Variables
+
+**Via CLI**
+```bash
+# Add to all environments
+vercel env add MY_SECRET
+
+# Add to specific environment
+vercel env add MY_SECRET production
+vercel env add MY_SECRET preview
+vercel env add MY_SECRET development
+```
+
+**Via Project Settings**
+1. Dashboard > Project > Settings > Environment Variables
+2. Add variable name and value
+3. Select environments (Production, Preview, Development)
+
+### Required Variables for Supabase + Stack-auth
+```env
+# Public (browser-accessible)
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+NEXT_PUBLIC_STACK_AUTH_URL=https://api.stack-auth.com
+NEXT_PUBLIC_STACK_AUTH_PROJECT_ID=your-project-id
+
+# Server-only secrets
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+STACK_AUTH_SECRET_KEY=sk_...
+```
+
+### Pulling Environment Variables Locally
+```bash
+# Link project first
+vercel link
+
+# Pull env vars to .env.local
+vercel env pull .env.local
+```
+
+## Build Configuration
+
+### Build Commands
+```json
+{
+  "buildCommand": "npm run build",
+  "installCommand": "npm ci",
+  "devCommand": "npm run dev"
+}
+```
+
+### Build Output Settings
+```json
+{
+  "outputDirectory": ".next",
+  "cleanUrls": true,
+  "trailingSlash": false
+}
+```
+
+### Root Directory (Monorepo)
+```json
+{
+  "rootDirectory": "apps/web"
+}
+```
+
+## Deployment Types
+
+### Production Deployments
+```bash
+# Deploy to production
+vercel --prod
+
+# Or via git push to main branch
+git push origin main
+```
+
+### Preview Deployments
+- Automatic on PR creation
+- Unique URL per deployment
+- Comment on PR with preview link
+
+### Manual Deployments
+```bash
+# Deploy current directory
+vercel
+
+# Deploy specific directory
+vercel ./dist
+
+# Deploy with specific name
+vercel --name my-deployment
+```
+
+## Build Optimization
+
+### Caching
+```json
+{
+  "build": {
+    "env": {
+      "VERCEL_CACHE_KEY": "v1"
+    }
+  }
+}
+```
+
+### Ignore Build Step
+```bash
+# vercel.json or package.json script
+# Return exit code 0 to skip, 1 to build
+
+# Example: Skip if only docs changed
+git diff HEAD^ HEAD --quiet -- docs/
+```
+
+### Build Hooks
+```bash
+# Trigger build via webhook
+curl -X POST https://api.vercel.com/v1/integrations/deploy/YOUR_DEPLOY_HOOK
+```
+
+## Function Configuration
+
+### Serverless Functions
+```json
+{
+  "functions": {
+    "api/**/*.ts": {
+      "memory": 1024,
+      "maxDuration": 10
+    },
+    "api/heavy-task.ts": {
+      "memory": 3008,
+      "maxDuration": 60
+    }
+  }
+}
+```
+
+### Memory and Duration Limits
+
+| Plan | Max Memory | Max Duration |
+|------|------------|--------------|
+| Hobby | 1024 MB | 10s |
+| Pro | 3008 MB | 60s |
+| Enterprise | 3008 MB | 900s |
+
+## Domain Configuration
+
+### Adding Custom Domain
+```bash
+# Via CLI
+vercel domains add example.com
+
+# Verify DNS
+vercel domains verify example.com
+```
+
+### DNS Records
+```
+Type: A
+Name: @
+Value: 76.76.21.21
+
+Type: CNAME
+Name: www
+Value: cname.vercel-dns.com
+```
+
+## Deployment Protection
+
+### Password Protection (Preview)
+```json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        {
+          "key": "x-vercel-protection-bypass",
+          "value": "{{VERCEL_AUTOMATION_BYPASS_SECRET}}"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### IP Allowlisting
+Configure in Dashboard > Project > Settings > Deployment Protection
+
+## Monitoring and Logs
+
+### Viewing Logs
+```bash
+# Real-time logs
+vercel logs your-deployment-url
+
+# Via Dashboard
+# Project > Deployments > Select deployment > View Logs
+```
+
+### Speed Insights
+```typescript
+// Enable in next.config.js
+const config = {
+  experimental: {
+    instrumentationHook: true,
+  },
+}
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to Vercel
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy to Vercel
+        uses: amondnet/vercel-action@v25
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+          vercel-args: '--prod'
+```
+
+### Getting Credentials
+```bash
+# Get org ID and project ID
+vercel link
+# Check .vercel/project.json
+
+# Create token
+# Dashboard > Account Settings > Tokens
+```
+
+## Troubleshooting
+
+### Common Build Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Module not found` | Missing dependency | Check package.json, run `npm install` |
+| `Type error` | TypeScript error | Fix type errors before deploy |
+| `Out of memory` | Build too large | Increase memory or optimize |
+| `Build timeout` | Build too slow | Optimize build, use caching |
+
+### Debug Build Locally
+```bash
+# Simulate Vercel build
+vercel build
+
+# Check output
+ls -la .vercel/output/
+```
+
+### Rollback
+```bash
+# Via CLI
+vercel rollback
+
+# Or in Dashboard
+# Project > Deployments > ... > Promote to Production
+```
+
+## Best Practices
+
+### Security Checklist
+- [ ] No secrets in `NEXT_PUBLIC_` variables
+- [ ] Service role keys only on server
+- [ ] Deployment protection enabled for preview
+- [ ] Environment variables per environment
+
+### Performance Checklist
+- [ ] Enable caching headers for static assets
+- [ ] Use Edge runtime where appropriate
+- [ ] Minimize serverless function cold starts
+- [ ] Configure appropriate regions
+
+### Deployment Checklist
+- [ ] Test preview deployment before production
+- [ ] Verify environment variables are set
+- [ ] Check build logs for warnings
+- [ ] Monitor initial traffic after deploy