thevoidforge 21.0.10 → 21.0.12

package/dist/docs/patterns/ai-router.ts

@@ -0,0 +1,194 @@
+/**
+ * Pattern: AI Router
+ *
+ * Maps natural language input to typed intents and dispatches to handlers.
+ * Think of this as a programmable switch statement where AI does the matching.
+ *
+ * Key principles:
+ * - Intents are a closed set — define them upfront, not discovered at runtime
+ * - Ambiguity is an explicit state — route to clarification, not a random handler
+ * - Default fallback prevents unhandled inputs from failing silently
+ * - Emit metrics on every route decision for observability
+ * - Handler functions are pure business logic — no AI inside handlers
+ *
+ * Agents: Picard (routing architecture), Stark (handler dispatch), Batman (edge cases)
+ *
+ * Provider note: Uses Anthropic for intent classification. Swap classify() for any provider.
+ */
+
+import Anthropic from '@anthropic-ai/sdk'
+import { z } from 'zod'
+
+// --- Intent definitions — closed set, exhaustive ---
+
+export const INTENTS = [
+  'check_order_status',
+  'request_refund',
+  'update_account',
+  'product_question',
+  'speak_to_human',
+  'ambiguous',
+] as const
+
+export type Intent = (typeof INTENTS)[number]
+
+// --- Router types ---
+
+interface RouteResult {
+  intent: Intent
+  confidence: number
+  params: Record<string, string> // Extracted entities (orderId, productName, etc.)
+  handlerResponse: unknown
+}
+
+interface RouterMetrics {
+  intent: Intent
+  confidence: number
+  latencyMs: number
+  routed: boolean // false if fell through to default
+}
+
+type MetricsEmitter = (metrics: RouterMetrics) => void
+
+type IntentHandler = (
+  input: string,
+  params: Record<string, string>
+) => Promise<unknown>
+
+// --- Intent classification ---
+
+const IntentOutputSchema = z.object({
+  intent: z.enum(INTENTS),
+  confidence: z.number().min(0).max(1),
+  params: z.record(z.string()),
+})
+
+async function classifyIntent(
+  client: Anthropic,
+  input: string
+): Promise<z.infer<typeof IntentOutputSchema>> {
+  const response = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 256,
+    system: [
+      'You are an intent classifier. Classify the user message into exactly one intent.',
+      `Valid intents: ${INTENTS.join(', ')}`,
+      'If the intent is unclear, use "ambiguous".',
+      'Extract relevant parameters (orderId, productName, etc.) from the message.',
+      'Respond with JSON: { "intent": "<intent>", "confidence": <0-1>, "params": {} }',
+    ].join('\n'),
+    messages: [{ role: 'user', content: input }],
+  })
+
+  const content = response.content[0]
+  if (content.type !== 'text') throw new Error('Expected text response')
+  return IntentOutputSchema.parse(JSON.parse(content.text))
+}
+
+// OpenAI adaptation:
+//   Use openai.chat.completions.create() with response_format: { type: 'json_object' }.
+//   Same schema parsing. For very high throughput, consider fine-tuned gpt-4o-mini.
+
+// --- IntentRouter class ---
+
+const AMBIGUITY_THRESHOLD = 0.50 // Below this, treat as ambiguous regardless of model label
+
+export class IntentRouter {
+  private handlers = new Map<Intent, IntentHandler>()
+  private defaultHandler: IntentHandler
+  private emitMetrics: MetricsEmitter
+
+  constructor(
+    private client: Anthropic,
+    options: {
+      defaultHandler: IntentHandler
+      emitMetrics?: MetricsEmitter
+    }
+  ) {
+    this.defaultHandler = options.defaultHandler
+    this.emitMetrics = options.emitMetrics ?? (() => {}) // No-op if not provided
+  }
+
+  /** Register a handler for an intent. One handler per intent. */
+  on(intent: Intent, handler: IntentHandler): this {
+    this.handlers.set(intent, handler)
+    return this
+  }
+
+  /** Classify intent from natural language and dispatch to the registered handler. */
+  async routeRequest(input: string): Promise<RouteResult> {
+    const start = Date.now()
+    const classification = await classifyIntent(this.client, input)
+    const latencyMs = Date.now() - start
+
+    // Override to ambiguous if confidence is too low, regardless of model's label
+    const effectiveIntent: Intent =
+      classification.confidence < AMBIGUITY_THRESHOLD ? 'ambiguous' : classification.intent
+
+    const handler = this.handlers.get(effectiveIntent) ?? this.defaultHandler
+    const routed = this.handlers.has(effectiveIntent)
+
+    // Emit metrics for observability — track routing decisions, not content
+    this.emitMetrics({
+      intent: effectiveIntent,
+      confidence: classification.confidence,
+      latencyMs,
+      routed,
+    })
+
+    const handlerResponse = await handler(input, classification.params)
+
+    return {
+      intent: effectiveIntent,
+      confidence: classification.confidence,
+      params: classification.params,
+      handlerResponse,
+    }
+  }
+}
+
+// --- Usage example ---
+
+// const router = new IntentRouter(anthropicClient, {
+//   defaultHandler: async (input) => ({
+//     message: "I'm not sure how to help with that. Let me connect you with someone.",
+//   }),
+//   emitMetrics: (m) => statsd.increment('ai.router.intent', { intent: m.intent }),
+// })
+//
+// router
+//   .on('check_order_status', async (_input, params) => {
+//     return orderService.getStatus(params.orderId)
+//   })
+//   .on('request_refund', async (_input, params) => {
+//     return refundService.initiate(params.orderId)
+//   })
+//   .on('ambiguous', async (input) => {
+//     return { message: 'Could you clarify? I can help with orders, refunds, or account changes.' }
+//   })
+//
+// const result = await router.routeRequest("Where's my order #12345?")
+
+/**
+ * Framework adaptations:
+ *
+ * Express:
+ *   - Mount router as middleware: app.post('/api/chat', async (req, res) => {
+ *       const result = await router.routeRequest(req.body.message)
+ *       res.json(result)
+ *     })
+ *   - Metrics via StatsD/Prometheus middleware
+ *   - Rate limit the classification endpoint (express-rate-limit)
+ *
+ * FastAPI:
+ *   - IntentRouter as a dependency: router = Depends(get_intent_router)
+ *   - Pydantic models for RouteResult and RouterMetrics
+ *   - Metrics via prometheus-fastapi-instrumentator or custom middleware
+ *   - Async handlers: all handlers are async def by default in Python
+ *
+ * Django:
+ *   - IntentRouter instantiated in services.py, called from views
+ *   - Store routing decisions in a RoutingLog model for analytics
+ *   - Metrics via django-prometheus or statsd
+ *   - For real-time: combine with SSE pattern (sse-endpoint.ts) via Django Channels
+ */

package/dist/docs/patterns/ai-tool-schema.ts

@@ -0,0 +1,237 @@
+/**
+ * Pattern: AI Tool Schema
+ *
+ * Key principles:
+ * - Define tools once, convert to any provider format (Anthropic, OpenAI)
+ * - Zod schemas for parameter validation — model output is untrusted input
+ * - Tool execution has error boundaries — one bad tool call can't crash the agent
+ * - Registry pattern for managing available tools per context/user/role
+ * - Tool results are always strings — structured data is JSON-serialized
+ *
+ * Agents: Stark (backend), Picard (architecture), Kenobi (input validation)
+ *
+ * Provider note: defineTool() creates a provider-agnostic definition.
+ * toAnthropicFormat() and toOpenAIFormat() convert for each SDK.
+ */
+
+import { z, ZodType, ZodObject, ZodRawShape } from 'zod'
+import type Anthropic from '@anthropic-ai/sdk'
+
+// --- Core types ---
+
+/** Provider-agnostic tool definition. */
+export interface ToolDefinition<TInput extends ZodRawShape = ZodRawShape> {
+  name: string
+  description: string
+  parameters: ZodObject<TInput>
+  execute: (input: z.infer<ZodObject<TInput>>) => Promise<string>
+}
+
+/** Result of a tool execution. */
+export interface ToolResult {
+  toolName: string
+  success: boolean
+  output: string
+  durationMs: number
+  error?: string
+}
+
+// --- defineTool() — type-safe tool creation ---
+
+/** Create a tool definition with Zod-validated parameters. */
+export function defineTool<T extends ZodRawShape>(config: {
+  name: string
+  description: string
+  parameters: ZodObject<T>
+  execute: (input: z.infer<ZodObject<T>>) => Promise<string>
+}): ToolDefinition<T> {
+  return config
+}
+
+// Example tool definitions:
+//
+// const getWeatherTool = defineTool({
+//   name: 'get_weather',
+//   description: 'Get current weather for a city',
+//   parameters: z.object({
+//     city: z.string().describe('City name'),
+//     units: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature units'),
+//   }),
+//   execute: async (input) => {
+//     const weather = await weatherService.getCurrent(input.city, input.units)
+//     return JSON.stringify(weather) // Always return string
+//   },
+// })
+
+// --- Tool execution with error boundary ---
+
+/** Execute a tool safely. Validates input, catches errors, measures duration. */
+export async function executeTool<T extends ZodRawShape>(
+  tool: ToolDefinition<T>,
+  rawInput: unknown
+): Promise<ToolResult> {
+  const start = Date.now()
+
+  // 1. Validate input with Zod — model output is untrusted
+  const parseResult = tool.parameters.safeParse(rawInput)
+  if (!parseResult.success) {
+    return {
+      toolName: tool.name,
+      success: false,
+      output: '',
+      durationMs: Date.now() - start,
+      error: `Invalid parameters: ${parseResult.error.issues.map((i) => i.message).join(', ')}`,
+    }
+  }
+
+  // 2. Execute with error boundary
+  try {
+    const output = await tool.execute(parseResult.data)
+    return {
+      toolName: tool.name,
+      success: true,
+      output,
+      durationMs: Date.now() - start,
+    }
+  } catch (error) {
+    return {
+      toolName: tool.name,
+      success: false,
+      output: '',
+      durationMs: Date.now() - start,
+      error: error instanceof Error ? error.message : 'Tool execution failed',
+    }
+  }
+}
+
+// --- ToolRegistry — manage available tools ---
+
+export class ToolRegistry {
+  private tools = new Map<string, ToolDefinition>()
+
+  /** Register a tool. Throws if name already taken. */
+  register(tool: ToolDefinition): this {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool already registered: ${tool.name}`)
+    }
+    this.tools.set(tool.name, tool)
+    return this
+  }
+
+  /** Get a tool by name. Returns undefined if not found. */
+  get(name: string): ToolDefinition | undefined {
+    return this.tools.get(name)
+  }
+
+  /** Execute a tool by name with raw input from the model. */
+  async execute(name: string, rawInput: unknown): Promise<ToolResult> {
+    const tool = this.tools.get(name)
+    if (!tool) {
+      return {
+        toolName: name,
+        success: false,
+        output: '',
+        durationMs: 0,
+        error: `Unknown tool: ${name}`,
+      }
+    }
+    return executeTool(tool, rawInput)
+  }
+
+  /** Convert all registered tools to Anthropic format. */
+  toAnthropicFormat(): Anthropic.Tool[] {
+    return Array.from(this.tools.values()).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      input_schema: zodToJsonSchema(tool.parameters),
+    }))
+  }
+
+  /** Convert all registered tools to OpenAI format. */
+  toOpenAIFormat(): Array<{
+    type: 'function'
+    function: { name: string; description: string; parameters: Record<string, unknown> }
+  }> {
+    return Array.from(this.tools.values()).map((tool) => ({
+      type: 'function' as const,
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: zodToJsonSchema(tool.parameters),
+      },
+    }))
+  }
+
+  /** List all registered tool names. */
+  listNames(): string[] {
+    return Array.from(this.tools.keys())
+  }
+}
+
+// --- Zod to JSON Schema conversion (simplified) ---
+// In production, use zod-to-json-schema package. This is a minimal reference.
+
+function zodToJsonSchema(schema: ZodType): Record<string, unknown> {
+  // Use zod-to-json-schema in production:
+  //   import { zodToJsonSchema } from 'zod-to-json-schema'
+  //   return zodToJsonSchema(schema)
+  //
+  // Simplified version for the pattern reference:
+  if (schema instanceof ZodObject) {
+    const shape = schema.shape
+    const properties: Record<string, unknown> = {}
+    const required: string[] = []
+
+    for (const [key, value] of Object.entries(shape)) {
+      const zodField = value as ZodType
+      properties[key] = { type: 'string', description: zodField.description ?? '' }
+      if (!zodField.isOptional()) required.push(key)
+    }
+
+    return { type: 'object', properties, required }
+  }
+  return { type: 'object', properties: {} }
+}
+
+// --- Usage example ---
+
+// const registry = new ToolRegistry()
+//   .register(getWeatherTool)
+//   .register(lookupOrderTool)
+//   .register(createTicketTool)
+//
+// // Pass to Anthropic agent loop (see ai-orchestrator.ts):
+// const response = await client.messages.create({
+//   model: 'claude-sonnet-4-20250514',
+//   tools: registry.toAnthropicFormat(),
+//   messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],
+// })
+//
+// // When model returns tool_use, execute via registry:
+// for (const block of response.content) {
+//   if (block.type === 'tool_use') {
+//     const result = await registry.execute(block.name, block.input)
+//     // Feed result back to model as tool_result
+//   }
+// }
+
+/**
+ * Framework adaptations:
+ *
+ * Express:
+ *   - ToolRegistry as singleton, initialized at startup
+ *   - Register tools from service layer — tools call services, not DB directly
+ *   - Admin endpoint to list available tools: GET /api/admin/tools
+ *
+ * FastAPI:
+ *   - defineTool equivalent: dataclass with Pydantic model for parameters
+ *   - ToolRegistry as dependency: registry = Depends(get_tool_registry)
+ *   - Pydantic replaces Zod for parameter validation
+ *   - Same provider adapter pattern: to_anthropic_format(), to_openai_format()
+ *
+ * Django:
+ *   - Tools defined in tools.py, registered in apps.py ready() method
+ *   - Tool permissions tied to Django auth: tool.requires_perm('orders.view')
+ *   - ToolResult logged to ToolExecutionLog model for audit
+ *   - Admin interface to enable/disable tools per tenant (multi-tenant.ts)
+ */

package/dist/docs/patterns/api-route.ts

@@ -0,0 +1,241 @@
+/**
+ * Pattern: API Route Handler
+ *
+ * Key principles:
+ * - Validate input at the boundary (Zod schema)
+ * - Auth check before business logic
+ * - Business logic in service layer, not the route
+ * - Consistent response shape
+ * - Structured error handling — never leak internals
+ * - Ownership verification for user-scoped resources
+ *
+ * Agents: Rogers (API design), Barton (error handling), Kenobi (security)
+ *
+ * Framework adaptations:
+ *   Next.js: This file (NextRequest/NextResponse, App Router)
+ *   Express: router.post('/api/projects', validate(schema), auth, async (req, res, next) => { ... })
+ *   Django: DRF ViewSet with serializer validation, permission_classes, service call
+ *   Rails: Controller action with strong_params, before_action :authenticate, service call
+ *
+ * === Django Deep Dive (DRF) ===
+ *
+ *   from rest_framework import viewsets, serializers, permissions, status
+ *   from rest_framework.response import Response
+ *   from .services import ProjectService
+ *
+ *   class ProjectSerializer(serializers.Serializer):
+ *       name = serializers.CharField(max_length=200)
+ *       description = serializers.CharField(required=False, allow_blank=True)
+ *
+ *   class ProjectViewSet(viewsets.ViewSet):
+ *       permission_classes = [permissions.IsAuthenticated]
+ *
+ *       def create(self, request):
+ *           serializer = ProjectSerializer(data=request.data)
+ *           serializer.is_valid(raise_exception=True)  # DRF handles 400 automatically
+ *           project = ProjectService.create(
+ *               user=request.user,
+ *               **serializer.validated_data
+ *           )
+ *           return Response(ProjectSerializer(project).data, status=status.HTTP_201_CREATED)
+ *
+ *   # Key differences from TypeScript pattern:
+ *   # - Validation: DRF serializers replace Zod schemas
+ *   # - Auth: permission_classes replaces getSession() — declarative, not imperative
+ *   # - Ownership: service receives request.user, enforces ownership internally
+ *   # - Errors: DRF exception handler maps service exceptions to HTTP responses
+ *   # - SELECT control: Use serializer fields to control response shape, not Prisma select
+ *   #   For mutations, always SELECT only the fields you need (serializer.fields controls this)
+ *
+ * === FastAPI Deep Dive ===
+ *
+ *   from fastapi import APIRouter, Depends, HTTPException
+ *   from pydantic import BaseModel
+ *   from .services import ProjectService
+ *   from .auth import get_current_user, User
+ *
+ *   router = APIRouter(prefix="/api/projects")
+ *
+ *   class CreateProjectRequest(BaseModel):
+ *       name: str
+ *       description: str | None = None
+ *
+ *   @router.post("/", status_code=201)
+ *   async def create_project(
+ *       body: CreateProjectRequest,
+ *       user: User = Depends(get_current_user),
+ *   ):
+ *       project = await ProjectService.create(user=user, **body.model_dump())
+ *       return project
+ *
+ *   # Key differences from TypeScript pattern:
+ *   # - Validation: Pydantic models replace Zod schemas (validated before handler runs)
+ *   # - Auth: Depends(get_current_user) replaces getSession() — dependency injection
+ *   # - Ownership: service receives user, enforces ownership internally
+ *   # - Errors: HTTPException or custom exception handlers map to HTTP responses
+ *   # - Fire-and-forget: Use BackgroundTasks for sendBeacon-style endpoints
+ *
+ * See /docs/patterns/error-handling.ts for the canonical error strategy.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getSession } from '@/lib/auth'
+import { projectService } from '@/lib/services/projects'
+import { ApiError, handleApiError } from '@/lib/errors'
+
+// --- Input validation at the boundary ---
+const createProjectSchema = z.object({
+  name: z.string().min(1).max(100).trim(),
+  description: z.string().max(500).optional(),
+})
+
+// --- POST /api/projects ---
+export async function POST(req: NextRequest) {
+  try {
+    // 1. Authenticate
+    const session = await getSession(req)
+    if (!session) {
+      return NextResponse.json(
+        { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
+        { status: 401 }
+      )
+    }
+
+    // 2. Validate input
+    const body = await req.json()
+    const parsed = createProjectSchema.safeParse(body)
+    if (!parsed.success) {
+      return NextResponse.json(
+        {
+          error: {
+            code: 'VALIDATION_ERROR',
+            message: 'Invalid input',
+            details: parsed.error.flatten().fieldErrors,
+          },
+        },
+        { status: 400 }
+      )
+    }
+
+    // 3. Business logic in service layer
+    const project = await projectService.create({
+      ...parsed.data,
+      ownerId: session.userId,
+    })
+
+    // 4. Consistent success response
+    return NextResponse.json({ project }, { status: 201 })
+  } catch (error) {
+    return handleApiError(error)
+  }
+}
+
+// --- GET /api/projects ---
+export async function GET(req: NextRequest) {
+  try {
+    const session = await getSession(req)
+    if (!session) {
+      return NextResponse.json(
+        { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
+        { status: 401 }
+      )
+    }
+
+    const { searchParams } = new URL(req.url)
+    const page = Math.max(1, Number(searchParams.get('page')) || 1)
+    const limit = Math.min(50, Math.max(1, Number(searchParams.get('limit')) || 20))
+
+    // Service handles pagination, filtering, ownership scoping
+    const result = await projectService.list({
+      ownerId: session.userId,
+      page,
+      limit,
+    })
+
+    return NextResponse.json({
+      projects: result.items,
+      pagination: {
+        page: result.page,
+        limit: result.limit,
+        total: result.total,
+        hasMore: result.hasMore,
+      },
+    })
+  } catch (error) {
+    return handleApiError(error)
+  }
+}
+
+// --- Prisma Select on Mutations ---
+// RULE: Always use `select` on Prisma create/update responses. Never return
+// raw Prisma results from mutations — they include ALL columns by default,
+// silently leaking sensitive fields (phoneHash, email, tokens, internal IDs).
+//
+// BAD:  const user = await db.user.update({ where: { id }, data: { name } })
+//       return NextResponse.json({ user })  // leaks phoneHash, email, etc.
+//
+// GOOD: const user = await db.user.update({
+//         where: { id }, data: { name },
+//         select: { id: true, name: true, avatar: true }
+//       })
+//       return NextResponse.json({ user })  // only selected fields
+//
+// This applies to create(), update(), upsert(), and any mutation that returns data.
+// findMany/findUnique already use select in the service pattern — mutations must too.
+// (Field report #36: Prisma update() without select leaked phoneHash and whatsappId.)
+
+// --- Fire-and-Forget Endpoints (sendBeacon) ---
+// navigator.sendBeacon() cannot set custom headers — it sends a plain POST with
+// Content-Type: text/plain. This makes it incompatible with header-based CSRF
+// enforcement (X-CSRF-Token). For analytics/telemetry endpoints that use sendBeacon:
+//
+// 1. Exempt the endpoint from CSRF header checks
+// 2. Add compensating controls: per-IP rate limiting, session cookie validation,
+//    origin check via Referer/Origin header (browsers always send these on sendBeacon)
+// 3. Ensure the endpoint only WRITES (append-only) — never reads or mutates user data
+// 4. Log the exemption in the security audit
+//
+// Pattern:
+//   POST /api/analytics/event  — exempt from X-CSRF-Token
+//   Validation: session cookie + origin header + rate limit (100/min/IP)
+//   Data: append-only event log, no user data returned in response
+//
+// (Field report #36: analytics endpoint failed silently because sendBeacon
+// couldn't attach the CSRF header.)
+
+// ── Anti-pattern: Raw Prisma spread ──────────────────
+// NEVER spread raw ORM/Prisma objects into API responses:
+//   ❌ res.json({ ...record })           — leaks internal fields (userId, rawMessageId, FK columns)
+//   ❌ res.json({ ...record, extra: 1 }) — still leaks everything from the spread
+//   ✅ res.json({ id: record.id, name: record.name, context: record.context })
+//
+// Prisma `include` without `select` returns ALL columns.
+// Spreading passes them to the client, exposing internal schema.
+// Always whitelist fields explicitly.
+// (Field report #77: Dialog Travel leaked 12 internal fields via ...rec spread)
+
+// --- Consistent error handler (shared across all routes) ---
+// Located in /lib/errors.ts — shown here for reference
+/*
+export function handleApiError(error: unknown) {
+  if (error instanceof ApiError) {
+    return NextResponse.json(
+      { error: { code: error.code, message: error.message } },
+      { status: error.status }
+    )
+  }
+
+  // Log unexpected errors with context, never expose to client
+  console.error('[API Error]', {
+    message: error instanceof Error ? error.message : 'Unknown error',
+    stack: error instanceof Error ? error.stack : undefined,
+    timestamp: new Date().toISOString(),
+  })
+
+  return NextResponse.json(
+    { error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' } },
+    { status: 500 }
+  )
+}
+*/