spine-framework 0.3.144 → 0.4.0

package/.framework/functions/_shared/app-manifest.ts

@@ -1,26 +1,37 @@
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Shared manifest loader for Spine apps"]
+// CIL[DOC-RESPONSIBILITY responsibility="Defines AppManifest and NavItem interfaces and provides manifest loading, caching, merging, and discovery helpers"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Module-level entry point; no runtime logic" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developers"]
 
 
 
 
 
-// CIL[BEGIN chunk_id="app-manifest_moduleheader_1784066609" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="App manifest loading and management"]
-// CIL[DOC-RESPONSIBILITY responsibility="Load and merge app configuration manifests"]
-// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="manifest utilities" errors="none" side_effects="file system access"]
-// CIL[DOC-MICRO logic_summary="Defines AppManifest, NavItem interfaces and manifest cache" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/RolesPage.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."]
+
+import { readFileSync, realpathSync, readdirSync, statSync } from 'fs'
+import { resolve, join, sep } from 'path'
+// CIL[DOC-VECTOR type="context" content="purpose='Shared manifest loader for Spine apps'; 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"]
-import { readFileSync } from 'fs'
-import { resolve } from 'path'
+// CIL[END stable_id="~/.framework/functions/_shared/app-manifest.ts:module_header:module_header"]
 
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:AppManifest:interface" type="interface" identity="AppManifest" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Describes the runtime configuration shape of a Spine app manifest"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the AppManifest type fields used by loaders and renderers"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AppManifest type definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Optional and required fields for app metadata, routing, roles, and domains" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface AppManifest {
   name: string
   slug: string
@@ -39,7 +50,23 @@ export interface AppManifest {
   preview_domain?: string
   prod_domain?: string
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Describes the runtime configuration shape of a Spine app manifest'; 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/functions/_shared/app-manifest.ts:AppManifest:interface"]
 
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:NavItem:interface" type="interface" identity="NavItem" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Describes the shape of a navigation item in an app manifest"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the NavItem type used for app navigation trees"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="NavItem type definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Title, path, icon, order, and optional nested children" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface NavItem {
   title: string
   path: string
@@ -47,108 +74,169 @@ export interface NavItem {
   order?: number
   children?: NavItem[]
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Describes the shape of a navigation item in an app manifest'; 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/functions/_shared/app-manifest.ts:NavItem:interface"]
+
+
+
+
+
 
-const manifestCache = new Map<string, AppManifest>()
 
-// CIL[END chunk_id="app-manifest_moduleheader_1784066609"]
-// CIL[BEGIN chunk_id="app-manifest_loadmanifest_1784066609" type="function" identity="loadManifest" parent="none"]
-// CIL[DOC-MACRO purpose="Load app manifest from file"]
-// CIL[DOC-RESPONSIBILITY responsibility="Read and parse manifest JSON with caching"]
-// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\"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="AppManifest or null" errors="file system errors" side_effects="file reads"]
-// CIL[DOC-MICRO logic_summary="Loads manifest from disk with validation and caching" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:manifestCache:constant" type="constant" identity="manifestCache" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Cache loaded manifests by file path to avoid repeated disk reads"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold in-memory Map of manifest paths to AppManifest objects"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="canonical manifest path string key" outputs="AppManifest or undefined" errors="none" side_effects="Cache state is mutable module state"]
+// CIL[DOC-MICRO logic_summary="Instantiated once at module load; keyed by canonical manifest path" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: 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."]
+const manifestCache = new Map<string, AppManifest>()
+// CIL[DOC-VECTOR type="context" content="purpose='Cache loaded manifests by file path to avoid repeated disk reads'; 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"]
-export function loadManifest(manifestPath: string): AppManifest | null {
-  if (manifestCache.has(manifestPath)) {
-    return manifestCache.get(manifestPath)!
-  }
+// CIL[END stable_id="~/.framework/functions/_shared/app-manifest.ts:manifestCache:constant"]
 
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:loadManifest:function" type="function" identity="loadManifest" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Read, parse, and cache a Spine app manifest JSON file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load manifest from disk, validate required fields, cache, and return it"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="manifestPath: relative or absolute path to manifest JSON, projectRoot: optional root (defaults to REPO_PATH or cwd)" outputs="AppManifest or null" errors="Returns null on path escapes, missing or invalid fields, or read/parse errors and logs to console" side_effects="Reads from filesystem and updates manifestCache keyed by canonical path"]
+// CIL[DOC-MICRO logic_summary="Canonicalizes project root and manifest path with realpathSync, rejects lexical or symlink escapes, parses JSON, validates object shape, nonempty name, slug charset, and required_roles array, then caches by canonical path" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+export function loadManifest(
+  manifestPath: string,
+  projectRoot: string = resolve(process.env.REPO_PATH || process.cwd())
+): AppManifest | null {
   try {
-    const projectRoot = resolve(__dirname, '../../../..')
-    const fullPath = resolve(projectRoot, manifestPath)
-    
-    const content = readFileSync(fullPath, 'utf-8')
+    const root = realpathSync(resolve(projectRoot))
+    const lexical = resolve(root, manifestPath)
+    if (lexical !== root && !lexical.startsWith(root + sep)) {
+      console.error(`[app-manifest] Manifest path escapes project root: ${manifestPath}`)
+      return null
+    }
+    const canonical = realpathSync(lexical)
+    if (canonical !== root && !canonical.startsWith(root + sep)) {
+      console.error(`[app-manifest] Manifest resolves outside project root: ${manifestPath}`)
+      return null
+    }
+
+    if (manifestCache.has(canonical)) {
+      return manifestCache.get(canonical)!
+    }
+
+    const content = readFileSync(canonical, 'utf-8')
     const manifest: AppManifest = JSON.parse(content)
-    
-    if (!manifest.slug || !manifest.name) {
-      console.error(`[app-manifest] Invalid manifest at ${manifestPath}: missing slug or name`)
+
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+      console.error(`[app-manifest] Invalid manifest at ${manifestPath}: root must be an object`)
+      return null
+    }
+
+    if (typeof manifest.name !== 'string' || !manifest.name.trim()) {
+      console.error(`[app-manifest] Invalid manifest at ${manifestPath}: missing name`)
+      return null
+    }
+
+    if (typeof manifest.slug !== 'string' || !/^[a-z][a-z0-9-]*$/.test(manifest.slug)) {
+      console.error(`[app-manifest] Invalid manifest at ${manifestPath}: missing or invalid slug`)
       return null
     }
-    
-    if (!manifest.required_roles) {
+
+    if (manifest.required_roles === undefined || manifest.required_roles === null) {
       manifest.required_roles = []
+    } else if (!Array.isArray(manifest.required_roles) || manifest.required_roles.some((r) => typeof r !== 'string' || !r.trim())) {
+      console.error(`[app-manifest] Invalid manifest at ${manifestPath}: required_roles must be an array of nonempty strings`)
+      return null
     }
-    
-    manifestCache.set(manifestPath, manifest)
-    
+
+    manifestCache.set(canonical, manifest)
+
     return manifest
   } catch (err) {
     console.error(`[app-manifest] Failed to load ${manifestPath}:`, err)
     return null
   }
 }
-// CIL[END chunk_id="app-manifest_loadmanifest_1784066609"]
-// CIL[BEGIN chunk_id="app-manifest_clearmanifestcache_1784066609" type="function" identity="clearManifestCache" parent="none"]
-// CIL[DOC-MACRO purpose="Clear manifest cache"]
-// CIL[DOC-RESPONSIBILITY responsibility="Reset cached manifest data"]
-// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="none" side_effects="cache clearing"]
-// CIL[DOC-MICRO logic_summary="Clears all cached manifest entries" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Read, parse, and cache a Spine app manifest JSON file'; 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/functions/_shared/app-manifest.ts:loadManifest:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:clearManifestCache:function" type="function" identity="clearManifestCache" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Clear the manifest cache"]
+// CIL[DOC-RESPONSIBILITY responsibility="Reset the manifestCache Map"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="none" side_effects="Empties manifestCache"]
+// CIL[DOC-MICRO logic_summary="Calls Map.clear on the module-level cache" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function clearManifestCache(): void {
   manifestCache.clear()
 }
-// CIL[END chunk_id="app-manifest_clearmanifestcache_1784066609"]
-// CIL[BEGIN chunk_id="app-manifest_mergewithmanifest_1784066609" type="function" identity="mergeWithManifest" parent="none"]
-// CIL[DOC-MACRO purpose="Merge database record with manifest"]
-// CIL[DOC-RESPONSIBILITY responsibility="Combine DB and manifest configuration"]
-// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="merged record" errors="manifest load errors" side_effects="file reads"]
-// CIL[DOC-MICRO logic_summary="Merges database record with manifest file data" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/IntegrationsPage.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='Clear the manifest cache'; 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/functions/_shared/app-manifest.ts:clearManifestCache:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:mergeWithManifest:function" type="function" identity="mergeWithManifest" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Merge a database app record with its manifest file values"]
+// CIL[DOC-RESPONSIBILITY responsibility="When config_source is manifest, load and overlay manifest fields onto the database record"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="dbRecord: any database app row object" outputs="merged app object or null" errors="Falls back to database record if manifest missing or invalid, logging a warning" side_effects="Calls loadManifest which may read from disk and cache"]
+// CIL[DOC-MICRO logic_summary="Returns DB-derived fallback when no manifest config, preserving an existing required_roles array and deriving from min_role only when absent; otherwise loads manifest and overlays manifest-authoritative fields on the full DB record" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function mergeWithManifest(dbRecord: any): any {
   if (!dbRecord) return null
-  
+
+  const fallbackRoles = Array.isArray(dbRecord.required_roles)
+    ? dbRecord.required_roles
+    : dbRecord.min_role ? [dbRecord.min_role] : []
+
   if (!dbRecord.manifest_path || dbRecord.config_source !== 'manifest') {
     return {
       ...dbRecord,
-      required_roles: dbRecord.min_role ? [dbRecord.min_role] : [],
+      required_roles: fallbackRoles,
       _source: 'database'
     }
   }
-  
+
   const manifest = loadManifest(dbRecord.manifest_path)
   if (!manifest) {
     console.warn(`[app-manifest] Could not load manifest for ${dbRecord.slug}, falling back to DB`)
     return {
       ...dbRecord,
-      required_roles: dbRecord.min_role ? [dbRecord.min_role] : [],
+      required_roles: fallbackRoles,
       _source: 'database (manifest missing)'
     }
   }
-  
+
   return {
+    ...dbRecord,
     id: dbRecord.id,
     slug: manifest.slug,
     name: manifest.name,
@@ -171,25 +259,57 @@ export function mergeWithManifest(dbRecord: any): any {
     _manifest_path: dbRecord.manifest_path
   }
 }
-// CIL[END chunk_id="app-manifest_mergewithmanifest_1784066609"]
-// CIL[BEGIN chunk_id="app-manifest_discovermanifests_1784066609" type="function" identity="discoverManifests" parent="none"]
-// CIL[DOC-MACRO purpose="Discover available app manifests"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return list of known manifest paths"]
-// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="manifest list" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Returns hardcoded list of app manifest locations" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. 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='Merge a database app record with its manifest file values'; 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"]
-export function discoverManifests(): Array<{slug: string, path: string}> {
-  return [
-    { slug: 'cortex', path: 'custom/apps/cortex/manifest.json' },
-    { slug: 'customer-portal', path: 'custom/apps/customer-portal/manifest.json' }
-  ]
+// CIL[END stable_id="~/.framework/functions/_shared/app-manifest.ts:mergeWithManifest:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/app-manifest.ts:discoverManifests:function" type="function" identity="discoverManifests" parent="~/.framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-MACRO purpose="Discover app manifests by enumerating custom/apps directories"]
+// CIL[DOC-RESPONSIBILITY responsibility="Enumerate custom/apps children, load and validate each manifest, and return slug/path entries for directories whose name matches the manifest slug"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="projectRoot?: string defaults to REPO_PATH or cwd" outputs="Array of {slug, path} objects sorted lexically by directory name" errors="Returns [] when custom/apps is absent or unreadable" side_effects="Reads the filesystem and may populate the manifest cache"]
+// CIL[DOC-MICRO logic_summary="Canonicalizes the project root, lists custom/apps entries sorted lexically, skips non-directories and external symlink escapes via loadManifest containment, and keeps entries whose directory name equals the validated manifest slug" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+export function discoverManifests(
+  projectRoot: string = resolve(process.env.REPO_PATH || process.cwd())
+): Array<{slug: string, path: string}> {
+  try {
+    const root = realpathSync(resolve(projectRoot))
+    const appsDir = join(root, 'custom', 'apps')
+    const names = readdirSync(appsDir, { withFileTypes: true })
+      .map((d) => d.name)
+      .sort()
+
+    const found: Array<{slug: string, path: string}> = []
+    for (const name of names) {
+      const dirPath = join(appsDir, name)
+      let isDir = false
+      try {
+        isDir = statSync(dirPath).isDirectory()
+      } catch {
+        continue
+      }
+      if (!isDir) continue
+
+      const rel = `custom/apps/${name}/manifest.json`
+      const manifest = loadManifest(rel, root)
+      if (!manifest || manifest.slug !== name) continue
+      found.push({ slug: manifest.slug, path: rel })
+    }
+    return found
+  } catch {
+    return []
+  }
 }
-// CIL[END chunk_id="app-manifest_discovermanifests_1784066609"]
+// CIL[DOC-VECTOR type="context" content="purpose='Discover app manifests by enumerating custom/apps directories'; 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/functions/_shared/app-manifest.ts:discoverManifests:function"]

package/.framework/functions/_shared/ast.ts

@@ -0,0 +1,214 @@
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/ast.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/ast.ts"]
+// CIL[DOC-MACRO purpose="Provides the TypeScript compiler API import for AST identity extraction"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the typescript dependency and serve as the module-level CIL header"]
+// CIL[DOC-CONTEXT module=".framework/functions/_shared/ast.ts" layer="shared" related_files=".framework/functions/_shared/ast.ts"]
+// CIL[DOC-CONTRACT inputs="" outputs="" errors="" side_effects=""]
+// CIL[DOC-MICRO logic_summary="Imports the entire typescript namespace as ts"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+// CIL[DOC-AUDIENCE audience="cil pipeline"]
+import * as ts from 'typescript'
+// CIL[DOC-VECTOR type="context" content="purpose='Provides the TypeScript compiler API import for AST identity extraction'; 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/functions/_shared/ast.ts:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/ast.ts:IdentityProposal:interface" type="interface" identity="IdentityProposal" parent="~/.framework/functions/_shared/ast.ts"]
+// CIL[DOC-MACRO purpose="Defines the shape of an extracted code identity proposal"]
+// CIL[DOC-RESPONSIBILITY responsibility="Model an identity proposal with identity, type, parent, line range and text"]
+// CIL[DOC-CONTEXT module=".framework/functions/_shared/ast.ts" layer="shared" related_files=".framework/functions/_shared/ast.ts"]
+// CIL[DOC-CONTRACT inputs="none (structural interface)" outputs="none (structural interface)" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Simple TypeScript interface describing a proposed chunk identity"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+export interface IdentityProposal {
+  identity: string
+  type: string
+  parent: string
+  line_start: number
+  line_end: number
+  text: string
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the shape of an extracted code identity proposal'; 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/functions/_shared/ast.ts:IdentityProposal:interface"]
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/ast.ts:isCapitalized:function" type="function" identity="isCapitalized" parent="~/.framework/functions/_shared/ast.ts"]
+// CIL[DOC-MACRO purpose="Check whether a string begins with an uppercase letter"]
+  // CIL[DOC-STABILITY stability="internal"]
+  // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+  // CIL[DOC-CONTEXT module="ast" layer="functions" related_files=".framework/functions/_shared/ast.ts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Determine capitalization of an identifier to classify React components"]
+// CIL[DOC-CONTRACT inputs="name: string" outputs="boolean" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns true when the first character is the same as its uppercase form"]
+function isCapitalized(name: string): boolean {
+  return name.length > 0 && name[0] === name[0].toUpperCase()
+}
+// CIL[END stable_id="~/.framework/functions/_shared/ast.ts:isCapitalized:function"]
+
+
+// CIL[DOC-VECTOR type="context" content="purpose='Check whether a string begins with an uppercase letter'; 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[BEGIN stable_id="~/.framework/functions/_shared/ast.ts:isHook:function" type="function" identity="isHook" parent="~/.framework/functions/_shared/ast.ts"]
+// CIL[DOC-MACRO purpose="Validation function for identifying React Hook names"]
+// CIL[DOC-RESPONSIBILITY responsibility="Decide if a string is a valid React hook name by convention"]
+// CIL[DOC-CONTEXT module=".framework/functions/_shared/ast.ts" layer="shared" related_files=".framework/functions/_shared/ast.ts"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-CONTRACT inputs="name: string" outputs="boolean" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks if the name starts with 'use', has length greater than 3, and the fourth character is uppercase"]
+// CIL[DOC-STABILITY stable]
+function isHook(name: string): boolean {
+  return name.startsWith('use') && name.length > 3 && name[3] === name[3].toUpperCase()
+}
+// CIL[END stable_id="~/.framework/functions/_shared/ast.ts:isHook:function"]
+// CIL[DOC-VECTOR type="context" content="purpose='Validation function for identifying React Hook names'; 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[BEGIN stable_id="~/.framework/functions/_shared/ast.ts:lineOf:function" type="function" identity="lineOf" parent="~/.framework/functions/_shared/ast.ts"]
+// CIL[DOC-MACRO purpose="Compute the 1-based line number of a TypeScript AST node"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert a node's start position to a human-readable line number"]
+// CIL[DOC-CONTEXT module=".framework/functions/_shared/ast.ts" layer="shared" related_files=".framework/functions/_shared/ast.ts"]
+// CIL[DOC-CONTRACT inputs="sourceFile: ts.SourceFile, node: ts.Node" outputs="number" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses sourceFile.getLineAndCharacterOfPosition and adds 1"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+function lineOf(sourceFile: ts.SourceFile, node: ts.Node): number {
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Compute the 1-based line number of a TypeScript AST node'; 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/functions/_shared/ast.ts:lineOf:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/ast.ts:extractIdentities:function" type="function" identity="extractIdentities" parent="~/.framework/functions/_shared/ast.ts"]
+// CIL[DOC-MACRO purpose="Extract candidate code identities from a TypeScript source file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Walk the TypeScript AST and build a list of IdentityProposal objects for CIL chunking"]
+// CIL[DOC-CONTEXT module=".framework/functions/_shared/ast.ts" layer="shared" related_files=".framework/functions/_shared/ast.ts"]
+// CIL[DOC-CONTRACT inputs="sourceFile: ts.SourceFile, fileStableId: string" outputs="IdentityProposal[]" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Traverses declarations, class members, interfaces, type aliases, variable statements and export assignments; determines types using isHook, isCapitalized; increments anonymousCounter for default exports"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+export function extractIdentities(sourceFile: ts.SourceFile, fileStableId: string): IdentityProposal[] {
+  const proposals: IdentityProposal[] = []
+
+  proposals.push({
+    identity: 'module_header',
+    type: 'module_header',
+    parent: fileStableId,
+    line_start: 1,
+    line_end: sourceFile.getLineAndCharacterOfPosition(sourceFile.getFullStart() + sourceFile.getFullWidth()).line + 1,
+    text: sourceFile.text,
+  })
+
+  proposals.push({
+    identity: 'file',
+    type: 'file',
+    parent: 'none',
+    line_start: 1,
+    line_end: sourceFile.getLineAndCharacterOfPosition(sourceFile.getFullStart() + sourceFile.getFullWidth()).line + 1,
+    text: sourceFile.text,
+  })
+
+  let anonymousCounter = 0
+
+  function visit(node: ts.Node, parentId: string) {
+    const startLine = lineOf(sourceFile, node)
+    const endLine = lineOf(sourceFile, node) + sourceFile.text.slice(node.getStart(), node.getEnd()).split('\n').length - 1
+    const text = sourceFile.text.slice(node.getStart(), node.getEnd())
+
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      const name = node.name.text
+      const type = isHook(name) ? 'hook' : isCapitalized(name) ? 'component' : 'function'
+      proposals.push({ identity: name, type, parent: parentId, line_start: startLine, line_end: endLine, text })
+      ts.forEachChild(node, child => visit(child, `${parentId}:${name}:${type}`))
+      return
+    }
+
+    if (ts.isClassDeclaration(node) && node.name) {
+      const className = node.name.text
+      const classId = `${parentId}:${className}:class`
+      proposals.push({ identity: className, type: 'class', parent: parentId, line_start: startLine, line_end: endLine, text })
+      node.members.forEach(member => {
+        if (ts.isMethodDeclaration(member) && member.name) {
+          const methodName = ts.isIdentifier(member.name) ? member.name.text : ts.isStringLiteral(member.name) ? member.name.text : String(member.name.getText(sourceFile))
+          proposals.push({
+            identity: `${className}.${methodName}`,
+            type: 'method',
+            parent: classId,
+            line_start: lineOf(sourceFile, member),
+            line_end: lineOf(sourceFile, member) + text.slice(member.getStart(), member.getEnd()).split('\n').length - 1,
+            text: sourceFile.text.slice(member.getStart(), member.getEnd()),
+          })
+        }
+      })
+      return
+    }
+
+    if (ts.isInterfaceDeclaration(node) && node.name) {
+      proposals.push({ identity: node.name.text, type: 'interface', parent: parentId, line_start: startLine, line_end: endLine, text })
+      return
+    }
+
+    if (ts.isTypeAliasDeclaration(node) && node.name) {
+      proposals.push({ identity: node.name.text, type: 'type', parent: parentId, line_start: startLine, line_end: endLine, text })
+      return
+    }
+
+    if (ts.isVariableStatement(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) {
+          const name = decl.name.text
+          const isConst = Boolean(node.declarationList.flags & ts.NodeFlags.Const)
+          let type = isConst ? 'constant' : 'variable'
+          if (decl.initializer) {
+            if (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)) {
+              type = isHook(name) ? 'hook' : isCapitalized(name) ? 'component' : 'function'
+            }
+          }
+          proposals.push({ identity: name, type, parent: parentId, line_start: startLine, line_end: endLine, text })
+        }
+      }
+      return
+    }
+
+    if (ts.isExportAssignment(node)) {
+      anonymousCounter += 1
+      proposals.push({ identity: 'default', type: 'function', parent: parentId, line_start: startLine, line_end: endLine, text })
+      return
+    }
+
+    ts.forEachChild(node, child => visit(child, parentId))
+  }
+
+  visit(sourceFile, fileStableId)
+  return proposals
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Extract candidate code identities from a TypeScript source file'; 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/functions/_shared/ast.ts:extractIdentities:function"]