spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/mcp/tools/cil/context.ts

@@ -1,345 +0,0 @@
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-MACRO purpose="MCP tool module that exposes CIL context and post-edit helpers for named chunks"]
-// CIL[DOC-RESPONSIBILITY responsibility="Register MCP tools providing pre-edit context briefs and post-edit next steps"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="tools" related_files=".framework/mcp/shared/db.ts"]
-// CIL[DOC-CONTRACT inputs="McpServer instance" outputs="registered tools" errors="none" side_effects="registers three tools on the server"]
-// CIL[DOC-MICRO logic_summary="Imports SDK, zod, and shared DB helpers; no runtime logic" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="internal"]
-
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
-import { adminDb, resolveLinkTypeId } from '../../shared/db.js'
-// CIL[DOC-VECTOR type="context" content="purpose='MCP tool module that exposes CIL context and post-edit helpers for named chunks'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/context.ts:module_header:module_header"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:getChunkById:function" type="function" identity="getChunkById" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-MACRO purpose="Fetch a CIL chunk row by its primary id"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return raw chunk data for a given id"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="data-access" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-CONTRACT inputs="id: string" outputs="chunk data or undefined" errors="none" side_effects="queries adminDb"]
-// CIL[DOC-MICRO logic_summary="Selects from items table by id" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-async function getChunkById(id: string) {
-  const { data } = await adminDb.from('items').select('id, title, data')
-    .eq('id', id).maybeSingle()
-  return data
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Fetch a CIL chunk row by its primary id'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/context.ts:getChunkById:function"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:getChunkByStableId:function" type="function" identity="getChunkByStableId" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-MACRO purpose="Fetch an active CIL chunk by project and stable id"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return the matching chunk or undefined"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="data-access" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-CONTRACT inputs="projectId: string, stableId: string, versionId?: string" outputs="chunk data" errors="none" side_effects="queries adminDb with filters"]
-// CIL[DOC-MICRO logic_summary="Builds a filtered Supabase query and returns maybeSingle result" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-async function getChunkByStableId(projectId: string, stableId: string, versionId?: string) {
-  let q = adminDb.from('items').select('id, title, data')
-    .filter('data->>kb_type', 'eq', 'cil_chunk')
-    .filter('data->>project_id', 'eq', projectId)
-    .filter('data->>stable_id', 'eq', stableId)
-    .eq('is_active', true)
-  if (versionId) q = (q as any).filter('data->>version_id', 'eq', versionId)
-  const { data } = await (q as any).maybeSingle()
-  return data
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Fetch an active CIL chunk by project and stable id'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/context.ts:getChunkByStableId:function"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:findChunkByName:function" type="function" identity="findChunkByName" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-MACRO purpose="Find an active CIL chunk by chunk name"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return the first matching chunk by name"]
-// CIL[DOC-STABILITY stability="internal"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="data-access" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-CONTRACT inputs="name: string, projectId?: string" outputs="chunk data" errors="none" side_effects="queries adminDb"]
-// CIL[DOC-MICRO logic_summary="Filters by chunk_name and optional project, returns first result" notable_decisions="[]"]
-async function findChunkByName(name: string, projectId?: string) {
-  let q = adminDb.from('items').select('id, title, data')
-    .filter('data->>kb_type', 'eq', 'cil_chunk')
-    .filter('data->>chunk_name', 'eq', name)
-    .eq('is_active', true)
-  if (projectId) q = (q as any).filter('data->>project_id', 'eq', projectId)
-  const { data } = await (q as any).limit(1).maybeSingle()
-  return data
-}
-// CIL[END stable_id="~/.framework/mcp/tools/cil/context.ts:findChunkByName:function"]
-
-// CIL[DOC-VECTOR type="context" content="purpose='Find an active CIL chunk by chunk name'; No verified external callers; imports: .framework/mcp/shared/db.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[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:blastRadiusBFS:function" type="function" identity="blastRadiusBFS" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-MACRO purpose="Compute transitive callers of a chunk up to a max depth"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return a list of caller chunks with depth metadata"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="analysis" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-CONTRACT inputs="chunkId, maxDepth, callsLinkTypeId" outputs="caller records" errors="none" side_effects="queries links and items tables"]
-// CIL[DOC-MICRO logic_summary="Breadth-first search over cil_calls links in reverse direction" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-async function blastRadiusBFS(
-  chunkId: string, maxDepth: number, callsLinkTypeId: string
-): Promise<{ chunk_id: string; chunk_name: string; file_path: string; depth: number }[]> {
-  const visited = new Set([chunkId])
-  const queue: { id: string; depth: number }[] = [{ id: chunkId, depth: 0 }]
-  const result: { chunk_id: string; chunk_name: string; file_path: string; depth: number }[] = []
-
-  while (queue.length > 0) {
-    const { id, depth } = queue.shift()!
-    if (depth >= maxDepth) continue
-    const { data: callerLinks } = await adminDb.from('links').select('source_id')
-      .eq('link_type_id', callsLinkTypeId).eq('target_id', id)
-    for (const link of callerLinks || []) {
-      if (visited.has(link.source_id)) continue
-      visited.add(link.source_id)
-      const c = await getChunkById(link.source_id)
-      if (!c) continue
-      result.push({ chunk_id: c.id, chunk_name: c.data?.chunk_name || '', file_path: c.data?.file_path || '', depth: depth + 1 })
-      queue.push({ id: c.id, depth: depth + 1 })
-    }
-  }
-  return result
-}
-// CIL[END stable_id="~/.framework/mcp/tools/cil/context.ts:blastRadiusBFS:function"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:safetyVerdict:function" type="function" identity="safetyVerdict" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-VECTOR type="context" content="purpose='Compute transitive callers of a chunk up to a max depth'; No verified external callers; imports: .framework/mcp/shared/db.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[DOC-MACRO purpose="Assess edit safety for a chunk based on stability, blast radius, docs, and config dependencies"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return a safety level and list of risk flags"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="analysis" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-CONTRACT inputs="chunk, blastRadius, configDeps" outputs="{level, flags, summary}" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Inspects chunk data and derived metrics to classify risk" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-function safetyVerdict(chunk: any, blastRadius: any[], configDeps: any[]) {
-  const d = chunk.data || {}
-  const flags: string[] = []
-  if (d.stability === 'stable') flags.push('stability=stable: downstream consumers may break on signature changes')
-  if (blastRadius.length >= 10) flags.push(`high blast radius: ${blastRadius.length} transitive callers`)
-  else if (blastRadius.length >= 3) flags.push(`moderate blast radius: ${blastRadius.length} callers`)
-  if (configDeps.length > 0) flags.push(`reads ${configDeps.length} config field(s)`)
-  if (!d.macro && !d.micro) flags.push('no contract documentation')
-  if (d.is_dead_code) flags.push('flagged as dead code')
-  const level = flags.length === 0 ? 'safe' : (d.stability === 'stable' || blastRadius.length >= 10) ? 'risky' : 'caution'
-  return { level, flags, summary: level === 'safe' ? 'Low risk.' : `${level === 'risky' ? 'High' : 'Moderate'} risk — review flags before editing.` }
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Assess edit safety for a chunk based on stability, blast radius, docs, and config dependencies'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/context.ts:safetyVerdict:function"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:buildBrief:function" type="function" identity="buildBrief" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-MACRO purpose="Assemble a full pre-edit context brief for a chunk"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return contract, blast radius, callees, tests, config deps, and safety verdict"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="analysis" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-CONTRACT inputs="chunk: any, maxDepth: number = 4" outputs="context brief object" errors="none" side_effects="queries multiple link and item tables"]
-// CIL[DOC-MICRO logic_summary="Resolves link types, computes blast radius, gathers callees, tests, and config dependencies" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-async function buildBrief(chunk: any, maxDepth = 4) {
-  const d = chunk.data || {}
-  const [callsId, testedById, configuresId] = await Promise.all([
-    resolveLinkTypeId('cil_calls').catch(() => null),
-    resolveLinkTypeId('cil_tested_by').catch(() => null),
-    resolveLinkTypeId('cil_configures').catch(() => null),
-  ])
-
-  const blastRadius = callsId ? await blastRadiusBFS(chunk.id, maxDepth, callsId) : []
-
-  const callees: any[] = []
-  if (callsId) {
-    const { data: ls } = await adminDb.from('links').select('target_id').eq('link_type_id', callsId).eq('source_id', chunk.id)
-    for (const l of ls || []) {
-      const c = await getChunkById(l.target_id)
-      if (c) callees.push({ chunk_id: c.id, chunk_name: c.data?.chunk_name || '', file_path: c.data?.file_path || '' })
-    }
-  }
-
-  const testPaths: { path: string; is_e2e: boolean }[] = []
-  if (testedById) {
-    const { data: ls } = await adminDb.from('links').select('target_id, metadata').eq('link_type_id', testedById).eq('source_id', chunk.id)
-    for (const l of ls || []) testPaths.push({ path: l.metadata?.test_path || '', is_e2e: l.metadata?.is_e2e || false })
-  }
-  if (testPaths.length === 0) {
-    if (d.test_unit_path) testPaths.push({ path: d.test_unit_path, is_e2e: false })
-    if (d.test_e2e_path)  testPaths.push({ path: d.test_e2e_path, is_e2e: true })
-  }
-
-  const configDeps: { field_name: string; config_id: string }[] = []
-  if (configuresId) {
-    const { data: ls } = await adminDb.from('links').select('source_id, metadata').eq('link_type_id', configuresId).eq('target_id', chunk.id)
-    for (const l of ls || []) {
-      const ci = await getChunkById(l.source_id)
-      if (ci) configDeps.push({ field_name: ci.data?.field_name || '', config_id: l.source_id })
-    }
-  }
-
-  return {
-    chunk_id: chunk.id,
-    chunk_name: d.chunk_name || '',
-    file_path: d.file_path || '',
-    line_start: d.line_start || null,
-    line_end: d.line_end || null,
-    chunk_type: d.chunk_type || '',
-    source_set_id: d.source_set_id || null,
-    layer: d.layer || null,
-    contract: {
-      description: d.description || '',
-      module: d.module || '',
-      audience: d.audience || '',
-      macro: d.macro || '',
-      micro: d.micro || '',
-      input_spec: d.input_spec || '',
-      output_spec: d.output_spec || '',
-      side_effects: d.side_effects || '',
-      throws: d.throws || '',
-      stability: d.stability || 'unknown',
-      called_by: d.called_by || '',
-      calls: d.calls || '',
-      tags: d.tags || '',
-      complexity: d.complexity || '',
-      error_handling: d.error_handling || '',
-      related_files: d.related_files || d.see_also || '',
-      depends_on: d.depends_on || [],
-      depended_by: d.depended_by || [],
-      doc_confidence: d.doc_confidence || 'unverified_legacy',
-      validation_errors: d.doc_validation_errors || [],
-    },
-    hash: { stored_hash: d.stored_hash || null, hash_updated_at: d.hash_updated_at || null },
-    blast_radius: { direct_caller_count: blastRadius.filter(r => r.depth === 1).length, total_affected: blastRadius.length, callers: blastRadius },
-    calls: callees,
-    test_paths: testPaths,
-    config_dependencies: configDeps,
-    edit_safety: safetyVerdict(chunk, blastRadius, configDeps),
-  }
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Assemble a full pre-edit context brief for a chunk'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/context.ts:buildBrief:function"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/context.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-MACRO purpose="Register CIL context tools on an MCP server"]
-// CIL[DOC-RESPONSIBILITY responsibility="Expose spine_cil_find_context, spine_cil_get_context, and spine_cil_post_edit"]
-// CIL[DOC-CONTEXT module="mcp-cil-context" layer="tools" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/context.ts"]
-// CIL[DOC-CONTRACT inputs="server: McpServer" outputs="none" errors="none" side_effects="registers three tools"]
-// CIL[DOC-MICRO logic_summary="Calls server.registerTool for find context, get context, and post edit handlers" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-export function register(server: McpServer) {
-
-  server.registerTool(
-    'spine_cil_find_context',
-    {
-      description: 'Get a full pre-edit context brief for a chunk by name. Call this BEFORE editing any named chunk. Returns contract, blast radius, test paths, config dependencies, and an edit_safety verdict (safe/caution/risky).',
-      inputSchema: z.object({
-        stable_id: z.string().describe('Exact stable_id of the chunk'),
-        project_id: z.string().uuid().describe('The cil_project UUID'),
-        version_id: z.string().optional().describe('Optional version UUID to scope the lookup'),
-        max_depth: z.number().int().min(1).max(6).default(4).optional().describe('BFS depth for blast radius traversal'),
-      }),
-    },
-    async ({ stable_id, project_id, version_id, max_depth }) => {
-      const chunk = await getChunkByStableId(project_id, stable_id, version_id)
-      if (!chunk) {
-        return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: `No chunk with stable_id "${stable_id}" found`, hint: 'Use spine_cil_search_chunks to find chunks by description' }) }] }
-      }
-      const brief = await buildBrief(chunk, max_depth ?? 4)
-      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, brief }, null, 2) }] }
-    }
-  )
-
-  server.registerTool(
-    'spine_cil_get_context',
-    {
-      description: 'Get a full pre-edit context brief for a chunk by its stable_id. Returns contract, blast radius, test paths, config dependencies, and edit_safety verdict.',
-      inputSchema: z.object({
-        project_id: z.string().uuid().describe('The cil_project UUID'),
-        stable_id: z.string().describe('The chunk stable_id'),
-        version_id: z.string().optional().describe('Optional version UUID to scope the lookup'),
-        max_depth: z.number().int().min(1).max(6).default(4).optional(),
-      }),
-    },
-    async ({ project_id, stable_id, version_id, max_depth }) => {
-      const chunk = await getChunkByStableId(project_id, stable_id, version_id)
-      if (!chunk) return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: `Chunk not found: ${stable_id}` }) }] }
-      const brief = await buildBrief(chunk, max_depth ?? 4)
-      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, brief }, null, 2) }] }
-    }
-  )
-
-  server.registerTool(
-    'spine_cil_post_edit',
-    {
-      description: 'Call this AFTER editing a chunk. Returns its stored hash status and exact next_steps commands to reindex and validate the change.',
-      inputSchema: z.object({
-        project_id: z.string().uuid().describe('The cil_project UUID'),
-        stable_id: z.string().describe('The stable_id of the chunk you just edited'),
-        version_id: z.string().optional().describe('Optional version UUID to scope the lookup'),
-      }),
-    },
-    async ({ project_id, stable_id, version_id }) => {
-      const chunk = await getChunkByStableId(project_id, stable_id, version_id)
-      if (!chunk) return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: `Chunk not found: ${stable_id}` }) }] }
-      const d = chunk.data || {}
-      const result = {
-        ok: true,
-        stable_id,
-        project_id,
-        version_id: version_id || d.version_id || null,
-        chunk_name: d.chunk_name || '',
-        file_path: d.file_path || '',
-        stored_hash: d.stored_hash || null,
-        hash_updated_at: d.hash_updated_at || null,
-        action_required: d.stored_hash
-          ? 'Run spine_cil_reindex_chunk to refresh the stored hash after your edit, then spine_cil_validate_file to confirm drift is resolved.'
-          : 'No stored hash yet — run spine_cil_reindex_chunk or Pass 2 ingestion.',
-        next_steps: [
-          `spine_cil_reindex_chunk({ project_id: "${d.project_id || project_id}", stable_id: "${stable_id}", version_id: "${version_id || d.version_id || ''}", also_embed: true })`,
-          `spine_cil_validate_file({ project_id: "${d.project_id || project_id}", file_path: "${d.file_path || ''}" })`,
-        ],
-      }
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
-    }
-  )
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Register CIL context tools on an MCP server'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/context.ts:register:function"]

package/.framework/mcp/tools/cil/graph.ts

@@ -1,242 +0,0 @@
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/graph.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/cil/graph.ts"]
-// CIL[DOC-MACRO purpose="Import dependencies and set up the CIL graph MCP tool module"]
-// CIL[DOC-RESPONSIBILITY responsibility="Declare module-level imports for the MCP CIL graph tool"]
-// CIL[DOC-CONTEXT module="mcp-tools-cil" layer="tools" related_files=".framework/mcp/shared/db.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Import McpServer SDK, zod, and shared database helpers" notable_decisions="none"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="maintainer"]
-
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
-import { adminDb, resolveLinkTypeId, fetchFunction } from '../../shared/db.js'
-// CIL[DOC-VECTOR type="context" content="purpose='Import dependencies and set up the CIL graph MCP tool module'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/graph.ts:module_header:module_header"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/graph.ts:getChunkById:function" type="function" identity="getChunkById" parent="~/.framework/mcp/tools/cil/graph.ts"]
-// CIL[DOC-MACRO purpose="Fetch a single CIL chunk by its primary item id"]
-// CIL[DOC-RESPONSIBILITY responsibility="Load a chunk record from the items table by id"]
-// CIL[DOC-CONTEXT module="mcp-tools-cil" layer="tools" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/graph.ts"]
-// CIL[DOC-CONTRACT inputs="id: string" outputs="chunk record or null" errors="none" side_effects="database read"]
-// CIL[DOC-MICRO logic_summary="Query adminDb items table for id, title, data matching the given id and return the data" notable_decisions="Uses maybeSingle to return null when no match"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-async function getChunkById(id: string) {
-  const { data } = await adminDb.from('items').select('id, title, data')
-    .eq('id', id).maybeSingle()
-  return data
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Fetch a single CIL chunk by its primary item id'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/graph.ts:getChunkById:function"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/graph.ts:getChunkByStableId:function" type="function" identity="getChunkByStableId" parent="~/.framework/mcp/tools/cil/graph.ts"]
-// CIL[DOC-MACRO purpose="Fetch a CIL chunk by its stable_id within a project and optional version"]
-// CIL[DOC-RESPONSIBILITY responsibility="Locate a unique active CIL chunk by stable_id"]
-// CIL[DOC-CONTEXT module="mcp-tools-cil" layer="tools" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/graph.ts"]
-// CIL[DOC-CONTRACT inputs="projectId: string, stableId: string, versionId?: string" outputs="chunk record or null" errors="none" side_effects="database read"]
-// CIL[DOC-MICRO logic_summary="Filter items by kb_type, project_id, stable_id, is_active and optional version_id, then return data" notable_decisions="Casts query to any when adding the optional version filter"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-async function getChunkByStableId(projectId: string, stableId: string, versionId?: string) {
-  let q = adminDb.from('items').select('id, title, data')
-    .filter('data->>kb_type', 'eq', 'cil_chunk')
-    .filter('data->>project_id', 'eq', projectId)
-    .filter('data->>stable_id', 'eq', stableId)
-    .eq('is_active', true)
-  if (versionId) q = (q as any).filter('data->>version_id', 'eq', versionId)
-  const { data } = await (q as any).maybeSingle()
-  return data
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Fetch a CIL chunk by its stable_id within a project and optional version'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/graph.ts:getChunkByStableId:function"]
-
-// CIL[BEGIN stable_id="~/.framework/mcp/tools/cil/graph.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/cil/graph.ts"]
-// CIL[DOC-MACRO purpose="Register CIL graph query tools on an MCP server"]
-// CIL[DOC-RESPONSIBILITY responsibility="Wire up MCP tools for blast radius, callers, file chunks and graph diff"]
-// CIL[DOC-CONTEXT module="mcp-tools-cil" layer="tools" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/cil/graph.ts"]
-// CIL[DOC-CONTRACT inputs="server: McpServer" outputs="registered tool handlers" errors="throws if cil_calls link type or chunk is not found" side_effects="registers tools on the server and queries the database and links table"]
-// CIL[DOC-MICRO logic_summary="Use server.registerTool to expose four CIL graph introspection endpoints backed by Supabase items and links" notable_decisions="Returns JSON-stringified content; uses BFS for blast radius; filters symbol references for direct callers; delegates graph_diff to fetchFunction"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-export function register(server: McpServer) {
-
-  server.registerTool(
-    'spine_cil_blast_radius',
-    {
-      description: 'Find all chunks that transitively call a given chunk (BFS traversal). Use this before refactoring to understand how many callers will be affected.',
-      inputSchema: z.object({
-        project_id: z.string().uuid().describe('The cil_project UUID'),
-        stable_id: z.string().describe('The chunk stable_id to analyse'),
-        version_id: z.string().optional().describe('Optional version UUID to scope the lookup'),
-        max_depth: z.number().int().min(1).max(6).default(4).optional().describe('Maximum BFS hop depth'),
-      }),
-    },
-    async ({ project_id, stable_id, version_id, max_depth = 4 }) => {
-      let callsId: string
-      try { callsId = await resolveLinkTypeId('cil_calls') }
-      catch { return { content: [{ type: 'text', text: JSON.stringify({ error: 'cil_calls link type not found — run Pass 4b first' }) }] } }
-
-      const chunk = await getChunkByStableId(project_id, stable_id, version_id)
-      if (!chunk) return { content: [{ type: 'text', text: JSON.stringify({ error: `Chunk not found: ${stable_id}` }) }] }
-
-      const startId = chunk.id
-      const visited = new Set([startId])
-      const queue: { id: string; depth: number }[] = [{ id: startId, depth: 0 }]
-      const callers: { stable_id: string; chunk_name: string; file_path: string; depth: number }[] = []
-
-      while (queue.length > 0) {
-        const { id, depth } = queue.shift()!
-        if (depth >= max_depth) continue
-        const { data: links } = await adminDb.from('links').select('source_id')
-          .eq('link_type_id', callsId).eq('target_id', id)
-        for (const l of links || []) {
-          if (visited.has(l.source_id)) continue
-          visited.add(l.source_id)
-          const c = await getChunkById(l.source_id)
-          if (!c) continue
-          callers.push({ stable_id: c.data?.stable_id || c.id, chunk_name: c.data?.chunk_name || '', file_path: c.data?.file_path || '', depth: depth + 1 })
-          queue.push({ id: c.id, depth: depth + 1 })
-        }
-      }
-
-      const result = {
-        stable_id,
-        chunk_name: chunk.data?.chunk_name || '',
-        file_path: chunk.data?.file_path || '',
-        max_depth,
-        direct_callers: callers.filter(c => c.depth === 1).length,
-        total_affected: callers.length,
-        callers,
-      }
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
-    }
-  )
-
-  server.registerTool(
-    'spine_cil_get_callers',
-    {
-      description: 'Get the direct callers and symbol references (imports/references) of a chunk (depth-1 only). Faster than spine_cil_blast_radius when you just need to know what directly uses a chunk.',
-      inputSchema: z.object({
-        project_id: z.string().uuid().describe('The cil_project UUID'),
-        stable_id: z.string().describe('The chunk stable_id'),
-        version_id: z.string().optional().describe('Optional version UUID to scope the lookup'),
-      }),
-    },
-    async ({ project_id, stable_id, version_id }) => {
-      let callsId: string
-      try { callsId = await resolveLinkTypeId('cil_calls') }
-      catch { return { content: [{ type: 'text', text: JSON.stringify({ error: 'cil_calls link type not found' }) }] } }
-
-      const chunk = await getChunkByStableId(project_id, stable_id, version_id)
-      if (!chunk) return { content: [{ type: 'text', text: JSON.stringify({ error: `Chunk not found: ${stable_id}` }) }] }
-
-      const { data: links } = await adminDb.from('links').select('source_id, data, metadata')
-        .eq('link_type_id', callsId).eq('target_id', chunk.id)
-
-      const callers = []
-      for (const l of links || []) {
-        const c = await getChunkById(l.source_id)
-        if (c) callers.push({ stable_id: c.data?.stable_id || c.id, chunk_name: c.data?.chunk_name || '', file_path: c.data?.file_path || '' })
-      }
-
-      return { content: [{ type: 'text', text: JSON.stringify({ stable_id, caller_count: callers.length, callers }, null, 2) }] }
-    }
-  )
-
-  server.registerTool(
-    'spine_cil_get_file_chunks',
-    {
-      description: 'List all indexed chunks for a file, sorted by line number. Useful for understanding the structure of a file before editing.',
-      inputSchema: z.object({
-        project_id: z.string().uuid().describe('The cil_project UUID'),
-        file_path: z.string().describe('Relative file path from repo root, e.g. ".framework/cli/commands/auth.ts"'),
-      }),
-    },
-    async ({ project_id, file_path }) => {
-      const { data: chunks } = await adminDb.from('items').select('id, title, data')
-        .filter('data->>kb_type', 'eq', 'cil_chunk')
-        .filter('data->>project_id', 'eq', project_id)
-        .filter('data->>file_path', 'eq', file_path)
-        .eq('is_active', true)
-
-      if (!chunks || chunks.length === 0) {
-        return { content: [{ type: 'text', text: JSON.stringify({ error: `No chunks found for file: ${file_path}` }) }] }
-      }
-
-      const sorted = chunks
-        .map((c: any) => ({
-          id: c.id,
-          stable_id: c.data?.stable_id || '',
-          version_id: c.data?.version_id || '',
-          chunk_name: c.data?.chunk_name || '',
-          chunk_type: c.data?.chunk_type || '',
-          line_start: c.data?.line_start || 0,
-          line_end: c.data?.line_end || 0,
-          macro: c.data?.macro || '',
-          doc_confidence: c.data?.doc_confidence || 'unverified_legacy',
-          is_dead_code: c.data?.is_dead_code || false,
-          stability: c.data?.stability || '',
-        }))
-        .sort((a: any, b: any) => a.line_start - b.line_start)
-
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            project_id,
-            file_path,
-            chunk_count: sorted.length,
-            chunks: sorted,
-          }, null, 2),
-        }],
-      }
-    }
-  )
-
-  server.registerTool(
-    'spine_cil_graph_diff',
-    {
-      description: 'Compare the CIL call and import graph between two project versions. Returns added, removed, and unchanged edges keyed by stable IDs and file paths.',
-      inputSchema: z.object({
-        project_id: z.string().uuid().describe('The cil_project UUID'),
-        from_version_id: z.string().uuid().describe('The source version UUID to diff from'),
-        to_version_id: z.string().uuid().describe('The target version UUID to diff to'),
-      }),
-    },
-    async ({ project_id, from_version_id, to_version_id }) => {
-      try {
-        const result = await fetchFunction('cil-graph', 'graph_diff', {
-          project_id,
-          from_version_id,
-          to_version_id,
-        })
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
-      } catch (err: any) {
-        return { content: [{ type: 'text', text: JSON.stringify({ error: err?.message || String(err) }) }] }
-      }
-    }
-  )
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Register CIL graph query tools on an MCP server'; No verified external callers; imports: .framework/mcp/shared/db.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/tools/cil/graph.ts:register:function"]