spine-framework 0.3.124 → 0.3.126

package/.framework/cli/commands/doctor.ts

@@ -1,44 +1,38 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/doctor
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine doctor` command — comprehensive system validation for agentic IDE setup.
- * Checks environment, database, migrations, integrity, and custom code.
- *
- * **Commands:**
- * | Subcommand        | Description                                           |
- * |-------------------|-------------------------------------------------------|
- * | `doctor`          | Run all checks and report status                      |
- * | `doctor --json`   | Output structured JSON for agent consumption          |
- * | `doctor --fix`    | Attempt automatic remediation where possible          |
- *
- * **Checks performed:**
- * 1. Environment variables (SUPABASE_URL, SERVICE_ROLE_KEY)
- * 2. Database connectivity and latency
- * 3. Migration status (local vs applied)
- * 4. Core integrity (manifest hash verification)
- * 5. Custom code TypeScript compilation
- * 6. Test suite status (last run results)
- *
- * **Exit codes:**
- * - 0: All checks passed (healthy)
- * - 1: One or more checks failed
- * - 2: Check passed but warnings present (degraded)
- *
- * **Usage:**
- * ```bash
- * spine doctor
- * spine doctor --json
- * spine doctor --fix
- * ```
- *
- * @seeAlso cli/context.ts (buildCliContext)
- * @seeAlso functions/system.ts (health endpoint)
- */
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="doctor_module_header_1784071456" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for doctor CLI commands"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide imports and utilities for health checks"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" 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="imports" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Command type, context, database, and file system modules" 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: cli. 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 type { Command } from 'commander'
 import { buildCliContext, handleError } from '../context.ts'
 import { adminDb } from '../../functions/_shared/index.ts'
@@ -48,9 +42,21 @@ import { fileURLToPath } from 'url'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
-
-// ─── TYPES ─────────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="doctor_module_header_1784071456"]
+// CIL[BEGIN chunk_id="doctor_checkresult_1784071456" type="interface" identity="CheckResult" parent="none"]
+// CIL[DOC-MACRO purpose="Define structure for health check results"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide standardized check result format"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines check result with status, message, and optional details" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
 interface CheckResult {
   name: string
   status: 'pass' | 'fail' | 'warn'
@@ -58,7 +64,21 @@ interface CheckResult {
   details?: Record<string, any>
   fixable?: boolean
 }
-
+// CIL[END chunk_id="doctor_checkresult_1784071456"]
+// CIL[BEGIN chunk_id="doctor_doctorreport_1784071456" type="interface" identity="DoctorReport" parent="none"]
+// CIL[DOC-MACRO purpose="Define structure for comprehensive doctor report"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide complete health check summary format"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines report with overall status and check summaries" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
 interface DoctorReport {
   overall: 'healthy' | 'degraded' | 'unhealthy'
   checks: CheckResult[]
@@ -69,9 +89,21 @@ interface DoctorReport {
     fixable: number
   }
 }
-
-// ─── CHECK IMPLEMENTATIONS ─────────────────────────────────────────────────
-
+// CIL[END chunk_id="doctor_doctorreport_1784071456"]
+// CIL[BEGIN chunk_id="doctor_checkenvironment_1784071456" type="function" identity="checkEnvironment" parent="none"]
+// CIL[DOC-MACRO purpose="Check required environment variables"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate Supabase environment configuration"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="none" side_effects="reads environment variables"]
+// CIL[DOC-MICRO logic_summary="Validates required env vars and checks for .xenv file" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .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"]
 async function checkEnvironment(): Promise<CheckResult> {
   const required = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY']
   const missing = required.filter(v => !process.env[v])
@@ -86,7 +118,7 @@ async function checkEnvironment(): Promise<CheckResult> {
     }
   }
 
-  // Check if .xenv exists
+  
   const xenvPath = resolve(__dirname, '../../.xenv')
   const hasXenv = existsSync(xenvPath)
 
@@ -97,7 +129,21 @@ async function checkEnvironment(): Promise<CheckResult> {
     details: { has_xenv: hasXenv, vars_present: required.length }
   }
 }
-
+// CIL[END chunk_id="doctor_checkenvironment_1784071456"]
+// CIL[BEGIN chunk_id="doctor_checkdatabase_1784071456" type="function" identity="checkDatabase" parent="none"]
+// CIL[DOC-MACRO purpose="Check database connectivity and performance"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate database connection and measure latency"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="database connection errors" side_effects="queries database"]
+// CIL[DOC-MICRO logic_summary="Tests database connection with simple query and measures latency" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.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"]
 async function checkDatabase(): Promise<CheckResult> {
   const start = Date.now()
   try {
@@ -129,7 +175,21 @@ async function checkDatabase(): Promise<CheckResult> {
     }
   }
 }
-
+// CIL[END chunk_id="doctor_checkdatabase_1784071456"]
+// CIL[BEGIN chunk_id="doctor_checkmigrations_1784071456" type="function" identity="checkMigrations" parent="none"]
+// CIL[DOC-MACRO purpose="Check migration status and pending migrations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Compare local migration files with applied migrations"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="database query errors" side_effects="queries database, reads filesystem"]
+// CIL[DOC-MICRO logic_summary="Compares local SQL files with database migration records" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 async function checkMigrations(): Promise<CheckResult> {
   const migrationsDir = resolve(__dirname, '../../migrations_dayzero')
 
@@ -191,7 +251,21 @@ async function checkMigrations(): Promise<CheckResult> {
     }
   }
 }
-
+// CIL[END chunk_id="doctor_checkmigrations_1784071456"]
+// CIL[BEGIN chunk_id="doctor_checkintegrity_1784071456" type="function" identity="checkIntegrity" parent="none"]
+// CIL[DOC-MACRO purpose="Check core integrity manifest"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate spine manifest and integrity hash"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="file system errors" side_effects="reads manifest file"]
+// CIL[DOC-MICRO logic_summary="Checks for manifest file and validates integrity hash presence" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 async function checkIntegrity(): Promise<CheckResult> {
   const manifestPath = resolve(__dirname, '../../.spine-manifest.json')
 
@@ -218,9 +292,7 @@ async function checkIntegrity(): Promise<CheckResult> {
       }
     }
 
-    // Note: We don't actually verify the hash here - that would require
-    // computing SHA256 of all core files, which is slow. We just check
-    // that a manifest exists and looks valid.
+    
     return {
       name: 'integrity',
       status: 'pass',
@@ -236,7 +308,21 @@ async function checkIntegrity(): Promise<CheckResult> {
     }
   }
 }
-
+// CIL[END chunk_id="doctor_checkintegrity_1784071456"]
+// CIL[BEGIN chunk_id="doctor_checktestruns_1784071456" type="function" identity="checkTestRuns" parent="none"]
+// CIL[DOC-MACRO purpose="Check recent test run status"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query latest test run and report status"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="database query errors" side_effects="queries test_runs table"]
+// CIL[DOC-MICRO logic_summary="Retrieves most recent test run and reports its status" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 async function checkTestRuns(): Promise<CheckResult> {
   try {
     const { data, error } = await adminDb
@@ -281,9 +367,21 @@ async function checkTestRuns(): Promise<CheckResult> {
     }
   }
 }
-
-// ─── FIX IMPLEMENTATIONS ───────────────────────────────────────────────────
-
+// CIL[END chunk_id="doctor_checktestruns_1784071456"]
+// CIL[BEGIN chunk_id="doctor_tryfix_1784071456" type="function" identity="tryFix" parent="none"]
+// CIL[DOC-MACRO purpose="Provide fix suggestions for failed checks"]
+// CIL[DOC-RESPONSIBILITY responsibility="Generate remediation instructions for common issues"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Maps check names to specific fix commands and instructions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 async function tryFix(check: CheckResult): Promise<string> {
   switch (check.name) {
     case 'environment':
@@ -302,9 +400,21 @@ async function tryFix(check: CheckResult): Promise<string> {
       return 'No automatic fix available'
   }
 }
-
-// ─── COMMAND REGISTRATION ──────────────────────────────────────────────────
-
+// CIL[END chunk_id="doctor_tryfix_1784071456"]
+// CIL[BEGIN chunk_id="doctor_registerdoctorcommands_1784071456" type="function" identity="registerDoctorCommands" parent="none"]
+// CIL[DOC-MACRO purpose="Register doctor command with CLI framework"]
+// CIL[DOC-RESPONSIBILITY responsibility="Orchestrate all health checks and generate report"]
+// CIL[DOC-CONTEXT module="doctor-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="doctor command registration" errors="CLI context errors" side_effects="outputs health report"]
+// CIL[DOC-MICRO logic_summary="Runs all checks in dependency order and formats results" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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 function registerDoctorCommands(program: Command) {
   program
     .command('doctor')
@@ -313,8 +423,7 @@ export function registerDoctorCommands(program: Command) {
     .option('--fix', 'Show fix instructions for failed checks')
     .action(async (opts) => {
       try {
-        // Don't require full context for doctor - we want to diagnose issues
-        // even when env vars are missing
+        
         let ctx
         try {
           ctx = await buildCliContext()
@@ -322,16 +431,16 @@ export function registerDoctorCommands(program: Command) {
           ctx = null
         }
 
-        // Run all checks
+        
         const checks: CheckResult[] = []
 
         checks.push(await checkEnvironment())
 
-        // Only proceed with DB checks if env is valid
+        
         if (checks[0].status === 'pass') {
           checks.push(await checkDatabase())
 
-          // Only proceed with data checks if DB is connected
+          
           if (checks[1].status === 'pass') {
             checks.push(await checkMigrations())
             checks.push(await checkTestRuns())
@@ -372,7 +481,7 @@ export function registerDoctorCommands(program: Command) {
 
         checks.push(await checkIntegrity())
 
-        // Calculate overall status
+        
         const failed = checks.filter(c => c.status === 'fail').length
         const warnings = checks.filter(c => c.status === 'warn').length
         const fixable = checks.filter(c => c.fixable).length
@@ -397,7 +506,7 @@ export function registerDoctorCommands(program: Command) {
           }
         }
 
-        // Output
+        
         if (opts.json) {
           console.log(JSON.stringify(report, null, 2))
         } else {
@@ -426,7 +535,7 @@ export function registerDoctorCommands(program: Command) {
           console.log()
         }
 
-        // Exit code
+        
         if (overall === 'unhealthy') {
           process.exit(1)
         } else if (overall === 'degraded') {
@@ -440,3 +549,4 @@ export function registerDoctorCommands(program: Command) {
       }
     })
 }
+// CIL[END chunk_id="doctor_registerdoctorcommands_1784071456"]