AGENTS.md

1<!-- Parent: ../AGENTS.md -->
2<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
3 
4# lsp
5 
6Language Server Protocol (LSP) client implementation providing IDE-like code intelligence.
7 
8## Purpose
9 
10This directory implements the LSP client that enables agents to:
11- Connect to language servers (TypeScript, Python, Rust, Go, etc.)
12- Get type information, documentation, and signatures
13- Find definitions, references, and symbols
14- Perform refactoring operations (rename, code actions)
15- Collect diagnostics (errors, warnings)
16 
17## Key Files
18 
19| File | Description |
20|------|-------------|
21| `index.ts` | Module exports - re-exports client, servers, utils |
22| `client.ts` | `LspClient` class - JSON-RPC 2.0 over stdio communication |
23| `servers.ts` | `LSP_SERVERS` config - known language server definitions |
24| `utils.ts` | Formatting utilities for LSP responses |
25 
26## For AI Agents
27 
28### Working In This Directory
29 
30#### LSP Client Architecture
31 
32```
33┌─────────────────┐     JSON-RPC 2.0      ┌──────────────────┐
34│   LspClient     │◄────────────────────►│ Language Server  │
35│                 │       stdio           │ (tsserver, etc.) │
36│ - connect()     │                       │                  │
37│ - hover()       │                       │                  │
38│ - definition()  │                       │                  │
39│ - references()  │                       │                  │
40│ - diagnostics() │                       │                  │
41└─────────────────┘                       └──────────────────┘
42```
43 
44#### Client Manager
45 
46`lspClientManager` is a singleton that pools connections:
47 
48```typescript
49// Get client for a file (auto-selects appropriate server)
50const client = await lspClientManager.getClientForFile('src/index.ts');
51 
52// Client is reused for same workspace/server combo
53const key = `${workspaceRoot}:${serverConfig.command}`;
54```
55 
56#### Server Configuration
57 
58Each server in `LSP_SERVERS` has:
59```typescript
60interface LspServerConfig {
61  name: string;           // Human-readable name
62  command: string;        // Executable command
63  args: string[];         // Command arguments
64  extensions: string[];   // File extensions handled
65  installHint: string;    // Installation instructions
66}
67```
68 
69### Common Patterns
70 
71**Request/Response:**
72```typescript
73// All requests use JSON-RPC 2.0 format
74const request = {
75  jsonrpc: '2.0',
76  id: this.requestId++,
77  method: 'textDocument/hover',
78  params: { textDocument: { uri }, position: { line, character } }
79};
80 
81// Wrapped in Content-Length header
82const message = `Content-Length: ${content.length}\r\n\r\n${content}`;
83```
84 
85**Notification handling:**
86```typescript
87// Server pushes diagnostics via notifications
88if (notification.method === 'textDocument/publishDiagnostics') {
89  this.diagnostics.set(params.uri, params.diagnostics);
90}
91```
92 
93### Testing Requirements
94 
95LSP tests require language servers to be installed:
96```bash
97# Install TypeScript server
98npm i -g typescript-language-server typescript
99 
100# Run tests
101npm test -- --grep &quot;lsp&quot;
102```
103 
104## Dependencies
105 
106### Internal
107- None
108 
109### External
110| Package | Purpose |
111|---------|---------|
112| `vscode-languageserver-protocol` | LSP type definitions |
113| `child_process` | Spawning language servers |
114| `fs`, `path` | File operations |
115 
116## Supported Language Servers
117 
118This table documents catalog/discovery support. Runtime semantic quality still depends on installing and correctly configuring the underlying language server.
119 
120| Language | Server | Command | Extensions |
121|----------|--------|---------|------------|
122| TypeScript/JS | typescript-language-server | `typescript-language-server` | .ts, .tsx, .js, .jsx |
123| Python | ty | `ty server` | .py, .pyw |
124| Rust | rust-analyzer | `rust-analyzer` | .rs |
125| Go | gopls | `gopls` | .go |
126| C/C++ | clangd | `clangd` | .c, .h, .cpp, .cc, .hpp |
127| Java | jdtls | `jdtls` | .java |
128| JSON | vscode-json-language-server | `vscode-json-language-server` | .json, .jsonc |
129| HTML | vscode-html-language-server | `vscode-html-language-server` | .html, .htm |
130| CSS | vscode-css-language-server | `vscode-css-language-server` | .css, .scss, .less |
131| Vue | vue-language-server | `vue-language-server --stdio` | .vue |
132| YAML | yaml-language-server | `yaml-language-server` | .yaml, .yml |
133 
134<!-- MANUAL: -->
135