@mrclrchtr/supi-lsp 0.1.0

package/runtime-state.ts

@@ -0,0 +1,113 @@
+// Runtime LSP guidance state — tracks qualifying source interactions and
+// computes stateful pre-turn guidance so runtime guidance stays dormant
+// until the session actually touches supported source files.
+
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import {
+  buildRuntimeLspGuidance,
+  computeTrackedDiagnosticsSummary,
+  type RuntimeGuidanceInput,
+} from "./guidance.ts";
+import type { LspManager } from "./manager.ts";
+import { getRawFilePathFromToolEvent } from "./recent-paths.ts";
+import { displayRelativeFilePath } from "./summary.ts";
+
+export const MAX_TRACKED_SOURCE_PATHS = 8;
+
+export interface LspRuntimeGuidanceState {
+  runtimeActive: boolean;
+  trackedSourcePaths: string[];
+  pendingActivation: boolean;
+  lastInjectedFingerprint: string | null;
+}
+
+export function createRuntimeGuidanceState(): LspRuntimeGuidanceState {
+  return {
+    runtimeActive: false,
+    trackedSourcePaths: [],
+    pendingActivation: false,
+    lastInjectedFingerprint: null,
+  };
+}
+
+export function resetRuntimeGuidanceState(state: LspRuntimeGuidanceState): void {
+  state.runtimeActive = false;
+  state.trackedSourcePaths = [];
+  state.pendingActivation = false;
+  state.lastInjectedFingerprint = null;
+}
+
+export function registerQualifyingSourceInteraction(
+  state: LspRuntimeGuidanceState,
+  manager: LspManager,
+  toolName: string,
+  input: Record<string, unknown>,
+): void {
+  const rawPath = getRawFilePathFromToolEvent(toolName, input);
+  if (!rawPath) return;
+  if (!manager.isSupportedSourceFile(rawPath)) return;
+
+  // displayRelativeFilePath is the same form diagnostics get keyed under, so
+  // the tracked-files list lines up with diagnostic relevance matching for
+  // both in-tree files (relative form) and out-of-tree absolute paths.
+  const trackedPath = displayRelativeFilePath(rawPath);
+
+  // pendingActivation is a one-shot signal: set only on the first qualifying
+  // interaction so the next turn can inject the "LSP ready" hint exactly once.
+  // Subsequent interactions keep tracking files but must not re-arm activation
+  // — the caller clears the flag after injecting.
+  const wasDormant = !state.runtimeActive;
+  state.runtimeActive = true;
+
+  if (wasDormant) {
+    state.pendingActivation = true;
+  }
+
+  state.trackedSourcePaths = [
+    trackedPath,
+    ...state.trackedSourcePaths.filter((entry) => entry !== trackedPath),
+  ].slice(0, MAX_TRACKED_SOURCE_PATHS);
+}
+
+/**
+ * Drop tracked source paths whose underlying file is gone (deleted/renamed).
+ * Without this, `pruneMissingFiles()` cleans the live LSP clients but the
+ * runtime guidance would keep advertising the stale path on subsequent turns,
+ * and the session couldn't return to a dormant state until other interactions
+ * evicted the entry. Tracked paths are in `displayRelativeFilePath` form so
+ * `path.resolve` transparently handles both in-tree relative and out-of-tree
+ * absolute entries.
+ */
+export function pruneMissingTrackedPaths(state: LspRuntimeGuidanceState): void {
+  if (state.trackedSourcePaths.length === 0) return;
+  const surviving = state.trackedSourcePaths.filter((entry) => existsSync(path.resolve(entry)));
+  if (surviving.length === state.trackedSourcePaths.length) return;
+  state.trackedSourcePaths = surviving;
+  if (surviving.length === 0) {
+    state.runtimeActive = false;
+    state.pendingActivation = false;
+  }
+}
+
+export function computePendingRuntimeGuidance(
+  state: LspRuntimeGuidanceState,
+  manager: LspManager,
+  inlineSeverity: number,
+): { input: RuntimeGuidanceInput; content: string | null } | null {
+  if (!state.runtimeActive) return null;
+
+  const diagnosticsSummary = computeTrackedDiagnosticsSummary(
+    manager,
+    inlineSeverity,
+    state.trackedSourcePaths,
+  );
+
+  const input: RuntimeGuidanceInput = {
+    pendingActivation: state.pendingActivation,
+    diagnosticsSummary,
+    trackedFiles: state.trackedSourcePaths,
+  };
+
+  return { input, content: buildRuntimeLspGuidance(input) };
+}

package/summary.ts

@@ -0,0 +1,118 @@
+import * as path from "node:path";
+import type { ActiveCoverageSummaryEntry, OutstandingDiagnosticSummaryEntry } from "./manager.ts";
+
+/**
+ * Display form for a file path used both for human-readable LSP output and as
+ * the diagnostic key. In-tree paths return the project-relative form; out-of-
+ * tree paths preserve the absolute path so files in sibling worktrees or
+ * monorepo packages don't collapse to a basename — that collapse used to make
+ * unrelated files with the same name appear interchangeable in relevance
+ * matching, and it broke diagnostic correlation for tracked external paths.
+ */
+export function displayRelativeFilePath(filePath: string): string {
+  const absolutePath = path.resolve(filePath);
+  const relativePath = path.relative(process.cwd(), absolutePath);
+  if (relativePath === "") return path.basename(absolutePath);
+  if (relativePath.startsWith(`..${path.sep}`) || relativePath === "..") {
+    return absolutePath;
+  }
+  return relativePath;
+}
+
+export function formatCoverageSummaryText(
+  entries: ActiveCoverageSummaryEntry[],
+  maxServers: number,
+  maxFiles: number,
+): string | null {
+  if (entries.length === 0) return null;
+
+  const visible = entries.slice(0, maxServers);
+  const parts = visible.map(
+    (entry) => `${entry.name} (${formatOpenFiles(entry.openFiles, maxFiles)})`,
+  );
+  const remaining = entries.length - visible.length;
+  const suffix =
+    remaining > 0 ? `; +${remaining} more ${remaining === 1 ? "server" : "servers"}` : "";
+
+  return `Active LSP coverage: ${parts.join("; ")}${suffix}.`;
+}
+
+export function formatOutstandingDiagnosticsSummaryText(
+  entries: OutstandingDiagnosticSummaryEntry[],
+  maxFiles: number,
+): string | null {
+  if (entries.length === 0) return null;
+
+  const visible = entries.slice(0, maxFiles);
+  const parts = visible.map((entry) => `${entry.file} (${formatDiagnosticCounts(entry)})`);
+  const remaining = entries.length - visible.length;
+  const suffix = remaining > 0 ? `; +${remaining} more ${remaining === 1 ? "file" : "files"}` : "";
+
+  return `Outstanding LSP diagnostics: ${parts.join("; ")}${suffix}.`;
+}
+
+export function normalizeRelevantPaths(relevantPaths: string[]): string[] {
+  return Array.from(new Set(relevantPaths.map(normalizeRelevantPath).filter(Boolean)));
+}
+
+/**
+ * Match a file against caller-supplied relevance hints. Hints come from prompt
+ * tokens and recent tool paths, so they're heterogeneous: full relative paths,
+ * directory names, or bare filenames. Matching modes:
+ *  - exact path match
+ *  - candidate contains "/": treat as a directory prefix (`lsp/foo` ⊂ `lsp/foo/...`)
+ *  - candidate has no "/" and no ".": treat as a directory name anywhere in the path
+ *  - otherwise: treat as a filename and match the basename
+ */
+export function isPathRelevant(filePath: string, relevantPaths: string[]): boolean {
+  const normalizedFilePath = normalizeRelevantPath(filePath);
+  if (shouldIgnoreLspPath(normalizedFilePath)) return false;
+
+  return relevantPaths.some((candidate) => {
+    if (normalizedFilePath === candidate) return true;
+    if (candidate.includes("/")) return normalizedFilePath.startsWith(`${candidate}/`);
+    if (!candidate.includes(".")) {
+      return (
+        normalizedFilePath.startsWith(`${candidate}/`) ||
+        normalizedFilePath.includes(`/${candidate}/`)
+      );
+    }
+    return path.basename(normalizedFilePath) === candidate;
+  });
+}
+
+export function shouldIgnoreLspPath(filePath: string): boolean {
+  const normalized = normalizeRelevantPath(filePath);
+  return (
+    normalized === "node_modules" ||
+    normalized.startsWith("node_modules/") ||
+    normalized.includes("/node_modules/") ||
+    normalized === ".pnpm" ||
+    normalized.startsWith(".pnpm/") ||
+    normalized.includes("/.pnpm/")
+  );
+}
+
+function normalizeRelevantPath(filePath: string): string {
+  return filePath.replaceAll("\\", "/").replace(/\/$/, "").trim();
+}
+
+function formatOpenFiles(openFiles: string[], maxFiles: number): string {
+  const visible = openFiles.slice(0, maxFiles);
+  const remaining = openFiles.length - visible.length;
+  const suffix = remaining > 0 ? `, +${remaining} more` : "";
+  return `${pluralize(openFiles.length, "open file")}: ${visible.join(", ")}${suffix}`;
+}
+
+function formatDiagnosticCounts(entry: OutstandingDiagnosticSummaryEntry): string {
+  const counts: string[] = [];
+  if (entry.errors > 0) counts.push(pluralize(entry.errors, "error"));
+  if (entry.warnings > 0) counts.push(pluralize(entry.warnings, "warning"));
+  if (entry.information > 0) counts.push(pluralize(entry.information, "info"));
+  if (entry.hints > 0) counts.push(pluralize(entry.hints, "hint"));
+  return counts.join(", ");
+}
+
+function pluralize(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}

package/tool-actions.ts

@@ -0,0 +1,211 @@
+// LSP tool action implementations — dispatches agent tool calls to LSP clients.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatDiagnostics } from "./diagnostics.ts";
+import {
+  formatCodeActions,
+  formatDocumentSymbols,
+  formatHover,
+  formatLocations,
+  formatSymbolInformation,
+  formatWorkspaceEdit,
+  normalizeLocations,
+} from "./format.ts";
+import type { LspManager } from "./manager.ts";
+import type { DocumentSymbol, Range, SymbolInformation } from "./types.ts";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export type LspAction =
+  | "hover"
+  | "definition"
+  | "references"
+  | "diagnostics"
+  | "symbols"
+  | "rename"
+  | "code_actions";
+
+export interface LspToolParams {
+  action: LspAction;
+  file?: string;
+  line?: number;
+  character?: number;
+  newName?: string;
+}
+
+// ── Tool Description ──────────────────────────────────────────────────
+
+export const lspToolDescription = `Language Server Protocol tool — provides type-aware code intelligence.
+
+Actions:
+- hover: Get type info and docs at a position. Params: file, line, character
+- definition: Go to definition of a symbol. Params: file, line, character
+- references: Find all references to a symbol. Params: file, line, character
+- diagnostics: Get type errors and warnings. Params: file (optional — omit for all files)
+- symbols: List all symbols in a file. Params: file
+- rename: Rename a symbol across the project. Params: file, line, character, newName
+- code_actions: Get available fixes/refactors at a position. Params: file, line, character
+
+Line and character are 1-based. File paths are relative to cwd.`;
+
+// ── Action Dispatcher ─────────────────────────────────────────────────
+
+export async function executeAction(manager: LspManager, params: LspToolParams): Promise<string> {
+  switch (params.action) {
+    case "hover":
+      return handleHover(manager, params);
+    case "definition":
+      return handleDefinition(manager, params);
+    case "references":
+      return handleReferences(manager, params);
+    case "diagnostics":
+      return handleDiagnostics(manager, params);
+    case "symbols":
+      return handleSymbols(manager, params);
+    case "rename":
+      return handleRename(manager, params);
+    case "code_actions":
+      return handleCodeActions(manager, params);
+    default:
+      return `Unknown action: ${params.action}`;
+  }
+}
+
+// ── Action Handlers ───────────────────────────────────────────────────
+
+async function handleHover(manager: LspManager, params: LspToolParams): Promise<string> {
+  const { file, line, character } = requireFilePosition(params);
+  const client = await manager.ensureFileOpen(file);
+  if (!client) return noServerMessage(file);
+
+  const hover = await client.hover(path.resolve(file), toZeroBased(line, character));
+  if (!hover) return "No hover information available at this position.";
+  return formatHover(hover);
+}
+
+async function handleDefinition(manager: LspManager, params: LspToolParams): Promise<string> {
+  const { file, line, character } = requireFilePosition(params);
+  const client = await manager.ensureFileOpen(file);
+  if (!client) return noServerMessage(file);
+
+  const result = await client.definition(path.resolve(file), toZeroBased(line, character));
+  if (!result) return "No definition found.";
+
+  const locations = normalizeLocations(result);
+  if (locations.length === 0) return "No definition found.";
+
+  return formatLocations("Definition", locations);
+}
+
+async function handleReferences(manager: LspManager, params: LspToolParams): Promise<string> {
+  const { file, line, character } = requireFilePosition(params);
+  const client = await manager.ensureFileOpen(file);
+  if (!client) return noServerMessage(file);
+
+  const locations = await client.references(path.resolve(file), toZeroBased(line, character));
+  if (!locations || locations.length === 0) return "No references found.";
+
+  return formatLocations("References", locations);
+}
+
+async function handleDiagnostics(manager: LspManager, params: LspToolParams): Promise<string> {
+  if (params.file) {
+    const resolvedPath = path.resolve(params.file);
+    const client = await manager.ensureFileOpen(params.file);
+    if (!client) return noServerMessage(params.file);
+
+    let content: string;
+    try {
+      content = fs.readFileSync(resolvedPath, "utf-8");
+    } catch {
+      return `Error: cannot read file ${params.file}`;
+    }
+
+    const diags = await client.syncAndWaitForDiagnostics(resolvedPath, content);
+    return formatDiagnostics(params.file, diags);
+  }
+
+  const summary = manager.getDiagnosticSummary();
+  if (summary.length === 0) return "No diagnostics across any files.";
+
+  const lines = ["## Diagnostics Summary\n"];
+  for (const s of summary) {
+    lines.push(`- **${s.file}**: ${s.errors} error(s), ${s.warnings} warning(s)`);
+  }
+  return lines.join("\n");
+}
+
+async function handleSymbols(manager: LspManager, params: LspToolParams): Promise<string> {
+  if (!params.file) return "Error: 'file' parameter is required for symbols action.";
+
+  const client = await manager.ensureFileOpen(params.file);
+  if (!client) return noServerMessage(params.file);
+
+  const symbols = await client.documentSymbols(path.resolve(params.file));
+  if (!symbols || symbols.length === 0) return "No symbols found.";
+
+  if ("children" in symbols[0] || "selectionRange" in symbols[0]) {
+    return formatDocumentSymbols(symbols as DocumentSymbol[], 0);
+  }
+  return formatSymbolInformation(symbols as SymbolInformation[]);
+}
+
+async function handleRename(manager: LspManager, params: LspToolParams): Promise<string> {
+  const { file, line, character } = requireFilePosition(params);
+  if (!params.newName) return "Error: 'newName' parameter is required for rename action.";
+
+  const client = await manager.ensureFileOpen(file);
+  if (!client) return noServerMessage(file);
+
+  const edit = await client.rename(
+    path.resolve(file),
+    toZeroBased(line, character),
+    params.newName,
+  );
+  if (!edit) return "Rename not available at this position.";
+
+  return formatWorkspaceEdit(edit);
+}
+
+async function handleCodeActions(manager: LspManager, params: LspToolParams): Promise<string> {
+  const { file, line, character } = requireFilePosition(params);
+  const client = await manager.ensureFileOpen(file);
+  if (!client) return noServerMessage(file);
+
+  const pos = toZeroBased(line, character);
+  const range: Range = { start: pos, end: pos };
+  const diags = client.getDiagnostics(path.resolve(file));
+
+  const relevantDiags = diags.filter(
+    (d) => d.range.start.line <= pos.line && d.range.end.line >= pos.line,
+  );
+
+  const actions = await client.codeActions(path.resolve(file), range, {
+    diagnostics: relevantDiags,
+  });
+  if (!actions || actions.length === 0) return "No code actions available at this position.";
+
+  return formatCodeActions(actions);
+}
+
+// ── Utility ───────────────────────────────────────────────────────────
+
+function requireFilePosition(params: LspToolParams): {
+  file: string;
+  line: number;
+  character: number;
+} {
+  if (!params.file) throw new Error("'file' parameter is required.");
+  if (params.line === undefined) throw new Error("'line' parameter is required.");
+  if (params.character === undefined) throw new Error("'character' parameter is required.");
+  return { file: params.file, line: params.line, character: params.character };
+}
+
+function toZeroBased(line: number, character: number): { line: number; character: number } {
+  return { line: line - 1, character: character - 1 };
+}
+
+function noServerMessage(file: string): string {
+  return `No LSP server available for this file type (${path.extname(file) || "unknown"})`;
+}

package/transport.ts

@@ -0,0 +1,188 @@
+// JSON-RPC 2.0 transport over stdio with Content-Length header framing.
+
+import type { Readable, Writable } from "node:stream";
+import type {
+  JsonRpcMessage,
+  JsonRpcNotification,
+  JsonRpcRequest,
+  JsonRpcResponse,
+} from "./types.ts";
+
+const CONTENT_LENGTH = "Content-Length: ";
+const HEADER_DELIMITER = "\r\n\r\n";
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export type NotificationHandler = (method: string, params: unknown) => void;
+
+interface PendingRequest {
+  resolve: (result: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+// ── JsonRpcClient ─────────────────────────────────────────────────────
+
+export class JsonRpcClient {
+  private nextId = 1;
+  private buffer = Buffer.alloc(0);
+  private pending = new Map<number, PendingRequest>();
+  private notificationHandler: NotificationHandler | null = null;
+  private closed = false;
+  private readonly timeoutMs: number;
+
+  constructor(
+    private readonly input: Readable,
+    private readonly output: Writable,
+    options?: { timeoutMs?: number },
+  ) {
+    this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.input.on("data", (chunk: Buffer) => this.onData(chunk));
+    this.input.on("end", () => this.onClose());
+    this.input.on("error", () => this.onClose());
+  }
+
+  /** Register a handler for server notifications (no id). */
+  onNotification(handler: NotificationHandler): void {
+    this.notificationHandler = handler;
+  }
+
+  /** Send a request and wait for the correlated response. */
+  sendRequest(method: string, params?: unknown): Promise<unknown> {
+    if (this.closed) {
+      return Promise.reject(new Error("JSON-RPC client is closed"));
+    }
+
+    const id = this.nextId++;
+    const promise = new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Request ${method} (id=${id}) timed out after ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+    });
+
+    const msg: JsonRpcRequest = { jsonrpc: "2.0", id, method, params };
+    this.writeMessage(msg);
+
+    // Prevent unhandled rejection when dispose() rejects orphaned promises
+    promise.catch(() => {});
+    return promise;
+  }
+
+  /** Send a notification (no response expected). */
+  sendNotification(method: string, params?: unknown): void {
+    if (this.closed) return;
+    const msg: JsonRpcNotification = { jsonrpc: "2.0", method, params };
+    this.writeMessage(msg);
+  }
+
+  /** Clean up all pending requests. */
+  dispose(): void {
+    this.closed = true;
+    for (const [id, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(new Error("JSON-RPC client disposed"));
+      this.pending.delete(id);
+    }
+  }
+
+  // ── Private ───────────────────────────────────────────────────────
+
+  private writeMessage(msg: JsonRpcMessage): void {
+    const body = JSON.stringify(msg);
+    const contentLength = Buffer.byteLength(body, "utf-8");
+    const header = `${CONTENT_LENGTH}${contentLength}${HEADER_DELIMITER}`;
+    this.output.write(header + body);
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    this.processBuffer();
+  }
+
+  private processBuffer(): void {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      // Look for header delimiter
+      const headerEnd = this.buffer.indexOf(HEADER_DELIMITER);
+      if (headerEnd === -1) return;
+
+      // Parse Content-Length from headers
+      const headerText = this.buffer.subarray(0, headerEnd).toString("utf-8");
+      const contentLength = parseContentLength(headerText);
+      if (contentLength === null) {
+        // Malformed header — skip past delimiter and try again
+        this.buffer = this.buffer.subarray(headerEnd + HEADER_DELIMITER.length);
+        continue;
+      }
+
+      // Check if we have the full body
+      const bodyStart = headerEnd + HEADER_DELIMITER.length;
+      const messageEnd = bodyStart + contentLength;
+      if (this.buffer.length < messageEnd) {
+        return; // Need more data — partial message
+      }
+
+      // Extract and parse the body
+      const body = this.buffer.subarray(bodyStart, messageEnd).toString("utf-8");
+      this.buffer = this.buffer.subarray(messageEnd);
+
+      try {
+        const msg = JSON.parse(body) as JsonRpcMessage;
+        this.handleMessage(msg);
+      } catch {
+        // Malformed JSON — skip
+      }
+    }
+  }
+
+  private handleMessage(msg: JsonRpcMessage): void {
+    // Response (has id, has result or error)
+    if ("id" in msg && msg.id != null && ("result" in msg || "error" in msg)) {
+      const response = msg as JsonRpcResponse;
+      const pending = this.pending.get(response.id);
+      if (pending) {
+        this.pending.delete(response.id);
+        clearTimeout(pending.timer);
+        if (response.error) {
+          pending.reject(new Error(`LSP error ${response.error.code}: ${response.error.message}`));
+        } else {
+          pending.resolve(response.result);
+        }
+      }
+      return;
+    }
+
+    // Notification (no id)
+    if ("method" in msg && !("id" in msg)) {
+      const notification = msg as JsonRpcNotification;
+      this.notificationHandler?.(notification.method, notification.params);
+    }
+
+    // Request from server (has id + method) — we don't handle server→client requests yet
+  }
+
+  private onClose(): void {
+    this.closed = true;
+    for (const [id, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(new Error("JSON-RPC connection closed"));
+      this.pending.delete(id);
+    }
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function parseContentLength(header: string): number | null {
+  for (const line of header.split("\r\n")) {
+    if (line.startsWith(CONTENT_LENGTH)) {
+      const value = parseInt(line.slice(CONTENT_LENGTH.length), 10);
+      if (Number.isFinite(value) && value >= 0) return value;
+    }
+  }
+  return null;
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["*.ts"],
+  "exclude": ["__tests__"]
+}