@build-astron-co/nimbus 0.2.0

package/src/llm/types.ts

@@ -0,0 +1,232 @@
+/**
+ * Base LLM Provider Interface
+ * Defines the contract that all LLM providers must implement
+ */
+
+/** A text content block inside a multi-part message. */
+export interface TextContentBlock {
+  type: 'text';
+  text: string;
+}
+
+/** An image content block (base64-encoded). */
+export interface ImageContentBlock {
+  type: 'image';
+  source: {
+    type: 'base64';
+    media_type: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+    data: string;
+  };
+}
+
+/** A single content block inside a message. */
+export type ContentBlock = TextContentBlock | ImageContentBlock;
+
+export interface LLMMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  /** Plain string for text-only messages, or an array of content blocks for multimodal. */
+  content: string | ContentBlock[];
+  toolCalls?: ToolCall[];
+  toolCallId?: string;
+  name?: string;
+}
+
+export interface ToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string; // JSON string
+  };
+}
+
+export interface CompletionRequest {
+  messages: LLMMessage[];
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  stopSequences?: string[];
+  responseFormat?: { type: 'text' | 'json_object' };
+}
+
+export interface ToolCompletionRequest extends CompletionRequest {
+  tools: ToolDefinition[];
+  toolChoice?: 'auto' | 'none' | { type: 'function'; function: { name: string } };
+}
+
+export interface ToolDefinition {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+  };
+}
+
+export interface JSONSchema {
+  type: string;
+  properties?: Record<string, any>;
+  required?: string[];
+  [key: string]: any;
+}
+
+export interface LLMResponse {
+  content: string;
+  toolCalls?: ToolCall[];
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  model: string;
+  finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+  /** Per-request cost information (added by the router after provider responds) */
+  cost?: {
+    costUSD: number;
+    breakdown: {
+      input: number;
+      output: number;
+    };
+  };
+}
+
+export interface StreamChunk {
+  content?: string;
+  done: boolean;
+  toolCalls?: ToolCall[];
+  /** Emitted when a tool call block starts, before arguments are fully assembled.
+   *  Allows the TUI to show "preparing tool X..." feedback during streaming. */
+  toolCallStart?: { id: string; name: string };
+  /** Token usage info, typically sent with the final (done) chunk */
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+/**
+ * Extract the text content from a message's content field.
+ * Handles both plain strings and content block arrays.
+ */
+export function getTextContent(content: string | ContentBlock[]): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+  return content
+    .filter((b): b is TextContentBlock => b.type === 'text')
+    .map(b => b.text)
+    .join('');
+}
+
+/**
+ * Check if a message contains image content blocks.
+ */
+export function hasImageContent(content: string | ContentBlock[]): boolean {
+  if (typeof content === 'string') {
+    return false;
+  }
+  return content.some(b => b.type === 'image');
+}
+
+/**
+ * Base interface that all LLM providers must implement
+ */
+export interface LLMProvider {
+  /** Provider name (e.g., 'anthropic', 'openai', 'google', 'ollama') */
+  name: string;
+
+  /**
+   * Complete a chat request synchronously
+   */
+  complete(request: CompletionRequest): Promise<LLMResponse>;
+
+  /**
+   * Stream a chat completion
+   */
+  stream(request: CompletionRequest): AsyncIterable<StreamChunk>;
+
+  /**
+   * Complete a chat request with tool calling support
+   */
+  completeWithTools(request: ToolCompletionRequest): Promise<LLMResponse>;
+
+  /**
+   * Stream a chat completion with tool calling support.
+   * Text chunks are yielded incrementally; tool calls are accumulated
+   * and emitted on the final chunk.  Providers that don't implement native
+   * streaming-with-tools fall back to the non-streaming completeWithTools.
+   */
+  streamWithTools?(request: ToolCompletionRequest): AsyncIterable<StreamChunk>;
+
+  /**
+   * Count tokens in a text string
+   */
+  countTokens(text: string): Promise<number>;
+
+  /**
+   * Get maximum token limit for a model
+   */
+  getMaxTokens(model: string): number;
+
+  /**
+   * List available models for this provider
+   */
+  listModels(): Promise<string[]>;
+}
+
+/**
+ * Base provider class with common utilities
+ */
+export abstract class BaseProvider implements LLMProvider {
+  abstract name: string;
+  abstract complete(request: CompletionRequest): Promise<LLMResponse>;
+  abstract stream(request: CompletionRequest): AsyncIterable<StreamChunk>;
+  abstract completeWithTools(request: ToolCompletionRequest): Promise<LLMResponse>;
+  abstract countTokens(text: string): Promise<number>;
+  abstract getMaxTokens(model: string): number;
+  abstract listModels(): Promise<string[]>;
+
+  /**
+   * Extract system prompt from messages
+   */
+  protected extractSystemPrompt(messages: LLMMessage[]): string | undefined {
+    const systemMessages = messages.filter(m => m.role === 'system');
+    if (systemMessages.length === 0) {
+      return undefined;
+    }
+    return systemMessages.map(m => getTextContent(m.content)).join('\n\n');
+  }
+
+  /**
+   * Filter out system messages
+   */
+  protected filterSystemMessages(messages: LLMMessage[]): LLMMessage[] {
+    return messages.filter(m => m.role !== 'system');
+  }
+
+  /**
+   * Map finish reason to standard format
+   */
+  protected mapFinishReason(reason: string | null | undefined): LLMResponse['finishReason'] {
+    if (!reason) {
+      return 'stop';
+    }
+
+    const normalized = reason.toLowerCase();
+    if (normalized.includes('stop') || normalized === 'end_turn') {
+      return 'stop';
+    }
+    if (normalized.includes('length') || normalized.includes('max_tokens')) {
+      return 'length';
+    }
+    if (normalized.includes('tool') || normalized.includes('function')) {
+      return 'tool_calls';
+    }
+    if (normalized.includes('content_filter') || normalized.includes('safety')) {
+      return 'content_filter';
+    }
+
+    return 'stop';
+  }
+}

package/src/lsp/client.ts

@@ -0,0 +1,298 @@
+/**
+ * LSP Client -- JSON-RPC over stdio
+ *
+ * Implements the Language Server Protocol client that communicates
+ * with language servers via stdin/stdout using JSON-RPC 2.0.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import type { LanguageConfig } from './languages';
+
+/** LSP Diagnostic severity levels. */
+export type DiagnosticSeverity = 1 | 2 | 3 | 4; // Error, Warning, Info, Hint
+
+/** A single diagnostic from the language server. */
+export interface Diagnostic {
+  file: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+  severity: DiagnosticSeverity;
+  message: string;
+  source?: string;
+  code?: string | number;
+}
+
+/** Severity labels for display. */
+const SEVERITY_LABELS: Record<number, string> = {
+  1: 'Error',
+  2: 'Warning',
+  3: 'Info',
+  4: 'Hint',
+};
+
+export function severityLabel(severity: DiagnosticSeverity): string {
+  return SEVERITY_LABELS[severity] ?? 'Unknown';
+}
+
+/**
+ * LSP Client that communicates with a single language server.
+ */
+export class LSPClient extends EventEmitter {
+  private process: ChildProcess | null = null;
+  private config: LanguageConfig;
+  private requestId = 0;
+  private pending = new Map<
+    number,
+    { resolve: (value: any) => void; reject: (err: Error) => void }
+  >();
+  private buffer = '';
+  private initialized = false;
+  private rootUri: string;
+  private diagnostics = new Map<string, Diagnostic[]>();
+
+  constructor(config: LanguageConfig, rootUri: string) {
+    super();
+    this.config = config;
+    this.rootUri = rootUri;
+  }
+
+  /** Whether the client is connected and initialized. */
+  get isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /** Get the language ID. */
+  get languageId(): string {
+    return this.config.id;
+  }
+
+  /** Start the language server process. */
+  async start(): Promise<boolean> {
+    try {
+      this.process = spawn(this.config.command, this.config.args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+
+      if (!this.process.stdout || !this.process.stdin) {
+        this.process.kill();
+        this.process = null;
+        return false;
+      }
+
+      this.process.stdout.on('data', (data: Buffer) => {
+        this.handleData(data.toString());
+      });
+
+      this.process.stderr?.on('data', () => {
+        // Silently ignore stderr from language servers
+      });
+
+      this.process.on('exit', () => {
+        this.initialized = false;
+        this.process = null;
+        this.emit('exit');
+      });
+
+      // Send initialize request
+      const _initResult = await this.sendRequest('initialize', {
+        processId: process.pid,
+        rootUri: `file://${this.rootUri}`,
+        capabilities: {
+          textDocument: {
+            synchronization: { didOpen: true, didChange: true, didClose: true },
+            publishDiagnostics: { relatedInformation: true },
+          },
+        },
+        initializationOptions: this.config.initializationOptions ?? {},
+      });
+
+      // Send initialized notification
+      this.sendNotification('initialized', {});
+      this.initialized = true;
+      return true;
+    } catch {
+      this.process = null;
+      return false;
+    }
+  }
+
+  /** Stop the language server. */
+  async stop(): Promise<void> {
+    if (!this.process) {
+      return;
+    }
+
+    try {
+      await this.sendRequest('shutdown', null);
+      this.sendNotification('exit', null);
+    } catch {
+      // Server may already be dead
+    }
+
+    // Force kill after 2 seconds
+    const proc = this.process;
+    setTimeout(() => {
+      if (proc && !proc.killed) {
+        proc.kill('SIGKILL');
+      }
+    }, 2000);
+
+    this.process = null;
+    this.initialized = false;
+  }
+
+  /** Notify the server that a file was opened or changed. */
+  async touchFile(filePath: string, content: string, version: number = 1): Promise<void> {
+    if (!this.initialized) {
+      return;
+    }
+
+    const uri = `file://${filePath}`;
+    const languageId = this.config.id;
+
+    // Send didOpen (simplified -- in a full implementation we'd track open state)
+    this.sendNotification('textDocument/didOpen', {
+      textDocument: { uri, languageId, version, text: content },
+    });
+  }
+
+  /** Request diagnostics for a file by waiting for publishDiagnostics. */
+  async getDiagnostics(filePath: string, timeoutMs: number = 2000): Promise<Diagnostic[]> {
+    const uri = `file://${filePath}`;
+
+    // Return cached diagnostics if available
+    const cached = this.diagnostics.get(uri);
+
+    // Wait for new diagnostics up to timeout
+    return new Promise<Diagnostic[]>(resolve => {
+      const timer = setTimeout(() => {
+        resolve(cached ?? []);
+      }, timeoutMs);
+
+      const handler = (params: any) => {
+        if (params.uri === uri) {
+          clearTimeout(timer);
+          this.removeListener('diagnostics', handler);
+          resolve(this.diagnostics.get(uri) ?? []);
+        }
+      };
+
+      this.on('diagnostics', handler);
+    });
+  }
+
+  /** Get all cached diagnostics for a file. */
+  getCachedDiagnostics(filePath: string): Diagnostic[] {
+    return this.diagnostics.get(`file://${filePath}`) ?? [];
+  }
+
+  /** Send a JSON-RPC request and wait for response. */
+  private sendRequest(method: string, params: any): Promise<any> {
+    return new Promise((resolve, reject) => {
+      if (!this.process?.stdin) {
+        reject(new Error('LSP process not running'));
+        return;
+      }
+
+      const id = ++this.requestId;
+      this.pending.set(id, { resolve, reject });
+
+      const message = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+      const header = `Content-Length: ${Buffer.byteLength(message)}\r\n\r\n`;
+      this.process.stdin.write(header + message);
+
+      // Timeout after 10 seconds
+      setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id);
+          reject(new Error(`LSP request timeout: ${method}`));
+        }
+      }, 10000);
+    });
+  }
+
+  /** Send a JSON-RPC notification (no response expected). */
+  private sendNotification(method: string, params: any): void {
+    if (!this.process?.stdin) {
+      return;
+    }
+
+    const message = JSON.stringify({ jsonrpc: '2.0', method, params });
+    const header = `Content-Length: ${Buffer.byteLength(message)}\r\n\r\n`;
+    this.process.stdin.write(header + message);
+  }
+
+  /** Handle incoming data from the language server. */
+  private handleData(data: string): void {
+    this.buffer += data;
+
+    for (;;) {
+      const headerEnd = this.buffer.indexOf('\r\n\r\n');
+      if (headerEnd === -1) {
+        break;
+      }
+
+      const header = this.buffer.slice(0, headerEnd);
+      const contentLengthMatch = header.match(/Content-Length:\s*(\d+)/i);
+      if (!contentLengthMatch) {
+        this.buffer = this.buffer.slice(headerEnd + 4);
+        continue;
+      }
+
+      const contentLength = parseInt(contentLengthMatch[1], 10);
+      const bodyStart = headerEnd + 4;
+
+      if (this.buffer.length < bodyStart + contentLength) {
+        break;
+      }
+
+      const body = this.buffer.slice(bodyStart, bodyStart + contentLength);
+      this.buffer = this.buffer.slice(bodyStart + contentLength);
+
+      try {
+        const message = JSON.parse(body);
+        this.handleMessage(message);
+      } catch {
+        // Ignore malformed messages
+      }
+    }
+  }
+
+  /** Handle a parsed JSON-RPC message. */
+  private handleMessage(message: any): void {
+    // Response to a request
+    if (message.id !== undefined && this.pending.has(message.id)) {
+      const handler = this.pending.get(message.id)!;
+      this.pending.delete(message.id);
+
+      if (message.error) {
+        handler.reject(new Error(message.error.message));
+      } else {
+        handler.resolve(message.result);
+      }
+      return;
+    }
+
+    // Notification from server
+    if (message.method === 'textDocument/publishDiagnostics') {
+      const { uri, diagnostics: rawDiags } = message.params;
+      const parsed: Diagnostic[] = rawDiags.map((d: any) => ({
+        file: uri.replace('file://', ''),
+        line: (d.range?.start?.line ?? 0) + 1,
+        column: (d.range?.start?.character ?? 0) + 1,
+        endLine: d.range?.end ? d.range.end.line + 1 : undefined,
+        endColumn: d.range?.end ? d.range.end.character + 1 : undefined,
+        severity: d.severity ?? 1,
+        message: d.message,
+        source: d.source,
+        code: d.code,
+      }));
+      this.diagnostics.set(uri, parsed);
+      this.emit('diagnostics', message.params);
+    }
+  }
+}

package/src/lsp/languages.ts

@@ -0,0 +1,116 @@
+/**
+ * Language Server Configurations
+ *
+ * Defines the LSP binary names, install commands, and file associations
+ * for each supported language.
+ */
+
+export interface LanguageConfig {
+  /** Language identifier (e.g. 'typescript'). */
+  id: string;
+  /** Display name. */
+  name: string;
+  /** File extensions that trigger this language server. */
+  extensions: string[];
+  /** Command to start the LSP binary. */
+  command: string;
+  /** Arguments to pass to the LSP binary. */
+  args: string[];
+  /** Install command hint if binary not found. */
+  installHint: string;
+  /** Initialization options passed to the LSP server. */
+  initializationOptions?: Record<string, unknown>;
+  /** Idle timeout in ms before shutting down the server (default: 5 min). */
+  idleTimeout?: number;
+}
+
+/** Supported language server configurations. */
+export const LANGUAGE_CONFIGS: LanguageConfig[] = [
+  {
+    id: 'typescript',
+    name: 'TypeScript',
+    extensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+    command: 'typescript-language-server',
+    args: ['--stdio'],
+    installHint: 'npm install -g typescript-language-server typescript',
+    initializationOptions: {
+      preferences: {
+        includeInlayParameterNameHints: 'none',
+      },
+    },
+  },
+  {
+    id: 'go',
+    name: 'Go',
+    extensions: ['.go'],
+    command: 'gopls',
+    args: ['serve'],
+    installHint: 'go install golang.org/x/tools/gopls@latest',
+  },
+  {
+    id: 'python',
+    name: 'Python',
+    extensions: ['.py', '.pyi'],
+    command: 'pylsp',
+    args: [],
+    installHint: 'pip install python-lsp-server',
+  },
+  {
+    id: 'terraform',
+    name: 'Terraform/HCL',
+    extensions: ['.tf', '.tfvars', '.hcl'],
+    command: 'terraform-ls',
+    args: ['serve'],
+    installHint: 'brew install hashicorp/tap/terraform-ls',
+  },
+  {
+    id: 'yaml',
+    name: 'YAML',
+    extensions: ['.yaml', '.yml'],
+    command: 'yaml-language-server',
+    args: ['--stdio'],
+    installHint: 'npm install -g yaml-language-server',
+  },
+  {
+    id: 'docker',
+    name: 'Docker',
+    extensions: ['Dockerfile', '.dockerfile'],
+    command: 'docker-langserver',
+    args: ['--stdio'],
+    installHint: 'npm install -g dockerfile-language-server-nodejs',
+  },
+];
+
+/**
+ * Find the language config for a given file path.
+ * Returns undefined if no matching language server is configured.
+ */
+export function getLanguageForFile(filePath: string): LanguageConfig | undefined {
+  const lowerPath = filePath.toLowerCase();
+  const baseName = filePath.split('/').pop() ?? '';
+
+  for (const config of LANGUAGE_CONFIGS) {
+    for (const ext of config.extensions) {
+      if (ext.startsWith('.')) {
+        if (lowerPath.endsWith(ext)) {
+          return config;
+        }
+      } else {
+        // Match exact filename (e.g., Dockerfile)
+        if (baseName === ext || baseName.toLowerCase() === ext.toLowerCase()) {
+          return config;
+        }
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Get the priority order of language configs.
+ * TypeScript > Go > Python > HCL > YAML > Docker
+ */
+export function getLanguagePriority(): LanguageConfig[] {
+  return [...LANGUAGE_CONFIGS];
+}