spine-framework 0.3.125 → 0.3.126

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

@@ -1,22 +1,85 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/install-app
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine-framework install-app` — installs a Spine Framework app from npm.
- * Copies app files into custom/apps/, seeds types/roles/link-types into the DB.
- *
- * **Usage:**
- * ```bash
- * npx spine-framework install-app spine-framework-portal@latest
- * npx spine-framework install-app spine-framework-cortex
- * npx spine-framework uninstall-app spine-framework-portal
- * npx spine-framework update-app spine-framework-portal
- * ```
- */
 
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="install-app_registrationconfig_1784069813" type="interface" identity="RegistrationConfig" parent="none"]
+// CIL[DOC-MACRO purpose="Define registration configuration for an installed app"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the RegistrationConfig interface definition"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines registration settings including default role, redirect path, and account strategy" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" 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: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+interface RegistrationConfig {
+  enabled: boolean
+  default_role: string
+  redirect_path: string
+  account_strategy?: 'existing' | 'new' | 'choice'
+  target_account?: string
+}
+// CIL[END chunk_id="install-app_registrationconfig_1784069813"]
+
+// CIL[BEGIN chunk_id="install-app_spineconfig_1784069813" type="interface" identity="SpineConfig" parent="none"]
+// CIL[DOC-MACRO purpose="Define spine.config.json structure for registration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the SpineConfig interface definition"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines registration config with default app/role, URL override flag, and apps map" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" 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: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+interface SpineConfig {
+  registration?: {
+    default_app?: string
+    default_role?: string
+    allow_url_override?: boolean
+    default_app_by_role?: Record<string, string>
+    apps?: Record<string, {
+      roles: string[]
+      default_role: string
+      path: string
+      enabled: boolean
+      account_strategy: 'existing' | 'new' | 'choice'
+      target_account?: string
+    }>
+  }
+}
+// CIL[END chunk_id="install-app_spineconfig_1784069813"]
+
+// CIL[BEGIN chunk_id="install-app_moduleheader_1784069813" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Module imports for app installation CLI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide filesystem, database, and CLI utilities"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" 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="imports" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Node.js modules, Supabase client, and migration utilities" 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: .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"]
 import type { Command } from 'commander'
 import { existsSync, readFileSync, mkdirSync, cpSync, writeFileSync } from 'fs'
 import { resolve, dirname, join, basename } from 'path'
@@ -29,9 +92,26 @@ import { runMigrations } from './migrate.js'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 const PROJECT_ROOT = process.cwd()
-
+const SPINE_CONFIG_PATH = join(PROJECT_ROOT, 'spine.config.json')
+// CIL[END chunk_id="install-app_moduleheader_1784069813"]
+// CIL[BEGIN chunk_id="install-app_registerinstallappcommands_1784069813" type="function" identity="registerInstallAppCommands" parent="none"]
+// CIL[DOC-LEARNING topic="install-app:two_phase_install" content="install-app is two phases: npm copy then DB seed. If seed fails or is skipped, custom/apps/<slug> files may exist while the app is absent from public.apps, so it will not appear in the app registry."]
+// CIL[DOC-MACRO purpose="Register app management CLI commands"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide install, uninstall, update, and sync operations"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" 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="CLI commands" errors="npm, filesystem, database errors" side_effects="filesystem writes, database writes"]
+// CIL[DOC-NOTE type="manifest_config_sync" content="install-app and update-db-app now persist manifest.config and manifest.metadata into the apps table's config/metadata JSONB columns."]
+// CIL[DOC-MICRO logic_summary="Registers install-app, uninstall-app, update-app, and update-db-app commands; syncs manifest config/metadata into apps table" 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/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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function registerInstallAppCommands(program: Command) {
-  // install-app
+  
   program
     .command('install-app <package>')
     .description('Install a Spine Framework app from npm')
@@ -42,7 +122,7 @@ export function registerInstallAppCommands(program: Command) {
       loadEnv()
 
       try {
-        // 1. npm install the package
+        
         console.log(`  Installing ${packageName} via npm...`)
         execSync(`npm install ${packageName} --save`, {
           cwd: PROJECT_ROOT,
@@ -50,7 +130,7 @@ export function registerInstallAppCommands(program: Command) {
         })
         console.log('  ✓ npm install complete')
 
-        // 2. Resolve package location in node_modules
+        
         const pkgSlug = packageName.split('@')[0] // strip version
         const pkgPath = join(PROJECT_ROOT, 'node_modules', pkgSlug)
 
@@ -60,20 +140,18 @@ export function registerInstallAppCommands(program: Command) {
 
         console.log(`  Package path: ${pkgPath}`)
         
-        // 3. Determine app slug from package manifest or name
+        
         const appSlug = resolveAppSlug(pkgPath, pkgSlug)
         console.log(`  App slug: ${appSlug}`)
 
-        // 4. Copy app files to custom/apps/<slug>/
+        
         const appDest = join(PROJECT_ROOT, 'custom/apps', appSlug)
         const isReinstall = existsSync(appDest)
         if (!isReinstall) {
           mkdirSync(appDest, { recursive: true })
         }
 
-        // On reinstall, preserve the developer's local manifest.json — it is
-        // the source of truth for route_prefix and other project-level config.
-        // All other files are updated from npm as normal.
+        
         const allowedEntries = [
           'index.tsx', 'manifest.json', 'package.json',
           'pages', 'components', 'hooks', 'utils', 'functions', 'seed', 'public'
@@ -85,7 +163,7 @@ export function registerInstallAppCommands(program: Command) {
           const src = join(pkgPath, entry)
           if (!existsSync(src)) continue
 
-          // Preserve local manifest on reinstall — developer owns it after first install
+          
           if (entry === 'manifest.json' && isReinstall) {
             console.log(`    Preserving local manifest.json (use update-db-app to sync changes)`)
             continue
@@ -96,7 +174,7 @@ export function registerInstallAppCommands(program: Command) {
         }
         console.log(`  ✓ App files copied to custom/apps/${appSlug}/`)
 
-        // 5. Run pending migrations before seeding so schema is up to date
+        
         console.log('  Running migrations...')
         try {
           const migrateResult = await runMigrations({ frameworkOnly: false })
@@ -114,17 +192,17 @@ export function registerInstallAppCommands(program: Command) {
           console.warn(`  ⚠ Migration error: ${migrateErr.message} — continuing with seed`)
         }
 
-        // 6. Seed types, roles, link-types into database
+        
         if (!opts.seed === false) {
           await seedApp(appDest, appSlug)
         }
 
-        // 7. Aggregate registration config from manifest into spine.config.json
+        
         const manifestPath = join(appDest, 'manifest.json')
         let manifest: Record<string, any> = {}
         try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) } catch {}
         if (manifest.registration?.enabled) {
-          updateRegistrationConfig(appSlug, manifest.registration)
+          updateRegistrationConfig(appSlug, manifest.registration, manifest.required_roles ?? [])
         }
 
         let installedVersion = 'unknown'
@@ -140,7 +218,7 @@ export function registerInstallAppCommands(program: Command) {
       }
     })
 
-  // uninstall-app
+  
   program
     .command('uninstall-app <package>')
     .description('Remove an installed Spine Framework app')
@@ -173,7 +251,7 @@ export function registerInstallAppCommands(program: Command) {
       }
     })
 
-  // update-app
+  
   program
     .command('update-app <package>')
     .description('Update an installed Spine Framework app to a newer version')
@@ -203,12 +281,12 @@ export function registerInstallAppCommands(program: Command) {
           }
         }
 
-        // Update registration config from manifest
+        
         const manifestPath = join(appDest, 'manifest.json')
         let manifest: Record<string, any> = {}
         try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) } catch {}
         if (manifest.registration?.enabled) {
-          updateRegistrationConfig(appSlug, manifest.registration)
+          updateRegistrationConfig(appSlug, manifest.registration, manifest.required_roles ?? [])
         }
 
         let updatedVersion = 'unknown'
@@ -221,7 +299,7 @@ export function registerInstallAppCommands(program: Command) {
       }
     })
 
-  // update-db-app
+  
   program
     .command('update-db-app <slug>')
     .description('Sync local manifest.json changes to the database (no npm, no file changes)')
@@ -274,6 +352,8 @@ export function registerInstallAppCommands(program: Command) {
             min_role: manifest.required_roles?.[0] ?? manifest.min_role ?? null,
             preview_domain: manifest.preview_domain ?? null,
             prod_domain: manifest.prod_domain ?? null,
+            config: manifest.config ?? undefined,
+            metadata: manifest.metadata ?? undefined,
           },
           { onConflict: 'slug' }
         )
@@ -285,30 +365,56 @@ export function registerInstallAppCommands(program: Command) {
         process.exit(1)
       }
 
-      console.log(`  ✓ apps row updated (route_prefix: ${manifest.route_prefix ?? '/' + slug})`)
+      console.log(`  ✓ apps row updated (route_prefix: ${manifest.route_prefix ?? '/' + slug}, config: ${manifest.config ? 'synced' : 'none'})`)
 
-      // Update registration config in spine.config.json if declared
+      
       if (manifest.registration?.enabled) {
-        updateRegistrationConfig(slug, manifest.registration)
+        updateRegistrationConfig(slug, manifest.registration, manifest.required_roles ?? [])
       }
 
       console.log(`\n✅ ${slug} DB synced from local manifest.\n`)
       console.log(`Next: npm run assemble && netlify dev\n`)
     })
 }
-
-// ─── HELPERS ────────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="install-app_registerinstallappcommands_1784069813"]
+// CIL[BEGIN chunk_id="install-app_resolveappslug_1784069813" type="function" identity="resolveAppSlug" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve app slug from package name or manifest"]
+// CIL[DOC-RESPONSIBILITY responsibility="Extract app identifier from package metadata"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" 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="app slug" errors="file read errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Reads manifest.json slug field or strips spine-framework- prefix" 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: 1. 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: 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function resolveAppSlug(pkgPath: string, pkgName: string): string {
   try {
     const manifest = JSON.parse(readFileSync(join(pkgPath, 'manifest.json'), 'utf8'))
     if (manifest.slug) return manifest.slug
   } catch {}
-  // Derive from package name: spine-framework-portal → portal
+  
   const slug = pkgName.replace(/^spine-framework-/, '')
   return slug || pkgName // fallback to full name if replacement results in empty
 }
-
+// CIL[END chunk_id="install-app_resolveappslug_1784069813"]
+// CIL[BEGIN chunk_id="install-app_loadenv_1784069813" type="function" identity="loadEnv" parent="none"]
+// CIL[DOC-MACRO purpose="Load environment variables from .env file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Parse and set environment variables"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="process.env updates" errors="file read errors" side_effects="process.env mutation"]
+// CIL[DOC-MICRO logic_summary="Reads .env file, parses key=value pairs, sets process.env" 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: 1. Direct calls: 0. Related files: \."]
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function loadEnv() {
   const envPath = join(PROJECT_ROOT, '.env')
   if (!existsSync(envPath)) return
@@ -323,7 +429,25 @@ function loadEnv() {
     if (key && !(key in process.env)) process.env[key] = val
   }
 }
-
+// CIL[END chunk_id="install-app_loadenv_1784069813"]
+// CIL[BEGIN chunk_id="install-app_seedapp_1784069813" type="function" identity="seedApp" parent="none"]
+// CIL[DOC-LEARNING topic="install-app:seed_requires_env" content="DB seed requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .env; missing env vars cause install-app to copy files without registering the app in public.apps."]
+// CIL[DOC-LEARNING topic="install-app:types_unique_slug" content="public.types must enforce a unique slug. Seeding types per app (inject_app_id with conflict 'app_id,kind,slug') created duplicate funnel_signal, support_ticket, etc. rows, breaking resolveTypeId and .single() lookups. Types are now seeded with conflict 'kind,slug', inject_app_id: false, and ignoreDuplicates to keep them global."]
+// CIL[DOC-NOTE type="caution" content="The apps upsert uses onConflict: 'slug' and can still fail on the active route_prefix unique index if another active app already owns the same route_prefix."]
+// CIL[DOC-NOTE type="caution" content="types seeds must not inject app_id. The types table uses slug as the global type identifier; app-scoped duplicates cause lookup ambiguity."]
+// CIL[DOC-MACRO purpose="Seed database with app types, roles, and permissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Populate database with app-specific seed data"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="database records" errors="database errors" side_effects="database writes, app config sync from manifest"]
+// CIL[DOC-MICRO logic_summary="Registers app (including manifest.config/metadata), seeds roles/types, handles permission patches with user prompts" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_database_operations"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function seedApp(appDir: string, appSlug: string) {
   const supabaseUrl = process.env.SUPABASE_URL
   const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
@@ -337,9 +461,7 @@ async function seedApp(appDir: string, appSlug: string) {
     auth: { persistSession: false },
   })
 
-  // Upsert the app row first so we always have a real app_id UUID.
-  // apps.slug is UNIQUE NOT NULL, making it the only reliable conflict target
-  // at install time (we have no UUID yet).
+  
   const manifestPath = join(appDir, 'manifest.json')
   let manifest: Record<string, any> = {}
   try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) } catch {}
@@ -358,12 +480,14 @@ async function seedApp(appDir: string, appSlug: string) {
         is_active: true,
         route_prefix: manifest.route_prefix ?? ('/' + appSlug),
         renderer: manifest.renderer ?? 'custom',
-        // required_roles: full array from manifest (e.g. ["support", "support_admin"])
+        
         required_roles: manifest.required_roles ?? (manifest.min_role ? [manifest.min_role] : []),
-        // min_role: kept as legacy fallback — first entry of required_roles
+        
         min_role: manifest.required_roles?.[0] ?? manifest.min_role ?? null,
         preview_domain: manifest.preview_domain ?? null,
         prod_domain: manifest.prod_domain ?? null,
+        config: manifest.config ?? undefined,
+        metadata: manifest.metadata ?? undefined,
       },
       { onConflict: 'slug' }
     )
@@ -377,37 +501,29 @@ async function seedApp(appDir: string, appSlug: string) {
   }
 
   const appId = appRow.id
-  console.log(`  ✓ App registered (id: ${appId})`)
+  console.log(`  ✓ App registered (id: ${appId}, config: ${manifest.config ? 'synced' : 'none'})`)
 
-  // ── Manifest-driven seed loop ─────────────────────────────────────────────
-  // If manifest declares a `seed` array, use it. Each entry:
-  //   { file, table, conflict, inject_app_id? }
-  // inject_app_id defaults to true — set false for tables with no app_id column.
-  //
-  // Fallback: if no manifest.seed, use legacy hardcoded behavior so existing
-  // apps without a seed block continue to work.
-  // ─────────────────────────────────────────────────────────────────────────
+  
 
   interface SeedEntry {
     file: string
     table: string
     conflict: string
     inject_app_id?: boolean
-    // When true: only patch design_schema.record_permissions on existing types.
-    // The record must have { kind, slug, record_permissions } — no app_id injection.
+    ignore_duplicates?: boolean
     permissions_patch?: boolean
   }
 
   const seedEntries: SeedEntry[] = Array.isArray(manifest.seed)
     ? manifest.seed
     : [
-        // Legacy fallback — matches pre-019 behavior
-        { file: 'seed/roles.json',      table: 'roles',      conflict: 'app_id,slug' },
-        { file: 'seed/types.json',       table: 'types',      conflict: 'app_id,kind,slug' },
+        
+        { file: 'seed/roles.json',      table: 'roles',      conflict: 'slug' },
+        { file: 'seed/types.json',       table: 'types',      conflict: 'kind,slug', inject_app_id: false },
         { file: 'seed/link-types.json',  table: 'link_types', conflict: 'app_id,slug' },
       ]
 
-  // Always append the permissions patch file if it exists, unless already declared
+  
   const hasPermissionsPatch = seedEntries.some(e => e.permissions_patch)
   if (!hasPermissionsPatch) {
     seedEntries.push({
@@ -439,7 +555,7 @@ async function seedApp(appDir: string, appSlug: string) {
       continue
     }
 
-    // ── type_permissions.json: targeted record_permissions patch with check-and-choose ──
+    
     if (entry.permissions_patch) {
       console.log(`  Patching record_permissions for ${records.length} type(s) from ${entry.file}...`)
       for (const record of records) {
@@ -449,7 +565,7 @@ async function seedApp(appDir: string, appSlug: string) {
           continue
         }
 
-        // Fetch the existing type (match on kind+slug regardless of app_id)
+        
         const { data: existing } = await db
           .from('types')
           .select('id, design_schema')
@@ -465,13 +581,13 @@ async function seedApp(appDir: string, appSlug: string) {
         const existingSchema = (existing.design_schema ?? {}) as Record<string, any>
         const existingPerms = existingSchema.record_permissions ?? null
 
-        // Deep-equal check
+        
         if (JSON.stringify(existingPerms) === JSON.stringify(newPerms)) {
           console.log(`    ✓ ${kind}/${slug} record_permissions unchanged — skipped`)
           continue
         }
 
-        // Show diff and prompt
+        
         console.log(`\n    Type: ${kind}/${slug}`)
         console.log(`    Existing record_permissions:`)
         console.log('    ' + JSON.stringify(existingPerms, null, 2).replace(/\n/g, '\n    '))
@@ -484,7 +600,7 @@ async function seedApp(appDir: string, appSlug: string) {
           continue
         }
 
-        // Targeted JSON merge: only update record_permissions key in design_schema
+        
         const { error: patchErr } = await db
           .from('types')
           .update({
@@ -502,7 +618,7 @@ async function seedApp(appDir: string, appSlug: string) {
       continue
     }
 
-    // ── Standard seed: upsert whole record ────────────────────────────────────
+    
     const injectAppId = entry.inject_app_id !== false // default true
     console.log(`  Seeding ${records.length} record(s) from ${entry.file} → ${entry.table}...`)
 
@@ -510,7 +626,10 @@ async function seedApp(appDir: string, appSlug: string) {
       const row = injectAppId ? { ...record, app_id: appId } : { ...record }
       const { error } = await db
         .from(entry.table)
-        .upsert(row, { onConflict: entry.conflict })
+        .upsert(row, {
+          onConflict: entry.conflict,
+          ignoreDuplicates: entry.table === 'types' || entry.ignore_duplicates === true,
+        })
       if (error) {
         const label = record.slug ?? record.name ?? JSON.stringify(record).slice(0, 40)
         console.warn(`    ⚠ ${entry.table} "${label}": ${error.message}`)
@@ -520,9 +639,21 @@ async function seedApp(appDir: string, appSlug: string) {
     console.log(`  ✓ ${entry.table} seeded`)
   }
 }
-
-// ─── PROMPT HELPER ──────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="install-app_seedapp_1784069813"]
+// CIL[BEGIN chunk_id="install-app_prompt_1784069813" type="function" identity="prompt" parent="none"]
+// CIL[DOC-MACRO purpose="Prompt user for input via command line"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle interactive user input"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="user answer" errors="readline errors" side_effects="stdin interaction"]
+// CIL[DOC-MICRO logic_summary="Creates readline interface and returns user input as Promise" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function prompt(question: string): Promise<string> {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
   return new Promise(resolve => {
@@ -532,35 +663,21 @@ function prompt(question: string): Promise<string> {
     })
   })
 }
-
-// ─── SPINE CONFIG HELPERS ───────────────────────────────────────────────────
-
-interface RegistrationConfig {
-  enabled: boolean
-  default_role: string
-  redirect_path: string
-  account_strategy?: 'existing' | 'new' | 'choice'
-  target_account?: string
-}
-
-interface SpineConfig {
-  registration?: {
-    default_app?: string
-    default_role?: string
-    allow_url_override?: boolean
-    apps?: Record<string, {
-      roles: string[]
-      default_role: string
-      path: string
-      enabled: boolean
-      account_strategy: 'existing' | 'new' | 'choice'
-      target_account?: string
-    }>
-  }
-}
-
-const SPINE_CONFIG_PATH = join(PROJECT_ROOT, 'spine.config.json')
-
+// CIL[END chunk_id="install-app_prompt_1784069813"]
+// CIL[BEGIN chunk_id="install-app_loadspineconfig_1784069813" type="function" identity="loadSpineConfig" parent="none"]
+// CIL[DOC-MACRO purpose="Load spine.config.json configuration file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Read and parse Spine configuration"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineConfig object" errors="file read errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Reads spine.config.json with fallback to empty config" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function loadSpineConfig(): SpineConfig {
   if (!existsSync(SPINE_CONFIG_PATH)) {
     return { registration: { apps: {} } }
@@ -571,15 +688,44 @@ function loadSpineConfig(): SpineConfig {
     return { registration: { apps: {} } }
   }
 }
-
+// CIL[END chunk_id="install-app_loadspineconfig_1784069813"]
+// CIL[BEGIN chunk_id="install-app_savespineconfig_1784069813" type="function" identity="saveSpineConfig" parent="none"]
+// CIL[DOC-MACRO purpose="Save configuration to spine.config.json"]
+// CIL[DOC-RESPONSIBILITY responsibility="Write Spine configuration to file"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="file write" errors="file write errors" side_effects="filesystem write"]
+// CIL[DOC-MICRO logic_summary="Writes configuration as formatted JSON to spine.config.json" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function saveSpineConfig(config: SpineConfig): void {
   writeFileSync(SPINE_CONFIG_PATH, JSON.stringify(config, null, 2) + '\n')
 }
-
-function updateRegistrationConfig(appSlug: string, regConfig: RegistrationConfig): void {
+// CIL[END chunk_id="install-app_savespineconfig_1784069813"]
+// CIL[BEGIN chunk_id="install-app_updateregistrationconfig_1784069813" type="function" identity="updateRegistrationConfig" parent="none"]
+// CIL[DOC-LEARNING topic="spine.config:registration_slug_match" content="spine.config.json registration.apps is keyed by app slug and default_app points to that key; the slug must match the public.apps row or post-login redirects will point to a non-routable app."]
+// CIL[DOC-MACRO purpose="Update registration config for app in spine.config.json"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure app registration and role settings"]
+// CIL[DOC-CONTEXT module="cli.commands.install-app" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="config file update" errors="file errors" side_effects="config file write"]
+// CIL[DOC-MICRO logic_summary="Updates spine.config.json with app registration settings and available roles" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+function updateRegistrationConfig(appSlug: string, regConfig: RegistrationConfig, requiredRoles: string[] = []): void {
   const config = loadSpineConfig()
 
-  // Ensure registration section exists
+  
   if (!config.registration) {
     config.registration = { apps: {} }
   }
@@ -587,22 +733,10 @@ function updateRegistrationConfig(appSlug: string, regConfig: RegistrationConfig
     config.registration.apps = {}
   }
 
-  // Try to load all roles from the app's seed data
-  let availableRoles: string[] = [regConfig.default_role] // Start with default role from manifest
   
-  try {
-    const rolesPath = join(PROJECT_ROOT, 'custom/apps', appSlug, 'seed/roles.json')
-    if (existsSync(rolesPath)) {
-      const rolesData = JSON.parse(readFileSync(rolesPath, 'utf8'))
-      if (Array.isArray(rolesData)) {
-        availableRoles = rolesData.map((role: any) => role.slug).filter(Boolean)
-      }
-    }
-  } catch (error) {
-    console.log(`  ⚠️  Could not load roles from seed data, using default role only`)
-  }
+  let availableRoles: string[] = requiredRoles.length ? requiredRoles : [regConfig.default_role]
 
-  // Add/update this app's registration entry with multi-role and account strategy support
+  
   config.registration.apps[appSlug] = {
     roles: availableRoles,
     default_role: regConfig.default_role,
@@ -612,14 +746,14 @@ function updateRegistrationConfig(appSlug: string, regConfig: RegistrationConfig
     target_account: regConfig.target_account,
   }
 
-  // If this is the first registration-enabled app, make it the default
+  
   const enabledApps = Object.entries(config.registration.apps).filter(([, cfg]) => cfg.enabled)
   if (enabledApps.length === 1 || !config.registration.default_app) {
     config.registration.default_app = appSlug
     config.registration.default_role = regConfig.default_role
   }
 
-  // Default allow_url_override to true if not set
+  
   if (config.registration.allow_url_override === undefined) {
     config.registration.allow_url_override = true
   }
@@ -628,3 +762,4 @@ function updateRegistrationConfig(appSlug: string, regConfig: RegistrationConfig
   console.log(`  ✓ Updated spine.config.json registration for ${appSlug}`)
   console.log(`  ✓ Available roles: ${availableRoles.join(', ')}`)
 }
+// CIL[END chunk_id="install-app_updateregistrationconfig_1784069813"]