@caddis/cli 0.3.0 → 0.4.0

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 |

package/bundles/codex/.codex/skills/coding/fastapi-dev/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: fastapi-dev
+description: Build FastAPI backends with standard patterns, error handling, and testing
+---
+
+# FastAPI Development
+
+> **Project Context** — Read `project-config.md` in the repo root for brand tokens, shared-library paths, and deployment targets.
+
+## When to Use
+
+Invoke this skill when:
+- Creating a new FastAPI backend for a project
+- Adding API endpoints for Streamlit frontends
+- Implementing repository pattern with SQL Server
+- Setting up dependency injection chains
+- Configuring CORS for Streamlit ↔ FastAPI communication
+- Deploying FastAPI on IIS/on-premise infrastructure
+
+---
+
+## Project Structure
+
+```
+backend/
+├── app/
+│   ├── __init__.py
+│   ├── main.py              # FastAPI application entry
+│   ├── config.py            # Settings (pydantic-settings)
+│   ├── dependencies.py      # Shared DI providers
+│   ├── routers/
+│   │   ├── __init__.py
+│   │   ├── records.py        # Records endpoints
+│   │   └── analytics.py     # Analytics endpoints
+│   ├── models/
+│   │   ├── __init__.py
+│   │   ├── record.py         # Pydantic request/response models
+│   │   └── user.py
+│   ├── services/
+│   │   ├── __init__.py
+│   │   └── record_service.py
+│   └── repositories/
+│       ├── __init__.py
+│       └── record_repo.py
+├── tests/
+├── .env
+└── requirements.txt
+```
+
+---
+
+## Steps
+
+### Step 1: Configuration (pydantic-settings)
+
+```python
+# app/config.py
+from functools import lru_cache
+from pydantic_settings import BaseSettings
+from pydantic import Field
+
+class Settings(BaseSettings):
+    app_name: str = "API"
+    debug: bool = False
+    db_server: str = Field(..., description="SQL Server host")
+    db_name: str = Field(..., description="Database name")
+    db_password: str = Field(..., repr=False)
+    api_key: str = Field(..., repr=False)
+    allowed_origins: list[str] = ["http://localhost:8501"]
+    ollama_base_url: str = "http://localhost:11434"
+    ollama_model: str = "llama3.1"
+
+    class Config:
+        env_file = ".env"
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()
+```
+
+### Step 2: Pydantic Models (Base/Create/Update/Response pattern)
+
+```python
+# app/models/record.py
+from pydantic import BaseModel, ConfigDict, Field
+from uuid import UUID
+from datetime import datetime
+from typing import Literal
+
+class RecordBase(BaseModel):
+    customer_id: str = Field(..., min_length=1, max_length=50, example="CUST001")
+    record_type: Literal["billing", "service", "technical"]
+    description: str = Field(..., min_length=10, max_length=5000)
+    priority: int = Field(default=3, ge=1, le=5)
+
+class RecordCreate(RecordBase):
+    pass
+
+class RecordUpdate(BaseModel):
+    status: Literal["open", "in_progress", "resolved"] | None = None
+    resolution_notes: str | None = Field(None, max_length=2000)
+    priority: int | None = Field(None, ge=1, le=5)
+
+class RecordResponse(RecordBase):
+    model_config = ConfigDict(from_attributes=True)
+    id: UUID
+    status: str
+    created_at: datetime
+    updated_at: datetime | None = None
+
+class RecordList(BaseModel):
+    items: list[RecordResponse]
+    total: int
+    page: int
+    per_page: int
+    pages: int
+```
+
+### Step 3: Dependency Injection Chain
+
+```python
+# app/dependencies.py
+from typing import Annotated, Generator
+from fastapi import Depends, Header, HTTPException
+from libs.data import DatabaseAdapter
+
+def get_db_adapter() -> Generator[DatabaseAdapter, None, None]:
+    adapter = DatabaseAdapter()
+    try:
+        yield adapter
+    finally:
+        adapter.close()
+
+def get_record_repository(
+    db: Annotated[DatabaseAdapter, Depends(get_db_adapter)]
+) -> RecordRepository:
+    return RecordRepository(db)
+
+def get_record_service(
+    repo: Annotated[RecordRepository, Depends(get_record_repository)]
+) -> RecordService:
+    return RecordService(repo)
+
+async def verify_api_key(
+    x_api_key: Annotated[str, Header(..., description="API Key")]
+) -> str:
+    if x_api_key != get_settings().api_key:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+    return x_api_key
+```
+
+### Step 4: Router Pattern
+
+```python
+# app/routers/records.py
+from fastapi import APIRouter, Depends, Query
+from typing import Annotated
+
+router = APIRouter(prefix="/records", tags=["records"])
+
+@router.get("/", response_model=RecordList)
+async def list_records(
+    service: Annotated[RecordService, Depends(get_record_service)],
+    page: int = Query(1, ge=1),
+    per_page: int = Query(25, ge=1, le=100),
+    status: str | None = None,
+):
+    return await service.list_records(page=page, per_page=per_page, status=status)
+
+@router.post("/", response_model=RecordResponse, status_code=201)
+async def create_record(
+    record: RecordCreate,
+    service: Annotated[RecordService, Depends(get_record_service)],
+):
+    return await service.create_record(record)
+```
+
+### Step 5: Application Entry
+
+```python
+# app/main.py
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from loguru import logger
+
+app = FastAPI(title="API", version="1.0.0")
+
+# CORS for Streamlit frontends
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=get_settings().allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(records_router)
+
+@app.get("/health")
+async def health_check():
+    return {"status": "healthy", "service": "API"}
+
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    logger.exception(f"Unhandled error on {request.url.path}: {exc}")
+    return JSONResponse(status_code=500, content={"detail": "An internal error occurred"})
+```
+
+### Step 6: SQL Server Connection
+
+```python
+# Using pyodbc for MSSQL with Windows Auth
+import pyodbc
+
+conn_str = (
+    "DRIVER={ODBC Driver 18 for SQL Server};"
+    f"SERVER={settings.db_server};"
+    f"DATABASE={settings.db_name};"
+    "Trusted_Connection=yes;"
+    "Encrypt=yes;"
+    "TrustServerCertificate=yes;"
+)
+conn = pyodbc.connect(conn_str, timeout=10)
+```
+
+---
+
+## Patterns and Examples
+
+### Repository Pattern
+
+```python
+class RecordRepository:
+    def __init__(self, adapter: DatabaseAdapter):
+        self._adapter = adapter
+
+    def get_by_id(self, record_id: UUID) -> dict | None:
+        query = "SELECT * FROM AppRecords WHERE CaseID = ?"
+        return self._adapter.fetch_one(query, (str(record_id),))
+
+    def get_paginated(self, page: int, per_page: int, status: str | None) -> tuple[list, int]:
+        count_query = "SELECT COUNT(*) FROM AppRecords"
+        params = []
+        if status:
+            count_query += " WHERE Status = ?"
+            params.append(status)
+        total = self._adapter.fetch_scalar(count_query, params)
+
+        query = "SELECT * FROM AppRecords"
+        if status:
+            query += " WHERE Status = ?"
+        query += " ORDER BY [Created Date Time] DESC OFFSET ? ROWS FETCH NEXT ? ROWS ONLY"
+        params.extend([(page - 1) * per_page, per_page])
+        items = self._adapter.fetch_all(query, params)
+        return items, total
+```
+
+### Error Handling with loguru
+
+```python
+from loguru import logger
+
+@router.post("/")
+async def create_record(record: RecordCreate, service: ...):
+    try:
+        result = await service.create_record(record)
+        logger.info(f"Created record {result.id} for customer {record.customer_id}")
+        return result
+    except ValidationError as e:
+        logger.warning(f"Validation error: {e}")
+        raise HTTPException(status_code=422, detail=str(e))
+    except Exception as e:
+        logger.exception(f"Failed to create record: {e}")
+        raise HTTPException(status_code=500, detail="Internal error")
+```
+
+---
+
+## Checklist
+
+- [ ] Project structure follows standard pattern (routers/models/services/repositories)
+- [ ] Pydantic models use Base/Create/Update/Response hierarchy
+- [ ] Dependency injection chain: adapter -> repo -> service
+- [ ] CORS configured for Streamlit frontend origins
+- [ ] Health check endpoint at `/health`
+- [ ] Global exception handler with loguru logging
+- [ ] SQL queries use parameterized inputs (no f-strings)
+- [ ] Configuration via pydantic-settings and .env file
+- [ ] API key verification on protected endpoints
+- [ ] All endpoints have proper response_model types
+
+## Related Resources
+
+| Resource | Path |
+|----------|------|
+| FastAPI instructions | `instructions/fastapi.instructions.md` |
+| SQL expert skill | the `sql` skill |
+| Python instructions | `instructions/python.instructions.md` |
+| Security instructions | `instructions/security.instructions.md` |

package/bundles/codex/.codex/skills/coding/javascript-typescript/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: javascript-typescript
+description: JavaScript and TypeScript development with ES6+, Node.js, React, and modern web frameworks. Use for frontend, backend, or full-stack JavaScript/TypeScript projects.
+source: wshobson/agents
+license: MIT
+---
+
+# JavaScript/TypeScript Development
+
+## TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## Type Patterns
+
+### Utility Types
+```typescript
+// Pick specific properties
+type UserPreview = Pick<User, 'id' | 'name'>;
+
+// Omit properties
+type CreateUser = Omit<User, 'id' | 'createdAt'>;
+
+// Make all properties optional
+type PartialUser = Partial<User>;
+
+// Make all properties required
+type RequiredUser = Required<User>;
+
+// Extract union types
+type Status = 'pending' | 'active' | 'inactive';
+type ActiveStatus = Extract<Status, 'active' | 'pending'>;
+```
+
+### Discriminated Unions
+```typescript
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: Error };
+
+function handleResult<T>(result: Result<T>) {
+  if (result.success) {
+    console.log(result.data); // T
+  } else {
+    console.error(result.error); // Error
+  }
+}
+```
+
+### Generic Constraints
+```typescript
+interface HasId {
+  id: string | number;
+}
+
+function findById<T extends HasId>(items: T[], id: T['id']): T | undefined {
+  return items.find(item => item.id === id);
+}
+```
+
+## Modern JavaScript
+
+### Destructuring & Spread
+```javascript
+const { name, ...rest } = user;
+const merged = { ...defaults, ...options };
+const [first, ...others] = items;
+```
+
+### Optional Chaining & Nullish Coalescing
+```javascript
+const city = user?.address?.city ?? 'Unknown';
+const count = data?.items?.length ?? 0;
+```
+
+### Array Methods
+```javascript
+const adults = users.filter(u => u.age >= 18);
+const names = users.map(u => u.name);
+const total = items.reduce((sum, item) => sum + item.price, 0);
+const hasAdmin = users.some(u => u.role === 'admin');
+const allActive = users.every(u => u.active);
+```
+
+## React Patterns
+
+```typescript
+// Props with children
+interface CardProps {
+  title: string;
+  children: React.ReactNode;
+}
+
+// Event handlers
+interface ButtonProps {
+  onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
+}
+
+// Custom hooks
+function useLocalStorage<T>(key: string, initial: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initial;
+  });
+
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+
+  return [value, setValue] as const;
+}
+```
+
+## Node.js Patterns
+
+```typescript
+// ES Modules
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// Error handling
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+```