spine-framework 0.2.1 → 1.0.0

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

@@ -1,442 +0,0 @@
-/// <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)
- */
-
-import type { Command } from 'commander'
-import { buildCliContext, handleError } from '../context.ts'
-import { adminDb } from '../../functions/_shared/index.ts'
-import { readFileSync, existsSync, readdirSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-// ─── TYPES ─────────────────────────────────────────────────────────────────
-
-interface CheckResult {
-  name: string
-  status: 'pass' | 'fail' | 'warn'
-  message: string
-  details?: Record<string, any>
-  fixable?: boolean
-}
-
-interface DoctorReport {
-  overall: 'healthy' | 'degraded' | 'unhealthy'
-  checks: CheckResult[]
-  summary: {
-    passed: number
-    failed: number
-    warnings: number
-    fixable: number
-  }
-}
-
-// ─── CHECK IMPLEMENTATIONS ─────────────────────────────────────────────────
-
-async function checkEnvironment(): Promise<CheckResult> {
-  const required = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY']
-  const missing = required.filter(v => !process.env[v])
-
-  if (missing.length > 0) {
-    return {
-      name: 'environment',
-      status: 'fail',
-      message: `Missing required env vars: ${missing.join(', ')}`,
-      details: { missing },
-      fixable: true
-    }
-  }
-
-  // Check if .xenv exists
-  const xenvPath = resolve(__dirname, '../../.xenv')
-  const hasXenv = existsSync(xenvPath)
-
-  return {
-    name: 'environment',
-    status: 'pass',
-    message: 'All required environment variables present',
-    details: { has_xenv: hasXenv, vars_present: required.length }
-  }
-}
-
-async function checkDatabase(): Promise<CheckResult> {
-  const start = Date.now()
-  try {
-    const { error } = await adminDb.from('accounts').select('id').limit(1)
-    const latency = Date.now() - start
-
-    if (error) {
-      return {
-        name: 'database',
-        status: 'fail',
-        message: `Database connection failed: ${error.message}`,
-        details: { error: error.message },
-        fixable: false
-      }
-    }
-
-    return {
-      name: 'database',
-      status: 'pass',
-      message: `Database connected (${latency}ms latency)`,
-      details: { latency_ms: latency }
-    }
-  } catch (err: any) {
-    return {
-      name: 'database',
-      status: 'fail',
-      message: `Database connection error: ${err.message}`,
-      fixable: false
-    }
-  }
-}
-
-async function checkMigrations(): Promise<CheckResult> {
-  const migrationsDir = resolve(__dirname, '../../migrations_dayzero')
-
-  if (!existsSync(migrationsDir)) {
-    return {
-      name: 'migrations',
-      status: 'fail',
-      message: 'Migrations directory not found',
-      fixable: false
-    }
-  }
-
-  const localFiles = readdirSync(migrationsDir)
-    .filter(f => f.endsWith('.sql'))
-    .sort()
-
-  try {
-    const { data, error } = await adminDb
-      .schema('public' as any)
-      .from('schema_migrations' as any)
-      .select('version')
-
-    if (error) {
-      return {
-        name: 'migrations',
-        status: 'fail',
-        message: `Cannot query applied migrations: ${error.message}`,
-        details: { error: error.message },
-        fixable: false
-      }
-    }
-
-    const applied = (data || []).map((r: any) => r.version)
-    const appliedSet = new Set(applied)
-    const pending = localFiles.filter(f => !appliedSet.has(f.replace('.sql', '')))
-
-    if (pending.length > 0) {
-      return {
-        name: 'migrations',
-        status: 'warn',
-        message: `${pending.length} pending migrations: ${pending.join(', ')}`,
-        details: { pending: pending.map(f => f.replace('.sql', '')), applied: applied.length },
-        fixable: true
-      }
-    }
-
-    return {
-      name: 'migrations',
-      status: 'pass',
-      message: `All ${applied.length} migrations applied`,
-      details: { applied: applied.length, latest: applied[applied.length - 1] }
-    }
-  } catch (err: any) {
-    return {
-      name: 'migrations',
-      status: 'fail',
-      message: `Migration check error: ${err.message}`,
-      fixable: false
-    }
-  }
-}
-
-async function checkIntegrity(): Promise<CheckResult> {
-  const manifestPath = resolve(__dirname, '../../.spine-manifest.json')
-
-  if (!existsSync(manifestPath)) {
-    return {
-      name: 'integrity',
-      status: 'warn',
-      message: 'No manifest found (integrity check skipped)',
-      details: { manifest_path: manifestPath },
-      fixable: true
-    }
-  }
-
-  try {
-    const content = readFileSync(manifestPath, 'utf8')
-    const manifest = JSON.parse(content)
-
-    if (!manifest.integrity?.src) {
-      return {
-        name: 'integrity',
-        status: 'warn',
-        message: 'Manifest exists but has no integrity hash',
-        fixable: true
-      }
-    }
-
-    // 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',
-      message: 'Core manifest present and valid',
-      details: { version: manifest.version, has_integrity: true }
-    }
-  } catch (err: any) {
-    return {
-      name: 'integrity',
-      status: 'fail',
-      message: `Manifest error: ${err.message}`,
-      fixable: true
-    }
-  }
-}
-
-async function checkTestRuns(): Promise<CheckResult> {
-  try {
-    const { data, error } = await adminDb
-      .from('test_runs')
-      .select('suite, status, started_at')
-      .order('started_at', { ascending: false })
-      .limit(1)
-      .single()
-
-    if (error) {
-      return {
-        name: 'test_runs',
-        status: 'warn',
-        message: `Cannot query test runs: ${error.message}`,
-        details: { error: error.message },
-        fixable: false
-      }
-    }
-
-    if (!data) {
-      return {
-        name: 'test_runs',
-        status: 'warn',
-        message: 'No test runs found - run `spine test` to populate',
-        fixable: true
-      }
-    }
-
-    const status = data.status === 'passed' ? 'pass' : 'warn'
-    return {
-      name: 'test_runs',
-      status,
-      message: `Last test run (${data.suite}): ${data.status}`,
-      details: { last_suite: data.suite, last_status: data.status, last_at: data.started_at }
-    }
-  } catch (err: any) {
-    return {
-      name: 'test_runs',
-      status: 'warn',
-      message: `Test run check error: ${err.message}`,
-      fixable: false
-    }
-  }
-}
-
-// ─── FIX IMPLEMENTATIONS ───────────────────────────────────────────────────
-
-async function tryFix(check: CheckResult): Promise<string> {
-  switch (check.name) {
-    case 'environment':
-      return 'Please set missing environment variables in .xenv or export them'
-
-    case 'migrations':
-      return 'Run `npx spine migrations apply` or use Supabase CLI to apply pending migrations'
-
-    case 'integrity':
-      return 'Run `npm run manifest` to regenerate the integrity manifest'
-
-    case 'test_runs':
-      return 'Run `npm run test` to execute test suites'
-
-    default:
-      return 'No automatic fix available'
-  }
-}
-
-// ─── COMMAND REGISTRATION ──────────────────────────────────────────────────
-
-export function registerDoctorCommands(program: Command) {
-  program
-    .command('doctor')
-    .description('Validate Spine installation health')
-    .option('--json', 'Output as JSON')
-    .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()
-        } catch {
-          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())
-          } else {
-            checks.push({
-              name: 'migrations',
-              status: 'fail',
-              message: 'Skipped - database not connected',
-              fixable: false
-            })
-            checks.push({
-              name: 'test_runs',
-              status: 'fail',
-              message: 'Skipped - database not connected',
-              fixable: false
-            })
-          }
-        } else {
-          checks.push({
-            name: 'database',
-            status: 'fail',
-            message: 'Skipped - environment variables missing',
-            fixable: false
-          })
-          checks.push({
-            name: 'migrations',
-            status: 'fail',
-            message: 'Skipped - environment variables missing',
-            fixable: false
-          })
-          checks.push({
-            name: 'test_runs',
-            status: 'fail',
-            message: 'Skipped - environment variables missing',
-            fixable: false
-          })
-        }
-
-        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
-
-        let overall: DoctorReport['overall']
-        if (failed > 0) {
-          overall = 'unhealthy'
-        } else if (warnings > 0) {
-          overall = 'degraded'
-        } else {
-          overall = 'healthy'
-        }
-
-        const report: DoctorReport = {
-          overall,
-          checks,
-          summary: {
-            passed: checks.filter(c => c.status === 'pass').length,
-            failed,
-            warnings,
-            fixable
-          }
-        }
-
-        // Output
-        if (opts.json) {
-          console.log(JSON.stringify(report, null, 2))
-        } else {
-          console.log('\nSpine Doctor — System Health Check')
-          console.log('═'.repeat(50))
-          console.log(`Overall Status: ${overall.toUpperCase()}`)
-          console.log()
-
-          for (const check of checks) {
-            const icon = check.status === 'pass' ? '✓' :
-                        check.status === 'warn' ? '⚠' : '✗'
-            const color = check.status === 'pass' ? '\x1b[32m' :
-                         check.status === 'warn' ? '\x1b[33m' : '\x1b[31m'
-            const reset = '\x1b[0m'
-
-            console.log(`${color}${icon}${reset} ${check.name}: ${check.message}`)
-
-            if (opts.fix && check.status !== 'pass' && check.fixable) {
-              const fixMsg = await tryFix(check)
-              console.log(`       → ${fixMsg}`)
-            }
-          }
-
-          console.log()
-          console.log('Summary:', report.summary)
-          console.log()
-        }
-
-        // Exit code
-        if (overall === 'unhealthy') {
-          process.exit(1)
-        } else if (overall === 'degraded') {
-          process.exit(2)
-        } else {
-          process.exit(0)
-        }
-
-      } catch (err: any) {
-        handleError(err)
-      }
-    })
-}