@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-lsp/extensions/lsp/tools/programs.ts

@@ -0,0 +1,293 @@
+/**
+ * Effect programs backing the unified `lsp` tool.
+ *
+ * Each operation is an Effect that depends on the `ServerManager` service to
+ * locate the right client, then wraps the client's async LSP calls in
+ * `Effect.tryPromise` so transport failures surface as typed
+ * `LspOperationError`s. Routing/validation failures are typed too
+ * (`LspValidationError`, `NoCapableServerError`, `NoServerAvailableError`).
+ */
+
+import { Context, Effect } from 'effect';
+
+import type { LspClient } from '../client';
+import {
+  LspOperationError,
+  LspValidationError,
+  NoCapableServerError,
+  NoServerAvailableError,
+  type LspExtensionError,
+} from '../errors';
+import {
+  formatCallHierarchy,
+  formatCodeActions,
+  formatDiagnostics,
+  formatDocumentSymbols,
+  formatHover,
+  formatIncomingCalls,
+  formatLocations,
+  formatOutgoingCalls,
+  formatWorkspaceSymbols,
+} from '../formatting';
+import type { Diagnostic } from '../types';
+import {
+  FILE_ONLY_OPERATIONS,
+  type LspOperation,
+  POSITION_OPERATIONS,
+  QUERY_OPERATIONS,
+} from '../types';
+
+// ── ServerManager service ─────────────────────────────────────────────────────
+
+export interface ServerManagerService {
+  /** Get all LSP clients that handle a given file extension. */
+  clientsForFile: (filePath: string) => LspClient[];
+  /** Get the first LSP client that handles a file and has a capability. */
+  clientForFileWithCapability: (filePath: string, capability: string) => LspClient | null;
+  /** Get any initialized client (for workspace-wide ops). */
+  anyClient: () => LspClient | null;
+  /** Current root path. */
+  getRootPath: () => string;
+}
+
+export class ServerManager extends Context.Tag('Lsp/ServerManager')<
+  ServerManager,
+  ServerManagerService
+>() {}
+
+export interface ToolResult {
+  content: { type: 'text'; text: string }[];
+  details: Record<string, unknown>;
+}
+
+export interface LspToolParams {
+  operation: LspOperation;
+  filePath?: string;
+  line?: number;
+  character?: number;
+  query?: string;
+}
+
+// ── Capability map ────────────────────────────────────────────────────────────
+
+const CAPABILITY_MAP: Record<LspOperation, string> = {
+  diagnostics: 'textDocumentSync',
+  hover: 'hoverProvider',
+  goToDefinition: 'definitionProvider',
+  findReferences: 'referencesProvider',
+  goToImplementation: 'implementationProvider',
+  documentSymbol: 'documentSymbolProvider',
+  workspaceSymbol: 'workspaceSymbolProvider',
+  prepareCallHierarchy: 'callHierarchyProvider',
+  incomingCalls: 'callHierarchyProvider',
+  outgoingCalls: 'callHierarchyProvider',
+  codeActions: 'codeActionProvider',
+};
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function cleanPath(path: string): string {
+  return path.replace(/^@/, '');
+}
+
+function toZeroIndexed(oneIndexed: number): number {
+  return Math.max(0, oneIndexed - 1);
+}
+
+function ok(text: string): ToolResult {
+  return { content: [{ type: 'text', text }], details: {} };
+}
+
+/** Server name for error context — tolerates partially-shaped clients. */
+function serverName(client: LspClient): string {
+  return client.config?.name ?? 'lsp';
+}
+
+/** Wrap an async LSP client call as a typed Effect. */
+function call<A>(
+  operation: string,
+  server: string,
+  thunk: () => Promise<A>,
+): Effect.Effect<A, LspOperationError> {
+  return Effect.tryPromise({
+    try: thunk,
+    catch: (cause) => new LspOperationError({ operation, server, cause }),
+  });
+}
+
+function validate(params: LspToolParams): Effect.Effect<void, LspValidationError> {
+  const { operation, filePath, line, character, query } = params;
+  const fail = (reason: string) => Effect.fail(new LspValidationError({ reason }));
+
+  if (POSITION_OPERATIONS.includes(operation)) {
+    if (!filePath) return fail(`Operation '${operation}' requires filePath`);
+    if (line === undefined) return fail(`Operation '${operation}' requires line`);
+    if (character === undefined) return fail(`Operation '${operation}' requires character`);
+  }
+  if (FILE_ONLY_OPERATIONS.includes(operation)) {
+    if (!filePath) return fail(`Operation '${operation}' requires filePath`);
+  }
+  if (QUERY_OPERATIONS.includes(operation)) {
+    if (!query) return fail(`Operation '${operation}' requires query`);
+  }
+  return Effect.void;
+}
+
+// ── Program ────────────────────────────────────────────────────────────────────
+
+export function lspToolProgram(
+  raw: LspToolParams,
+): Effect.Effect<ToolResult, LspExtensionError, ServerManager> {
+  return Effect.gen(function* () {
+    yield* validate(raw);
+
+    const mgr = yield* ServerManager;
+    const operation = raw.operation;
+    const filePath = raw.filePath ? cleanPath(raw.filePath) : undefined;
+    const rootPath = mgr.getRootPath();
+
+    if (operation === 'diagnostics') {
+      return yield* diagnosticsProgram(mgr, filePath!);
+    }
+
+    if (operation === 'workspaceSymbol') {
+      return yield* workspaceSymbolProgram(mgr, raw.query!, rootPath);
+    }
+
+    const capability = CAPABILITY_MAP[operation];
+    const client = mgr.clientForFileWithCapability(filePath!, capability);
+    if (!client) {
+      return yield* new NoCapableServerError({ operation, filePath: filePath! });
+    }
+
+    const server = serverName(client);
+    const line = raw.line!;
+    const character = raw.character!;
+    const pos = { line: toZeroIndexed(line), character: toZeroIndexed(character) };
+
+    switch (operation) {
+      case 'hover': {
+        const result = yield* call(operation, server, () => client.hover(filePath!, pos));
+        return ok(formatHover(result, filePath!, pos.line, pos.character));
+      }
+      case 'goToDefinition': {
+        const locs = yield* call(operation, server, () => client.definition(filePath!, pos));
+        return ok(
+          formatLocations(locs, 'Definition', filePath!, pos.line, pos.character, rootPath),
+        );
+      }
+      case 'findReferences': {
+        const locs = yield* call(operation, server, () => client.references(filePath!, pos));
+        return ok(
+          formatLocations(locs, 'References', filePath!, pos.line, pos.character, rootPath),
+        );
+      }
+      case 'goToImplementation': {
+        const locs = yield* call(operation, server, () => client.implementation(filePath!, pos));
+        return ok(
+          formatLocations(locs, 'Implementation', filePath!, pos.line, pos.character, rootPath),
+        );
+      }
+      case 'documentSymbol': {
+        const symbols = yield* call(operation, server, () => client.documentSymbol(filePath!));
+        return ok(formatDocumentSymbols(symbols, filePath!, rootPath));
+      }
+      case 'prepareCallHierarchy': {
+        const items = yield* call(operation, server, () =>
+          client.prepareCallHierarchy(filePath!, pos),
+        );
+        return ok(formatCallHierarchy(items, filePath!, pos.line, pos.character, rootPath));
+      }
+      case 'incomingCalls': {
+        const items = yield* call(operation, server, () =>
+          client.prepareCallHierarchy(filePath!, pos),
+        );
+        if (items.length === 0) {
+          return ok(`No call hierarchy item at ${filePath!}:${line}:${character}`);
+        }
+        const calls = yield* call(operation, server, () => client.incomingCalls(items[0]));
+        return ok(formatIncomingCalls(calls, items[0], rootPath));
+      }
+      case 'outgoingCalls': {
+        const items = yield* call(operation, server, () =>
+          client.prepareCallHierarchy(filePath!, pos),
+        );
+        if (items.length === 0) {
+          return ok(`No call hierarchy item at ${filePath!}:${line}:${character}`);
+        }
+        const calls = yield* call(operation, server, () => client.outgoingCalls(items[0]));
+        return ok(formatOutgoingCalls(calls, items[0], rootPath));
+      }
+      case 'codeActions': {
+        const diagsForFile = yield* call(operation, server, () => client.getDiagnostics(filePath!));
+        const zeroLine = toZeroIndexed(line);
+        const lineDiags = diagsForFile.filter(
+          (d) => d.range.start.line <= zeroLine && d.range.end.line >= zeroLine,
+        );
+        const range = {
+          start: { line: zeroLine, character: 0 },
+          end: { line: zeroLine, character: Number.MAX_SAFE_INTEGER },
+        };
+        const actions = yield* call(operation, server, () =>
+          client.codeActions(filePath!, range, { diagnostics: lineDiags }),
+        );
+        return ok(formatCodeActions(actions, filePath!, zeroLine));
+      }
+      default:
+        return yield* new LspValidationError({ reason: `Unknown operation: ${operation}` });
+    }
+  });
+}
+
+function diagnosticsProgram(
+  mgr: ServerManagerService,
+  filePath: string,
+): Effect.Effect<ToolResult, never> {
+  return Effect.gen(function* () {
+    const groups: { source: string; diagnostics: Diagnostic[] }[] = [];
+    const errors: string[] = [];
+
+    for (const client of mgr.clientsForFile(filePath)) {
+      const name = serverName(client);
+      const result = yield* call('diagnostics', name, () => client.getDiagnostics(filePath)).pipe(
+        Effect.either,
+      );
+
+      if (result._tag === 'Right') {
+        if (result.right.length > 0) {
+          groups.push({ source: name, diagnostics: result.right });
+        }
+      } else {
+        errors.push(`${name}: ${result.left.message}`);
+      }
+    }
+
+    const text = formatDiagnostics(filePath, groups);
+    const errorNote = errors.length > 0 ? `\n\nNote: ${errors.join('; ')}` : '';
+
+    return {
+      content: [{ type: 'text' as const, text: text + errorNote }],
+      details: {
+        groups: groups.map((g) => ({ source: g.source, count: g.diagnostics.length })),
+        errors,
+      },
+    };
+  });
+}
+
+function workspaceSymbolProgram(
+  mgr: ServerManagerService,
+  query: string,
+  rootPath: string,
+): Effect.Effect<ToolResult, LspExtensionError> {
+  return Effect.gen(function* () {
+    const client = mgr.anyClient();
+    if (!client) {
+      return yield* new NoServerAvailableError({ operation: 'workspace symbol search' });
+    }
+    const symbols = yield* call('workspaceSymbol', serverName(client), () =>
+      client.workspaceSymbol(query),
+    );
+    return ok(formatWorkspaceSymbols(symbols, query, rootPath));
+  });
+}

package/3p/pi-lsp/extensions/lsp/tools.ts

@@ -0,0 +1,89 @@
+/**
+ * Single unified `lsp` tool registration.
+ *
+ * 11 operations routed to the right server by file extension. The execution
+ * logic lives in `tools/programs.ts` as Effect programs; this module owns the
+ * tool schema/description and runs the program with the live `ServerManager`.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Effect } from 'effect';
+import { Type } from 'typebox';
+import { StringEnum } from '@earendil-works/pi-ai';
+
+import { toNativeError } from './errors';
+import {
+  lspToolProgram,
+  ServerManager,
+  type LspToolParams,
+  type ServerManagerService,
+} from './tools/programs';
+import { LSP_OPERATIONS, type LspOperation } from './types';
+
+export type { ServerManagerService } from './tools/programs';
+export { ServerManager } from './tools/programs';
+
+// ── Registration ────────────────────────────────────────────────────────────
+
+export function registerLspTool(pi: ExtensionAPI, mgr: ServerManagerService) {
+  pi.registerTool({
+    name: 'lsp',
+    label: 'LSP',
+    description: [
+      'Interact with Language Server Protocol servers for code intelligence.',
+      '',
+      'Supported operations:',
+      '  goToDefinition    — find where a symbol is defined',
+      '  findReferences    — find all references to a symbol',
+      '  hover             — get type info and documentation for a symbol',
+      '  diagnostics       — get type errors and lint warnings for a file',
+      '  documentSymbol    — get all symbols in a file (with line:column positions)',
+      '  workspaceSymbol   — search for symbols across the workspace',
+      '  goToImplementation — find implementations of an interface/abstract method',
+      '  prepareCallHierarchy — get call hierarchy item at a position',
+      '  incomingCalls     — find callers of a function/method (auto-prepares hierarchy)',
+      '  outgoingCalls     — find callees of a function/method (auto-prepares hierarchy)',
+      '  codeActions       — get quick fixes and refactoring suggestions',
+      '',
+      'Parameters:',
+      '  operation (required) — one of the operations above',
+      '  filePath  — file path relative to project root (required for most operations)',
+      '  line      — line number, 1-indexed (required for position-based operations)',
+      '  character — column number, 1-indexed (required for position-based operations)',
+      '  query     — search string (required for workspaceSymbol)',
+      '',
+      'Tips:',
+      '  — Position the character in the middle of the symbol name for best results.',
+      '  — Use hover before goToDefinition to quickly check signatures and docs.',
+      '  — workspaceSymbol may need a retry if the server is still indexing.',
+    ].join('\n'),
+    promptSnippet:
+      'Interact with LSP servers for code intelligence: definitions, references, hover, diagnostics, symbols, call hierarchy, code actions',
+    promptGuidelines: [
+      'lsp line and character params are 1-indexed — use the values from the read tool or rg output directly.',
+      'lsp `hover` is the fastest way to get a function signature, type params, and doc comment — prefer it over `goToDefinition` for quick type inspection.',
+      'lsp `documentSymbol` returns line:column positions for each symbol — use those values directly for follow-up lsp operations.',
+      'For lsp position-based operations, place the character in the **middle** of the symbol name, not at the first character.',
+      'lsp `incomingCalls` and `outgoingCalls` automatically prepare the call hierarchy — no need to call `prepareCallHierarchy` first.',
+      'lsp `workspaceSymbol` may return empty results while the LSP server is still indexing. If it returns nothing, wait a few seconds and retry.',
+      'lsp `diagnostics` relies on server-pushed notifications which may be slow for some servers. For compiled languages (Rust, Go, C++), prefer running the compiler directly (e.g. `cargo check`, `go build`) for reliable error checking.',
+      'Use lsp for type info, macro-generated symbols, and cross-module navigation. Use rg for simple text search and file discovery — it is faster and needs no server.',
+      'lsp servers are auto-detected by file extension. Use /lsp to check status.',
+    ],
+    parameters: Type.Object({
+      operation: StringEnum(LSP_OPERATIONS),
+      filePath: Type.Optional(Type.String({ description: 'File path relative to project root' })),
+      line: Type.Optional(Type.Number({ description: 'Line number (1-indexed)' })),
+      character: Type.Optional(Type.Number({ description: 'Column number (1-indexed)' })),
+      query: Type.Optional(Type.String({ description: 'Search query (for workspaceSymbol)' })),
+    }),
+    async execute(_toolCallId, params) {
+      const program = lspToolProgram(params as LspToolParams);
+      return Effect.runPromise(
+        program.pipe(Effect.provideService(ServerManager, mgr), Effect.mapError(toNativeError)),
+      );
+    },
+  });
+}
+
+export type { LspOperation };

package/3p/pi-lsp/extensions/lsp/types.ts

@@ -0,0 +1,243 @@
+// ── LSP protocol types (minimal subset) ─────────────────────────────────────
+
+/** 0-indexed line/character position. */
+export interface Position {
+  line: number;
+  character: number;
+}
+
+export interface Range {
+  start: Position;
+  end: Position;
+}
+
+export interface Location {
+  uri: string;
+  range: Range;
+}
+
+export const enum DiagnosticSeverity {
+  Error = 1,
+  Warning = 2,
+  Information = 3,
+  Hint = 4,
+}
+
+export interface DiagnosticRelatedInformation {
+  location: Location;
+  message: string;
+}
+
+export interface Diagnostic {
+  range: Range;
+  severity?: DiagnosticSeverity;
+  code?: number | string;
+  codeDescription?: { href: string };
+  source?: string;
+  message: string;
+  relatedInformation?: DiagnosticRelatedInformation[];
+}
+
+export interface MarkupContent {
+  kind: 'plaintext' | 'markdown';
+  value: string;
+}
+
+export interface Hover {
+  contents: MarkupContent | string | Array<string | { language: string; value: string }>;
+  range?: Range;
+}
+
+export interface CodeActionContext {
+  diagnostics: Diagnostic[];
+  only?: string[];
+}
+
+export interface CodeAction {
+  title: string;
+  kind?: string;
+  diagnostics?: Diagnostic[];
+  isPreferred?: boolean;
+  edit?: WorkspaceEdit;
+}
+
+export interface TextEdit {
+  range: Range;
+  newText: string;
+}
+
+export interface WorkspaceEdit {
+  changes?: Record<string, TextEdit[]>;
+}
+
+export interface PublishDiagnosticsParams {
+  uri: string;
+  diagnostics: Diagnostic[];
+  version?: number;
+}
+
+// ── Symbol types ────────────────────────────────────────────────────────────
+
+export const enum SymbolKind {
+  File = 1,
+  Module = 2,
+  Namespace = 3,
+  Package = 4,
+  Class = 5,
+  Method = 6,
+  Property = 7,
+  Field = 8,
+  Constructor = 9,
+  Enum = 10,
+  Interface = 11,
+  Function = 12,
+  Variable = 13,
+  Constant = 14,
+  String = 15,
+  Number = 16,
+  Boolean = 17,
+  Array = 18,
+  Object = 19,
+  Key = 20,
+  Null = 21,
+  EnumMember = 22,
+  Struct = 23,
+  Event = 24,
+  Operator = 25,
+  TypeParameter = 26,
+}
+
+export interface DocumentSymbol {
+  name: string;
+  detail?: string;
+  kind: SymbolKind;
+  range: Range;
+  selectionRange: Range;
+  children?: DocumentSymbol[];
+}
+
+export interface SymbolInformation {
+  name: string;
+  kind: SymbolKind;
+  location: Location;
+  containerName?: string;
+}
+
+// ── Call hierarchy types ────────────────────────────────────────────────────
+
+export interface CallHierarchyItem {
+  name: string;
+  kind: SymbolKind;
+  detail?: string;
+  uri: string;
+  range: Range;
+  selectionRange: Range;
+}
+
+export interface CallHierarchyIncomingCall {
+  from: CallHierarchyItem;
+  fromRanges: Range[];
+}
+
+export interface CallHierarchyOutgoingCall {
+  to: CallHierarchyItem;
+  fromRanges: Range[];
+}
+
+// ── JSON-RPC types ──────────────────────────────────────────────────────────
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: number;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+// ── Server configuration ────────────────────────────────────────────────────
+
+/** Config for a single LSP server as written in config files. */
+export interface LspServerUserConfig {
+  /** Command + args to spawn the server. e.g. ["typescript-language-server", "--stdio"] */
+  command?: string[];
+  /** File extensions this server handles (with leading dot). */
+  extensions?: string[];
+  /** Disable this server. */
+  disabled?: boolean;
+  /** Environment variables for the server process. */
+  env?: Record<string, string>;
+  /** Initialization options sent during LSP initialize. */
+  initialization?: Record<string, unknown>;
+}
+
+/** Top-level config file shape. */
+export interface LspConfigFile {
+  /** Set to false to disable all LSP servers. */
+  lsp?: false | Record<string, LspServerUserConfig>;
+}
+
+/** Resolved server config ready to use. */
+export interface ResolvedServerConfig {
+  /** Server name (key from config). */
+  name: string;
+  /** Command to spawn. */
+  command: string;
+  /** Command arguments. */
+  args: string[];
+  /** File extensions this server handles (with leading dot). */
+  extensions: string[];
+  /** Environment variables for the server process. */
+  env: Record<string, string>;
+  /** Initialization options. */
+  initializationOptions: Record<string, unknown>;
+}
+
+// ── Operations ──────────────────────────────────────────────────────────────
+
+export const LSP_OPERATIONS = [
+  'diagnostics',
+  'hover',
+  'goToDefinition',
+  'findReferences',
+  'goToImplementation',
+  'documentSymbol',
+  'workspaceSymbol',
+  'prepareCallHierarchy',
+  'incomingCalls',
+  'outgoingCalls',
+  'codeActions',
+] as const;
+
+export type LspOperation = (typeof LSP_OPERATIONS)[number];
+
+/** Operations that require filePath + line + character. */
+export const POSITION_OPERATIONS: LspOperation[] = [
+  'hover',
+  'goToDefinition',
+  'findReferences',
+  'goToImplementation',
+  'prepareCallHierarchy',
+  'incomingCalls',
+  'outgoingCalls',
+  'codeActions',
+];
+
+/** Operations that require filePath only. */
+export const FILE_ONLY_OPERATIONS: LspOperation[] = ['diagnostics', 'documentSymbol'];
+
+/** Operations that require query only. */
+export const QUERY_OPERATIONS: LspOperation[] = ['workspaceSymbol'];

package/3p/pi-lsp/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@dreki-gg/pi-lsp",
+  "version": "0.4.0",
+  "description": "Language-agnostic LSP code intelligence for pi — diagnostics, hover, definitions, references, symbols, and call hierarchy",
+  "keywords": [],
+  "author": "Juan Albarran <jalbarrandev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dreki-gg/pi-extensions",
+    "directory": "packages/lsp"
+  },
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "oxlint extensions test",
+    "format": "oxfmt --write extensions test",
+    "format:check": "oxfmt --check extensions test"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/lsp"
+    ]
+  },
+  "dependencies": {
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@types/node": "24",
+    "bun-types": "latest",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "typescript": "^6.0.0",
+    "typescript-language-server": "^5.1.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}