@caddis/cli 0.0.0 → 0.1.0

package/bundles/antigravity-plugin/skills/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/antigravity-plugin/skills/excalidraw-db/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: excalidraw-db
+description: Turn a SQL artifact into an Excalidraw diagram for a design review / ARB pack / slide — higher-level, drag-the-boxes format
+---
+
+# /excalidraw-db — diagram a SQL artifact as Excalidraw
+
+Explain a SQL artifact as an **Excalidraw** diagram — for a design review, an ARB pack, or a slide deck,
+anywhere someone needs to drag boxes around rather than read a text file. For a git-tracked reference
+diagram, prefer `/mermaid-db` instead.
+
+Input: **$ARGUMENTS**
+
+## Do this
+
+Load and follow the **`db-diagram`** skill; produce the Excalidraw output specifically. In short:
+
+1. **Get the SQL** — same resolution as `/mermaid-db` (file / DB object via MCP or read-only `sqlcmd` /
+   context / pasted). Multiple objects → ONE diagram of their relationships.
+2. **Generate the `.excalidraw` directly** — run the skill's extractor with
+   `scripts/sql_to_graph.py --file <path> --format excalidraw` and save the output as a `.excalidraw` file.
+   The generator lays out deterministically on a **white canvas**: a query becomes a **left-to-right data
+   flow** (sources → filters → result → projection) with container-bound text that stays inside every box;
+   schema DDL becomes an **ER diagram** where each entity has a distinct **header + bulleted columns** and
+   every FK arrow is **edge-anchored and orthogonally routed so it never crosses (or hides behind) a box** —
+   even on hub / chain / self-reference schemas. No separate drawing skill, no MCP server.
+3. **Optional no-app preview** — for a shareable page, `--format html` emits a self-contained HTML (inline
+   SVG, a light/dark toggle that seeds from the OS and never half-applies, no external requests);
+   `--format svg` emits a standalone SVG.
+4. **Narrate + caveat** — include the business context and the execution-plan caveat (verbatim, per the
+   skill).
+
+## Rules (from the skill — non-negotiable)
+
+- **Read-only.** Never run DDL/DML.
+- **Never guess schema.** Mark anything inferred-from-SQL-only.
+- **Don't maintain both formats for one artifact.** If a Mermaid diagram already exists for this object,
+  say so and ask: a one-off review copy, or a replacement?

package/bundles/antigravity-plugin/skills/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 | `skills/coding/sql/SKILL.md` |
+| Python instructions | `instructions/python.instructions.md` |
+| Security instructions | `instructions/security.instructions.md` |