spine-framework 0.1.0

package/.framework/functions/system.ts

@@ -0,0 +1,323 @@
+/**
+ * @module system
+ * @audience both
+ * @layer api-handler
+ * @stability stable
+ *
+ * System discovery and health endpoints for agentic IDE integration.
+ * Provides machine-readable descriptions of the Spine instance,
+ * runtime health checks, and OpenAPI spec generation.
+ *
+ * **Routed by:** `GET /.netlify/functions/system`
+ *
+ * **Dispatch table:**
+ * | ?action | Description |
+ * |---------|-------------|
+ * | manifest | Returns system manifest (version, functions, integrity) |
+ * | health   | Returns health check status of all components |
+ * | openapi  | Returns OpenAPI 3.1 spec for all endpoints |
+ *
+ * **Authorization:**
+ * - `manifest`: No auth required (public endpoint)
+ * - `health`: No auth required (public endpoint)
+ * - `openapi`: No auth required (public endpoint)
+ *
+ * @seeAlso .spine-manifest.json (integrity hashes)
+ * @seeAlso cli/index.ts (CLI consumer of these endpoints)
+ */
+
+import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { resolve } from 'path'
+
+// ─── TYPES ────────────────────────────────────────────────────────────────────
+
+interface FunctionInfo {
+  name: string
+  methods: string[]
+  path: string
+  description?: string
+}
+
+interface SystemManifest {
+  version: string
+  schema: string
+  migrations: {
+    applied: number
+    latest: string | null
+    pending: number
+  }
+  functions: FunctionInfo[]
+  integrity: {
+    core_hash: string | null
+    verified: boolean
+  }
+}
+
+interface HealthCheck {
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  checks: {
+    database: { connected: boolean; latency_ms: number }
+    migrations: { current: boolean; pending: number; applied: number }
+    integrity: { verified: boolean }
+    test_runs?: { last_suite: string; last_status: string; last_at: string }
+  }
+}
+
+// ─── HELPERS ─────────────────────────────────────────────────────────────────
+
+// Netlify functions run from /functions directory after assembly
+// Project root is two levels up: /functions/../.. = project root
+const PROJECT_ROOT = resolve(process.cwd(), '.')
+
+function loadManifest(): { version: string; integrity: { core_hash: string | null; verified: boolean } } {
+  try {
+    const manifestPath = resolve(PROJECT_ROOT, '.spine-manifest.json')
+    if (!existsSync(manifestPath)) {
+      return { version: '2.0.0', integrity: { core_hash: null, verified: false } }
+    }
+    const content = readFileSync(manifestPath, 'utf8')
+    const manifest = JSON.parse(content)
+    return {
+      version: manifest.version || '2.0.0',
+      integrity: {
+        core_hash: manifest.integrity?.src || null,
+        verified: true
+      }
+    }
+  } catch {
+    return { version: '2.0.0', integrity: { core_hash: null, verified: false } }
+  }
+}
+
+async function discoverFunctions(): Promise<FunctionInfo[]> {
+  const functionsDir = resolve(PROJECT_ROOT, 'v2-core/functions')
+  if (!existsSync(functionsDir)) {
+    return []
+  }
+
+  const files = readdirSync(functionsDir)
+    .filter(f => f.endsWith('.ts') && !f.startsWith('_'))
+    .sort()
+
+  return files.map(f => {
+    const name = f.replace('.ts', '')
+    // Infer methods from common patterns
+    const methods = ['GET']
+    if (!['logs', 'tests', 'system-cron', 'debug-auth'].includes(name)) {
+      methods.push('POST')
+    }
+    if (!['logs', 'tests', 'system-cron'].includes(name)) {
+      methods.push('PATCH')
+    }
+    if (!['logs', 'tests', 'system-cron', 'debug-auth', 'auth'].includes(name)) {
+      methods.push('DELETE')
+    }
+
+    return {
+      name,
+      methods,
+      path: `/.netlify/functions/${name}`,
+      description: `Spine ${name} endpoint`
+    }
+  })
+}
+
+// ─── HANDLERS ────────────────────────────────────────────────────────────────
+
+async function getManifest(): Promise<{ data: SystemManifest }> {
+  const manifest = loadManifest()
+
+  // Get migration status
+  const migrationsDir = resolve(PROJECT_ROOT, 'v2-core/migrations_dayzero')
+  let localMigrations: string[] = []
+  if (existsSync(migrationsDir)) {
+    localMigrations = readdirSync(migrationsDir)
+      .filter(f => f.endsWith('.sql'))
+      .sort()
+  }
+
+  let appliedMigrations: string[] = []
+  try {
+    const { data } = await adminDb
+      .schema('public' as any)
+      .from('schema_migrations' as any)
+      .select('version')
+      .order('version', { ascending: true })
+    appliedMigrations = (data || []).map((r: any) => r.version)
+  } catch {
+    // Schema migrations table may not exist yet
+  }
+
+  const appliedSet = new Set(appliedMigrations)
+  const pendingCount = localMigrations.filter(m => !appliedSet.has(m.replace('.sql', ''))).length
+
+  const functions = await discoverFunctions()
+
+  return {
+    data: {
+      version: manifest.version,
+      schema: 'public',
+      migrations: {
+        applied: appliedMigrations.length,
+        latest: appliedMigrations[appliedMigrations.length - 1] || null,
+        pending: pendingCount
+      },
+      functions,
+      integrity: manifest.integrity
+    }
+  }
+}
+
+async function getHealth(): Promise<{ data: HealthCheck }> {
+  const checks: HealthCheck['checks'] = {
+    database: { connected: false, latency_ms: 0 },
+    migrations: { current: false, pending: 0, applied: 0 },
+    integrity: { verified: false }
+  }
+
+  // Database check
+  const dbStart = Date.now()
+  try {
+    const { error } = await adminDb.from('accounts').select('id').limit(1)
+    checks.database.connected = !error
+    checks.database.latency_ms = Date.now() - dbStart
+  } catch {
+    checks.database.connected = false
+  }
+
+  // Migration check
+  const migrationsDir = resolve(PROJECT_ROOT, 'v2-core/migrations_dayzero')
+  let localMigrations: string[] = []
+  if (existsSync(migrationsDir)) {
+    localMigrations = readdirSync(migrationsDir)
+      .filter(f => f.endsWith('.sql'))
+      .sort()
+  }
+
+  try {
+    const { data } = await adminDb
+      .schema('public' as any)
+      .from('schema_migrations' as any)
+      .select('version')
+    const applied = (data || []).map((r: any) => r.version)
+    checks.migrations.applied = applied.length
+    const appliedSet = new Set(applied)
+    checks.migrations.pending = localMigrations.filter(m => !appliedSet.has(m.replace('.sql', ''))).length
+    checks.migrations.current = checks.migrations.pending === 0
+  } catch {
+    checks.migrations.pending = localMigrations.length
+    checks.migrations.current = false
+  }
+
+  // Integrity check
+  const manifest = loadManifest()
+  checks.integrity.verified = manifest.integrity.verified
+
+  // Test run check (optional)
+  try {
+    const { data } = await adminDb
+      .from('test_runs')
+      .select('suite, status, started_at')
+      .order('started_at', { ascending: false })
+      .limit(1)
+      .single()
+    if (data) {
+      checks.test_runs = {
+        last_suite: data.suite,
+        last_status: data.status,
+        last_at: data.started_at
+      }
+    }
+  } catch {
+    // test_runs table may not exist
+  }
+
+  // Determine overall status
+  let status: HealthCheck['status'] = 'healthy'
+  if (!checks.database.connected) {
+    status = 'unhealthy'
+  } else if (checks.migrations.pending > 0 || !checks.integrity.verified) {
+    status = 'degraded'
+  }
+
+  return { data: { status, checks } }
+}
+
+async function getOpenApi(): Promise<{ data: any }> {
+  const functions = await discoverFunctions()
+  const manifest = loadManifest()
+
+  const paths: Record<string, any> = {}
+  for (const fn of functions) {
+    const pathKey = fn.path.replace('/.netlify/functions', '')
+    paths[pathKey] = {}
+
+    for (const method of fn.methods) {
+      const methodLower = method.toLowerCase()
+      paths[pathKey][methodLower] = {
+        operationId: `${fn.name}_${methodLower}`,
+        summary: fn.description || `${method} ${fn.name}`,
+        parameters: [
+          {
+            name: 'action',
+            in: 'query',
+            required: false,
+            schema: { type: 'string' },
+            description: 'Action to perform (list, get, create, update, delete)'
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Success',
+            content: {
+              'application/json': {
+                schema: { type: 'object' }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    data: {
+      openapi: '3.1.0',
+      info: {
+        title: 'Spine API',
+        version: manifest.version,
+        description: 'Spine v2 REST API for agentic IDE integration'
+      },
+      servers: [
+        { url: '/.netlify/functions' }
+      ],
+      paths
+    }
+  }
+}
+
+// ─── MAIN HANDLER ─────────────────────────────────────────────────────────────
+
+export const handler = createHandler(async (ctx) => {
+  const q = (ctx as any).query || {}
+  const action = q.action || 'manifest'
+
+  switch (action) {
+    case 'manifest':
+      return getManifest()
+
+    case 'health':
+      return getHealth()
+
+    case 'openapi':
+      return getOpenApi()
+
+    default:
+      return {
+        error: `Unknown action: ${action}. Valid actions: manifest, health, openapi`,
+        status: 400
+      }
+  }
+})

package/.framework/functions/tests.ts

@@ -0,0 +1,119 @@
+/**
+ * @module tests
+ * @audience both
+ * @layer api-handler
+ * @stability stable
+ *
+ * Read-only API for the admin Testing dashboard. Exposes test run history
+ * and per-case results stored in public.test_runs / public.test_results.
+ *
+ * **Routed by:** `GET /.netlify/functions/tests`
+ *
+ * **Dispatch table:**
+ * | ?action | ?id | Description |
+ * |---------|-----|-------------|
+ * | list    | —   | Returns 20 most recent test_runs (summary, no individual results) |
+ * | get     | uuid | Returns one test_run + all its test_results |
+ * | stats   | —   | Returns pass/fail counts grouped by suite for last 30 days |
+ *
+ * **Authorization:** system_admin only (machine principals with *:* also allowed).
+ *
+ * INVARIANT: no writes. This endpoint is purely for reading stored test run data.
+ *
+ * @seeAlso migrations_dayzero/008_test_runs.sql
+ * @seeAlso tests/reporter.ts (writes the data this endpoint reads)
+ * @seeAlso src/pages/admin/TestingDashboard.tsx (primary consumer)
+ */
+
+import { createHandler, requireSystemContextWithAudit } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+
+export const handler = createHandler(async (ctx) => {
+  const authErr = requireSystemContextWithAudit(ctx)
+  if (authErr) return authErr
+
+  const q = (ctx as any).query || {}
+  const action = q.action || 'list'
+  const id = q.id || q.run_id || null
+
+  if (action === 'get' || id) {
+    const runId = id
+    if (!runId) {
+      return { error: 'id is required for action=get', status: 400 }
+    }
+
+    const { data: run, error: runErr } = await adminDb
+      .from('test_runs')
+      .select('*')
+      .eq('id', runId)
+      .single()
+
+    if (runErr || !run) {
+      return { error: `Test run not found: ${runId}`, status: 404 }
+    }
+
+    const { data: results, error: resultsErr } = await adminDb
+      .from('test_results')
+      .select('*')
+      .eq('run_id', runId)
+      .order('status', { ascending: true })
+      .order('file', { ascending: true })
+      .order('name', { ascending: true })
+
+    if (resultsErr) {
+      return { error: resultsErr.message, status: 500 }
+    }
+
+    return { data: { ...run, results: results ?? [] }, error: null }
+  }
+
+  if (action === 'stats') {
+    const since = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()
+
+    const { data, error } = await adminDb
+      .from('test_runs')
+      .select('suite, status, started_at, passed, failed, total, duration_ms')
+      .gte('started_at', since)
+      .order('started_at', { ascending: false })
+      .limit(200)
+
+    if (error) return { error: error.message, status: 500 }
+
+    const suites = ['unit', 'integration', 'api', 'ui']
+    const stats = suites.map(suite => {
+      const suiteRuns = (data ?? []).filter(r => r.suite === suite)
+      const lastRun = suiteRuns[0] ?? null
+      return {
+        suite,
+        total_runs: suiteRuns.length,
+        last_status: lastRun?.status ?? null,
+        last_run_at: lastRun?.started_at ?? null,
+        last_passed: lastRun?.passed ?? null,
+        last_failed: lastRun?.failed ?? null,
+        last_total:  lastRun?.total ?? null,
+      }
+    })
+
+    return { data: stats, error: null }
+  }
+
+  // action === 'list'
+  const limit = Math.min(parseInt(q.limit || '20', 10), 100)
+  const suite = q.suite || null
+
+  let query = adminDb
+    .from('test_runs')
+    .select('id, suite, status, started_at, finished_at, duration_ms, total, passed, failed, skipped, triggered_by')
+    .order('started_at', { ascending: false })
+    .limit(limit)
+
+  if (suite) {
+    query = query.eq('suite', suite)
+  }
+
+  const { data, error } = await query
+
+  if (error) return { error: error.message, status: 500 }
+
+  return { data: data ?? [], error: null }
+})