forge-server 0.1.0

package/src/tools/pipeline-tools.ts

@@ -0,0 +1,188 @@
+// pipeline-tools.ts — B13
+// MCP tool handlers for project lifecycle management.
+// Tools: create_project, get_state
+
+import { z } from 'zod';
+import type { PipelineEngine } from '../pipeline/engine.js';
+import type { RepoRegistry } from '../knowledge/registry.js';
+import type { Phase, PipelineTier } from '../util/types.js';
+import { getAvailableTransitions } from '../pipeline/state-machine.js';
+import { logger } from '../util/logger.js';
+import { resolve } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+export const createProjectSchema = z.object({
+  name: z.string().min(1, 'Project name is required'),
+  description: z.string().optional(),
+  repo_path: z.string().optional(),
+  tier: z.enum(['full', 'abbreviated', 'trivial']).default('full'),
+  jira_ticket: z.string().optional(),
+  jira_epic: z.string().optional(),
+});
+
+export const getStateSchema = z.object({
+  project_id: z.string().min(1, 'project_id is required'),
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createPipelineTools(
+  engine: PipelineEngine,
+  registry: RepoRegistry,
+) {
+  return {
+    'create_project': {
+      schema: createProjectSchema,
+      description: 'Create a new pipeline project for a task/feature',
+      handler: async (input: z.infer<typeof createProjectSchema>) => {
+        try {
+          // Determine repo path
+          const repoPath = input.repo_path
+            ? resolve(input.repo_path)
+            : resolve(process.cwd());
+
+          // Find or auto-register the repo
+          let repo = registry.findRepoByPath(repoPath);
+
+          if (!repo) {
+            // Auto-register using current directory
+            try {
+              const result = await registry.register(repoPath);
+              repo = registry.getRepo(result.repo_id);
+              logger.info('pipeline-tools.create_project: auto-registered repo', {
+                repoId: result.repo_id,
+                path: repoPath,
+              });
+            } catch (regErr) {
+              // If registration fails (no manifest), create a minimal fallback
+              // repo entry so the project can still be created.
+              logger.warn('pipeline-tools.create_project: repo auto-register failed', {
+                path: repoPath,
+                error: String(regErr),
+              });
+              // Try to find any registered repo as fallback
+              const allRepos = registry.listRepos();
+              repo = allRepos[0] ?? null;
+
+              if (!repo) {
+                return {
+                  error: 'NO_REPO_REGISTERED',
+                  message:
+                    'No registered repo found. Run forge.init + forge.register first, ' +
+                    'or provide a valid repo_path that has a .forge/manifest.yaml.',
+                };
+              }
+            }
+          }
+
+          if (!repo) {
+            return {
+              error: 'REPO_NOT_FOUND',
+              message: `No repo found at ${repoPath}. Run forge.init to initialize.`,
+            };
+          }
+
+          // Build metadata with optional Jira context
+          const metadata: Record<string, unknown> = {};
+          if (input.jira_ticket) metadata.jira_ticket = input.jira_ticket;
+          if (input.jira_epic) metadata.jira_epic = input.jira_epic;
+
+          // Create the project
+          const project = engine.createProject({
+            name: input.name,
+            description: input.description,
+            repoId: repo.id,
+            tier: input.tier as PipelineTier,
+            metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+          });
+
+          const availableTransitions = getAvailableTransitions(
+            project.currentPhase as Phase,
+            project.tier,
+          );
+
+          logger.info('pipeline-tools.create_project: project created', {
+            projectId: project.id,
+            name: project.name,
+            repoId: repo.id,
+          });
+
+          return {
+            project_id: project.id,
+            repo_id: repo.id,
+            repo_name: repo.name,
+            current_phase: project.currentPhase,
+            tier: project.tier,
+            available_transitions: availableTransitions,
+          };
+        } catch (err) {
+          logger.error('pipeline-tools.create_project: error', { error: String(err) });
+          return {
+            error: 'CREATE_PROJECT_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+
+    'get_state': {
+      schema: getStateSchema,
+      description: 'Returns the current pipeline state and history for a project',
+      handler: async (input: z.infer<typeof getStateSchema>) => {
+        try {
+          const project = engine.getProject(input.project_id);
+          if (!project) {
+            return {
+              error: 'PROJECT_NOT_FOUND',
+              project_id: input.project_id,
+            };
+          }
+
+          const cycleCounts = engine.getCycleCounts(input.project_id);
+          const activeClaims = engine.getActiveClaims(input.project_id);
+          const { history } = engine.getHistory(input.project_id);
+
+          const availableTransitions = getAvailableTransitions(
+            project.currentPhase as Phase,
+            project.tier,
+          );
+
+          return {
+            project_id: project.id,
+            name: project.name,
+            current_phase: project.currentPhase,
+            status: project.status,
+            tier: project.tier,
+            metadata: project.metadata,
+            history: history.map(h => ({
+              phase: h.phase,
+              agent: h.agent,
+              started_at: h.startedAt,
+              completed_at: h.completedAt,
+              success: h.success,
+            })),
+            active_claims: activeClaims.map(c => ({
+              module: c.moduleName,
+              agent: c.agent,
+              status: c.status,
+            })),
+            cycle_counts: cycleCounts,
+            available_transitions: availableTransitions,
+          };
+        } catch (err) {
+          logger.error('pipeline-tools.get_state: error', { error: String(err) });
+          return {
+            error: 'GET_STATE_FAILED',
+            project_id: input.project_id,
+            message: String(err),
+          };
+        }
+      },
+    },
+  };
+}

package/src/tools/registration-tools.ts

@@ -0,0 +1,450 @@
+// registration-tools.ts — B16
+// MCP tool handlers for repo registration and initialization.
+// Tools: register, init, list_repos, get_manifest, index_repo, get_index_status
+
+import { z } from 'zod';
+import type { RepoRegistry } from '../knowledge/registry.js';
+import type { VectorStore, GraphStore, FileContentCache } from '../storage/interfaces.js';
+import { fullIndex, type IndexResult } from '../ingestion/indexer.js';
+import type { RepoConfig, IndexStatusOutput } from '../util/types.js';
+import { getUptimeSeconds } from '../memory/session-tracker.js';
+import { join, resolve } from 'node:path';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+export const registerSchema = z.object({
+  path: z.string().optional(),
+  auto: z.boolean().default(true),
+});
+
+export const initSchema = z.object({
+  path: z.string().optional(),
+  name: z.string().min(1, 'name is required'),
+  stack: z.array(z.string()).min(1, 'at least one stack tag is required'),
+  sharing: z.enum(['team', 'private', 'public']).default('private'),
+  org: z.string().optional(),
+});
+
+export const listReposSchema = z.object({});
+
+export const getManifestSchema = z.object({
+  repo_path: z.string().optional(),
+});
+
+export const indexRepoSchema = z.object({
+  repo_id: z.string().optional(),
+  path: z.string().optional(),
+  force: z.boolean().default(false),
+});
+
+export const getIndexStatusSchema = z.object({
+  repo_id: z.string().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Store dependencies for indexing
+// ---------------------------------------------------------------------------
+
+export interface RegistrationToolStores {
+  vectorStore: VectorStore | null;
+  graphStore: GraphStore | null;
+  fileCache: FileContentCache;
+}
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createRegistrationTools(
+  registry: RepoRegistry,
+  stores?: RegistrationToolStores,
+) {
+  return {
+    'register': {
+      schema: registerSchema,
+      description: 'Register a repo with the forge server, loading its .forge/manifest.yaml and syncing knowledge to Qdrant',
+      handler: async (input: z.infer<typeof registerSchema>) => {
+        try {
+          const repoPath = resolve(input.path ?? process.cwd());
+
+          const result = await registry.register(repoPath, {
+            auto: input.auto,
+          });
+
+          logger.info('registration-tools.register: completed', {
+            repoId: result.repo_id,
+            name: result.name,
+            newlyRegistered: result.newly_registered,
+          });
+
+          const response: Record<string, unknown> = {
+            repo_id: result.repo_id,
+            name: result.name,
+            path: result.path,
+            remote: result.remote,
+            stack: result.stack,
+            sharing: result.sharing,
+            newly_registered: result.newly_registered,
+            knowledge_items_loaded: result.knowledge_items_loaded,
+          };
+
+          // Auto-index after registration when auto: true and stores are available
+          if (input.auto && stores?.vectorStore) {
+            try {
+              const indexResult = await runIndex(
+                registry, stores, result.repo_id, result.path, result.stack, false,
+              );
+              response.index_result = {
+                files_processed: indexResult.filesProcessed,
+                files_skipped: indexResult.filesSkipped,
+                files_errored: indexResult.filesErrored,
+                chunks_created: indexResult.chunksCreated,
+                knowledge_items_extracted: indexResult.knowledgeItemsExtracted,
+                duration_ms: indexResult.durationMs,
+              };
+              logger.info('registration-tools.register: auto-index completed', {
+                repoId: result.repo_id,
+                filesProcessed: indexResult.filesProcessed,
+                chunksCreated: indexResult.chunksCreated,
+              });
+            } catch (indexErr) {
+              // Non-fatal: registration still succeeds
+              response.index_warning = `Auto-index failed: ${String(indexErr)}`;
+              logger.warn('registration-tools.register: auto-index failed (non-fatal)', {
+                repoId: result.repo_id,
+                error: String(indexErr),
+              });
+            }
+          }
+
+          return response;
+        } catch (err) {
+          logger.error('registration-tools.register: error', { error: String(err) });
+          return {
+            error: 'REGISTER_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+
+    'init': {
+      schema: initSchema,
+      description: 'Initialize the .forge/ directory structure in a repo, creating manifest.yaml and empty knowledge YAML files',
+      handler: async (input: z.infer<typeof initSchema>) => {
+        try {
+          const repoPath = resolve(input.path ?? process.cwd());
+
+          const manifest = {
+            name: input.name,
+            stack: input.stack,
+            sharing: input.sharing as 'team' | 'private' | 'public',
+            org: input.org,
+            repo_id_override: null,
+          };
+
+          const { forgePath, filesCreated } = registry.initForge(repoPath, manifest);
+
+          logger.info('registration-tools.init: completed', {
+            forgePath,
+            filesCreated: filesCreated.length,
+          });
+
+          return {
+            forge_dir: forgePath,
+            manifest_path: join(forgePath, 'manifest.yaml'),
+            knowledge_dir: join(forgePath, 'knowledge'),
+            files_created: filesCreated,
+          };
+        } catch (err) {
+          logger.error('registration-tools.init: error', { error: String(err) });
+          return {
+            error: 'INIT_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+
+    'list_repos': {
+      schema: listReposSchema,
+      description: 'List all registered repos with their stack tags and last-seen timestamps',
+      handler: async (_input: z.infer<typeof listReposSchema>) => {
+        try {
+          const repos = registry.listRepos();
+
+          logger.debug('registration-tools.list_repos: completed', {
+            count: repos.length,
+          });
+
+          return {
+            repos: repos.map(r => ({
+              id: r.id,
+              name: r.name,
+              path: r.path,
+              stack: r.stack,
+              sharing: r.sharing,
+              last_seen: new Date(r.lastSeenAt).toISOString(),
+              knowledge_count: r.knowledge_count,
+            })),
+          };
+        } catch (err) {
+          logger.error('registration-tools.list_repos: error', { error: String(err) });
+          return {
+            error: 'LIST_REPOS_FAILED',
+            message: String(err),
+            repos: [],
+          };
+        }
+      },
+    },
+
+    'get_manifest': {
+      schema: getManifestSchema,
+      description: 'Read and return the .forge/manifest.yaml from a repo path',
+      handler: async (input: z.infer<typeof getManifestSchema>) => {
+        try {
+          const repoPath = resolve(input.repo_path ?? process.cwd());
+          const forgePath = join(repoPath, '.forge');
+
+          const manifest = registry.readManifest(forgePath);
+          const forgeExists = registry.forgeDirectoryExists(repoPath);
+
+          return {
+            manifest: manifest
+              ? {
+                  name: manifest.name,
+                  stack: manifest.stack,
+                  sharing: manifest.sharing,
+                  org: manifest.org,
+                }
+              : null,
+            forge_dir_exists: forgeExists,
+          };
+        } catch (err) {
+          logger.error('registration-tools.get_manifest: error', { error: String(err) });
+          return {
+            error: 'GET_MANIFEST_FAILED',
+            message: String(err),
+            manifest: null,
+            forge_dir_exists: false,
+          };
+        }
+      },
+    },
+
+    'index_repo': {
+      schema: indexRepoSchema,
+      description: 'Index a registered repo, populating vector and graph stores with code chunks and extracting knowledge from markdown docs',
+      handler: async (input: z.infer<typeof indexRepoSchema>) => {
+        if (!stores?.vectorStore) {
+          return {
+            error: 'INDEX_UNAVAILABLE',
+            message: 'Vector store (Qdrant) is not available. Cannot index without it.',
+          };
+        }
+
+        try {
+          // Resolve repo by ID or path
+          let repo;
+          if (input.repo_id) {
+            repo = registry.getRepo(input.repo_id);
+            if (!repo) {
+              return {
+                error: 'REPO_NOT_FOUND',
+                message: `Repo not found: ${input.repo_id}. Run 'forge register' first.`,
+              };
+            }
+          } else {
+            const repoPath = resolve(input.path ?? process.cwd());
+            repo = registry.findRepoByPath(repoPath);
+            if (!repo) {
+              return {
+                error: 'REPO_NOT_FOUND',
+                message: `No registered repo found at ${repoPath}. Run 'forge register' first.`,
+              };
+            }
+          }
+
+          const result = await runIndex(
+            registry, stores, repo.id, repo.path, repo.stack, input.force,
+          );
+
+          logger.info('registration-tools.index_repo: completed', {
+            repoId: repo.id,
+            filesProcessed: result.filesProcessed,
+            chunksCreated: result.chunksCreated,
+            knowledgeItemsExtracted: result.knowledgeItemsExtracted,
+          });
+
+          return {
+            repo_id: result.repoId,
+            files_processed: result.filesProcessed,
+            files_skipped: result.filesSkipped,
+            files_errored: result.filesErrored,
+            chunks_created: result.chunksCreated,
+            knowledge_items_extracted: result.knowledgeItemsExtracted,
+            duration_ms: result.durationMs,
+            errors: result.errors.length > 0 ? result.errors.slice(0, 10) : undefined,
+          };
+        } catch (err) {
+          logger.error('registration-tools.index_repo: error', { error: String(err) });
+          return {
+            error: 'INDEX_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+
+    'get_index_status': {
+      schema: getIndexStatusSchema,
+      description: 'Get health and index status for all backends (Qdrant, FalkorDB, file cache). Optionally filter by repo_id for per-repo stats.',
+      handler: async (input: z.infer<typeof getIndexStatusSchema>) => {
+        try {
+          // --- Repo listing ---
+          const allRepos = registry.listRepos();
+          const filteredRepos = input.repo_id
+            ? allRepos.filter(r => r.id === input.repo_id)
+            : allRepos;
+
+          const repoStatuses = filteredRepos.map(r => ({
+            repoId: r.id,
+            path: r.path,
+            filesIndexed: 0,   // Approximate — exact count requires scanning
+            filesTotal: 0,
+            lastIndexedAt: r.lastSeenAt,
+            staleFiles: 0,
+          }));
+
+          // --- Vector store health ---
+          let vectorCounts = { codeChunks: 0, observations: 0 };
+          let qdrantHealthy = false;
+          if (stores?.vectorStore) {
+            try {
+              qdrantHealthy = await stores.vectorStore.isHealthy();
+              if (qdrantHealthy) {
+                vectorCounts = await stores.vectorStore.getCounts();
+              }
+            } catch (err) {
+              logger.warn('get_index_status: Qdrant getCounts failed', { error: String(err) });
+            }
+          }
+
+          // --- Graph store health ---
+          let graphCounts = { totalNodes: 0, totalEdges: 0, byLabel: {} as Record<string, number> };
+          let graphHealthy = false;
+          if (stores?.graphStore) {
+            try {
+              graphHealthy = await stores.graphStore.isHealthy();
+              if (graphHealthy) {
+                graphCounts = await stores.graphStore.getCounts();
+              }
+            } catch (err) {
+              logger.warn('get_index_status: FalkorDB getCounts failed', { error: String(err) });
+            }
+          }
+
+          // --- Cache stats ---
+          const cacheStats = stores?.fileCache
+            ? stores.fileCache.getStats()
+            : { entries: 0, memoryUsageMb: 0, hitRate: 0, evictionCount: 0, oldestEntryAgeSeconds: 0 };
+
+          // --- Overall health ---
+          let health: 'healthy' | 'degraded' | 'unavailable';
+          if (qdrantHealthy && graphHealthy) {
+            health = 'healthy';
+          } else if (qdrantHealthy || graphHealthy) {
+            health = 'degraded';
+          } else {
+            health = 'unavailable';
+          }
+
+          const result: IndexStatusOutput = {
+            repos: repoStatuses,
+            graph: {
+              total_nodes: graphCounts.totalNodes,
+              total_edges: graphCounts.totalEdges,
+              node_counts: graphCounts.byLabel,
+            },
+            vector: {
+              code_chunks_count: vectorCounts.codeChunks,
+              observations_count: vectorCounts.observations,
+            },
+            cache: cacheStats,
+            health,
+            embedding_model: 'Xenova/all-MiniLM-L6-v2',
+            uptime_seconds: getUptimeSeconds(),
+          };
+
+          logger.debug('registration-tools.get_index_status: completed', {
+            repoCount: repoStatuses.length,
+            health,
+            uptimeSeconds: result.uptime_seconds,
+          });
+
+          return result;
+        } catch (err) {
+          logger.error('registration-tools.get_index_status: error', { error: String(err) });
+          return {
+            error: 'GET_INDEX_STATUS_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared indexing helper
+// ---------------------------------------------------------------------------
+
+async function runIndex(
+  registry: RepoRegistry,
+  stores: RegistrationToolStores,
+  repoId: string,
+  repoPath: string,
+  stackTags: string[],
+  force: boolean,
+): Promise<IndexResult> {
+  // Build a no-op graph store if FalkorDB is unavailable
+  const effectiveGraphStore = stores.graphStore ?? createNoOpGraphStore();
+
+  const repoConfig: RepoConfig = {
+    id: repoId,
+    path: repoPath,
+    ownership: 'owned',
+    watch: false,
+    languages: stackTags,
+  };
+
+  return fullIndex({
+    repoConfig,
+    graphStore: effectiveGraphStore,
+    vectorStore: stores.vectorStore!,
+    fileCache: stores.fileCache,
+    allRepos: [repoConfig],
+  });
+}
+
+/**
+ * Minimal no-op graph store for when FalkorDB is unavailable.
+ */
+function createNoOpGraphStore(): GraphStore {
+  return {
+    connect: async () => {},
+    disconnect: async () => {},
+    isHealthy: async () => false,
+    query: async () => ({ nodes: [], edges: [], raw: [] }),
+    upsertNode: async () => {},
+    upsertEdge: async () => {},
+    deleteFile: async () => {},
+    deleteRepo: async () => {},
+    getCounts: async () => ({ totalNodes: 0, totalEdges: 0, byLabel: {} }),
+    ensureIndexes: async () => {},
+  };
+}