cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/testing-strategist/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: Testing Strategist
+description: Design and implement comprehensive testing strategies. Use when setting up tests, choosing test types, implementing TDD, or improving code quality. Covers unit tests, integration tests, E2E tests, test-driven development, and testing best practices.
+version: 1.0.0
+---
+
+# Testing Strategist
+
+Test the right things at the right level — write tests that give you confidence to ship.
+
+## Stack-Specific References
+
+After reading the methodology below, read the reference matching your surface's Languages column in the surface stack map (`.codex/instructions/tech-stack.md`):
+
+| Language | Reference |
+|----------|-----------|
+| TypeScript / JavaScript | `references/typescript.md` |
+| Python | `references/python.md` |
+| Go | `references/go.md` |
+| Rust | `references/rust.md` |
+
+## Core Principle
+
+**The Testing Pyramid:** 70% unit tests, 20% integration tests, 10% E2E tests.
+
+Tests should be:
+
+- **Fast** — Run in milliseconds (unit) to seconds (integration) to minutes (E2E)
+- **Isolated** — Test one thing at a time
+- **Repeatable** — Same input = same output
+- **Self-checking** — Pass/fail automatically, no manual verification
+- **Timely** — Written alongside code (or before, with TDD)
+
+---
+
+## The Testing Pyramid
+
+```
+           /\
+          /  \         E2E Tests (10%)
+         /----\        - Slow, brittle, expensive
+        /      \       - Test critical user journeys
+       /--------\      - Example: "User can complete checkout"
+      /          \
+     /------------\    Integration Tests (20%)
+    /              \   - Medium speed, test components together
+   /----------------\  - Example: "API endpoint returns correct data"
+  /                  \
+ /--------------------\ Unit Tests (70%)
+/______________________\ - Fast, isolated, test functions/components
+                        - Example: "calculateTotal returns sum"
+```
+
+### Why This Ratio?
+
+- **Unit tests:** Fast feedback, pinpoint bugs precisely, easy to maintain
+- **Integration tests:** Ensure components work together, catch interface issues
+- **E2E tests:** Verify actual user flows, catch UI bugs, but slow and brittle
+
+---
+
+## Level 1: Unit Tests (70%)
+
+### What to Test
+
+Test individual functions, components, or classes in isolation.
+
+**Good candidates:**
+
+- ✅ Business logic functions (calculations, validation, transformations)
+- ✅ Utility functions (formatting, parsing, etc.)
+- ✅ UI components (rendering, props, state)
+- ✅ Pure functions (same input = same output)
+
+**Skip:**
+
+- ❌ Third-party libraries (assume they work)
+- ❌ Framework internals
+- ❌ Simple getters/setters with no logic
+
+### Unit Test Best Practices
+
+✅ **Do:**
+
+- Test behavior, not implementation
+- Use descriptive test names
+- Follow AAA pattern: Arrange, Act, Assert
+- Test edge cases (empty, null, negative, boundary values)
+- Keep tests simple and readable
+
+❌ **Don't:**
+
+- Test private methods directly
+- Over-mock (makes tests brittle)
+- Test framework internals
+- Write tests that depend on other tests
+
+---
+
+## Level 2: Integration Tests (20%)
+
+### What to Test
+
+Test multiple units working together — typically API routes, database operations, or service integrations.
+
+**Good candidates:**
+
+- ✅ API endpoints (request → handler → database → response)
+- ✅ Database operations (queries, transactions)
+- ✅ Third-party integrations (payment, email, etc.)
+- ✅ Authentication flows
+- ✅ File upload/download
+
+### Integration Test Best Practices
+
+✅ **Do:**
+
+- Use test database (separate from development/production)
+- Clean up test data before/after each test
+- Test happy path + error cases
+- Test authentication/authorization
+- Use factories/fixtures for test data
+
+❌ **Don't:**
+
+- Test against production database
+- Leave test data behind
+- Mock database (defeats purpose of integration test)
+- Depend on external services (mock external APIs)
+
+---
+
+## Level 3: E2E Tests (10%)
+
+### What to Test
+
+Test complete user journeys through the actual UI.
+
+**Good candidates:**
+
+- ✅ Critical user flows (signup, login, checkout)
+- ✅ Core business processes
+- ✅ Multi-step workflows
+
+**Skip:**
+
+- ❌ Every possible UI interaction (too slow/brittle)
+- ❌ Edge cases (cover with unit/integration tests)
+
+### E2E Test Best Practices
+
+✅ **Do:**
+
+- Test critical paths only (< 20 tests)
+- Use stable selectors (test IDs, roles, labels — not CSS classes)
+- Run in CI/CD pipeline
+- Test across browsers if web surface
+- Take screenshots on failure
+
+❌ **Don't:**
+
+- Test every UI variation
+- Use fragile selectors (nth-child, CSS classes)
+- Run E2E tests on every commit (too slow)
+- Ignore flaky tests (fix or remove them)
+
+---
+
+## Test-Driven Development (TDD)
+
+### The Red-Green-Refactor Cycle
+
+1. **Red:** Write a failing test that defines expected behavior
+2. **Green:** Write minimal code to make it pass
+3. **Refactor:** Improve code while keeping tests green
+
+### When to Use TDD
+
+**Good for:**
+
+- ✅ Complex business logic
+- ✅ Bug fixes (write test that reproduces bug first)
+- ✅ Well-defined requirements
+- ✅ Critical algorithms
+
+**Skip for:**
+
+- ❌ Exploratory coding (don't know requirements yet)
+- ❌ Throwaway prototypes
+- ❌ Simple CRUD operations
+
+---
+
+## Mocking Strategies
+
+### When to Mock
+
+- ✅ External APIs (slow, unreliable, cost money)
+- ✅ Time/randomness (make tests deterministic)
+- ✅ File system operations
+- ✅ Database (in unit tests only — NEVER in integration tests)
+
+### Anti-Mock-Abuse Rules
+
+1. **Never mock what you own** — if you wrote the module, test it directly
+2. **One mock = one boundary** — only mock at the boundary between your code and external systems
+3. **Verify mock interactions** — assert that mocked deps were called with correct arguments
+4. **Mock return values, not internals** — mock the return value, not the internal implementation
+
+### Mocking Best Practices
+
+✅ **Do:**
+
+- Mock at boundaries (APIs, file system, network)
+- Restore mocks after tests
+- Make mocks realistic (same shape as real data)
+
+❌ **Don't:**
+
+- Over-mock (makes tests brittle and meaningless)
+- Mock your own code (test real behavior)
+- Leave mocks unreset between tests
+
+---
+
+## Assertion Depth Rules
+
+### ❌ Shallow Assertions (BANNED)
+
+Assertions that prove nothing about correctness:
+- "Result is defined" — undefined would also be defined
+- "Result is truthy" — empty arrays and objects are truthy
+- "Status is 200" alone — doesn't verify response body
+
+### ✅ Deep Assertions (REQUIRED)
+
+Every test must assert:
+1. **The correct output** — specific values, not just types
+2. **The correct side effects** — what changed in the system
+3. **The correct error behavior** — specific error type and message
+
+---
+
+## Code Coverage
+
+### Coverage Targets
+
+- **70% minimum** — Below this, you're missing important tests
+- **80% good** — Solid coverage of critical paths
+- **90%+ diminishing returns** — Chasing 100% often not worth it
+
+### What to Focus On
+
+**High priority (90%+ coverage):**
+
+- Business logic
+- Authentication/authorization
+- Payment processing
+- Data validation
+
+**Medium priority (70%+):**
+
+- API routes
+- Database queries
+- Utility functions
+
+**Low priority (okay to skip):**
+
+- UI components (test behavior, not rendering)
+- Configuration files
+- Type definitions
+
+---
+
+## Common Testing Patterns
+
+### Testing Async Code
+Write tests that properly wait for async operations to complete before asserting. Use your framework's async test utilities.
+
+### Testing Error Handling
+Mock dependencies to throw errors, then assert your code handles them correctly — shows the right error message, returns the right status code, logs appropriately.
+
+### Testing Forms
+Fill form fields programmatically, submit, and assert both the submission data and any validation errors.
+
+---
+
+## Test Organization
+
+### File Structure
+
+Tests co-locate with source files:
+
+```
+source-file.ext      → source-file.test.ext     (unit tests)
+route-handler.ext    → route-handler.test.ext   (integration tests)
+e2e/                 → feature-name.e2e.ext     (E2E tests)
+```
+
+### Naming Conventions
+
+- Unit/Integration: `*.test.*` or `*.spec.*`
+- E2E: `*.e2e.*` or `*.spec.*` (in tests/e2e/)
+- Test names should describe behavior: "returns X when Y" or "throws error for invalid input"
+
+---
+
+## When to Use This Skill
+
+- ✅ Setting up testing for new project
+- ✅ Choosing test frameworks
+- ✅ Deciding what to test and at what level
+- ✅ Implementing TDD
+- ✅ Improving code coverage
+- ✅ Fixing flaky tests
+
+---
+
+**Good tests give you confidence to ship.** ✅

package/template/.codex/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/.codex/skills/update-architecture-map/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: update-architecture-map
+description: Generate or refresh docs/ARCHITECTURE.md from current codebase state with evidence-backed component and data-flow mapping
+parameters:
+  - name: mode
+    type: string
+    required: false
+    description: Optional mode override (create|update)
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Verify latest phase validation report passed.
+2. Load architecture-mapping skill.
+3. Perform filesystem reconnaissance and deep file reads.
+4. Extract components, schemas, data flows, and key patterns with citations.
+5. Create/update `docs/ARCHITECTURE.md` holistically and refresh timestamp.
+6. Evaluate phase completion gate and emit phase-aware next-step guidance.