xtrm-tools 0.5.0

package/skills/updating-service-skills/scripts/drift_detector.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Drift detector — PostToolUse hook for updating-service-skills.
+
+Checks whether a modified file belongs to a registered service territory.
+If so, notifies Claude to sync the skill documentation.
+
+Configured via updating-service-skills/SKILL.md frontmatter hooks:
+  PostToolUse → matcher: "Write|Edit" → command: drift_detector.py check-hook
+
+Subcommands:
+  check-hook          Read file_path from stdin JSON (PostToolUse hook mode)
+  check <file>        Check a specific file path from CLI
+  sync <service-id>   Mark service as synced (update registry timestamp)
+  scan                Scan all territories for drifted services
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Bootstrap lives in creating-service-skills — shared utility
+BOOTSTRAP_DIR = Path(__file__).parent.parent.parent / "creating-service-skills" / "scripts"
+sys.path.insert(0, str(BOOTSTRAP_DIR))
+
+from bootstrap import (  # noqa: E402
+    RootResolutionError,
+    find_service_for_path,
+    get_project_root,
+    get_service,
+    load_registry,
+    save_registry,
+)
+
+
+def check_drift(file_path: str, project_root: str | None = None) -> dict:
+    """Check if a file change causes drift in any registered service territory."""
+    if project_root is None:
+        try:
+            project_root = get_project_root()
+        except RootResolutionError:
+            return {"drift": False, "reason": "Cannot resolve project root"}
+
+    # Normalize to relative path
+    fp = Path(file_path)
+    if fp.is_absolute():
+        try:
+            fp = fp.relative_to(project_root)
+            file_path = str(fp)
+        except ValueError:
+            pass
+
+    service_id = find_service_for_path(file_path, project_root)
+    if not service_id:
+        return {"drift": False, "reason": "No service owns this file"}
+
+    service = get_service(service_id, project_root)
+    if not service:
+        return {"drift": False, "reason": "Service not found in registry"}
+
+    return {
+        "drift": True,
+        "service_id": service_id,
+        "service_name": service.get("name", service_id),
+        "skill_path": service.get("skill_path"),
+        "last_sync": service.get("last_sync", ""),
+        "file_path": file_path,
+        "message": (
+            f"[Skill Sync]: Implementation drift detected in '{service_id}'. "
+            f"File '{file_path}' was modified. "
+            f"Use '/updating-service-skills' to sync the {service.get('name', service_id)} documentation."
+        ),
+    }
+
+
+def check_drift_from_hook_stdin() -> None:
+    """
+    PostToolUse hook mode: reads file_path from stdin JSON.
+
+    The PostToolUse hook delivers stdin JSON with shape:
+      {"tool_name": "Write", "tool_input": {"file_path": "/abs/path"}, ...}
+
+    Outputs drift message to stdout (shown to Claude via PostToolUse additionalContext).
+    Exits 0 always — drift detection is advisory, never blocking.
+    """
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+
+    tool_input = data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path:
+        sys.exit(0)
+
+    result = check_drift(file_path)
+
+    if result.get("drift"):
+        # Output additionalContext for Claude via PostToolUse JSON format
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": result["message"],
+            }
+        }
+        print(json.dumps(output))
+
+    sys.exit(0)
+
+
+def update_sync_time(service_id: str, project_root: str | None = None) -> bool:
+    """Update last_sync timestamp for a service in the registry."""
+    try:
+        registry = load_registry(project_root)
+    except Exception:
+        return False
+
+    if "services" not in registry or service_id not in registry["services"]:
+        return False
+
+    registry["services"][service_id]["last_sync"] = (
+        datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    try:
+        save_registry(registry, project_root)
+        return True
+    except Exception:
+        return False
+
+
+def scan_drift(project_root: str | None = None) -> list[dict]:
+    """Scan all territories and identify services with files modified since last sync."""
+    if project_root is None:
+        try:
+            project_root = get_project_root()
+        except RootResolutionError:
+            return []
+
+    root = Path(project_root)
+    registry = load_registry(project_root)
+    drifted: list[dict] = []
+
+    for service_id, service in registry.get("services", {}).items():
+        last_sync_str = service.get("last_sync", "")
+        if not last_sync_str:
+            continue
+        try:
+            sync_time = datetime.fromisoformat(last_sync_str.replace("Z", "+00:00"))
+        except ValueError:
+            continue
+
+        for pattern in service.get("territory", []):
+            for fp in root.glob(pattern):
+                if fp.is_file():
+                    try:
+                        mtime = datetime.fromtimestamp(fp.stat().st_mtime, tz=timezone.utc)
+                        if mtime > sync_time:
+                            drifted.append(
+                                {
+                                    "service_id": service_id,
+                                    "service_name": service.get("name", service_id),
+                                    "file_path": str(fp.relative_to(root)),
+                                    "last_sync": last_sync_str,
+                                }
+                            )
+                    except (OSError, ValueError):
+                        continue
+
+    return drifted
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python drift_detector.py <command> [args...]")
+        print("  check-hook          — Read file from stdin JSON (PostToolUse hook mode)")
+        print("  check <file>        — Check a specific file path")
+        print("  sync <service-id>   — Mark service as synced")
+        print("  scan                — Scan all territories for drift")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+
+    if cmd == "check-hook":
+        check_drift_from_hook_stdin()
+
+    elif cmd == "check" and len(sys.argv) > 2:
+        result = check_drift(sys.argv[2])
+        if result.get("drift"):
+            print(result["message"])
+        else:
+            print(f"No drift: {result.get('reason', 'OK')}")
+
+    elif cmd == "sync" and len(sys.argv) > 2:
+        service_id = sys.argv[2]
+        if update_sync_time(service_id):
+            print(f"✓ Synced: {service_id}")
+        else:
+            print(f"✗ Failed to sync: {service_id}")
+            sys.exit(1)
+
+    elif cmd == "scan":
+        drifted = scan_drift()
+        if drifted:
+            print(f"Found {len(drifted)} drifted service(s):")
+            for item in drifted:
+                print(
+                    f"  {item['service_id']}: {item['file_path']} "
+                    f"(last sync: {item['last_sync']})"
+                )
+        else:
+            print("No drift detected.")
+
+    else:
+        print(f"Unknown command: {cmd}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/using-TDD/SKILL.md

@@ -0,0 +1,410 @@
+---
+name: tdd-workflow
+description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
+origin: ECC
+---
+
+# Test-Driven Development Workflow
+
+This skill ensures all code development follows TDD principles with comprehensive test coverage.
+
+## When to Activate
+
+- Writing new features or functionality
+- Fixing bugs or issues
+- Refactoring existing code
+- Adding API endpoints
+- Creating new components
+
+## Core Principles
+
+### 1. Tests BEFORE Code
+ALWAYS write tests first, then implement code to make tests pass.
+
+### 2. Coverage Requirements
+- Minimum 80% coverage (unit + integration + E2E)
+- All edge cases covered
+- Error scenarios tested
+- Boundary conditions verified
+
+### 3. Test Types
+
+#### Unit Tests
+- Individual functions and utilities
+- Component logic
+- Pure functions
+- Helpers and utilities
+
+#### Integration Tests
+- API endpoints
+- Database operations
+- Service interactions
+- External API calls
+
+#### E2E Tests (Playwright)
+- Critical user flows
+- Complete workflows
+- Browser automation
+- UI interactions
+
+## TDD Workflow Steps
+
+### Step 1: Write User Journeys
+```
+As a [role], I want to [action], so that [benefit]
+
+Example:
+As a user, I want to search for markets semantically,
+so that I can find relevant markets even without exact keywords.
+```
+
+### Step 2: Generate Test Cases
+For each user journey, create comprehensive test cases:
+
+```typescript
+describe('Semantic Search', () => {
+  it('returns relevant markets for query', async () => {
+    // Test implementation
+  })
+
+  it('handles empty query gracefully', async () => {
+    // Test edge case
+  })
+
+  it('falls back to substring search when Redis unavailable', async () => {
+    // Test fallback behavior
+  })
+
+  it('sorts results by similarity score', async () => {
+    // Test sorting logic
+  })
+})
+```
+
+### Step 3: Run Tests (They Should Fail)
+```bash
+npm test
+# Tests should fail - we haven't implemented yet
+```
+
+### Step 4: Implement Code
+Write minimal code to make tests pass:
+
+```typescript
+// Implementation guided by tests
+export async function searchMarkets(query: string) {
+  // Implementation here
+}
+```
+
+### Step 5: Run Tests Again
+```bash
+npm test
+# Tests should now pass
+```
+
+### Step 6: Refactor
+Improve code quality while keeping tests green:
+- Remove duplication
+- Improve naming
+- Optimize performance
+- Enhance readability
+
+### Step 7: Verify Coverage
+```bash
+npm run test:coverage
+# Verify 80%+ coverage achieved
+```
+
+## Testing Patterns
+
+### Unit Test Pattern (Jest/Vitest)
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button Component', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick}>Click</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Click</Button>)
+    expect(screen.getByRole('button')).toBeDisabled()
+  })
+})
+```
+
+### API Integration Test Pattern
+```typescript
+import { NextRequest } from 'next/server'
+import { GET } from './route'
+
+describe('GET /api/markets', () => {
+  it('returns markets successfully', async () => {
+    const request = new NextRequest('http://localhost/api/markets')
+    const response = await GET(request)
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.success).toBe(true)
+    expect(Array.isArray(data.data)).toBe(true)
+  })
+
+  it('validates query parameters', async () => {
+    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
+    const response = await GET(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('handles database errors gracefully', async () => {
+    // Mock database failure
+    const request = new NextRequest('http://localhost/api/markets')
+    // Test error handling
+  })
+})
+```
+
+### E2E Test Pattern (Playwright)
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user can search and filter markets', async ({ page }) => {
+  // Navigate to markets page
+  await page.goto('/')
+  await page.click('a[href="/markets"]')
+
+  // Verify page loaded
+  await expect(page.locator('h1')).toContainText('Markets')
+
+  // Search for markets
+  await page.fill('input[placeholder="Search markets"]', 'election')
+
+  // Wait for debounce and results
+  await page.waitForTimeout(600)
+
+  // Verify search results displayed
+  const results = page.locator('[data-testid="market-card"]')
+  await expect(results).toHaveCount(5, { timeout: 5000 })
+
+  // Verify results contain search term
+  const firstResult = results.first()
+  await expect(firstResult).toContainText('election', { ignoreCase: true })
+
+  // Filter by status
+  await page.click('button:has-text("Active")')
+
+  // Verify filtered results
+  await expect(results).toHaveCount(3)
+})
+
+test('user can create a new market', async ({ page }) => {
+  // Login first
+  await page.goto('/creator-dashboard')
+
+  // Fill market creation form
+  await page.fill('input[name="name"]', 'Test Market')
+  await page.fill('textarea[name="description"]', 'Test description')
+  await page.fill('input[name="endDate"]', '2025-12-31')
+
+  // Submit form
+  await page.click('button[type="submit"]')
+
+  // Verify success message
+  await expect(page.locator('text=Market created successfully')).toBeVisible()
+
+  // Verify redirect to market page
+  await expect(page).toHaveURL(/\/markets\/test-market/)
+})
+```
+
+## Test File Organization
+
+```
+src/
+├── components/
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.test.tsx          # Unit tests
+│   │   └── Button.stories.tsx       # Storybook
+│   └── MarketCard/
+│       ├── MarketCard.tsx
+│       └── MarketCard.test.tsx
+├── app/
+│   └── api/
+│       └── markets/
+│           ├── route.ts
+│           └── route.test.ts         # Integration tests
+└── e2e/
+    ├── markets.spec.ts               # E2E tests
+    ├── trading.spec.ts
+    └── auth.spec.ts
+```
+
+## Mocking External Services
+
+### Supabase Mock
+```typescript
+jest.mock('@/lib/supabase', () => ({
+  supabase: {
+    from: jest.fn(() => ({
+      select: jest.fn(() => ({
+        eq: jest.fn(() => Promise.resolve({
+          data: [{ id: 1, name: 'Test Market' }],
+          error: null
+        }))
+      }))
+    }))
+  }
+}))
+```
+
+### Redis Mock
+```typescript
+jest.mock('@/lib/redis', () => ({
+  searchMarketsByVector: jest.fn(() => Promise.resolve([
+    { slug: 'test-market', similarity_score: 0.95 }
+  ])),
+  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
+}))
+```
+
+### OpenAI Mock
+```typescript
+jest.mock('@/lib/openai', () => ({
+  generateEmbedding: jest.fn(() => Promise.resolve(
+    new Array(1536).fill(0.1) // Mock 1536-dim embedding
+  ))
+}))
+```
+
+## Test Coverage Verification
+
+### Run Coverage Report
+```bash
+npm run test:coverage
+```
+
+### Coverage Thresholds
+```json
+{
+  "jest": {
+    "coverageThresholds": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  }
+}
+```
+
+## Common Testing Mistakes to Avoid
+
+### ❌ WRONG: Testing Implementation Details
+```typescript
+// Don't test internal state
+expect(component.state.count).toBe(5)
+```
+
+### ✅ CORRECT: Test User-Visible Behavior
+```typescript
+// Test what users see
+expect(screen.getByText('Count: 5')).toBeInTheDocument()
+```
+
+### ❌ WRONG: Brittle Selectors
+```typescript
+// Breaks easily
+await page.click('.css-class-xyz')
+```
+
+### ✅ CORRECT: Semantic Selectors
+```typescript
+// Resilient to changes
+await page.click('button:has-text("Submit")')
+await page.click('[data-testid="submit-button"]')
+```
+
+### ❌ WRONG: No Test Isolation
+```typescript
+// Tests depend on each other
+test('creates user', () => { /* ... */ })
+test('updates same user', () => { /* depends on previous test */ })
+```
+
+### ✅ CORRECT: Independent Tests
+```typescript
+// Each test sets up its own data
+test('creates user', () => {
+  const user = createTestUser()
+  // Test logic
+})
+
+test('updates user', () => {
+  const user = createTestUser()
+  // Update logic
+})
+```
+
+## Continuous Testing
+
+### Watch Mode During Development
+```bash
+npm test -- --watch
+# Tests run automatically on file changes
+```
+
+### Pre-Commit Hook
+```bash
+# Runs before every commit
+npm test && npm run lint
+```
+
+### CI/CD Integration
+```yaml
+# GitHub Actions
+- name: Run Tests
+  run: npm test -- --coverage
+- name: Upload Coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Best Practices
+
+1. **Write Tests First** - Always TDD
+2. **One Assert Per Test** - Focus on single behavior
+3. **Descriptive Test Names** - Explain what's tested
+4. **Arrange-Act-Assert** - Clear test structure
+5. **Mock External Dependencies** - Isolate unit tests
+6. **Test Edge Cases** - Null, undefined, empty, large
+7. **Test Error Paths** - Not just happy paths
+8. **Keep Tests Fast** - Unit tests < 50ms each
+9. **Clean Up After Tests** - No side effects
+10. **Review Coverage Reports** - Identify gaps
+
+## Success Metrics
+
+- 80%+ code coverage achieved
+- All tests passing (green)
+- No skipped or disabled tests
+- Fast test execution (< 30s for unit tests)
+- E2E tests cover critical user flows
+- Tests catch bugs before production
+
+---
+
+**Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.