@mrclrchtr/supi-lsp 1.5.0 → 1.7.0

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,8 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -28,6 +29,9 @@
     },
     "@earendil-works/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "main": "src/api.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -1,11 +1,12 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
-// and settings registry for supi-wide TUI settings.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
 
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
+  readJsonFile,
   removeSupiConfigKey,
   writeSupiConfig,
 } from "./config/config.ts";
@@ -83,3 +84,13 @@ export {
   signalWaiting,
   WAITING_SYMBOL,
 } from "./terminal.ts";
+export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
+export {
+  CharacterParam,
+  derivePromptSurface,
+  FileParam,
+  LineParam,
+  MaxResultsParam,
+  registerSuiPiTools,
+  SymbolParam,
+} from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -20,7 +20,7 @@ function getProjectConfigPath(cwd: string): string {
   return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
 }
 
-function readJsonFile(filePath: string): Record<string, unknown> | null {
+export function readJsonFile(filePath: string): Record<string, unknown> | null {
   let content: string;
   try {
     content = fs.readFileSync(filePath, "utf-8");

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -1,11 +1,12 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
-// and settings registry for supi-wide TUI settings.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
 
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
+  readJsonFile,
   removeSupiConfigKey,
   writeSupiConfig,
 } from "./config/config.ts";
@@ -83,3 +84,13 @@ export {
   signalWaiting,
   WAITING_SYMBOL,
 } from "./terminal.ts";
+export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
+export {
+  CharacterParam,
+  derivePromptSurface,
+  FileParam,
+  LineParam,
+  MaxResultsParam,
+  registerSuiPiTools,
+  SymbolParam,
+} from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -0,0 +1,116 @@
+// Shared tool framework for SuPi extensions.
+//
+// Provides a standard ToolSpec→PromptSurface→registerTool pipeline so
+// individual packages do not duplicate spec interfaces, guidance derivation,
+// registration loops, or common TypeBox parameter schemas.
+
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Minimum contract for a SuPi tool definition. */
+export interface SuiPiToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+}
+
+/** Derived prompt surface — what pi flattens into the system prompt. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guidance derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Static derivation: copies spec fields into a prompt surface.
+ *
+ * Packages that need dynamic guidance (e.g. server-coverage injection) should
+ * build their own surfaces, optionally starting from the output of this helper.
+ */
+export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface {
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/complexity/useMaxParams: matches pi ToolDefinition.execute signature
+export type ToolExecuteFn = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+/**
+ * Register a set of tools from specs + pre-derived surfaces.
+ *
+ * `createExecute` receives the spec and returns a pi-compatible execute
+ * function.  This keeps execute-logic package-local while the framework owns
+ * the declarative surface and registration boilerplate.
+ */
+export function registerSuiPiTools(
+  pi: ExtensionAPI,
+  specs: readonly SuiPiToolSpec[],
+  surfaces: Record<string, SuiPiToolPromptSurface>,
+  createExecute: (spec: SuiPiToolSpec) => ToolExecuteFn,
+): void {
+  for (const spec of specs) {
+    const surface = surfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface?.description ?? spec.description,
+      promptSnippet: surface?.promptSnippet ?? spec.promptSnippet,
+      promptGuidelines: surface?.promptGuidelines ?? [...spec.promptGuidelines],
+      parameters: spec.parameters,
+      execute: createExecute(spec),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter builders
+// ---------------------------------------------------------------------------
+
+/** File path (relative or absolute). */
+export const FileParam = Type.String({ description: "File path (relative or absolute)" });
+
+/** 1-based line number. */
+export const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+
+/** 1-based character column (UTF-16). */
+export const CharacterParam = Type.Number({
+  description: "1-based column number (UTF-16)",
+  minimum: 1,
+});
+
+/** Symbol name for discovery-based resolution. */
+export const SymbolParam = Type.String({
+  description: "Symbol name for discovery-based resolution",
+});
+
+/** Maximum results to return. */
+export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -21,11 +21,18 @@
     "!__tests__"
   ],
   "dependencies": {
+    "ignore": "^7.0.5",
     "typescript": "6.0.3",
-    "@mrclrchtr/supi-core": "1.5.0"
+    "vscode-jsonrpc": "^8.2.1",
+    "vscode-languageserver-protocol": "^3.17.5",
+    "vscode-languageserver-types": "^3.17.5",
+    "@mrclrchtr/supi-core": "1.7.0"
   },
   "bundledDependencies": [
-    "@mrclrchtr/supi-core"
+    "@mrclrchtr/supi-core",
+    "vscode-jsonrpc",
+    "vscode-languageserver-protocol",
+    "vscode-languageserver-types"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/client/client.ts

@@ -173,7 +173,13 @@ export class LspClient {
           setTimeout(() => reject(new Error("shutdown timeout")), SHUTDOWN_TIMEOUT_MS),
         ),
       ]);
-      this.rpc.sendNotification("exit");
+      // Flush the final exit notification before disposing the transport.
+      await Promise.race([
+        this.rpc.sendNotification("exit"),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error("exit notification timeout")), SHUTDOWN_TIMEOUT_MS),
+        ),
+      ]);
     } catch {
       // Timeout or error — force kill
     }
@@ -333,10 +339,7 @@ export class LspClient {
 
   /** Check if server supports pull diagnostics. */
   get hasDiagnosticProvider(): boolean {
-    return (
-      this.capabilities?.diagnosticProvider !== undefined &&
-      this.capabilities.diagnosticProvider !== false
-    );
+    return this.capabilities?.diagnosticProvider !== undefined;
   }
 
   /** Notify the server that watched workspace files changed. */

package/src/client/transport.ts

@@ -1,16 +1,18 @@
-// JSON-RPC 2.0 transport over stdio with Content-Length header framing.
+// JSON-RPC 2.0 transport — thin wrapper around vscode-jsonrpc.
+// Handles Content-Length framing, request/response correlation, timeouts,
+// and notification/request dispatching through vscode-jsonrpc's MessageConnection.
 
 import type { Readable, Writable } from "node:stream";
-import type {
-  JsonRpcId,
-  JsonRpcMessage,
-  JsonRpcNotification,
-  JsonRpcRequest,
-  JsonRpcResponse,
-} from "../config/types.ts";
-
-const CONTENT_LENGTH = "Content-Length: ";
-const HEADER_DELIMITER = "\r\n\r\n";
+import {
+  CancellationTokenSource,
+  createMessageConnection,
+  type MessageConnection,
+  NullLogger,
+  ResponseError,
+  StreamMessageReader,
+  StreamMessageWriter,
+} from "vscode-jsonrpc/node";
+
 const DEFAULT_TIMEOUT_MS = 30_000;
 
 // ── Types ─────────────────────────────────────────────────────────────
@@ -18,29 +20,15 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 export type NotificationHandler = (method: string, params: unknown) => void;
 export type RequestHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
 
-interface PendingRequest {
-  resolve: (result: unknown) => void;
-  reject: (error: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
-}
+/** Re-export ResponseError so callers don't need a separate vscode-jsonrpc import. */
+const JsonRpcRequestError = ResponseError;
 
-export class JsonRpcRequestError extends Error {
-  constructor(
-    readonly code: number,
-    message: string,
-    readonly data?: unknown,
-  ) {
-    super(message);
-    this.name = "JsonRpcRequestError";
-  }
-}
+export { JsonRpcRequestError };
 
 // ── JsonRpcClient ─────────────────────────────────────────────────────
 
 export class JsonRpcClient {
-  private nextId = 1;
-  private buffer = Buffer.alloc(0);
-  private pending = new Map<JsonRpcId, PendingRequest>();
+  private connection: MessageConnection | null = null;
   private notificationHandler: NotificationHandler | null = null;
   private requestHandler: RequestHandler | null = null;
   private closed = false;
@@ -52,9 +40,31 @@ export class JsonRpcClient {
     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());
+
+    const reader = new StreamMessageReader(this.input);
+    const writer = new StreamMessageWriter(this.output);
+
+    this.connection = createMessageConnection(reader, writer, NullLogger);
+
+    // Register catch-all notification handler
+    this.connection.onNotification((method, params) => {
+      this.notificationHandler?.(method, params);
+    });
+
+    // Register catch-all request handler for server-initiated requests
+    this.connection.onRequest(async (method, params, _token) => {
+      if (!this.requestHandler) {
+        throw new JsonRpcRequestError(-32601, `Method not found: ${method}`);
+      }
+      return this.requestHandler(method, params);
+    });
+
+    // Handle connection close
+    this.connection.onClose(() => {
+      this.closed = true;
+    });
+
+    this.connection.listen();
   }
 
   /** Register a handler for server notifications (no id). */
@@ -73,176 +83,55 @@ export class JsonRpcClient {
     params?: unknown,
     options?: { timeoutMs?: number },
   ): Promise<unknown> {
-    if (this.closed) {
+    if (this.closed || !this.connection) {
       return Promise.reject(new Error("JSON-RPC client is closed"));
     }
 
-    const id = this.nextId++;
     const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
-    const promise = new Promise<unknown>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error(`Request ${method} (id=${id}) timed out after ${timeoutMs}ms`));
-      }, 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
+    const tokenSource = new CancellationTokenSource();
+
+    const timer = setTimeout(() => tokenSource.cancel(), timeoutMs);
+
+    const request = this.connection.sendRequest(method, params, tokenSource.token);
+
+    // Race the request against a timeout so callers don't hang forever.
+    // The CancellationToken is also passed to sendRequest so the connection
+    // can short-circuit writes and cleanup when the token fires.
+    const promise = Promise.race([
+      request,
+      new Promise<never>((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`Request ${method} timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        ),
+      ),
+    ]).finally(() => clearTimeout(timer));
+
+    // Prevent unhandled rejection when dispose() cancels requests
     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);
+  /**
+   * Send a notification (no response expected).
+   *
+   * Returns the underlying write promise so ordering-sensitive cleanup paths
+   * can await the final flush. A no-op catch is still attached to prevent
+   * unhandled rejections when callers intentionally fire-and-forget.
+   */
+  sendNotification(method: string, params?: unknown): Promise<void> {
+    if (this.closed || !this.connection) return Promise.resolve();
+    const promise = this.connection.sendNotification(method, params);
+    promise.catch(() => {});
+    return promise;
   }
 
-  /** Clean up all pending requests. */
+  /** Clean up the connection. */
   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 {
-    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 id = response.id;
-      if (id === null) return;
-      const pending = this.pending.get(id);
-      if (pending) {
-        this.pending.delete(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);
-      return;
-    }
-
-    // Request from server (has id + method)
-    if ("method" in msg && "id" in msg && msg.id != null) {
-      void this.handleInboundRequest(msg as JsonRpcRequest);
-    }
-  }
-
-  private async handleInboundRequest(request: JsonRpcRequest): Promise<void> {
-    if (this.closed) return;
-
-    try {
-      if (!this.requestHandler) {
-        throw new JsonRpcRequestError(-32601, `Method not found: ${request.method}`);
-      }
-
-      const result = await this.requestHandler(request.method, request.params);
-      this.writeMessage({
-        jsonrpc: "2.0",
-        id: request.id,
-        result: result ?? null,
-      } satisfies JsonRpcResponse);
-    } catch (error) {
-      const failure =
-        error instanceof JsonRpcRequestError
-          ? error
-          : new JsonRpcRequestError(-32603, error instanceof Error ? error.message : String(error));
-      this.writeMessage({
-        jsonrpc: "2.0",
-        id: request.id,
-        error: {
-          code: failure.code,
-          message: failure.message,
-          ...(failure.data !== undefined ? { data: failure.data } : {}),
-        },
-      } satisfies JsonRpcResponse);
-    }
-  }
-
-  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;
+    if (this.connection) {
+      this.connection.dispose();
+      this.connection = null;
     }
   }
-  return null;
 }

package/src/config/server-config.ts

@@ -0,0 +1,38 @@
+// SuPi-specific server configuration types — not part of the LSP specification.
+// These are our own types for server discovery, configuration, and status tracking.
+
+export interface ServerConfig {
+  command: string;
+  args?: string[];
+  fileTypes: string[];
+  rootMarkers: string[];
+  enabled?: boolean;
+  initializationOptions?: unknown;
+}
+
+/** LSP configuration keyed by language name (e.g. `typescript`, `python`). */
+export interface LspConfig {
+  servers: Record<string, ServerConfig>;
+}
+
+export interface DetectedProjectServer {
+  name: string;
+  root: string;
+  fileTypes: string[];
+}
+
+export interface ProjectServerInfo extends DetectedProjectServer {
+  status: "running" | "error" | "unavailable";
+  supportedActions: string[];
+  openFiles: string[];
+}
+
+/** A language whose source files are present but the server binary is missing. */
+export interface MissingServer {
+  /** Language name (e.g. "python", "rust"). */
+  name: string;
+  /** Server command that was not found on PATH. */
+  command: string;
+  /** File extensions found in the project (subset of server.fileTypes). */
+  foundExtensions: string[];
+}