@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/api-client-patterns/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: api-client-patterns
+description: Typed API client patterns for consuming REST APIs and tRPC. Use for typed fetch wrappers, zod response validation, API client factory, auth injection, TanStack Query (useQuery, useMutation, infinite queries, optimistic updates), tRPC end-to-end types, error handling with discriminated unions, OpenAPI client codegen, or pagination envelopes. Complements backend-development (server side) with client-side consumption patterns.
+---
+
+# API Client Patterns Skill
+
+Typed, maintainable API clients — from simple fetch wrappers to full TanStack Query integration and tRPC.
+
+## 1. Typed Fetch Wrapper with Zod Validation
+
+```ts
+// lib/api/fetcher.ts
+import { z } from 'zod'
+
+export type ApiError = { type: 'network'; message: string }
+                     | { type: 'validation'; issues: z.ZodIssue[] }
+                     | { type: 'http'; status: number; body: unknown }
+
+export type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError }
+
+async function fetchJson<T>(
+  url: string,
+  schema: z.ZodSchema<T>,
+  init?: RequestInit,
+): Promise<ApiResult<T>> {
+  let response: Response
+
+  try {
+    response = await fetch(url, { ...init, headers: { 'Content-Type': 'application/json', ...init?.headers } })
+  } catch (e) {
+    return { ok: false, error: { type: 'network', message: String(e) } }
+  }
+
+  if (!response.ok) {
+    return { ok: false, error: { type: 'http', status: response.status, body: await response.json().catch(() => null) } }
+  }
+
+  const raw = await response.json()
+  const parsed = schema.safeParse(raw)
+
+  if (!parsed.success) {
+    return { ok: false, error: { type: 'validation', issues: parsed.error.issues } }
+  }
+
+  return { ok: true, data: parsed.data }
+}
+```
+
+## 2. API Client Factory Pattern
+
+```ts
+// lib/api/client.ts
+import { z } from 'zod'
+
+function createApiClient(baseUrl: string, getAuth: () => string | null) {
+  async function request<T>(
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    path: string,
+    schema: z.ZodSchema<T>,
+    body?: unknown,
+  ) {
+    const token = getAuth()
+    return fetchJson(`${baseUrl}${path}`, schema, {
+      method,
+      headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    })
+  }
+
+  return {
+    get: <T>(path: string, schema: z.ZodSchema<T>) => request('GET', path, schema),
+    post: <T>(path: string, schema: z.ZodSchema<T>, body: unknown) => request('POST', path, schema, body),
+    put: <T>(path: string, schema: z.ZodSchema<T>, body: unknown) => request('PUT', path, schema, body),
+    patch: <T>(path: string, schema: z.ZodSchema<T>, body: unknown) => request('PATCH', path, schema, body),
+    delete: <T>(path: string, schema: z.ZodSchema<T>) => request('DELETE', path, schema),
+  }
+}
+
+// Usage
+import { getAccessToken } from '@/lib/auth'
+export const api = createApiClient(process.env.NEXT_PUBLIC_API_URL!, getAccessToken)
+```
+
+## 3. Response Contracts — Pagination and Error Envelopes
+
+```ts
+// lib/api/schemas.ts — reusable response shapes
+import { z } from 'zod'
+
+export const paginatedSchema = <T extends z.ZodTypeAny>(itemSchema: T) =>
+  z.object({
+    data: z.array(itemSchema),
+    total: z.number(),
+    page: z.number(),
+    per_page: z.number(),
+    has_next: z.boolean(),
+  })
+
+export const apiErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  details: z.record(z.string()).optional(),
+})
+
+// Domain schemas
+export const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user', 'viewer']),
+  createdAt: z.coerce.date(),
+})
+
+export type User = z.infer<typeof userSchema>
+export const paginatedUsersSchema = paginatedSchema(userSchema)
+```
+
+## 4. TanStack Query Integration
+
+### Setup (`QueryClientProvider`)
+```tsx
+// app/providers.tsx
+'use client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+import { useState } from 'react'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 60_000, retry: 1 },
+    },
+  }))
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```
+
+### `useQuery` — Fetching
+```tsx
+import { useQuery } from '@tanstack/react-query'
+import { api } from '@/lib/api/client'
+import { paginatedUsersSchema } from '@/lib/api/schemas'
+
+// Query key factory — centralized, type-safe
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
+  detail: (id: string) => [...userKeys.all, 'detail', id] as const,
+}
+
+export function useUsers(filters: UserFilters) {
+  return useQuery({
+    queryKey: userKeys.list(filters),
+    queryFn: async () => {
+      const params = new URLSearchParams(filters as Record<string, string>)
+      const result = await api.get(`/users?${params}`, paginatedUsersSchema)
+      if (!result.ok) throw new Error(result.error.message ?? 'Failed to fetch users')
+      return result.data
+    },
+  })
+}
+```
+
+### `useMutation` — Creating/Updating
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { toast } from 'sonner'
+
+export function useCreateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (body: CreateUserInput) => {
+      const result = await api.post('/users', userSchema, body)
+      if (!result.ok) throw new Error('Failed to create user')
+      return result.data
+    },
+    onSuccess: () => {
+      // Invalidate all user list queries
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() })
+      toast.success('User created successfully')
+    },
+    onError: (error) => {
+      toast.error(error.message)
+    },
+  })
+}
+```
+
+### Optimistic Updates
+```tsx
+export function useUpdateUser(id: string) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (patch: Partial<User>) => api.patch(`/users/${id}`, userSchema, patch),
+
+    onMutate: async (patch) => {
+      await queryClient.cancelQueries({ queryKey: userKeys.detail(id) })
+      const previous = queryClient.getQueryData(userKeys.detail(id))
+      queryClient.setQueryData(userKeys.detail(id), (old: User) => ({ ...old, ...patch }))
+      return { previous }  // Return context for rollback
+    },
+
+    onError: (_err, _vars, context) => {
+      // Rollback to previous value
+      queryClient.setQueryData(userKeys.detail(id), context?.previous)
+    },
+
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.detail(id) })
+    },
+  })
+}
+```
+
+### Infinite Queries — Pagination
+```tsx
+import { useInfiniteQuery } from '@tanstack/react-query'
+
+export function useInfiniteUsers() {
+  return useInfiniteQuery({
+    queryKey: userKeys.lists(),
+    queryFn: ({ pageParam = 1 }) =>
+      api.get(`/users?page=${pageParam}&per_page=20`, paginatedUsersSchema)
+        .then(r => { if (!r.ok) throw new Error('Fetch failed'); return r.data }),
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) =>
+      lastPage.has_next ? lastPage.page + 1 : undefined,
+  })
+}
+
+// Usage
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteUsers()
+const users = data?.pages.flatMap(p => p.data) ?? []
+```
+
+## 5. tRPC — End-to-End Type Safety
+
+```ts
+// server/router.ts (Next.js App Router example)
+import { initTRPC } from '@trpc/server'
+import { z } from 'zod'
+
+const t = initTRPC.create()
+const router = t.router
+const publicProcedure = t.procedure
+
+export const appRouter = router({
+  users: router({
+    list: publicProcedure
+      .input(z.object({ page: z.number().default(1) }))
+      .query(({ input }) => getUsersPaginated(input.page)),
+
+    create: publicProcedure
+      .input(z.object({ name: z.string(), email: z.string().email() }))
+      .mutation(({ input }) => createUser(input)),
+  }),
+})
+
+export type AppRouter = typeof appRouter
+```
+
+```tsx
+// Client usage — fully typed, no schemas needed client-side
+const { data } = api.users.list.useQuery({ page: 1 })
+const createUser = api.users.create.useMutation({
+  onSuccess: () => utils.users.list.invalidate(),
+})
+```
+
+## 6. Error Handling — Discriminated Unions
+
+```tsx
+// Typed error display in components
+function UserListView() {
+  const { data, error, status } = useUsers({})
+
+  if (status === 'pending') return <Skeleton />
+  
+  if (status === 'error') {
+    // error is typed as Error from React Query
+    return <ErrorAlert message={error.message} />
+  }
+
+  return <UserTable data={data.data} />
+}
+```
+
+```ts
+// Custom error classes for better discrimination
+export class ApiValidationError extends Error {
+  constructor(public issues: z.ZodIssue[]) {
+    super('Validation failed')
+    this.name = 'ApiValidationError'
+  }
+}
+
+export class ApiHttpError extends Error {
+  constructor(public status: number, public body: unknown) {
+    super(`HTTP ${status}`)
+    this.name = 'ApiHttpError'
+  }
+}
+```
+
+## 7. OpenAPI Client Codegen
+
+```bash
+# Install openapi-typescript-codegen
+pnpm add -D openapi-typescript-codegen
+
+# Generate client from OpenAPI spec
+npx openapi-typescript-codegen \
+  --input https://api.example.com/openapi.json \
+  --output src/lib/api/generated \
+  --client axios  # or fetch
+```
+
+Or use `@hey-api/openapi-ts` for modern output:
+```bash
+pnpm add -D @hey-api/openapi-ts
+npx @hey-api/openapi-ts -i openapi.json -o src/lib/api/generated -c fetch
+```
+
+**When to use codegen**: When an OpenAPI spec exists and is maintained. When building typed wrappers over a third-party API. Wrap generated clients in your factory pattern — don't expose them directly.
+
+## 8. Retry Logic
+
+```ts
+async function fetchWithRetry<T>(
+  fn: () => Promise<ApiResult<T>>,
+  maxRetries = 3,
+  backoffMs = 300,
+): Promise<ApiResult<T>> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const result = await fn()
+    if (result.ok) return result
+    if (result.error.type === 'http' && result.error.status < 500) return result  // Don't retry 4xx
+    if (attempt < maxRetries - 1) await new Promise(r => setTimeout(r, backoffMs * 2 ** attempt))
+  }
+  return fn()
+}
+```
+
+TanStack Query handles retries with `retry` option — use that for query/mutation retries instead of manual loops.
+
+## 9. Checklist
+
+- [ ] All API responses validated with Zod schemas
+- [ ] Typed `ApiResult<T>` discriminated union for every fetch
+- [ ] API client factory with auth injection, not per-call token access
+- [ ] Query keys use factory pattern (`userKeys.list(filters)`)
+- [ ] `useMutation` invalidates related queries `onSuccess`
+- [ ] Optimistic updates roll back on error via `onError` context
+- [ ] Infinite queries use `getNextPageParam` from server response
+- [ ] tRPC used when full-stack TypeScript with no codegen needed
+- [ ] Retry limited to 5xx errors, not 4xx
+- [ ] Error states displayed to user — not silently swallowed

package/bundles/antigravity-plugin-extras/skills/architecture-design/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: architecture-design
+context: fork
+description: Design application architecture and system diagrams with layered patterns, Mermaid C4 diagrams, SQL Server data platform, and on-premise deployment considerations.
+---
+
+# Architecture Design
+
+> **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:
+- Designing a new application or feature
+- Creating architecture documentation for stakeholders
+- Planning system integrations (Streamlit + FastAPI + SQL Server)
+- Evaluating architectural trade-offs
+- Creating C4 diagrams for project systems
+- Reviewing NFRs (scalability, performance, security)
+- Planning on-premise or air-gapped deployments
+
+---
+
+## Steps
+
+### Step 1: Clarify Scope
+
+Before designing, answer:
+1. What system or feature is being designed?
+2. Who are the users? (internal dashboards, external APIs, batch jobs)
+3. What are the data sources? (SQL Server tables, APIs, files)
+4. What are the deployment constraints? (on-premise, air-gapped, VPN)
+5. What NFRs matter most? (latency, throughput, availability)
+
+### Step 2: Define Layered Architecture
+
+Applications follow a consistent layered pattern:
+
+```
+Pages → Components → Services → Repository → Adapter → Database
+```
+
+```mermaid
+graph TB
+    subgraph "Presentation Layer"
+        UI[Streamlit Pages]
+        Components[UI Components]
+    end
+
+    subgraph "Business Logic"
+        Services[Service Layer]
+        Models[Pydantic Models]
+    end
+
+    subgraph "Data Access"
+        Repo[Repository]
+        Adapter[Database Adapter]
+    end
+
+    subgraph "Infrastructure"
+        DB[(SQL Server)]
+        LLM[Ollama LLM]
+        Cache[Cache Layer]
+    end
+
+    UI --> Components
+    Components --> Services
+    Services --> Models
+    Services --> Repo
+    Repo --> Adapter
+    Adapter --> DB
+    Services --> LLM
+    Services --> Cache
+```
+
+#### Component Responsibilities
+
+| Component | Responsibility | Key Patterns |
+|-----------|---------------|--------------|
+| Pages | User interface, routing | `apply_page_config`, `render_header` |
+| Components | Reusable UI elements | Streamlit widgets, Plotly charts |
+| Services | Business logic, orchestration | Caching, validation, transformations |
+| Repository | Data access facade | Query abstraction, `queries.yaml` |
+| Adapter | Database communication | Parameterized queries, connection pooling |
+
+### Step 3: Design File Structure
+
+```
+src/
+├── pages/
+│   └── {page}.py              # Streamlit page
+├── components/
+│   ├── shared_header.py       # Fixed header navigation
+│   ├── kpi_cards.py           # KPI card components
+│   └── {component}.py         # Feature-specific components
+├── services/
+│   ├── cached_repository.py   # Multi-user cached data
+│   └── {service}.py           # Business logic
+├── models/
+│   └── {model}.py             # Pydantic models
+├── ingestion_config/
+│   ├── data_sources.py        # DB configuration
+│   └── queries.yaml           # Externalized SQL queries
+├── styles/
+│   └── theme.css              # Brand theming CSS
+└── utils/
+    ├── dev_mode.py            # Query transparency
+    └── paths.py               # Path management
+```
+
+### Step 4: Create C4 Diagrams
+
+#### System Context Diagram
+
+```mermaid
+C4Context
+    title System Context - Application
+
+    Person(user, "User", "Internal staff member")
+    System(app, "Application", "Streamlit dashboard + FastAPI backend")
+    System_Ext(sqlserver, "SQL Server", "Enterprise database")
+    System_Ext(ollama, "Ollama", "Local LLM inference")
+
+    Rel(user, app, "Uses", "HTTPS")
+    Rel(app, sqlserver, "Queries", "pyodbc/ODBC")
+    Rel(app, ollama, "Infers", "HTTP/REST")
+```
+
+#### Container Diagram
+
+```mermaid
+C4Container
+    title Container Diagram - Application
+
+    Container(streamlit, "Streamlit Frontend", "Python/Streamlit", "Dashboard UI with brand theming")
+    Container(fastapi, "FastAPI Backend", "Python/FastAPI", "REST API layer")
+    ContainerDb(sqlserver, "SQL Server", "MSSQL", "Application tables")
+    Container(ollama, "Ollama", "Go", "Local LLM models")
+    Container(cache, "Cache Layer", "st.cache / Redis", "Data and resource caching")
+
+    Rel(streamlit, fastapi, "API calls", "HTTP/JSON")
+    Rel(fastapi, sqlserver, "Queries", "pyodbc")
+    Rel(fastapi, ollama, "LLM requests", "HTTP")
+    Rel(streamlit, cache, "Cached reads")
+```
+
+### Step 5: Define NFRs
+
+| Aspect | Approach | Project Specifics |
+|--------|----------|-------------------|
+| **Scalability** | Pagination, lazy loading | Application tables |
+| **Performance** | Caching with TTL, query optimization | 15-min TTL for dashboards |
+| **Security** | Parameterized queries, input validation | Windows Auth, regulatory compliance |
+| **Maintainability** | Clear separation, type hints | Shared UI / data libraries |
+| **Availability** | Error handling, graceful degradation | Air-gapped: no external dependencies |
+| **Observability** | Loguru structured logging | On-premise log aggregation |
+
+### Step 6: Document Design Decisions
+
+| Decision | Options Considered | Choice | Rationale |
+|----------|-------------------|--------|-----------|
+| Frontend framework | React, Streamlit, Dash | Streamlit | Rapid development, Python-native, team expertise |
+| Database access | ORM, raw SQL, repository | Repository + raw SQL | Performance control, query externalization |
+| Caching | Redis, Memcached, st.cache | st.cache + optional Redis | Simple for Streamlit, Redis for FastAPI |
+| LLM provider | OpenAI, Azure, Ollama | Ollama | Air-gapped requirement, data sovereignty |
+| Deployment | Cloud, hybrid, on-premise | On-premise | Security requirements, existing infrastructure |
+
+### Step 7: Identify Risks
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| SQL Server performance degradation | High | Medium | Query optimization, caching, pagination |
+| Air-gapped dependency issues | Medium | Low | Vendor packages, local mirrors |
+| Single point of failure (no HA) | High | Low | Graceful degradation, health checks |
+| Data freshness vs cache staleness | Medium | Medium | Configurable TTL, cache invalidation |
+
+---
+
+## Patterns and Examples
+
+### Architecture Decision Record (ADR) Template
+
+```markdown
+# ADR-001: [Decision Title]
+
+## Status: Accepted
+
+## Context
+[What is the problem or situation requiring a decision?]
+
+## Decision
+[What was decided and why]
+
+## Consequences
+### Positive
+- [Benefit 1]
+
+### Negative
+- [Trade-off 1]
+
+### Neutral
+- [Observation]
+```
+
+### Integration Pattern: Streamlit + FastAPI
+
+```python
+# Streamlit page calling FastAPI backend
+import requests
+
+BACKEND_URL = "http://localhost:8000"
+
+def fetch_records(status: str = None, page: int = 1):
+    params = {"page": page}
+    if status:
+        params["status"] = status
+    response = requests.get(f"{BACKEND_URL}/records", params=params)
+    response.raise_for_status()
+    return response.json()
+```
+
+---
+
+## Checklist
+
+- [ ] System context diagram created (C4 Level 1)
+- [ ] Container diagram created (C4 Level 2)
+- [ ] Component responsibilities defined
+- [ ] File structure planned
+- [ ] NFRs documented with project-specific values
+- [ ] Design decisions recorded with rationale
+- [ ] Risks identified and mitigations planned
+- [ ] Deployment strategy defined (on-premise/air-gapped)
+- [ ] Integration patterns documented (Streamlit ↔ FastAPI ↔ SQL Server)
+- [ ] Handoff ready: can create implementation plan from this design
+
+## Related Resources
+
+| Resource | Path |
+|----------|------|
+| Architect agent | `agents/architect.agent.md` |
+| FastAPI dev skill | `skills/coding/fastapi-dev/SKILL.md` |
+| Streamlit dev skill | `skills/frontend/streamlit-dev/SKILL.md` |
+| SQL expert skill | `skills/coding/sql/SKILL.md` |