spine-framework 0.3.124 → 0.3.126

package/.framework/functions/system.ts

@@ -1,38 +1,44 @@
-/**
- * @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)
- */
 
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="system_module_header_1783931956" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for system discovery endpoints"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware, database, and file system utilities"]
+// CIL[DOC-CONTEXT module="system" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports handler, database, and file system modules for system operations" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { readFileSync, existsSync, readdirSync } from 'fs'
 import { resolve } from 'path'
-
-// ─── TYPES ────────────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="system_module_header_1783931956"]
+// CIL[BEGIN chunk_id="system_types_1783931956" type="interface" identity="types" parent="none"]
+// CIL[DOC-MACRO purpose="Define type interfaces for system endpoints"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definitions for system data structures"]
+// CIL[DOC-CONTEXT module="system" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definitions" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines FunctionInfo, SystemManifest, and HealthCheck interfaces" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 9. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/IntegrationsPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 9. Total affected: 9."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface FunctionInfo {
   name: string
   methods: string[]
@@ -64,11 +70,21 @@ interface HealthCheck {
     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
+// CIL[END chunk_id="system_types_1783931956"]
+// CIL[BEGIN chunk_id="system_helpers_1783931956" type="helpers" identity="helpers" parent="none"]
+// CIL[DOC-MACRO purpose="Provide helper functions for system operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle manifest loading and function discovery"]
+// CIL[DOC-CONTEXT module="system" layer="api-handler" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="helper functions" errors="none" side_effects="file system access"]
+// CIL[DOC-MICRO logic_summary="Loads manifest from disk, discovers available functions in filesystem" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const PROJECT_ROOT = resolve(process.cwd(), '.')
 
 function loadManifest(): { version: string; integrity: { core_hash: string | null; verified: boolean } } {
@@ -103,7 +119,6 @@ async function discoverFunctions(): Promise<FunctionInfo[]> {
 
   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')
@@ -123,13 +138,24 @@ async function discoverFunctions(): Promise<FunctionInfo[]> {
     }
   })
 }
-
-// ─── HANDLERS ────────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="system_helpers_1783931956"]
+// CIL[BEGIN chunk_id="system_getmanifest_1783931956" type="function" identity="getManifest" parent="none"]
+// CIL[DOC-MACRO purpose="Generate system manifest with version and migration status"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide complete system status information"]
+// CIL[DOC-CONTEXT module="system" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SystemManifest data" errors="none" side_effects="database and file system queries"]
+// CIL[DOC-MICRO logic_summary="Compares local migrations with applied migrations, discovers functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 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)) {
@@ -147,7 +173,6 @@ async function getManifest(): Promise<{ data: SystemManifest }> {
       .order('version', { ascending: true })
     appliedMigrations = (data || []).map((r: any) => r.version)
   } catch {
-    // Schema migrations table may not exist yet
   }
 
   const appliedSet = new Set(appliedMigrations)
@@ -169,7 +194,21 @@ async function getManifest(): Promise<{ data: SystemManifest }> {
     }
   }
 }
-
+// CIL[END chunk_id="system_getmanifest_1783931956"]
+// CIL[BEGIN chunk_id="system_gethealth_1783931956" type="function" identity="getHealth" parent="none"]
+// CIL[DOC-MACRO purpose="Perform system health checks across components"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check database, migrations, and integrity status"]
+// CIL[DOC-CONTEXT module="system" layer="api-handler" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="HealthCheck data" errors="none" side_effects="database queries"]
+// CIL[DOC-MICRO logic_summary="Tests database connectivity, compares migration status, checks integrity" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 1. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function getHealth(): Promise<{ data: HealthCheck }> {
   const checks: HealthCheck['checks'] = {
     database: { connected: false, latency_ms: 0 },
@@ -177,7 +216,6 @@ async function getHealth(): Promise<{ data: HealthCheck }> {
     integrity: { verified: false }
   }
 
-  // Database check
   const dbStart = Date.now()
   try {
     const { error } = await adminDb.from('accounts').select('id').limit(1)
@@ -187,7 +225,6 @@ async function getHealth(): Promise<{ data: HealthCheck }> {
     checks.database.connected = false
   }
 
-  // Migration check
   const migrationsDir = resolve(PROJECT_ROOT, 'v2-core/migrations_dayzero')
   let localMigrations: string[] = []
   if (existsSync(migrationsDir)) {
@@ -211,11 +248,9 @@ async function getHealth(): Promise<{ data: HealthCheck }> {
     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')
@@ -231,10 +266,8 @@ async function getHealth(): Promise<{ data: HealthCheck }> {
       }
     }
   } catch {
-    // test_runs table may not exist
   }
 
-  // Determine overall status
   let status: HealthCheck['status'] = 'healthy'
   if (!checks.database.connected) {
     status = 'unhealthy'
@@ -244,7 +277,21 @@ async function getHealth(): Promise<{ data: HealthCheck }> {
 
   return { data: { status, checks } }
 }
-
+// CIL[END chunk_id="system_gethealth_1783931956"]
+// CIL[BEGIN chunk_id="system_getopenapi_1783931956" type="function" identity="getOpenApi" parent="none"]
+// CIL[DOC-MACRO purpose="Generate OpenAPI 3.1 specification for all endpoints"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create machine-readable API documentation"]
+// CIL[DOC-CONTEXT module="system" layer="api-handler" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="OpenAPI spec object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Builds OpenAPI paths and operations from discovered function metadata" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 1. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function getOpenApi(): Promise<{ data: any }> {
   const functions = await discoverFunctions()
   const manifest = loadManifest()
@@ -297,9 +344,21 @@ async function getOpenApi(): Promise<{ data: any }> {
     }
   }
 }
-
-// ─── MAIN HANDLER ─────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="system_getopenapi_1783931956"]
+// CIL[BEGIN chunk_id="system_handler_1783931956" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Route system API requests to appropriate handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch system endpoint actions based on query parameters"]
+// CIL[DOC-CONTEXT module="system" layer="api-handler" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="system data responses" errors="400" side_effects="calls helper functions"]
+// CIL[DOC-MICRO logic_summary="Routes to manifest, health, or openapi based on action parameter" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const handler = createHandler(async (ctx) => {
   const q = (ctx as any).query || {}
   const action = q.action || 'manifest'
@@ -321,3 +380,4 @@ export const handler = createHandler(async (ctx) => {
       }
   }
 })
+// CIL[END chunk_id="system_handler_1783931956"]

package/.framework/functions/tests.ts

@@ -1,33 +1,37 @@
-/**
- * @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)
- */
 
+
+// CIL[BEGIN chunk_id="tests_module_header_1783931956" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for test API handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware and database access"]
+// CIL[DOC-CONTEXT module="tests" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler middleware and adminDb for database access" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { createHandler, requireSystemContextWithAudit } from './_shared/middleware'
 import { adminDb } from './_shared/db'
-
+// CIL[END chunk_id="tests_module_header_1783931956"]
+// CIL[BEGIN chunk_id="tests_handler_1783931956" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Handle test API requests with multiple actions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Process test list, get, and stats endpoints"]
+// CIL[DOC-CONTEXT module="tests" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test data or error responses" errors="400/404/500" side_effects="database queries"]
+// CIL[DOC-MICRO logic_summary="Routes requests by action parameter, queries test_runs and test_results tables" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const handler = createHandler(async (ctx) => {
   const authErr = requireSystemContextWithAudit(ctx)
   if (authErr) return authErr
@@ -97,7 +101,6 @@ export const handler = createHandler(async (ctx) => {
     return { data: stats, error: null }
   }
 
-  // action === 'list'
   const limit = Math.min(parseInt(q.limit || '20', 10), 100)
   const suite = q.suite || null
 
@@ -117,3 +120,4 @@ export const handler = createHandler(async (ctx) => {
 
   return { data: data ?? [], error: null }
 })
+// CIL[END chunk_id="tests_handler_1783931956"]