specvector 0.0.1 → 0.1.2

package/src/mcp/mcp-client.ts

@@ -0,0 +1,382 @@
+/**
+ * MCP Client - Unified wrapper for MCP server connections.
+ *
+ * Uses subprocess/stdio transport with JSON-RPC 2.0 protocol.
+ * Designed for ephemeral connections in CI/CD environments.
+ */
+
+import { spawn, type Subprocess, type FileSink } from "bun";
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+import type {
+  MCPServerConfig,
+  MCPError,
+  MCPRequest,
+  MCPResponse,
+  MCPTool,
+  MCPToolsListResult,
+  MCPToolCallResult,
+} from "./types";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_TIMEOUT = 30_000; // 30 seconds
+const INIT_TIMEOUT = 10_000; // 10 seconds for initialization
+
+// ============================================================================
+// MCP Client Interface
+// ============================================================================
+
+export interface MCPClient {
+  /** Server name from config */
+  readonly name: string;
+  /** Call a tool on the MCP server */
+  callTool(name: string, args: Record<string, unknown>): Promise<Result<MCPToolCallResult, MCPError>>;
+  /** List available tools */
+  listTools(): Promise<Result<MCPTool[], MCPError>>;
+  /** Close the connection and kill subprocess */
+  close(): Promise<void>;
+}
+
+// ============================================================================
+// Internal State
+// ============================================================================
+
+interface MCPClientState {
+  config: MCPServerConfig;
+  proc: Subprocess;
+  requestId: number;
+  pendingRequests: Map<number, {
+    resolve: (response: MCPResponse) => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+  }>;
+  buffer: string;
+  initialized: boolean;
+}
+
+// ============================================================================
+// MCP Client Factory
+// ============================================================================
+
+/**
+ * Create and initialize an MCP client.
+ *
+ * Spawns the MCP server subprocess and performs the initialization handshake.
+ */
+export async function createMCPClient(
+  config: MCPServerConfig
+): Promise<Result<MCPClient, MCPError>> {
+  // Spawn the subprocess
+  let proc: Subprocess;
+  try {
+    proc = spawn([config.command, ...config.args], {
+      env: { ...process.env, ...config.env },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+  } catch (error) {
+    return err({
+      code: "SPAWN_ERROR",
+      message: `Failed to spawn MCP server: ${error instanceof Error ? error.message : "Unknown error"}`,
+    });
+  }
+
+  // Create client state
+  const state: MCPClientState = {
+    config,
+    proc,
+    requestId: 0,
+    pendingRequests: new Map(),
+    buffer: "",
+    initialized: false,
+  };
+
+  // Start reading stdout
+  startReadingStdout(state);
+
+  // Start reading stderr (for debugging)
+  startReadingStderr(state);
+
+  // Perform MCP initialization handshake
+  const initResult = await initializeMCP(state);
+  if (!initResult.ok) {
+    await killProcess(state);
+    return initResult;
+  }
+
+  state.initialized = true;
+
+  // Create the client interface
+  const client: MCPClient = {
+    name: config.name,
+
+    async callTool(name: string, args: Record<string, unknown>): Promise<Result<MCPToolCallResult, MCPError>> {
+      if (!state.initialized) {
+        return err({ code: "CONNECTION_FAILED", message: "MCP client not initialized" });
+      }
+
+      const response = await sendRequest(state, "tools/call", {
+        name,
+        arguments: args,
+      });
+
+      if (!response.ok) {
+        return response;
+      }
+
+      if (response.value.error) {
+        return err({
+          code: "TOOL_ERROR",
+          message: response.value.error.message,
+        });
+      }
+
+      return ok(response.value.result as MCPToolCallResult);
+    },
+
+    async listTools(): Promise<Result<MCPTool[], MCPError>> {
+      if (!state.initialized) {
+        return err({ code: "CONNECTION_FAILED", message: "MCP client not initialized" });
+      }
+
+      const response = await sendRequest(state, "tools/list", {});
+
+      if (!response.ok) {
+        return response;
+      }
+
+      if (response.value.error) {
+        return err({
+          code: "SERVER_ERROR",
+          message: response.value.error.message,
+        });
+      }
+
+      const result = response.value.result as MCPToolsListResult;
+      return ok(result.tools);
+    },
+
+    async close(): Promise<void> {
+      await killProcess(state);
+    },
+  };
+
+  return ok(client);
+}
+
+// ============================================================================
+// Internal Functions
+// ============================================================================
+
+/**
+ * Perform MCP initialization handshake.
+ */
+async function initializeMCP(state: MCPClientState): Promise<Result<void, MCPError>> {
+  // Send initialize request
+  const initResponse = await sendRequest(state, "initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: {
+      name: "specvector",
+      version: "1.0.0",
+    },
+  }, INIT_TIMEOUT);
+
+  if (!initResponse.ok) {
+    return err(initResponse.error);
+  }
+
+  if (initResponse.value.error) {
+    return err({
+      code: "PROTOCOL_ERROR",
+      message: `MCP initialization failed: ${initResponse.value.error.message}`,
+    });
+  }
+
+  // Send initialized notification (no response expected)
+  const notification: MCPRequest = {
+    jsonrpc: "2.0",
+    id: 0, // Notifications don't have IDs, but we include for consistency
+    method: "notifications/initialized",
+    params: {},
+  };
+
+  try {
+    const writer = state.proc.stdin as FileSink | null;
+    if (writer && typeof writer.write === "function") {
+      writer.write(JSON.stringify(notification) + "\n");
+    }
+  } catch {
+    // Notification failures are non-fatal
+  }
+
+  return ok(undefined);
+}
+
+/**
+ * Send a JSON-RPC request and await response.
+ */
+async function sendRequest(
+  state: MCPClientState,
+  method: string,
+  params: Record<string, unknown>,
+  timeout?: number
+): Promise<Result<MCPResponse, MCPError>> {
+  const id = ++state.requestId;
+  const request: MCPRequest = {
+    jsonrpc: "2.0",
+    id,
+    method,
+    params,
+  };
+
+  const requestTimeout = timeout ?? state.config.timeout ?? DEFAULT_TIMEOUT;
+
+  return new Promise((resolve) => {
+    // Set up timeout
+    const timeoutHandle = setTimeout(() => {
+      state.pendingRequests.delete(id);
+      resolve(err({
+        code: "TIMEOUT",
+        message: `Request timed out after ${requestTimeout}ms`,
+      }));
+    }, requestTimeout);
+
+    // Store pending request
+    state.pendingRequests.set(id, {
+      resolve: (response: MCPResponse) => {
+        clearTimeout(timeoutHandle);
+        state.pendingRequests.delete(id);
+        resolve(ok(response));
+      },
+      reject: (error: Error) => {
+        clearTimeout(timeoutHandle);
+        state.pendingRequests.delete(id);
+        resolve(err({
+          code: "PROTOCOL_ERROR",
+          message: error.message,
+        }));
+      },
+      timeout: timeoutHandle,
+    });
+
+    // Send the request
+    try {
+      const writer = state.proc.stdin as FileSink | null;
+      if (writer && typeof writer.write === "function") {
+        writer.write(JSON.stringify(request) + "\n");
+      } else {
+        state.pendingRequests.get(id)?.reject(new Error("stdin not available"));
+      }
+    } catch (error) {
+      state.pendingRequests.get(id)?.reject(
+        error instanceof Error ? error : new Error("Failed to write to stdin")
+      );
+    }
+  });
+}
+
+/**
+ * Start reading stdout and dispatch responses.
+ */
+function startReadingStdout(state: MCPClientState): void {
+  const reader = state.proc.stdout;
+  if (!reader || typeof reader === "number") return;
+
+  const stream = reader as ReadableStream<Uint8Array>;
+  const textReader = stream.getReader();
+
+  (async () => {
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await textReader.read();
+        if (done) break;
+        state.buffer += decoder.decode(value, { stream: true });
+        processBuffer(state);
+      }
+    } catch {
+      // Stream ended or error - reject all pending requests
+      for (const [, pending] of state.pendingRequests) {
+        pending.reject(new Error("Connection closed"));
+      }
+      state.pendingRequests.clear();
+    }
+  })();
+}
+
+/**
+ * Process buffered data, extracting complete JSON lines.
+ */
+function processBuffer(state: MCPClientState): void {
+  let newlineIndex: number;
+  while ((newlineIndex = state.buffer.indexOf("\n")) !== -1) {
+    const line = state.buffer.slice(0, newlineIndex).trim();
+    state.buffer = state.buffer.slice(newlineIndex + 1);
+
+    if (!line) continue;
+
+    try {
+      const response = JSON.parse(line) as MCPResponse;
+      const pending = state.pendingRequests.get(response.id);
+      if (pending) {
+        pending.resolve(response);
+      }
+    } catch {
+      // Invalid JSON - ignore
+    }
+  }
+}
+
+/**
+ * Start reading stderr for debugging.
+ */
+function startReadingStderr(state: MCPClientState): void {
+  const reader = state.proc.stderr;
+  if (!reader || typeof reader === "number") return;
+
+  const stream = reader as ReadableStream<Uint8Array>;
+  const textReader = stream.getReader();
+
+  (async () => {
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await textReader.read();
+        if (done) break;
+        const text = decoder.decode(value, { stream: true });
+        // Log stderr for debugging (could be made configurable)
+        if (text.trim()) {
+          console.error(`[MCP:${state.config.name}] ${text.trim()}`);
+        }
+      }
+    } catch {
+      // Ignore stderr errors
+    }
+  })();
+}
+
+/**
+ * Kill the subprocess and clean up.
+ */
+async function killProcess(state: MCPClientState): Promise<void> {
+  // Clear all pending requests
+  for (const [, pending] of state.pendingRequests) {
+    clearTimeout(pending.timeout);
+    pending.reject(new Error("Client closed"));
+  }
+  state.pendingRequests.clear();
+
+  // Kill the process
+  try {
+    state.proc.kill();
+  } catch {
+    // Ignore kill errors
+  }
+
+  state.initialized = false;
+}

package/src/mcp/types.ts

@@ -0,0 +1,104 @@
+/**
+ * MCP (Model Context Protocol) Type Definitions
+ *
+ * Types for the JSON-RPC 2.0 protocol used by MCP servers.
+ */
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export type MCPErrorCode =
+  | "CONNECTION_FAILED"
+  | "SPAWN_ERROR"
+  | "TIMEOUT"
+  | "PROTOCOL_ERROR"
+  | "TOOL_ERROR"
+  | "SERVER_ERROR";
+
+export interface MCPError {
+  code: MCPErrorCode;
+  message: string;
+}
+
+// ============================================================================
+// Server Configuration
+// ============================================================================
+
+export interface MCPServerConfig {
+  /** Server identifier (e.g., 'linear', 'filesystem') */
+  name: string;
+  /** Command to spawn (e.g., 'bunx', 'npx', or path to binary) */
+  command: string;
+  /** Arguments for the command (e.g., ['-y', '@anthropic-ai/mcp-server-linear']) */
+  args: string[];
+  /** Environment variables to pass (merged with process.env) */
+  env?: Record<string, string>;
+  /** Timeout in ms for requests (default: 30000) */
+  timeout?: number;
+}
+
+// ============================================================================
+// MCP Protocol Types (JSON-RPC 2.0)
+// ============================================================================
+
+export interface MCPRequest {
+  jsonrpc: "2.0";
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface MCPResponse {
+  jsonrpc: "2.0";
+  id: number;
+  result?: unknown;
+  error?: MCPRPCError;
+}
+
+export interface MCPRPCError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+// ============================================================================
+// MCP Tool Types
+// ============================================================================
+
+export interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema: MCPInputSchema;
+}
+
+export interface MCPInputSchema {
+  type: "object";
+  properties?: Record<string, MCPSchemaProperty>;
+  required?: string[];
+}
+
+export interface MCPSchemaProperty {
+  type: string;
+  description?: string;
+}
+
+// ============================================================================
+// MCP Result Types (for tools/list and tools/call)
+// ============================================================================
+
+export interface MCPToolsListResult {
+  tools: MCPTool[];
+}
+
+export interface MCPToolCallResult {
+  content: MCPContent[];
+  isError?: boolean;
+}
+
+export interface MCPContent {
+  type: "text" | "image" | "resource";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+}

package/src/review/diff-parser.ts

@@ -0,0 +1,168 @@
+/**
+ * Diff parser for unified diff format.
+ * Converts raw `gh pr diff` output into structured types.
+ */
+
+import type {
+  DiffChange,
+  DiffFile,
+  DiffHunk,
+  ParsedDiff,
+} from "../types/diff";
+
+/**
+ * Parse a unified diff string into structured format.
+ */
+export function parseDiff(diffText: string): ParsedDiff {
+  const files: DiffFile[] = [];
+  let totalAdditions = 0;
+  let totalDeletions = 0;
+
+  // Split by file boundaries (diff --git)
+  const fileSections = diffText.split(/^diff --git /m).filter(Boolean);
+
+  for (const section of fileSections) {
+    const file = parseFileSection(section);
+    if (file) {
+      files.push(file);
+      totalAdditions += file.additions;
+      totalDeletions += file.deletions;
+    }
+  }
+
+  return {
+    files,
+    totalAdditions,
+    totalDeletions,
+    filesChanged: files.length,
+  };
+}
+
+/**
+ * Parse a single file section from the diff.
+ */
+function parseFileSection(section: string): DiffFile | null {
+  const lines = section.split("\n");
+  if (lines.length === 0) return null;
+
+  // First line is the file paths: a/path b/path
+  const headerMatch = lines[0]?.match(/^a\/(.+?) b\/(.+?)$/);
+  if (!headerMatch) return null;
+
+  const oldPath = headerMatch[1] ?? null;
+  const newPath = headerMatch[2] ?? null;
+
+  // Check for binary file
+  const isBinary = lines.some((line) => line.startsWith("Binary files"));
+  if (isBinary) {
+    return {
+      oldPath,
+      newPath,
+      status: determineStatus(oldPath, newPath, lines),
+      binary: true,
+      hunks: [],
+      additions: 0,
+      deletions: 0,
+    };
+  }
+
+  // Parse hunks
+  const hunks: DiffHunk[] = [];
+  let currentHunk: DiffHunk | null = null;
+  let additions = 0;
+  let deletions = 0;
+
+  for (const line of lines) {
+    // Hunk header: @@ -1,3 +1,4 @@
+    const hunkMatch = line.match(/^@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@/);
+    if (hunkMatch) {
+      if (currentHunk) {
+        hunks.push(currentHunk);
+      }
+      currentHunk = {
+        oldStart: parseInt(hunkMatch[1] ?? "0", 10),
+        oldLines: parseInt(hunkMatch[2] ?? "1", 10) || 1,
+        newStart: parseInt(hunkMatch[3] ?? "0", 10),
+        newLines: parseInt(hunkMatch[4] ?? "1", 10) || 1,
+        content: line,
+        changes: [],
+      };
+      continue;
+    }
+
+    // Content lines
+    if (currentHunk && (line.startsWith("+") || line.startsWith("-") || line.startsWith(" "))) {
+      const change: DiffChange = {
+        type: line.startsWith("+") ? "add" : line.startsWith("-") ? "delete" : "normal",
+        content: line.slice(1),
+      };
+      currentHunk.changes.push(change);
+      currentHunk.content += "\n" + line;
+
+      if (line.startsWith("+") && !line.startsWith("+++")) {
+        additions++;
+      } else if (line.startsWith("-") && !line.startsWith("---")) {
+        deletions++;
+      }
+    }
+  }
+
+  // Push last hunk
+  if (currentHunk) {
+    hunks.push(currentHunk);
+  }
+
+  return {
+    oldPath,
+    newPath,
+    status: determineStatus(oldPath, newPath, lines),
+    binary: false,
+    hunks,
+    additions,
+    deletions,
+  };
+}
+
+/**
+ * Determine the status of a file change.
+ */
+function determineStatus(
+  oldPath: string | null,
+  newPath: string | null,
+  lines: string[]
+): DiffFile["status"] {
+  // Check for new file
+  if (lines.some((l) => l.startsWith("new file mode"))) {
+    return "added";
+  }
+  // Check for deleted file
+  if (lines.some((l) => l.startsWith("deleted file mode"))) {
+    return "deleted";
+  }
+  // Check for rename
+  if (lines.some((l) => l.startsWith("rename from")) || oldPath !== newPath) {
+    return "renamed";
+  }
+  return "modified";
+}
+
+/**
+ * Get a summary of the diff for logging.
+ */
+export function getDiffSummary(diff: ParsedDiff): string {
+  const lines = [
+    `Files changed: ${diff.filesChanged}`,
+    `Additions: +${diff.totalAdditions}`,
+    `Deletions: -${diff.totalDeletions}`,
+    "",
+    "Files:",
+  ];
+
+  for (const file of diff.files) {
+    const path = file.newPath ?? file.oldPath ?? "unknown";
+    const stats = file.binary ? "(binary)" : `+${file.additions}/-${file.deletions}`;
+    lines.push(`  ${file.status}: ${path} ${stats}`);
+  }
+
+  return lines.join("\n");
+}