spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/cli/context.ts

@@ -1,67 +1,113 @@
 // 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="cli_engineers,framework_maintainers"]
+/**
+ * @module   context
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module provides context management for the CLI, facilitating interactions with the core system and user databases. It serves as a foundational component for handling user authentication and data access. INVARIANT: The CoreContext must be initialized before any database operations are performed.
+ *
+ * @seeAlso functions/_shared/index.ts (contains shared core functionalities).
+ * @seeAlso functions/_shared/hash-api-key.ts (provides API key verification logic).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 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"]
+import { verifyApiKey } from '../functions/_shared/hash-api-key.ts'
 // 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"]
+/**
+ * __filename is a constant that holds the absolute path of the current module file, providing a reference to the file location for logging or resolving relative paths.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @calls       fileURLToPath
+ * @cil-generated
+ */
 const __filename = fileURLToPath(import.meta.url)
-// 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"]
+/**
+ * __dirname is a constant that holds the directory name of the current module, allowing for relative file path resolution. It exists to facilitate file operations within the module's directory context.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @calls       dirname
+ * @cil-generated
+ */
 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"]
+/**
+ * Loads environment variables from a specified file into the process environment, ensuring that any variables defined in the file are available to the application at runtime.
+ *
+ * @outputSpec  void
+ * @sideEffects Reads from the file system to load environment variables.
+ * @stability   internal
+ * @calls       resolve, existsSync, readFileSync
+ * @cil-generated
+ */
 function loadEnv() {
   const envPath = resolve(__dirname, '../.xenv')
   if (existsSync(envPath)) {
@@ -79,41 +125,66 @@ function loadEnv() {
     }
   }
 }
-// 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"]
+/**
+ * The CliOptions interface defines the structure for command-line interface options, allowing for optional configuration of an account string. It exists to standardize the way CLI options are handled within the module.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 export interface CliOptions {
   account?: string
 }
-// 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"]
+/**
+ * Builds a CLI context by validating environment variables and retrieving user or API key information. It ensures that the necessary credentials are available for subsequent operations.
+ *
+ * @macro       Async function that constructs a CoreContext for CLI operations.
+ * @micro       Validates environment variables and checks for either an API key or JWT to determine the principal and associated account.
+ * @inputSpec
+ *   opts: CliOptions (optional) — options for building the CLI context.
+ * @outputSpec  Promise<CoreContext> — returns a context object containing principal, accountId, database connection, and requestId.
+ * @throws      Error — Missing required env vars: SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY; Error — Invalid or inactive SPINE_CLI_API_KEY; Error — Invalid or expired SPINE_CLI_JWT
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('api_keys'), adminDb.from('people'), userDb.auth.getUser
+ * @cil-generated
+ */
 export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContext> {
   loadEnv()
 
@@ -129,19 +200,30 @@ export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContex
 
   const apiKey = process.env.SPINE_CLI_API_KEY
   if (apiKey) {
-    const { data: keyRecord } = await adminDb
+    const keyPrefix = apiKey.slice(0, 8)
+
+    const { data: rows, error } = await adminDb
       .from('api_keys')
-      .select('id, account_id, scopes, principal_id')
-      .eq('key_hash', apiKey)
+      .select('id, account_id, scopes, key_hash, expires_at')
+      .eq('key_prefix', keyPrefix)
       .eq('is_active', true)
-      .single()
+      .order('created_at', { ascending: false })
+      .limit(10)
+
+    const now = Date.now()
+    const keyRecord = !error && rows
+      ? rows.find((k: any) =>
+          (!k.expires_at || new Date(k.expires_at).getTime() >= now) &&
+          verifyApiKey(apiKey, k.key_hash)
+        )
+      : undefined
 
     if (!keyRecord) {
       throw new Error('Invalid or inactive SPINE_CLI_API_KEY')
     }
 
     const principal: Principal = {
-      id: keyRecord.principal_id || keyRecord.id,
+      id: keyRecord.id,
       type: 'machine',
       accountId: keyRecord.account_id,
       scopes: keyRecord.scopes || [],
@@ -208,22 +290,38 @@ export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContex
     requestId
   }
 }
-// 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"]
+/**
+ * Prints the result of the given data to the console in a readable format for CLI users. It provides flexibility to display data either as a formatted table or as JSON based on the provided options.
+ *
+ * @macro       Utility function for displaying data in various formats.
+ * @micro       Uses conditional checks to determine the format of the output based on the type of data and options provided.
+ * @inputSpec
+ *   data: any — the data to be printed.
+ *   opts: { json?: boolean } (optional) — options to control the output format.
+ * @outputSpec  void
+ * @sideEffects prints to console
+ * @stability   internal
+ * @calls       console.log, console.table, JSON.stringify
+ * @cil-generated
+ */
 export function printResult(data: any, opts: { json?: boolean } = {}) {
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2))
@@ -243,22 +341,36 @@ export function printResult(data: any, opts: { json?: boolean } = {}) {
     console.log(data)
   }
 }
-// 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"]
+/**
+ * The handleError function logs error messages to the console based on the error type and exits the process. It provides specific messages for known error codes and a general message for other errors.
+ *
+ * @inputSpec
+ *   error: any (required) — the error object to handle.
+ *   context: string (optional) — an optional context string for additional logging.
+ * @outputSpec  none
+ * @sideEffects Logs error messages to the console and exits the process with status code 1.
+ * @stability   internal
+ * @calls       console.error, process.exit
+ * @cil-generated
+ */
 export function handleError(error: any, context?: string) {
   const message = error?.message || String(error)
   const contextStr = context ? `[${context}] ` : ''
@@ -273,10 +385,11 @@ export function handleError(error: any, context?: string) {
   
   process.exit(1)
 }
-// 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/index.ts

@@ -71,6 +71,7 @@ program
 const [
   { registerInitCommands },
   { registerMigrateCommands },
+  { registerBootstrapCommands },
   { registerInstallAppCommands },
   { registerStatusCommands },
   { registerAuthCommands },
@@ -85,10 +86,12 @@ const [
   { registerGenerateCommands },
   { registerCreateAppCommands },
   { registerValidateAppCommands },
+  { registerValidateSchemaCommands },
   { registerUpgradeCommands },
 ] = await Promise.all([
   import('./commands/init.ts'),
   import('./commands/migrate.ts'),
+  import('./commands/bootstrap.ts'),
   import('./commands/install-app.ts'),
   import('./commands/status.ts'),
   import('./commands/auth.ts'),
@@ -103,6 +106,7 @@ const [
   import('./commands/generate.ts'),
   import('./commands/create-app.ts'),
   import('./commands/validate-app.ts'),
+  import('./commands/validate-schema.ts'),
   import('./commands/upgrade.ts'),
 ])
 // CIL[DOC-VECTOR type="context" content="purpose='Dynamically import all CLI command modules'; No verified external callers; imports: .framework/cli/env-loader.ts"]
@@ -122,6 +126,7 @@ const [
 // CIL[DOC-STABILITY stability="stable"]
 registerInitCommands(program)
 registerMigrateCommands(program)
+registerBootstrapCommands(program)
 registerInstallAppCommands(program)
 registerStatusCommands(program)
 registerAuthCommands(program)
@@ -136,6 +141,7 @@ registerSystemCommands(program)
 registerGenerateCommands(program)
 registerCreateAppCommands(program)
 registerValidateAppCommands(program)
+registerValidateSchemaCommands(program)
 registerUpgradeCommands(program)
 // CIL[DOC-VECTOR type="context" content="purpose='Register all CLI commands with the program'; No verified external callers; imports: .framework/cli/env-loader.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]