@bradtaylorsf/alpha-loop 1.1.2 → 1.2.0

package/templates/skills/playwright-testing/SKILL.md

@@ -1,124 +0,0 @@
-# Playwright E2E Testing Skill
-
-## Overview
-
-This skill teaches agents how to write and maintain Playwright end-to-end tests for the Alpha Loop dashboard. E2E tests validate that the app works visually in a browser, catching issues that pass unit tests but break the UI.
-
-## Test Configuration
-
-- **Test directory**: `tests/e2e/`
-- **Config file**: `playwright.config.ts`
-- **E2E port**: `4002` (isolated from dev 4001 and prod 4000)
-- **Database**: In-memory SQLite (`DATABASE_PATH=:memory:`)
-- **Mock API**: `MOCK_CLAUDE_API=true` to avoid real AI calls
-- **Browser**: Chromium only
-- **Run command**: `pnpm test:e2e`
-
-## Writing E2E Tests
-
-### File naming
-
-- Place tests in `tests/e2e/`
-- Use `.spec.ts` suffix (e.g., `dashboard.spec.ts`)
-
-### Test structure
-
-```typescript
-import { test, expect } from "@playwright/test";
-
-test.describe("Feature Name", () => {
-  test("describes what it validates", async ({ page }) => {
-    await page.goto("/");
-    // Use waitForSelector or expect with auto-waiting
-    await expect(page.locator("h1")).toHaveText("Alpha Loop");
-  });
-});
-```
-
-### Best practices for reliability
-
-1. **Use Playwright auto-waiting** — `expect(locator).toBeVisible()` auto-waits up to the configured timeout
-2. **Avoid fixed timeouts** — use `waitForSelector`, `waitForResponse`, or `expect` assertions instead of `page.waitForTimeout()`
-3. **Use data-testid attributes** — prefer `[data-testid='config-view']` over fragile CSS selectors
-4. **Clean up state** — each test should work in isolation, don't depend on test execution order
-5. **Seed test data via API** — create test data by hitting API endpoints, not by manipulating the DB directly
-
-### Seeding test data
-
-```typescript
-test("shows runs created via API", async ({ request, page }) => {
-  // Create test data via API
-  await request.post("/api/runs", {
-    data: {
-      issue_number: 42,
-      issue_title: "Test issue",
-      agent: "claude",
-      model: "sonnet",
-    },
-  });
-
-  // Navigate and verify
-  await page.goto("/");
-  await page.click("button:has-text('Run History')");
-  await expect(page.locator("text=Test issue")).toBeVisible();
-});
-```
-
-### Testing SSE / Live View
-
-```typescript
-test("live view connects to SSE stream", async ({ page }) => {
-  await page.goto("/");
-  // The EventSource connection happens automatically
-  await expect(page.locator("text=Connected")).toBeVisible({ timeout: 5000 });
-});
-```
-
-### Common selectors
-
-| Element | Selector |
-|---------|----------|
-| App title | `h1` (text: "Alpha Loop") |
-| Tab buttons | `button:has-text('Live View')`, `button:has-text('Run History')`, `button:has-text('Config')` |
-| Live log | `[data-testid='live-log']` |
-| Config view | `[data-testid='config-view']` |
-| Config editor | `[data-testid='config-editor']` |
-| Status badge | `[data-testid='status-badge']` |
-| History table | `table` within Run History tab |
-
-## Running E2E Tests
-
-```bash
-# Run all E2E tests
-pnpm test:e2e
-
-# Run with headed browser (for debugging)
-npx playwright test --headed
-
-# Run a specific test file
-npx playwright test tests/e2e/dashboard.spec.ts
-
-# Show test report after failure
-npx playwright show-report
-```
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SKIP_E2E` | `false` | Skip Playwright in the loop pipeline |
-| `DATABASE_PATH` | file path | Set to `:memory:` for in-memory SQLite |
-| `MOCK_CLAUDE_API` | `false` | Mock Claude API calls |
-| `PORT` | `4000` | Server port (E2E uses `4002`) |
-
-## Integration with Loop Pipeline
-
-E2E tests run after unit/API tests in the loop pipeline:
-
-1. Implement
-2. Run unit/API tests (with retry)
-3. **Run Playwright E2E tests** (with same retry loop)
-4. Code review
-5. Create PR
-
-If `SKIP_E2E=true`, the E2E step is skipped. E2E test failures trigger the same retry loop as unit tests — the agent receives the error output and attempts to fix the issue.

package/templates/skills/sqlite-patterns/SKILL.md

@@ -1,229 +0,0 @@
----
-name: sqlite-patterns
-description: SQLite database patterns using better-sqlite3. Synchronous API, file-based storage, great for single-user apps and development.
----
-
-# SQLite Patterns Skill
-
-Patterns for SQLite database operations using better-sqlite3.
-
-## When to Use SQLite
-
-- Single-user applications
-- Development/prototyping
-- File-based storage needs
-- Simple applications without concurrency
-- Embedded databases
-
-## Setup
-
-```typescript
-import Database from 'better-sqlite3';
-
-// Production
-const db = new Database('./data/app.db');
-
-// Testing (in-memory)
-const testDb = new Database(':memory:');
-
-// Enable WAL mode for better performance
-db.pragma('journal_mode = WAL');
-```
-
-## Basic Patterns
-
-### Query Single Row
-
-```typescript
-function getUserById(id: number): User | null {
-  const result = db.prepare(`
-    SELECT id, email, name, created_at as createdAt
-    FROM users
-    WHERE id = ?
-  `).get(id);
-
-  return result ?? null; // better-sqlite3 returns undefined, not null
-}
-```
-
-### Query Multiple Rows
-
-```typescript
-function getAllUsers(): User[] {
-  return db.prepare(`
-    SELECT id, email, name, created_at as createdAt
-    FROM users
-    ORDER BY created_at DESC
-  `).all() as User[];
-}
-```
-
-### Insert and Get ID
-
-```typescript
-function createUser(data: CreateUserDto): User {
-  const stmt = db.prepare(`
-    INSERT INTO users (email, password_hash, name)
-    VALUES (?, ?, ?)
-  `);
-
-  const info = stmt.run(data.email, passwordHash, data.name);
-  const id = info.lastInsertRowid;
-
-  return getUserById(Number(id))!;
-}
-```
-
-### Update
-
-```typescript
-function updateUser(id: number, updates: UpdateUserDto): User | null {
-  const stmt = db.prepare(`
-    UPDATE users
-    SET email = COALESCE(?, email),
-        name = COALESCE(?, name),
-        updated_at = datetime('now')
-    WHERE id = ?
-  `);
-
-  const info = stmt.run(updates.email, updates.name, id);
-
-  if (info.changes === 0) return null;
-  return getUserById(id);
-}
-```
-
-### Delete
-
-```typescript
-function deleteUser(id: number): boolean {
-  const info = db.prepare('DELETE FROM users WHERE id = ?').run(id);
-  return info.changes > 0;
-}
-```
-
-## Transactions
-
-```typescript
-function transferFunds(fromId: number, toId: number, amount: number): void {
-  const transfer = db.transaction(() => {
-    db.prepare('UPDATE accounts SET balance = balance - ? WHERE id = ?')
-      .run(amount, fromId);
-
-    db.prepare('UPDATE accounts SET balance = balance + ? WHERE id = ?')
-      .run(amount, toId);
-  });
-
-  transfer(); // Automatically rolls back on error
-}
-```
-
-## JSON Fields
-
-```typescript
-// Store JSON
-function saveSettings(userId: number, settings: Settings): void {
-  db.prepare(`
-    UPDATE users SET settings = ? WHERE id = ?
-  `).run(JSON.stringify(settings), userId);
-}
-
-// Parse JSON
-function getSettings(userId: number): Settings {
-  const result = db.prepare(`
-    SELECT settings FROM users WHERE id = ?
-  `).get(userId) as { settings: string } | undefined;
-
-  return result ? JSON.parse(result.settings) : {};
-}
-
-// Helper for safe JSON parsing
-function parseJsonField<T>(value: string | null | undefined, fallback: T): T {
-  if (!value) return fallback;
-  try {
-    return JSON.parse(value) as T;
-  } catch {
-    return fallback;
-  }
-}
-```
-
-## Migrations
-
-```sql
--- migrations/001_create_users.sql
-CREATE TABLE IF NOT EXISTS users (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  email TEXT UNIQUE NOT NULL,
-  password_hash TEXT NOT NULL,
-  name TEXT NOT NULL,
-  settings TEXT DEFAULT '{}',
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE INDEX idx_users_email ON users(email);
-```
-
-```typescript
-// Run migrations
-function runMigrations(db: Database.Database): void {
-  const migrations = fs.readdirSync('./migrations')
-    .filter(f => f.endsWith('.sql'))
-    .sort();
-
-  for (const file of migrations) {
-    const sql = fs.readFileSync(`./migrations/${file}`, 'utf-8');
-    db.exec(sql);
-  }
-}
-```
-
-## Error Handling
-
-```typescript
-function createUser(data: CreateUserDto): User {
-  try {
-    // ... insert logic
-  } catch (error: unknown) {
-    if (error instanceof Error && 'code' in error) {
-      const sqliteError = error as { code: string };
-      if (sqliteError.code === 'SQLITE_CONSTRAINT') {
-        throw new AppError('Email already exists', 400);
-      }
-    }
-    throw error;
-  }
-}
-```
-
-## Timestamps
-
-```typescript
-// SQLite datetime format
-const now = new Date().toISOString(); // '2024-01-15T10:30:00.000Z'
-
-// Or use SQLite's built-in
-db.prepare(`
-  INSERT INTO logs (message, created_at)
-  VALUES (?, datetime('now'))
-`).run(message);
-```
-
-## Best Practices
-
-1. **Use prepared statements** - Prevents SQL injection
-2. **Use transactions** - For multiple related operations
-3. **Enable WAL mode** - Better concurrent read performance
-4. **Use in-memory for tests** - Fast, isolated testing
-5. **Handle undefined** - better-sqlite3 returns undefined, not null
-6. **Index foreign keys** - Improve JOIN performance
-7. **Use COALESCE for updates** - Partial updates without overwriting
-
-## Common Gotchas
-
-- Returns `undefined` not `null` for missing rows
-- `lastInsertRowid` is a BigInt (convert with Number())
-- JSON must be stringified before storage
-- Datetime stored as TEXT (ISO format recommended)
-- No native boolean type (use INTEGER 0/1)

package/templates/skills/test-caching/SKILL.md

@@ -1,99 +0,0 @@
----
-name: test-caching
-description: API response caching for expensive AI API calls in tests. Use when writing tests that call Claude, OpenAI, or other AI APIs.
-auto_load: false
-priority: medium
----
-
-# Test Caching Skill
-
-## Trigger
-When writing tests that make HTTP calls to AI/LLM APIs (Claude, OpenAI, etc.) or any expensive external API.
-
-## How It Works
-
-The `mockExpensiveAPI()` helper intercepts HTTP requests matching a URL pattern.
-
-- **Default mode** (`pnpm test`): Replays responses from fixture files in `tests/fixtures/`. No network calls.
-- **Record mode** (`RECORD_FIXTURES=true` / `pnpm test:full`): Lets real requests through, captures responses to fixture files.
-
-## Usage
-
-```typescript
-import { mockExpensiveAPI } from '../../src/testing/cache';
-
-describe('my AI feature', () => {
-  let mock: ReturnType<typeof mockExpensiveAPI>;
-
-  beforeEach(() => {
-    mock = mockExpensiveAPI({
-      name: 'my-feature-openai',        // fixture filename
-      pattern: 'https://api.openai.com', // URL prefix to intercept
-      service: 'openai',                 // metadata
-      estimatedCostUSD: 0.02,            // metadata
-    });
-  });
-
-  afterEach(() => {
-    mock.restore(); // always restore HTTP patches
-  });
-
-  it('calls the AI API', async () => {
-    // In replay mode, this returns the cached response
-    // In record mode, this hits the real API and saves the response
-    const result = await callMyAIFeature();
-    expect(result).toBeDefined();
-  });
-});
-```
-
-## Options
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `name` | Yes | Unique fixture name (becomes `<name>.fixture.json`) |
-| `pattern` | Yes | URL prefix (string) or RegExp to intercept |
-| `service` | No | Service name for metadata (default: `"unknown"`) |
-| `estimatedCostUSD` | No | Cost per call for metadata (default: `0`) |
-| `fixturesDir` | No | Override fixture directory (default: `tests/fixtures/`) |
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `pnpm test` | Run tests with cached API responses (default) |
-| `pnpm test:full` | Run tests with real API calls, re-record fixtures |
-
-## Fixture Format
-
-Fixtures are stored as JSON arrays in `tests/fixtures/<name>.fixture.json`:
-
-```json
-[
-  {
-    "request": { "url": "https://api.openai.com/v1/chat", "method": "POST", "body": { "model": "gpt-4" } },
-    "response": { "status": 200, "headers": {}, "body": { "choices": [] } },
-    "metadata": { "recordedAt": "2025-01-15T10:00:00.000Z", "service": "openai", "estimatedCostUSD": 0.02 }
-  }
-]
-```
-
-## Cache Invalidation
-
-Fixtures older than 30 days produce a warning at test startup. Re-record with `RECORD_FIXTURES=true` to refresh.
-
-## In the Loop
-
-`scripts/loop.sh` uses cached mode by default. Pass `--run-full` to bypass cache:
-
-```bash
-bash scripts/loop.sh --run-full    # real API calls
-bash scripts/loop.sh               # cached (default)
-```
-
-## Rules
-
-1. Always call `mock.restore()` in `afterEach` to undo HTTP patches
-2. Commit fixture files to git so CI can replay without API keys
-3. Use descriptive `name` values — one fixture per test scenario
-4. Check `mock.warnings` for staleness alerts in your test setup