spine-framework 0.3.125 → 0.3.126

package/.framework/cli/commands/status.ts

@@ -1,20 +1,20 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/status
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine-framework status` — shows installed apps, migration state, and
- * framework version.
- *
- * **Usage:**
- * ```bash
- * npx spine-framework status
- * npx spine-framework status --json
- * ```
- */
 
+
+// CIL[BEGIN chunk_id="status_moduleheader_1784068794" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies and set up paths"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load required modules and configure directory paths"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" 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="loaded_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Commander, file system, path utilities, and Supabase client" 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: commands. 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"]
 import type { Command } from 'commander'
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { resolve, dirname, join, basename } from 'path'
@@ -25,7 +25,21 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 const PACKAGE_ROOT = resolve(__dirname, '../../../')
 const PROJECT_ROOT = process.cwd()
-
+// CIL[END chunk_id="status_moduleheader_1784068794"]
+// CIL[BEGIN chunk_id="status_registerstatuscommands_1784068794" type="function" identity="registerStatusCommands" parent="none"]
+// CIL[DOC-MACRO purpose="Register status command with CLI program"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display framework and project status information"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="status_display" errors="file_read_errors" side_effects="console_output"]
+// CIL[DOC-MICRO logic_summary="Shows framework version, installed apps, and migration status" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: commands. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .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"]
 export function registerStatusCommands(program: Command) {
   program
     .command('status')
@@ -37,14 +51,12 @@ export function registerStatusCommands(program: Command) {
       const supabaseUrl = process.env.SUPABASE_URL
       const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
 
-      // Framework version
       let frameworkVersion = 'unknown'
       try {
         const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
         frameworkVersion = pkg.version
       } catch {}
 
-      // Installed apps (from custom/apps/)
       const appsDir = join(PROJECT_ROOT, 'custom/apps')
       const installedApps: { slug: string; version?: string; hasManifest: boolean }[] = []
 
@@ -65,7 +77,6 @@ export function registerStatusCommands(program: Command) {
         }
       }
 
-      // Migration state
       let migrations: { applied: number; pending: number; files: string[] } = {
         applied: 0,
         pending: 0,
@@ -94,7 +105,6 @@ export function registerStatusCommands(program: Command) {
           migrations.applied = migrations.files.filter(f => appliedSet.has(f)).length
           migrations.pending = migrations.files.length - migrations.applied
         } catch {
-          // DB not accessible — just show file count
           migrations.pending = migrations.files.length
         }
       }
@@ -104,7 +114,6 @@ export function registerStatusCommands(program: Command) {
         return
       }
 
-      // Human-readable output
       console.log('\n── Spine Framework Status ─────────────────────────────')
       console.log(`   Version:      spine-framework@${frameworkVersion}`)
       console.log(`   Project:      ${PROJECT_ROOT}`)
@@ -136,7 +145,21 @@ export function registerStatusCommands(program: Command) {
       console.log()
     })
 }
-
+// CIL[END chunk_id="status_registerstatuscommands_1784068794"]
+// CIL[BEGIN chunk_id="status_loadenv_1784068794" type="function" identity="loadEnv" parent="none"]
+// CIL[DOC-MACRO purpose="Load environment variables from .env file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Parse and set environment variables"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="process_env" errors="file_read_errors" side_effects="process_env_modification"]
+// CIL[DOC-MICRO logic_summary="Reads .env file and sets non-existent environment variables" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: commands. Direct callers: 0. Direct calls: 0. Related files: \."]
+// 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"]
 function loadEnv() {
   const envPath = join(PROJECT_ROOT, '.env')
   if (!existsSync(envPath)) return
@@ -151,3 +174,4 @@ function loadEnv() {
     if (key && !(key in process.env)) process.env[key] = val
   }
 }
+// CIL[END chunk_id="status_loadenv_1784068794"]

package/.framework/cli/commands/system.ts

@@ -1,45 +1,43 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/system
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine system` command — CLI interface to system discovery endpoints.
- * Queries the running Spine instance for manifest, health, and OpenAPI spec.
- *
- * **Commands:**
- * | Subcommand              | Description                                           |
- * |-------------------------|-------------------------------------------------------|
- * | `system manifest`       | Fetch and display system manifest                     |
- * | `system health`         | Fetch and display health check results                |
- * | `system openapi`        | Fetch OpenAPI spec (outputs JSON)                     |
- * | `system --json`         | Output as JSON for all subcommands                    |
- *
- * **Usage:**
- * ```bash
- * spine system manifest
- * spine system health --json
- * spine system openapi > openapi.json
- * ```
- *
- * @seeAlso functions/system.ts (HTTP endpoints this CLI consumes)
- */
 
+
+// CIL[BEGIN chunk_id="system_moduleheader_1784068794" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import CLI dependencies and context utilities"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load required modules for system commands"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" 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="loaded_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Commander type and context utilities" 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: commands. 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"]
 import type { Command } from 'commander'
 import { buildCliContext, printResult, handleError } from '../context.ts'
-
-// ─── API CLIENT ────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="system_moduleheader_1784068794"]
+// CIL[BEGIN chunk_id="system_fetchsystemendpoint_1784068794" type="function" identity="fetchSystemEndpoint" parent="none"]
+// CIL[DOC-MACRO purpose="Fetch system endpoint from local dev server"]
+// CIL[DOC-RESPONSIBILITY responsibility="Make HTTP requests to system functions"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="json_response" errors="http_errors" side_effects="network_requests"]
+// CIL[DOC-MICRO logic_summary="Makes GET requests to local dev server with proper error handling" 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: commands. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, 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"]
 async function fetchSystemEndpoint(ctx: any, action: string): Promise<any> {
   const supabaseUrl = process.env.SUPABASE_URL
   if (!supabaseUrl) {
     throw new Error('SUPABASE_URL not configured')
   }
 
-  // Construct the Netlify function URL
-  // When running locally, this is http://localhost:8888/.netlify/functions/system
-  // We'll try localhost:8888 first, then fall back to production URL if configured
   const localUrl = 'http://localhost:8888/.netlify/functions/system'
   const url = `${localUrl}?action=${action}`
 
@@ -59,7 +57,6 @@ async function fetchSystemEndpoint(ctx: any, action: string): Promise<any> {
 
     return await response.json()
   } catch (err: any) {
-    // If local fails, try direct Supabase function invoke (for production)
     if (err.message.includes('fetch failed') || err.message.includes('ECONNREFUSED')) {
       throw new Error(
         'Cannot connect to local dev server. ' +
@@ -69,9 +66,21 @@ async function fetchSystemEndpoint(ctx: any, action: string): Promise<any> {
     throw err
   }
 }
-
-// ─── COMMAND REGISTRATION ────────────────────────────────────────────────
-
+// CIL[END chunk_id="system_fetchsystemendpoint_1784068794"]
+// CIL[BEGIN chunk_id="system_registersystemcommands_1784068794" type="function" identity="registerSystemCommands" parent="none"]
+// CIL[DOC-MACRO purpose="Register system commands with CLI program"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure system discovery and health commands"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="system_commands" errors="command_errors" side_effects="console_output"]
+// CIL[DOC-MICRO logic_summary="Registers manifest, health, and openapi subcommands" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: commands. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.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 function registerSystemCommands(program: Command) {
   const system = program
     .command('system')
@@ -182,3 +191,4 @@ export function registerSystemCommands(program: Command) {
       }
     })
 }
+// CIL[END chunk_id="system_registersystemcommands_1784068794"]

package/.framework/cli/commands/test.ts

@@ -1,48 +1,24 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/test
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine test` command — unified test runner for all 4 test surfaces.
- * Runs Vitest tests and persists results to Supabase via the custom reporter.
- *
- * **Commands:**
- * | Subcommand              | Description                                           |
- * |-------------------------|-------------------------------------------------------|
- * | `test`                  | Run all test suites                                   |
- * | `test unit`             | Run unit tests only                                   |
- * | `test integration`      | Run integration tests only                            |
- * | `test api`              | Run API tests only                                    |
- * | `test ui`               | Run UI/Playwright tests only                          |
- * | `test --json`           | Output structured JSON summary                        |
- * | `test --watch`          | Run in watch mode (for unit/integration)              |
- *
- * **Test surfaces:**
- * - **unit**: Fast tests, no DB (v2-core/tests/unit/)
- * - **integration**: DB tests with fixtures (v2-core/tests/integration/)
- * - **api**: HTTP fetch tests against localhost:8888 (v2-core/tests/api/)
- * - **ui**: Playwright browser tests (v2-core/tests/ui/)
- *
- * **Results:**
- * All test runs are persisted to `public.test_runs` and `public.test_results`
- * via the custom Vitest reporter (v2-core/tests/reporter.ts).
- *
- * **Usage:**
- * ```bash
- * spine test
- * spine test unit --watch
- * spine test integration --json
- * spine test api
- * spine test ui
- * ```
- *
- * @seeAlso tests/reporter.ts (custom Vitest reporter)
- * @seeAlso functions/tests.ts (API endpoint for querying results)
- * @seeAlso pages/admin/TestingDashboard.tsx (UI for viewing results)
- */
 
+
+
+
+
+
+// CIL[BEGIN chunk_id="test_moduleheader_1784068794" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies and set up test configuration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load required modules and define test types"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" 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="loaded_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Commander, child process, path utilities and defines TestSuite type" 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: commands. 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"]
 import type { Command } from 'commander'
 import { spawn } from 'child_process'
 import { resolve, dirname } from 'path'
@@ -52,21 +28,43 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 const PROJECT_ROOT = resolve(__dirname, '../../../')
 
-// ─── TYPES ─────────────────────────────────────────────────────────────────
-
 type TestSuite = 'unit' | 'integration' | 'api' | 'ui' | 'all'
-
-// ─── SUITE CONFIGURATION ───────────────────────────────────────────────────
-
+// CIL[END chunk_id="test_moduleheader_1784068794"]
+// CIL[BEGIN chunk_id="test_suites_1784068794" type="variable" identity="SUITES" parent="none"]
+// CIL[DOC-MACRO purpose="Define test suite configurations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure test patterns and runners"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="suite_config" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Maps test suite names to file patterns and test runners" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: commands. 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, custom/apps/cortex/functions/custom_cil-embeddings.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 SUITES: Record<string, { pattern: string; runner: 'vitest' | 'playwright' | 'node' }> = {
   unit: { pattern: 'v2-core/tests/unit', runner: 'vitest' },
   integration: { pattern: 'v2-core/tests/integration', runner: 'vitest' },
   api: { pattern: 'v2-core/tests/api', runner: 'vitest' },
   ui: { pattern: 'v2-core/tests/ui', runner: 'playwright' }
 }
-
-// ─── COMMAND REGISTRATION ──────────────────────────────────────────────────
-
+// CIL[END chunk_id="test_suites_1784068794"]
+// CIL[BEGIN chunk_id="test_registertestcommands_1784068794" type="function" identity="registerTestCommands" parent="none"]
+// CIL[DOC-MACRO purpose="Register test commands with CLI program"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure and execute test suite commands"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test_execution" errors="test_errors" side_effects="process_exit"]
+// CIL[DOC-MICRO logic_summary="Registers test command with options for suite, watch, reporter, and JSON output" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: commands. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, .framework/src/pages/admin/TypeDetailPage.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 function registerTestCommands(program: Command) {
   const testCmd = program
     .command('test [suite]')
@@ -77,14 +75,12 @@ export function registerTestCommands(program: Command) {
     .action(async (suiteArg: string | undefined, opts) => {
       const suite: TestSuite = (suiteArg || 'all') as TestSuite
 
-      // Validate suite
       if (suite !== 'all' && !SUITES[suite]) {
         console.error(`\n❌ Unknown test suite: ${suite}`)
         console.log('Valid suites: unit, integration, api, ui, all')
         process.exit(1)
       }
 
-      // Determine which suites to run
       const suitesToRun = suite === 'all'
         ? ['unit', 'integration', 'api', 'ui']
         : [suite]
@@ -123,7 +119,6 @@ export function registerTestCommands(program: Command) {
         }
       }
 
-      // Summary
       console.log('\n' + '='.repeat(50))
       console.log('Test Run Summary')
       console.log('='.repeat(50))
@@ -140,7 +135,6 @@ export function registerTestCommands(program: Command) {
       console.log()
       console.log(`Total: ${totalPassed} passed, ${totalFailed} failed`)
 
-      // JSON output
       if (opts.json) {
         const jsonOutput = {
           suites: results.map(r => ({
@@ -157,13 +151,24 @@ export function registerTestCommands(program: Command) {
         console.log('\n' + JSON.stringify(jsonOutput, null, 2))
       }
 
-      // Exit code
       process.exit(totalFailed > 0 ? 1 : 0)
     })
 }
-
-// ─── RUNNER IMPLEMENTATIONS ────────────────────────────────────────────────
-
+// CIL[END chunk_id="test_registertestcommands_1784068794"]
+// CIL[BEGIN chunk_id="test_runvitest_1784068794" type="function" identity="runVitest" parent="none"]
+// CIL[DOC-MACRO purpose="Execute Vitest test runner"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run unit/integration/API tests with Vitest"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="exit_code" errors="vitest_errors" side_effects="process_spawn"]
+// CIL[DOC-MICRO logic_summary="Configures and runs Vitest with pattern, config, watch mode, and reporter options" 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: commands. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, \."]
+// 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 runVitest(suite: string, opts: any): Promise<number> {
   const config = SUITES[suite]
   const args = [
@@ -173,10 +178,9 @@ async function runVitest(suite: string, opts: any): Promise<number> {
   ]
 
   if (opts.watch) {
-    args[0] = 'watch' // Replace 'run' with 'watch'
+    args[0] = 'watch'
   }
 
-  // Custom reporters - include both default and our custom reporter
   if (opts.reporter === 'default') {
     args.push('--reporter=default')
     args.push('--reporter=' + resolve(PROJECT_ROOT, 'v2-core/tests/reporter.ts'))
@@ -186,10 +190,22 @@ async function runVitest(suite: string, opts: any): Promise<number> {
 
   return runCommand('npx', ['vitest', ...args], PROJECT_ROOT)
 }
-
+// CIL[END chunk_id="test_runvitest_1784068794"]
+// CIL[BEGIN chunk_id="test_runplaywright_1784068794" type="function" identity="runPlaywright" parent="none"]
+// CIL[DOC-MACRO purpose="Execute Playwright test runner"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run UI tests with Playwright"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="exit_code" errors="playwright_errors" side_effects="process_spawn"]
+// CIL[DOC-MICRO logic_summary="Configures and runs Playwright with pattern and JSON reporter option" 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: commands. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, \."]
+// 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 runPlaywright(suite: string, opts: any): Promise<number> {
-  // Playwright tests run against a running dev server
-  // We need to ensure the server is running or start it
   console.log('   (Playwright tests require dev server on localhost:8888)')
 
   const args = ['playwright', 'test', SUITES[suite].pattern]
@@ -200,13 +216,40 @@ async function runPlaywright(suite: string, opts: any): Promise<number> {
 
   return runCommand('npx', args, PROJECT_ROOT)
 }
-
+// CIL[END chunk_id="test_runplaywright_1784068794"]
+// CIL[BEGIN chunk_id="test_runnode_1784068794" type="function" identity="runNode" parent="none"]
+// CIL[DOC-MACRO purpose="Execute Node.js test runner"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run tests directly with Node.js"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="exit_code" errors="node_errors" side_effects="process_spawn"]
+// CIL[DOC-MICRO logic_summary="Runs test files directly with Node.js using suite pattern" 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: commands. 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 runNode(suite: string, opts: any): Promise<number> {
-  // For custom test scripts that aren't Vitest or Playwright
   const args = [SUITES[suite].pattern]
   return runCommand('node', args, PROJECT_ROOT)
 }
-
+// CIL[END chunk_id="test_runnode_1784068794"]
+// CIL[BEGIN chunk_id="test_runcommand_1784068794" type="function" identity="runCommand" parent="none"]
+// CIL[DOC-MACRO purpose="Execute shell command with promise wrapper"]
+// CIL[DOC-RESPONSIBILITY responsibility="Spawn child process and handle exit/error"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="exit_code" errors="spawn_errors" side_effects="process_spawn"]
+// CIL[DOC-MICRO logic_summary="Wraps child_process.spawn in Promise with proper error handling" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: commands. 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"]
 function runCommand(command: string, args: string[], cwd: string): Promise<number> {
   return new Promise((resolve, reject) => {
     const proc = spawn(command, args, {
@@ -225,3 +268,4 @@ function runCommand(command: string, args: string[], cwd: string): Promise<numbe
     })
   })
 }
+// CIL[END chunk_id="test_runcommand_1784068794"]