bros-harness 0.1.0

package/assets/opencode/skills/e2e-testing/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: e2e-testing
+description: Playwright E2E testing patterns, Page Object Model, configuration, CI/CD integration, artifact management, and flaky test strategies.
+origin: ECC
+---
+
+# E2E Testing Patterns
+
+Comprehensive Playwright patterns for building stable, fast, and maintainable E2E test suites.
+
+## Test File Organization
+
+```
+tests/
+├── e2e/
+│   ├── auth/
+│   │   ├── login.spec.ts
+│   │   ├── logout.spec.ts
+│   │   └── register.spec.ts
+│   ├── features/
+│   │   ├── browse.spec.ts
+│   │   ├── search.spec.ts
+│   │   └── create.spec.ts
+│   └── api/
+│       └── endpoints.spec.ts
+├── fixtures/
+│   ├── auth.ts
+│   └── data.ts
+└── playwright.config.ts
+```
+
+## Page Object Model (POM)
+
+```typescript
+import { Page, Locator } from '@playwright/test'
+
+export class ItemsPage {
+  readonly page: Page
+  readonly searchInput: Locator
+  readonly itemCards: Locator
+  readonly createButton: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.searchInput = page.locator('[data-testid="search-input"]')
+    this.itemCards = page.locator('[data-testid="item-card"]')
+    this.createButton = page.locator('[data-testid="create-btn"]')
+  }
+
+  async goto() {
+    await this.page.goto('/items')
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async search(query: string) {
+    await this.searchInput.fill(query)
+    await this.page.waitForResponse(resp => resp.url().includes('/api/search'))
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async getItemCount() {
+    return await this.itemCards.count()
+  }
+}
+```
+
+## Test Structure
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ItemsPage } from '../../pages/ItemsPage'
+
+test.describe('Item Search', () => {
+  let itemsPage: ItemsPage
+
+  test.beforeEach(async ({ page }) => {
+    itemsPage = new ItemsPage(page)
+    await itemsPage.goto()
+  })
+
+  test('should search by keyword', async ({ page }) => {
+    await itemsPage.search('test')
+
+    const count = await itemsPage.getItemCount()
+    expect(count).toBeGreaterThan(0)
+
+    await expect(itemsPage.itemCards.first()).toContainText(/test/i)
+    await page.screenshot({ path: 'artifacts/search-results.png' })
+  })
+
+  test('should handle no results', async ({ page }) => {
+    await itemsPage.search('xyznonexistent123')
+
+    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+    expect(await itemsPage.getItemCount()).toBe(0)
+  })
+})
+```
+
+## Playwright Configuration
+
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report' }],
+    ['junit', { outputFile: 'playwright-results.xml' }],
+    ['json', { outputFile: 'playwright-results.json' }]
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    actionTimeout: 10000,
+    navigationTimeout: 30000,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+})
+```
+
+## Flaky Test Patterns
+
+### Quarantine
+
+```typescript
+test('flaky: complex search', async ({ page }) => {
+  test.fixme(true, 'Flaky - Issue #123')
+  // test code...
+})
+
+test('conditional skip', async ({ page }) => {
+  test.skip(process.env.CI, 'Flaky in CI - Issue #123')
+  // test code...
+})
+```
+
+### Identify Flakiness
+
+```bash
+npx playwright test tests/search.spec.ts --repeat-each=10
+npx playwright test tests/search.spec.ts --retries=3
+```
+
+### Common Causes & Fixes
+
+**Race conditions:**
+```typescript
+// Bad: assumes element is ready
+await page.click('[data-testid="button"]')
+
+// Good: auto-wait locator
+await page.locator('[data-testid="button"]').click()
+```
+
+**Network timing:**
+```typescript
+// Bad: arbitrary timeout
+await page.waitForTimeout(5000)
+
+// Good: wait for specific condition
+await page.waitForResponse(resp => resp.url().includes('/api/data'))
+```
+
+**Animation timing:**
+```typescript
+// Bad: click during animation
+await page.click('[data-testid="menu-item"]')
+
+// Good: wait for stability
+await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
+await page.waitForLoadState('networkidle')
+await page.locator('[data-testid="menu-item"]').click()
+```
+
+## Artifact Management
+
+### Screenshots
+
+```typescript
+await page.screenshot({ path: 'artifacts/after-login.png' })
+await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })
+await page.locator('[data-testid="chart"]').screenshot({ path: 'artifacts/chart.png' })
+```
+
+### Traces
+
+```typescript
+await browser.startTracing(page, {
+  path: 'artifacts/trace.json',
+  screenshots: true,
+  snapshots: true,
+})
+// ... test actions ...
+await browser.stopTracing()
+```
+
+### Video
+
+```typescript
+// In playwright.config.ts
+use: {
+  video: 'retain-on-failure',
+  videosPath: 'artifacts/videos/'
+}
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+        env:
+          BASE_URL: ${{ vars.STAGING_URL }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+## Test Report Template
+
+```markdown
+# E2E Test Report
+
+**Date:** YYYY-MM-DD HH:MM
+**Duration:** Xm Ys
+**Status:** PASSING / FAILING
+
+## Summary
+- Total: X | Passed: Y (Z%) | Failed: A | Flaky: B | Skipped: C
+
+## Failed Tests
+
+### test-name
+**File:** `tests/e2e/feature.spec.ts:45`
+**Error:** Expected element to be visible
+**Screenshot:** artifacts/failed.png
+**Recommended Fix:** [description]
+
+## Artifacts
+- HTML Report: playwright-report/index.html
+- Screenshots: artifacts/*.png
+- Videos: artifacts/videos/*.webm
+- Traces: artifacts/*.zip
+```
+
+## Wallet / Web3 Testing
+
+```typescript
+test('wallet connection', async ({ page, context }) => {
+  // Mock wallet provider
+  await context.addInitScript(() => {
+    window.ethereum = {
+      isMetaMask: true,
+      request: async ({ method }) => {
+        if (method === 'eth_requestAccounts')
+          return ['0x1234567890123456789012345678901234567890']
+        if (method === 'eth_chainId') return '0x1'
+      }
+    }
+  })
+
+  await page.goto('/')
+  await page.locator('[data-testid="connect-wallet"]').click()
+  await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')
+})
+```
+
+## Financial / Critical Flow Testing
+
+```typescript
+test('trade execution', async ({ page }) => {
+  // Skip on production — real money
+  test.skip(process.env.NODE_ENV === 'production', 'Skip on production')
+
+  await page.goto('/markets/test-market')
+  await page.locator('[data-testid="position-yes"]').click()
+  await page.locator('[data-testid="trade-amount"]').fill('1.0')
+
+  // Verify preview
+  const preview = page.locator('[data-testid="trade-preview"]')
+  await expect(preview).toContainText('1.0')
+
+  // Confirm and wait for blockchain
+  await page.locator('[data-testid="confirm-trade"]').click()
+  await page.waitForResponse(
+    resp => resp.url().includes('/api/trade') && resp.status() === 200,
+    { timeout: 30000 }
+  )
+
+  await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()
+})
+```

package/assets/opencode/skills/e2e-testing/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "E2E Testing"
+  short_description: "Playwright end-to-end testing"
+  brand_color: "#06B6D4"
+  default_prompt: "Generate Playwright E2E tests with Page Object Model"
+policy:
+  allow_implicit_invocation: true

package/assets/opencode/skills/error-handling/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: error-handling
+description: Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages.
+origin: ECC
+---
+
+# Error Handling Patterns
+
+Consistent, robust error handling patterns for production applications.
+
+## When to Activate
+
+- Designing error types or exception hierarchies for a new module or service
+- Adding retry logic or circuit breakers for unreliable external dependencies
+- Reviewing API endpoints for missing error handling
+- Implementing user-facing error messages and feedback
+- Debugging cascading failures or silent error swallowing
+
+## Core Principles
+
+1. **Fail fast and loudly** — surface errors at the boundary where they occur; don't bury them
+2. **Typed errors over string messages** — errors are first-class values with structure
+3. **User messages ≠ developer messages** — show friendly text to users, log full context server-side
+4. **Never swallow errors silently** — every `catch` block must either handle, re-throw, or log
+5. **Errors are part of your API contract** — document every error code a client may receive
+
+## TypeScript / JavaScript
+
+### Typed Error Classes
+
+```typescript
+// Define an error hierarchy for your domain
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500,
+    public readonly details?: unknown,
+  ) {
+    super(message)
+    this.name = this.constructor.name
+    // Maintain correct prototype chain in transpiled ES5 JavaScript.
+    // Required for `instanceof` checks (e.g., `error instanceof NotFoundError`)
+    // to work correctly when extending the built-in Error class.
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404)
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details: { field: string; message: string }[]) {
+    super(message, 'VALIDATION_ERROR', 422, details)
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(reason = 'Authentication required') {
+    super(reason, 'UNAUTHORIZED', 401)
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor(public readonly retryAfterMs: number) {
+    super('Rate limit exceeded', 'RATE_LIMITED', 429)
+  }
+}
+```
+
+### Result Pattern (no-throw style)
+
+For operations where failure is expected and common (parsing, external calls):
+
+```typescript
+type Result<T, E = AppError> =
+  | { ok: true; value: T }
+  | { ok: false; error: E }
+
+function ok<T>(value: T): Result<T> {
+  return { ok: true, value }
+}
+
+function err<E>(error: E): Result<never, E> {
+  return { ok: false, error }
+}
+
+// Usage
+async function fetchUser(id: string): Promise<Result<User>> {
+  try {
+    const user = await db.users.findUnique({ where: { id } })
+    if (!user) return err(new NotFoundError('User', id))
+    return ok(user)
+  } catch (e) {
+    return err(new AppError('Database error', 'DB_ERROR'))
+  }
+}
+
+const result = await fetchUser('abc-123')
+if (!result.ok) {
+  // TypeScript knows result.error here
+  logger.error('Failed to fetch user', { error: result.error })
+  return
+}
+// TypeScript knows result.value here
+console.log(result.value.email)
+```
+
+### API Error Handler (Next.js / Express)
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+
+function handleApiError(error: unknown): NextResponse {
+  // Known application error
+  if (error instanceof AppError) {
+    return NextResponse.json(
+      {
+        error: {
+          code: error.code,
+          message: error.message,
+          ...(error.details ? { details: error.details } : {}),
+        },
+      },
+      { status: error.statusCode },
+    )
+  }
+
+  // Zod validation error
+  if (error instanceof z.ZodError) {
+    return NextResponse.json(
+      {
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: 'Request validation failed',
+          details: error.issues.map(i => ({
+            field: i.path.join('.'),
+            message: i.message,
+          })),
+        },
+      },
+      { status: 422 },
+    )
+  }
+
+  // Unexpected error — log details, return generic message
+  console.error('Unexpected error:', error)
+  return NextResponse.json(
+    { error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } },
+    { status: 500 },
+  )
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    // ... handler logic
+  } catch (error) {
+    return handleApiError(error)
+  }
+}
+```
+
+### React Error Boundary
+
+```typescript
+import { Component, ErrorInfo, ReactNode } from 'react'
+
+interface Props {
+  fallback: ReactNode
+  onError?: (error: Error, info: ErrorInfo) => void
+  children: ReactNode
+}
+
+interface State {
+  hasError: boolean
+  error: Error | null
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false, error: null }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error }
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info)
+    console.error('Unhandled React error:', error, info)
+  }
+
+  render() {
+    if (this.state.hasError) return this.props.fallback
+    return this.props.children
+  }
+}
+
+// Usage
+<ErrorBoundary fallback={<p>Something went wrong. Please refresh.</p>}>
+  <MyComponent />
+</ErrorBoundary>
+```
+
+## Python
+
+### Custom Exception Hierarchy
+
+```python
+class AppError(Exception):
+    """Base application error."""
+    def __init__(self, message: str, code: str, status_code: int = 500):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, id: str):
+        super().__init__(f"{resource} not found: {id}", "NOT_FOUND", 404)
+
+class ValidationError(AppError):
+    def __init__(self, message: str, details: list[dict] | None = None):
+        super().__init__(message, "VALIDATION_ERROR", 422)
+        self.details = details or []
+```
+
+### FastAPI Global Exception Handler
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": {"code": exc.code, "message": str(exc)}},
+    )
+
+@app.exception_handler(Exception)
+async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
+    # Log full details, return generic message
+    logger.exception("Unexpected error", exc_info=exc)
+    return JSONResponse(
+        status_code=500,
+        content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}},
+    )
+```
+
+## Go
+
+### Sentinel Errors and Error Wrapping
+
+```go
+package domain
+
+import "errors"
+
+// Sentinel errors for type-checking
+var (
+    ErrNotFound    = errors.New("not found")
+    ErrUnauthorized = errors.New("unauthorized")
+    ErrConflict     = errors.New("conflict")
+)
+
+// Wrap errors with context — never lose the original
+func (r *UserRepository) FindByID(ctx context.Context, id string) (*User, error) {
+    user, err := r.db.QueryRow(ctx, "SELECT * FROM users WHERE id = $1", id)
+    if errors.Is(err, sql.ErrNoRows) {
+        return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
+    }
+    if err != nil {
+        return nil, fmt.Errorf("querying user %s: %w", id, err)
+    }
+    return user, nil
+}
+
+// At the handler level, unwrap to determine response
+func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {
+    user, err := h.service.GetUser(r.Context(), chi.URLParam(r, "id"))
+    if err != nil {
+        switch {
+        case errors.Is(err, domain.ErrNotFound):
+            writeError(w, http.StatusNotFound, "not_found", err.Error())
+        case errors.Is(err, domain.ErrUnauthorized):
+            writeError(w, http.StatusForbidden, "forbidden", "Access denied")
+        default:
+            slog.Error("unexpected error", "err", err)
+            writeError(w, http.StatusInternalServerError, "internal_error", "An unexpected error occurred")
+        }
+        return
+    }
+    writeJSON(w, http.StatusOK, user)
+}
+```
+
+## Retry with Exponential Backoff
+
+```typescript
+interface RetryOptions {
+  maxAttempts?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  retryIf?: (error: unknown) => boolean
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 10_000,
+    retryIf = () => true,
+  } = options
+
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+      if (attempt === maxAttempts || !retryIf(error)) throw error
+
+      const jitter = Math.random() * baseDelayMs
+      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1) + jitter, maxDelayMs)
+      await new Promise(resolve => setTimeout(resolve, delay))
+    }
+  }
+
+  throw lastError
+}
+
+// Usage: retry transient network errors, not 4xx
+const data = await withRetry(() => fetch('/api/data').then(r => r.json()), {
+  maxAttempts: 3,
+  retryIf: (error) => !(error instanceof AppError && error.statusCode < 500),
+})
+```
+
+## User-Facing Error Messages
+
+Map error codes to human-readable messages. Keep technical details out of user-visible text.
+
+```typescript
+const USER_ERROR_MESSAGES: Record<string, string> = {
+  NOT_FOUND: 'The requested item could not be found.',
+  UNAUTHORIZED: 'Please sign in to continue.',
+  FORBIDDEN: "You don't have permission to do that.",
+  VALIDATION_ERROR: 'Please check your input and try again.',
+  RATE_LIMITED: 'Too many requests. Please wait a moment and try again.',
+  INTERNAL_ERROR: 'Something went wrong on our end. Please try again later.',
+}
+
+export function getUserMessage(code: string): string {
+  return USER_ERROR_MESSAGES[code] ?? USER_ERROR_MESSAGES.INTERNAL_ERROR
+}
+```
+
+## Error Handling Checklist
+
+Before merging any code that touches error handling:
+
+- [ ] Every `catch` block handles, re-throws, or logs — no silent swallowing
+- [ ] API errors follow the standard envelope `{ error: { code, message } }`
+- [ ] User-facing messages contain no stack traces or internal details
+- [ ] Full error context is logged server-side
+- [ ] Custom error classes extend a base `AppError` with a `code` field
+- [ ] Async functions surface errors to callers — no fire-and-forget without fallback
+- [ ] Retry logic only retries retriable errors (not 4xx client errors)
+- [ ] React components are wrapped in `ErrorBoundary` for rendering errors

package/assets/opencode/skills/frontend-design/.openskills.json

@@ -0,0 +1,7 @@
+{
+  "source": "affaan-m/everything-claude-code",
+  "sourceType": "git",
+  "repoUrl": "https://github.com/affaan-m/everything-claude-code",
+  "subpath": "skills/frontend-design",
+  "installedAt": "2026-04-16T03:02:23.968Z"
+}