@caddis/cli 0.3.0 → 0.4.0

package/bundles/codex/.codex/skills/coding/api-design/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: api-design
+description: REST and GraphQL API design patterns. Use when designing new API endpoints, defining resource schemas, planning versioning strategies, or reviewing API contracts. Covers naming conventions, pagination, filtering, error responses, and OpenAPI documentation.
+---
+
+# API Design Skill
+
+Design APIs that are consistent, discoverable, and hard to misuse. Conventions over configuration.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Designing new API endpoints or a full API surface
+- "What should this endpoint look like?"
+- Planning API versioning or migration
+- Reviewing API contracts for consistency
+- Building an API spec or OpenAPI document
+
+## 2. REST Resource Naming
+
+### URL Convention
+
+```
+# Resources are nouns, plural, lowercase, kebab-case
+GET    /api/v1/customers                  # List
+GET    /api/v1/customers/{id}             # Get one
+POST   /api/v1/customers                  # Create
+PUT    /api/v1/customers/{id}             # Full update
+PATCH  /api/v1/customers/{id}             # Partial update
+DELETE /api/v1/customers/{id}             # Delete
+
+# Nested resources for strong ownership
+GET    /api/v1/customers/{id}/orders      # Customer's orders
+POST   /api/v1/customers/{id}/orders      # Create order for customer
+
+# Actions (when CRUD doesn't fit) — verb suffix
+POST   /api/v1/orders/{id}/cancel         # Action on resource
+POST   /api/v1/reports/generate           # Trigger async operation
+```
+
+### Naming Rules
+
+| Rule | Good | Bad |
+|------|------|-----|
+| Plural nouns | `/customers` | `/customer`, `/getCustomers` |
+| Kebab-case | `/order-items` | `/orderItems`, `/order_items` |
+| No verbs in path | `/customers` (POST = create) | `/createCustomer` |
+| Consistent nesting depth | Max 2 levels: `/customers/{id}/orders` | `/customers/{id}/orders/{id}/items/{id}/details` |
+| No trailing slash | `/customers` | `/customers/` |
+
+## 3. Request & Response Envelope
+
+### Success Response
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "request_id": "req_abc123",
+    "timestamp": "2025-01-15T10:30:00Z"
+  }
+}
+```
+
+### List Response (with pagination)
+
+```json
+{
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "per_page": 25,
+    "total": 142,
+    "total_pages": 6
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Invalid email format" },
+      { "field": "age", "message": "Must be at least 18" }
+    ]
+  }
+}
+```
+
+## 4. HTTP Status Codes
+
+Use the right code. Clients depend on these for control flow.
+
+| Code | When to Use |
+|------|-------------|
+| `200 OK` | Successful GET, PUT, PATCH |
+| `201 Created` | Successful POST that creates a resource |
+| `204 No Content` | Successful DELETE |
+| `400 Bad Request` | Malformed request body or parameters |
+| `401 Unauthorized` | Missing or invalid authentication |
+| `403 Forbidden` | Authenticated but not authorized |
+| `404 Not Found` | Resource doesn't exist |
+| `409 Conflict` | Duplicate resource, version conflict |
+| `422 Unprocessable Entity` | Valid syntax but semantic validation failed |
+| `429 Too Many Requests` | Rate limit exceeded (include `Retry-After` header) |
+| `500 Internal Server Error` | Unhandled server error |
+
+## 5. Pagination
+
+### Offset-based (simple, good for most cases)
+
+```
+GET /api/v1/customers?page=2&per_page=25
+```
+
+### Cursor-based (better for real-time data, large datasets)
+
+```
+GET /api/v1/events?cursor=eyJpZCI6MTAwfQ&limit=25
+```
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| Offset | Simple, supports jumping to page N | Skips/duplicates on mutations, slow at high offsets |
+| Cursor | Consistent with mutations, performant | No "jump to page 5", harder to implement |
+
+**Rule:** Use offset for admin/dashboard UIs. Use cursor for feeds, events, and public APIs.
+
+## 6. Filtering, Sorting, and Search
+
+```
+# Filtering — field-level with operators
+GET /api/v1/orders?status=open&created_after=2025-01-01
+
+# Sorting — field with direction prefix
+GET /api/v1/orders?sort=-created_at        # descending
+GET /api/v1/orders?sort=status,created_at   # multi-field
+
+# Search — dedicated parameter
+GET /api/v1/customers?q=acme+corp
+
+# Field selection — sparse fieldsets
+GET /api/v1/customers?fields=id,name,email
+```
+
+## 7. Versioning
+
+### URL Path versioning (recommended)
+
+```
+/api/v1/customers
+/api/v2/customers
+```
+
+### Version lifecycle
+
+| Phase | Duration | Behaviour |
+|-------|----------|-----------|
+| **Current** | Indefinite | Actively maintained |
+| **Deprecated** | 6-12 months | Returns `Deprecation` header, still works |
+| **Sunset** | After deprecation | Returns `410 Gone` |
+
+```python
+# FastAPI deprecation header
+@app.get("/api/v1/old-endpoint", deprecated=True)
+async def old_endpoint(response: Response):
+    response.headers["Deprecation"] = "true"
+    response.headers["Sunset"] = "2026-06-01"
+    response.headers["Link"] = '</api/v2/new-endpoint>; rel="successor-version"'
+    return {"data": ...}
+```
+
+## 8. Authentication & Security
+
+- Use `Authorization: Bearer <token>` for API auth
+- Never put tokens in URL query parameters (they appear in logs)
+- Return `401` for missing/invalid auth, `403` for insufficient permissions
+- Include `X-Request-Id` header for tracing
+- Rate limit all public endpoints
+
+## 9. FastAPI Implementation Pattern
+
+```python
+from fastapi import APIRouter, Depends, Query, HTTPException, status
+from pydantic import BaseModel, Field
+
+router = APIRouter(prefix="/api/v1/customers", tags=["customers"])
+
+class CustomerCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=200)
+    email: str = Field(..., pattern=r"^[\w.-]+@[\w.-]+\.\w+$")
+
+class CustomerResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+
+class PaginatedResponse(BaseModel):
+    data: list[CustomerResponse]
+    pagination: dict
+
+@router.get("", response_model=PaginatedResponse)
+async def list_customers(
+    page: int = Query(1, ge=1),
+    per_page: int = Query(25, ge=1, le=100),
+):
+    ...
+
+@router.post("", response_model=CustomerResponse, status_code=status.HTTP_201_CREATED)
+async def create_customer(body: CustomerCreate):
+    ...
+
+@router.get("/{customer_id}", response_model=CustomerResponse)
+async def get_customer(customer_id: str):
+    customer = await repo.find(customer_id)
+    if not customer:
+        raise HTTPException(status_code=404, detail="Customer not found")
+    return customer
+```
+
+## 10. API Design Checklist
+
+Before shipping an API endpoint:
+
+- [ ] Resource names are plural nouns in kebab-case
+- [ ] Correct HTTP methods (GET reads, POST creates, etc.)
+- [ ] Correct status codes (201 for create, 204 for delete)
+- [ ] Request body validated with Pydantic/Zod
+- [ ] Error responses use consistent envelope with error code
+- [ ] Pagination implemented for list endpoints
+- [ ] Authentication required (unless intentionally public)
+- [ ] Rate limiting configured
+- [ ] OpenAPI spec generated and reviewed
+- [ ] No sensitive data in URLs or logs
+
+## 11. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Verbs in URLs | `/getUser`, `/deleteOrder` | Use HTTP methods + nouns |
+| Inconsistent pluralisation | `/user` vs `/orders` | Always plural |
+| Returning 200 for errors | Client can't distinguish success/failure | Use proper status codes |
+| Nested resources > 2 levels | Hard to discover, fragile URLs | Flatten with query params |
+| No pagination on lists | Unbounded response size, OOM | Always paginate |
+| Exposing internal IDs/schemas | Coupling clients to implementation | Use public-facing schemas |

package/bundles/codex/.codex/skills/coding/backend-development/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: backend-development
+description: Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture.
+source: wshobson/agents
+license: MIT
+---
+
+# Backend Development
+
+## API Design
+
+### RESTful Conventions
+```
+GET    /users          # List users
+POST   /users          # Create user
+GET    /users/:id      # Get user
+PUT    /users/:id      # Update user (full)
+PATCH  /users/:id      # Update user (partial)
+DELETE /users/:id      # Delete user
+
+GET    /users/:id/posts  # List user's posts
+POST   /users/:id/posts  # Create post for user
+```
+
+### Response Format
+```json
+{
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 100
+  }
+}
+```
+
+### Error Format
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      { "field": "email", "message": "Invalid format" }
+    ]
+  }
+}
+```
+
+## Database Patterns
+
+### Schema Design
+```sql
+-- Use UUIDs for public IDs
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  public_id UUID DEFAULT gen_random_uuid() UNIQUE,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Soft deletes
+ALTER TABLE users ADD COLUMN deleted_at TIMESTAMPTZ;
+
+-- Indexes
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_created ON users(created_at DESC);
+```
+
+### Query Patterns
+```sql
+-- Pagination with cursor
+SELECT * FROM posts
+WHERE created_at < $cursor
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- Efficient counting
+SELECT reltuples::bigint AS estimate
+FROM pg_class WHERE relname = 'users';
+```
+
+## Authentication
+
+### JWT Pattern
+```typescript
+interface TokenPayload {
+  sub: string;      // User ID
+  iat: number;      // Issued at
+  exp: number;      // Expiration
+  scope: string[];  // Permissions
+}
+
+function verifyToken(token: string): TokenPayload {
+  return jwt.verify(token, SECRET) as TokenPayload;
+}
+```
+
+### Middleware
+```typescript
+async function authenticate(req: Request, res: Response, next: Next) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (!token) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  try {
+    req.user = verifyToken(token);
+    next();
+  } catch {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+}
+```
+
+## Caching Strategy
+
+```typescript
+// Cache-aside pattern
+async function getUser(id: string): Promise<User> {
+  const cached = await redis.get(`user:${id}`);
+  if (cached) return JSON.parse(cached);
+
+  const user = await db.users.findById(id);
+  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
+  return user;
+}
+
+// Cache invalidation
+async function updateUser(id: string, data: Partial<User>) {
+  await db.users.update(id, data);
+  await redis.del(`user:${id}`);
+}
+```
+
+## Architecture Patterns
+
+### Repository Pattern
+Abstract data access from business logic for testability and swappable backends.
+
+```typescript
+interface UserRepository {
+  findAll(filters?: UserFilters): Promise<User[]>
+  findById(id: string): Promise<User | null>
+  create(data: CreateUserDto): Promise<User>
+  update(id: string, data: UpdateUserDto): Promise<User>
+  delete(id: string): Promise<void>
+}
+```
+
+### Service Layer Pattern
+Separate business logic from data access and HTTP concerns.
+
+```typescript
+class UserService {
+  constructor(private userRepo: UserRepository) {}
+
+  async createUser(data: CreateUserDto): Promise<User> {
+    // Business logic: validation, enrichment, side effects
+    const existing = await this.userRepo.findByEmail(data.email);
+    if (existing) throw new ConflictError('Email already registered');
+    return this.userRepo.create(data);
+  }
+}
+```
+
+### N+1 Query Prevention
+```typescript
+// Bad: N+1 queries
+const posts = await getPosts();
+for (const post of posts) {
+  post.author = await getUser(post.author_id);  // N queries
+}
+
+// Good: Batch fetch
+const posts = await getPosts();
+const authorIds = posts.map(p => p.author_id);
+const authors = await getUsers(authorIds);  // 1 query
+const authorMap = new Map(authors.map(a => [a.id, a]));
+posts.forEach(post => { post.author = authorMap.get(post.author_id); });
+```
+
+## Rate Limiting
+
+```typescript
+// Library-based approach
+const limiter = rateLimit({
+  windowMs: 60 * 1000,  // 1 minute
+  max: 100,             // 100 requests per window
+  keyGenerator: (req) => req.ip,
+  handler: (req, res) => {
+    res.status(429).json({ error: 'Too many requests' });
+  }
+});
+```
+
+## Error Handling
+
+### Retry with Exponential Backoff
+```typescript
+async function fetchWithRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3
+): Promise<T> {
+  let lastError: Error;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      if (i < maxRetries - 1) {
+        const delay = Math.pow(2, i) * 1000;
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError!;
+}
+```
+
+### Centralized Error Handler
+```typescript
+class ApiError extends Error {
+  constructor(public statusCode: number, message: string, public isOperational = true) {
+    super(message);
+  }
+}
+
+function errorHandler(error: unknown, req: Request): Response {
+  if (error instanceof ApiError) {
+    return json({ error: error.message }, { status: error.statusCode });
+  }
+  if (error instanceof z.ZodError) {
+    return json({ error: 'Validation failed', details: error.errors }, { status: 400 });
+  }
+  console.error('Unexpected error:', error);
+  return json({ error: 'Internal server error' }, { status: 500 });
+}
+```
+
+## Role-Based Access Control
+
+```typescript
+type Permission = 'read' | 'write' | 'delete' | 'admin';
+
+const rolePermissions: Record<string, Permission[]> = {
+  admin: ['read', 'write', 'delete', 'admin'],
+  moderator: ['read', 'write', 'delete'],
+  user: ['read', 'write']
+};
+
+function hasPermission(user: { role: string }, permission: Permission): boolean {
+  return (rolePermissions[user.role] || []).includes(permission);
+}
+```
+
+## Background Jobs and Queues
+
+```typescript
+class JobQueue<T> {
+  private queue: T[] = [];
+  private processing = false;
+
+  async add(job: T): Promise<void> {
+    this.queue.push(job);
+    if (!this.processing) this.process();
+  }
+
+  private async process(): Promise<void> {
+    this.processing = true;
+    while (this.queue.length > 0) {
+      const job = this.queue.shift()!;
+      try { await this.execute(job); }
+      catch (error) { console.error('Job failed:', error); }
+    }
+    this.processing = false;
+  }
+
+  private async execute(job: T): Promise<void> { /* implementation */ }
+}
+```
+
+## Observability
+
+### Structured Logging
+```typescript
+class Logger {
+  log(level: 'info' | 'warn' | 'error', message: string, context?: Record<string, unknown>) {
+    console.log(JSON.stringify({
+      timestamp: new Date().toISOString(), level, message, ...context
+    }));
+  }
+  info(msg: string, ctx?: Record<string, unknown>) { this.log('info', msg, ctx); }
+  warn(msg: string, ctx?: Record<string, unknown>) { this.log('warn', msg, ctx); }
+  error(msg: string, err: Error, ctx?: Record<string, unknown>) {
+    this.log('error', msg, { ...ctx, error: err.message, stack: err.stack });
+  }
+}
+```
+
+### Health and Monitoring
+- **Metrics**: Request latency, error rates, queue depths
+- **Tracing**: Distributed tracing with correlation IDs
+- **Health checks**: `/health` and `/ready` endpoints

package/bundles/codex/.codex/skills/coding/code-review/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: code-review
+context: fork
+description: Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits.
+source: anthropics/claude-code
+license: Apache-2.0
+---
+
+# Code Review
+
+> **On Claude Code, prefer the native `/code-review`.** It is a command, not a skill, so it always
+> fires — including headless — and it has grown capabilities this one does not have: effort levels
+> (`low`…`max`), an `ultra` mode that runs a multi-agent review in the cloud, `--comment` to post
+> findings as inline PR comments, and `--fix` to apply them to the working tree. Reach for it first.
+>
+> This surface remains because caddis ships to harnesses that have **no** native equivalent — agy,
+> Codex and Copilot. There it is the only review you get. Do not delete it to tidy up Claude Code.
+>
+> `/caddis:cross-review` is NOT replaced by either. It sends the diff to a **different vendor's**
+> model, which neither this nor the native reviewer can do.
+
+## Review Categories
+
+### 1. Security Review
+Check for:
+- SQL injection vulnerabilities
+- XSS (Cross-Site Scripting)
+- Command injection
+- Insecure deserialization
+- Hardcoded secrets/credentials
+- Improper authentication/authorization
+- Insecure direct object references
+
+### 2. Performance Review
+Check for:
+- N+1 queries
+- Missing database indexes
+- Unnecessary re-renders (React)
+- Memory leaks
+- Blocking operations in async code
+- Missing caching opportunities
+- Large bundle sizes
+
+### 3. Code Quality Review
+Check for:
+- Code duplication (DRY violations)
+- Functions doing too much (SRP violations)
+- Deep nesting / complex conditionals
+- Magic numbers/strings
+- Poor naming
+- Missing error handling
+- Incomplete type coverage
+
+### 4. Testing Review
+Check for:
+- Missing test coverage for new code
+- Tests that don't test behavior
+- Flaky test patterns
+- Missing edge cases
+- Mocked external dependencies
+
+## Review Output Format
+
+```markdown
+## Code Review Summary
+
+### 🔴 Critical (Must Fix)
+- **[File:Line]** [Issue description]
+  - **Why:** [Explanation]
+  - **Fix:** [Suggested fix]
+
+### 🟡 Suggestions (Should Consider)
+- **[File:Line]** [Issue description]
+  - **Why:** [Explanation]
+  - **Fix:** [Suggested fix]
+
+### 🟢 Nits (Optional)
+- **[File:Line]** [Minor suggestion]
+
+### ✅ What's Good
+- [Positive feedback on good patterns]
+```
+
+## Common Patterns to Flag
+
+### Security
+```javascript
+// BAD: SQL injection
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD: Parameterized query
+const query = 'SELECT * FROM users WHERE id = $1';
+await db.query(query, [userId]);
+```
+
+### Performance
+```javascript
+// BAD: N+1 query
+users.forEach(async user => {
+  const posts = await getPosts(user.id);
+});
+
+// GOOD: Batch query
+const userIds = users.map(u => u.id);
+const posts = await getPostsForUsers(userIds);
+```
+
+### Error Handling
+```javascript
+// BAD: Swallowing errors
+try {
+  await riskyOperation();
+} catch (e) {}
+
+// GOOD: Handle or propagate
+try {
+  await riskyOperation();
+} catch (e) {
+  logger.error('Operation failed', { error: e });
+  throw new AppError('Operation failed', { cause: e });
+}
+```
+
+## Review Checklist
+
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] Error handling complete
+- [ ] Types/interfaces defined
+- [ ] Tests added for new code
+- [ ] No obvious performance issues
+- [ ] Code is readable and documented
+- [ ] Breaking changes documented
+
+## Machine Verdict (automated / headless runs)
+
+**Then, as the very last line of your output (nothing after it), emit the machine verdict:**
+`REVIEW: CLEAN` (no blocking issues found across the categories above) or `REVIEW: BLOCKING` (one
+or more blocking issues). Automated runners read only this line; it must exactly match one of
+those two forms.