spine-framework 0.3.124 → 0.3.125

package/.framework/cli/commands/doctor.ts

@@ -1,44 +1,12 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/doctor
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine doctor` command — comprehensive system validation for agentic IDE setup.
- * Checks environment, database, migrations, integrity, and custom code.
- *
- * **Commands:**
- * | Subcommand        | Description                                           |
- * |-------------------|-------------------------------------------------------|
- * | `doctor`          | Run all checks and report status                      |
- * | `doctor --json`   | Output structured JSON for agent consumption          |
- * | `doctor --fix`    | Attempt automatic remediation where possible          |
- *
- * **Checks performed:**
- * 1. Environment variables (SUPABASE_URL, SERVICE_ROLE_KEY)
- * 2. Database connectivity and latency
- * 3. Migration status (local vs applied)
- * 4. Core integrity (manifest hash verification)
- * 5. Custom code TypeScript compilation
- * 6. Test suite status (last run results)
- *
- * **Exit codes:**
- * - 0: All checks passed (healthy)
- * - 1: One or more checks failed
- * - 2: Check passed but warnings present (degraded)
- *
- * **Usage:**
- * ```bash
- * spine doctor
- * spine doctor --json
- * spine doctor --fix
- * ```
- *
- * @seeAlso cli/context.ts (buildCliContext)
- * @seeAlso functions/system.ts (health endpoint)
- */
 
+
+// CIL[BEGIN chunk_id="doctor_module_header_1783405679" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Setup imports and path constants for doctor command"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure module dependencies and file paths"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imports, paths" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import CLI framework, database, and file system utilities" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
 import type { Command } from 'commander'
 import { buildCliContext, handleError } from '../context.ts'
 import { adminDb } from '../../functions/_shared/index.ts'
@@ -48,9 +16,17 @@ import { fileURLToPath } from 'url'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
+// CIL[END chunk_id="doctor_module_header_1783405679"]
+
 
-// ─── TYPES ─────────────────────────────────────────────────────────────────
 
+// CIL[BEGIN chunk_id="doctor_CheckResult_1783405679" type="interface" identity="CheckResult" parent="none"]
+// CIL[DOC-MACRO purpose="Define structure for individual health check results"]
+// CIL[DOC-RESPONSIBILITY responsibility="Standardize check result data format"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Type definition for check status and metadata" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
 interface CheckResult {
   name: string
   status: 'pass' | 'fail' | 'warn'
@@ -58,7 +34,15 @@ interface CheckResult {
   details?: Record<string, any>
   fixable?: boolean
 }
-
+// CIL[END chunk_id="doctor_CheckResult_1783405679"]
+
+// CIL[BEGIN chunk_id="doctor_DoctorReport_1783405679" type="interface" identity="DoctorReport" parent="none"]
+// CIL[DOC-MACRO purpose="Define structure for complete doctor health report"]
+// CIL[DOC-RESPONSIBILITY responsibility="Aggregate all check results into summary report"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="DoctorReport interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Type definition for overall health status and summary" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
 interface DoctorReport {
   overall: 'healthy' | 'degraded' | 'unhealthy'
   checks: CheckResult[]
@@ -69,9 +53,17 @@ interface DoctorReport {
     fixable: number
   }
 }
+// CIL[END chunk_id="doctor_DoctorReport_1783405679"]
 
-// ─── CHECK IMPLEMENTATIONS ─────────────────────────────────────────────────
 
+
+// CIL[BEGIN chunk_id="doctor_checkEnvironment_1783405679" type="function" identity="checkEnvironment" parent="none"]
+// CIL[DOC-MACRO purpose="Validate required environment variables are set"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check SUPABASE_URL and SERVICE_ROLE_KEY presence"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Check process.env for required vars and .xenv file existence" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 async function checkEnvironment(): Promise<CheckResult> {
   const required = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY']
   const missing = required.filter(v => !process.env[v])
@@ -86,7 +78,7 @@ async function checkEnvironment(): Promise<CheckResult> {
     }
   }
 
-  // Check if .xenv exists
+  
   const xenvPath = resolve(__dirname, '../../.xenv')
   const hasXenv = existsSync(xenvPath)
 
@@ -97,7 +89,15 @@ async function checkEnvironment(): Promise<CheckResult> {
     details: { has_xenv: hasXenv, vars_present: required.length }
   }
 }
-
+// CIL[END chunk_id="doctor_checkEnvironment_1783405679"]
+
+// CIL[BEGIN chunk_id="doctor_checkDatabase_1783405679" type="function" identity="checkDatabase" parent="none"]
+// CIL[DOC-MACRO purpose="Test database connectivity and measure latency"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify database connection and performance"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="database connection errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query accounts table to test connection and measure response time" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 async function checkDatabase(): Promise<CheckResult> {
   const start = Date.now()
   try {
@@ -129,7 +129,15 @@ async function checkDatabase(): Promise<CheckResult> {
     }
   }
 }
-
+// CIL[END chunk_id="doctor_checkDatabase_1783405679"]
+
+// CIL[BEGIN chunk_id="doctor_checkMigrations_1783405679" type="function" identity="checkMigrations" parent="none"]
+// CIL[DOC-MACRO purpose="Compare local migration files with applied database migrations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Detect pending migrations and migration status"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="database query errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="List local SQL files and compare with schema_migrations table" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
 async function checkMigrations(): Promise<CheckResult> {
   const migrationsDir = resolve(__dirname, '../../migrations_dayzero')
 
@@ -191,7 +199,15 @@ async function checkMigrations(): Promise<CheckResult> {
     }
   }
 }
-
+// CIL[END chunk_id="doctor_checkMigrations_1783405679"]
+
+// CIL[BEGIN chunk_id="doctor_checkIntegrity_1783405679" type="function" identity="checkIntegrity" parent="none"]
+// CIL[DOC-MACRO purpose="Validate core manifest file and integrity hash presence"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check manifest file exists and has integrity data"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="file read/parse errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Read manifest.json and verify integrity hash exists" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
 async function checkIntegrity(): Promise<CheckResult> {
   const manifestPath = resolve(__dirname, '../../.spine-manifest.json')
 
@@ -218,9 +234,7 @@ async function checkIntegrity(): Promise<CheckResult> {
       }
     }
 
-    // Note: We don't actually verify the hash here - that would require
-    // computing SHA256 of all core files, which is slow. We just check
-    // that a manifest exists and looks valid.
+    
     return {
       name: 'integrity',
       status: 'pass',
@@ -236,7 +250,15 @@ async function checkIntegrity(): Promise<CheckResult> {
     }
   }
 }
-
+// CIL[END chunk_id="doctor_checkIntegrity_1783405679"]
+
+// CIL[BEGIN chunk_id="doctor_checkTestRuns_1783405679" type="function" identity="checkTestRuns" parent="none"]
+// CIL[DOC-MACRO purpose="Check latest test run status and results"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify test suite execution and report status"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CheckResult" errors="database query errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query test_runs table for most recent test execution" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
 async function checkTestRuns(): Promise<CheckResult> {
   try {
     const { data, error } = await adminDb
@@ -281,9 +303,17 @@ async function checkTestRuns(): Promise<CheckResult> {
     }
   }
 }
+// CIL[END chunk_id="doctor_checkTestRuns_1783405679"]
 
-// ─── FIX IMPLEMENTATIONS ───────────────────────────────────────────────────
 
+
+// CIL[BEGIN chunk_id="doctor_tryFix_1783405679" type="function" identity="tryFix" parent="none"]
+// CIL[DOC-MACRO purpose="Provide fix suggestions for failed health checks"]
+// CIL[DOC-RESPONSIBILITY responsibility="Generate remediation instructions for each check type"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="CheckResult" outputs="string fix instructions" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Switch statement mapping check names to fix commands" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 async function tryFix(check: CheckResult): Promise<string> {
   switch (check.name) {
     case 'environment':
@@ -302,9 +332,17 @@ async function tryFix(check: CheckResult): Promise<string> {
       return 'No automatic fix available'
   }
 }
+// CIL[END chunk_id="doctor_tryFix_1783405679"]
+
 
-// ─── COMMAND REGISTRATION ──────────────────────────────────────────────────
 
+// CIL[BEGIN chunk_id="doctor_registerDoctorCommands_1783405679" type="function" identity="registerDoctorCommands" parent="none"]
+// CIL[DOC-MACRO purpose="Register doctor CLI command and orchestrate health checks"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute all health checks and format results"]
+// CIL[DOC-CONTEXT module="cli/commands/doctor" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="Command program" outputs="registered CLI command" errors="CLI errors" side_effects="process exit"]
+// CIL[DOC-MICRO logic_summary="Run checks sequentially, aggregate results, output formatted report" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
 export function registerDoctorCommands(program: Command) {
   program
     .command('doctor')
@@ -313,8 +351,7 @@ export function registerDoctorCommands(program: Command) {
     .option('--fix', 'Show fix instructions for failed checks')
     .action(async (opts) => {
       try {
-        // Don't require full context for doctor - we want to diagnose issues
-        // even when env vars are missing
+        
         let ctx
         try {
           ctx = await buildCliContext()
@@ -322,16 +359,16 @@ export function registerDoctorCommands(program: Command) {
           ctx = null
         }
 
-        // Run all checks
+        
         const checks: CheckResult[] = []
 
         checks.push(await checkEnvironment())
 
-        // Only proceed with DB checks if env is valid
+        
         if (checks[0].status === 'pass') {
           checks.push(await checkDatabase())
 
-          // Only proceed with data checks if DB is connected
+          
           if (checks[1].status === 'pass') {
             checks.push(await checkMigrations())
             checks.push(await checkTestRuns())
@@ -372,7 +409,7 @@ export function registerDoctorCommands(program: Command) {
 
         checks.push(await checkIntegrity())
 
-        // Calculate overall status
+        
         const failed = checks.filter(c => c.status === 'fail').length
         const warnings = checks.filter(c => c.status === 'warn').length
         const fixable = checks.filter(c => c.fixable).length
@@ -397,7 +434,7 @@ export function registerDoctorCommands(program: Command) {
           }
         }
 
-        // Output
+        
         if (opts.json) {
           console.log(JSON.stringify(report, null, 2))
         } else {
@@ -426,7 +463,7 @@ export function registerDoctorCommands(program: Command) {
           console.log()
         }
 
-        // Exit code
+        
         if (overall === 'unhealthy') {
           process.exit(1)
         } else if (overall === 'degraded') {
@@ -440,3 +477,4 @@ export function registerDoctorCommands(program: Command) {
       }
     })
 }
+// CIL[END chunk_id="doctor_registerDoctorCommands_1783405679"]

package/.framework/cli/commands/generate.ts

@@ -1,38 +1,12 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/generate
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine generate` command — code scaffolding for extending Spine safely.
- * Generates type definitions, handlers, and UI pages in v2-custom/ only.
- *
- * **Commands:**
- * | Subcommand              | Description                                           |
- * |-------------------------|-------------------------------------------------------|
- * | `generate type <slug>`  | Create new type with handler and UI stubs             |
- * | `generate function <name>` | Create new Netlify function stub                   |
- *
- * **What gets generated for `type`:**
- * 1. Type record in database (item type by default)
- * 2. Handler stub: `v2-custom/functions/{slug}.ts`
- * 3. UI page stub: `v2-custom/src/pages/{slug}/index.tsx`
- *
- * **What gets generated for `function`:**
- * 1. Netlify function stub: `v2-custom/functions/{name}.ts`
- * 2. Basic handler structure with middleware imports
- *
- * **Usage:**
- * ```bash
- * spine generate type ticket-v2
- * spine generate function webhook-handler
- * ```
- *
- * @seeAlso functions/types.ts (type CRUD API)
- * @seeAlso functions/_shared/middleware.ts (handler structure)
- */
 
+
+// CIL[BEGIN chunk_id="generate_module_header_1783475972" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Setup imports and path constants for generate command"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure module dependencies and file paths"]
+// CIL[DOC-CONTEXT module="cli/commands/generate" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imports, paths" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import CLI framework, database, and file system utilities" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
 import type { Command } from 'commander'
 import { buildCliContext, handleError } from '../context.ts'
 import { adminDb } from '../../functions/_shared/index.ts'
@@ -43,9 +17,17 @@ import { fileURLToPath } from 'url'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 const PROJECT_ROOT = resolve(__dirname, '../../../')
+// CIL[END chunk_id="generate_module_header_1783475972"]
 
-// ─── TYPE GENERATION ─────────────────────────────────────────────────────────
 
+
+// CIL[BEGIN chunk_id="generate_generatetype_1783475972" type="function" identity="generateType" parent="none"]
+// CIL[DOC-MACRO purpose="Generate complete type with database record and code stubs"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create type in DB and generate handler/UI files"]
+// CIL[DOC-CONTEXT module="cli/commands/generate" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="ctx, slug, options" outputs="none" errors="database errors, file errors" side_effects="file creation, DB writes"]
+// CIL[DOC-MICRO logic_summary="Create DB type record, generate handler stub, generate UI page stub" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
 async function generateType(ctx: any, slug: string, options: any): Promise<void> {
   const name = options.name || slug.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ')
   const kind = options.kind || 'item'
@@ -53,8 +35,7 @@ async function generateType(ctx: any, slug: string, options: any): Promise<void>
 
   console.log(`\n🔧 Generating type '${slug}'...`)
 
-  // Step 1: Create type record in database
-  console.log('  Step 1: Creating type record in database...')
+  
 
   const { data: existing, error: checkErr } = await adminDb
     .from('types')
@@ -63,7 +44,7 @@ async function generateType(ctx: any, slug: string, options: any): Promise<void>
     .eq('kind', kind)
     .single()
 
-  if (checkErr && checkErr.code !== 'PGRST116') { // PGRST116 = not found
+  if (checkErr && checkErr.code !== 'PGRST116') {
     throw new Error(`Failed to check existing type: ${checkErr.message}`)
   }
 
@@ -111,8 +92,7 @@ async function generateType(ctx: any, slug: string, options: any): Promise<void>
     console.log('  ✓ Type record created')
   }
 
-  // Step 2: Generate handler stub
-  console.log('  Step 2: Generating handler stub...')
+  
   const handlerPath = resolve(PROJECT_ROOT, `v2-custom/functions/${slug}.ts`)
 
   if (existsSync(handlerPath) && !options.force) {
@@ -123,8 +103,7 @@ async function generateType(ctx: any, slug: string, options: any): Promise<void>
     console.log(`  ✓ Handler stub created: v2-custom/functions/${slug}.ts`)
   }
 
-  // Step 3: Generate UI page stub
-  console.log('  Step 3: Generating UI page stub...')
+  
   const pageDir = resolve(PROJECT_ROOT, `v2-custom/src/pages/${slug}`)
   const pagePath = resolve(pageDir, 'index.tsx')
 
@@ -143,7 +122,15 @@ async function generateType(ctx: any, slug: string, options: any): Promise<void>
   console.log(`   2. Edit v2-custom/src/pages/${slug}/index.tsx to customize the UI`)
   console.log(`   3. Run 'spine dev' to see your changes`)
 }
-
+// CIL[END chunk_id="generate_generatetype_1783475972"]
+
+// CIL[BEGIN chunk_id="generate_generatehandlerstub_1783475972" type="function" identity="generateHandlerStub" parent="none"]
+// CIL[DOC-MACRO purpose="Generate TypeScript handler stub with CRUD methods"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create template handler code for new types"]
+// CIL[DOC-CONTEXT module="cli/commands/generate" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="slug, kind, name" outputs="string handler code" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return template string with handler structure and HTTP methods" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 function generateHandlerStub(slug: string, kind: string, name: string): string {
   return `/**
  * @module ${slug}
@@ -185,7 +172,15 @@ export const handler = createHandler(async (ctx) => {
 })
 `
 }
-
+// CIL[END chunk_id="generate_generatehandlerstub_1783475972"]
+
+// CIL[BEGIN chunk_id="generate_generatepagestub_1783475972" type="function" identity="generatePageStub" parent="none"]
+// CIL[DOC-MACRO purpose="Generate React UI page stub for type management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create template React component with API integration"]
+// CIL[DOC-CONTEXT module="cli/commands/generate" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="slug, name, kind" outputs="string React component code" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return template string with React component and API hooks" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 function generatePageStub(slug: string, name: string, kind: string): string {
   return `/**
  * @page ${slug}/index
@@ -227,9 +222,17 @@ export default function ${name.replace(/\s+/g, '')}Page() {
 }
 `
 }
+// CIL[END chunk_id="generate_generatepagestub_1783475972"]
+
 
-// ─── FUNCTION GENERATION ─────────────────────────────────────────────────────
 
+// CIL[BEGIN chunk_id="generate_generatefunction_1783475972" type="function" identity="generateFunction" parent="none"]
+// CIL[DOC-MACRO purpose="Generate standalone Netlify function stub"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create custom function file with basic structure"]
+// CIL[DOC-CONTEXT module="cli/commands/generate" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="name, options" outputs="none" errors="file errors" side_effects="file creation"]
+// CIL[DOC-MICRO logic_summary="Check existing file, generate function stub, write to disk" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 async function generateFunction(name: string, options: any): Promise<void> {
   console.log(`\n🔧 Generating function '${name}'...`)
 
@@ -250,7 +253,15 @@ async function generateFunction(name: string, options: any): Promise<void> {
   console.log(`   1. Edit the handler to implement your logic`)
   console.log(`   2. Run 'spine dev' to see your changes`)
 }
-
+// CIL[END chunk_id="generate_generatefunction_1783555400"]
+
+// CIL[BEGIN chunk_id="generate_generatefunctionstub_1783555400" type="function" identity="generateFunctionStub" parent="none"]
+// CIL[DOC-MACRO purpose="Generate standalone Netlify function template"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create template function with action routing"]
+// CIL[DOC-CONTEXT module="cli/commands/generate" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="name, description" outputs="string function code" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return template string with handler structure and action switch" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 function generateFunctionStub(name: string, description?: string): string {
   return `/**
  * @module ${name}
@@ -293,9 +304,15 @@ export const handler = createHandler(async (ctx) => {
 })
 `
 }
-
-// ─── COMMAND REGISTRATION ────────────────────────────────────────────────────
-
+// CIL[END chunk_id="generate_generatefunctionstub_1783555400"]
+
+// CIL[BEGIN chunk_id="generate_registergeneratecommands_1783555400" type="function" identity="registerGenerateCommands" parent="none"]
+// CIL[DOC-MACRO purpose="Register generate CLI commands for type and function scaffolding"]
+// CIL[DOC-RESPONSIBILITY responsibility="Setup CLI interface for code generation tools"]
+// CIL[DOC-CONTEXT module="cli/commands/generate" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="Command program" outputs="registered CLI commands" errors="CLI errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Register 'generate type' and 'generate function' subcommands with options" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
 export function registerGenerateCommands(program: Command) {
   const generate = program
     .command('generate')
@@ -330,3 +347,4 @@ export function registerGenerateCommands(program: Command) {
       }
     })
 }
+// CIL[END chunk_id="generate_registergeneratecommands_1783555400"]

package/.framework/functions/_shared/cil-state.ts

@@ -9,7 +9,16 @@
 
 import { adminDb } from './db'
 
-export type FileStatus = 'discovered' | 'pass2_complete' | 'pass3_complete' | 'pass4_complete' | 'pass4b_complete' | 'pass5_complete'
+export type FileStatus =
+  | '0-discovered'
+  | '1-selected'
+  | '2-chunked'
+  | '3-first-pass-complete'
+  | '4-first-pass-embedded'
+  | '5-first-pass-mapped'
+  | '6-second-pass-complete'
+  | '7-second-pass-embedded'
+  | '8-second-pass-mapped'
 
 export interface FileTreeNode {
   id?: string | null
@@ -40,7 +49,7 @@ export function isSelectedPath(filePath: string, selectedPaths: string[]): boole
  * Extract the file status from a cil_file item.
  */
 export function getFileStatus(fileItem: any): FileStatus {
-  return fileItem.data?.status || 'discovered'
+  return fileItem.data?.status || '0-discovered'
 }
 
 /**

package/.framework/functions/_shared/index.ts

@@ -258,6 +258,20 @@ export { sanitizeRecordData, validateUpdatePermissions, canAccessRecord } from '
 export { generateValidationSchema } from './schema-utils'
 export type { ValidationSchema } from './schema-utils'
 
+// ============================================
+// ID Resolution — type, link type, account, agent lookups
+// ============================================
+
+/**
+ * resolveTypeId — resolve a single type UUID by kind + slug.
+ * resolveTypeIds — batch resolve multiple type UUIDs.
+ * resolveTypeRecord — resolve a type's full record (id + design_schema + validation_schema).
+ *   Use this when creating items that need to be stamped with schema data.
+ * resolveLinkTypeId / resolveLinkTypeIds — resolve link type UUIDs by slug.
+ */
+export { resolveTypeId, resolveTypeIds, resolveTypeRecord, resolveLinkTypeId, resolveLinkTypeIds, resolveAccountId, resolveAgentId, resolvePromptConfigId } from './resolve-ids'
+export type { TypeRecord } from './resolve-ids'
+
 // ============================================
 // Audit
 // ============================================

package/.framework/functions/_shared/resolve-ids.ts

@@ -1,10 +1,5 @@
-// Slug-based ID resolution utilities
-// Custom app code must never hardcode UUIDs — IDs differ on every fresh install.
-// All functions that need entity IDs must call resolveIds() at request time.
-
 import { adminDb } from './db'
 
-// Resolve type IDs by (kind, slug) pairs
 export async function resolveTypeIds(
   pairs: Array<{ kind: string; slug: string }>
 ): Promise<Record<string, string>> {
@@ -32,13 +27,46 @@ export async function resolveTypeIds(
   return result
 }
 
-// Resolve a single type ID — throws if not found
 export async function resolveTypeId(kind: string, slug: string): Promise<string> {
   const ids = await resolveTypeIds([{ kind, slug }])
   return ids[`${kind}/${slug}`]
 }
 
-// Resolve link type IDs by slug
+export interface TypeRecord {
+  id: string
+  slug: string
+  kind: string
+  design_schema: Record<string, any>
+  validation_schema: Record<string, any>
+  is_active: boolean
+}
+
+/**
+ * Resolve a type record by kind + slug in a single query.
+ * Returns id, design_schema, and validation_schema — everything needed
+ * to stamp a new item record (mirrors the admin-data.ts create handler pattern).
+ */
+export async function resolveTypeRecord(kind: string, slug: string): Promise<TypeRecord> {
+  const { data, error } = await adminDb
+    .from('types')
+    .select('id, slug, kind, design_schema, validation_schema, is_active')
+    .eq('kind', kind)
+    .eq('slug', slug)
+    .single()
+
+  if (error || !data) throw new Error(`Type not found: ${kind}/${slug}`)
+  if (!data.is_active) throw new Error(`Type is inactive: ${kind}/${slug}`)
+
+  return {
+    id: data.id,
+    slug: data.slug,
+    kind: data.kind,
+    design_schema: data.design_schema || {},
+    validation_schema: data.validation_schema || {},
+    is_active: data.is_active,
+  }
+}
+
 export async function resolveLinkTypeIds(slugs: string[]): Promise<Record<string, string>> {
   if (slugs.length === 0) return {}
 
@@ -61,13 +89,11 @@ export async function resolveLinkTypeIds(slugs: string[]): Promise<Record<string
   return result
 }
 
-// Resolve a single link type ID — throws if not found
 export async function resolveLinkTypeId(slug: string): Promise<string> {
   const ids = await resolveLinkTypeIds([slug])
   return ids[slug]
 }
 
-// Resolve account ID by slug
 export async function resolveAccountId(slug: string): Promise<string> {
   const { data, error } = await adminDb
     .from('accounts')
@@ -79,7 +105,6 @@ export async function resolveAccountId(slug: string): Promise<string> {
   return data.id
 }
 
-// Resolve AI agent ID by name
 export async function resolveAgentId(name: string): Promise<string> {
   const { data, error } = await adminDb
     .from('ai_agents')
@@ -92,7 +117,6 @@ export async function resolveAgentId(name: string): Promise<string> {
   return data.id
 }
 
-// Resolve prompt config ID by slug
 export async function resolvePromptConfigId(slug: string): Promise<string> {
   const { data, error } = await adminDb
     .from('prompt_configs')

package/.framework/functions/admin-data.ts

@@ -45,7 +45,7 @@
 import { createHandler } from './_shared/middleware'
 import { sanitizeRecordData } from './_shared/permissions'
 import { adminDb } from './_shared/db'
-import { resolveTypeId } from './_shared/resolve-ids'
+import { resolveTypeId, resolveTypeRecord } from './_shared/resolve-ids'
 import { fireCreateTriggers, fireUpdateTriggers, fireDeleteTriggers } from './_shared/trigger-engine'
 // ─── CHUNK_END: ADMIN_DATA_OVERVIEW ──────────────────────────────────────────────
 
@@ -299,36 +299,30 @@ export const create = createHandler(async (ctx, body) => {
     const e: any = new Error('Valid entity parameter is required'); e.statusCode = 400; throw e
   }
 
-  // Resolve type_id from type_slug if provided, otherwise require type_id directly
-  let typeId = recordData.type_id
-  if (!typeId && body?.type_slug) {
+  // Resolve type record (id + design_schema + validation_schema) in one query.
+  // Accepts either type_slug (resolved by kind) or a direct type_id already in recordData.
+  let typeRecord: { id: string; design_schema: Record<string, any>; validation_schema: Record<string, any> }
+
+  if (body?.type_slug) {
     const kind = ENTITY_TO_KIND[entity]
     if (!kind) {
       const e: any = new Error(`type_slug is not supported for entity: ${entity}`); e.statusCode = 400; throw e
     }
-    typeId = await resolveTypeId(kind, body.type_slug)
-  }
-
-  // type_id is required on all runtime record creation
-  if (!typeId) {
+    typeRecord = await resolveTypeRecord(kind, body.type_slug)
+  } else if (recordData.type_id) {
+    const { data, error: typeErr } = await adminDb
+      .from('types')
+      .select('id, design_schema, validation_schema, is_active')
+      .eq('id', recordData.type_id)
+      .single()
+    if (typeErr || !data) throw new Error(`type_id not found: ${recordData.type_id}`)
+    if (!data.is_active) throw new Error(`type_id references an inactive type: ${recordData.type_id}`)
+    typeRecord = { id: data.id, design_schema: data.design_schema || {}, validation_schema: data.validation_schema || {} }
+  } else {
     const e: any = new Error('type_id or type_slug is required — every runtime record must reference a type'); e.statusCode = 400; throw e
   }
-  recordData.type_id = typeId
 
-  // Look up the type to stamp design_schema and validation_schema
-  const { data: typeRecord, error: typeErr } = await adminDb
-    .from('types')
-    .select('id, design_schema, validation_schema, is_active')
-    .eq('id', typeId)
-    .single()
-
-  if (typeErr || !typeRecord) {
-    throw new Error(`type_id not found: ${typeId}`)
-  }
-
-  if (!typeRecord.is_active) {
-    throw new Error(`type_id references an inactive type: ${typeId}`)
-  }
+  recordData.type_id = typeRecord.id
 
   // Ensure the type has at least permissions=ALL (defensive — migration 062 guarantees this)
   let designSchema = typeRecord.design_schema || {}

package/.framework/src/contexts/AuthContext.tsx

@@ -42,7 +42,8 @@ import { User } from '../types/auth'
 const STORAGE_VERSION = 1
 const STORAGE_KEY = 'spine_user'
 /** Max age (ms) before stored user is considered stale and discarded */
-const STORAGE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+const STORAGE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+const SESSION_TIMEOUT_MS = 15000 // guard against stale Supabase sessions hanging on reload
 
 interface StoredUserEnvelope {
   version: number
@@ -80,6 +81,23 @@ function writeStoredUser(user: User | null) {
   }
 }
 
+/**
+ * Wrapper around supabase.auth.getSession() that times out to prevent the
+ * app from getting stuck on a corrupted/stale stored session.
+ */
+async function getSessionWithTimeout(): Promise<{ data: { session: any | null } }> {
+  try {
+    return await Promise.race([
+      supabase.auth.getSession(),
+      new Promise<{ data: { session: null } }>((resolve) =>
+        setTimeout(() => resolve({ data: { session: null } }), SESSION_TIMEOUT_MS)
+      )
+    ])
+  } catch (error) {
+    return { data: { session: null } }
+  }
+}
+
 // ─── TYPES ───────────────────────────────────────────────────────────────────
 
 /**
@@ -167,7 +185,6 @@ async function fetchUserContext(maxRetries = 2): Promise<User | null> {
 
       const data = await response.json()
       if (data.error || !data.data) return null
-
       return data.data
     } catch (error) {
       lastError = error
@@ -177,8 +194,6 @@ async function fetchUserContext(maxRetries = 2): Promise<User | null> {
       return null
     }
   }
-
-  console.error('fetchUserContext failed after retries:', lastError)
   return null
 }
 
@@ -274,7 +289,7 @@ export function AuthProvider({ children }: AuthProviderProps) {
   // ── Refresh ────────────────────────────────────────────────────────────────
 
   const refreshUser = useCallback(async () => {
-    const { data: { session } } = await supabase.auth.getSession()
+    const { data: { session } } = await getSessionWithTimeout()
 
     if (!session?.user) {
       clearUser()
@@ -330,7 +345,7 @@ export function AuthProvider({ children }: AuthProviderProps) {
 
     const checkAuth = async () => {
       try {
-        const { data: { session } } = await supabase.auth.getSession()
+        const { data: { session } } = await getSessionWithTimeout()
 
         if (!session?.user) {
           if (!cancelled) clearUser()

package/.framework/src/lib/api.ts

@@ -58,7 +58,7 @@ export function getAccountId(): string | null {
 // ─── 401 INTERCEPTOR ─────────────────────────────────────────────────────────
 
 /** Paths that are expected to return 401 (don't trigger the interceptor) */
-const AUTH_PATHS = ['/api/auth']
+const AUTH_PATHS = ['/api/auth', '/api/admin-data']
 
 let _onUnauthorizedCallback: (() => void) | null = null
 
@@ -118,6 +118,8 @@ export async function getAuthHeaders(): Promise<Record<string, string>> {
   const { data: { session } } = await supabase.auth.getSession()
   if (session?.access_token) {
     headers['Authorization'] = `Bearer ${session.access_token}`
+  } else {
+    
   }
 
   if (_accountId) {

package/netlify.toml

@@ -30,6 +30,9 @@
 [functions."custom_cil-ingest"]
   timeout = 300
 
+[functions."custom_cil-embeddings"]
+  timeout = 300
+
 [[redirects]]
   from = "/*"
   to = "/index.html"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.124",
+  "version": "0.3.125",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {