@caddis/cli 0.2.6 → 0.4.0

package/bundles/antigravity-plugin-extras/skills/webapp-development/SKILL.md

@@ -283,6 +283,6 @@ st.plotly_chart(create_trend_chart(filter_type), use_container_width=True)
 |----------|------|
 | Streamlit dev skill | `skills/frontend/streamlit-dev/SKILL.md` |
 | FastAPI dev skill | `skills/coding/fastapi-dev/SKILL.md` |
-| SQL expert skill | `skills/coding/sql/SKILL.md` |
+| SQL expert skill | the `sql` skill |
 | Caching patterns | `skills/coding/caching-patterns/SKILL.md` |
 | UX design skill | `skills/frontend/ux-design/SKILL.md` |

package/bundles/codex/.codex/config.toml.example

@@ -0,0 +1,36 @@
+# Codex CLI configuration example
+# Copy to ~/.codex/config.toml  (user-level, all projects)
+#       or <project>/.codex/config.toml  (project-level; project must be trusted)
+#
+# Add a server interactively: codex mcp add <name> -- <command> [args...]
+# Verify loaded servers:      codex mcp list
+
+# ── Model (adjust to your OpenAI tier) ───────────────────────────────────────
+# model = "codex-mini-latest"
+
+# ── Skills ────────────────────────────────────────────────────────────────────
+# Project skills:  <project>/.codex/skills/<category>/<name>/SKILL.md
+# User skills:     ~/.codex/skills/<name>/SKILL.md  (no category subdir)
+# (Paths probed from codex 0.137 — see docs/analysis/codex-cli-contract.md.
+#  .agents/ is codex's PLUGINS root, not a skills root.)
+#
+# Disable a skill without deleting it:
+# [[skills.config]]
+# path = ".codex/skills/devops/windows-deployment"
+# enabled = false
+
+# ── junai MCP (pipeline state + project context) ─────────────────────────────
+# OFF by default. The junai MCP server tracks pipeline stage and project state
+# across sessions. Enable when the server is available locally.
+#
+# Prerequisites:
+#   pip install junai-mcp   (or: uv tool install junai-mcp)
+#   codex mcp add junai -- python -m junai_mcp --project-root .
+#
+# Or add the block below manually and run `codex mcp list` to confirm:
+#
+# [[mcp_servers]]
+# name = "junai"
+# command = "python"
+# args = ["-m", "junai_mcp", "--project-root", "."]
+# env = {}

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