forge-server 0.1.0

package/src/tools/context-tools.ts

@@ -0,0 +1,493 @@
+// context-tools.ts — B15
+// MCP tool handlers for codebase context and knowledge search.
+// Tools: search_knowledge, get_codebase_context, get_project_history, get_git_context
+
+import { z } from 'zod';
+import type { KnowledgeSearch } from '../knowledge/search.js';
+import type { CodebaseContext } from '../context/codebase.js';
+import type { MemoryBridge } from '../context/memory.js';
+import type { PipelineEngine } from '../pipeline/engine.js';
+import type { VectorStore, GraphStore } from '../storage/interfaces.js';
+import { detectIntent, getIntentStrategy } from '../query/intent-detector.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+export const searchKnowledgeSchema = z.object({
+  query: z.string().min(1, 'query is required'),
+  category: z.enum(['gotcha', 'pattern', 'decision', 'convention']).optional(),
+  stack_tags: z.array(z.string()).optional(),
+  repo_id: z.string().optional(),
+  limit: z.number().int().min(1).max(50).default(10),
+  include_cross_repo: z.boolean().default(true),
+});
+
+export const getCodebaseContextSchema = z.object({
+  query: z.string().min(1, 'query is required'),
+  repo_id: z.string().optional(),
+  detail: z.enum(['full', 'skeleton', 'paths']).default('full'),
+  max_results: z.number().int().min(1).max(20).default(5),
+  include_tests: z.boolean().default(false),
+  include_cross_repo: z.boolean().default(true),
+});
+
+export const getProjectHistorySchema = z.object({
+  project_id: z.string().min(1, 'project_id is required'),
+});
+
+export const getGitContextSchema = z.object({
+  mode: z.enum(['hotspots', 'commit_search', 'file_history']),
+  repo_id: z.string().optional(),
+  query: z.string().optional(),
+  file_path: z.string().optional(),
+  limit: z.number().int().min(1).max(100).default(20),
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createContextTools(
+  knowledgeSearch: KnowledgeSearch,
+  codebaseContext: CodebaseContext,
+  engine: PipelineEngine,
+  memoryBridge?: MemoryBridge | null,
+  vectorStore?: VectorStore | null,
+  graphStore?: GraphStore | null,
+) {
+  return {
+    'search_knowledge': {
+      schema: searchKnowledgeSchema,
+      description: 'Semantic search over knowledge items (gotchas, patterns, decisions, conventions) across all registered repos. PREFER THIS over ad-hoc file searching when looking for known issues, established patterns, or past decisions — it searches curated knowledge, not raw code. Cross-repo results are filtered by repo sharing mode. Provide repo_id to boost same-repo results.',
+      handler: async (input: z.infer<typeof searchKnowledgeSchema>) => {
+        try {
+          const results = await knowledgeSearch.search(input.query, {
+            category: input.category,
+            stack_tags: input.stack_tags,
+            repo_id: input.repo_id,
+            limit: input.limit,
+            include_cross_repo: input.include_cross_repo,
+          });
+
+          const reposSearched = new Set(results.map(r => r.source_repo)).size;
+
+          logger.debug('context-tools.search_knowledge: completed', {
+            query: input.query.slice(0, 80),
+            resultCount: results.length,
+          });
+
+          return {
+            results: results.map(r => ({
+              id: r.id,
+              category: r.category,
+              title: r.title,
+              content: r.content,
+              confidence: r.confidence,
+              stack_tags: r.stack_tags,
+              source_repo: r.source_repo,
+              relevance_score: r.relevance_score,
+            })),
+            search_method: 'vector' as const,
+            repos_searched: reposSearched,
+          };
+        } catch (err) {
+          logger.error('context-tools.search_knowledge: error', { error: String(err) });
+          return {
+            error: 'SEARCH_KNOWLEDGE_FAILED',
+            message: String(err),
+            results: [],
+            search_method: 'vector' as const,
+            repos_searched: 0,
+          };
+        }
+      },
+    },
+
+    'get_codebase_context': {
+      schema: getCodebaseContextSchema,
+      description: 'Hybrid search over indexed codebase (vector + graph) to retrieve relevant code context for a query. PREFER THIS over built-in Read/Grep/Glob when the repo is indexed — it combines vector similarity, graph centrality, recency, and hotspot scoring for much better results than keyword search. Cross-repo results are filtered by repo sharing mode. Provide repo_id to scope to a single repo.',
+      handler: async (input: z.infer<typeof getCodebaseContextSchema>) => {
+        const startTime = Date.now();
+        try {
+          // Classify query intent and get retrieval strategy weights
+          const queryIntent = detectIntent(input.query);
+          const strategy = getIntentStrategy(queryIntent);
+
+          const result = await codebaseContext.getContext(input.query, {
+            repoId: input.repo_id,
+            detail: input.detail,
+            maxResults: input.max_results,
+            includeTests: input.include_tests ?? strategy.includeTests,
+            includeCrossRepo: input.include_cross_repo,
+            maxTokens: 8000,
+            vectorWeight: strategy.vectorWeight,
+            graphWeight: strategy.graphWeight,
+          });
+
+          // Populate related memories from observation store
+          let relatedMemories: Array<{
+            content: string;
+            relevance_score: number;
+          }> = [];
+          if (memoryBridge) {
+            try {
+              const memories = await memoryBridge.searchMemories(input.query, {
+                repoId: input.repo_id,
+                limit: 3,
+              });
+              relatedMemories = memories.map(m => ({
+                content: m.content,
+                relevance_score: m.relevanceScore,
+              }));
+            } catch (memErr) {
+              logger.debug('context-tools.get_codebase_context: memory search failed (non-fatal)', {
+                error: String(memErr),
+              });
+            }
+          }
+
+          const executionTimeMs = Date.now() - startTime;
+
+          logger.debug('context-tools.get_codebase_context: completed', {
+            query: input.query.slice(0, 80),
+            queryIntent,
+            pivotCount: result.pivotFiles.length,
+            tokenCount: result.tokenCount,
+            memoryCount: relatedMemories.length,
+            executionTimeMs,
+          });
+
+          return {
+            pivot_files: result.pivotFiles.map(f => ({
+              file_path: f.filePath,
+              content: f.content,
+              relevance_score: f.relevanceScore,
+              match_reason: f.matchReason,
+            })),
+            supporting_skeletons: result.supportingSkeletons.map(s => ({
+              file_path: s.filePath,
+              skeleton: s.skeleton,
+              relevance_score: s.relevanceScore,
+            })),
+            related_memories: relatedMemories,
+            query_intent: queryIntent,
+            token_count: result.tokenCount,
+            execution_time_ms: executionTimeMs,
+          };
+        } catch (err) {
+          logger.error('context-tools.get_codebase_context: error', { error: String(err) });
+          return {
+            error: 'GET_CODEBASE_CONTEXT_FAILED',
+            message: String(err),
+            pivot_files: [],
+            supporting_skeletons: [],
+            related_memories: [],
+            query_intent: 'read',
+            token_count: 0,
+            execution_time_ms: Date.now() - startTime,
+          };
+        }
+      },
+    },
+
+    'get_project_history': {
+      schema: getProjectHistorySchema,
+      description: 'Returns the full event history and phase outputs for a project. Use this to understand what happened during a pipeline run — phase transitions, agent outputs, broadcasts, and decisions.',
+      handler: async (input: z.infer<typeof getProjectHistorySchema>) => {
+        try {
+          const project = engine.getProject(input.project_id);
+          if (!project) {
+            return {
+              error: 'PROJECT_NOT_FOUND',
+              project_id: input.project_id,
+            };
+          }
+
+          const { events, outputs } = engine.getHistory(input.project_id);
+
+          logger.debug('context-tools.get_project_history: completed', {
+            projectId: input.project_id,
+            eventCount: events.length,
+            outputCount: outputs.length,
+          });
+
+          return {
+            project_id: input.project_id,
+            events: events.map(ev => ({
+              type: ev.eventType,
+              from_phase: ev.fromPhase ?? undefined,
+              to_phase: ev.toPhase ?? undefined,
+              agent: ev.agent ?? undefined,
+              timestamp: new Date(ev.createdAt).toISOString(),
+              payload: ev.payload as Record<string, unknown>,
+            })),
+            outputs: outputs.map(o => ({
+              phase: o.phase,
+              type: o.outputType,
+              preview: o.content.slice(0, 500),
+              file_path: o.filePath ?? undefined,
+              timestamp: new Date(o.createdAt).toISOString(),
+            })),
+          };
+        } catch (err) {
+          logger.error('context-tools.get_project_history: error', { error: String(err) });
+          return {
+            error: 'GET_PROJECT_HISTORY_FAILED',
+            project_id: input.project_id,
+            message: String(err),
+          };
+        }
+      },
+    },
+
+    'get_git_context': {
+      schema: getGitContextSchema,
+      description: 'Query git history context: hotspots (frequently changed files), commit_search (semantic search over commit messages), or file_history (commits for a specific file). PREFER THIS over raw `git log` commands — it uses indexed data with semantic search over commit messages. Requires FalkorDB for hotspots/file_history and Qdrant git_commits collection for commit_search.',
+      handler: async (input: z.infer<typeof getGitContextSchema>) => {
+        try {
+          switch (input.mode) {
+            // -----------------------------------------------------------------
+            // hotspots: top N files by commit_count from FalkorDB File nodes
+            // -----------------------------------------------------------------
+            case 'hotspots': {
+              if (!graphStore) {
+                return {
+                  mode: 'hotspots',
+                  error: 'GRAPH_UNAVAILABLE',
+                  message: 'FalkorDB is not connected — hotspots require the graph store',
+                  results: [],
+                };
+              }
+
+              const graphHealthy = await graphStore.isHealthy();
+              if (!graphHealthy) {
+                return {
+                  mode: 'hotspots',
+                  error: 'GRAPH_UNAVAILABLE',
+                  message: 'FalkorDB is unhealthy — hotspots unavailable',
+                  results: [],
+                };
+              }
+
+              const repoFilter = input.repo_id
+                ? `{repo_id: "${escCypher(input.repo_id)}"}`
+                : '';
+              const cypher = `
+                MATCH (f:File ${repoFilter})
+                WHERE f.commit_count IS NOT NULL AND f.commit_count > 0
+                RETURN f.path AS path, f.commit_count AS commit_count,
+                       f.stability_score AS stability_score,
+                       f.change_velocity AS change_velocity
+                ORDER BY f.commit_count DESC
+                LIMIT ${input.limit}
+              `;
+
+              const result = await graphStore.query(cypher);
+              const rows = result.raw ?? [];
+
+              const hotspots = rows.map((row: unknown) => {
+                if (Array.isArray(row)) {
+                  return {
+                    file_path: row[0] as string,
+                    commit_count: row[1] as number,
+                    stability_score: row[2] as number | null,
+                    change_velocity: row[3] as number | null,
+                  };
+                }
+                const obj = row as Record<string, unknown>;
+                return {
+                  file_path: obj.path as string,
+                  commit_count: obj.commit_count as number,
+                  stability_score: (obj.stability_score as number) ?? null,
+                  change_velocity: (obj.change_velocity as number) ?? null,
+                };
+              });
+
+              logger.debug('context-tools.get_git_context: hotspots', {
+                repoId: input.repo_id,
+                resultCount: hotspots.length,
+              });
+
+              return {
+                mode: 'hotspots',
+                results: hotspots,
+                total: hotspots.length,
+              };
+            }
+
+            // -----------------------------------------------------------------
+            // commit_search: semantic search over git_commits in Qdrant
+            // -----------------------------------------------------------------
+            case 'commit_search': {
+              if (!input.query) {
+                return {
+                  mode: 'commit_search',
+                  error: 'MISSING_QUERY',
+                  message: 'commit_search mode requires a query string',
+                  results: [],
+                };
+              }
+
+              // Guard: searchGitCommits is a QdrantVectorStore-specific method
+              // that only exists after git_commits collection is created (Phase 3)
+              if (
+                !vectorStore ||
+                !('searchGitCommits' in vectorStore)
+              ) {
+                return {
+                  mode: 'commit_search',
+                  error: 'GIT_COMMITS_UNAVAILABLE',
+                  message: 'Git commits collection is not indexed — run index_repo with git enrichment first',
+                  results: [],
+                };
+              }
+
+              const healthy = await vectorStore.isHealthy();
+              if (!healthy) {
+                return {
+                  mode: 'commit_search',
+                  error: 'VECTOR_UNAVAILABLE',
+                  message: 'Qdrant is unhealthy — commit search unavailable',
+                  results: [],
+                };
+              }
+
+              const qdrantStore = vectorStore as unknown as { searchGitCommits(query: string, opts: { repoId?: string; limit?: number }): Promise<Array<{ id: string; score: number; payload: Record<string, unknown> }>> };
+              const commits = await qdrantStore.searchGitCommits(input.query, {
+                repoId: input.repo_id,
+                limit: input.limit,
+              });
+
+              logger.debug('context-tools.get_git_context: commit_search', {
+                query: input.query.slice(0, 80),
+                resultCount: Array.isArray(commits) ? commits.length : 0,
+              });
+
+              return {
+                mode: 'commit_search',
+                results: Array.isArray(commits) ? commits : [],
+                total: Array.isArray(commits) ? commits.length : 0,
+              };
+            }
+
+            // -----------------------------------------------------------------
+            // file_history: recent commits for a specific file from FalkorDB
+            // -----------------------------------------------------------------
+            case 'file_history': {
+              if (!input.file_path) {
+                return {
+                  mode: 'file_history',
+                  error: 'MISSING_FILE_PATH',
+                  message: 'file_history mode requires a file_path',
+                  results: [],
+                };
+              }
+
+              if (!graphStore) {
+                return {
+                  mode: 'file_history',
+                  error: 'GRAPH_UNAVAILABLE',
+                  message: 'FalkorDB is not connected — file history requires the graph store',
+                  results: [],
+                };
+              }
+
+              const graphHealthy = await graphStore.isHealthy();
+              if (!graphHealthy) {
+                return {
+                  mode: 'file_history',
+                  error: 'GRAPH_UNAVAILABLE',
+                  message: 'FalkorDB is unhealthy — file history unavailable',
+                  results: [],
+                };
+              }
+
+              const repoMatch = input.repo_id
+                ? `, repo_id: "${escCypher(input.repo_id)}"`
+                : '';
+              const cypher = `
+                MATCH (f:File {path: "${escCypher(input.file_path)}"${repoMatch}})
+                RETURN f.path AS path, f.commit_count AS commit_count,
+                       f.stability_score AS stability_score,
+                       f.change_velocity AS change_velocity,
+                       f.last_commit_hash AS last_commit_hash,
+                       f.last_commit_ts AS last_commit_ts
+              `;
+
+              const result = await graphStore.query(cypher);
+              const rows = result.raw ?? [];
+
+              const fileStats = rows.map((row: unknown) => {
+                if (Array.isArray(row)) {
+                  return {
+                    file_path: row[0] as string,
+                    commit_count: row[1] as number | null,
+                    stability_score: row[2] as number | null,
+                    change_velocity: row[3] as number | null,
+                    last_commit_hash: row[4] as string | null,
+                    last_commit_ts: row[5] as number | null,
+                  };
+                }
+                const obj = row as Record<string, unknown>;
+                return {
+                  file_path: obj.path as string,
+                  commit_count: (obj.commit_count as number) ?? null,
+                  stability_score: (obj.stability_score as number) ?? null,
+                  change_velocity: (obj.change_velocity as number) ?? null,
+                  last_commit_hash: (obj.last_commit_hash as string) ?? null,
+                  last_commit_ts: (obj.last_commit_ts as number) ?? null,
+                };
+              });
+
+              logger.debug('context-tools.get_git_context: file_history', {
+                filePath: input.file_path,
+                found: fileStats.length > 0,
+              });
+
+              return {
+                mode: 'file_history',
+                results: fileStats,
+                total: fileStats.length,
+              };
+            }
+
+            default:
+              return {
+                error: 'INVALID_MODE',
+                message: `Unknown mode: ${String((input as Record<string, unknown>).mode)}`,
+              };
+          }
+        } catch (err) {
+          logger.error('context-tools.get_git_context: error', {
+            mode: input.mode,
+            error: String(err),
+          });
+          return {
+            mode: input.mode,
+            error: 'GET_GIT_CONTEXT_FAILED',
+            message: String(err),
+            results: [],
+          };
+        }
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape a string for safe embedding in Cypher queries.
+ * FalkorDB uses double-quoted strings.
+ */
+function escCypher(s: string): string {
+  return s
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '');
+}