@build-astron-co/nimbus 0.2.0

package/src/lsp/manager.ts

@@ -0,0 +1,278 @@
+/**
+ * LSP Manager -- Language Server Lifecycle
+ *
+ * Manages starting, stopping, and querying multiple language servers.
+ * Lazy loading: servers only start when a file of that type is first edited.
+ * Auto-stop: servers shut down after 5 minutes of inactivity.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { LSPClient, type Diagnostic } from './client';
+import { getLanguageForFile, LANGUAGE_CONFIGS, type LanguageConfig } from './languages';
+
+const execAsync = promisify(exec);
+
+/** Default idle timeout: 5 minutes. */
+const DEFAULT_IDLE_TIMEOUT = 5 * 60 * 1000;
+
+/** Delay after file change before requesting diagnostics. */
+const DIAGNOSTIC_DELAY = 500;
+
+export interface LSPStatus {
+  language: string;
+  active: boolean;
+  available: boolean;
+}
+
+export class LSPManager {
+  private clients = new Map<string, LSPClient>();
+  private idleTimers = new Map<string, Timer>();
+  private rootUri: string;
+  private availabilityCache = new Map<string, boolean>();
+  private fileVersions = new Map<string, number>();
+  private enabled: boolean = true;
+
+  constructor(rootUri?: string) {
+    this.rootUri = rootUri ?? process.cwd();
+  }
+
+  /** Enable or disable LSP integration. */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+    if (!enabled) {
+      this.stopAll();
+    }
+  }
+
+  /**
+   * Notify the LSP manager that a file was modified.
+   * This lazily starts the appropriate language server and sends the update.
+   */
+  async touchFile(filePath: string): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    const config = getLanguageForFile(filePath);
+    if (!config) {
+      return;
+    }
+
+    // Ensure the client is running
+    const client = await this.ensureClient(config);
+    if (!client) {
+      return;
+    }
+
+    // Read file content and bump version
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch {
+      return;
+    }
+
+    const version = (this.fileVersions.get(filePath) ?? 0) + 1;
+    this.fileVersions.set(filePath, version);
+
+    await client.touchFile(filePath, content, version);
+    this.resetIdleTimer(config.id);
+  }
+
+  /**
+   * Get diagnostics for a file.
+   * Waits up to `delayMs` for the LSP to process and return results.
+   */
+  async getDiagnostics(
+    filePath: string,
+    delayMs: number = DIAGNOSTIC_DELAY
+  ): Promise<Diagnostic[]> {
+    if (!this.enabled) {
+      return [];
+    }
+
+    const config = getLanguageForFile(filePath);
+    if (!config) {
+      return [];
+    }
+
+    const client = this.clients.get(config.id);
+    if (!client?.isInitialized) {
+      return [];
+    }
+
+    // Wait a brief moment for the LSP to process
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+
+    return client.getDiagnostics(filePath);
+  }
+
+  /**
+   * Get errors only (severity 1 = Error).
+   */
+  async getErrors(filePath: string): Promise<Diagnostic[]> {
+    const diagnostics = await this.getDiagnostics(filePath);
+    return diagnostics.filter(d => d.severity === 1);
+  }
+
+  /**
+   * Format diagnostics as messages suitable for injection into the agent conversation.
+   */
+  formatDiagnosticsForAgent(diagnostics: Diagnostic[]): string | null {
+    if (diagnostics.length === 0) {
+      return null;
+    }
+
+    const errors = diagnostics.filter(d => d.severity === 1);
+    const warnings = diagnostics.filter(d => d.severity === 2);
+
+    if (errors.length === 0 && warnings.length === 0) {
+      return null;
+    }
+
+    const lines: string[] = ['[LSP Diagnostics]'];
+    for (const d of errors) {
+      const loc = `${d.file}:${d.line}:${d.column}`;
+      lines.push(`  Error: ${loc} — ${d.message}${d.source ? ` (${d.source})` : ''}`);
+    }
+    for (const d of warnings.slice(0, 5)) {
+      const loc = `${d.file}:${d.line}:${d.column}`;
+      lines.push(`  Warning: ${loc} — ${d.message}${d.source ? ` (${d.source})` : ''}`);
+    }
+
+    if (warnings.length > 5) {
+      lines.push(`  ... and ${warnings.length - 5} more warnings`);
+    }
+
+    return lines.join('\n');
+  }
+
+  /** Get status of all known language servers. */
+  async getStatus(): Promise<LSPStatus[]> {
+    const statuses: LSPStatus[] = [];
+    for (const config of LANGUAGE_CONFIGS) {
+      const client = this.clients.get(config.id);
+      const available = await this.isAvailable(config);
+      statuses.push({
+        language: config.name,
+        active: client?.isInitialized ?? false,
+        available,
+      });
+    }
+    return statuses;
+  }
+
+  /** Stop all running language servers. */
+  async stopAll(): Promise<void> {
+    for (const [id, client] of this.clients) {
+      await client.stop();
+      const timer = this.idleTimers.get(id);
+      if (timer) {
+        clearTimeout(timer);
+      }
+    }
+    this.clients.clear();
+    this.idleTimers.clear();
+  }
+
+  /** Stop a specific language server. */
+  async stop(languageId: string): Promise<void> {
+    const client = this.clients.get(languageId);
+    if (client) {
+      await client.stop();
+      this.clients.delete(languageId);
+    }
+    const timer = this.idleTimers.get(languageId);
+    if (timer) {
+      clearTimeout(timer);
+      this.idleTimers.delete(languageId);
+    }
+  }
+
+  /** Ensure a client exists and is initialized for the given language. */
+  private async ensureClient(config: LanguageConfig): Promise<LSPClient | null> {
+    const existing = this.clients.get(config.id);
+    if (existing?.isInitialized) {
+      return existing;
+    }
+
+    // Check if the binary is available
+    const available = await this.isAvailable(config);
+    if (!available) {
+      return null;
+    }
+
+    const client = new LSPClient(config, this.rootUri);
+    const started = await client.start();
+    if (!started) {
+      return null;
+    }
+
+    this.clients.set(config.id, client);
+    this.resetIdleTimer(config.id);
+
+    client.on('exit', () => {
+      this.clients.delete(config.id);
+      const timer = this.idleTimers.get(config.id);
+      if (timer) {
+        clearTimeout(timer);
+        this.idleTimers.delete(config.id);
+      }
+    });
+
+    return client;
+  }
+
+  /** Check if a language server binary is available in PATH. */
+  private async isAvailable(config: LanguageConfig): Promise<boolean> {
+    const cached = this.availabilityCache.get(config.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    try {
+      await execAsync(`which ${config.command}`);
+      this.availabilityCache.set(config.id, true);
+      return true;
+    } catch {
+      this.availabilityCache.set(config.id, false);
+      return false;
+    }
+  }
+
+  /** Reset the idle timer for a language server. */
+  private resetIdleTimer(languageId: string): void {
+    const existing = this.idleTimers.get(languageId);
+    if (existing) {
+      clearTimeout(existing);
+    }
+
+    const config = LANGUAGE_CONFIGS.find(c => c.id === languageId);
+    const timeout = config?.idleTimeout ?? DEFAULT_IDLE_TIMEOUT;
+
+    const timer = setTimeout(() => {
+      this.stop(languageId);
+    }, timeout);
+
+    this.idleTimers.set(languageId, timer);
+  }
+}
+
+/** Singleton LSP manager instance. */
+let lspManagerInstance: LSPManager | null = null;
+
+/** Get or create the singleton LSP manager. */
+export function getLSPManager(rootUri?: string): LSPManager {
+  if (!lspManagerInstance) {
+    lspManagerInstance = new LSPManager(rootUri);
+  }
+  return lspManagerInstance;
+}
+
+/** Reset the singleton (for testing). */
+export function resetLSPManager(): void {
+  lspManagerInstance?.stopAll();
+  lspManagerInstance = null;
+}

package/src/mcp/client.ts

@@ -0,0 +1,402 @@
+/**
+ * MCP Client
+ *
+ * Connects to Model Context Protocol servers (local command-based or
+ * remote HTTP-based) and dynamically registers their tools into
+ * the Nimbus tool registry.
+ *
+ * MCP specification: https://modelcontextprotocol.io/
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { ToolDefinition, ToolResult } from '../tools/schemas/types';
+import { z } from 'zod';
+
+/** MCP server configuration */
+export interface MCPServerConfig {
+  /** Unique server identifier */
+  name: string;
+  /** Server type */
+  type: 'command' | 'http';
+  /** For command servers: the command to spawn */
+  command?: string;
+  /** For command servers: command arguments */
+  args?: string[];
+  /** For command servers: environment variables */
+  env?: Record<string, string>;
+  /** For HTTP servers: the base URL */
+  url?: string;
+  /** For HTTP servers: authentication token */
+  token?: string;
+  /** Whether to connect lazily (only when a tool is used) */
+  lazy?: boolean;
+}
+
+/** MCP tool definition from server */
+interface MCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: JSONSchemaProperty;
+}
+
+/** MCP JSON-RPC message */
+interface JSONRPCMessage {
+  jsonrpc: '2.0';
+  id?: number | string;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/** Shape of MCP content blocks returned by tools/call */
+interface MCPContentBlock {
+  type: string;
+  text?: string;
+}
+
+/** Shape of MCP tools/call result */
+interface MCPCallResult {
+  content?: MCPContentBlock[];
+  isError?: boolean;
+}
+
+/**
+ * MCP Client that connects to a single MCP server.
+ */
+export class MCPClient {
+  readonly config: MCPServerConfig;
+  private process: ChildProcess | null = null;
+  private connected = false;
+  private requestId = 0;
+  private pendingRequests = new Map<
+    number,
+    {
+      resolve: (value: unknown) => void;
+      reject: (error: Error) => void;
+    }
+  >();
+  private buffer = '';
+  private tools: MCPToolDefinition[] = [];
+
+  constructor(config: MCPServerConfig) {
+    this.config = config;
+  }
+
+  /** Whether the client is connected to the server */
+  get isConnected(): boolean {
+    return this.connected;
+  }
+
+  /** The tools discovered from this server */
+  get discoveredTools(): readonly MCPToolDefinition[] {
+    return this.tools;
+  }
+
+  /**
+   * Connect to the MCP server.
+   * For command servers, spawns the process and initializes via JSON-RPC.
+   * For HTTP servers, sends a GET to check availability.
+   */
+  async connect(): Promise<void> {
+    if (this.connected) {
+      return;
+    }
+
+    if (this.config.type === 'command') {
+      await this.connectCommand();
+    } else {
+      await this.connectHttp();
+    }
+
+    this.connected = true;
+  }
+
+  /**
+   * Discover tools from the connected server.
+   */
+  async listTools(): Promise<MCPToolDefinition[]> {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    if (this.config.type === 'command') {
+      const response = (await this.sendRequest('tools/list', {})) as {
+        tools?: MCPToolDefinition[];
+      };
+      this.tools = response.tools ?? [];
+    } else {
+      // HTTP server
+      const headers: Record<string, string> = {};
+      if (this.config.token) {
+        headers['Authorization'] = `Bearer ${this.config.token}`;
+      }
+      const response = await fetch(`${this.config.url}/tools/list`, { headers });
+      const data = (await response.json()) as { tools?: MCPToolDefinition[] };
+      this.tools = data.tools ?? [];
+    }
+
+    return this.tools;
+  }
+
+  /**
+   * Call a tool on the MCP server.
+   */
+  async callTool(name: string, input: unknown): Promise<ToolResult> {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    try {
+      let result: MCPCallResult;
+
+      if (this.config.type === 'command') {
+        result = (await this.sendRequest('tools/call', {
+          name,
+          arguments: input,
+        })) as MCPCallResult;
+      } else {
+        const headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+        };
+        if (this.config.token) {
+          headers['Authorization'] = `Bearer ${this.config.token}`;
+        }
+        const response = await fetch(`${this.config.url}/tools/call`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify({ name, arguments: input }),
+        });
+        result = (await response.json()) as MCPCallResult;
+      }
+
+      // MCP tool results have content array
+      const content = result.content ?? [];
+      const textParts = content
+        .filter(
+          (c): c is MCPContentBlock & { text: string } =>
+            c.type === 'text' && typeof c.text === 'string'
+        )
+        .map(c => c.text);
+
+      return {
+        output: textParts.join('\n') || JSON.stringify(result),
+        isError: result.isError ?? false,
+        error: result.isError ? textParts.join('\n') : undefined,
+      };
+    } catch (error: unknown) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return {
+        output: '',
+        error: `MCP tool call failed: ${msg}`,
+        isError: true,
+      };
+    }
+  }
+
+  /**
+   * Convert discovered MCP tools to Nimbus ToolDefinition format.
+   */
+  toToolDefinitions(): ToolDefinition[] {
+    return this.tools.map(mcpTool => ({
+      name: `mcp_${this.config.name}_${mcpTool.name}`,
+      description: `[MCP: ${this.config.name}] ${mcpTool.description}`,
+      inputSchema: jsonSchemaToZod(mcpTool.inputSchema),
+      execute: async (input: unknown) => this.callTool(mcpTool.name, input),
+      permissionTier: 'ask_once' as const,
+      category: 'mcp' as const,
+    }));
+  }
+
+  /**
+   * Disconnect from the server.
+   */
+  async disconnect(): Promise<void> {
+    if (this.process) {
+      this.process.kill();
+      this.process = null;
+    }
+    this.connected = false;
+    this.tools = [];
+    this.pendingRequests.clear();
+  }
+
+  // ---------------------------------------------------------------
+  // Internal: Command-based server
+  // ---------------------------------------------------------------
+
+  private async connectCommand(): Promise<void> {
+    if (!this.config.command) {
+      throw new Error(
+        `MCP server '${this.config.name}' has type 'command' but no command specified`
+      );
+    }
+
+    this.process = spawn(this.config.command, this.config.args ?? [], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...this.config.env },
+    });
+
+    // Handle stdout (JSON-RPC responses)
+    this.process.stdout?.on('data', (data: Buffer) => {
+      this.buffer += data.toString();
+      this.processBuffer();
+    });
+
+    this.process.on('exit', () => {
+      this.connected = false;
+    });
+
+    // Send initialize request
+    await this.sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'nimbus', version: '0.2.0' },
+    });
+
+    // Send initialized notification
+    this.sendNotification('notifications/initialized', {});
+  }
+
+  private async connectHttp(): Promise<void> {
+    if (!this.config.url) {
+      throw new Error(`MCP server '${this.config.name}' has type 'http' but no URL specified`);
+    }
+
+    // Ping the server
+    const headers: Record<string, string> = {};
+    if (this.config.token) {
+      headers['Authorization'] = `Bearer ${this.config.token}`;
+    }
+    const response = await fetch(this.config.url, { headers });
+
+    if (!response.ok) {
+      throw new Error(`MCP server '${this.config.name}' returned HTTP ${response.status}`);
+    }
+  }
+
+  private sendRequest(method: string, params: unknown): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const id = ++this.requestId;
+      this.pendingRequests.set(id, { resolve, reject });
+
+      const message: JSONRPCMessage = {
+        jsonrpc: '2.0',
+        id,
+        method,
+        params,
+      };
+
+      if (this.process?.stdin) {
+        this.process.stdin.write(`${JSON.stringify(message)}\n`);
+      } else {
+        reject(new Error('MCP server process stdin not available'));
+      }
+
+      // Timeout after 30 seconds
+      setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          reject(new Error(`MCP request timed out: ${method}`));
+        }
+      }, 30_000);
+    });
+  }
+
+  private sendNotification(method: string, params: unknown): void {
+    const message: JSONRPCMessage = {
+      jsonrpc: '2.0',
+      method,
+      params,
+    };
+
+    if (this.process?.stdin) {
+      this.process.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+  }
+
+  private processBuffer(): void {
+    const lines = this.buffer.split('\n');
+    this.buffer = lines.pop() ?? '';
+
+    for (const line of lines) {
+      if (!line.trim()) {
+        continue;
+      }
+      try {
+        const message = JSON.parse(line) as JSONRPCMessage;
+        if (message.id !== undefined && this.pendingRequests.has(message.id as number)) {
+          const pending = this.pendingRequests.get(message.id as number)!;
+          this.pendingRequests.delete(message.id as number);
+          if (message.error) {
+            pending.reject(new Error(message.error.message));
+          } else {
+            pending.resolve(message.result);
+          }
+        }
+      } catch {
+        // Skip non-JSON lines
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------
+// JSON Schema -> Zod conversion
+// ---------------------------------------------------------------
+
+/** Minimal representation of a JSON Schema property used during conversion */
+interface JSONSchemaProperty {
+  type?: string;
+  description?: string;
+  enum?: [string, ...string[]];
+  items?: JSONSchemaProperty;
+  properties?: Record<string, JSONSchemaProperty>;
+  required?: string[];
+}
+
+/**
+ * Convert a JSON Schema object to a Zod schema.
+ * Handles basic types used in MCP tool definitions.
+ */
+function jsonSchemaToZod(schema: JSONSchemaProperty | undefined): z.ZodType<unknown> {
+  if (!schema || schema.type !== 'object') {
+    return z.object({});
+  }
+
+  const shape: Record<string, z.ZodType<unknown>> = {};
+  const required = new Set(schema.required ?? []);
+
+  for (const [key, prop] of Object.entries(schema.properties ?? {})) {
+    let fieldSchema: z.ZodType<unknown>;
+
+    switch (prop.type) {
+      case 'string':
+        fieldSchema = prop.enum ? z.enum(prop.enum) : z.string();
+        break;
+      case 'number':
+      case 'integer':
+        fieldSchema = z.number();
+        break;
+      case 'boolean':
+        fieldSchema = z.boolean();
+        break;
+      case 'array':
+        fieldSchema = z.array(prop.items ? jsonSchemaToZod(prop.items) : z.unknown());
+        break;
+      case 'object':
+        fieldSchema = jsonSchemaToZod(prop);
+        break;
+      default:
+        fieldSchema = z.unknown();
+    }
+
+    if (prop.description) {
+      fieldSchema = fieldSchema.describe(prop.description);
+    }
+
+    shape[key] = required.has(key) ? fieldSchema : fieldSchema.optional();
+  }
+
+  return z.object(shape);
+}

package/src/mcp/index.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP (Model Context Protocol) -- Barrel re-exports
+ */
+export { MCPClient, type MCPServerConfig } from './client';
+export { MCPManager, type MCPConfig } from './manager';