spine-framework 0.3.145 → 0.4.1

package/.framework/cli/context.ts

@@ -1,45 +1,67 @@
-
-
-
-
-
-// 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[BEGIN stable_id="~/.framework/cli/context.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Defines shared CLI runtime context and helpers for spine commands."]
+// CIL[DOC-RESPONSIBILITY responsibility="Initialize CLI execution context, load environment, and expose result formatting and error handling helpers."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="command-line options and environment variables" outputs="CoreContext, formatted output, error handling" errors="Throws when required Supabase env vars are missing" side_effects="Reads .xenv and process.env"]
+// CIL[DOC-MICRO logic_summary="Imports dependencies, sets up ESM-compatible path constants, builds a CoreContext from env/JWT/API key, and provides output/error formatting." notable_decisions="Defaults to SYSTEM_PRINCIPAL; prioritizes API key auth over JWT over anonymous."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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"]
+// CIL[DOC-AUDIENCE audience="cli_engineers,framework_maintainers"]
+
 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'
+// CIL[DOC-VECTOR type="context" content="purpose='Defines shared CLI runtime context and helpers for spine commands.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:module_header:module_header"]
 
+// CIL[BEGIN stable_id="~/.framework/cli/context.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Provides an ESM-compatible __filename constant for this module."]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve the current source file path from import.meta.url."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="import.meta.url" outputs="string absolute file path" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Converts the module's URL to a file path with fileURLToPath." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-// 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-VECTOR type="context" content="purpose='Provides an ESM-compatible __filename constant for this module.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:__filename:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/context.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Provides an ESM-compatible __dirname constant for this module."]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve the directory containing this source file."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="__filename" outputs="string absolute directory path" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Derives the parent directory of __filename using the dirname helper." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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."]
+const __dirname = dirname(__filename)
+// CIL[DOC-VECTOR type="context" content="purpose='Provides an ESM-compatible __dirname constant for this module.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:__dirname:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/context.ts:loadEnv:function" type="function" identity="loadEnv" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Loads local environment overrides from a .xenv file."]
+// CIL[DOC-RESPONSIBILITY responsibility="Read the framework .xenv file and populate process.env without overwriting existing values."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs=".xenv file in the framework parent directory" outputs="Updated process.env" errors="none" side_effects="Mutates process.env for missing keys only"]
+// CIL[DOC-MICRO logic_summary="Resolves .xenv, reads its lines, ignores blank or comment lines, parses KEY=VALUE pairs, strips surrounding quotes, and sets only missing keys." notable_decisions="Existing process.env values are intentionally not overwritten."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function loadEnv() {
   const envPath = resolve(__dirname, '../.xenv')
   if (existsSync(envPath)) {
@@ -57,39 +79,41 @@ function loadEnv() {
     }
   }
 }
-// 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="context" content="purpose='Loads local environment overrides from a .xenv file.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:loadEnv:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/context.ts:CliOptions:interface" type="interface" identity="CliOptions" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Declares the shape of options passed to CLI context builders."]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the optional account parameter used by CLI commands."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="N/A" outputs="TypeScript interface" errors="N/A" side_effects="N/A"]
+// CIL[DOC-MICRO logic_summary="Contains an optional account property for scoping CLI invocations." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface CliOptions {
   account?: string
 }
-// 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="context" content="purpose='Declares the shape of options passed to CLI context builders.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:CliOptions:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/context.ts:buildCliContext:function" type="function" identity="buildCliContext" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Constructs a CoreContext for spine CLI commands from environment or credentials."]
+// CIL[DOC-RESPONSIBILITY responsibility="Load environment, validate required Supabase variables, resolve account/request IDs, authenticate via API key or JWT, and return a CoreContext."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="opts: CliOptions = {}" outputs="Promise<CoreContext>" errors="Throws if SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY are missing; throws on invalid API key or JWT" side_effects="Reads process.env; queries Supabase; calls crypto.randomUUID"]
+// CIL[DOC-MICRO logic_summary="Loads .xenv, asserts required Supabase env, picks account and request IDs, attempts API key auth, then JWT auth, then falls back to SYSTEM_PRINCIPAL." notable_decisions="API key auth takes precedence over JWT; account is resolved from opts, SPINE_CLI_ACCOUNT_ID, or the authenticated key record."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContext> {
   loadEnv()
 
@@ -184,21 +208,22 @@ export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContex
     requestId
   }
 }
-// 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="context" content="purpose='Constructs a CoreContext for spine CLI commands from environment or credentials.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:buildCliContext:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/context.ts:printResult:function" type="function" identity="printResult" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Prints CLI command results to stdout in human-readable or JSON form."]
+// CIL[DOC-RESPONSIBILITY responsibility="Format and emit command results based on the json option."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="data, opts" outputs="Formatted output to stdout" errors="none" side_effects="Writes to stdout"]
+// CIL[DOC-MICRO logic_summary="Takes data and opts. If opts.json is true, pretty-prints JSON; otherwise prints arrays as tables, objects as JSON, and primitives as plain text. Empty arrays print 'No results found.'" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function printResult(data: any, opts: { json?: boolean } = {}) {
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2))
@@ -218,21 +243,22 @@ export function printResult(data: any, opts: { json?: boolean } = {}) {
     console.log(data)
   }
 }
-// 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="context" content="purpose='Prints CLI command results to stdout in human-readable or JSON form.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:printResult:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/context.ts:handleError:function" type="function" identity="handleError" parent="~/.framework/cli/context.ts"]
+// CIL[DOC-MACRO purpose="Prints a friendly error message for known failure codes and exits the process."]
+// CIL[DOC-RESPONSIBILITY responsibility="Map known Postgres/Supabase error codes to readable messages and terminate with exit code 1."]
+// CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="error, context" outputs="Error message to stderr and process termination" errors="none" side_effects="Writes to stderr; calls process.exit(1)"]
+// CIL[DOC-MICRO logic_summary="Takes error and optional context. Extracts the message, prefixes with context when provided, maps PGRST116 to not-found and PGRST301 to permission-denied, prints the message, and exits." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function handleError(error: any, context?: string) {
   const message = error?.message || String(error)
   const contextStr = context ? `[${context}] ` : ''
@@ -247,4 +273,10 @@ export function handleError(error: any, context?: string) {
   
   process.exit(1)
 }
-// CIL[END chunk_id="context_handleerror_1784068794"]
+// CIL[DOC-VECTOR type="context" content="purpose='Prints a friendly error message for known failure codes and exits the process.'; No verified external callers; imports: .framework/functions/_shared/index.ts"]
+// 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/context.ts:handleError:function"]

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

@@ -1,41 +1,65 @@
-
-
-// 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[BEGIN stable_id="~/.framework/cli/env-loader.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/env-loader.ts"]
+// CIL[DOC-MACRO purpose="CLI environment file loader module entry point"]
+// CIL[DOC-RESPONSIBILITY responsibility="Initialize file system and path utilities and resolve environment files"]
+// CIL[DOC-CONTEXT module="env-loader" layer="cli" related_files=".framework/cli/env-loader.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="loaded environment variables in process.env" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Module-level imports for fs, path, and url helpers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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"]
+// CIL[DOC-AUDIENCE audience="cli"]
 import { readFileSync, existsSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
+// CIL[DOC-VECTOR type="context" content="purpose='CLI environment file loader module entry point'; 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/env-loader.ts:module_header:module_header"]
 
+// CIL[BEGIN stable_id="~/.framework/cli/env-loader.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/env-loader.ts"]
+// CIL[DOC-MACRO purpose="Resolve the current module file path"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide __filename equivalent for ESM modules"]
+// CIL[DOC-CONTEXT module="env-loader" layer="cli" related_files=".framework/cli/env-loader.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="__filename string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Convert import.meta.url to a file path" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 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-VECTOR type="context" content="purpose='Resolve 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[END stable_id="~/.framework/cli/env-loader.ts:__filename:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/env-loader.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/env-loader.ts"]
+// CIL[DOC-MACRO purpose="Resolve the current module directory path"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide __dirname equivalent for ESM modules"]
+// CIL[DOC-CONTEXT module="env-loader" layer="cli" related_files=".framework/cli/env-loader.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="__dirname string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Derive the directory name from __filename" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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."]
+const __dirname = dirname(__filename)
+// CIL[DOC-VECTOR type="context" content="purpose='Resolve the current module directory 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/env-loader.ts:__dirname:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/env-loader.ts:loadEnvFile:function" type="function" identity="loadEnvFile" parent="~/.framework/cli/env-loader.ts"]
+// CIL[DOC-MACRO purpose="Parse and load key-value pairs from a .env file into process.env"]
+// CIL[DOC-RESPONSIBILITY responsibility="Read environment files and populate process.env for missing keys"]
+// CIL[DOC-CONTEXT module="env-loader" layer="cli" related_files=".framework/cli/env-loader.ts"]
+// CIL[DOC-CONTRACT inputs="envPath: string" outputs="process.env updated with new key-value pairs" errors="none" side_effects="mutates process.env"]
+// CIL[DOC-MICRO logic_summary="Read .env file, parse KEY=VALUE lines, skip comments and blanks, strip quotes, and set process.env only for unset keys" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function loadEnvFile(envPath: string) {
   if (!existsSync(envPath)) return
   const lines = readFileSync(envPath, 'utf8').split('\n')
@@ -51,22 +75,29 @@ function loadEnvFile(envPath: string) {
     }
   }
 }
-// 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="context" content="purpose='Parse and load key-value pairs from a .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"]
+// CIL[END stable_id="~/.framework/cli/env-loader.ts:loadEnvFile:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/env-loader.ts:env_loader_init:expression" type="function" identity="env_loader_init" parent="~/.framework/cli/env-loader.ts"]
+// CIL[DOC-MACRO purpose="Execute environment loading for the CLI at startup"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load .env files from project root and framework directory"]
+// CIL[DOC-CONTEXT module="env-loader" layer="cli" related_files=".framework/cli/env-loader.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="process.env populated from .env and .xenv files" errors="none" side_effects="calls loadEnvFile and mutates process.env"]
+// CIL[DOC-MICRO logic_summary="Invoke loadEnvFile for .env in process.cwd and .xenv in the framework directory" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 loadEnvFile(resolve(process.cwd(), '.env'))
 
 loadEnvFile(resolve(__dirname, '../.xenv'))
-// CIL[END chunk_id="env-loader_execution_1784068794"]
+// CIL[DOC-VECTOR type="context" content="purpose='Execute environment loading for the CLI at startup'; 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/env-loader.ts:env_loader_init:expression"]