spine-framework 0.3.145 → 0.4.0

package/.framework/scripts/app-install-cli.ts

@@ -7,71 +7,157 @@
 
 
 
-// CIL[BEGIN chunk_id="app-install-cli_module_header_1783931090" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import Node.js modules for CLI app installation tool"]
-// CIL[DOC-RESPONSIBILITY responsibility="Manage all external module imports for CLI operations"]
-// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules and utilities" errors="Import failures" side_effects="Module loading"]
-// CIL[DOC-MICRO logic_summary="Imports file system, CLI, YAML validation, and ES modules utilities" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Module entry point for the app-install CLI tool"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import dependencies and expose the CLI script"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="loaded modules and configured execution environment" errors="none at import time" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Node.js fs, path, commander, js-yaml, ajv, and url helpers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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: .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.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"]
+// CIL[DOC-AUDIENCE audience="engineers using or extending the app install CLI"]
 import { readFileSync, existsSync, writeFileSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { program } from 'commander'
 import yaml from 'js-yaml'
 import Ajv from 'ajv'
 import { fileURLToPath } from 'url'
-// CIL[END chunk_id="app-install-cli_module_header_1783931090"]
-// CIL[BEGIN chunk_id="app-install-cli_setup_1783931090" type="setup" identity="setup" parent="none"]
-// CIL[DOC-MACRO purpose="Initialize CLI environment, schema validation, and type definitions"]
-// CIL[DOC-RESPONSIBILITY responsibility="Set up file paths, schema validator, and installation context"]
-// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Schema validator, file paths, context interface" errors="Schema loading failures" side_effects="File system reads"]
-// CIL[DOC-MICRO logic_summary="Resolves paths, loads schema, creates validator, defines context interface" notable_decisions="['schema_loading', 'ajv_validation']"]
-// 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: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/db.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='Module entry point for the app-install CLI tool'; 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/scripts/app-install-cli.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Declares and initializes the __filename constant for the CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value of __filename for use by the script"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="the __filename constant value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Assigns an initial value to the __filename constant" 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='Declares and initializes the __filename constant for the CLI'; 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/scripts/app-install-cli.ts:__filename:constant"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Declares and initializes the __dirname constant for the CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value of __dirname for use by the script"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="the __dirname constant value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Assigns an initial value to the __dirname constant" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const __dirname = dirname(__filename)
+// CIL[DOC-VECTOR type="context" content="purpose='Declares and initializes the __dirname constant for the CLI'; 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/scripts/app-install-cli.ts:__dirname:constant"]
 
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:schemaPath:constant" type="constant" identity="schemaPath" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Declares and initializes the schemaPath constant for the CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value of schemaPath for use by the script"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="the schemaPath constant value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Assigns an initial value to the schemaPath constant" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const schemaPath = resolve(__dirname, '../docs/app-installation/schema.json')
+// CIL[DOC-VECTOR type="context" content="purpose='Declares and initializes the schemaPath constant for the CLI'; 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/scripts/app-install-cli.ts:schemaPath:constant"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:schema:constant" type="constant" identity="schema" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Declares and initializes the schema constant for the CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value of schema for use by the script"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="the schema constant value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Assigns an initial value to the schema constant" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const schema = JSON.parse(readFileSync(schemaPath, 'utf8'))
+// CIL[DOC-VECTOR type="context" content="purpose='Declares and initializes the schema constant for the CLI'; 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/scripts/app-install-cli.ts:schema:constant"]
 
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:ajv:constant" type="constant" identity="ajv" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Declares and initializes the ajv constant for the CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value of ajv for use by the script"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="the ajv constant value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Assigns an initial value to the ajv constant" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const ajv = new Ajv()
+// CIL[DOC-VECTOR type="context" content="purpose='Declares and initializes the ajv constant for the CLI'; 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/scripts/app-install-cli.ts:ajv:constant"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:validate:constant" type="constant" identity="validate" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Declares and initializes the validate constant for the CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value of validate for use by the script"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="the validate constant value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Assigns an initial value to the validate constant" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const validate = ajv.compile(schema)
+// CIL[DOC-VECTOR type="context" content="purpose='Declares and initializes the validate constant for the CLI'; 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/scripts/app-install-cli.ts:validate:constant"]
 
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:InstallationContext:interface" type="interface" identity="InstallationContext" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Defines the TypeScript contract for InstallationContext"]
+// CIL[DOC-RESPONSIBILITY responsibility="Structural type definition used across the CLI"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="type definition for InstallationContext" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares the fields of the InstallationContext interface" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface InstallationContext {
   TARGET_ACCOUNT_ID?: string
   PACK_INSTALLATION_ID?: string
   [key: string]: string | undefined
 }
-// CIL[END chunk_id="app-install-cli_setup_1783931090"]
-// CIL[BEGIN chunk_id="app-install-cli_substitutevariables_1783931090" type="function" identity="substituteVariables" parent="none"]
-// CIL[DOC-MACRO purpose="Recursively substitute ${VAR} placeholders with context values"]
-// CIL[DOC-RESPONSIBILITY responsibility="Variable template substitution engine for installation configs"]
-// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="substituted object" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Handles strings, arrays, and objects recursively with regex replacement" notable_decisions="['recursive_substitution', 'fallback_to_match']"]
-// 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: 2. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, .framework/src/components/ui/table-primitives.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 2. Total affected: 2."]
-// 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='Defines the TypeScript contract for InstallationContext'; 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/scripts/app-install-cli.ts:InstallationContext:interface"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:substituteVariables:function" type="function" identity="substituteVariables" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Implements the substituteVariables function"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute the substituteVariables logic and return or exit"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="obj, context" outputs="return value or void" errors="may throw or exit on invalid input" side_effects="console output and file system access as applicable"]
+// CIL[DOC-MICRO logic_summary="Performs substituteVariables with validation and execution flow" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-PARAM name="obj" type="any" description="Parameter obj"]
+// CIL[DOC-PARAM name="context" type="InstallationContext" description="Parameter context"]
 function substituteVariables(obj: any, context: InstallationContext): any {
   if (typeof obj === 'string') {
     return obj.replace(/\$\{([^}]+)\}/g, (match, varName) => {
@@ -88,21 +174,22 @@ function substituteVariables(obj: any, context: InstallationContext): any {
   }
   return obj
 }
-// CIL[END chunk_id="app-install-cli_substitutevariables_1783931090"]
-// CIL[BEGIN chunk_id="app-install-cli_validateinstructionfile_1783931090" type="function" identity="validateInstructionFile" parent="none"]
-// CIL[DOC-MACRO purpose="Validate YAML instruction files against JSON schema"]
-// CIL[DOC-RESPONSIBILITY responsibility="Schema validation and file existence checking"]
-// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="validation result" errors="File not found, validation failures" side_effects="Console output, process.exit"]
-// CIL[DOC-MICRO logic_summary="Checks file existence, loads YAML, validates against schema, exits on failure" notable_decisions="['process_exit_on_failure', 'schema_validation']"]
-// 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: 1. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
-// 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='Implements the substituteVariables function'; 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/scripts/app-install-cli.ts:substituteVariables:function"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:validateInstructionFile:function" type="function" identity="validateInstructionFile" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Implements the validateInstructionFile function"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute the validateInstructionFile logic and return or exit"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="filePath" outputs="return value or void" errors="may throw or exit on invalid input" side_effects="console output and file system access as applicable"]
+// CIL[DOC-MICRO logic_summary="Performs validateInstructionFile with validation and execution flow" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-PARAM name="filePath" type="string" description="Parameter filePath"]
 async function validateInstructionFile(filePath: string): Promise<void> {
   try {
     console.log(`🔍 Validating ${filePath}...`)
@@ -127,21 +214,23 @@ async function validateInstructionFile(filePath: string): Promise<void> {
     process.exit(1)
   }
 }
-// CIL[END chunk_id="app-install-cli_validateinstructionfile_1783931090"]
-// CIL[BEGIN chunk_id="app-install-cli_executeinstallation_1783931090" type="function" identity="executeInstallation" parent="none"]
-// CIL[DOC-MACRO purpose="Execute multi-step app installation from instruction files"]
-// CIL[DOC-RESPONSIBILITY responsibility="Orchestrate complete app installation workflow"]
-// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="installation result" errors="Installation failures" side_effects="Console output, process.exit"]
-// CIL[DOC-MICRO logic_summary="Validates, sets context, simulates pack install, creates apps, runs migrations, verifies" notable_decisions="['simulated_installation', 'step_by_step_execution']"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, 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='Implements the validateInstructionFile function'; 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/scripts/app-install-cli.ts:validateInstructionFile:function"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:executeInstallation:function" type="function" identity="executeInstallation" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Implements the executeInstallation function"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute the executeInstallation logic and return or exit"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="filePath, options" outputs="return value or void" errors="may throw or exit on invalid input" side_effects="console output and file system access as applicable"]
+// CIL[DOC-MICRO logic_summary="Performs executeInstallation with validation and execution flow" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-PARAM name="filePath" type="string" description="Parameter filePath"]
+// CIL[DOC-PARAM name="options" type="any" description="Parameter options"]
 async function executeInstallation(filePath: string, options: any): Promise<void> {
   try {
     console.log(`🚀 Executing installation from ${filePath}...`)
@@ -210,21 +299,23 @@ async function executeInstallation(filePath: string, options: any): Promise<void
     process.exit(1)
   }
 }
-// CIL[END chunk_id="app-install-cli_executeinstallation_1783931090"]
-// CIL[BEGIN chunk_id="app-install-cli_generatetemplate_1783931090" type="function" identity="generateTemplate" parent="none"]
-// CIL[DOC-MACRO purpose="Generate YAML templates for app installations or migrations"]
-// CIL[DOC-RESPONSIBILITY responsibility="Template generation and file output management"]
-// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="template content" errors="Template loading failures" side_effects="File writes, console output"]
-// CIL[DOC-MICRO logic_summary="Resolves template paths, loads files, outputs to file or stdout" notable_decisions="['template_type_switching', 'output_option_handling']"]
-// 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: 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='Implements the executeInstallation function'; 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/scripts/app-install-cli.ts:executeInstallation:function"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:generateTemplate:function" type="function" identity="generateTemplate" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Implements the generateTemplate function"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute the generateTemplate logic and return or exit"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="type, options" outputs="return value or void" errors="may throw or exit on invalid input" side_effects="console output and file system access as applicable"]
+// CIL[DOC-MICRO logic_summary="Performs generateTemplate with validation and execution flow" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-PARAM name="type" type="string" description="Parameter type"]
+// CIL[DOC-PARAM name="options" type="any" description="Parameter options"]
 async function generateTemplate(type: string, options: any): Promise<void> {
   try {
     const templateDir = resolve(__dirname, '../docs/app-installation/templates')
@@ -255,21 +346,21 @@ async function generateTemplate(type: string, options: any): Promise<void> {
     process.exit(1)
   }
 }
-// CIL[END chunk_id="app-install-cli_generatetemplate_1783931090"]
-// CIL[BEGIN chunk_id="app-install-cli_cli_setup_1783931090" type="cli_setup" identity="cli_setup" parent="none"]
-// CIL[DOC-MACRO purpose="Define CLI commands and argument parsing"]
-// CIL[DOC-RESPONSIBILITY responsibility="Set up commander.js CLI interface with commands and options"]
-// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="CLI interface" errors="Command parsing errors" side_effects="CLI execution"]
-// CIL[DOC-MICRO logic_summary="Configures validate, install, and template commands with arguments and options" notable_decisions="['commander_setup', 'action_binding']"]
-// 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='Implements the generateTemplate function'; 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/scripts/app-install-cli.ts:generateTemplate:function"]
+// CIL[BEGIN stable_id="~/.framework/scripts/app-install-cli.ts:cli:variable" type="variable" identity="cli" parent="~/.framework/scripts/app-install-cli.ts"]
+// CIL[DOC-MACRO purpose="Configures the cli CLI program and its command wiring"]
+// CIL[DOC-RESPONSIBILITY responsibility="Wire commander commands to the appropriate action handlers"]
+// CIL[DOC-CONTEXT module=".framework/scripts" layer="script" related_files=".framework/scripts/app-install-cli.ts"]
+// CIL[DOC-CONTRACT inputs="command-line arguments" outputs="parsed command dispatch" errors="exits on unknown command or invalid arguments" side_effects="console output and invokes validate, install, or template handlers"]
+// CIL[DOC-MICRO logic_summary="Builds commander program with validate, install, and template commands" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 program
   .name('app-install-cli')
   .description('Spine App Installation CLI - Validate and execute app installation instructions')
@@ -297,4 +388,10 @@ program
   .action(generateTemplate)
 
 program.parse()
-// CIL[END chunk_id="app-install-cli_cli_setup_1783931090"]
+// CIL[DOC-VECTOR type="context" content="purpose='Configures the cli CLI program and its command wiring'; 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/scripts/app-install-cli.ts:cli:variable"]

package/.framework/scripts/assemble-frontend.sh

@@ -1,89 +1,172 @@
 #!/usr/bin/env bash
 
-# Frontend Assembly - Merge .framework/src + custom/apps/*/src → .assembled/src
+# CIL[BEGIN stable_id="~/.framework/scripts/assemble-frontend.sh:module:script" type="script" identity="assemble-frontend" parent="~/.framework/scripts/assemble-frontend.sh"]
+# CIL[DOC-MACRO purpose="Assemble .framework/src base layer + each custom app under .assembled/src/<app-slug>/ and merge public assets with collision detection, for the Vite build."]
+# CIL[DOC-RESPONSIBILITY responsibility="Stage core src, per-app dirs (verbatim, no basename flattening), index.html path fix, _redirects, and public assets; then mtime-preserving rsync into .assembled/src and public/."]
+# CIL[DOC-CONTEXT module="assembly" layer="build" related_files="scripts/assemble-functions.sh,scripts/assemble.sh,config/vite.config.ts,.framework/src/components/CustomAppLoader.tsx"]
+# CIL[DOC-CONTRACT inputs=".framework/src,.framework/public,custom/apps/*,spine.config.json; env SPINE_PROJECT_ROOT (fixture override for tests)" outputs=".assembled/src + merged public/; exit 1 on public-path collision" errors="hard error naming both sources when two public assets share a relative path with different content" side_effects="rewrites .assembled/src and public/"]
+# CIL[DOC-MICRO logic_summary="Temp-dir staging → core copy → per-app rsync with excludes (functions/seed/public/node_modules/dist/dotfiles) → public manifest-tracked collision check → rsync -rlc (no -t) publish." notable_decisions="identical duplicate public assets skip silently; root spine.config.json wins over framework template; no .gitkeep rsync exclude so --delete can remove stale dirs"]
+# CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+# CIL[DOC-STABILITY stability="stable"]
+# CIL[DOC-NOTE type="invariant" content="import.meta.glob('../../../custom/apps/*/index.tsx') in CustomAppLoader must keep resolving — app dirs are copied verbatim under src/<slug>/, never flattened by basename."]
+# CIL[END stable_id="~/.framework/scripts/assemble-frontend.sh:module:script"]
+
+# Frontend Assembly - Merge .framework/src + custom/apps/* → .assembled/src
 #
 # Purpose: Create unified frontend source directory for Vite build process.
-# - .framework/src is the canonical Spine frontend
-# - custom/apps/*/src are your application sources
-# - Vite expects a single src directory, so we assemble at build time
+# - .framework/src is the canonical Spine frontend (base layer at root)
+# - each custom/apps/<app> is copied to .assembled/src/<app-slug>/ VERBATIM —
+#   no basename flattening (two apps' components/ must never merge silently)
+# - custom app index resolution uses import.meta.glob('../../../custom/apps/*/index.tsx')
+#   in .framework/src/components/CustomAppLoader.tsx — assembled app dirs exist
+#   for @/(@core)-style imports and layout consistency, not for the glob
 #
 # Process:
-# 1. Clean target directory
-# 2. Copy core src files
-# 3. Overlay custom src files (overwrites existing)
+# 1. Assemble into temp directory first
+# 2. Copy core src files (base layer)
+# 3. Copy each app to <app-slug>/, excluding functions/, seed/, public/,
+#    node_modules, dist, and dotfiles
+# 4. Merge public assets with same-relative-path collision detection
+# 5. rsync -c into target so unchanged files keep their mtimes — Vite then only
+#    reloads modules that actually changed instead of every file
+#
+# SPINE_PROJECT_ROOT (optional): override the project root — used by the
+# fixture-based unit tests; production use leaves it unset.
 #
-# Dependencies: standard bash utilities, find, cp, rsync
+# Dependencies: standard bash utilities, find, cp, rsync, cmp
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+# Canonicalize (-P resolves symlinks) — consistent with assemble-functions.sh
+# and safe when the repo itself is reached through a symlinked path.
+PROJECT_ROOT="$(cd "${SPINE_PROJECT_ROOT:-$(dirname "$SCRIPT_DIR")}" && pwd -P)"
 
 CORE_SRC_DIR="$PROJECT_ROOT/.framework/src"
 CUSTOM_SRC_DIR="$PROJECT_ROOT/custom/apps"
 TARGET_SRC_DIR="$PROJECT_ROOT/.assembled/src"
+VITE_PUBLIC_DIR="$PROJECT_ROOT/public"
+TMP_ROOT="$PROJECT_ROOT/.frontend-assemble-tmp"
+TMP_SRC_DIR="$TMP_ROOT/src"
+TMP_PUBLIC_DIR="$TMP_ROOT/public"
+# rel-path → source-file map for public-asset collision errors
+PUBLIC_MANIFEST="$TMP_ROOT/public-manifest.tsv"
 
 echo "🔧 Assembling frontend → $TARGET_SRC_DIR"
 
-# 1. Clean target (except .gitkeep if exists)
-if [ -d "$TARGET_SRC_DIR" ]; then
-  find "$TARGET_SRC_DIR" -mindepth 1 -not -name '.gitkeep' -delete 2>/dev/null || true
-else
-  mkdir -p "$TARGET_SRC_DIR"
-fi
+# 1. Stage into temp dir
+rm -rf "$TMP_ROOT"
+mkdir -p "$TMP_SRC_DIR" "$TMP_PUBLIC_DIR"
+: > "$PUBLIC_MANIFEST"
 
 # 2. Copy core src (base layer)
 if [ -d "$CORE_SRC_DIR" ]; then
-  # Ensure subdirectories are copied properly
-  cp -r "$CORE_SRC_DIR"/* "$TARGET_SRC_DIR"/ 2>/dev/null || true
+  cp -r "$CORE_SRC_DIR"/* "$TMP_SRC_DIR"/ 2>/dev/null || true
   echo "  ✓ Core: $(find "$CORE_SRC_DIR" -name '*.tsx' -o -name '*.ts' -o -name '*.css' | wc -l | tr -d ' ') files"
 else
   echo "  ⚠ Core: $CORE_SRC_DIR not found"
 fi
 
-# 4. Copy public files from .framework
+# 3. Copy index.html, fixing the script src path for assembled structure
 if [ -f "$PROJECT_ROOT/.framework/index.html" ]; then
-  # Copy and fix the script src path for assembled structure
-  sed 's|/src/main.tsx|./main.tsx|g' "$PROJECT_ROOT/.framework/index.html" > "$TARGET_SRC_DIR/index.html"
+  sed 's|/src/main.tsx|./main.tsx|g' "$PROJECT_ROOT/.framework/index.html" > "$TMP_SRC_DIR/index.html"
   echo "  ✓ Core: index.html (paths fixed)"
 fi
 
-# 3. Copy public assets from .framework
-# Vite's publicDir is set to PROJECT_ROOT/public (i.e. ../public relative to .assembled/src)
-# so static files must go there to be served at the root URL
-VITE_PUBLIC_DIR="$PROJECT_ROOT/public"
+# 4. Stage a public-asset source dir into TMP_PUBLIC_DIR with collision
+# detection. The SAME relative path may never come from two different sources:
+# - identical content → skip silently (duplicate copy is harmless)
+# - differing content → hard error naming both source files
+stage_public_dir() {
+  local src_dir="$1"
+  local f rel staged prev
+  while IFS= read -r -d '' f; do
+    rel="${f#"$src_dir"/}"
+    staged="$TMP_PUBLIC_DIR/$rel"
+    if [ -e "$staged" ]; then
+      if cmp -s "$f" "$staged"; then
+        continue
+      fi
+      prev="$(awk -F '\t' -v r="$rel" '$1 == r { print $2; exit }' "$PUBLIC_MANIFEST")"
+      echo "  ✗ Public asset collision: '$rel' is provided by both" >&2
+      echo "      - $prev" >&2
+      echo "      - $f" >&2
+      echo "    Rename one of them — public/ merges flat, last-wins is forbidden." >&2
+      exit 1
+    fi
+    mkdir -p "$(dirname "$staged")"
+    cp "$f" "$staged"
+    printf '%s\t%s\n' "$rel" "$f" >> "$PUBLIC_MANIFEST"
+  done < <(find "$src_dir" -type f ! -name '.*' -print0 | sort -z)
+}
+
+# 5. Framework public assets merge first — Vite's publicDir is
+# PROJECT_ROOT/public, so static files must land there to be served at root URL
 if [ -d "$PROJECT_ROOT/.framework/public" ]; then
-  mkdir -p "$VITE_PUBLIC_DIR"
-  cp -r "$PROJECT_ROOT/.framework/public"/* "$VITE_PUBLIC_DIR/" 2>/dev/null || true
+  stage_public_dir "$PROJECT_ROOT/.framework/public"
   echo "  ✓ Core: $(find "$PROJECT_ROOT/.framework/public" -type f | wc -l | tr -d ' ') public files"
 fi
 
-# 3.5. Copy _redirects to Vite-served root for Netlify dev (served from .assembled/src root)
+# 6. Copy _redirects to Vite-served root for Netlify dev (served from .assembled/src root)
 if [ -f "$PROJECT_ROOT/.framework/public/_redirects" ]; then
-  cp "$PROJECT_ROOT/.framework/public/_redirects" "$TARGET_SRC_DIR/_redirects"
+  cp "$PROJECT_ROOT/.framework/public/_redirects" "$TMP_SRC_DIR/_redirects"
   echo "  ✓ Core: _redirects copied to Vite-served directory for Netlify dev"
 fi
 
-# 3.6. Copy spine.config.json to Vite publicDir so it's served at /spine.config.json
+# 7. Per-app copy: custom/apps/<app> → .assembled/src/<app-slug>/ verbatim.
+# Excluded: functions (goes to .assembled/netlify/functions), seed, public
+# (merged into /public above), node_modules, dist, dotfiles.
+CUSTOM_COUNT=0
+if [ -d "$CUSTOM_SRC_DIR" ]; then
+  for app_dir in "$CUSTOM_SRC_DIR"/*/; do
+    [ -d "$app_dir" ] || continue
+    slug="$(basename "$app_dir")"
+
+    rsync -a \
+      --exclude='functions' \
+      --exclude='seed' \
+      --exclude='public' \
+      --exclude='node_modules' \
+      --exclude='dist' \
+      --exclude='.*' \
+      "$app_dir" "$TMP_SRC_DIR/$slug/"
+
+    # App public assets merge into /public AFTER framework public; a same
+    # relative path in two sources (or vs framework) is a hard error above.
+    if [ -d "$app_dir/public" ]; then
+      stage_public_dir "$app_dir/public"
+    fi
+
+    app_count=$(find "$TMP_SRC_DIR/$slug" -name '*.tsx' -o -name '*.ts' -o -name '*.css' 2>/dev/null | wc -l | tr -d ' ')
+    CUSTOM_COUNT=$((CUSTOM_COUNT + app_count))
+    echo "  ✓ $slug: $app_count files → src/$slug/"
+  done
+fi
+if [ "$CUSTOM_COUNT" -eq 0 ]; then
+  echo "  ○ Custom: (empty)"
+fi
+
+# 8. spine.config.json → staged public (root config, served at /spine.config.json).
+# The ROOT copy is the instance config and intentionally wins over the
+# framework template of the same name (framework/public/spine.config.json).
 if [ -f "$PROJECT_ROOT/spine.config.json" ]; then
-  mkdir -p "$VITE_PUBLIC_DIR"
-  cp "$PROJECT_ROOT/spine.config.json" "$VITE_PUBLIC_DIR/spine.config.json"
+  cp -f "$PROJECT_ROOT/spine.config.json" "$TMP_PUBLIC_DIR/spine.config.json"
   echo "  ✓ Config: spine.config.json copied to public/"
 fi
 
-# 6. Overlay custom src (overrides + additions)
-if [ -d "$CUSTOM_SRC_DIR" ]; then
-  # Copy files and subdirectories
-  cp -r "$CUSTOM_SRC_DIR"/* "$TARGET_SRC_DIR"/ 2>/dev/null || true
-  
-  # Handle subdirectories properly
-  find "$CUSTOM_SRC_DIR" -mindepth 1 -type d -exec sh -c 'dir="$1"; base=$(basename "$dir"); mkdir -p "'"$TARGET_SRC_DIR"'/$base" && cp -r "$dir"/* "'"$TARGET_SRC_DIR"'/$base/"' _ {} \; 2>/dev/null || true
-  
-  CUSTOM_COUNT=$(find "$CUSTOM_SRC_DIR" -name '*.tsx' -o -name '*.ts' -o -name '*.css' 2>/dev/null | wc -l | tr -d ' ')
-  echo "  ✓ Custom: $CUSTOM_COUNT files"
-else
-  echo "  ○ Custom: (empty)"
-fi
+# 9. Publish staged public assets. -c compares content checksums; deliberately
+# NO -t so unchanged files keep mtimes (see final sync note below).
+mkdir -p "$VITE_PUBLIC_DIR"
+rsync -rlc "$TMP_PUBLIC_DIR"/ "$VITE_PUBLIC_DIR"/
+
+# 10. Sync temp into place. -c compares content checksums; deliberately NO -t —
+# otherwise rsync "corrects" mtimes of unchanged files to the fresh temp-copy
+# time and Vite reloads the entire module graph on every assemble.
+mkdir -p "$TARGET_SRC_DIR"
+# No .gitkeep exclusion: .assembled/ is gitignored, and leftover .gitkeep
+# files inside stale dirs would make --delete treat them as non-empty.
+rsync -rlc --delete "$TMP_SRC_DIR"/ "$TARGET_SRC_DIR"/
+rm -rf "$TMP_ROOT"
 
 echo "  ✓ Assembled: $(find "$TARGET_SRC_DIR" -name '*.tsx' -o -name '*.ts' -o -name '*.css' | wc -l | tr -d ' ') total files"
 echo "✅ Done"