@soleri/core 2.9.0 → 2.11.0

package/src/transport/lsp-server.ts

@@ -0,0 +1,401 @@
+/**
+ * LSP Server — Language Server Protocol transport for editor-native agent integration.
+ *
+ * Speaks JSON-RPC 2.0 over stdio using the LSP wire format:
+ *   Content-Length: <N>\r\n\r\n<JSON payload>
+ *
+ * Maps agent capabilities to LSP features:
+ *   - Completions → vault search suggestions
+ *   - Diagnostics → quality gate violations
+ *   - Hover → pattern documentation
+ *   - Code actions → agent ops
+ *
+ * Uses only node:readline + node:process (zero deps).
+ */
+
+import type { LspTransportConfig, LspCapabilities } from './types.js';
+
+// =============================================================================
+// LSP TYPES (subset of the spec needed for transport)
+// =============================================================================
+
+/** JSON-RPC 2.0 request */
+export interface LspRequest {
+  jsonrpc: '2.0';
+  id: number | string;
+  method: string;
+  params?: unknown;
+}
+
+/** JSON-RPC 2.0 notification (no id) */
+export interface LspNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: unknown;
+}
+
+/** JSON-RPC 2.0 response */
+export interface LspResponse {
+  jsonrpc: '2.0';
+  id: number | string | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/** LSP Position */
+export interface LspPosition {
+  line: number;
+  character: number;
+}
+
+/** LSP Range */
+export interface LspRange {
+  start: LspPosition;
+  end: LspPosition;
+}
+
+/** LSP Diagnostic */
+export interface LspDiagnostic {
+  range: LspRange;
+  severity?: number; // 1=Error, 2=Warning, 3=Info, 4=Hint
+  source?: string;
+  message: string;
+  code?: string | number;
+}
+
+/** LSP Completion Item */
+export interface LspCompletionItem {
+  label: string;
+  kind?: number; // 1=Text, 6=Variable, 15=Snippet, etc.
+  detail?: string;
+  documentation?: string | { kind: 'markdown' | 'plaintext'; value: string };
+  insertText?: string;
+}
+
+/** LSP Hover */
+export interface LspHover {
+  contents: string | { kind: 'markdown' | 'plaintext'; value: string };
+  range?: LspRange;
+}
+
+/** LSP Code Action */
+export interface LspCodeAction {
+  title: string;
+  kind?: string; // e.g. 'quickfix', 'refactor', 'source'
+  diagnostics?: LspDiagnostic[];
+  command?: { title: string; command: string; arguments?: unknown[] };
+}
+
+// =============================================================================
+// CALLBACKS
+// =============================================================================
+
+export interface LspServerCallbacks {
+  /** Return completions for the given document URI and position. */
+  onCompletion?: (uri: string, position: LspPosition) => Promise<LspCompletionItem[]>;
+  /** Return hover info for the given document URI and position. */
+  onHover?: (uri: string, position: LspPosition) => Promise<LspHover | null>;
+  /** Return diagnostics for the given document URI and content. */
+  onDiagnostics?: (uri: string, content: string) => Promise<LspDiagnostic[]>;
+  /** Return code actions for the given document URI, range, and current diagnostics. */
+  onCodeAction?: (
+    uri: string,
+    range: LspRange,
+    diagnostics: LspDiagnostic[],
+  ) => Promise<LspCodeAction[]>;
+  /** Called when the server is initialized. Return additional server info if desired. */
+  onInitialize?: () => Promise<{ name?: string; version?: string }>;
+  /** Called when a document is opened or changed. */
+  onDocumentChange?: (uri: string, content: string) => Promise<void>;
+  /** Called on shutdown. */
+  onShutdown?: () => Promise<void>;
+}
+
+// =============================================================================
+// LSP SERVER
+// =============================================================================
+
+export class LspServer {
+  private config: LspTransportConfig;
+  private callbacks: LspServerCallbacks;
+  private capabilities: Required<LspCapabilities>;
+  private input: NodeJS.ReadableStream;
+  private output: NodeJS.WritableStream;
+  private running = false;
+  private buffer = '';
+  private contentLength = -1;
+  private initialized = false;
+
+  constructor(
+    config: LspTransportConfig,
+    callbacks: LspServerCallbacks,
+    input?: NodeJS.ReadableStream,
+    output?: NodeJS.WritableStream,
+  ) {
+    this.config = config;
+    this.callbacks = callbacks;
+    this.capabilities = {
+      completions: config.capabilities?.completions ?? true,
+      diagnostics: config.capabilities?.diagnostics ?? true,
+      hover: config.capabilities?.hover ?? true,
+      codeActions: config.capabilities?.codeActions ?? false,
+    };
+    this.input = input ?? process.stdin;
+    this.output = output ?? process.stdout;
+  }
+
+  /** Start listening for LSP messages on stdio. */
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.input.setEncoding('utf-8');
+    this.input.on('data', (chunk: string) => this.onData(chunk));
+    this.input.on('end', () => {
+      this.running = false;
+    });
+  }
+
+  /** Stop the server. */
+  async stop(): Promise<void> {
+    this.running = false;
+    this.input.removeAllListeners('data');
+    this.input.removeAllListeners('end');
+  }
+
+  /** Whether the server is currently running. */
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  /** Send a notification to the client (e.g., diagnostics). */
+  notify(method: string, params?: unknown): void {
+    this.writeMessage({ jsonrpc: '2.0', method, params });
+  }
+
+  /** Push diagnostics for a document. */
+  publishDiagnostics(uri: string, diagnostics: LspDiagnostic[]): void {
+    this.notify('textDocument/publishDiagnostics', { uri, diagnostics });
+  }
+
+  // ─── Message Parsing (LSP wire format) ─────────────────────────────
+
+  private onData(chunk: string): void {
+    this.buffer += chunk;
+    this.processBuffer();
+  }
+
+  private processBuffer(): void {
+    while (true) {
+      if (this.contentLength < 0) {
+        // Looking for headers
+        const headerEnd = this.buffer.indexOf('\r\n\r\n');
+        if (headerEnd < 0) return; // incomplete headers
+
+        const headers = this.buffer.substring(0, headerEnd);
+        const match = headers.match(/Content-Length:\s*(\d+)/i);
+        if (!match) {
+          // Skip malformed header
+          this.buffer = this.buffer.substring(headerEnd + 4);
+          continue;
+        }
+
+        this.contentLength = parseInt(match[1], 10);
+        this.buffer = this.buffer.substring(headerEnd + 4);
+      }
+
+      // Check if we have the full body
+      if (Buffer.byteLength(this.buffer, 'utf-8') < this.contentLength) return;
+
+      // Extract exactly contentLength bytes
+      const bodyBytes = Buffer.from(this.buffer, 'utf-8');
+      const body = bodyBytes.subarray(0, this.contentLength).toString('utf-8');
+      this.buffer = bodyBytes.subarray(this.contentLength).toString('utf-8');
+      this.contentLength = -1;
+
+      try {
+        const message = JSON.parse(body) as LspRequest | LspNotification;
+        this.handleMessage(message).catch(() => {
+          // Silently handle errors in message processing
+        });
+      } catch {
+        // Invalid JSON — skip
+      }
+    }
+  }
+
+  // ─── Message Handling ──────────────────────────────────────────────
+
+  private async handleMessage(message: LspRequest | LspNotification): Promise<void> {
+    const method = message.method;
+    const id = 'id' in message ? message.id : undefined;
+
+    switch (method) {
+      case 'initialize':
+        await this.handleInitialize(id as number | string);
+        break;
+      case 'initialized':
+        // Client acknowledgement — no response needed
+        break;
+      case 'shutdown':
+        await this.callbacks.onShutdown?.();
+        if (id !== undefined) {
+          this.respond(id as number | string, null);
+        }
+        break;
+      case 'exit':
+        this.running = false;
+        break;
+      case 'textDocument/completion':
+        await this.handleCompletion(id as number | string, message.params);
+        break;
+      case 'textDocument/hover':
+        await this.handleHover(id as number | string, message.params);
+        break;
+      case 'textDocument/codeAction':
+        await this.handleCodeAction(id as number | string, message.params);
+        break;
+      case 'textDocument/didOpen':
+      case 'textDocument/didChange':
+        await this.handleDocumentChange(message.params);
+        break;
+      case 'textDocument/didClose':
+        // No-op
+        break;
+      default:
+        // Unknown method — respond with MethodNotFound if it has an id
+        if (id !== undefined) {
+          this.respondError(id as number | string, -32601, `Method not found: ${method}`);
+        }
+        break;
+    }
+  }
+
+  private async handleInitialize(id: number | string): Promise<void> {
+    const info = await this.callbacks.onInitialize?.();
+
+    const serverCapabilities: Record<string, unknown> = {};
+
+    if (this.capabilities.completions) {
+      serverCapabilities.completionProvider = {
+        triggerCharacters: ['@', '/'],
+        resolveProvider: false,
+      };
+    }
+
+    if (this.capabilities.hover) {
+      serverCapabilities.hoverProvider = true;
+    }
+
+    if (this.capabilities.diagnostics) {
+      // Diagnostics are push-based via textDocument/publishDiagnostics
+      // We signal support via textDocumentSync
+    }
+
+    if (this.capabilities.codeActions) {
+      serverCapabilities.codeActionProvider = true;
+    }
+
+    // Always support text document sync (needed for diagnostics + change tracking)
+    serverCapabilities.textDocumentSync = {
+      openClose: true,
+      change: 1, // Full content on change
+    };
+
+    this.respond(id, {
+      capabilities: serverCapabilities,
+      serverInfo: {
+        name: info?.name ?? 'soleri-lsp',
+        version: info?.version ?? '0.1.0',
+      },
+    });
+
+    this.initialized = true;
+  }
+
+  private async handleCompletion(id: number | string, params: unknown): Promise<void> {
+    if (!this.capabilities.completions || !this.callbacks.onCompletion) {
+      this.respond(id, []);
+      return;
+    }
+
+    const p = params as {
+      textDocument: { uri: string };
+      position: LspPosition;
+    };
+
+    const items = await this.callbacks.onCompletion(p.textDocument.uri, p.position);
+    this.respond(id, items);
+  }
+
+  private async handleHover(id: number | string, params: unknown): Promise<void> {
+    if (!this.capabilities.hover || !this.callbacks.onHover) {
+      this.respond(id, null);
+      return;
+    }
+
+    const p = params as {
+      textDocument: { uri: string };
+      position: LspPosition;
+    };
+
+    const hover = await this.callbacks.onHover(p.textDocument.uri, p.position);
+    this.respond(id, hover);
+  }
+
+  private async handleCodeAction(id: number | string, params: unknown): Promise<void> {
+    if (!this.capabilities.codeActions || !this.callbacks.onCodeAction) {
+      this.respond(id, []);
+      return;
+    }
+
+    const p = params as {
+      textDocument: { uri: string };
+      range: LspRange;
+      context: { diagnostics: LspDiagnostic[] };
+    };
+
+    const actions = await this.callbacks.onCodeAction(
+      p.textDocument.uri,
+      p.range,
+      p.context.diagnostics,
+    );
+    this.respond(id, actions);
+  }
+
+  private async handleDocumentChange(params: unknown): Promise<void> {
+    const p = params as {
+      textDocument: { uri: string };
+      contentChanges?: Array<{ text: string }>;
+      // didOpen has text at top level via textDocument
+    };
+
+    const uri = p.textDocument.uri;
+    const content =
+      p.contentChanges?.[0]?.text ?? (p.textDocument as unknown as { text?: string }).text ?? '';
+
+    await this.callbacks.onDocumentChange?.(uri, content);
+
+    // If diagnostics are enabled, compute and push them
+    if (this.capabilities.diagnostics && this.callbacks.onDiagnostics && content) {
+      const diagnostics = await this.callbacks.onDiagnostics(uri, content);
+      this.publishDiagnostics(uri, diagnostics);
+    }
+  }
+
+  // ─── Response Helpers ──────────────────────────────────────────────
+
+  private respond(id: number | string, result: unknown): void {
+    this.writeMessage({ jsonrpc: '2.0', id, result });
+  }
+
+  private respondError(id: number | string, code: number, message: string): void {
+    this.writeMessage({ jsonrpc: '2.0', id, error: { code, message } });
+  }
+
+  private writeMessage(message: unknown): void {
+    const json = JSON.stringify(message);
+    const contentLength = Buffer.byteLength(json, 'utf-8');
+    const header = `Content-Length: ${contentLength}\r\n\r\n`;
+    this.output.write(header + json);
+  }
+}

package/src/transport/rate-limiter.ts

@@ -0,0 +1,97 @@
+/**
+ * Sliding Window Rate Limiter
+ *
+ * Per-key tracking (session ID or IP) with periodic self-cleanup.
+ * Returns Retry-After hint for 429 responses.
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface RateLimitResult {
+  /** Whether the request is allowed */
+  allowed: boolean;
+  /** Remaining requests in current window */
+  remaining: number;
+  /** Milliseconds until the client can retry (0 if allowed) */
+  retryAfterMs: number;
+}
+
+// =============================================================================
+// RATE LIMITER
+// =============================================================================
+
+export class RateLimiter {
+  private windows = new Map<string, number[]>();
+  private maxRequests: number;
+  private windowMs: number;
+  private cleanupCounter = 0;
+  private static readonly CLEANUP_INTERVAL = 100;
+
+  constructor(maxRequests = 100, windowMs = 60_000) {
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+  }
+
+  /** Check if a request from the given key is allowed. Records timestamp if allowed. */
+  check(key: string): RateLimitResult {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+
+    if (++this.cleanupCounter >= RateLimiter.CLEANUP_INTERVAL) {
+      this.cleanupCounter = 0;
+      this.cleanup(windowStart);
+    }
+
+    let timestamps = this.windows.get(key);
+    if (!timestamps) {
+      timestamps = [];
+      this.windows.set(key, timestamps);
+    }
+
+    // Remove expired timestamps
+    const filtered = timestamps.filter((t) => t > windowStart);
+    this.windows.set(key, filtered);
+
+    if (filtered.length >= this.maxRequests) {
+      const retryAfterMs = filtered[0] + this.windowMs - now;
+      return { allowed: false, remaining: 0, retryAfterMs: Math.max(retryAfterMs, 1) };
+    }
+
+    filtered.push(now);
+    return { allowed: true, remaining: this.maxRequests - filtered.length, retryAfterMs: 0 };
+  }
+
+  /** Reset rate limit state for a key. */
+  reset(key: string): void {
+    this.windows.delete(key);
+  }
+
+  /** Clear all rate limit state. */
+  clear(): void {
+    this.windows.clear();
+  }
+
+  /** Get current state for a key. */
+  getKeyState(key: string): { requestCount: number; remaining: number } {
+    const timestamps = this.windows.get(key);
+    const windowStart = Date.now() - this.windowMs;
+
+    if (!timestamps) return { requestCount: 0, remaining: this.maxRequests };
+
+    const active = timestamps.filter((t) => t > windowStart).length;
+    return { requestCount: active, remaining: Math.max(0, this.maxRequests - active) };
+  }
+
+  private cleanup(windowStart: number): void {
+    for (const [key, timestamps] of this.windows) {
+      const filtered = timestamps.filter((t) => t > windowStart);
+      if (filtered.length === 0) {
+        this.windows.delete(key);
+      } else {
+        this.windows.set(key, filtered);
+      }
+    }
+  }
+}

package/src/transport/session-manager.ts

@@ -0,0 +1,120 @@
+/**
+ * Session Manager — tracks HTTP transport sessions with TTL-based reaping.
+ *
+ * Each connected client gets a session entry. Sessions are reaped
+ * automatically after their TTL expires.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface Session {
+  id: string;
+  /** Opaque transport reference — the MCP SDK's StreamableHTTPServerTransport */
+  transport: unknown;
+  /** Opaque server reference — the MCP SDK's McpServer */
+  server: unknown;
+  createdAt: number;
+}
+
+export interface SessionManagerConfig {
+  /** Session TTL in ms. 0 to disable reaping. Default: 3600000 (1 hour). */
+  ttl?: number;
+  /** Reaper check interval in ms. Default: 60000 (1 minute). */
+  reaperInterval?: number;
+  /** Callback when a session is reaped. */
+  onReap?: (session: Session) => void;
+}
+
+// =============================================================================
+// SESSION MANAGER
+// =============================================================================
+
+const DEFAULT_TTL = 60 * 60 * 1000; // 1 hour
+const DEFAULT_REAPER_INTERVAL = 60 * 1000; // 1 minute
+
+export class SessionManager {
+  private sessions = new Map<string, Session>();
+  private reaperTimer: ReturnType<typeof setInterval> | undefined;
+  private config: SessionManagerConfig;
+
+  constructor(config: SessionManagerConfig = {}) {
+    this.config = config;
+  }
+
+  /** Generate a new session ID. */
+  generateId(): string {
+    return randomUUID();
+  }
+
+  /** Register a new session. */
+  add(id: string, transport: unknown, server: unknown): Session {
+    const session: Session = { id, transport, server, createdAt: Date.now() };
+    this.sessions.set(id, session);
+    return session;
+  }
+
+  /** Get a session by ID. */
+  get(id: string): Session | undefined {
+    return this.sessions.get(id);
+  }
+
+  /** Remove a session. */
+  remove(id: string): boolean {
+    return this.sessions.delete(id);
+  }
+
+  /** Number of active sessions. */
+  get size(): number {
+    return this.sessions.size;
+  }
+
+  /** List all session IDs. */
+  listIds(): string[] {
+    return Array.from(this.sessions.keys());
+  }
+
+  /** Start the periodic session reaper. */
+  startReaper(): void {
+    const ttl = this.config.ttl ?? DEFAULT_TTL;
+    if (ttl <= 0) return;
+
+    const interval = this.config.reaperInterval ?? DEFAULT_REAPER_INTERVAL;
+    this.reaperTimer = setInterval(() => {
+      this.reap(ttl);
+    }, interval);
+
+    // Don't prevent process exit
+    if (this.reaperTimer && typeof this.reaperTimer === 'object' && 'unref' in this.reaperTimer) {
+      (this.reaperTimer as NodeJS.Timeout).unref();
+    }
+  }
+
+  /** Stop the reaper. */
+  stopReaper(): void {
+    if (this.reaperTimer) {
+      clearInterval(this.reaperTimer);
+      this.reaperTimer = undefined;
+    }
+  }
+
+  /** Close all sessions and stop reaper. */
+  close(): void {
+    this.stopReaper();
+    this.sessions.clear();
+  }
+
+  /** Evict sessions older than TTL. */
+  private reap(ttlMs: number): void {
+    const now = Date.now();
+    for (const [id, session] of this.sessions) {
+      if (now - session.createdAt > ttlMs) {
+        this.sessions.delete(id);
+        this.config.onReap?.(session);
+      }
+    }
+  }
+}