spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/cli/commands/validate-schema.ts

@@ -0,0 +1,147 @@
+// validate-schema — standalone design_schema validator.
+//
+// Ported from .framework/mcp/tools/architect.ts (the retired Spine MCP
+// architect tools) so `spine-schema` and CI have a runnable validator without
+// the MCP server. `validate-app` covers app packages (manifest/package.json/
+// structure) — this command covers a single design_schema JSON file.
+
+import type { Command } from 'commander'
+import { readFileSync, existsSync } from 'fs'
+import { resolve } from 'path'
+
+const DATA_TYPES = new Set([
+  'text', 'textarea', 'rich_text', 'email', 'phone', 'url', 'number', 'currency', 'range',
+  'date', 'datetime', 'boolean', 'checkbox', 'select', 'multiselect', 'radio', 'color',
+  'file', 'image', 'json', 'reference', 'address',
+])
+
+const DISPLAY_TYPES = new Set([
+  'text', 'input', 'textarea', 'rich_text', 'select', 'multiselect', 'radio', 'checkbox',
+  'switch', 'date_picker', 'datetime_picker', 'color_picker', 'file_upload', 'image_upload',
+  'range_slider', 'badge', 'timestamp', 'currency', 'number',
+])
+
+/**
+ * Validate a design_schema object. `checkViews` additionally requires
+ * views.default_list / views.default_detail and scans every declared
+ * display_type — the generic runtime UI breaks without them.
+ */
+export function validateDesignSchema(
+  schema: any,
+  opts: { checkViews?: boolean } = {},
+): { ok: boolean; errors: string[] } {
+  const checkViews = opts.checkViews ?? true
+  const errors: string[] = []
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    errors.push('design_schema must be an object')
+    return { ok: false, errors }
+  }
+
+  const scope = schema.scope ?? 'account'
+  if (scope !== 'account' && scope !== 'platform') {
+    errors.push('scope must be "account" or "platform"')
+  }
+
+  if (!schema.fields || typeof schema.fields !== 'object' || Object.keys(schema.fields).length === 0) {
+    errors.push('fields is required and must contain at least one field definition')
+  }
+
+  for (const [key, field] of Object.entries(schema.fields || {})) {
+    if (!field || typeof field !== 'object') {
+      errors.push(`fields.${key} must be an object`)
+      continue
+    }
+    const f = field as any
+    if (!f.data_type) errors.push(`fields.${key} is missing data_type`)
+    else if (!DATA_TYPES.has(f.data_type)) errors.push(`fields.${key} has unknown data_type: ${f.data_type}`)
+    if (!f.label) errors.push(`fields.${key} is missing label`)
+    if (f.required === undefined) errors.push(`fields.${key} is missing required`)
+    if (['select', 'multiselect', 'radio'].includes(f.data_type) && (!f.options || !Array.isArray(f.options) || f.options.length === 0)) {
+      errors.push(`fields.${key} (${f.data_type}) requires options`)
+    }
+  }
+
+  if (!schema.record_permissions || typeof schema.record_permissions !== 'object') {
+    errors.push('record_permissions is required')
+  } else if (!Object.keys(schema.record_permissions).includes('system-admin') && !Object.keys(schema.record_permissions).includes('system_admin')) {
+    errors.push('record_permissions must grant at least system-admin or system_admin')
+  }
+
+  if (schema.views) {
+    if (schema.views.default_list) {
+      const list = schema.views.default_list
+      if (list.type !== 'list') errors.push('views.default_list.type must be "list"')
+      if (!list.fields || typeof list.fields !== 'object') errors.push('views.default_list.fields is required')
+      if (!list.default_sort) errors.push('views.default_list.default_sort is required')
+    }
+    if (schema.views.default_detail) {
+      const detail = schema.views.default_detail
+      if (detail.type !== 'detail') errors.push('views.default_detail.type must be "detail"')
+    }
+  }
+
+  if (checkViews && !schema.views) {
+    errors.push('views is required when check_views is true')
+  }
+  if (schema.views) {
+    if (checkViews && !schema.views.default_list) errors.push('views.default_list is required')
+    if (checkViews && !schema.views.default_detail) errors.push('views.default_detail is required')
+    for (const [viewName, view] of Object.entries(schema.views || {})) {
+      const v = view as any
+      if (!v || typeof v !== 'object') continue
+      for (const [fieldName, field] of Object.entries(v.fields || {})) {
+        const f = field as any
+        if (f && f.display_type && !DISPLAY_TYPES.has(f.display_type)) {
+          errors.push(`views.${viewName}.fields.${fieldName} has unknown display_type: ${f.display_type}`)
+        }
+      }
+      if (v.sections) {
+        for (const section of v.sections) {
+          for (const [fieldName, field] of Object.entries(section.fields || {})) {
+            const f = field as any
+            if (f && f.display_type && !DISPLAY_TYPES.has(f.display_type)) {
+              errors.push(`views.${viewName}.sections.*.fields.${fieldName} has unknown display_type: ${f.display_type}`)
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors }
+}
+
+export function registerValidateSchemaCommands(program: Command) {
+  program
+    .command('validate-schema')
+    .description('Validate a design_schema JSON file against the Spine design-schema rules')
+    .argument('<file>', 'Path to a design_schema JSON file')
+    .option('--no-views', 'Skip the default_list/default_detail view requirements (custom apps)')
+    .option('--json', 'Output the result as JSON')
+    .action(async (file: string, opts: { views: boolean; json: boolean }) => {
+      const abs = resolve(file)
+      if (!existsSync(abs)) {
+        console.error(`❌ file not found: ${file}`)
+        process.exit(1)
+      }
+      let schema: any
+      try {
+        schema = JSON.parse(readFileSync(abs, 'utf8'))
+      } catch (err: any) {
+        console.error(`❌ ${file} is not valid JSON: ${err.message}`)
+        process.exit(1)
+      }
+
+      const result = validateDesignSchema(schema, { checkViews: opts.views })
+
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: result.ok, error_count: result.errors.length, errors: result.errors }, null, 2))
+      } else if (result.ok) {
+        console.log(`✅ ${file}: design_schema is valid`)
+      } else {
+        console.error(`❌ ${file}: ${result.errors.length} design_schema error(s)`)
+        for (const e of result.errors) console.error(`   - ${e}`)
+      }
+      if (!result.ok) process.exit(1)
+    })
+}

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"]