@mrclrchtr/supi-lsp 1.3.0 → 1.4.0

package/README.md

@@ -1,71 +1,90 @@
 # @mrclrchtr/supi-lsp
 
-Language Server Protocol for PI — your agent navigates code like an IDE.
+Adds Language Server Protocol support to the [pi coding agent](https://github.com/earendil-works/pi).
 
-Without LSP, agents grep and guess. With it, they jump to definitions, find every reference, rename across files, and catch type errors inline. The same precision you get from an editor, available to your agent.
+## Install
 
-## What you get
+```bash
+pi install npm:@mrclrchtr/supi-lsp
+```
 
-### Navigate with precision
+For local development:
 
-Go-to-definition, find-references, rename, hover types. The agent stops guessing and starts navigating your codebase with IDE-level accuracy.
+```bash
+pi install ./packages/supi-lsp
+```
 
-### Catch problems immediately
+After editing the source, run `/reload`.
 
-Type errors, warnings, and hints surface inline after every edit. The agent sees mistakes as it makes them — not 10 turns later when tests fail.
+## What you get
 
-### Always ready
+After install, pi gets:
 
-Servers start automatically for your project. The agent gets language-aware guidance at session start and stale diagnostics are refreshed when dependencies change.
+- `lsp_lookup` — semantic hover, definition, references, and implementation at a known position
+- `lsp_document_symbols` — semantic declarations for one supported file
+- `lsp_workspace_symbols` — semantic symbol-name lookup across the project
+- `lsp_diagnostics` — current diagnostics for one file or a workspace summary
+- `lsp_refactor` — semantic rename planning and code actions at a known position
+- `lsp_recover` — refresh stale diagnostics after workspace changes
+- `/lsp-status` — inspect detected servers, roots, open files, and diagnostics
+- automatic LSP-aware diagnostic surfacing around edits and agent turns
 
-## Install
+Coordinates use **1-based** line and character positions.
 
-```bash
-pi install npm:@mrclrchtr/supi-lsp
-```
+## Automatic behavior
 
-## Quick look
+This package does more than register a tool:
 
-The agent gets an `lsp` tool. The most-used actions:
+- starts detected language servers for the current project
+- rebuilds project-specific prompt guidance based on active servers
+- injects outstanding diagnostics into context before agent turns when issues exist
+- adds inline diagnostics after `write` and `edit` results
+- watches for workspace changes such as `package.json`, lockfile, `tsconfig`, generated types, and source-file edits so recovery can happen when diagnostics go stale
+- warns when configured language-server commands are missing
 
-| Action | What the agent can do |
-|--------|----------------------|
-| `hover` | See the type of any symbol |
-| `definition` | Jump to where something is defined |
-| `references` | Find every usage across the project |
-| `diagnostics` | See errors, warnings, and hints |
-| `rename` | Rename across the entire project |
+## Settings
 
-Full action reference: the agent's system prompt includes complete guidelines for all 11 actions (hover, definition, references, diagnostics, symbols, rename, code_actions, workspace_symbol, search, symbol_hover, recover). All positions are 1-based.
+This package registers an **LSP** section in `/supi-settings`.
 
-## Settings
+Available settings:
 
-Configure via `/supi-settings` (LSP panel):
+- `enabled` — turn all LSP behavior on or off
+- `severity` — inline diagnostic threshold: `1` errors, `2` warnings, `3` info, `4` hints
+- `active` — choose which configured language servers are active; empty means all
+- `exclude` — gitignore-style patterns that suppress diagnostics for matching files
 
-- Enable or disable LSP per project
-- Set diagnostic severity threshold (errors only, or include warnings/hints)
-- Choose which language servers to activate
-- Add file exclusion patterns (gitignore-style globs)
+Config lives in the standard SuPi config files:
 
-Settings are stored in `~/.pi/agent/supi/config.json` (global) or `.pi/supi/config.json` (project). The `/lsp-status` command shows active servers and outstanding diagnostics.
+- global: `~/.pi/agent/supi/config.json`
+- project: `.pi/supi/config.json`
 
 ## Package surfaces
 
-- `@mrclrchtr/supi-lsp/api` — reusable library surface for peer extensions
+- `@mrclrchtr/supi-lsp/api` — reusable session-scoped LSP service and related types
 - `@mrclrchtr/supi-lsp/extension` — pi extension entrypoint
 
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
-
-## For extension developers
-
-This package exports a reusable session-scoped LSP service. Peer extensions can query the same LSP runtime without starting duplicate servers:
+Example:
 
 ```ts
-import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp/api";
+import { getSessionLspService, toLspPosition } from "@mrclrchtr/supi-lsp/api";
 
 const state = getSessionLspService("/project");
 if (state.kind === "ready") {
-  const defs = await state.service.definition("src/index.ts", { line: 5, character: 10 });
-  const refs = await state.service.references("src/index.ts", { line: 5, character: 10 });
+  const defs = await state.service.definition("src/index.ts", toLspPosition(6, 11));
 }
 ```
+
+`SessionLspService` methods use raw **0-based LSP positions**. The expert tools (`lsp_lookup`, `lsp_refactor`, etc.) keep the public 1-based coordinate UX.
+
+## Source
+
+- `src/lsp.ts` — extension wiring, session lifecycle, and `/lsp-status`
+- `src/config/` — server config, defaults, capabilities, and exported LSP protocol types
+- `src/session/` — session state, scanning, settings registration, tree persistence, and shared service registry
+- `src/tool/register-tools.ts` — expert tool registration for the split LSP toolset
+- `src/tool/service-actions.ts` — service-backed tool execution and formatting
+- `src/tool/guidance.ts` / `src/tool/names.ts` — prompt surfaces and stable tool names
+- `src/tool/overrides.ts` — read/write/edit overrides for inline diagnostics
+- `src/ui/` — custom diagnostic message rendering and the status overlay
+- `src/client/`, `src/manager/`, `src/diagnostics/` — runtime engine subsystems
+- `src/api.ts` — reusable developer-facing surface

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -1,65 +1,78 @@
 # @mrclrchtr/supi-core
 
-Shared infrastructure for SuPi packages.
+Shared infrastructure for SuPi extensions.
+
+This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
 
 ## Install
 
-Use it as a dependency in another extension package:
+### As a dependency for another extension
 
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-## Package role
-
-`@mrclrchtr/supi-core` now has two explicit surfaces:
+### As a pi package
 
-- `@mrclrchtr/supi-core/api` — shared library helpers for other SuPi packages
-- `@mrclrchtr/supi-core/extension` — a minimal pi extension that registers `/supi-settings`
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
 
-## What it provides
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
 
-Current exports cover:
+## Package surfaces
 
-- shared config loading, scoped reads, writes, and key removal
-- config-backed settings registration helpers for `/supi-settings`
-- the shared settings registry, overlay UI, and `registerSettingsCommand()` helper
-- XML `<extension-context>` wrapping plus context-message utilities
-- context-provider and debug-event registries reused across SuPi packages
-- project root and path helpers reused by packages such as `supi-lsp`
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
-## Config system
+## What you get from the API
 
-Config resolution order:
+### Config helpers
 
-```text
-defaults <- global <- project
-```
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
 
 - global: `~/.pi/agent/supi/config.json`
 - project: `.pi/supi/config.json`
 
-Main helpers:
+### Settings helpers
+
+- `registerSettings()` — register an arbitrary settings section
+- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand()` — register `/supi-settings`
+- `openSettingsOverlay()` — open the shared settings UI directly
+- `createInputSubmenu()` — helper for simple text-entry submenus
+
+The built-in settings UI supports:
 
-- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
-- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
-- `writeSupiConfig()`
-- `removeSupiConfigKey()`
-- `registerConfigSettings()`
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
 
-## Context and settings helpers
+### Context helpers
 
-- `wrapExtensionContext()`
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 - `findLastUserMessageIndex()`
 - `getContextToken()`
+- `getPromptContent()`
 - `pruneAndReorderContextMessages()`
-- `registerSettings()`
-- `registerSettingsCommand()`
-- `openSettingsOverlay()`
+- `restorePromptContent()`
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry for producers that want shared debug capture
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
 ## Example
 
@@ -80,17 +93,15 @@ registerConfigSettings({
 });
 
 const message = wrapExtensionContext("my-extension", "hello", {
-  turn: 1,
   file: "CLAUDE.md",
+  turn: 1,
 });
 ```
 
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-
 ## Source
 
-- Library surface: `src/api.ts`
-- Extension surface: `src/extension.ts`
+- `src/api.ts` — exported library surface
+- `src/extension.ts` — minimal `/supi-settings` entrypoint
+- `src/config.ts` — shared config loading and writing
+- `src/config-settings.ts` — config-backed settings registration helper
+- `src/settings-ui.ts` — shared settings overlay

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{config-settings.ts → config/config-settings.ts}

@@ -2,9 +2,9 @@
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
-import type { SettingsScope } from "./settings-registry.ts";
-import { registerSettings } from "./settings-registry.ts";
 
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */

package/node_modules/@mrclrchtr/supi-core/src/{context-provider-registry.ts → context/context-provider-registry.ts}

@@ -3,7 +3,7 @@
 // Extensions declare context data providers via `registerContextProvider()` during their
 // factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
 
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export interface ContextProvider {
   /** Unique identifier — e.g. "rtk" */

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

@@ -1 +1 @@
-export { registerSettingsCommand as default } from "./settings-command.ts";
+export { registerSettingsCommand as default } from "./settings/settings-command.ts";

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

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{settings-registry.ts → settings/settings-registry.ts}

@@ -4,7 +4,7 @@
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export type SettingsScope = "project" | "global";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,8 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.3.0"
+    "typescript": "6.0.3",
+    "@mrclrchtr/supi-core": "1.4.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -48,7 +49,8 @@
   },
   "pi": {
     "extensions": [
-      "./src/extension.ts"
+      "./src/extension.ts",
+      "node_modules/@mrclrchtr/supi-core/src/extension.ts"
     ]
   },
   "main": "src/api.ts",

package/src/api.ts

@@ -1,8 +1,7 @@
 // Public API surface for the LSP session-scoped service.
 
-export type { SessionLspServiceState } from "./service-registry.ts";
-export { getSessionLspService, SessionLspService } from "./service-registry.ts";
 export type {
+  CodeAction,
   Diagnostic,
   DocumentSymbol,
   Hover,
@@ -10,6 +9,20 @@ export type {
   LocationLink,
   Position,
   ProjectServerInfo,
+  Range,
   SymbolInformation,
+  WorkspaceEdit,
   WorkspaceSymbol,
-} from "./types.ts";
+} from "./config/types.ts";
+export { toLspPosition, toOneBasedPosition } from "./coordinates.ts";
+export type {
+  OutstandingDiagnosticSummaryEntry,
+  RecoverDiagnosticsResult,
+  SessionLspServiceState,
+  WorkspaceDiagnosticSummaryEntry,
+} from "./session/service-registry.ts";
+export {
+  getSessionLspService,
+  SessionLspService,
+  waitForSessionLspService,
+} from "./session/service-registry.ts";

package/src/client/client-refresh.ts

@@ -2,7 +2,7 @@
 // Extracted from client.ts to keep file sizes manageable.
 
 import { existsSync, readFileSync } from "node:fs";
-import type { DocumentDiagnosticReport, TextDocumentIdentifier } from "../types.ts";
+import type { DocumentDiagnosticReport, TextDocumentIdentifier } from "../config/types.ts";
 import { uriToFile } from "../utils.ts";
 import type { DiagnosticCacheEntry, LspClient } from "./client.ts";
 import type { JsonRpcClient } from "./transport.ts";

package/src/client/client.ts

@@ -4,7 +4,8 @@
 // biome-ignore lint/nursery/noExcessiveLinesPerFile: LspClient remains a cohesive stateful wrapper; refresh logic is already split out.
 import { type ChildProcess, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { CLIENT_CAPABILITIES } from "../capabilities.ts";
+import * as path from "node:path";
+import { CLIENT_CAPABILITIES } from "../config/capabilities.ts";
 import type {
   CodeAction,
   CodeActionContext,
@@ -27,9 +28,9 @@ import type {
   VersionedTextDocumentIdentifier,
   WorkspaceEdit,
   WorkspaceSymbol,
-} from "../types.ts";
+} from "../config/types.ts";
 import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
-import { JsonRpcClient } from "./transport.ts";
+import { JsonRpcClient, JsonRpcRequestError } from "./transport.ts";
 
 const SHUTDOWN_TIMEOUT_MS = 5_000;
 const DIAGNOSTIC_WAIT_MS = 3_000;
@@ -119,6 +120,7 @@ export class LspClient {
         this.handlePublishDiagnostics(params as PublishDiagnosticsParams);
       }
     });
+    this.rpc.onRequest((method, params) => this.handleServerRequest(method, params));
 
     // Handle crashes
     this.process.on("exit", (_code) => {
@@ -469,6 +471,28 @@ export class LspClient {
     }
   }
 
+  private handleServerRequest(method: string, params: unknown): unknown {
+    switch (method) {
+      case "workspace/configuration":
+        return this.buildWorkspaceConfigurationResult(params);
+      case "workspace/workspaceFolders":
+        return [{ uri: fileToUri(this.root), name: path.basename(this.root) || this.root }];
+      case "client/registerCapability":
+      case "client/unregisterCapability":
+      case "window/workDoneProgress/create":
+        return null;
+      default:
+        throw new JsonRpcRequestError(-32601, `Method not found: ${method}`);
+    }
+  }
+
+  private buildWorkspaceConfigurationResult(params: unknown): unknown[] {
+    if (!params || typeof params !== "object") return [];
+    const items = (params as { items?: unknown }).items;
+    if (!Array.isArray(items)) return [];
+    return items.map(() => null);
+  }
+
   private handlePublishDiagnostics(params: PublishDiagnosticsParams): void {
     // If the publication includes a version and we have a newer synced
     // version for this open document, ignore the stale publication.