@mrclrchtr/supi-lsp 1.0.0 → 1.1.3

package/README.md

@@ -1,112 +1,66 @@
 # @mrclrchtr/supi-lsp
 
-Language Server Protocol integration for the [pi coding agent](https://github.com/earendil-works/pi).
+Language Server Protocol for PI — your agent navigates code like an IDE.
 
-## Install
-
-```bash
-pi install npm:@mrclrchtr/supi-lsp
-```
-
-## What it adds
-
-- `lsp` tool with `hover`, `definition`, `references`, `diagnostics`, `symbols`, `rename`, `code_actions`, `workspace_symbol`, `search`, `symbol_hover`, and `recover`
-- Stable system-prompt guidance that tells the agent to prefer LSP over grep/rg for code navigation
-- Proactive project scanning and eager startup of detected language servers
-- Automatic stale-diagnostic recovery when workspace sentinels change (`package.json`, root lockfiles, `tsconfig*`, generated `*.d.ts` files`) before the next agent turn, plus immediate recovery after successful `write` or `edit` calls for those paths
-- Inline diagnostic surfacing around reads, writes, and edits
-- Compact diagnostic context injection when outstanding diagnostics change, with stale-diagnostic warnings when needed
-- `/lsp-status` status overlay
+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.
 
-## Public library API
+## What you get
 
-In addition to the extension entrypoint, `@mrclrchtr/supi-lsp` exports a reusable session-scoped service API for peer extensions:
+### Navigate with precision
 
-```ts
-import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp";
-
-const state = getSessionLspService("/project");
+Go-to-definition, find-references, rename, hover types. The agent stops guessing and starts navigating your codebase with IDE-level accuracy.
 
-if (state.kind === "ready") {
-  const service = state.service;
-  const hover = await service.hover("src/index.ts", { line: 5, character: 10 });
-  const defs = await service.definition("src/index.ts", { line: 5, character: 10 });
-  const refs = await service.references("src/index.ts", { line: 5, character: 10 });
-  const impls = await service.implementation("src/index.ts", { line: 5, character: 10 });
-  const symbols = await service.documentSymbols("src/index.ts");
-  const projectServers = service.getProjectServers();
-}
-```
+### Catch problems immediately
 
-Peer extensions can import from the package root without reaching into private files.
+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.
 
-## Tool actions
+### Always ready
 
-The `lsp` tool supports these actions:
+Servers start automatically for your project. The agent gets language-aware guidance at session start and stale diagnostics are refreshed when dependencies change.
 
-- `hover`: type info at a position
-- `definition`: go to definition
-- `references`: find all references
-- `diagnostics`: per-file or project-wide diagnostics
-- `symbols`: document symbols
-- `rename`: workspace-wide rename
-- `code_actions`: quick fixes at a position
-- `workspace_symbol`: fuzzy symbol search across the project
-- `search`: symbol search with text fallback
-- `symbol_hover`: hover by symbol name
-- `recover`: refresh diagnostics after workspace-wide dependency, config, or generated-type changes
-
-Line and character positions are **1-based**.
-
-Example:
+## Install
 
-```json
-{
-  "action": "definition",
-  "file": "src/index.ts",
-  "line": 12,
-  "character": 8
-}
+```bash
+pi install npm:@mrclrchtr/supi-lsp
 ```
 
-## Configuration
+## Quick look
 
-If your install surface includes `/supi-settings` (for example via `@mrclrchtr/supi`), this package contributes an LSP settings section there. Use that panel to:
+The agent gets an `lsp` tool. The most-used actions:
 
-- enable or disable LSP globally
-- control the severity threshold
-- select active language servers
-- configure file exclusion patterns
+| 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 |
 
-## Commands
+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.
 
-`/lsp-status` toggles an overlay showing active language servers and outstanding diagnostics:
+## Settings
 
-```text
- λ LSP inspector  /lsp-status toggles
- 3 servers running • 12 open files • 5 errors • 2 warnings
+Configure via `/supi-settings` (LSP panel):
 
- Servers
-   typescript  running    24 open files
-   python      running     8 open files
-   bash        running     0 open 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)
 
- Problems
-   src/lsp.ts:42       Cannot find name 'foo'          ts(2304)
-   src/manager.ts:108  Property 'bar' does not exist   ts(2339)
-```
+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.
 
-When no servers are available, the overlay shows `no LSP servers available for this project`. A compact status summary is always visible in the pi status bar.
+## For extension developers
 
-## Requirements
+This package exports a reusable session-scoped LSP service. Peer extensions can query the same LSP runtime without starting duplicate servers:
 
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-- `typebox`
-- relevant language servers installed and available on `PATH`
-- `@mrclrchtr/supi-core`
+```ts
+import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp";
 
-## Source
+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 });
+}
+```
 
-- Extension entrypoint: `lsp.ts`
-- Public library surface: `index.ts`
+Import from the package root — no need to reach into internal files.

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "0.2.0",
+  "version": "1.1.3",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -22,9 +22,13 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
-  "devDependencies": {
-    "@types/node": "25.6.2",
-    "vitest": "4.1.5"
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
   },
   "main": "src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "1.0.0",
+  "version": "1.1.3",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "workspace:*"
+    "@mrclrchtr/supi-core": "1.1.3"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -32,9 +32,19 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
-  "devDependencies": {
-    "vitest": "4.1.5",
-    "@mrclrchtr/supi-test-utils": "workspace:*"
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "pi": {
     "extensions": [

package/src/diagnostics/stale-diagnostics.ts

@@ -31,7 +31,7 @@ export function assessStaleDiagnostics(
   };
 }
 
-function isLikelyStaleDiagnostic(diagnostic: Diagnostic): boolean {
+export function isLikelyStaleDiagnostic(diagnostic: Diagnostic): boolean {
   if (diagnostic.severity === undefined) return false;
   if (diagnostic.code !== undefined) {
     if (typeof diagnostic.code === "number" && MODULE_RESOLUTION_CODES.has(diagnostic.code)) {

package/src/lsp.ts

@@ -29,6 +29,7 @@ import {
   removeLspTool,
 } from "./lsp-state.ts";
 import { LspManager } from "./manager/manager.ts";
+import { forceResyncStaleModuleFiles } from "./manager/manager-stale-resync.ts";
 import { registerLspAwareToolOverrides } from "./overrides.ts";
 import { registerLspMessageRenderer } from "./renderer.ts";
 import { scanMissingServers, scanProjectCapabilities, startDetectedServers } from "./scanner.ts";
@@ -305,6 +306,16 @@ function registerBehaviorHandlers(pi: ExtensionAPI, state: LspRuntimeState): voi
       // Refresh failures must not prevent agent startup
     }
     state.manager.pruneMissingFiles();
+
+    // Force re-open files with module-resolution errors to clear stale
+    // diagnostics that persist when the TS server caches by content hash.
+    // Must run before the diagnostic summary so fresh results are captured.
+    try {
+      await forceResyncStaleModuleFiles(state.manager, ctx.cwd);
+    } catch {
+      // Best-effort: don't fail the agent turn
+    }
+
     refreshProjectServers(state);
     updateLspUi(ctx, state.manager, state.inlineSeverity, state.projectServers);
 

package/src/manager/manager-stale-resync.ts

@@ -0,0 +1,47 @@
+import * as path from "node:path";
+import { isLikelyStaleDiagnostic } from "../diagnostics/stale-diagnostics.ts";
+import type { LspManager } from "./manager.ts";
+
+/**
+ * Force re-open files with module-resolution errors (e.g., "Cannot find module")
+ * to trigger fresh analysis by the language server.
+ *
+ * The TypeScript server caches diagnostics by file content hash. When a new
+ * file is created that resolves an existing file's import, the stale diagnostic
+ * persists because the importing file's content hasn't changed. Re-opening the
+ * file (didClose + didOpen) forces the server to re-resolve all imports.
+ *
+ * Returns true if any files were re-synced.
+ */
+export async function forceResyncStaleModuleFiles(
+  manager: LspManager,
+  cwd: string,
+): Promise<boolean> {
+  const outstanding = manager.getOutstandingDiagnostics(1);
+  const staleFiles: string[] = [];
+
+  for (const entry of outstanding) {
+    if (entry.diagnostics.some((d) => isLikelyStaleDiagnostic(d))) {
+      staleFiles.push(entry.file);
+    }
+  }
+
+  if (staleFiles.length === 0) return false;
+
+  for (const file of staleFiles) {
+    const filePath = path.resolve(cwd, file);
+    // Close the file to clear cached diagnostics and remove from openDocs
+    manager.closeFile(filePath);
+    // Re-open to force the server to re-resolve imports
+    await manager.ensureFileOpen(filePath);
+  }
+
+  // Re-sync and wait for fresh diagnostics after the re-opens
+  try {
+    await manager.refreshOpenDiagnostics({ quietMs: 300, maxWaitMs: 2000 });
+  } catch {
+    // Best-effort: don't fail the agent turn if refresh has issues
+  }
+
+  return true;
+}

package/src/settings-registration.ts

@@ -151,7 +151,7 @@ function buildLspSettingItems(
       id: "exclude",
       label: "Exclude Patterns",
       description:
-        "Gitignore patterns to suppress LSP diagnostics (e.g. __tests__/, *.generated.ts)",
+        "Gitignore patterns to suppress LSP diagnostics. Edit .pi/supi/config.json → lsp.exclude (or ~/.pi/agent/supi/config.json for global). Patterns like __tests__/ exclude a directory, *.test.ts wildcards match at any depth, /dist anchors to root.",
       currentValue: settings.exclude.length > 0 ? settings.exclude.join(", ") : "none",
       submenu: (_currentValue, done) => createExcludeSubmenu(scope, cwd, settings, done),
     },