spine-framework 0.3.125 → 0.3.127

package/.framework/cli/commands/dev.ts

@@ -1,41 +1,31 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/dev
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine dev` command — unified development server for Spine.
- * Handles assembly, integrity verification, and Vite dev server startup.
- *
- * **Commands:**
- * | Subcommand        | Description                                           |
- * |-------------------|-------------------------------------------------------|
- * | `dev`             | Start dev server with assembly and integrity check    |
- * | `dev --no-verify` | Skip integrity verification (faster)                  |
- * | `dev --port 3002` | Use custom port (default: 3001)                       |
- * | `dev --watch`     | Watch v2-custom for changes and auto-reassemble         |
- * | `dev --no-watch`  | Disable file watching (manual rebuild only)           |
- *
- * **What happens:**
- * 1. Runs `assemble:v2` to merge v2-core + v2-custom
- * 2. Runs `verify` to check core integrity (unless --no-verify)
- * 3. Starts Vite dev server on port 3001 (or --port)
- * 4. Watches v2-custom/ for changes (--watch by default)
- * 5. Fast incremental reassembly on custom code changes
- *
- * **Usage:**
- * ```bash
- * spine dev
- * spine dev --port 3002
- * spine dev --no-verify
- * ```
- *
- * @seeAlso scripts/assemble-v2.sh (assembly script)
- * @seeAlso scripts/verify-integrity.sh (verification script)
- * @seeAlso vite.config.ts (Vite configuration)
- */
 
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="dev_module_header_1784071456" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for dev server CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide imports and constants for dev commands"]
+// CIL[DOC-CONTEXT module="dev-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, child_process, path, and fs 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 { spawn, execSync } from 'child_process'
 import { resolve, dirname } from 'path'
@@ -45,9 +35,21 @@ import { watch, existsSync, statSync, readdirSync } from 'fs'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 const PROJECT_ROOT = resolve(__dirname, '../../../')
-
-// ─── COMMAND REGISTRATION ──────────────────────────────────────────────────
-
+// CIL[END chunk_id="dev_module_header_1784071456"]
+// CIL[BEGIN chunk_id="dev_registerdevcommands_1784071456" type="function" identity="registerDevCommands" parent="none"]
+// CIL[DOC-MACRO purpose="Register dev command with CLI framework"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle dev server startup and file watching"]
+// CIL[DOC-CONTEXT module="dev-cli" layer="cli" 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="dev command registration" errors="process exit on failure" side_effects="starts processes, watches files"]
+// CIL[DOC-MICRO logic_summary="Orchestrates assembly, verification, and Vite server startup" 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/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 registerDevCommands(program: Command) {
   program
     .command('dev')
@@ -61,7 +63,7 @@ export function registerDevCommands(program: Command) {
       console.log('\n🚀 Starting Spine dev server...\n')
 
       try {
-        // Step 1: Assembly
+        
         console.log('📦 Step 1: Assembling v2-core + v2-custom...')
         const assemblyExitCode = await runCommand(
           'bash',
@@ -75,7 +77,7 @@ export function registerDevCommands(program: Command) {
         }
         console.log('✓ Assembly complete\n')
 
-        // Step 2: Integrity verification (unless skipped)
+        
         if (opts.verify !== false) {
           console.log('🔒 Step 2: Verifying core integrity...')
           const verifyExitCode = await runCommand(
@@ -93,7 +95,7 @@ export function registerDevCommands(program: Command) {
           console.log('⏭️  Step 2: Skipping integrity verification (--no-verify)\n')
         }
 
-        // Step 3: Start Vite
+        
         console.log(`🌐 Step 3: Starting Vite dev server on port ${opts.port}...`)
         console.log('   (Press Ctrl+C to stop)\n')
 
@@ -111,7 +113,7 @@ export function registerDevCommands(program: Command) {
           }
         )
 
-        // Step 4: Watch v2-custom for changes (unless disabled)
+        
         let watcher: ReturnType<typeof watch> | null = null
         if (opts.watch !== false) {
           const watchDelay = parseInt(opts.watchDelay) || 500
@@ -124,14 +126,14 @@ export function registerDevCommands(program: Command) {
             let reassemblyTimeout: NodeJS.Timeout | null = null
 
             watcher = watch(customDir, { recursive: true }, (eventType, filename) => {
-              // Ignore node_modules, .git, and temp files
+              
               if (!filename || filename.includes('node_modules') || filename.startsWith('.')) {
                 return
               }
 
               console.log(`\n📝 Change detected in v2-custom/${filename}`)
 
-              // Debounce reassembly
+              
               if (reassemblyTimeout) {
                 clearTimeout(reassemblyTimeout)
               }
@@ -162,7 +164,7 @@ export function registerDevCommands(program: Command) {
           process.exit(code || 0)
         })
 
-        // Handle Ctrl+C gracefully
+        
         process.on('SIGINT', () => {
           console.log('\n\n🛑 Shutting down dev server...')
           if (watcher) {
@@ -187,9 +189,21 @@ export function registerDevCommands(program: Command) {
       }
     })
 }
-
-// ─── HELPER ────────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="dev_registerdevcommands_1784071456"]
+// CIL[BEGIN chunk_id="dev_runcommand_1784071456" type="function" identity="runCommand" parent="none"]
+// CIL[DOC-MACRO purpose="Execute shell command with promise wrapper"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run external processes and return exit code"]
+// CIL[DOC-CONTEXT module="dev-cli" layer="cli" 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="Promise<number>" errors="process spawn errors" side_effects="spawns child process"]
+// CIL[DOC-MICRO logic_summary="Wraps spawn in Promise for async command execution" 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/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"]
 function runCommand(command: string, args: string[], cwd: string): Promise<number> {
   return new Promise((resolve, reject) => {
     const proc = spawn(command, args, {
@@ -207,17 +221,27 @@ function runCommand(command: string, args: string[], cwd: string): Promise<numbe
     })
   })
 }
-
-/**
- * Fast incremental reassembly of v2-custom files only.
- * Uses rsync if available, falls back to selective copy.
- */
+// CIL[END chunk_id="dev_runcommand_1784071456"]
+// CIL[BEGIN chunk_id="dev_fastreassemble_1784071456" type="function" identity="fastReassemble" parent="none"]
+// CIL[DOC-MACRO purpose="Fast reassembly of custom code during dev"]
+// CIL[DOC-RESPONSIBILITY responsibility="Sync custom source and functions to assembled dirs"]
+// CIL[DOC-CONTEXT module="dev-cli" layer="cli" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="file system errors" side_effects="copies files, creates directories"]
+// CIL[DOC-MICRO logic_summary="Uses rsync or manual copy to sync v2-custom changes" 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/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function fastReassemble(projectRoot: string): Promise<void> {
   const customDir = resolve(projectRoot, 'v2-custom')
   const srcDest = resolve(projectRoot, 'src/v2-assembled')
   const funcsDest = resolve(projectRoot, 'functions')
 
-  // Check if rsync is available
+  
   let hasRsync = false
   try {
     execSync('which rsync', { stdio: 'pipe' })
@@ -226,24 +250,24 @@ async function fastReassemble(projectRoot: string): Promise<void> {
     hasRsync = false
   }
 
-  // Reassemble custom frontend files
+  
   const customSrcDir = resolve(customDir, 'src')
   if (existsSync(customSrcDir)) {
     const destDir = srcDest
 
     if (hasRsync) {
-      // Use rsync for efficient incremental sync
+      
       execSync(
         `rsync -av --delete "${customSrcDir}/" "${destDir}/"`,
         { stdio: 'pipe', cwd: projectRoot }
       )
     } else {
-      // Fallback: copy files that have changed
+      
       copyChangedFiles(customSrcDir, destDir)
     }
   }
 
-  // Reassemble custom function files
+  
   const customFuncsDir = resolve(customDir, 'functions')
   if (existsSync(customFuncsDir)) {
     if (hasRsync) {
@@ -256,7 +280,7 @@ async function fastReassemble(projectRoot: string): Promise<void> {
     }
   }
 
-  // Reassemble spine.config.json to public directory
+  
   const spineConfigSrc = resolve(projectRoot, 'spine.config.json')
   const publicDest = resolve(srcDest, 'public')
   if (existsSync(spineConfigSrc)) {
@@ -275,11 +299,21 @@ async function fastReassemble(projectRoot: string): Promise<void> {
     }
   }
 }
-
-/**
- * Copy only files that have changed (mtime comparison).
- * Fallback when rsync is not available.
- */
+// CIL[END chunk_id="dev_fastreassemble_1784071456"]
+// CIL[BEGIN chunk_id="dev_copychangedfiles_1784071456" type="function" identity="copyChangedFiles" parent="none"]
+// CIL[DOC-MACRO purpose="Recursively copy changed files during reassembly"]
+// CIL[DOC-RESPONSIBILITY responsibility="Copy only modified files to avoid unnecessary work"]
+// CIL[DOC-CONTEXT module="dev-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="file system errors" side_effects="copies files, creates directories"]
+// CIL[DOC-MICRO logic_summary="Compares file mtimes and copies only newer files" 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"]
 function copyChangedFiles(src: string, dest: string): void {
   const files = readdirSync(src, { withFileTypes: true })
 
@@ -289,14 +323,14 @@ function copyChangedFiles(src: string, dest: string): void {
 
     if (entry.isDirectory()) {
       if (!existsSync(destPath)) {
-        // Create directory
+        
         const { mkdirSync } = require('fs')
         mkdirSync(destPath, { recursive: true })
       }
-      // Recurse
+      
       copyChangedFiles(srcPath, destPath)
     } else {
-      // Check if file needs copying
+      
       const srcStat = statSync(srcPath)
       let needsCopy = true
 
@@ -312,3 +346,4 @@ function copyChangedFiles(src: string, dest: string): void {
     }
   }
 }
+// CIL[END chunk_id="dev_copychangedfiles_1784071456"]