@cdoing/core 0.1.0

package/src/indexing/recent-edits-cache.ts

@@ -0,0 +1,150 @@
+/**
+ * Recently-Edited LRU Cache — Keeps recently edited files hot for fast retrieval.
+ *
+ * When the agent edits a file, it's added to this cache. Subsequent codebase
+ * searches prioritize cached files, and context providers can include recent
+ * edits without re-reading from disk.
+ *
+ * This matches what Cursor and Windsurf do with their "recently edited" caches
+ * to improve relevance of search results and context suggestions.
+ */
+
+export interface CachedEdit {
+  /** Absolute file path */
+  filePath: string;
+  /** Content at time of last edit */
+  content: string;
+  /** Timestamp of last edit */
+  editedAt: number;
+  /** Number of times this file has been edited in the session */
+  editCount: number;
+  /** Brief description of last edit (e.g., "replaced 2 occurrences") */
+  lastEditSummary: string;
+}
+
+export class RecentEditsCache {
+  private cache = new Map<string, CachedEdit>();
+  private readonly maxSize: number;
+
+  constructor(maxSize: number = 50) {
+    this.maxSize = maxSize;
+  }
+
+  /**
+   * Record a file edit. Moves the file to the front of the LRU cache.
+   */
+  put(filePath: string, content: string, editSummary: string = ""): void {
+    const existing = this.cache.get(filePath);
+
+    // Delete first to re-insert at end (Map preserves insertion order)
+    if (existing) {
+      this.cache.delete(filePath);
+    }
+
+    this.cache.set(filePath, {
+      filePath,
+      content,
+      editedAt: Date.now(),
+      editCount: (existing?.editCount || 0) + 1,
+      lastEditSummary: editSummary,
+    });
+
+    // Evict oldest if over capacity
+    if (this.cache.size > this.maxSize) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) {
+        this.cache.delete(oldest);
+      }
+    }
+  }
+
+  /**
+   * Get a cached file by path. Returns null if not in cache.
+   */
+  get(filePath: string): CachedEdit | null {
+    return this.cache.get(filePath) || null;
+  }
+
+  /**
+   * Check if a file is in the cache.
+   */
+  has(filePath: string): boolean {
+    return this.cache.has(filePath);
+  }
+
+  /**
+   * Get all cached edits, ordered by most recently edited first.
+   */
+  getRecent(limit: number = 10): CachedEdit[] {
+    const entries = Array.from(this.cache.values());
+    // Map preserves insertion order; last inserted = most recent
+    return entries.reverse().slice(0, limit);
+  }
+
+  /**
+   * Get file paths of recently edited files, most recent first.
+   */
+  getRecentPaths(limit: number = 10): string[] {
+    return this.getRecent(limit).map((e) => e.filePath);
+  }
+
+  /**
+   * Get files that match a search query (case-insensitive path match).
+   * Recently edited files that match are boosted in search results.
+   */
+  searchByPath(query: string): CachedEdit[] {
+    const lower = query.toLowerCase();
+    return Array.from(this.cache.values())
+      .filter((e) => e.filePath.toLowerCase().includes(lower))
+      .reverse(); // most recent first
+  }
+
+  /**
+   * Search cached file contents for a text pattern.
+   */
+  searchContent(pattern: string): Array<{ entry: CachedEdit; matches: number }> {
+    const results: Array<{ entry: CachedEdit; matches: number }> = [];
+    const regex = new RegExp(pattern, "gi");
+
+    for (const entry of this.cache.values()) {
+      const matches = (entry.content.match(regex) || []).length;
+      if (matches > 0) {
+        results.push({ entry, matches });
+      }
+    }
+
+    // Sort by match count (descending), then recency
+    return results.sort((a, b) => b.matches - a.matches || b.entry.editedAt - a.entry.editedAt);
+  }
+
+  /**
+   * Remove a file from the cache.
+   */
+  remove(filePath: string): boolean {
+    return this.cache.delete(filePath);
+  }
+
+  /**
+   * Clear the entire cache.
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  stats(): { size: number; maxSize: number; totalEdits: number; oldestEditAt: number | null } {
+    let totalEdits = 0;
+    let oldestEditAt: number | null = null;
+
+    for (const entry of this.cache.values()) {
+      totalEdits += entry.editCount;
+      if (oldestEditAt === null || entry.editedAt < oldestEditAt) {
+        oldestEditAt = entry.editedAt;
+      }
+    }
+
+    return { size: this.cache.size, maxSize: this.maxSize, totalEdits, oldestEditAt };
+  }
+}

package/src/indexing/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Indexing Types — interfaces for the codebase indexing system.
+ */
+
+export interface IndexTag {
+  directory: string;
+  branch: string;
+  artifactId: string;
+}
+
+export interface ChunkWithMeta {
+  content: string;
+  path: string;
+  startLine: number;
+  endLine: number;
+  cacheKey: string;
+}
+
+export interface SearchResult {
+  path: string;
+  content: string;
+  startLine: number;
+  endLine: number;
+  score: number;
+  source: "fts" | "embedding" | "recent";
+}
+
+export interface IndexingProgress {
+  phase: string;
+  current: number;
+  total: number;
+  message: string;
+}
+
+export type IndexingProgressCallback = (progress: IndexingProgress) => void;
+
+export interface IndexStats {
+  totalFiles: number;
+  totalChunks: number;
+  ftsEntries: number;
+  embeddingEntries: number;
+  lastIndexed: number;
+  indexSizeBytes: number;
+}

package/src/mcp/index.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP (Model Context Protocol) Server Support
+ *
+ * MCP is an open protocol that lets AI models connect to external
+ * data sources and tools. Think of it as "USB for AI" — a standard
+ * way to plug in capabilities.
+ *
+ * How it works:
+ *   1. User configures MCP servers in .cdoing/mcp.json or settings
+ *   2. On startup, we connect to each configured server
+ *   3. Discover available tools from each server
+ *   4. Register those tools so the agent can call them
+ *   5. Route tool calls through the MCP protocol
+ *
+ * Configuration format (.cdoing/mcp.json):
+ *   {
+ *     "servers": [
+ *       {
+ *         "name": "jira",
+ *         "command": "npx",
+ *         "args": ["-y", "@modelcontextprotocol/server-jira"],
+ *         "env": { "JIRA_URL": "https://..." }
+ *       }
+ *     ]
+ *   }
+ *
+ * Learning note: MCP uses JSON-RPC over stdio or SSE (Server-Sent Events).
+ * Each server is a separate process that we spawn and communicate with
+ * through its stdin/stdout. This isolation means a buggy MCP server
+ * can't crash the main agent.
+ */
+
+export { McpManager, type McpServerConfig, type McpTool } from "./manager";

package/src/mcp/manager.ts

@@ -0,0 +1,385 @@
+/**
+ * MCP Manager — Manages connections to MCP (Model Context Protocol) servers.
+ *
+ * Handles:
+ *   - Loading server configurations
+ *   - Spawning and connecting to server processes
+ *   - Tool discovery (listing available tools from each server)
+ *   - Routing tool calls to the correct server
+ *   - Graceful shutdown of server processes
+ *
+ * Learning note: This uses JSON-RPC 2.0 over stdio for communication.
+ * Each message is a JSON object separated by newlines. The protocol
+ * is stateless — each request gets exactly one response.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { spawn, type ChildProcess } from "child_process";
+
+/**
+ * Configuration for a single MCP server.
+ */
+export interface McpServerConfig {
+  /** Human-readable name for this server */
+  name: string;
+
+  /** Command to run the server (e.g., "npx", "python") */
+  command: string;
+
+  /** Arguments to pass to the command */
+  args?: string[];
+
+  /** Environment variables for the server process */
+  env?: Record<string, string>;
+
+  /** Working directory for the server */
+  cwd?: string;
+
+  /** Whether this server is enabled (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * A tool discovered from an MCP server.
+ */
+export interface McpTool {
+  /** Tool name (namespaced: "server_name.tool_name") */
+  name: string;
+
+  /** Human-readable description */
+  description: string;
+
+  /** JSON Schema for the tool's input parameters */
+  inputSchema: Record<string, unknown>;
+
+  /** Which MCP server provides this tool */
+  serverName: string;
+}
+
+/**
+ * Internal state for a connected MCP server.
+ */
+interface McpConnection {
+  config: McpServerConfig;
+  process: ChildProcess;
+  tools: McpTool[];
+  requestId: number;
+  pendingRequests: Map<number, {
+    resolve: (value: unknown) => void;
+    reject: (reason: Error) => void;
+  }>;
+  buffer: string;
+}
+
+export class McpManager {
+  /** Active server connections */
+  private connections = new Map<string, McpConnection>();
+
+  /** Working directory for resolving config paths */
+  private workingDir: string;
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  /**
+   * Load MCP server configurations from config files.
+   *
+   * Checks these locations (in order):
+   *   1. .cdoing/mcp.json (project-specific)
+   *   2. ~/.cdoing/mcp.json (global)
+   *
+   * Learning note: Project configs take precedence over global ones.
+   * This lets you have project-specific MCP servers (e.g., a Jira
+   * server for one project, a Notion server for another).
+   */
+  loadConfig(): McpServerConfig[] {
+    const configs: McpServerConfig[] = [];
+    const paths = [
+      path.join(this.workingDir, ".cdoing", "mcp.json"),
+      path.join(os.homedir(), ".cdoing", "mcp.json"),
+    ];
+
+    for (const configPath of paths) {
+      try {
+        if (fs.existsSync(configPath)) {
+          const raw = fs.readFileSync(configPath, "utf-8");
+          const parsed = JSON.parse(raw);
+
+          if (parsed.servers && Array.isArray(parsed.servers)) {
+            for (const server of parsed.servers) {
+              // Don't add duplicates (project config overrides global)
+              if (!configs.some((c) => c.name === server.name)) {
+                configs.push(server);
+              }
+            }
+          }
+        }
+      } catch {
+        // Skip invalid config files
+      }
+    }
+
+    return configs;
+  }
+
+  /**
+   * Connect to all configured MCP servers.
+   * Spawns each server process and discovers its tools.
+   */
+  async connectAll(): Promise<void> {
+    const configs = this.loadConfig();
+
+    for (const config of configs) {
+      if (config.enabled === false) continue;
+
+      try {
+        await this.connect(config);
+      } catch (err) {
+        console.error(`[MCP] Failed to connect to ${config.name}:`, err);
+      }
+    }
+  }
+
+  /**
+   * Connect to a single MCP server.
+   *
+   * Learning note: We spawn the server as a child process and
+   * communicate via JSON-RPC over stdio. The "initialize" handshake
+   * tells the server our capabilities, and "tools/list" discovers
+   * what tools it offers.
+   */
+  async connect(config: McpServerConfig): Promise<void> {
+    // Spawn the server process
+    const child = spawn(config.command, config.args || [], {
+      cwd: config.cwd || this.workingDir,
+      env: { ...process.env, ...config.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    const connection: McpConnection = {
+      config,
+      process: child,
+      tools: [],
+      requestId: 0,
+      pendingRequests: new Map(),
+      buffer: "",
+    };
+
+    // Handle incoming messages from the server
+    child.stdout?.on("data", (data: Buffer) => {
+      connection.buffer += data.toString();
+
+      // Process complete JSON-RPC messages (delimited by newlines)
+      let newlineIndex: number;
+      while ((newlineIndex = connection.buffer.indexOf("\n")) >= 0) {
+        const line = connection.buffer.substring(0, newlineIndex).trim();
+        connection.buffer = connection.buffer.substring(newlineIndex + 1);
+
+        if (!line) continue;
+
+        try {
+          const message = JSON.parse(line);
+          this.handleServerMessage(config.name, message, connection);
+        } catch {
+          // Skip non-JSON lines (e.g., server startup logs)
+        }
+      }
+    });
+
+    // Handle server errors
+    child.stderr?.on("data", (data: Buffer) => {
+      // Log but don't crash — server stderr is often debug output
+      const text = data.toString().trim();
+      if (text) {
+        console.error(`[MCP:${config.name}] ${text}`);
+      }
+    });
+
+    child.on("exit", (code) => {
+      this.connections.delete(config.name);
+    });
+
+    this.connections.set(config.name, connection);
+
+    // Perform MCP handshake
+    try {
+      await this.sendRequest(config.name, "initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "cdoing-agent", version: "0.1.0" },
+      });
+
+      // Discover tools
+      const toolsResult = await this.sendRequest(config.name, "tools/list", {}) as any;
+      if (toolsResult?.tools) {
+        connection.tools = toolsResult.tools.map((t: any) => ({
+          name: `${config.name}_${t.name}`,
+          description: `[${config.name}] ${t.description || t.name}`,
+          inputSchema: t.inputSchema || { type: "object", properties: {} },
+          serverName: config.name,
+        }));
+      }
+    } catch (err) {
+      // If handshake fails, clean up
+      child.kill();
+      this.connections.delete(config.name);
+      throw err;
+    }
+  }
+
+  /**
+   * Send a JSON-RPC request to an MCP server.
+   *
+   * Learning note: JSON-RPC uses numeric IDs to match requests
+   * with responses. We store pending requests in a Map and resolve
+   * the Promise when we get the matching response.
+   */
+  private sendRequest(serverName: string, method: string, params: unknown): Promise<unknown> {
+    const connection = this.connections.get(serverName);
+    if (!connection) {
+      return Promise.reject(new Error(`MCP server not connected: ${serverName}`));
+    }
+
+    return new Promise((resolve, reject) => {
+      const id = ++connection.requestId;
+      connection.pendingRequests.set(id, { resolve, reject });
+
+      const message = JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        method,
+        params,
+      });
+
+      connection.process.stdin?.write(message + "\n");
+
+      // Timeout after 30 seconds
+      setTimeout(() => {
+        const pending = connection.pendingRequests.get(id);
+        if (pending) {
+          connection.pendingRequests.delete(id);
+          pending.reject(new Error(`MCP request timeout: ${method}`));
+        }
+      }, 30000);
+    });
+  }
+
+  /**
+   * Handle an incoming message from an MCP server.
+   */
+  private handleServerMessage(
+    serverName: string,
+    message: any,
+    connection: McpConnection,
+  ): void {
+    // JSON-RPC response (has an "id" field)
+    if (message.id !== undefined) {
+      const pending = connection.pendingRequests.get(message.id);
+      if (pending) {
+        connection.pendingRequests.delete(message.id);
+        if (message.error) {
+          pending.reject(new Error(message.error.message || "MCP error"));
+        } else {
+          pending.resolve(message.result);
+        }
+      }
+    }
+    // JSON-RPC notification (no "id" field) — log but ignore
+  }
+
+  /**
+   * Get all tools from all connected MCP servers.
+   */
+  getAllTools(): McpTool[] {
+    const tools: McpTool[] = [];
+    for (const connection of this.connections.values()) {
+      tools.push(...connection.tools);
+    }
+    return tools;
+  }
+
+  /**
+   * Call a tool on an MCP server.
+   *
+   * @param toolName - Namespaced tool name (e.g., "jira_create_issue")
+   * @param input - Tool input parameters
+   * @returns Tool execution result
+   */
+  async callTool(toolName: string, input: Record<string, unknown>): Promise<{
+    success: boolean;
+    output: string;
+    error?: string;
+  }> {
+    // Find which server provides this tool
+    for (const connection of this.connections.values()) {
+      const tool = connection.tools.find((t) => t.name === toolName);
+      if (tool) {
+        // Strip the server name prefix to get the original tool name
+        const originalName = toolName.replace(`${tool.serverName}_`, "");
+
+        try {
+          const result = await this.sendRequest(tool.serverName, "tools/call", {
+            name: originalName,
+            arguments: input,
+          }) as any;
+
+          // MCP tool results have a "content" array
+          const output = result?.content
+            ?.map((c: any) => c.text || JSON.stringify(c))
+            .join("\n") || JSON.stringify(result);
+
+          return { success: true, output };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return { success: false, output: "", error: message };
+        }
+      }
+    }
+
+    return { success: false, output: "", error: `Unknown MCP tool: ${toolName}` };
+  }
+
+  /**
+   * Check if a tool name belongs to an MCP server.
+   */
+  isMcpTool(toolName: string): boolean {
+    for (const connection of this.connections.values()) {
+      if (connection.tools.some((t) => t.name === toolName)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get connected server names.
+   */
+  getConnectedServers(): string[] {
+    return Array.from(this.connections.keys());
+  }
+
+  /**
+   * Disconnect from all MCP servers.
+   * Sends a graceful shutdown signal to each server process.
+   */
+  async disconnectAll(): Promise<void> {
+    for (const [name, connection] of this.connections) {
+      try {
+        connection.process.kill("SIGTERM");
+      } catch {
+        // Process may already be dead
+      }
+    }
+    this.connections.clear();
+  }
+
+  /**
+   * Update the working directory.
+   */
+  setWorkingDir(dir: string): void {
+    this.workingDir = dir;
+  }
+}