cfsa-antigravity 2.0.0 → 2.2.0

package/template/.agent/skills/testing-strategist/references/typescript.md

@@ -0,0 +1,328 @@
+# TypeScript Testing Patterns
+
+Language-specific patterns for the `testing-strategist` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Framework Stack
+
+| Level | Tool | Purpose |
+|-------|------|---------|
+| Unit | **Jest** or **Vitest** | Test runner, assertions, mocking |
+| Component | **React Testing Library** | User-centric component testing |
+| Integration | **Supertest** | HTTP API testing |
+| E2E | **Playwright** | Browser automation |
+
+## Commands
+
+```bash
+npm test                    # Run tests
+npm test -- --watch         # Watch mode
+npm run test:coverage       # Coverage report
+npx playwright test         # E2E tests
+open coverage/lcov-report/index.html  # View HTML report
+```
+
+---
+
+## Unit Test: Business Logic
+
+```typescript
+// src/lib/pricing.ts
+export function calculateTotal(items: { price: number; quantity: number }[]) {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+}
+
+export function applyDiscount(total: number, discountPercent: number) {
+  if (discountPercent < 0 || discountPercent > 100) {
+    throw new Error('Invalid discount percentage')
+  }
+  return total * (1 - discountPercent / 100)
+}
+
+// src/lib/pricing.test.ts
+import { calculateTotal, applyDiscount } from './pricing'
+
+describe('calculateTotal', () => {
+  it('calculates total for single item', () => {
+    const items = [{ price: 10, quantity: 2 }]
+    expect(calculateTotal(items)).toBe(20)
+  })
+
+  it('calculates total for multiple items', () => {
+    const items = [
+      { price: 10, quantity: 2 },
+      { price: 5, quantity: 3 }
+    ]
+    expect(calculateTotal(items)).toBe(35)
+  })
+
+  it('returns 0 for empty array', () => {
+    expect(calculateTotal([])).toBe(0)
+  })
+})
+
+describe('applyDiscount', () => {
+  it('applies discount correctly', () => {
+    expect(applyDiscount(100, 20)).toBe(80)
+  })
+
+  it('throws error for invalid discount', () => {
+    expect(() => applyDiscount(100, -10)).toThrow('Invalid discount')
+    expect(() => applyDiscount(100, 150)).toThrow('Invalid discount')
+  })
+})
+```
+
+## Unit Test: React Components
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('applies primary variant by default', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByRole('button')).toHaveClass('btn-primary')
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick}>Click me</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+})
+```
+
+## Unit Test: Custom Hooks
+
+```typescript
+import { renderHook, act } from '@testing-library/react'
+import { useCounter } from './useCounter'
+
+describe('useCounter', () => {
+  it('initializes with default value', () => {
+    const { result } = renderHook(() => useCounter())
+    expect(result.current.count).toBe(0)
+  })
+
+  it('increments count', () => {
+    const { result } = renderHook(() => useCounter())
+    act(() => { result.current.increment() })
+    expect(result.current.count).toBe(1)
+  })
+
+  it('resets to initial value', () => {
+    const { result } = renderHook(() => useCounter(10))
+    act(() => {
+      result.current.increment()
+      result.current.reset()
+    })
+    expect(result.current.count).toBe(10)
+  })
+})
+```
+
+---
+
+## Integration Test: API Routes
+
+```typescript
+import { testClient } from '@/lib/test-utils'
+
+describe('POST /api/posts', () => {
+  beforeEach(async () => {
+    await db.post.deleteMany()
+  })
+
+  it('creates a new post', async () => {
+    const response = await testClient
+      .post('/api/posts')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ title: 'Test Post', content: 'This is a test post' })
+
+    expect(response.status).toBe(201)
+    expect(response.body).toMatchObject({
+      title: 'Test Post',
+      content: 'This is a test post'
+    })
+
+    // Verify in database
+    const posts = await db.post.findMany()
+    expect(posts).toHaveLength(1)
+    expect(posts[0].title).toBe('Test Post')
+  })
+
+  it('returns 400 for invalid data', async () => {
+    const response = await testClient
+      .post('/api/posts')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ title: '' })
+
+    expect(response.status).toBe(400)
+    expect(response.body.errors).toBeDefined()
+  })
+
+  it('returns 401 for unauthenticated request', async () => {
+    const response = await testClient.post('/api/posts')
+      .send({ title: 'Test', content: 'Test' })
+
+    expect(response.status).toBe(401)
+  })
+})
+```
+
+## Integration Test: Database Operations
+
+```typescript
+describe('userRepository', () => {
+  beforeEach(async () => { await db.user.deleteMany() })
+  afterAll(async () => { await db.$disconnect() })
+
+  describe('createUser', () => {
+    it('creates user with hashed password', async () => {
+      const user = await createUser({
+        email: 'test@example.com',
+        password: 'password123'
+      })
+
+      expect(user.email).toBe('test@example.com')
+      expect(user.password).not.toBe('password123')
+      expect(user.password).toMatch(/^\$2[aby]/) // bcrypt hash
+    })
+
+    it('throws error for duplicate email', async () => {
+      await createUser({ email: 'test@example.com', password: 'pass' })
+      await expect(createUser({ email: 'test@example.com', password: 'pass' }))
+        .rejects.toThrow()
+    })
+  })
+})
+```
+
+---
+
+## E2E Test: Playwright
+
+```typescript
+import { test, expect } from '@playwright/test'
+
+test.describe('Authentication', () => {
+  test('user can sign up and log in', async ({ page }) => {
+    await page.goto('/signup')
+    await page.fill('input[name="email"]', 'test@example.com')
+    await page.fill('input[name="password"]', 'SecurePass123!')
+    await page.fill('input[name="confirmPassword"]', 'SecurePass123!')
+    await page.click('button[type="submit"]')
+
+    await expect(page).toHaveURL('/dashboard')
+    await expect(page.locator('h1')).toContainText('Welcome')
+  })
+
+  test('shows error for invalid credentials', async ({ page }) => {
+    await page.goto('/login')
+    await page.fill('input[name="email"]', 'wrong@example.com')
+    await page.fill('input[name="password"]', 'wrongpassword')
+    await page.click('button[type="submit"]')
+
+    await expect(page.locator('[role="alert"]')).toContainText('Invalid credentials')
+    await expect(page).toHaveURL('/login')
+  })
+})
+```
+
+---
+
+## Mocking
+
+```typescript
+// Mock external API
+import { fetchUserData } from '@/lib/api'
+
+jest.mock('@/lib/api')
+const mockFetchUserData = fetchUserData as jest.MockedFunction<typeof fetchUserData>
+
+it('displays user data', async () => {
+  mockFetchUserData.mockResolvedValue({
+    id: '1', name: 'John Doe', email: 'john@example.com'
+  })
+
+  render(<UserProfile userId="1" />)
+
+  await waitFor(() => {
+    expect(screen.getByText('John Doe')).toBeInTheDocument()
+  })
+})
+
+// Mock Date
+beforeAll(() => {
+  jest.useFakeTimers()
+  jest.setSystemTime(new Date('2024-01-01'))
+})
+afterAll(() => { jest.useRealTimers() })
+
+// Mock Math.random
+const mockRandom = jest.spyOn(Math, 'random')
+mockRandom.mockReturnValue(0.5)
+// ... assertions ...
+mockRandom.mockRestore()
+```
+
+---
+
+## Coverage Configuration
+
+```javascript
+// jest.config.js
+module.exports = {
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/**/*.stories.tsx',
+    '!src/types/**'
+  ],
+  coverageThresholds: {
+    global: {
+      branches: 70, functions: 70, lines: 70, statements: 70
+    },
+    './src/lib/auth/**': {
+      branches: 90, functions: 90, lines: 90
+    }
+  }
+}
+```
+
+## CI/CD
+
+```yaml
+- name: Run Tests
+  run: npm test -- --coverage
+- name: Upload Coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Assertion Examples
+
+### ❌ Shallow (BANNED)
+```typescript
+expect(result).toBeDefined()
+expect(result).toBeTruthy()
+```
+
+### ✅ Deep (REQUIRED)
+```typescript
+expect(result).toEqual({
+  id: expect.any(String),
+  name: 'Test',
+  items: expect.arrayContaining([
+    expect.objectContaining({ amount: 100 })
+  ])
+})
+```

package/template/.agent/skills/workflow-automation/SKILL.md

@@ -1,10 +1,7 @@
 ---
 name: workflow-automation
-description: "Architect durable, event-driven workflows using platforms like Inngest, Temporal, and BullMQ. Covers step functions, retry strategies, idempotency, fan-out patterns, and the critical differences between orchestration approaches."
+description: "Architect durable, event-driven workflows using step functions, retry strategies, idempotency, fan-out patterns, and the critical differences between orchestration approaches."
 version: 2.0.0
-source: self
-date_added: "2026-02-27"
-date_rewritten: "2026-03-14"
 ---
 
 # Workflow Automation
@@ -21,31 +18,39 @@ You are a workflow architect who understands the fundamental tradeoff: **simplic
 
 ## When NOT to Use
 
-- Simple fire-and-forget tasks (use a queue or `setTimeout`)
+- Simple fire-and-forget tasks (use a queue or a delay)
 - Synchronous request-response flows
 - Tasks under 100ms that don't involve external services
 
+## Ecosystem-Specific References
+
+After reading the methodology below, read the reference matching your orchestration platform:
+
+| Platform | Reference | Best For |
+|----------|-----------|----------|
+| Inngest | `references/inngest.md` | Serverless, event-driven, fast shipping |
+| Temporal | `references/temporal.md` | Complex orchestration, human-in-the-loop |
+| BullMQ | `references/bullmq.md` | Simple job queues, rate limiting, Redis stack |
+
 ---
 
 ## Core Concept: Durable Execution
 
-The fundamental insight: **wrap each unit of work in a step, so the system can retry, resume, and checkpoint independently.**
+**Wrap each unit of work in a step, so the system can retry, resume, and checkpoint independently.**
 
-Without durable execution:
-```
-fetch data → process → save → send email
-         ↑ server crashes here
-         ↓ entire pipeline reruns from scratch
-         ↓ customer gets duplicate email
 ```
+Without durable execution:
+  fetch data → process → save → send email
+           ↑ server crashes here
+           ↓ entire pipeline reruns from scratch
+           ↓ customer gets duplicate email
 
 With durable execution:
-```
-step("fetch")  ✓ saved
-step("process") ✓ saved
-step("save")    ← server crashes here
-step("save")    ← retries ONLY this step
-step("email")   ✓ runs once
+  step("fetch")   ✓ saved
+  step("process") ✓ saved
+  step("save")    ← server crashes here
+  step("save")    ← retries ONLY this step
+  step("email")   ✓ runs once
 ```
 
 ---
@@ -57,17 +62,17 @@ step("email")   ✓ runs once
 | **Complexity** | Low (serverless functions) | High (workers + server) | Medium (Redis-backed) |
 | **Durability** | Steps checkpointed | Full workflow replay | Job-level retry |
 | **Infrastructure** | Managed or self-hosted | Requires Temporal Server | Requires Redis |
-| **Best for** | Serverless, Next.js, event-driven | Complex orchestration, long-running | Simple job queues, rate limiting |
+| **Best for** | Serverless, event-driven | Complex orchestration | Simple job queues |
 | **Learning curve** | 1-2 days | 1-2 weeks | 1-2 days |
 | **Language support** | TS, Python, Go | TS, Go, Java, Python, .NET | TS/JS only |
 
 ### Decision Rules
 
 1. **Serverless + event-driven?** → Inngest
-2. **Complex orchestration, human-in-the-loop, multi-day workflows?** → Temporal
-3. **Simple job queue with rate limiting, Redis already in stack?** → BullMQ
+2. **Complex orchestration, human-in-the-loop, multi-day?** → Temporal
+3. **Simple job queue, Redis already in stack?** → BullMQ
 4. **Team of 1-3, shipping fast?** → Inngest
-5. **Enterprise, compliance-heavy, existing Java/.NET stack?** → Temporal
+5. **Enterprise, compliance-heavy, Java/.NET stack?** → Temporal
 
 ---
 
@@ -75,85 +80,28 @@ step("email")   ✓ runs once
 
 Each step depends on the previous result. Steps checkpoint independently.
 
-### Inngest
-
-```typescript
-const syncUser = inngest.createFunction(
-  { id: "sync-user-data" },
-  { event: "user/signup.completed" },
-  async ({ event, step }) => {
-    const user = await step.run("create-db-record", async () => {
-      return db.users.create({ email: event.data.email });
-    });
-
-    const stripeCustomer = await step.run("create-stripe-customer", async () => {
-      return stripe.customers.create({ email: user.email });
-    });
-
-    await step.run("send-welcome-email", async () => {
-      return email.send({ to: user.email, template: "welcome" });
-    });
-  }
-);
 ```
-
-### Temporal
-
-```typescript
-// activities.ts
-export async function createDbRecord(email: string): Promise<User> {
-  return db.users.create({ email });
-}
-
-export async function createStripeCustomer(email: string): Promise<Customer> {
-  return stripe.customers.create({ email });
-}
-
-// workflows.ts
-const { createDbRecord, createStripeCustomer } = proxyActivities<typeof activities>({
-  startToCloseTimeout: "30 seconds",
-  retry: { initialInterval: "1s", maximumAttempts: 3 },
-});
-
-export async function syncUserWorkflow(email: string): Promise<void> {
-  const user = await createDbRecord(email);
-  const customer = await createStripeCustomer(user.email);
-}
+step("create-db-record")       → returns user
+step("create-stripe-customer") → uses user.email
+step("send-welcome-email")     → uses user.email
 ```
 
+If step 2 fails, only step 2 retries. Steps 1 and 3 are not re-executed.
+
 ---
 
 ## Pattern 2: Fan-Out (Parallel Execution)
 
 One event triggers multiple independent workflows. Each runs and retries independently.
 
-### Inngest
-
-```typescript
-// Each function subscribes to the same event — runs independently
-const sendWelcome = inngest.createFunction(
-  { id: "send-welcome-email" },
-  { event: "user/signup.completed" },
-  async ({ event, step }) => {
-    await step.run("send", async () => {
-      await email.send({ to: event.data.email, template: "welcome" });
-    });
-  }
-);
-
-const startTrial = inngest.createFunction(
-  { id: "start-stripe-trial" },
-  { event: "user/signup.completed" },
-  async ({ event, step }) => {
-    await step.run("create-trial", async () => {
-      await stripe.subscriptions.create({
-        customer: event.data.stripeId,
-        trial_period_days: 14,
-      });
-    });
-  }
-);
 ```
+Event: user/signup.completed
+  → Workflow A: send-welcome-email   (independent)
+  → Workflow B: create-stripe-trial  (independent)
+  → Workflow C: provision-workspace  (independent)
+```
+
+If Workflow B fails, Workflows A and C are unaffected.
 
 ---
 
@@ -161,72 +109,32 @@ const startTrial = inngest.createFunction(
 
 Prevent duplicate execution when the same event fires twice.
 
-```typescript
-const processPayment = inngest.createFunction(
-  {
-    id: "process-payment",
-    // Only runs once per unique orderId within 24h
-    idempotency: "event.data.orderId",
-  },
-  { event: "order/payment.requested" },
-  async ({ event, step }) => {
-    await step.run("charge", async () => {
-      return stripe.charges.create({
-        amount: event.data.amount,
-        idempotencyKey: event.data.orderId, // Stripe-level idempotency too
-      });
-    });
-  }
-);
-```
+**Rule:** Idempotency at the workflow level AND the external call level. Belt and suspenders.
 
-**Rule**: Idempotency at the workflow level AND the external call level. Belt and suspenders.
+- **Workflow level:** Deduplicate by event ID or business key (e.g., order ID)
+- **External call level:** Use idempotency keys on payment APIs, email sends, etc.
 
 ---
 
 ## Pattern 4: Scheduled/Recurring
 
-### Inngest
-
-```typescript
-const dailyReport = inngest.createFunction(
-  { id: "daily-metrics-report" },
-  { cron: "0 9 * * *" }, // 9am daily
-  async ({ step }) => {
-    const metrics = await step.run("fetch-metrics", fetchDailyMetrics);
-    await step.run("send-report", async () => sendSlackReport(metrics));
-  }
-);
-```
+Cron-triggered workflows with observability:
+- Scheduled trigger (e.g., daily at 9am)
+- Steps checkpoint independently
+- Failed runs are visible, retriable, and alertable
 
 ---
 
-## Pattern 5: Human-in-the-Loop (Temporal)
+## Pattern 5: Human-in-the-Loop
 
 Workflows that pause and wait for external input — approval flows, multi-day processes.
 
-```typescript
-export const approvalSignal = defineSignal<[boolean]>("approval");
-
-export async function purchaseWorkflow(amount: number): Promise<string> {
-  if (amount > 10000) {
-    let approved: boolean | undefined;
-
-    setHandler(approvalSignal, (isApproved) => {
-      approved = isApproved;
-    });
-
-    // Workflow sleeps until signal received or 72h timeout
-    const gotApproval = await condition(() => approved !== undefined, "72 hours");
-
-    if (!gotApproval || !approved) {
-      return "Purchase denied or timed out";
-    }
-  }
-
-  // Continue with purchase...
-  return "Purchase completed";
-}
+```
+workflow: purchaseWorkflow(amount)
+  if amount > threshold:
+    pause and wait for approval signal (up to 72h)
+    if no approval → deny
+  continue with purchase
 ```
 
 ---
@@ -235,19 +143,19 @@ export async function purchaseWorkflow(amount: number): Promise<string> {
 
 | Issue | Severity | Rule |
 |-------|----------|------|
-| No idempotency keys on external calls | Critical | ALWAYS use idempotency keys for payments, emails, API mutations |
-| Side effects in workflow code (Temporal) | Critical | Workflows must be deterministic — no I/O, no random, no Date.now() |
-| Giant payloads in step results | High | Steps return serialized data — keep under 256KB |
-| No timeouts on activities | High | ALWAYS set `startToCloseTimeout` — default infinite hangs forever |
-| Linear retry without backoff | Medium | ALWAYS use exponential backoff: `initialInterval * backoffCoefficient^attempt` |
-| Missing dead letter handling | High | Failed-after-all-retries jobs need a destination — don't silently drop them |
-| Monolithic workflows | Medium | Break workflows >10 steps into child workflows or separate functions |
+| No idempotency keys on external calls | Critical | ALWAYS use idempotency keys for payments, emails, mutations |
+| Side effects in workflow code (Temporal) | Critical | Workflows must be deterministic — no I/O, no random, no clock |
+| Giant payloads in step results | High | Steps serialize data — keep under 256KB |
+| No timeouts on activities | High | ALWAYS set timeouts — default infinite hangs forever |
+| Linear retry without backoff | Medium | ALWAYS use exponential backoff |
+| Missing dead letter handling | High | Failed-after-all-retries jobs need a destination |
+| Monolithic workflows | Medium | Break workflows >10 steps into child workflows |
 
 ## Anti-Patterns
 
 | Don't | Do |
 |-------|-----|
-| `setTimeout(fn, 3600000)` for delays | `step.sleep("wait-1h", "1h")` — survives restarts |
+| `setTimeout(fn, 3600000)` for delays | Platform sleep — survives restarts |
 | Global variables for workflow state | Step results and explicit state passing |
 | Retry loops in application code | Platform-level retry policies |
 | Polling in a loop for completion | Event-driven triggers or workflow signals |
@@ -255,4 +163,4 @@ export async function purchaseWorkflow(amount: number): Promise<string> {
 
 ## Related Skills
 
-Works with: `error-handling-patterns`, `deployment-procedures`, `inngest` (skill-library), `bullmq` (skill-library)
+Works with: `error-handling-patterns`, `deployment-procedures`