@caddis/cli 0.2.6 → 0.4.0

package/bundles/codex/.codex/skills/coding/dashboard-perf-sweep/scripts/perf_sweep.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Cold/warm HTTP timing harness for the dashboard-perf-sweep skill.
+
+Given a base URL and a list of endpoints, measures a COLD request (first hit) and a WARM
+request (immediately after) per endpoint, safely: a timeout or connection error on one endpoint
+is recorded as a finding, never a crash of the whole sweep (DASHBOARD-PERFORMANCE-STANDARD.md
+Rule 6 gate-1 mechanics; the huge cold/warm gap without a cache in between is itself diagnostic
+of a query-shape problem, not a cache-TTL one).
+
+This harness does NOT start dev servers or know anything about a specific app -- that's the
+`run` skill's job. It only measures a URL that is already reachable. stdlib-only (urllib), no
+install, matching the other caddis tool scripts (oss_review.py etc.).
+
+CLI:
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json --output report.json
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json --gate1-seconds 1.0
+
+endpoints.json shape (a JSON list):
+  [
+    {"name": "Historical Trends chart", "method": "GET", "path": "/api/trends/daily"},
+    {"name": "IW grid", "method": "POST", "path": "/raworkbench/investigation/query",
+     "json": {"filters": {}}, "headers": {"Authorization": "Bearer ..."}}
+  ]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_GATE1_SECONDS = 1.0  # DASHBOARD-PERFORMANCE-STANDARD.md Rule 6
+
+
+@dataclass
+class RequestResult:
+    ok: bool
+    status: int | None = None
+    elapsed_ms: float | None = None
+    error: str | None = None
+
+
+@dataclass
+class EndpointResult:
+    name: str
+    method: str
+    path: str
+    cold: RequestResult
+    warm: RequestResult | None = None
+    gate1_breach: bool = False
+
+
+@dataclass
+class SweepReport:
+    base_url: str
+    gate1_seconds: float
+    endpoints: list[EndpointResult] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "base_url": self.base_url,
+            "gate1_seconds": self.gate1_seconds,
+            "endpoints": [
+                {
+                    "name": e.name,
+                    "method": e.method,
+                    "path": e.path,
+                    "cold": asdict(e.cold),
+                    "warm": asdict(e.warm) if e.warm else None,
+                    "gate1_breach": e.gate1_breach,
+                }
+                for e in self.endpoints
+            ],
+        }
+
+
+def _do_request(
+    url: str,
+    method: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> RequestResult:
+    """One timed HTTP request. Never raises -- a timeout/connection/HTTP error becomes a
+    RequestResult with ok=False and a human-readable error, which is itself a sweep finding."""
+    data = None
+    req_headers = dict(headers or {})
+    if json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        req_headers.setdefault("Content-Type", "application/json")
+
+    req = urllib.request.Request(url, data=data, headers=req_headers, method=method)
+    start = time.perf_counter()
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            resp.read()
+            elapsed_ms = (time.perf_counter() - start) * 1000.0
+            return RequestResult(ok=True, status=resp.status, elapsed_ms=elapsed_ms)
+    except urllib.error.HTTPError as exc:
+        # An HTTP error status still completed a round trip -- timing is a real finding.
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, status=exc.code, elapsed_ms=elapsed_ms, error=f"HTTP {exc.code}")
+    except urllib.error.URLError as exc:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, elapsed_ms=elapsed_ms, error=f"connection error: {exc.reason}")
+    except TimeoutError:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, elapsed_ms=elapsed_ms, error=f"timeout after {timeout}s")
+
+
+def sweep_endpoint(
+    base_url: str,
+    endpoint: dict[str, Any],
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    gate1_seconds: float = DEFAULT_GATE1_SECONDS,
+    warm: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> EndpointResult:
+    method = endpoint.get("method", "GET").upper()
+    path = endpoint["path"]
+    url = base_url.rstrip("/") + path
+    headers = dict(extra_headers or {})
+    headers.update(endpoint.get("headers", {}))
+    json_body = endpoint.get("json")
+
+    cold = _do_request(url, method, json_body=json_body, headers=headers, timeout=timeout)
+    warm_result = None
+    if warm:
+        warm_result = _do_request(url, method, json_body=json_body, headers=headers, timeout=timeout)
+
+    gate1_breach = bool(cold.ok and cold.elapsed_ms is not None and cold.elapsed_ms / 1000.0 > gate1_seconds)
+    return EndpointResult(
+        name=endpoint.get("name", path),
+        method=method,
+        path=path,
+        cold=cold,
+        warm=warm_result,
+        gate1_breach=gate1_breach,
+    )
+
+
+def sweep(
+    base_url: str,
+    endpoints: list[dict[str, Any]],
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    gate1_seconds: float = DEFAULT_GATE1_SECONDS,
+    warm: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> SweepReport:
+    report = SweepReport(base_url=base_url, gate1_seconds=gate1_seconds)
+    for endpoint in endpoints:
+        report.endpoints.append(
+            sweep_endpoint(
+                base_url,
+                endpoint,
+                timeout=timeout,
+                gate1_seconds=gate1_seconds,
+                warm=warm,
+                extra_headers=extra_headers,
+            )
+        )
+    return report
+
+
+def format_report(report: SweepReport) -> str:
+    lines = [f"Sweep: {report.base_url}  (gate 1 = {report.gate1_seconds}s cold, uncached)", ""]
+    for e in report.endpoints:
+        if not e.cold.ok:
+            lines.append(f"  [ERROR]  {e.method:5s} {e.path:45s}  {e.cold.error}")
+            continue
+        flag = "SLOW " if e.gate1_breach else "     "
+        cold_s = f"{e.cold.elapsed_ms:8.1f}ms"
+        warm_s = f"{e.warm.elapsed_ms:8.1f}ms" if e.warm and e.warm.ok else "n/a"
+        gap = ""
+        if e.warm and e.warm.ok and e.cold.elapsed_ms and e.warm.elapsed_ms:
+            ratio = e.cold.elapsed_ms / max(e.warm.elapsed_ms, 0.01)
+            if ratio > 3:
+                gap = f"  (cold/warm {ratio:.1f}x -- likely query-shape, not cache-TTL)"
+        lines.append(f"  {flag}{e.method:5s} {e.path:45s}  cold={cold_s}  warm={warm_s}{gap}")
+    breaches = [e for e in report.endpoints if e.gate1_breach]
+    errors = [e for e in report.endpoints if not e.cold.ok]
+    problems = breaches + errors
+    lines.append("")
+    lines.append(
+        f"{len(problems)}/{len(report.endpoints)} endpoint(s) have a problem "
+        f"({len(breaches)} slow, {len(errors)} errored/timed out -- a timeout is a WORSE "
+        f"signal than a gate-1 breach, not a lesser one)."
+    )
+    if problems:
+        lines.append("Not itself a rs-kit verdict -- apply the shape checklist (SKILL.md) next.")
+    return "\n".join(lines)
+
+
+def _parse_header(value: str) -> tuple[str, str]:
+    if ":" not in value:
+        raise argparse.ArgumentTypeError(f"--header must be 'Key: Value', got {value!r}")
+    key, _, val = value.partition(":")
+    return key.strip(), val.strip()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--base-url", required=True, help="e.g. http://localhost:8703")
+    parser.add_argument("--endpoints", required=True, help="path to a JSON file (see module docstring)")
+    parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT_SECONDS)
+    parser.add_argument("--gate1-seconds", type=float, default=DEFAULT_GATE1_SECONDS)
+    parser.add_argument("--no-warm", action="store_true", help="skip the warm (second) request")
+    parser.add_argument("--header", action="append", default=[], type=_parse_header,
+                         help="extra header applied to every request, repeatable: --header 'Cookie: session=...'")
+    parser.add_argument("--output", help="also write the JSON report to this path")
+    args = parser.parse_args(argv)
+
+    with open(args.endpoints, encoding="utf-8") as f:
+        endpoints = json.load(f)
+    if not isinstance(endpoints, list):
+        print(f"[FAIL] {args.endpoints} must contain a JSON list of endpoint objects", file=sys.stderr)
+        return 2
+
+    report = sweep(
+        args.base_url,
+        endpoints,
+        timeout=args.timeout,
+        gate1_seconds=args.gate1_seconds,
+        warm=not args.no_warm,
+        extra_headers=dict(args.header),
+    )
+
+    print(format_report(report))
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            json.dump(report.to_dict(), f, indent=2)
+        print(f"\nWrote {args.output}")
+
+    breaches = [e for e in report.endpoints if e.gate1_breach]
+    errors = [e for e in report.endpoints if not e.cold.ok]
+    return 1 if (breaches or errors) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/codex/.codex/skills/coding/error-handling/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: error-handling
+description: Error handling patterns for Python and TypeScript applications. Use when designing error hierarchies, implementing retry logic, building error boundaries, or establishing logging strategies. Covers custom exceptions, result types, circuit breakers, and user-facing error messages.
+---
+
+# Error Handling Skill
+
+Errors are not exceptional — they are part of the contract. This skill defines how to classify, propagate, and recover from errors consistently.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Designing error handling for a new service or feature
+- "How should we handle errors in this module?"
+- Building retry logic or circuit breakers
+- Reviewing code with bare `except:` or swallowed errors
+- Establishing error handling conventions for a project
+
+## 2. Error Classification
+
+Every error falls into one of three categories. Handle each differently.
+
+| Category | Retryable? | User Action? | Example |
+|----------|-----------|-------------|---------|
+| **Transient** | Yes | None (auto-retry) | Network timeout, DB connection dropped, rate limit |
+| **Operational** | No | Inform user | Invalid input, resource not found, insufficient permissions |
+| **Fatal** | No | Alert team | Corrupted state, config missing, unrecoverable assertion |
+
+## 3. Python Exception Hierarchy
+
+Build domain-specific exceptions. Never raise raw `Exception`.
+
+```python
+class AppError(Exception):
+    """Base error for the application."""
+    def __init__(self, message: str, code: str | None = None):
+        self.message = message
+        self.code = code or self.__class__.__name__
+        super().__init__(self.message)
+
+# Operational errors (expected, handled gracefully)
+class NotFoundError(AppError):
+    """Resource does not exist."""
+
+class ValidationError(AppError):
+    """Input validation failed."""
+
+class AuthorizationError(AppError):
+    """User not authorized for this action."""
+
+# Transient errors (retry-eligible)
+class TransientError(AppError):
+    """Temporary failure — safe to retry."""
+
+class ExternalServiceError(TransientError):
+    """External API call failed."""
+
+class DatabaseConnectionError(TransientError):
+    """Database connection lost."""
+```
+
+### Usage Patterns
+
+```python
+# ✅ GOOD: Specific exception with context
+def get_user(user_id: str) -> User:
+    user = repo.find_by_id(user_id)
+    if user is None:
+        raise NotFoundError(f"User {user_id} not found")
+    return user
+
+# ✅ GOOD: Catch specific, re-raise as domain error
+def fetch_external_data(url: str) -> dict:
+    try:
+        response = httpx.get(url, timeout=10)
+        response.raise_for_status()
+        return response.json()
+    except httpx.TimeoutException as e:
+        raise ExternalServiceError(f"Timeout calling {url}") from e
+    except httpx.HTTPStatusError as e:
+        raise ExternalServiceError(f"HTTP {e.response.status_code} from {url}") from e
+
+# ❌ BAD: Bare except swallows everything
+try:
+    result = process()
+except:
+    pass
+
+# ❌ BAD: Catching too broadly
+try:
+    result = process()
+except Exception:
+    logger.error("Something went wrong")
+    return None  # Hides the real error
+```
+
+## 4. TypeScript Error Patterns
+
+### Result Type (for expected failures)
+
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parseConfig(raw: string): Result<Config, ValidationError> {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isValidConfig(parsed)) {
+      return { ok: false, error: new ValidationError("Invalid config shape") };
+    }
+    return { ok: true, value: parsed as Config };
+  } catch {
+    return { ok: false, error: new ValidationError("Invalid JSON") };
+  }
+}
+
+// Usage — caller must handle both cases
+const result = parseConfig(rawInput);
+if (!result.ok) {
+  showError(result.error.message);
+  return;
+}
+useConfig(result.value);
+```
+
+### Error Boundaries (React)
+
+```tsx
+'use client';
+import { Component, type ReactNode } from 'react';
+
+interface Props { children: ReactNode; fallback: ReactNode; }
+interface State { hasError: boolean; }
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    console.error('Component error:', error, info.componentStack);
+    // Report to error tracking service
+  }
+
+  render() {
+    return this.state.hasError ? this.props.fallback : this.props.children;
+  }
+}
+```
+
+## 5. Retry with Exponential Backoff
+
+```python
+import asyncio
+import random
+from loguru import logger
+
+async def retry_with_backoff(
+    fn,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+    retryable_exceptions: tuple = (TransientError,),
+):
+    """Retry a function with exponential backoff and jitter."""
+    for attempt in range(max_retries + 1):
+        try:
+            return await fn()
+        except retryable_exceptions as e:
+            if attempt == max_retries:
+                logger.error(f"All {max_retries} retries exhausted: {e}")
+                raise
+            delay = min(base_delay * (2 ** attempt), max_delay)
+            jitter = random.uniform(0, delay * 0.1)
+            logger.warning(f"Attempt {attempt + 1} failed: {e}. Retrying in {delay:.1f}s")
+            await asyncio.sleep(delay + jitter)
+```
+
+## 6. FastAPI Error Handling
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from loguru import logger
+
+app = FastAPI()
+
+@app.exception_handler(NotFoundError)
+async def not_found_handler(request: Request, exc: NotFoundError):
+    return JSONResponse(status_code=404, content={"error": exc.code, "message": exc.message})
+
+@app.exception_handler(ValidationError)
+async def validation_handler(request: Request, exc: ValidationError):
+    return JSONResponse(status_code=422, content={"error": exc.code, "message": exc.message})
+
+@app.exception_handler(AuthorizationError)
+async def auth_handler(request: Request, exc: AuthorizationError):
+    return JSONResponse(status_code=403, content={"error": exc.code, "message": exc.message})
+
+@app.exception_handler(Exception)
+async def unhandled_handler(request: Request, exc: Exception):
+    logger.exception(f"Unhandled error on {request.method} {request.url}")
+    # Never expose internal details to the client
+    return JSONResponse(status_code=500, content={"error": "InternalError", "message": "An internal error occurred."})
+```
+
+## 7. Logging Errors Correctly
+
+```python
+from loguru import logger
+
+# ✅ GOOD: Log with context, not just the message
+logger.error(f"Failed to process order {order_id}: {e}", order_id=order_id, customer_id=customer_id)
+
+# ✅ GOOD: Use exception() to capture stack trace
+try:
+    process_order(order)
+except Exception as e:
+    logger.exception(f"Order processing failed for {order.id}")
+    raise
+
+# ❌ BAD: Logging sensitive data
+logger.error(f"Auth failed for {username} with password {password}")
+
+# ❌ BAD: Logging without context
+logger.error("Something failed")
+```
+
+## 8. Error Message Guidelines
+
+| Audience | Include | Exclude |
+|----------|---------|---------|
+| **End user** | What happened, what to do next | Stack traces, internal IDs, SQL errors |
+| **Developer (logs)** | Full context, request ID, stack trace | User passwords, tokens, PII |
+| **API consumer** | Error code, human message, field-level detail | Server internals, file paths |
+
+```python
+# User-facing message
+"Unable to load your dashboard. Please try again in a few minutes."
+
+# API response
+{"error": "ValidationError", "message": "Email format is invalid", "field": "email"}
+
+# Log entry
+"Validation failed on POST /api/users: email='not-an-email' — rejected by regex validator"
+```
+
+## 9. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Bare `except:` / `except Exception:` | Catches KeyboardInterrupt, SystemExit | Catch specific exceptions |
+| `return None` on error | Caller has no idea what went wrong | Raise typed exception |
+| Logging and re-raising | Double logging, noisy | Log at the boundary, not at every layer |
+| String error codes | Typos, no autocomplete | Enum or class-based error codes |
+| Swallowing errors in background tasks | Silent failures, data loss | Log + alert + dead-letter queue |
+| Generic "Something went wrong" | User can't self-serve | Specific message + action hint |