@wrongstack/plug-lsp 0.264.0 → 0.267.0

package/README.md

@@ -1,23 +1,136 @@
 # @wrongstack/plug-lsp
 
-Language Server Protocol tools for WrongStack.
+Language Server Protocol (LSP) integration for WrongStack. Provides a unified
+`/lsp` command to install, run, and manage LSP servers, plus 4 LSP-backed tools
+for the agent (diagnostics, definition, rename, codebase search).
 
-This package is implemented as a WrongStack monorepo plugin and reads its
-configuration from `extensions["@wrongstack/plug-lsp"]`.
+## Quick Start
+
+### 1. Enable the plugin
+
+Add to your WrongStack config (`~/.config/wrongstack/config.json` or project `.wrongstack/config.json`):
 
 ```json
 {
   "features": { "plugins": true },
-  "plugins": ["@wrongstack/plug-lsp"],
+  "plugins": ["@wrongstack/plug-lsp"]
+}
+```
+
+### 2. Install a language server
+
+```text
+/lsp install typescript
+/lsp install python
+/lsp install go
+```
+
+### 3. Add to config and start
+
+After installation, add the server to your config:
+
+```json
+{
   "extensions": {
     "@wrongstack/plug-lsp": {
-      "autoStart": "lazy",
       "servers": {
         "typescript": {
           "command": "typescript-language-server",
           "args": ["--stdio"],
           "languages": ["typescript", "typescriptreact", "javascript", "javascriptreact"],
-          "rootPatterns": ["tsconfig.json", "jsconfig.json", "package.json"]
+          "rootPatterns": ["tsconfig.json"]
+        }
+      }
+    }
+  }
+}
+```
+
+Then restart your WrongStack session and run:
+
+```text
+/lsp start typescript
+```
+
+## `/lsp` Command
+
+The primary interface for all LSP operations:
+
+| Command | Description |
+|---|---|
+| `/lsp` | List all configured servers and their states |
+| `/lsp list` | Same as `/lsp` |
+| `/lsp status` | Detailed status with failed server errors and active file count |
+| `/lsp install <lang>` | Install the LSP server for a language |
+| `/lsp start [name]` | Start all servers, or a specific one |
+| `/lsp stop [name]` | Stop all servers, or a specific one |
+| `/lsp restart [name]` | Restart all servers, or a specific one |
+| `/lsp diagnostics [file]` | Show diagnostics for a file or workspace |
+| `/lsp help` | Show full help |
+
+### Available Languages for `/lsp install`
+
+| Language | Server | Install Method |
+|---|---|---|
+| `typescript` | `typescript-language-server` | npm |
+| `python` | `pyright-langserver` | npm |
+| `json` | `vscode-json-language-server` | npm |
+| `html` | `vscode-html-language-server` | npm |
+| `css` | `vscode-css-language-server` | npm |
+| `yaml` | `yaml-language-server` | npm |
+| `shell` | `bash-language-server` | npm |
+| `go` | `gopls` | Go toolchain |
+| `rust` | `rust-analyzer` | Rust toolchain |
+| `ruby` | `ruby-lsp` | RubyGems |
+
+## Registered Tools
+
+The plugin registers 4 tools into WrongStack's tool system. These are kept because
+LSP provides genuinely unique data or capability the agent cannot replicate with
+basic tools (read, grep, edit) at comparable cost.
+
+| Tool | Permission | Description |
+|---|---|---|
+| `lsp_diagnostics` | `auto` | Get type/lint diagnostics for a file or whole workspace |
+| `lsp_definition` | `auto` | Jump to the definition of a symbol (more precise than grep) |
+| `lsp_rename` | `confirm` | Safe semantic rename across the workspace |
+| `codebase-lsp-search` | `auto` | Fast symbol search via WrongStack's index, with LSP fallback |
+
+The following LSP tools are intentionally excluded: `lsp_references` (returns
+positions the agent still has to read), `lsp_hover` (usually confirms what
+reading the definition already showed), `lsp_symbols` (a symbol tree is less
+useful than reading the file), and `lsp_code_actions` (high noise-to-signal in
+well-maintained codebases).
+
+**Positions use 1-based line numbers and 1-based UTF-8 byte columns** — matching
+WrongStack's grep tool convention, not LSP's 0-based UTF-16 code units.
+
+## Configuration Reference
+
+Full configuration options under `extensions["@wrongstack/plug-lsp"]`:
+
+```json
+{
+  "extensions": {
+    "@wrongstack/plug-lsp": {
+      "autoStart": "lazy",
+      "diagnosticsAfterEdit": "background",
+      "diagnosticsWaitMs": 1500,
+      "severityFilter": ["error", "warning"],
+      "maxDiagnosticsPerFile": 5,
+      "maxDiagnosticsTotal": 50,
+      "autoDiscover": true,
+      "logServerOutput": false,
+      "servers": {
+        "typescript": {
+          "command": "typescript-language-server",
+          "args": ["--stdio"],
+          "languages": ["typescript", "typescriptreact"],
+          "rootPatterns": ["tsconfig.json"],
+          "initializationOptions": {},
+          "settings": {},
+          "startupTimeoutMs": 15000,
+          "enabled": true
         }
       }
     }
@@ -25,36 +138,119 @@ configuration from `extensions["@wrongstack/plug-lsp"]`.
 }
 ```
 
-Registered tools:
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `autoStart` | `"lazy"` | `"lazy"` = start on first file access; `"eager"` = all at session start; `"never"` = manual only |
+| `diagnosticsAfterEdit` | `"background"` | `"background"` = fetch after edits; `"manual"` = on request only |
+| `diagnosticsWaitMs` | `1500` | Milliseconds to wait after an edit before fetching diagnostics |
+| `severityFilter` | `["error","warning"]` | Which diagnostic severities to return |
+| `maxDiagnosticsPerFile` | `5` | Maximum diagnostics per file |
+| `maxDiagnosticsTotal` | `50` | Maximum diagnostics total |
+| `autoDiscover` | `true` | Auto-discover servers on PATH or `node_modules/.bin` |
+| `logServerOutput` | `false` | Log server stderr to WrongStack log |
+
+## Auto-Discovery
+
+With `autoDiscover: true` (the default), the plugin searches for servers in:
+
+1. **`PATH`** — any command on the system PATH is used
+2. **`node_modules/.bin`** — npm-installed binaries in the project
+
+This means a minimal config is often sufficient:
+
+```json
+{
+  "features": { "plugins": true },
+  "plugins": ["@wrongstack/plug-lsp"]
+}
+```
+
+If `typescript-language-server` is in your project's `node_modules/.bin`, it is
+automatically discovered and started on first file access.
+
+## Server Lifecycle
 
-- `lsp_diagnostics`
-- `lsp_definition`
-- `lsp_references`
-- `lsp_hover`
-- `lsp_symbols`
-- `lsp_rename`
-- `lsp_code_actions`
+Each server runs as a separate child process communicating via JSON-RPC over stdio.
+The plugin handles:
 
-Plugin slash commands are namespaced by the current WrongStack command
-registry, for example `/@wrongstack/plug-lsp:list`.
+- **Initialization handshake** — sends `initialize` → waits for `InitializeResult` → sends `initialized`
+- **Document tracking** — sends `textDocument/didOpen` on first read, `textDocument/didChange` after edits
+- **Crash recovery** — 3 restart attempts with exponential backoff (1s, 4s, 16s)
+- **Graceful shutdown** — sends `shutdown` then `exit` on session end
 
-## Installing language servers
+States: `disabled` → `starting` → `initializing` → `ready` → `shutting_down` → `exited`
 
-The plugin is an LSP client. Language server binaries can be installed into the
-project instead of relying on global PATH state:
+## Custom Server Configuration
+
+For languages not in the preset list, add manually to your config:
+
+```json
+"servers": {
+  "myserver": {
+    "command": "my-language-server",
+    "args": ["--stdio"],
+    "languages": ["mylang"],
+    "rootPatterns": ["mylang.config"],
+    "startupTimeoutMs": 20000
+  }
+}
+```
+
+## CLI Setup Command
+
+For CI/CD or scripted installation, use the setup CLI directly:
 
 ```sh
-pnpm --filter @wrongstack/plug-lsp build
+# Install all preset servers (npm-based only)
 pnpm --filter @wrongstack/plug-lsp setup -- --cwd /path/to/project
+
+# Install specific servers
+pnpm --filter @wrongstack/plug-lsp setup -- --cwd . --languages typescript,python,go
+
+# Dry run
+pnpm --filter @wrongstack/plug-lsp setup -- --dry-run --languages typescript
 ```
 
-After setup, `autoDiscover` checks both PATH and project-local
-`node_modules/.bin`, so the same flow works on Windows, macOS, and Linux.
+## Troubleshooting
 
-Default setup installs npm-based servers for TypeScript/JavaScript, Python,
-JSON, HTML, CSS, YAML, and shell scripts. Extra toolchain-backed servers can be
-requested explicitly:
+**Server shows as "failed"**: Check the server binary is on PATH and starts correctly.
+Run `/lsp status` to see the error message from the server's stderr.
 
-```sh
-wrongstack-lsp-setup --languages typescript,python,go,rust,ruby
+**No diagnostics**: Open the file first (LSP servers report diagnostics for open files).
+Run `/lsp diagnostics <file>` after reading the file.
+
+**Wrong language detected**: Set the `languages` array explicitly in the server config
+to include the language ID for your file (e.g., `"python"` for Python files).
+
+## Architecture
+
+```
+packages/plug-lsp/src/
+├── slash-commands/
+│   ├── lsp.ts          — unified /lsp command dispatcher
+│   ├── install.ts       — language server installation logic
+│   ├── list/start/stop/restart/diagnostics.ts — individual commands
+├── server/
+│   ├── lsp-server.ts   — per-server LSP client (one process per server)
+│   ├── connection.ts    — JSON-RPC 2.0 over stdio transport
+│   └── lifecycle.ts     — state machine for server lifecycle
+├── tools/              — 4 LSP-backed agent tools (diagnostics, definition, rename, codebase-search)
+├── registry.ts         — manages all server instances
+├── document-tracker.ts — tracks open/edited files across sessions
+├── auto-discover.ts    — PATH and node_modules discovery
+└── presets.ts          — built-in server configurations
 ```
+
+## Plugin Command Names
+
+The plugin registers slash commands with the `@wrongstack/plug-lsp` namespace:
+
+- `/@wrongstack/plug-lsp:list`
+- `/@wrongstack/plug-lsp:start`
+- `/@wrongstack/plug-lsp:stop`
+- `/@wrongstack/plug-lsp:restart`
+- `/@wrongstack/plug-lsp:diagnostics`
+
+These are also available as the short form **`/lsp`**, **`/lsp list`**, etc.