spine-framework 0.3.124 → 0.3.126

package/.framework/cli/context.ts

@@ -1,36 +1,23 @@
-/// <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)
- */
 
+
+
+
+
+// CIL[BEGIN chunk_id="context_moduleheader_1784068794" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies and set up directory paths"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load required modules and configure paths"]
+// CIL[DOC-CONTEXT module="cli" layer="context" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="loaded_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports file system, path utilities, and shared functions" 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: context. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { readFileSync, existsSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
@@ -38,23 +25,21 @@ import { CoreContext, adminDb, SYSTEM_PRINCIPAL, Principal, getUserDb } from '..
 
 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
- */
+// CIL[END chunk_id="context_moduleheader_1784068794"]
+// CIL[BEGIN chunk_id="context_loadenv_1784068794" type="function" identity="loadEnv" parent="none"]
+// CIL[DOC-MACRO purpose="Load environment variables from .xenv file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Parse and set environment variables"]
+// CIL[DOC-CONTEXT module="cli" layer="context" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="process_env" errors="file_read_errors" side_effects="process_env_modification"]
+// CIL[DOC-MICRO logic_summary="Reads .xenv file and sets non-existent environment variables" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: context. 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function loadEnv() {
   const envPath = resolve(__dirname, '../.xenv')
   if (existsSync(envPath)) {
@@ -72,37 +57,39 @@ function loadEnv() {
     }
   }
 }
-// ─── 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
- */
+// CIL[END chunk_id="context_loadenv_1784068794"]
+// CIL[BEGIN chunk_id="interface_clioptions_1784068794" type="interface" identity="CliOptions" parent="none"]
+// CIL[DOC-MACRO purpose="Define CLI options interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for CLI configuration"]
+// CIL[DOC-CONTEXT module="cli" layer="context" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="type_definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface for optional account override parameter" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: context. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export 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
- */
+// CIL[END chunk_id="interface_clioptions_1784068794"]
+// CIL[BEGIN chunk_id="context_buildclicontext_1784068794" type="function" identity="buildCliContext" parent="none"]
+// CIL[DOC-MACRO purpose="Build CLI context with authentication and database"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create authenticated context for CLI operations"]
+// CIL[DOC-CONTEXT module="cli" layer="context" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="core_context" errors="auth_errors" side_effects="database_queries"]
+// CIL[DOC-MICRO logic_summary="Handles API key, JWT, or system authentication with proper principal setup" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: context. Direct callers: 2. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 2. Total affected: 2."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContext> {
   loadEnv()
 
@@ -116,7 +103,6 @@ export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContex
   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
@@ -151,7 +137,6 @@ export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContex
     }
   }
 
-  // JWT auth (human principal)
   const jwt = process.env.SPINE_CLI_JWT
   if (jwt) {
     const userDb = getUserDb(jwt)
@@ -192,7 +177,6 @@ export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContex
     }
   }
 
-  // Fallback: system principal (admin ops)
   return {
     principal: SYSTEM_PRINCIPAL,
     accountId,
@@ -200,25 +184,21 @@ export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContex
     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
- */
+// CIL[END chunk_id="context_buildclicontext_1784068794"]
+// CIL[BEGIN chunk_id="context_printresult_1784068794" type="function" identity="printResult" parent="none"]
+// CIL[DOC-MACRO purpose="Format and display CLI output data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle result formatting for CLI output"]
+// CIL[DOC-CONTEXT module="cli" layer="context" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="console_output" errors="none" side_effects="console_io"]
+// CIL[DOC-MICRO logic_summary="Formats data as JSON, table, or raw text based on type and 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: context. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function printResult(data: any, opts: { json?: boolean } = {}) {
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2))
@@ -227,42 +207,44 @@ export function printResult(data: any, opts: { json?: boolean } = {}) {
 
   if (Array.isArray(data)) {
     if (data.length === 0) {
-      console.log('(no results)')
+      console.log('No results found.')
       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.table(data)
+  } else if (data && typeof data === 'object') {
     console.log(JSON.stringify(data, null, 2))
+  } else {
+    console.log(data)
   }
 }
-// ─── 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)
+// CIL[END chunk_id="context_printresult_1784068794"]
+// CIL[BEGIN chunk_id="context_handleerror_1784068794" type="function" identity="handleError" parent="none"]
+// CIL[DOC-MACRO purpose="Handle and format CLI errors with context"]
+// CIL[DOC-RESPONSIBILITY responsibility="Process and display error messages appropriately"]
+// CIL[DOC-CONTEXT module="cli" layer="context" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="error_output" errors="none" side_effects="process_exit"]
+// CIL[DOC-MICRO logic_summary="Formats PostgREST errors and exits process with error code" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: context. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+export function handleError(error: any, context?: string) {
+  const message = error?.message || String(error)
+  const contextStr = context ? `[${context}] ` : ''
+  
+  if (error?.code === 'PGRST116') {
+    console.error(`${contextStr}Not found: The requested resource does not exist.`)
+  } else if (error?.code === 'PGRST301') {
+    console.error(`${contextStr}Permission denied: You don't have access to this resource.`)
+  } else {
+    console.error(`${contextStr}${message}`)
   }
+  
   process.exit(1)
 }
-// ─── CHUNK_END: CLI_CONTEXT_HANDLE_ERROR ────────────────────────────────────────────────
+// CIL[END chunk_id="context_handleerror_1784068794"]

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

@@ -1,24 +1,41 @@
-/// <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
- */
 
+
+// CIL[BEGIN chunk_id="env-loader_moduleheader_1784068794" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import file system and path utilities"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load required modules for file operations"]
+// CIL[DOC-CONTEXT module="cli" layer="environment" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="loaded_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports file system, path utilities, and URL handling" 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: environment. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { readFileSync, existsSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
-
+// CIL[END chunk_id="env-loader_moduleheader_1784068794"]
+// CIL[BEGIN chunk_id="env-loader_loadenvfile_1784068794" type="function" identity="loadEnvFile" parent="none"]
+// CIL[DOC-MACRO purpose="Load environment variables from a file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Parse and set environment variables from file"]
+// CIL[DOC-CONTEXT module="cli" layer="environment" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="process_env" errors="file_read_errors" side_effects="process_env_modification"]
+// CIL[DOC-MICRO logic_summary="Reads env file, parses key=value pairs, sets non-existent variables" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: environment. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/principal.ts, .framework/migrations/015_simplify_apps_table.sql, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function loadEnvFile(envPath: string) {
   if (!existsSync(envPath)) return
   const lines = readFileSync(envPath, 'utf8').split('\n')
@@ -34,10 +51,22 @@ function loadEnvFile(envPath: string) {
     }
   }
 }
-
-// 1. Load project .env first (process.cwd() = the developer's project root)
-//    This must happen before any module that reads env vars at import time (e.g. _shared/db.ts)
+// CIL[END chunk_id="env-loader_loadenvfile_1784068794"]
+// CIL[BEGIN chunk_id="env-loader_execution_1784068794" type="block" identity="env_loading" parent="none"]
+// CIL[DOC-MACRO purpose="Load environment files on module import"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute environment loading for CLI"]
+// CIL[DOC-CONTEXT module="cli" layer="environment" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="env_variables_loaded" errors="none" side_effects="process_env_modification"]
+// CIL[DOC-MICRO logic_summary="Loads local .env and framework .xenv files in order" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: environment. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.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"]
 loadEnvFile(resolve(process.cwd(), '.env'))
 
-// 2. Load framework's own .xenv (lower priority — project .env wins)
 loadEnvFile(resolve(__dirname, '../.xenv'))
+// CIL[END chunk_id="env-loader_execution_1784068794"]

package/.framework/cli/index.ts

@@ -1,43 +1,39 @@
-#!/usr/bin/env node
-/// <reference types="node" />
-/**
- * @module cli/index
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * Spine CLI entry point (`npx spine-framework`). Registers all command groups via
- * Commander and delegates each subcommand to the same core logic used by
- * API handlers and direct imports. No business logic lives here — only
- * command registration and top-level error handling.
- *
- * **Command groups registered:**
- * | Group       | File                       |
- * |-------------|----------------------------|
- * | auth        | commands/auth.ts           |
- * | pipelines   | commands/pipelines.ts      |
- * | items       | commands/items.ts          |
- * | agents      | commands/agents.ts         |
- * | migrations  | commands/migrations.ts     |
- *
- * **Usage:**
- * ```bash
- * npx spine-framework --help
- * npx spine-framework auth whoami
- * npx spine-framework pipelines run <id> --data '{"key":"value"}'
- * npx spine-framework items list --type support_ticket
- * npx spine-framework items get <id>
- * npx spine-framework agents run <thread-id> --message "Hello"
- * npx spine-framework migrations list
- * ```
- *
- * @seeAlso cli/context.ts (buildCliContext — constructs CoreContext for every command)
- * @seeAlso functions/_shared/index.ts (core functions exposed to CLI)
- */
 
+
+
+
+// CIL[BEGIN chunk_id="index_moduleheader_1784068794" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import CLI dependencies and environment loader"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load required modules for CLI setup"]
+// CIL[DOC-CONTEXT module="cli" layer="entry" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="loaded_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports environment loader and Commander.js" 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: entry. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import './env-loader.ts'
 import { Command } from 'commander'
-
+// CIL[END chunk_id="index_moduleheader_1784068794"]
+// CIL[BEGIN chunk_id="index_program_1784068794" type="variable" identity="program" parent="none"]
+// CIL[DOC-MACRO purpose="Initialize CLI program with basic configuration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure main CLI program instance"]
+// CIL[DOC-CONTEXT module="cli" layer="entry" 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="configured_program" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Creates Commander program with name, description, version, and account option" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: entry. 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[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const program = new Command()
 
 program
@@ -45,7 +41,21 @@ program
   .description('Spine Framework CLI — install, migrate, and manage your Spine instance')
   .version('2.0.0')
   .option('--account <id>', 'Override the account ID for this command')
-
+// CIL[END chunk_id="index_program_1784068794"]
+// CIL[BEGIN chunk_id="index_imports_1784068794" type="block" identity="command_imports" parent="none"]
+// CIL[DOC-MACRO purpose="Dynamically import all CLI command modules"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load command registration functions"]
+// CIL[DOC-CONTEXT module="cli" layer="entry" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="command_modules" errors="import_failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses Promise.all to parallel import all command modules" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: entry. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const [
   { registerInitCommands },
   { registerMigrateCommands },
@@ -79,7 +89,21 @@ const [
   import('./commands/generate.ts'),
   import('./commands/create-app.ts'),
 ])
-
+// CIL[END chunk_id="index_imports_1784068794"]
+// CIL[BEGIN chunk_id="index_registrations_1784068794" type="block" identity="command_registrations" parent="none"]
+// CIL[DOC-MACRO purpose="Register all CLI commands with the program"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure CLI with all available commands"]
+// CIL[DOC-CONTEXT module="cli" layer="entry" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="registered_commands" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Calls each command registration function with the program instance" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: entry. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 registerInitCommands(program)
 registerMigrateCommands(program)
 registerInstallAppCommands(program)
@@ -95,8 +119,23 @@ registerTestCommands(program)
 registerSystemCommands(program)
 registerGenerateCommands(program)
 registerCreateAppCommands(program)
-
-program.parseAsync(process.argv).catch((err) => {
-  console.error('Error:', err.message)
+// CIL[END chunk_id="index_registrations_1784068794"]
+// CIL[BEGIN chunk_id="index_parseasync_1784068794" type="block" identity="error_handling" parent="none"]
+// CIL[DOC-MACRO purpose="Parse CLI arguments and handle errors"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute CLI and handle uncaught errors"]
+// CIL[DOC-CONTEXT module="cli" layer="entry" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="command_execution" errors="cli_errors" side_effects="process_exit"]
+// CIL[DOC-MICRO logic_summary="Parses async command line arguments and exits on error" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: entry. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+program.parseAsync(process.argv).catch((error) => {
+  console.error('CLI Error:', error.message)
   process.exit(1)
 })
+// CIL[END chunk_id="index_parseasync_1784068794"]