spine-framework 0.1.0

package/.framework/cli/commands/test.ts

@@ -0,0 +1,227 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/test
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine test` command — unified test runner for all 4 test surfaces.
+ * Runs Vitest tests and persists results to Supabase via the custom reporter.
+ *
+ * **Commands:**
+ * | Subcommand              | Description                                           |
+ * |-------------------------|-------------------------------------------------------|
+ * | `test`                  | Run all test suites                                   |
+ * | `test unit`             | Run unit tests only                                   |
+ * | `test integration`      | Run integration tests only                            |
+ * | `test api`              | Run API tests only                                    |
+ * | `test ui`               | Run UI/Playwright tests only                          |
+ * | `test --json`           | Output structured JSON summary                        |
+ * | `test --watch`          | Run in watch mode (for unit/integration)              |
+ *
+ * **Test surfaces:**
+ * - **unit**: Fast tests, no DB (v2-core/tests/unit/)
+ * - **integration**: DB tests with fixtures (v2-core/tests/integration/)
+ * - **api**: HTTP fetch tests against localhost:8888 (v2-core/tests/api/)
+ * - **ui**: Playwright browser tests (v2-core/tests/ui/)
+ *
+ * **Results:**
+ * All test runs are persisted to `public.test_runs` and `public.test_results`
+ * via the custom Vitest reporter (v2-core/tests/reporter.ts).
+ *
+ * **Usage:**
+ * ```bash
+ * spine test
+ * spine test unit --watch
+ * spine test integration --json
+ * spine test api
+ * spine test ui
+ * ```
+ *
+ * @seeAlso tests/reporter.ts (custom Vitest reporter)
+ * @seeAlso functions/tests.ts (API endpoint for querying results)
+ * @seeAlso pages/admin/TestingDashboard.tsx (UI for viewing results)
+ */
+
+import type { Command } from 'commander'
+import { spawn } from 'child_process'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PROJECT_ROOT = resolve(__dirname, '../../../')
+
+// ─── TYPES ─────────────────────────────────────────────────────────────────
+
+type TestSuite = 'unit' | 'integration' | 'api' | 'ui' | 'all'
+
+// ─── SUITE CONFIGURATION ───────────────────────────────────────────────────
+
+const SUITES: Record<string, { pattern: string; runner: 'vitest' | 'playwright' | 'node' }> = {
+  unit: { pattern: 'v2-core/tests/unit', runner: 'vitest' },
+  integration: { pattern: 'v2-core/tests/integration', runner: 'vitest' },
+  api: { pattern: 'v2-core/tests/api', runner: 'vitest' },
+  ui: { pattern: 'v2-core/tests/ui', runner: 'playwright' }
+}
+
+// ─── COMMAND REGISTRATION ──────────────────────────────────────────────────
+
+export function registerTestCommands(program: Command) {
+  const testCmd = program
+    .command('test [suite]')
+    .description('Run Spine test suites')
+    .option('--json', 'Output as JSON')
+    .option('--watch', 'Watch mode (unit/integration only)')
+    .option('--reporter <name>', 'Vitest reporter', 'default')
+    .action(async (suiteArg: string | undefined, opts) => {
+      const suite: TestSuite = (suiteArg || 'all') as TestSuite
+
+      // Validate suite
+      if (suite !== 'all' && !SUITES[suite]) {
+        console.error(`\n❌ Unknown test suite: ${suite}`)
+        console.log('Valid suites: unit, integration, api, ui, all')
+        process.exit(1)
+      }
+
+      // Determine which suites to run
+      const suitesToRun = suite === 'all'
+        ? ['unit', 'integration', 'api', 'ui']
+        : [suite]
+
+      console.log(`\n🧪 Running Spine test suites: ${suitesToRun.join(', ')}\n`)
+
+      const results: Array<{ suite: string; exitCode: number; passed: boolean }> = []
+
+      for (const s of suitesToRun) {
+        const config = SUITES[s]
+        console.log(`\n▶️  ${s.toUpperCase()} tests (${config.runner})`)
+        console.log('-'.repeat(40))
+
+        try {
+          let exitCode: number
+
+          if (config.runner === 'vitest') {
+            exitCode = await runVitest(s, opts)
+          } else if (config.runner === 'playwright') {
+            exitCode = await runPlaywright(s, opts)
+          } else {
+            exitCode = await runNode(s, opts)
+          }
+
+          results.push({ suite: s, exitCode, passed: exitCode === 0 })
+
+          if (exitCode === 0) {
+            console.log(`✓ ${s} tests passed\n`)
+          } else {
+            console.error(`✗ ${s} tests failed (exit ${exitCode})\n`)
+          }
+
+        } catch (err: any) {
+          console.error(`\n❌ Error running ${s} tests:`, err.message)
+          results.push({ suite: s, exitCode: 1, passed: false })
+        }
+      }
+
+      // Summary
+      console.log('\n' + '='.repeat(50))
+      console.log('Test Run Summary')
+      console.log('='.repeat(50))
+
+      const totalPassed = results.filter(r => r.passed).length
+      const totalFailed = results.filter(r => !r.passed).length
+
+      for (const r of results) {
+        const icon = r.passed ? '✓' : '✗'
+        const status = r.passed ? 'PASSED' : 'FAILED'
+        console.log(`${icon} ${r.suite.padEnd(12)} ${status}`)
+      }
+
+      console.log()
+      console.log(`Total: ${totalPassed} passed, ${totalFailed} failed`)
+
+      // JSON output
+      if (opts.json) {
+        const jsonOutput = {
+          suites: results.map(r => ({
+            suite: r.suite,
+            status: r.passed ? 'passed' : 'failed',
+            exit_code: r.exitCode
+          })),
+          summary: {
+            total: results.length,
+            passed: totalPassed,
+            failed: totalFailed
+          }
+        }
+        console.log('\n' + JSON.stringify(jsonOutput, null, 2))
+      }
+
+      // Exit code
+      process.exit(totalFailed > 0 ? 1 : 0)
+    })
+}
+
+// ─── RUNNER IMPLEMENTATIONS ────────────────────────────────────────────────
+
+async function runVitest(suite: string, opts: any): Promise<number> {
+  const config = SUITES[suite]
+  const args = [
+    'run',
+    config.pattern,
+    '--config', resolve(PROJECT_ROOT, 'vitest.config.ts')
+  ]
+
+  if (opts.watch) {
+    args[0] = 'watch' // Replace 'run' with 'watch'
+  }
+
+  // Custom reporters - include both default and our custom reporter
+  if (opts.reporter === 'default') {
+    args.push('--reporter=default')
+    args.push('--reporter=' + resolve(PROJECT_ROOT, 'v2-core/tests/reporter.ts'))
+  } else {
+    args.push(`--reporter=${opts.reporter}`)
+  }
+
+  return runCommand('npx', ['vitest', ...args], PROJECT_ROOT)
+}
+
+async function runPlaywright(suite: string, opts: any): Promise<number> {
+  // Playwright tests run against a running dev server
+  // We need to ensure the server is running or start it
+  console.log('   (Playwright tests require dev server on localhost:8888)')
+
+  const args = ['playwright', 'test', SUITES[suite].pattern]
+
+  if (opts.json) {
+    args.push('--reporter=json')
+  }
+
+  return runCommand('npx', args, PROJECT_ROOT)
+}
+
+async function runNode(suite: string, opts: any): Promise<number> {
+  // For custom test scripts that aren't Vitest or Playwright
+  const args = [SUITES[suite].pattern]
+  return runCommand('node', args, PROJECT_ROOT)
+}
+
+function runCommand(command: string, args: string[], cwd: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(command, args, {
+      cwd,
+      stdio: 'inherit',
+      env: process.env,
+      shell: true
+    })
+
+    proc.on('exit', (code) => {
+      resolve(code || 0)
+    })
+
+    proc.on('error', (err) => {
+      reject(err)
+    })
+  })
+}

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

@@ -0,0 +1,166 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/uninstall-app
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework uninstall-app <slug>` — Soft-uninstall an app.
+ *
+ * Deactivates the app's types, link types, and triggers in the database.
+ * Does NOT delete data (items, threads, etc.) — those remain for audit.
+ * Does NOT remove filesystem files — the app code stays in custom/apps/.
+ *
+ * To fully remove: manually delete the app directory after uninstall.
+ *
+ * **Usage:**
+ * ```bash
+ * spine-framework uninstall-app cortex
+ * spine-framework uninstall-app cortex --hard   # Also deactivate items
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { adminDb } from '../../functions/_shared/index.ts'
+
+interface UninstallOptions {
+  hard: boolean
+  dryRun: boolean
+}
+
+async function uninstallApp(slug: string, options: UninstallOptions): Promise<void> {
+  console.log(`\n🗑️  Uninstalling app '${slug}'...\n`)
+
+  // 1. Find the app
+  const { data: app, error: appErr } = await adminDb
+    .from('apps')
+    .select('id, name')
+    .eq('slug', slug)
+    .single()
+
+  if (appErr || !app) {
+    console.error(`  ❌ App '${slug}' not found in database`)
+    process.exit(1)
+  }
+
+  const appId = app.id
+
+  // 2. Deactivate types
+  if (options.dryRun) {
+    const { data: types } = await adminDb
+      .from('types').select('slug').eq('app_id', appId).eq('is_active', true)
+    console.log(`  [dry-run] Would deactivate ${types?.length || 0} types`)
+  } else {
+    const { data: updated } = await adminDb
+      .from('types')
+      .update({ is_active: false })
+      .eq('app_id', appId)
+      .eq('is_active', true)
+      .select('id')
+
+    console.log(`  ✓ Deactivated ${updated?.length || 0} types`)
+  }
+
+  // 3. Deactivate link types
+  if (options.dryRun) {
+    const { data: lt } = await adminDb
+      .from('link_types').select('slug').eq('app_id', appId).eq('is_active', true)
+    console.log(`  [dry-run] Would deactivate ${lt?.length || 0} link types`)
+  } else {
+    const { data: updated } = await adminDb
+      .from('link_types')
+      .update({ is_active: false })
+      .eq('app_id', appId)
+      .eq('is_active', true)
+      .select('id')
+
+    console.log(`  ✓ Deactivated ${updated?.length || 0} link types`)
+  }
+
+  // 4. Deactivate triggers
+  if (options.dryRun) {
+    const { data: triggers } = await adminDb
+      .from('triggers').select('name').eq('app_id', appId).eq('is_active', true)
+    console.log(`  [dry-run] Would deactivate ${triggers?.length || 0} triggers`)
+  } else {
+    const { data: updated } = await adminDb
+      .from('triggers')
+      .update({ is_active: false })
+      .eq('app_id', appId)
+      .eq('is_active', true)
+      .select('id')
+
+    console.log(`  ✓ Deactivated ${updated?.length || 0} triggers`)
+  }
+
+  // 5. Hard mode: deactivate items of this app's types
+  if (options.hard) {
+    if (options.dryRun) {
+      const { data: types } = await adminDb
+        .from('types').select('id').eq('app_id', appId)
+      const typeIds = types?.map(t => t.id) || []
+      if (typeIds.length > 0) {
+        const { data: items } = await adminDb
+          .from('items').select('id').in('type_id', typeIds).eq('is_active', true)
+        console.log(`  [dry-run] Would deactivate ${items?.length || 0} items (--hard)`)
+      }
+    } else {
+      const { data: types } = await adminDb
+        .from('types').select('id').eq('app_id', appId)
+      const typeIds = types?.map(t => t.id) || []
+
+      if (typeIds.length > 0) {
+        const { data: updated } = await adminDb
+          .from('items')
+          .update({ is_active: false })
+          .in('type_id', typeIds)
+          .eq('is_active', true)
+          .select('id')
+
+        console.log(`  ✓ Deactivated ${updated?.length || 0} items (--hard)`)
+      }
+    }
+  }
+
+  // 6. Mark installation as disabled
+  if (!options.dryRun) {
+    await adminDb
+      .from('app_installations')
+      .update({ is_enabled: false, updated_at: new Date().toISOString() })
+      .eq('app_slug', slug)
+  }
+
+  // 7. Deactivate app record
+  if (!options.dryRun) {
+    await adminDb
+      .from('apps')
+      .update({ is_active: false })
+      .eq('id', appId)
+
+    console.log(`  ✓ App '${slug}' deactivated`)
+  }
+
+  console.log(`\n✅ App '${app.name}' uninstalled (soft-delete)`)
+  if (!options.hard) {
+    console.log(`   Items created by this app are preserved.`)
+    console.log(`   Use --hard to also deactivate items.`)
+  }
+  console.log(`   App files remain in custom/apps/${slug}/ — delete manually if desired.`)
+}
+
+export function registerUninstallAppCommands(program: Command) {
+  program
+    .command('uninstall-app <slug>')
+    .description('Soft-uninstall an app (deactivate types, triggers, link types)')
+    .option('--hard', 'Also deactivate items created by this app', false)
+    .option('--dry-run', 'Show what would happen without making changes', false)
+    .action(async (slug, opts) => {
+      try {
+        await uninstallApp(slug, opts)
+      } catch (err: any) {
+        console.error('Error:', err.message)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+}

package/.framework/cli/context.ts

@@ -0,0 +1,268 @@
+/// <reference types="node" />
+/**
+ * @module cli/context
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * CLI context builder and output utilities. This is the CLI equivalent of
+ * `createHandler()` in `middleware.ts` — it resolves the principal, picks the
+ * correct Supabase client, and returns a `CoreContext` that every CLI command
+ * passes directly to core functions.
+ *
+ * **Environment variables read from `.xenv` or `process.env`:**
+ * | Variable                  | Required | Purpose                            |
+ * |---------------------------|----------|------------------------------------|
+ * | `SUPABASE_URL`            | yes      | Project API URL                    |
+ * | `SUPABASE_SERVICE_ROLE_KEY` | yes    | Service-role client (admin ops)    |
+ * | `SUPABASE_ANON_KEY`       | yes      | User-scoped client (JWT mode)      |
+ * | `SPINE_CLI_ACCOUNT_ID`    | no       | Default account scope              |
+ * | `SPINE_CLI_JWT`           | no       | Human principal (Supabase JWT)     |
+ * | `SPINE_CLI_API_KEY`       | no       | Machine principal (hashed key)     |
+ * | `SPINE_CLI_DEBUG`         | no       | Print stack traces on error        |
+ *
+ * **Principal resolution priority** (first match wins):
+ * 1. `SPINE_CLI_JWT` → human principal (RLS-scoped `getUserDb`)
+ * 2. `SPINE_CLI_API_KEY` → machine principal (`adminDb`)
+ * 3. Fallback → `SYSTEM_PRINCIPAL` (`adminDb` — admin ops only)
+ *
+ * @seeAlso functions/_shared/middleware.ts (createHandler — server-side equivalent)
+ * @seeAlso functions/_shared/principal.ts (Principal type and SYSTEM_PRINCIPAL)
+ * @seeAlso cli/index.ts (entry point that imports all commands)
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { CoreContext, adminDb, SYSTEM_PRINCIPAL, Principal, getUserDb } from '../functions/_shared/index.ts'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// ─── ENV LOADING ────────────────────────────────────────────────────────────
+
+// ─── CHUNK_START: CLI_CONTEXT_LOAD_ENV ──────────────────────────────────────────────
+/**
+ * @chunk-id    CLI_CONTEXT_LOAD_ENV_1_0_0
+ * @version     1.0.0
+ * @hash        0adefa52a0c93821ee538ffe32a4069061bd75e7cada7175b11be3e11027e369
+ * @macro       Environment Variable Loader
+ * @micro       Reads .xenv file and populates process.env with missing vars
+ * @inputs      none — reads from .xenv file path
+ * @outputs     void — mutates process.env
+ * @depends-on  [fs, path]
+ * @depended-by [buildCliContext]
+ * @side-effects [mutates process.env, file system reads]
+ * @tags        environment, configuration, cli, dotenv
+ */
+function loadEnv() {
+  const envPath = resolve(__dirname, '../.xenv')
+  if (existsSync(envPath)) {
+    const lines = readFileSync(envPath, 'utf8').split('\n')
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const eqIdx = trimmed.indexOf('=')
+      if (eqIdx === -1) continue
+      const key = trimmed.slice(0, eqIdx).trim()
+      const value = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '')
+      if (!process.env[key]) {
+        process.env[key] = value
+      }
+    }
+  }
+}
+// ─── CHUNK_END: CLI_CONTEXT_LOAD_ENV ────────────────────────────────────────────────
+
+// ─── TYPES ──────────────────────────────────────────────────────────────────
+
+/**
+ * Options passed from CLI command `.action()` callbacks to `buildCliContext`.
+ *
+ * @inputSpec account: string | undefined — UUID of the target account; overrides
+ *   `SPINE_CLI_ACCOUNT_ID` if both are present.
+ * @calledBy All `registerXxxCommands` functions before calling core functions
+ */
+export interface CliOptions {
+  account?: string
+}
+
+// ─── CONTEXT BUILDER ─────────────────────────────────────────────────────────
+
+// ─── CHUNK_START: CLI_CONTEXT_BUILD ──────────────────────────────────────────────
+/**
+ * @chunk-id    CLI_CONTEXT_BUILD_1_0_0
+ * @version     1.0.0
+ * @hash        501162983b1b24e9a15267ca7b8398b3733f540b2a65a96d8277ec3d780f2003
+ * @macro       CLI Context Builder
+ * @micro       Constructs CoreContext with principal resolution and Supabase client
+ * @inputs      opts: CliOptions — Optional overrides including account ID
+ * @outputs     CoreContext — Fully resolved context with principal, DB client, and request ID
+ * @depends-on  [loadEnv, adminDb, getUserDb, SYSTEM_PRINCIPAL]
+ * @depended-by [All CLI command handlers]
+ * @side-effects [DB queries, environment reads, crypto.randomUUID]
+ * @tags        cli, authentication, principal-resolution, context
+ */
+export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContext> {
+  loadEnv()
+
+  if (!process.env.SUPABASE_URL || !process.env.SUPABASE_SERVICE_ROLE_KEY) {
+    throw new Error(
+      'Missing required env vars: SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.\n' +
+      'Set them in v2-core/.xenv or export them before running spine commands.'
+    )
+  }
+
+  const accountId = opts.account || process.env.SPINE_CLI_ACCOUNT_ID || null
+  const requestId = crypto.randomUUID()
+
+  // Machine API key auth
+  const apiKey = process.env.SPINE_CLI_API_KEY
+  if (apiKey) {
+    const { data: keyRecord } = await adminDb
+      .from('api_keys')
+      .select('id, account_id, scopes, principal_id')
+      .eq('key_hash', apiKey)
+      .eq('is_active', true)
+      .single()
+
+    if (!keyRecord) {
+      throw new Error('Invalid or inactive SPINE_CLI_API_KEY')
+    }
+
+    const principal: Principal = {
+      id: keyRecord.principal_id || keyRecord.id,
+      type: 'machine',
+      accountId: keyRecord.account_id,
+      scopes: keyRecord.scopes || [],
+      provenance: {
+        sourceType: 'api_key',
+        createdBy: null,
+        apiKeyId: keyRecord.id,
+        invokedAt: new Date().toISOString()
+      }
+    }
+
+    return {
+      principal,
+      accountId: accountId || keyRecord.account_id,
+      db: adminDb,
+      requestId
+    }
+  }
+
+  // JWT auth (human principal)
+  const jwt = process.env.SPINE_CLI_JWT
+  if (jwt) {
+    const userDb = getUserDb(jwt)
+    const { data: { user } } = await userDb.auth.getUser()
+
+    if (!user) {
+      throw new Error('Invalid or expired SPINE_CLI_JWT')
+    }
+
+    const { data: person } = await adminDb
+      .from('people')
+      .select('id, full_name, email, roles:people_roles(role:roles(slug))')
+      .eq('auth_user_id', user.id)
+      .single()
+
+    const roles = (person?.roles as any[])?.map((r: any) => r.role?.slug).filter(Boolean) || []
+
+    const principal: Principal = {
+      id: person?.id || user.id,
+      type: 'human',
+      accountId: accountId,
+      displayName: person?.full_name || user.email,
+      email: person?.email || user.email,
+      roles,
+      provenance: {
+        sourceType: 'jwt',
+        createdBy: person?.id || user.id,
+        invokedAt: new Date().toISOString()
+      },
+      authContext: { jwt }
+    }
+
+    return {
+      principal,
+      accountId,
+      db: userDb,
+      requestId
+    }
+  }
+
+  // Fallback: system principal (admin ops)
+  return {
+    principal: SYSTEM_PRINCIPAL,
+    accountId,
+    db: adminDb,
+    requestId
+  }
+}
+// ─── CHUNK_END: CLI_CONTEXT_BUILD ────────────────────────────────────────────────
+
+// ─── OUTPUT UTILITIES ─────────────────────────────────────────────────────────
+
+// ─── CHUNK_START: CLI_CONTEXT_PRINT_RESULT ──────────────────────────────────────────────
+/**
+ * @chunk-id    CLI_CONTEXT_PRINT_RESULT_1_0_0
+ * @version     1.0.0
+ * @hash        06e492defa9012290a5c8b2d4fca27f01df11bdc194ffbdf4f4b4518aa683c2b
+ * @macro       CLI Output Formatter
+ * @micro       Pretty-prints query results as JSON or ASCII tables
+ * @inputs      data: any — Result data to display (array or single value)
+ * @inputs      opts: { json?: boolean } — Output format options
+ * @outputs     void — Console output only
+ * @depends-on  [console, JSON]
+ * @depended-by [All CLI command list/get handlers]
+ * @side-effects [console.log output]
+ * @tags        cli, output, formatting, tables, json
+ */
+export function printResult(data: any, opts: { json?: boolean } = {}) {
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      console.log('(no results)')
+      return
+    }
+    const keys = Object.keys(data[0])
+    const rows = data.map(row => keys.map(k => String(row[k] ?? '')))
+    const widths = keys.map((k, i) => Math.max(k.length, ...rows.map(r => r[i].length)))
+    const hr = widths.map(w => '-'.repeat(w)).join('  ')
+    console.log(keys.map((k, i) => k.padEnd(widths[i])).join('  '))
+    console.log(hr)
+    rows.forEach(row => console.log(row.map((v, i) => v.padEnd(widths[i])).join('  ')))
+    console.log(`\n(${data.length} row${data.length !== 1 ? 's' : ''})`)
+  } else {
+    console.log(JSON.stringify(data, null, 2))
+  }
+}
+// ─── CHUNK_END: CLI_CONTEXT_PRINT_RESULT ────────────────────────────────────────────────
+
+// ─── CHUNK_START: CLI_CONTEXT_HANDLE_ERROR ──────────────────────────────────────────────
+/**
+ * @chunk-id    CLI_CONTEXT_HANDLE_ERROR_1_0_0
+ * @version     1.0.0
+ * @hash        61aca7e4bce61b5b790e8f27ef3f505a6a6fe9a8cd6643e577f610d9dd15b1cd
+ * @macro       CLI Error Handler
+ * @micro       Prints formatted error and exits with proper debug information
+ * @inputs      err: any — Error object or string message
+ * @outputs     void — Process termination (exit code 1)
+ * @depends-on  [console, process]
+ * @depended-by [All CLI command action handlers]
+ * @side-effects [console.error output, process.exit]
+ * @tags        cli, error-handling, debug, process-exit
+ */
+export function handleError(err: any) {
+  console.error(`\nError: ${err.message || err}`)
+  if (process.env.SPINE_CLI_DEBUG) {
+    console.error(err.stack)
+  }
+  process.exit(1)
+}
+// ─── CHUNK_END: CLI_CONTEXT_HANDLE_ERROR ────────────────────────────────────────────────

package/.framework/cli/env-loader.ts

@@ -0,0 +1,36 @@
+/// <reference types="node" />
+/**
+ * @module cli/env-loader
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * Side-effect module: loads `v2-core/.xenv` into `process.env` before any
+ * other CLI module is imported. Must be the first import in `cli/index.ts`
+ * so that `db.ts` (which reads env vars at module-load time) sees the values.
+ *
+ * @sideEffects Mutates process.env — only sets keys not already present
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const envPath = resolve(__dirname, '../.xenv')
+if (existsSync(envPath)) {
+  const lines = readFileSync(envPath, 'utf8').split('\n')
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    const value = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '')
+    if (!process.env[key]) {
+      process.env[key] = value
+    }
+  }
+}