spine-framework 0.3.145 → 0.4.1

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

@@ -1,70 +1,119 @@
-
-
-
-
-
-
-// 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"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Module-level setup and shared imports for the CLI test command"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide ESM path helpers, type definitions, and runner configuration used by test command functions"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="" outputs="" errors="" side_effects=""]
+// CIL[DOC-MICRO logic_summary="Imports Commander, child_process, and path helpers; defines constants and types for test execution" notable_decisions="ESM-compatible __filename and __dirname resolution"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+// CIL[DOC-AUDIENCE audience="cli developer, maintainer"]
 import type { Command } from 'commander'
 import { spawn } from 'child_process'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
-
+// CIL[DOC-VECTOR type="context" content="purpose='Module-level setup and shared imports for the CLI test command'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Compute the absolute file path for this ESM module"]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve the current modules __filename equivalent for path calculations"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="import.meta.url" outputs="string absolute file path" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Converts the ESM import.meta.url to a file URL path using fileURLToPath" notable_decisions="Polyfills CommonJS __filename in an ESM module"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 const __filename = fileURLToPath(import.meta.url)
+// CIL[DOC-VECTOR type="context" content="purpose='Compute the absolute file path for this ESM module'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:__filename:constant"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Compute the directory path of this ESM module"]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve the current modules __dirname equivalent for project-root lookup"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="__filename" outputs="string directory path" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses path.dirname to derive the directory from the ESM __filename" notable_decisions="Polyfills CommonJS __dirname in an ESM module"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 const __dirname = dirname(__filename)
+// CIL[DOC-VECTOR type="context" content="purpose='Compute the directory path of this ESM module'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:__dirname:constant"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:PROJECT_ROOT:constant" type="constant" identity="PROJECT_ROOT" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Resolve the absolute project root from the CLI command location"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the root directory used as working directory for test runners"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="__dirname" outputs="string project root path" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Resolves three parent directories up from .framework/cli/commands" notable_decisions="Hardcoded relative traversal matches the framework path layout"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 const PROJECT_ROOT = resolve(__dirname, '../../../')
-
+// CIL[DOC-VECTOR type="context" content="purpose='Resolve the absolute project root from the CLI command location'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:PROJECT_ROOT:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:TestSuite:type" type="type" identity="TestSuite" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Define the union of supported test suite identifiers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type-check the suite argument accepted by the test command"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TestSuite union type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Exports a string literal union of unit, integration, api, ui, and all" notable_decisions="Keeps suite names as a single source of truth for CLI validation"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 type TestSuite = 'unit' | 'integration' | 'api' | 'ui' | 'all'
-// 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="context" content="purpose='Define the union of supported test suite identifiers'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:TestSuite:type"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:SUITES:constant" type="constant" identity="SUITES" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Map suite names to their test directory patterns and runner executables"]
+// CIL[DOC-RESPONSIBILITY responsibility="Centralize suite configuration consumed by registerTestCommands and runner functions"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Record<string, {pattern: string, runner: vitest|playwright|node}>" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines a lookup of suite patterns under v2-core/tests and the runner to invoke" notable_decisions="Defaults all non-ui suites to vitest; ui suite uses playwright"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 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' }
 }
-// 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="context" content="purpose='Map suite names to their test directory patterns and runner executables'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:SUITES:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:registerTestCommands:function" type="function" identity="registerTestCommands" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Register the test subcommand with the Commander CLI program"]
+// CIL[DOC-RESPONSIBILITY responsibility="Wire the test command, validate the suite argument, run suites, and print a summary"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="program: Command" outputs="void" errors="console.error and process.exit(1) on unknown suite" side_effects="registers test subcommand, logs to console, calls process.exit with 0 or 1"]
+// CIL[DOC-MICRO logic_summary="Parses suite and options, iterates over suites, dispatches runner, collects results, and prints JSON or text summary" notable_decisions="Unknown suites cause immediate stderr and exit; all runs all known suites in order"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export function registerTestCommands(program: Command) {
   const testCmd = program
     .command('test [suite]')
@@ -154,21 +203,22 @@ export function registerTestCommands(program: Command) {
       process.exit(totalFailed > 0 ? 1 : 0)
     })
 }
-// 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="context" content="purpose='Register the test subcommand with the Commander CLI program'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:registerTestCommands:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:runVitest:function" type="function" identity="runVitest" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Assemble and execute a Vitest test run for a given suite"]
+// CIL[DOC-RESPONSIBILITY responsibility="Build Vitest CLI arguments and return the exit code"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="suite: string, opts: any" outputs="number (exit code)" errors="rejects if npx vitest fails to spawn or exits with an error event" side_effects="spawns npx vitest child process with inherited stdio"]
+// CIL[DOC-MICRO logic_summary="Constructs run/watch and reporter arguments, then delegates to runCommand" notable_decisions="Adds a custom reporter from v2-core/tests/reporter.ts when default is selected"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 async function runVitest(suite: string, opts: any): Promise<number> {
   const config = SUITES[suite]
   const args = [
@@ -190,21 +240,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="context" content="purpose='Assemble and execute a Vitest test run for a given suite'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:runVitest:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:runPlaywright:function" type="function" identity="runPlaywright" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Assemble and execute a Playwright test run for the UI suite"]
+// CIL[DOC-RESPONSIBILITY responsibility="Build Playwright CLI arguments and return the exit code"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="suite: string, opts: any" outputs="number (exit code)" errors="rejects if npx playwright fails to spawn or exits with an error event" side_effects="spawns npx playwright child process with inherited stdio; logs dev server requirement"]
+// CIL[DOC-MICRO logic_summary="Constructs playwright test arguments and optionally enables JSON reporter" notable_decisions="Assumes a dev server is running on localhost:8888"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 async function runPlaywright(suite: string, opts: any): Promise<number> {
   console.log('   (Playwright tests require dev server on localhost:8888)')
 
@@ -216,40 +267,42 @@ 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="context" content="purpose='Assemble and execute a Playwright test run for the UI suite'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:runPlaywright:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:runNode:function" type="function" identity="runNode" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Execute a test file directly with Node.js"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run a suites test directory as a Node.js module and return the exit code"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="suite: string, opts: any" outputs="number (exit code)" errors="rejects if node process fails to spawn or emits an error event" side_effects="spawns node child process with inherited stdio"]
+// CIL[DOC-MICRO logic_summary="Looks up the suite pattern and spawns node with it as the entry point" notable_decisions="Relies on Node.js for simple or one-off test scripts"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 async function runNode(suite: string, opts: any): Promise<number> {
   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="context" content="purpose='Execute a test file directly with Node.js'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:runNode:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/test.ts:runCommand:function" type="function" identity="runCommand" parent="~/.framework/cli/commands/test.ts"]
+// CIL[DOC-MACRO purpose="Spawn a shell command and return its exit code"]
+// CIL[DOC-RESPONSIBILITY responsibility="Abstract child_process spawn for test runners"]
+// CIL[DOC-CONTEXT module="cli" layer="commands" related_files=".framework/cli/commands/test.ts"]
+// CIL[DOC-CONTRACT inputs="command: string, args: string[], cwd: string" outputs="number (exit code)" errors="rejects on spawn error" side_effects="spawns a child process with inherited stdio and shell mode"]
+// CIL[DOC-MICRO logic_summary="Returns a promise that resolves when the child process exits and rejects on spawn errors" notable_decisions="Uses shell: true and stdio: inherit to preserve terminal output"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 function runCommand(command: string, args: string[], cwd: string): Promise<number> {
   return new Promise((resolve, reject) => {
     const proc = spawn(command, args, {
@@ -268,4 +321,10 @@ function runCommand(command: string, args: string[], cwd: string): Promise<numbe
     })
   })
 }
-// CIL[END chunk_id="test_runcommand_1784068794"]
+// CIL[DOC-VECTOR type="context" content="purpose='Spawn a shell command and return its exit code'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/test.ts:runCommand:function"]

package/.framework/cli/commands/upgrade.ts

@@ -0,0 +1,260 @@
+// CIL[BEGIN stable_id="~/.framework/cli/commands/upgrade.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/commands/upgrade.ts"]
+// CIL[DOC-MACRO purpose="Sync an installed project's framework-owned files to the spine-framework version in node_modules"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify the current tree against the frozen .spine-manifest.json, then overwrite .framework/config/scripts/bin from the installed package, merge framework deps+scripts into package.json, re-render netlify.toml preserving app-owned custom_* sections, and regenerate the manifest at the new framework_version"]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/lib/project-files.ts,.framework/templates/project.json,.framework/cli/commands/init.ts"]
+// CIL[DOC-CONTRACT inputs="[--dry-run] [--force]; runs in the project root; new version comes from node_modules/spine-framework" outputs="synced tree + regenerated manifest + change report" errors="exit 1 when no manifest, package absent/older, or protected files were locally modified (without --force)" side_effects="writes framework-owned paths only; --dry-run writes nothing"]
+// CIL[DOC-MICRO logic_summary="The executing command is always the NEW package's copy — npx spine-framework upgrade resolves node_modules. Deletions are limited to .framework/ entries tracked in the old manifest but absent upstream; config/scripts files dropped upstream are warned, not deleted. custom/, spine.config.json, .env, .spine/, and netlify.toml custom_* sections are never touched" notable_decisions="integrity abort is the safety rail — a sealed .framework/ tree means overwrite-on-upgrade loses nothing the user owned"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-NOTE type="design" content="Upgrade is file-sync, not git-aware; rollback = git. Migrations are reported, never run — `npx spine-framework migrate` applies them"]
+// CIL[DOC-AUDIENCE audience="developer"]
+
+import type { Command } from 'commander'
+import { existsSync, readFileSync, writeFileSync, rmSync, lstatSync } from 'fs'
+import { resolve, dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { hashEntry } from '../../../scripts/checksum-manifest.mts'
+import {
+  loadProjectProfile,
+  collectFrameworkFiles,
+  copyCollectedFiles,
+  renderNetlifyToml,
+  mergePackageJson,
+  writeFrozenManifest,
+  cmpSemver,
+} from '../lib/project-files.ts'
+// CIL[END stable_id="~/.framework/cli/commands/upgrade.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/upgrade.ts:paths:block" type="block" identity="paths" parent="~/.framework/cli/commands/upgrade.ts"]
+// CIL[DOC-MACRO purpose="Path constants — PACKAGE_ROOT is the new version's source of truth; PROJECT_ROOT is the installed project being upgraded"]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files="package.json,.spine-manifest.json"]
+// CIL[DOC-CONTRACT inputs="none" outputs="resolved path constants" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="PACKAGE_ROOT resolves inside node_modules/spine-framework — the executing command is always the NEW package's copy; PROJECT_ROOT is process.cwd()" notable_decisions="new code upgrades old files, never the reverse"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const PACKAGE_ROOT = resolve(__dirname, '../../../')
+const PROJECT_ROOT = process.cwd()
+
+const MANIFEST_PATH = join(PROJECT_ROOT, '.spine-manifest.json')
+// CIL[END stable_id="~/.framework/cli/commands/upgrade.ts:paths:block"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/upgrade.ts:registerUpgradeCommands:function" type="function" identity="registerUpgradeCommands" parent="~/.framework/cli/commands/upgrade.ts"]
+// CIL[DOC-MACRO purpose="Register `upgrade [--dry-run] [--force]` — delegates to runUpgrade with a fatal-error wrapper"]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/index.ts"]
+// CIL[DOC-CONTRACT inputs="program: Command" outputs="void" errors="catches runUpgrade errors → exit 1 (stack behind SPINE_CLI_DEBUG)" side_effects="mutates Commander program; may write project files via runUpgrade"]
+// CIL[DOC-MICRO logic_summary="Thin Commander wiring — all logic lives in runUpgrade" notable_decisions="error wrapper prints message + exits; stack only under SPINE_CLI_DEBUG"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+export function registerUpgradeCommands(program: Command) {
+  program
+    .command('upgrade')
+    .description('Sync this project to the spine-framework version installed in node_modules')
+    .option('--dry-run', 'Report the changes without writing anything', false)
+    .option('--force', 'Overwrite locally modified framework files', false)
+    .action(async (opts: { dryRun: boolean; force: boolean }) => {
+      try {
+        runUpgrade(opts)
+      } catch (err: any) {
+        console.error(`\n❌ Upgrade failed: ${err.message}`)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+}
+// CIL[END stable_id="~/.framework/cli/commands/upgrade.ts:registerUpgradeCommands:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/upgrade.ts:runUpgrade:function" type="function" identity="runUpgrade" parent="~/.framework/cli/commands/upgrade.ts"]
+// CIL[DOC-MACRO purpose="Sync installed project's framework-owned files to the package version — integrity check, file sync, package.json merge, netlify.toml render, manifest regen"]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".spine-manifest.json,.framework/cli/lib/project-files.ts"]
+// CIL[DOC-CONTRACT inputs="abs: string, opts: { dryRun: boolean; force: boolean }" outputs="change report to stdout; synced tree on disk" errors="exit 1 on missing manifest, missing/older package, or locally modified protected files without --force" side_effects="writes framework-owned paths only; --dry-run writes nothing; netlify.toml custom_* sections preserved verbatim"]
+// CIL[DOC-MICRO logic_summary="Three-way compare (disk vs old manifest vs package payload): integrity abort on local mods → copy added/changed files → delete only .framework entries dropped upstream → merge package.json deps/scripts/pin → re-render netlify.toml → regenerate frozen manifest → list new migrations without running them" notable_decisions="non-.framework files dropped upstream are warned and retained; identical rendered TOML writes no .bak"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+function diskHash(abs: string): string {
+  const lst = lstatSync(abs)
+  return hashEntry({ rel: '', abs, symlink: lst.isSymbolicLink() })
+}
+
+function runUpgrade(opts: { dryRun: boolean; force: boolean }): void {
+  console.log('\nSpine Framework upgrade\n')
+
+  // 1. Preconditions
+  const srcPkgEarly = safeJson(join(PACKAGE_ROOT, 'package.json'))
+  if (srcPkgEarly?.name !== 'spine-framework') {
+    throw new Error(
+      'This upgrade command is running from the vendored project copy, which cannot update itself.\n' +
+      '   Run the installed package instead: npx spine-framework upgrade  (or npm run upgrade)',
+    )
+  }
+  if (!existsSync(MANIFEST_PATH)) {
+    throw new Error('No .spine-manifest.json — not a Spine-managed project (use `spine-framework init`)')
+  }
+  const oldManifest = JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'))
+  const oldVersion: string | null = oldManifest.framework_version ?? null
+  const newVersion = getPackageVersion()
+  const prevFrameworkDeps: string[] = Array.isArray(oldManifest.framework_dependencies)
+    ? oldManifest.framework_dependencies
+    : []
+
+  if (!oldVersion) {
+    console.log('  ⚠ Manifest has no framework_version — proceeding carefully')
+  } else if (cmpSemver(newVersion, oldVersion) < 0) {
+    throw new Error(`Installed package (v${newVersion}) is older than this project (v${oldVersion}). Install a newer spine-framework first.`)
+  } else if (cmpSemver(newVersion, oldVersion) === 0) {
+    console.log(`  ℹ Project already at spine-framework ${oldVersion}; syncing anyway`)
+  } else {
+    console.log(`  ${oldVersion} → ${newVersion}`)
+  }
+
+  const profile = loadProjectProfile(PACKAGE_ROOT)
+  const srcPkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+
+  // 2. Integrity — abort on locally modified or missing framework files
+  const oldFiles: Record<string, string> = oldManifest.files ?? {}
+  const modified: string[] = []
+  const missing: string[] = []
+  for (const [rel, hash] of Object.entries(oldFiles)) {
+    const abs = join(PROJECT_ROOT, rel)
+    if (!existsSync(abs)) { missing.push(rel); continue }
+    if (diskHash(abs) !== hash) modified.push(rel)
+  }
+  if ((modified.length > 0 || missing.length > 0) && !opts.force) {
+    console.error('\n❌ Framework files were modified locally — upgrade would overwrite them:')
+    for (const f of modified) console.error(`     modified: ${f}`)
+    for (const f of missing) console.error(`     missing:  ${f}`)
+    console.error('\n   Revert the changes, or rerun with --force to overwrite.')
+    process.exit(1)
+  }
+  if (opts.force && (modified.length || missing.length)) {
+    console.log(`  ⚠ --force: overwriting ${modified.length} modified, restoring ${missing.length} missing files`)
+  }
+
+  // 3. Compute the new file set and the change report
+  const files = collectFrameworkFiles(PACKAGE_ROOT, profile)
+  const newRels = new Set(files.map((f) => f.rel))
+  const added: string[] = []
+  const changed: string[] = []
+  let kept = 0
+  for (const f of files) {
+    const oldHash = oldFiles[f.rel]
+    const newHash = hashEntry(f)
+    if (oldHash) {
+      if (newHash !== oldHash) changed.push(f.rel)
+      else kept++
+    } else {
+      // Not in the manifest (root config files aren't integrity-tracked).
+      // Compare against what's on disk so reruns don't report phantom adds.
+      const abs = join(PROJECT_ROOT, f.rel)
+      if (!existsSync(abs)) added.push(f.rel)
+      else if (diskHash(abs) !== newHash) changed.push(f.rel)
+      else kept++
+    }
+  }
+  // Deletions: only inside .framework/ (fully sealed). config/scripts entries
+  // dropped upstream are reported, not deleted — extras there are harmless.
+  const removed = Object.keys(oldFiles).filter((rel) => !newRels.has(rel) && rel.startsWith('.framework/'))
+  const staleOutside = Object.keys(oldFiles).filter((rel) => !newRels.has(rel) && !rel.startsWith('.framework/'))
+
+  // New framework migrations = files under .framework/migrations not in the old manifest
+  const newMigrations = files
+    .map((f) => f.rel)
+    .filter((rel) => rel.startsWith('.framework/migrations/') && rel.endsWith('.sql') && !(rel in oldFiles))
+
+  console.log(`\n  ${added.length} added · ${changed.length} changed · ${removed.length} removed · ${kept} unchanged`)
+  if (opts.dryRun) {
+    for (const f of added) console.log(`     + ${f}`)
+    for (const f of changed) console.log(`     ~ ${f}`)
+    for (const f of removed) console.log(`     - ${f}`)
+    for (const f of staleOutside) console.log(`     ? ${f} (dropped upstream, left in place)`)
+    if (newMigrations.length > 0) {
+      console.log(`\n  New migrations in this version (${newMigrations.length}):`)
+      for (const rel of newMigrations) console.log(`     ${rel.split('/').pop()}`)
+    }
+    console.log('\n  (dry run — nothing written)\n')
+    return
+  }
+
+  // 4. Apply: copy new files, remove dropped .framework files
+  copyCollectedFiles(files, PROJECT_ROOT)
+  for (const rel of removed) rmSync(join(PROJECT_ROOT, rel), { force: true })
+  for (const rel of staleOutside) console.log(`  ⚠ ${rel} is no longer shipped upstream — left in place`)
+  console.log(`  ✓ framework files synced (${files.length})`)
+
+  // 5. package.json — framework scripts/deps, exact pin
+  const pkgPath = join(PROJECT_ROOT, 'package.json')
+  const existingPkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf8')) : {}
+  const merged = mergePackageJson({
+    existing: existingPkg,
+    name: existingPkg.name ?? 'spine-project',
+    scripts: profile.package_scripts,
+    newDependencies: srcPkg.dependencies ?? {},
+    newDevDependencies: srcPkg.devDependencies ?? {},
+    prevFrameworkDeps,
+    spineVersion: newVersion,
+  })
+  writeFileSync(pkgPath, merged.text)
+  console.log('  ✓ package.json updated (spine-framework pin + framework deps/scripts)')
+
+  // 6. netlify.toml — framework base replaced, app custom_* sections preserved
+  const netlifySrc = join(PACKAGE_ROOT, 'netlify.toml')
+  const netlifyDest = join(PROJECT_ROOT, 'netlify.toml')
+  if (existsSync(netlifySrc)) {
+    const existingToml = existsSync(netlifyDest) ? readFileSync(netlifyDest, 'utf8') : undefined
+    const nextToml = renderNetlifyToml(readFileSync(netlifySrc, 'utf8'), existingToml)
+    if (existingToml && existingToml !== nextToml) {
+      writeFileSync(`${netlifyDest}.bak`, existingToml)
+      console.log('  ✓ netlify.toml updated (backup at netlify.toml.bak; custom_* sections preserved)')
+      writeFileSync(netlifyDest, nextToml)
+    } else {
+      writeFileSync(netlifyDest, nextToml)
+      console.log('  ✓ netlify.toml written')
+    }
+  }
+
+  // 7. Regenerate frozen manifest at the new version
+  const manifest = writeFrozenManifest({
+    projectRoot: PROJECT_ROOT,
+    frameworkVersion: newVersion,
+    frameworkDeps: merged.frameworkDeps,
+  })
+  console.log(`  ✓ .spine-manifest.json regenerated (${manifest.fileCount} files)`)
+
+  if (newMigrations.length > 0) {
+    console.log(`\n  New migrations in this version (${newMigrations.length}):`)
+    for (const rel of newMigrations) console.log(`     ${rel.split('/').pop()}`)
+  }
+
+  console.log('\nNext steps:')
+  console.log('  1. npm install            # resolve the new dependency set')
+  console.log('  2. npm run verify         # confirm frozen integrity')
+  console.log('  3. npx spine-framework migrate   # apply new migrations (if any)')
+  console.log('  4. commit + deploy\n')
+}
+// CIL[END stable_id="~/.framework/cli/commands/upgrade.ts:runUpgrade:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/upgrade.ts:helpers:block" type="block" identity="helpers" parent="~/.framework/cli/commands/upgrade.ts"]
+// CIL[DOC-MACRO purpose="safeJson + getPackageVersion helpers — package version read is tolerant of missing/malformed JSON"]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files="package.json"]
+// CIL[DOC-CONTRACT inputs="file: string" outputs="parsed JSON | null; version string" errors="safeJson returns null on missing/malformed input" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Tolerant reads — a missing or corrupt JSON file degrades to null rather than throwing" notable_decisions="absence is data for upgrade decisions, not an exception"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+function safeJson(file: string): Record<string, any> | null {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function getPackageVersion(): string {
+  return safeJson(join(PACKAGE_ROOT, 'package.json'))?.version ?? '0.0.0'
+}
+// CIL[END stable_id="~/.framework/cli/commands/upgrade.ts:helpers:block"]