spine-framework 0.3.145 → 0.4.0

package/.framework/functions/types.ts

@@ -1,48 +1,51 @@
-
-
-
-
-
-
-
-// CIL[BEGIN chunk_id="types_module_header_1783931956" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for types CRUD API"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware, database, permissions and schema utilities"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imported modules and permissions instance" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports all required modules for type management operations" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Netlify function module that exposes CRUD and schema query handlers for runtime record type definitions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import shared utilities and export typed handlers for listing, reading, creating, updating, soft-deleting, and routing types"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts"]
+// CIL[DOC-CONTRACT inputs="HTTP method, query parameters, request body" outputs="JSON response for type records or schema" errors="Validation, permission, and database errors" side_effects="Database reads/writes and audit log emissions"]
+// CIL[DOC-MICRO logic_summary="Aggregates all type operation handlers into a single module export" notable_decisions="Uses createHandler for request context; delegates routing to handler"]
+// 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: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.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="framework_developers"]
+
 import { createHandler } from './_shared/middleware'
 import { adminDb, joins } from './_shared/db'
 import { emitLog } from './_shared/audit'
 import { isSystemAdmin } from './_shared/principal'
 import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
 import { generateValidationSchema } from './_shared/schema-utils'
-
-const permissions = PermissionEngine as any
-// CIL[END chunk_id="types_module_header_1783931956"]
-// CIL[BEGIN chunk_id="types_list_1783931956" type="function" identity="list" parent="none"]
-// CIL[DOC-MACRO purpose="List types with filtering and sanitization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle type listing with authentication-based response"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" 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="sanitized type array" errors="throws" side_effects="database queries"]
-// CIL[DOC-MICRO logic_summary="Filters types by kind/app/ownership, sanitizes based on auth, preserves schemas" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-VECTOR type="context" content="purpose='Netlify function module that exposes CRUD and schema query handlers for runtime record type definitions'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:permissions:constant" type="constant" identity="permissions" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Provide a typed alias to the permission engine for system admin checks"]
+// CIL[DOC-RESPONSIBILITY responsibility="Cast PermissionEngine to any so handlers can call isSystemAdmin"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="permissions alias" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Casts PermissionEngine to any for convenience" notable_decisions="Avoids strict typing at this boundary"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. 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, .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."]
+const permissions = PermissionEngine as any
+// CIL[DOC-VECTOR type="context" content="purpose='Provide a typed alias to the permission engine for system admin checks'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:permissions:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="List active type definitions with optional filters and pagination"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query the public.types table and sanitize records based on the caller principal"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="kind, app_id, ownership, limit, offset, include_schema query parameters" outputs="array of sanitized type rows" errors="Database query errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Builds a filtered, paginated Supabase query against the types table and returns sanitized results" notable_decisions="Returns minimal fields for unauthenticated callers; includes schema only when requested"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const list = createHandler(async (ctx, body) => {
   const { kind, app_id, ownership, limit = '50', offset = '0', include_schema } = ctx.query || {}
 
@@ -101,21 +104,21 @@ export const list = createHandler(async (ctx, body) => {
 
   return sanitized
 })
-// CIL[END chunk_id="types_list_1783931956"]
-// CIL[BEGIN chunk_id="types_get_1783931956" type="function" identity="get" parent="none"]
-// CIL[DOC-MACRO purpose="Get single type by ID with sanitization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and sanitize individual type records"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="sanitized type object" errors="throws" side_effects="database query"]
-// CIL[DOC-MICRO logic_summary="Queries type by ID with app join, sanitizes based on permissions" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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="context" content="purpose='List active type definitions with optional filters and pagination'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:list:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Fetch a single active type record by id"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve a single type row by id and sanitize it for the caller"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="id query parameter" outputs="sanitized type record" errors="Missing id, not found, database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Selects a single active type by id and returns a sanitized record" notable_decisions="Uses adminDb for system admins and ctx.db otherwise"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const get = createHandler(async (ctx, body) => {
   const { id } = ctx.query || {}
   
@@ -136,21 +139,21 @@ export const get = createHandler(async (ctx, body) => {
 
   return await sanitizeRecordData(ctx, data, 'type')
 })
-// CIL[END chunk_id="types_get_1783931956"]
-// CIL[BEGIN chunk_id="types_getbyslug_1783931956" type="function" identity="getBySlug" parent="none"]
-// CIL[DOC-MACRO purpose="Get single type by slug with sanitization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve type records using slug identifier"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="sanitized type object" errors="throws" side_effects="database query"]
-// CIL[DOC-MICRO logic_summary="Queries type by slug with app join, sanitizes based on permissions" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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='Fetch a single active type record by id'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:get:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:getBySlug:constant" type="constant" identity="getBySlug" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Fetch an active type record by slug"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve a single active type row by slug, including related app, and sanitize it"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="slug query parameter" outputs="sanitized type record with app join" errors="Missing slug, not found, database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Selects a single active type by slug with the app join and returns sanitized data" notable_decisions="Uses ctx.db rather than adminDb"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getBySlug = createHandler(async (ctx, body) => {
   const { slug } = ctx.query || {}
   
@@ -169,21 +172,21 @@ export const getBySlug = createHandler(async (ctx, body) => {
 
   return await sanitizeRecordData(ctx, data, 'type')
 })
-// CIL[END chunk_id="types_getbyslug_1783931956"]
-// CIL[BEGIN chunk_id="types_getschema_1783931956" type="function" identity="getSchema" parent="none"]
-// CIL[DOC-MACRO purpose="Get type design schema via RPC"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve design schema for specific type"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="design_schema object" errors="throws" side_effects="database RPC call"]
-// CIL[DOC-MICRO logic_summary="Calls get_type_schema RPC with kind, slug, and optional app_id" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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="context" content="purpose='Fetch an active type record by slug'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:getBySlug:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:getSchema:constant" type="constant" identity="getSchema" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Return the design schema for a given kind and slug"]
+// CIL[DOC-RESPONSIBILITY responsibility="Call the get_type_schema database function and return the design schema"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="kind, slug, app_id query parameters" outputs="object containing design_schema" errors="Missing kind or slug, database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Invokes the get_type_schema Postgres RPC with optional app_id" notable_decisions="Passes app_id as null when not provided"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getSchema = createHandler(async (ctx, body) => {
   const { kind, slug, app_id } = ctx.query || {}
 
@@ -202,23 +205,21 @@ export const getSchema = createHandler(async (ctx, body) => {
 
   return { design_schema: data }
 })
-// CIL[END chunk_id="types_getschema_1783931956"]
-// CIL[BEGIN chunk_id="types_create_1783931956" type="function" identity="create" parent="none"]
-// CIL[DOC-LEARNING topic="runtime-type:generic/validation" content="The types API stores design_schema and auto-generates validation_schema from it via generateValidationSchema. design_schema must define record_permissions, fields, and views to drive the rest of the framework."]
-// CIL[DOC-NOTE type="design_schema_caveat" content="Hand-editing validation_schema is unsafe; it is overwritten by the API. design_schema changes do not retroactively re-stamp existing runtime records."]
-// CIL[DOC-MACRO purpose="Create new type with validation and audit"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle type creation with permissions and validation"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="created type record" errors="throws" side_effects="database insert, audit log"]
-// CIL[DOC-MICRO logic_summary="Validates permissions, checks uniqueness, generates validation schema, creates type" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. 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='Return the design schema for a given kind and slug'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:getSchema:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Create a new type definition"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate admin privileges, enforce required fields, check uniqueness, generate validation schema, insert the row, and emit an audit log"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="request body with name, slug, kind, and optional fields" outputs="newly created type row" errors="Non-admin, missing fields, duplicate slug, database errors" side_effects="Inserts row into public.types and emits type.created audit log"]
+// CIL[DOC-MICRO logic_summary="Enforces system admin, validates required fields, prevents duplicate active slug, generates validation schema if absent, inserts the row, and logs" notable_decisions="Uses adminDb for inserts and falls back to generated validation schema"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const create = createHandler(async (ctx, body) => {
   if (!permissions.isSystemAdmin(ctx)) {
     throw new Error('System admin required')
@@ -290,21 +291,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="types_create_1783931956"]
-// CIL[BEGIN chunk_id="types_update_1783931956" type="function" identity="update" parent="none"]
-// CIL[DOC-MACRO purpose="Update existing type with validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle type updates with permissions and schema sync"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="updated type record" errors="throws" side_effects="database update, audit log"]
-// CIL[DOC-MICRO logic_summary="Validates permissions, protects system types, regenerates validation schema on design changes" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. 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='Create a new type definition'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:create:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Update an existing type definition"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate admin, find the row, protect system ownership, build allowed updates, regenerate validation schema on design change, and log"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="id query parameter and request body fields" outputs="updated type row" errors="Non-admin, missing id, not found, ownership change forbidden, database errors" side_effects="Updates row and emits type.updated audit log"]
+// CIL[DOC-MICRO logic_summary="Selects existing type, blocks ownership changes on system types, applies whitelisted updates, regenerates validation schema when design_schema changes, and logs" notable_decisions="Only updates explicitly provided fields; permission check is performed before lookup"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const update = createHandler(async (ctx, body) => {
   if (!permissions.isSystemAdmin(ctx)) {
     throw new Error('System admin required')
@@ -384,21 +385,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="types_update_1783931956"]
-// CIL[BEGIN chunk_id="types_remove_1783931956" type="function" identity="remove" parent="none"]
-// CIL[DOC-MACRO purpose="Soft delete type with validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle type deletion with permissions and protection"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="success indicator" errors="throws" side_effects="database update, audit log"]
-// CIL[DOC-MICRO logic_summary="Validates permissions, protects system types, soft deletes by setting is_active=false" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. 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='Update an existing type definition'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:update:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Soft-delete an existing type definition"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate admin, find the active row, protect system types, set is_active false, and emit an audit log"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="id query parameter" outputs="success flag" errors="Non-admin, missing id, not found, system type deletion" side_effects="Sets is_active false and emits type.deleted audit log"]
+// CIL[DOC-MICRO logic_summary="Marks an active type as inactive and emits an audit log" notable_decisions="Uses soft delete via is_active update; blocks deletion of system-owned types"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const remove = createHandler(async (ctx, body) => {
   if (!permissions.isSystemAdmin(ctx)) {
     throw new Error('System admin required')
@@ -442,16 +443,21 @@ export const remove = createHandler(async (ctx, body) => {
 
   return { success: true }
 })
-// CIL[END chunk_id="types_remove_1783931956"]
-// CIL[BEGIN chunk_id="types_handler_1783931956" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Netlify function entrypoint for types API"]
-// CIL[DOC-RESPONSIBILITY responsibility="Dispatch incoming requests to list, get, getBySlug, getSchema, create, update, or remove based on HTTP method and query parameters"]
-// CIL[DOC-CONTEXT module="types" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/hooks/useSchemaRecord.ts\",\".framework/src/hooks/useListSchema.ts\"]"]
-// CIL[DOC-CONTRACT inputs="http context and optional body" outputs="routed handler result" errors="throws on unsupported action or method" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Routes GET by action/id/slug to list, get, getBySlug, or getSchema; POST to create; PATCH to update; DELETE to remove" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+// CIL[DOC-VECTOR type="context" content="purpose='Soft-delete an existing type definition'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:remove:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/types.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/types.ts"]
+// CIL[DOC-MACRO purpose="Route incoming requests to the appropriate type operation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch method and query parameters to list, get, getBySlug, getSchema, create, update, or remove"]
+// CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="action, id, slug, kind, method query parameters" outputs="result from delegated handler" errors="Invalid action or method" side_effects="None beyond delegated handler"]
+// CIL[DOC-MICRO logic_summary="Reads HTTP method and query flags to select the correct internal handler and returns its result" notable_decisions="Schema action takes precedence; GET defaults to list when no id/slug/kind provided"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
 export const handler = createHandler(async (ctx, body) => {
   const { action, id, slug, kind } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -484,4 +490,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// CIL[END chunk_id="types_handler_1783931956"]
+// CIL[DOC-VECTOR type="context" content="purpose='Route incoming requests to the appropriate type operation'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/functions/types.ts:handler:constant"]

package/.framework/mcp/index.ts

@@ -0,0 +1,133 @@
+// CIL[BEGIN stable_id="~/.framework/mcp/index.ts:module_header:module_header" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Initialize and wire up the Spine MCP server with all registered tool modules."]
+// CIL[DOC-RESPONSIBILITY responsibility="Load environment configuration, create the McpServer instance, and import and register every tool module."]
+// CIL[DOC-CONTEXT module="mcp" layer="entry-point" related_files=".framework/mcp/load-env.ts,.framework/mcp/tools/architect.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/graph.ts,.framework/mcp/tools/cil/ingest.ts,.framework/mcp/tools/cil/pipeline-orchestrator.ts,.framework/mcp/tools/cil/pipeline.ts,.framework/mcp/tools/cil/project.ts,.framework/mcp/tools/cil/retrieval.ts,.framework/mcp/tools/cil/search.ts,.framework/mcp/tools/cil/validate.ts,.framework/mcp/tools/kb/index.ts,.framework/mcp/tools/observability.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="[]" side_effects="[]"]
+// CIL[DOC-MICRO logic_summary="Imports the environment loader, McpServer SDK, all tool modules, and registers each module with a shared server instance." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="framework"]
+import './load-env.js'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+import * as contextTools from './tools/cil/context.js'
+import * as searchTools from './tools/cil/search.js'
+import * as graphTools from './tools/cil/graph.js'
+import * as validateTools from './tools/cil/validate.js'
+import * as projectTools from './tools/cil/project.js'
+import * as pipelineTools from './tools/cil/pipeline.js'
+import * as pipelineOrchestratorTools from './tools/cil/pipeline-orchestrator.js'
+import * as ingestTools from './tools/cil/ingest.js'
+import * as retrievalTools from './tools/cil/retrieval.js'
+import * as architectTools from './tools/architect.js'
+import * as kbTools from './tools/kb/index.js'
+import * as observabilityTools from './tools/observability.js'
+// CIL[DOC-VECTOR type="context" content="purpose='Initialize and wire up the Spine MCP server with all registered tool modules.'; No verified external callers; imports: .framework/mcp/load-env.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/search.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/mcp/index.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/mcp/index.ts:server:constant" type="constant" identity="server" parent="none"]
+// CIL[DOC-MACRO purpose="Define the configured McpServer instance used by the framework."]
+// CIL[DOC-RESPONSIBILITY responsibility="Instantiate the shared McpServer with the framework name and version."]
+// CIL[DOC-CONTEXT module="mcp" layer="server" related_files=".framework/mcp/index.ts,.framework/mcp/load-env.ts,.framework/mcp/tools/architect.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/graph.ts,.framework/mcp/tools/cil/ingest.ts,.framework/mcp/tools/cil/pipeline-orchestrator.ts,.framework/mcp/tools/cil/pipeline.ts,.framework/mcp/tools/cil/project.ts,.framework/mcp/tools/cil/retrieval.ts,.framework/mcp/tools/cil/search.ts,.framework/mcp/tools/cil/validate.ts,.framework/mcp/tools/kb/index.ts,.framework/mcp/tools/observability.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="server: McpServer" errors="[]" side_effects="[]"]
+// CIL[DOC-MICRO logic_summary="Constructs a new McpServer named 'spine-framework' at version '1.0.0'." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+const server = new McpServer({
+  name: 'spine-framework',
+  version: '1.0.0',
+})
+// CIL[DOC-VECTOR type="context" content="purpose='Define the configured McpServer instance used by the framework.'; No verified external callers; imports: .framework/mcp/load-env.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/search.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/mcp/index.ts:server:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/mcp/index.ts:tool_registrations:block" type="block" identity="tool_registrations" parent="none"]
+// CIL[DOC-MACRO purpose="Register all imported tool modules with the McpServer."]
+// CIL[DOC-RESPONSIBILITY responsibility="Attach CIL, architect, KB, and observability tool handlers to the McpServer."]
+// CIL[DOC-CONTEXT module="mcp" layer="registration" related_files=".framework/mcp/index.ts,.framework/mcp/load-env.ts,.framework/mcp/tools/architect.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/graph.ts,.framework/mcp/tools/cil/ingest.ts,.framework/mcp/tools/cil/pipeline-orchestrator.ts,.framework/mcp/tools/cil/pipeline.ts,.framework/mcp/tools/cil/project.ts,.framework/mcp/tools/cil/retrieval.ts,.framework/mcp/tools/cil/search.ts,.framework/mcp/tools/cil/validate.ts,.framework/mcp/tools/kb/index.ts,.framework/mcp/tools/observability.ts"]
+// CIL[DOC-CONTRACT inputs="server: McpServer" outputs="server with tool handlers registered" errors="[]" side_effects="mutates the McpServer"]
+// CIL[DOC-MICRO logic_summary="Calls register(server) for each imported tool module in turn." notable_decisions="Registration order follows import order."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+contextTools.register(server)
+searchTools.register(server)
+graphTools.register(server)
+validateTools.register(server)
+projectTools.register(server)
+pipelineTools.register(server)
+pipelineOrchestratorTools.register(server)
+ingestTools.register(server)
+retrievalTools.register(server)
+architectTools.register(server)
+kbTools.register(server)
+observabilityTools.register(server)
+// CIL[DOC-VECTOR type="context" content="purpose='Register all imported tool modules with the McpServer.'; No verified external callers; imports: .framework/mcp/load-env.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/search.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/mcp/index.ts:tool_registrations:block"]
+
+// CIL[BEGIN stable_id="~/.framework/mcp/index.ts:main:function" type="function" identity="main" parent="none"]
+// CIL[DOC-MACRO purpose="Start the MCP server after validating required environment variables."]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify SPINE_URL and SPINE_API_KEY, create a stdio transport, connect the server, and log startup."]
+// CIL[DOC-CONTEXT module="mcp" layer="runtime" related_files=".framework/mcp/index.ts,.framework/mcp/load-env.ts,.framework/mcp/tools/architect.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/graph.ts,.framework/mcp/tools/cil/ingest.ts,.framework/mcp/tools/cil/pipeline-orchestrator.ts,.framework/mcp/tools/cil/pipeline.ts,.framework/mcp/tools/cil/project.ts,.framework/mcp/tools/cil/retrieval.ts,.framework/mcp/tools/cil/search.ts,.framework/mcp/tools/cil/validate.ts,.framework/mcp/tools/kb/index.ts,.framework/mcp/tools/observability.ts"]
+// CIL[DOC-CONTRACT inputs="process.env" outputs="stdio transport connection" errors="Missing required environment variables" side_effects="process.exit(1) on validation failure; writes to stderr"]
+// CIL[DOC-MICRO logic_summary="Collect missing environment variables; if any are missing, log an error and exit. Otherwise connect the server to stdio and log a startup message." notable_decisions="Fails fast when SPINE_URL or SPINE_API_KEY are unset."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+async function main() {
+  const missingEnv = []
+  if (!process.env.SPINE_URL) missingEnv.push('SPINE_URL')
+  if (!process.env.SPINE_API_KEY) missingEnv.push('SPINE_API_KEY')
+
+  if (missingEnv.length > 0) {
+    process.stderr.write(
+      `[spine-framework-mcp] ERROR: Missing required environment variables: ${missingEnv.join(', ')}\n` +
+      `Set SPINE_URL and SPINE_API_KEY in the MCP host config (env block).\n`
+    )
+    process.exit(1)
+  }
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  process.stderr.write('[spine-framework-mcp] Server running on stdio\n')
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Start the MCP server after validating required environment variables.'; No verified external callers; imports: .framework/mcp/load-env.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/search.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/mcp/index.ts:main:function"]
+
+// CIL[BEGIN stable_id="~/.framework/mcp/index.ts:error_handling:block" type="block" identity="error_handling" parent="none"]
+// CIL[DOC-MACRO purpose="Catch unhandled fatal errors from main() and terminate the process."]
+// CIL[DOC-RESPONSIBILITY responsibility="Wrap main() execution, log any rejection, and exit with a fatal error code."]
+// CIL[DOC-CONTEXT module="mcp" layer="error-handling" related_files=".framework/mcp/index.ts,.framework/mcp/load-env.ts,.framework/mcp/tools/architect.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/graph.ts,.framework/mcp/tools/cil/ingest.ts,.framework/mcp/tools/cil/pipeline-orchestrator.ts,.framework/mcp/tools/cil/pipeline.ts,.framework/mcp/tools/cil/project.ts,.framework/mcp/tools/cil/retrieval.ts,.framework/mcp/tools/cil/search.ts,.framework/mcp/tools/cil/validate.ts,.framework/mcp/tools/kb/index.ts,.framework/mcp/tools/observability.ts"]
+// CIL[DOC-CONTRACT inputs="main(): Promise<void>" outputs="none" errors="[]" side_effects="process.stderr.write; process.exit(1)"]
+// CIL[DOC-MICRO logic_summary="Attaches a catch handler to main() that writes the error to stderr and exits." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+main().catch(err => {
+  process.stderr.write(`[spine-framework-mcp] Fatal error: ${err}\n`)
+  process.exit(1)
+})
+// CIL[DOC-VECTOR type="context" content="purpose='Catch unhandled fatal errors from main() and terminate the process.'; No verified external callers; imports: .framework/mcp/load-env.ts,.framework/mcp/tools/cil/context.ts,.framework/mcp/tools/cil/search.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/mcp/index.ts:error_handling:block"]

package/.framework/mcp/load-env.ts

@@ -0,0 +1,60 @@
+// CIL[BEGIN stable_id="~/.framework/mcp/load-env.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/load-env.ts"]
+// CIL[DOC-MACRO purpose="Imports Node.js utilities for resolving and loading an environment file."]
+// CIL[DOC-CONTEXT module="mcp" layer="framework" related_files=".framework/mcp/load-env.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="runtime dependencies available to the module" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports fs, path, and fileURLToPath for use by loadEnv." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developers"]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+// CIL[DOC-VECTOR type="context" content="purpose='Imports Node.js utilities for resolving and loading an environment file.'; 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/mcp/load-env.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/mcp/load-env.ts:loadEnv:function" type="function" identity="loadEnv" parent="~/.framework/mcp/load-env.ts"]
+// CIL[DOC-MACRO purpose="Reads a .env file and populates process.env for any keys that are not already set."]
+// CIL[DOC-RESPONSIBILITY responsibility="Bootstrap environment variables for the MCP server process."]
+// CIL[DOC-CONTEXT module="mcp" layer="framework" related_files=".framework/mcp/load-env.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="process.env updated from .env file" errors="read/parse failures are silently ignored" side_effects="mutates process.env"]
+// CIL[DOC-MICRO logic_summary="Resolves the .env path relative to this file, reads it line by line, skips empty and comment lines, parses KEY=VALUE pairs, trims and strips surrounding quotes from values, and writes to process.env only when the key is absent." notable_decisions="Returns early if .env is missing; ignores all exceptions so server startup is not blocked; preserves already-set environment variables."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function loadEnv(): void {
+  try {
+    const __filename = fileURLToPath(import.meta.url)
+    const envPath = path.resolve(path.dirname(__filename), '../../.env')
+    if (!fs.existsSync(envPath)) return
+    const text = fs.readFileSync(envPath, 'utf-8')
+    for (const raw of text.split(/\r?\n/)) {
+      const line = raw.trim()
+      if (!line || line.startsWith('#')) continue
+      const eq = line.indexOf('=')
+      if (eq === -1) continue
+      const key = line.slice(0, eq).trim()
+      let value = line.slice(eq + 1).trim()
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1)
+      }
+      if (key && process.env[key] === undefined) {
+        process.env[key] = value
+      }
+    }
+  } catch {
+    // Ignore read/parse errors so the server still starts if .env is missing.
+  }
+}
+
+loadEnv()
+// CIL[DOC-VECTOR type="context" content="purpose='Reads a .env file and populates process.env for any keys that are not already set.'; 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/mcp/load-env.ts:loadEnv:function"]