spine-framework 0.3.145 → 0.4.0

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

@@ -1,3 +1,15 @@
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Provides CLI commands for the development environment, facilitating process spawning and file watching."]
+// CIL[DOC-RESPONSIBILITY responsibility="Expose dev command utilities for developers to streamline application development workflow."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="[]" outputs="[]" errors="[]" side_effects="[]"]
+// CIL[DOC-MICRO logic_summary="Defines the dev module and its intent, invariant, and related modules." notable_decisions="Commands should only be executed in a valid development environment."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="internal"]
+
+
+
 
 
 
@@ -11,45 +23,102 @@
 
 
 
-// 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'
 import { fileURLToPath } from 'url'
 import { watch, existsSync, statSync, readdirSync } from 'fs'
 
+// CIL[DOC-VECTOR type="context" content="purpose='Provides CLI commands for the development environment, facilitating process spawning and file watching.'; 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/dev.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Resolves the current module's file URL to a filesystem path."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide a stable __filename reference for the module."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="[]" outputs="string" errors="[]" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Call fileURLToPath(import.meta.url) and assign to const __filename." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
+
 const __filename = fileURLToPath(import.meta.url)
+// CIL[DOC-VECTOR type="context" content="purpose='Resolves the current module's file URL to a filesystem path.'; 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/dev.ts:__filename:constant"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Provides the directory name of the current module for relative path resolution."]
+// CIL[DOC-RESPONSIBILITY responsibility="Derive the current module's directory from __filename."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="[]" outputs="string" errors="[]" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Call dirname(__filename) and assign to const __dirname." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
+
 const __dirname = dirname(__filename)
-const PROJECT_ROOT = resolve(__dirname, '../../../')
-// 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-VECTOR type="context" content="purpose='Provides the directory name of the current module for relative path resolution.'; 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/dev.ts:__dirname:constant"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:PROJECT_ROOT:constant" type="constant" identity="PROJECT_ROOT" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Defines the project root directory for relative path resolution."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide a resolved project root path for file operations."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="[]" outputs="string" errors="[]" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Resolve __dirname joined with '../../../' to produce PROJECT_ROOT." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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."]
+/**
+ * PROJECT_ROOT defines the root directory of the project, allowing for relative path resolution. It exists to facilitate file operations within the project structure.
+ *
+ * @sideEffects none
+ * @stability   stable
+ * @calls       resolve
+ * @cil-generated
+ */
+const PROJECT_ROOT = resolve(__dirname, '../../../')
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the project root directory for relative path resolution.'; 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/dev.ts:PROJECT_ROOT:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:registerDevCommands:function" type="function" identity="registerDevCommands" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Registers the 'dev' command for starting the Spine development server with options."]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure and launch the dev server with integrity verification and file watching."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="program: Command" outputs="Promise<void>" errors="Process exits on failure" side_effects="Executes shell commands, spawns a child process, and watches for file changes."]
+// CIL[DOC-MICRO logic_summary="Assemble v2 core and custom files, verify integrity unless skipped, spawn Vite server, and optionally watch v2-custom for changes with debounced reassembly." notable_decisions="Honors --no-verify, --port, --host, --no-watch, and --watch-delay options; ignores changes in node_modules and dotfiles; sets SPINE_DEV=true for the Vite process."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Registers development commands for starting the Spine development server with various options. It facilitates the assembly and verification of core components before launching the server.
+ *
+ * @macro       Command registration function for a CLI tool.
+ * @micro       Utilizes external scripts for assembly and integrity verification, followed by spawning a Vite server process.
+ * @inputSpec
+ *   program: Command (required) — The command program to register the dev commands with.
+ * @outputSpec  Promise<void>
+ * @sideEffects Executes shell commands, spawns a child process, and potentially modifies the file system through watching for changes.
+ * @stability   stable
+ * @calls       runCommand, spawn, watch, existsSync, resolve
+ * @errorHandling none
+ * @cil-generated
+ */
 export function registerDevCommands(program: Command) {
   program
     .command('dev')
@@ -189,21 +258,37 @@ export function registerDevCommands(program: Command) {
       }
     })
 }
-// 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="context" content="purpose='Registers the 'dev' command for starting the Spine development server with options.'; 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/dev.ts:registerDevCommands:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:runCommand:function" type="function" identity="runCommand" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Executes a shell command in a given working directory and returns its exit code."]
+// CIL[DOC-RESPONSIBILITY responsibility="Run a command as a child process and report its exit code."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="command: string, args: string[], cwd: string" outputs="Promise<number>" errors="Rejects on process error" side_effects="Spawns a child process with inherited stdio."]
+// CIL[DOC-MICRO logic_summary="Spawn the command with inherited stdio and environment, resolve with the exit code, reject on spawn error." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Executes a command in a specified directory and returns the exit code. This function is useful for running shell commands programmatically within the application.
+ *
+ * @macro       Command execution handler that returns the process exit code.
+ * @micro       Spawns a child process to run the command with inherited stdio and environment variables.
+ * @inputSpec
+ *   command: string (required) — the command to execute.
+ *   args: string[] (required) — an array of arguments for the command.
+ *   cwd: string (required) — the current working directory for the command.
+ * @outputSpec  Promise<number> — resolves with the exit code of the command.
+ * @sideEffects none
+ * @stability   stable
+ * @calls       spawn
+ * @cil-generated
+ */
 function runCommand(command: string, args: string[], cwd: string): Promise<number> {
   return new Promise((resolve, reject) => {
     const proc = spawn(command, args, {
@@ -221,21 +306,33 @@ function runCommand(command: string, args: string[], cwd: string): Promise<numbe
     })
   })
 }
-// 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="context" content="purpose='Executes a shell command in a given working directory and returns 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/dev.ts:runCommand:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:fastReassemble:function" type="function" identity="fastReassemble" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Synchronizes custom source and configuration files into assembled destinations."]
+// CIL[DOC-RESPONSIBILITY responsibility="Copy changed files from v2-custom to src/v2-assembled and functions, and update public spine.config.json."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="projectRoot: string" outputs="Promise<void>" errors="Throws on command or file system failure" side_effects="File I/O: copying, synchronizing, creating directories."]
+// CIL[DOC-MICRO logic_summary="Check for rsync; rsync or manually copy changed custom src and functions; conditionally copy spine.config.json if newer." notable_decisions="Prefers rsync when available; filters to changed files via mtime when rsync is absent; conditionally copies spine.config.json to src/v2-assembled/public."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The fastReassemble function synchronizes custom source files and configuration from a specified project root to designated destination directories. It ensures that the latest changes are reflected in the assembled output, using rsync if available for efficiency.
+ *
+ * @inputSpec
+ *   projectRoot: string (required) — the root directory of the project to reassemble.
+ * @outputSpec  Promise<void>
+ * @sideEffects file I/O operations including copying and synchronizing files, creating directories.
+ * @stability   stable
+ * @calls       execSync, existsSync, mkdirSync, statSync, copyFileSync, copyChangedFiles
+ * @cil-generated
+ */
 async function fastReassemble(projectRoot: string): Promise<void> {
   const customDir = resolve(projectRoot, 'v2-custom')
   const srcDest = resolve(projectRoot, 'src/v2-assembled')
@@ -299,21 +396,34 @@ async function fastReassemble(projectRoot: string): Promise<void> {
     }
   }
 }
-// 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="context" content="purpose='Synchronizes custom source and configuration files into assembled destinations.'; 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/dev.ts:fastReassemble:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/dev.ts:copyChangedFiles:function" type="function" identity="copyChangedFiles" parent="~/.framework/cli/commands/dev.ts"]
+// CIL[DOC-MACRO purpose="Copies files from source to destination only when modified."]
+// CIL[DOC-RESPONSIBILITY responsibility="Recursively mirror changed files while creating missing directories."]
+// CIL[DOC-CONTEXT module="dev" layer="app-specific" related_files=".framework/cli/commands/dev.ts"]
+// CIL[DOC-CONTRACT inputs="src: string, dest: string" outputs="void" errors="Throws on file system errors" side_effects="File I/O"]
+// CIL[DOC-MICRO logic_summary="Read source entries; for directories ensure destination and recurse; for files compare mtime and copy if newer." notable_decisions="Uses require('fs') for mkdirSync and copyFileSync inside the function; compares mtime to decide whether to copy."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Copies files from the source directory to the destination directory only if they have changed. This function ensures that only modified files are copied, optimizing the file transfer process.
+ *
+ * @inputSpec
+ *   src: string (required) — the source directory path.
+ *   dest: string (required) — the destination directory path.
+ * @outputSpec  void
+ * @sideEffects file I/O
+ * @stability   stable
+ * @calls       readdirSync, existsSync, mkdirSync, statSync, copyFileSync
+ * @cil-generated
+ */
 function copyChangedFiles(src: string, dest: string): void {
   const files = readdirSync(src, { withFileTypes: true })
 
@@ -346,4 +456,10 @@ function copyChangedFiles(src: string, dest: string): void {
     }
   }
 }
-// CIL[END chunk_id="dev_copychangedfiles_1784071456"]
+// CIL[DOC-VECTOR type="context" content="purpose='Copies files from source to destination only when modified.'; 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/dev.ts:copyChangedFiles:function"]