spine-framework 0.3.145 → 0.4.1

package/.framework/cli/commands/migrate.ts

@@ -1,3 +1,13 @@
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Provides the migrate command for applying database migrations to a Supabase project."]
+// CIL[DOC-RESPONSIBILITY responsibility="Bootstraps imports and module context for the migrate CLI command."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Commander type, fs, path, and url helpers and defines package and project root constants." notable_decisions="Package root is resolved relative to the installed package; project root is the current working directory."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
+
 
 
 
@@ -8,51 +18,120 @@
 
 
 
-// CIL[BEGIN chunk_id="migrate_moduleheader_1784069813" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Module imports and types for migration CLI"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide filesystem utilities and migration interfaces"]
-// CIL[DOC-CONTEXT module="cli.commands.migrate" 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\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imports and types" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports Node.js modules and defines MigrateOptions interface" 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, .framework/functions/_shared/principal.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"]
 import type { Command } from 'commander'
 import { existsSync, readdirSync, readFileSync } from 'fs'
 import { resolve, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
-
+// CIL[DOC-VECTOR type="context" content="purpose='Provides the migrate command for applying database migrations to a Supabase project.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Defines the current module file path."]
+// CIL[DOC-RESPONSIBILITY responsibility="Derives __filename from the module import meta URL."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-STABILITY stability="internal"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Converts import.meta.url to a file path and assigns to __filename." notable_decisions="none"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 const __filename = fileURLToPath(import.meta.url)
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:__filename:constant"]
+// CIL[DOC-CONTEXT module="unknown" layer="unknown" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the current module file path.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Defines the current module directory."]
+// CIL[DOC-RESPONSIBILITY responsibility="Derives __dirname from __filename."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-STABILITY stability="internal"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-MICRO logic_summary="Computes the directory of the current file and assigns to __dirname." notable_decisions="none"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 const __dirname = dirname(__filename)
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:__dirname:constant"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:PACKAGE_ROOT:constant" type="constant" identity="PACKAGE_ROOT" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the current module directory.'; 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[DOC-CONTEXT module="migrate" layer="cli" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Defines the package root path."]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolves the package root by walking up from the CLI directory."]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Resolves the package root three levels above the current module." notable_decisions="none"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 const PACKAGE_ROOT = resolve(__dirname, '../../../')
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:PACKAGE_ROOT:constant"]
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the package root path.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:PROJECT_ROOT:constant" type="constant" identity="PROJECT_ROOT" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Defines the project root path."]
+// CIL[DOC-RESPONSIBILITY responsibility="Uses the current working directory as the project root."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Sets PROJECT_ROOT to process.cwd()." notable_decisions="none"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 const PROJECT_ROOT = process.cwd()
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the project root path.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:PROJECT_ROOT:constant"]
+
 
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:MigrateOptions:interface" type="interface" identity="MigrateOptions" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Declares the migrate command options."]
+// CIL[DOC-RESPONSIBILITY responsibility="Types the CLI flags and optional db password."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines dbPassword, dryRun, and frameworkOnly fields." notable_decisions="none"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 interface MigrateOptions {
   dbPassword?: string
   dryRun: boolean
   frameworkOnly: boolean
 }
-// CIL[END chunk_id="migrate_moduleheader_1784069813"]
-// CIL[BEGIN chunk_id="migrate_runmigrations_1784069813" type="function" identity="runMigrations" parent="none"]
-// CIL[DOC-MACRO purpose="Execute database migrations via direct PostgreSQL connection"]
-// CIL[DOC-RESPONSIBILITY responsibility="Apply pending SQL migrations to database"]
-// CIL[DOC-CONTEXT module="cli.commands.migrate" layer="cli" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="migration results" errors="database errors" side_effects="database writes"]
-// CIL[DOC-MICRO logic_summary="Connects to PostgreSQL, creates migration tracking table, applies SQL files" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, .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."]
+// CIL[DOC-VECTOR type="context" content="purpose='Declares the migrate command options.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:MigrateOptions:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:runMigrations:function" type="function" identity="runMigrations" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Applies pending SQL migration files to the Supabase database and tracks which have been applied."]
+// CIL[DOC-RESPONSIBILITY responsibility="Executes migrations safely in transactions and records them in the tracking table."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="opts: { frameworkOnly?: boolean }" outputs="Promise<{ applied: number; skipped: number; failed: number } | null>" errors="Returns null if credentials missing; throws on invalid SUPABASE_URL, tracking-table failures, and file read errors; logs per migration statement errors to stderr, rolls back, increments failed once, and stops." side_effects="Connects to Postgres, creates _spine_migrations table, executes SQL, inserts migration records, writes to stdout/stderr."]
+// CIL[DOC-MICRO logic_summary="Reads env, validates SUPABASE_URL is a credential-free hosted https://<project-ref>.supabase.co URL, derives the db host, builds a pg.Client config object, collects migration files, filters already applied, splits and runs SQL statements, updates _spine_migrations, and returns counts." notable_decisions="Skips missing or placeholder credentials; non-HTTPS, credential-bearing, non-supabase.co, ported, pathed, or query/hash URLs are rejected before any client exists; uses a SET to track applied files; runs each migration in a transaction; tracking CREATE and SELECT propagate so migrations never run against unknown tracking state; first file error rolls back and breaks; the connected client always ends via finally."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Promise<{ applied: number; skipped: number; failed: number } | null> {
   const supabaseUrl = process.env.SUPABASE_URL
   if (!supabaseUrl || supabaseUrl.includes('placeholder') || supabaseUrl.includes('your-project')) {
@@ -64,16 +143,41 @@ export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Pro
     return null
   }
 
-  const projectRef = supabaseUrl.replace('https://', '').split('.')[0]
-  const connectionString = `postgresql://postgres:${dbPassword}@db.${projectRef}.supabase.co:5432/postgres`
+  let projectRef: string
+  try {
+    const parsed = new URL(supabaseUrl)
+    if (
+      parsed.protocol !== 'https:' ||
+      parsed.username !== '' ||
+      parsed.password !== '' ||
+      parsed.port !== '' ||
+      parsed.search !== '' ||
+      parsed.hash !== '' ||
+      (parsed.pathname !== '/' && parsed.pathname !== '') ||
+      !/^[a-z0-9-]+\.supabase\.co$/.test(parsed.hostname)
+    ) {
+      throw new Error('not a hosted Supabase URL')
+    }
+    projectRef = parsed.hostname.split('.')[0]
+  } catch {
+    throw new Error('Invalid SUPABASE_URL — expected a URL like https://<project-ref>.supabase.co')
+  }
 
   const migrationFiles = collectMigrations(opts.frameworkOnly ?? false)
   if (migrationFiles.length === 0) return { applied: 0, skipped: 0, failed: 0 }
 
   const { default: pg } = await import('pg')
-  const client = new pg.Client({ connectionString })
+  const client = new pg.Client({
+    user: 'postgres',
+    password: dbPassword,
+    host: `db.${projectRef}.supabase.co`,
+    port: 5432,
+    database: 'postgres',
+  })
   await client.connect()
 
+  let applied = 0, skipped = 0, failed = 0
+
   try {
     await client.query(`
       CREATE TABLE IF NOT EXISTS _spine_migrations (
@@ -82,62 +186,61 @@ export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Pro
         applied_at TIMESTAMPTZ DEFAULT NOW()
       )
     `)
-  } catch { /* non-fatal */ }
 
-  let appliedMigrations = new Set<string>()
-  try {
     const { rows } = await client.query('SELECT filename FROM _spine_migrations')
-    appliedMigrations = new Set(rows.map((r: { filename: string }) => r.filename))
-  } catch { /* non-fatal */ }
+    const appliedMigrations = new Set<string>(rows.map((r: { filename: string }) => r.filename))
 
-  let applied = 0, skipped = 0, failed = 0
-
-  for (const { name, path } of migrationFiles) {
-    if (appliedMigrations.has(name)) {
-      skipped++
-      continue
-    }
+    for (const { name, path } of migrationFiles) {
+      if (appliedMigrations.has(name)) {
+        skipped++
+        continue
+      }
 
-    const sql = readFileSync(path, 'utf8')
-    process.stdout.write(`  Applying ${name}... `)
-    const statements = splitSqlStatements(sql)
+      const sql = readFileSync(path, 'utf8')
+      process.stdout.write(`  Applying ${name}... `)
+      const statements = splitSqlStatements(sql)
 
-    try {
-      await client.query('BEGIN')
-      for (const stmt of statements) await client.query(stmt)
-      await client.query(
-        `INSERT INTO _spine_migrations (filename) VALUES ($1) ON CONFLICT (filename) DO NOTHING`,
-        [name]
-      )
-      await client.query('COMMIT')
-      console.log('✓')
-      applied++
-    } catch (err: any) {
-      await client.query('ROLLBACK').catch(() => {})
-      console.log('✗')
-      console.error(`    ${err.message}`)
-      failed++
+      try {
+        await client.query('BEGIN')
+        for (const stmt of statements) await client.query(stmt)
+        await client.query(
+          `INSERT INTO _spine_migrations (filename) VALUES ($1) ON CONFLICT (filename) DO NOTHING`,
+          [name]
+        )
+        await client.query('COMMIT')
+        console.log('✓')
+        applied++
+      } catch (err: any) {
+        await client.query('ROLLBACK').catch(() => { /* non-fatal */ })
+        console.log('✗')
+        console.error(`    ${err.message}`)
+        failed++
+        break
+      }
     }
+  } finally {
+    await client.end().catch(() => { /* non-fatal */ })
   }
 
-  await client.end()
   return { applied, skipped, failed }
 }
-// CIL[END chunk_id="migrate_runmigrations_1784069813"]
-// CIL[BEGIN chunk_id="migrate_migratecommand_1784069813" type="function" identity="migrateCommand" parent="none"]
-// CIL[DOC-MACRO purpose="Handle migration command execution with validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate environment and orchestrate migration process"]
-// CIL[DOC-CONTEXT module="cli.commands.migrate" layer="cli" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="migration execution" errors="validation errors" side_effects="process exit"]
-// CIL[DOC-MICRO logic_summary="Validates env vars, loads migrations, handles dry-run and execution" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/migrations/015_simplify_apps_table.sql, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Applies pending SQL migration files to the Supabase database and tracks which have been applied.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:runMigrations:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:migrateCommand:function" type="function" identity="migrateCommand" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="CLI action that collects, optionally dry-runs, and applies framework migrations."]
+// CIL[DOC-RESPONSIBILITY responsibility="Validates environment, loads .env, handles dry run, and prints result."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="options: MigrateOptions" outputs="Promise<void>" errors="Exits process with status 1 on missing credentials or failed migrations." side_effects="Reads .env, writes to stdout/stderr, may set process.env, calls process.exit."]
+// CIL[DOC-MICRO logic_summary="Loads .env, verifies SUPABASE_URL and password, collects migration files, dry-run lists them or calls runMigrations, reports counts, and exits." notable_decisions="Supports --db-password, --dry-run, and --framework-only; sets process.env.SUPABASE_DB_PASSWORD if passed; hard exits on missing env or failed migrations."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 async function migrateCommand(options: MigrateOptions): Promise<void> {
   console.log('\nRunning Spine Framework migrations...\n')
 
@@ -210,24 +313,26 @@ async function migrateCommand(options: MigrateOptions): Promise<void> {
 
   console.log('\n✅ All migrations applied successfully!\n')
   console.log('Next steps:')
-  console.log('  npx spine-framework install-app spine-framework-portal@latest')
+  console.log('  npx spine-framework install-app <app-package>')
   console.log('  npm install && npm run assemble && netlify dev\n')
 }
-// CIL[END chunk_id="migrate_migratecommand_1784069813"]
-// CIL[BEGIN chunk_id="migrate_registermigratecommands_1784069813" type="function" identity="registerMigrateCommands" parent="none"]
-// CIL[DOC-MACRO purpose="Register migrate command with CLI program"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide CLI interface for database migrations"]
-// CIL[DOC-CONTEXT module="cli.commands.migrate" layer="cli" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="CLI command registration" errors="command errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Registers migrate command with db-password, dry-run, and framework-only options" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:migrateCommand:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:registerMigrateCommands:function" type="function" identity="registerMigrateCommands" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-VECTOR type="context" content="purpose='CLI action that collects, optionally dry-runs, and applies framework migrations.'; 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[DOC-MACRO purpose="Registers the migrate command with the Commander program."]
+// CIL[DOC-RESPONSIBILITY responsibility="Defines CLI command options and delegates to migrateCommand."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="program: Command" outputs="void" errors="Logs error and exits on action failure." side_effects="Mutates the Commander program with a new command."]
+// CIL[DOC-MICRO logic_summary="Adds the migrate command with --db-password, --dry-run, and --framework-only options and an async action." notable_decisions="Catches action errors, prints messages, and exits on failure; logs stack if SPINE_CLI_DEBUG."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 export function registerMigrateCommands(program: Command) {
   program
     .command('migrate')
@@ -245,21 +350,23 @@ export function registerMigrateCommands(program: Command) {
       }
     })
 }
-// CIL[END chunk_id="migrate_registermigratecommands_1784069813"]
-// CIL[BEGIN chunk_id="migrate_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.migrate" 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: 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='Registers the migrate command with the Commander program.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:registerMigrateCommands:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:loadEnv:function" type="function" identity="loadEnv" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Loads key=value pairs from the project .env file into process.env."]
+// CIL[DOC-RESPONSIBILITY responsibility="Reads .env without overwriting existing environment variables."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="none (reads PROJECT_ROOT/.env)" outputs="void" errors="silently returns if .env is missing" side_effects="Mutates process.env."]
+// CIL[DOC-MICRO logic_summary="Reads .env lines, skips comments and blank lines, parses the first = into key and value, and sets process.env if absent." notable_decisions="Ignores malformed lines; does not overwrite existing environment variables."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
 function loadEnv() {
   const envPath = join(PROJECT_ROOT, '.env')
   if (!existsSync(envPath)) return
@@ -274,22 +381,24 @@ function loadEnv() {
     if (key && !(key in process.env)) process.env[key] = val
   }
 }
-// CIL[END chunk_id="migrate_loadenv_1784069813"]
-// CIL[BEGIN chunk_id="migrate_collectmigrations_1784069813" type="function" identity="collectMigrations" parent="none"]
-// CIL[DOC-MACRO purpose="Collect migration files from framework and custom directories"]
-// CIL[DOC-RESPONSIBILITY responsibility="Find and sort SQL migration files"]
-// CIL[DOC-CONTEXT module="cli.commands.migrate" layer="cli" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="migration file list" errors="filesystem errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Scans .framework/migrations and custom/migrations for .sql files" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Loads key=value pairs from the project .env file into process.env.'; 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"]
-function collectMigrations(frameworkOnly: boolean): { name: string; path: string }[] {
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:loadEnv:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:collectMigrations:function" type="function" identity="collectMigrations" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Collects SQL migration files from framework and custom directories."]
+// CIL[DOC-RESPONSIBILITY responsibility="Sorts and returns file paths for pending migrations, optionally including custom migrations."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="frameworkOnly: boolean" outputs="Array<{ name: string; path: string }>" errors="none" side_effects="Reads directories via readdirSync."]
+// CIL[DOC-MICRO logic_summary="Resolves the framework migrations directory, optionally adds custom/migrations, and returns sorted .sql entries." notable_decisions="Prefers PROJECT_ROOT/.framework/migrations over PACKAGE_ROOT; filters dotfiles and non-.sql files."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
+export function collectMigrations(frameworkOnly: boolean): { name: string; path: string }[] {
   const files: { name: string; path: string }[] = []
 
   
@@ -317,47 +426,81 @@ function collectMigrations(frameworkOnly: boolean): { name: string; path: string
 
   return files
 }
-// CIL[END chunk_id="migrate_collectmigrations_1784069813"]
-// CIL[BEGIN chunk_id="migrate_splitsqlstatements_1784069813" type="function" identity="splitSqlStatements" parent="none"]
-// CIL[DOC-MACRO purpose="Split SQL string into individual statements"]
-// CIL[DOC-RESPONSIBILITY responsibility="Parse SQL migration files into executable statements"]
-// CIL[DOC-CONTEXT module="cli.commands.migrate" layer="cli" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="statement array" errors="parsing errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Handles dollar-quoted blocks, removes comments, splits on semicolons" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_sql_parsing"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Collects SQL migration files from framework and custom 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"]
-function splitSqlStatements(sql: string): string[] {
-  const dollarBlocks: string[] = []
-  let blockIndex = 0
-
-  
-  const protectedSql = sql.replace(/\$[A-Za-z_]*\$[\s\S]*?\$[A-Za-z_]*\$/g, (match) => {
-    const placeholder = `__DOLLAR_BLOCK_${blockIndex}__`
-    dollarBlocks[blockIndex] = match
-    blockIndex++
-    return placeholder
-  })
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:collectMigrations:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:splitSqlStatements:function" type="function" identity="splitSqlStatements" parent="~/.framework/cli/commands/migrate.ts"]
+// CIL[DOC-MACRO purpose="Splits SQL into executable statements while preserving dollar-quoted blocks."]
+// CIL[DOC-RESPONSIBILITY responsibility="Removes single-line comments, splits on semicolons, restores protected dollar-quoted blocks, and returns trimmed statements."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="sql: string" outputs="Array<string>" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Single-pass scanner tracking --, /* */, single-quote, double-quote, and dollar-tag state so ; only splits statements in normal state" notable_decisions="Regex layering was abandoned — apostrophes inside comments and semicolons inside literals broke both orderings; a state machine is the only correct approach."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="engineers"]
+export function splitSqlStatements(sql: string): string[] {
+  // Single-pass scanner: a ; only ends a statement in normal state. Comments
+  // are dropped; string literals, quoted identifiers, and dollar-quoted blocks
+  // are preserved verbatim.
+  const statements: string[] = []
+  let buf = ''
+  let i = 0
+  let inLine = false, inBlock = false, inSingle = false, inDouble = false
+  let dollarTag: string | null = null
+
+  while (i < sql.length) {
+    const ch = sql[i], next = sql[i + 1]
+
+    if (inLine) { if (ch === '\n') inLine = false; i++; continue }
+    if (inBlock) { if (ch === '*' && next === '/') { inBlock = false; i += 2 } else i++; continue }
+
+    if (dollarTag) {
+      if (sql.startsWith(dollarTag, i)) { buf += dollarTag; i += dollarTag.length; dollarTag = null }
+      else { buf += ch; i++ }
+      continue
+    }
+    if (inSingle) {
+      buf += ch
+      if (ch === "'") { if (next === "'") { buf += next; i++ } else inSingle = false }
+      i++; continue
+    }
+    if (inDouble) {
+      buf += ch
+      if (ch === '"') inDouble = false
+      i++; continue
+    }
 
-  
-  const noComments = protectedSql.replace(/--[^\n]*/g, '')
+    if (ch === '-' && next === '-') { inLine = true; i += 2; continue }
+    if (ch === '/' && next === '*') { inBlock = true; i += 2; continue }
+    if (ch === "'") { inSingle = true; buf += ch; i++; continue }
+    if (ch === '"') { inDouble = true; buf += ch; i++; continue }
+    if (ch === '$') {
+      const m = sql.slice(i).match(/^\$[A-Za-z_]*\$/)
+      if (m) { dollarTag = m[0]; buf += m[0]; i += m[0].length; continue }
+    }
+    if (ch === ';') {
+      const s = buf.trim()
+      if (s) statements.push(s + ';')
+      buf = ''
+      i++
+      continue
+    }
+    buf += ch; i++
+  }
 
-  
-  return noComments
-    .split(';')
-    .map(s => {
-      let restored = s.trim()
-      dollarBlocks.forEach((block, idx) => {
-        restored = restored.replace(`__DOLLAR_BLOCK_${idx}__`, () => block)
-      })
-      return restored
-    })
-    .filter(s => s.length > 0)
-    .map(s => s + ';')
+  const tail = buf.trim()
+  if (tail) statements.push(tail + ';')
+  return statements
 }
-// CIL[END chunk_id="migrate_splitsqlstatements_1784069813"]
+// CIL[DOC-VECTOR type="context" content="purpose='Splits SQL into executable statements while preserving dollar-quoted blocks.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:splitSqlStatements:function"]