@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/core/lsp/client.js

@@ -0,0 +1,1229 @@
+/**
+ * LSP client wrapper — Phase 1 (LSP tool + worktree + apply_patch).
+ *
+ * Wraps a Language Server Protocol server process (started locally via
+ * stdio) behind a small async surface used by the LSP tools:
+ *
+ *  - hover(file, line, col)
+ *  - definition(file, line, col)
+ *  - references(file, line, col)
+ *  - diagnostics(file)
+ *
+ * Why no `vscode-languageserver-protocol` dep:
+ *
+ *  The + posture for `apps/pugi-cli` keeps the dep tree intentionally
+ *  lean (zod, ink, react, undici, tar — that's most of it). Pulling
+ *  `vscode-languageserver-protocol` + transitive `vscode-jsonrpc` for
+ *  four operations would expand the install footprint disproportionately.
+ *  The LSP framing protocol (Content-Length headers + JSON-RPC bodies)
+ *  is documented in the LSP spec §3 and stable since 2017; we implement
+ *  the framer ourselves in ~80 LOC. Pulling in the official packages
+ *  later (when we add 20+ operations) stays an open option — every
+ *  public surface here mirrors the official type names so a future swap
+ *  is mechanical.
+ *
+ * Why we spawn `npx <server>` for stock languages:
+ *
+ *  - typescript-language-server: `npx typescript-language-server --stdio`
+ *  - pyright: `pyright-langserver --stdio` (operator-installed)
+ *  - gopls: `gopls` (operator-installed via `go install`)
+ *  - rust-analyzer: `rust-analyzer` (operator-installed via `rustup`)
+ *
+ *  `npx typescript-language-server` resolves the binary from the
+ *  workspace's `node_modules/.bin` first, then falls back to the global
+ *  npm cache. The other servers are operator-installed system binaries
+ *  (we run `which <name>` once at start and fail loud with
+ *  `lsp_unavailable` if absent — see `detectServer` below). This keeps
+ *  `pugi` install-time zero-deps for non-TS workspaces.
+ *
+ * Lifecycle contract:
+ *
+ *  1. `startLspClient(lang, opts)` spawns the server, performs the LSP
+ *     `initialize` handshake, sends `initialized`, and returns a client.
+ *  2. Each operation auto-opens the target file via `textDocument/didOpen`
+ *     on first touch (we keep a `Set<string>` of opened URIs). Files are
+ *     never closed mid-session — the server is per-CLI-invocation and
+ *     the process exit cleans up.
+ *  3. `stop()` sends `shutdown` + `exit` (best-effort) and SIGKILLs the
+ *     child after a 1s grace window so the CLI never hangs on a
+ *     misbehaving server.
+ *
+ * Cancellation: every async operation accepts an optional CancellationToken
+ * . On abort, we send LSP `$/cancelRequest` for the in-flight ID and
+ * reject the promise with `OperatorAbortedError`.
+ *
+ * Privacy: requests stay client-side. There is no Anvil round-trip; the
+ * server process reads ONLY the files the operator's code actually opens.
+ * The `pugi privacy airgapped` mode does not need to gate this surface
+ * because the LSP server is local; we still honor the mode by skipping
+ * the optional update-check banner inside the CLI command surface.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { OperatorAbortedError } from '../../tools/file-tools.js';
+const LANGUAGE_SERVERS = {
+    ts: {
+        command: 'npx',
+        args: ['--yes', 'typescript-language-server', '--stdio'],
+        languageId: 'typescript',
+        probe: 'npx',
+    },
+    js: {
+        command: 'npx',
+        args: ['--yes', 'typescript-language-server', '--stdio'],
+        languageId: 'javascript',
+        probe: 'npx',
+    },
+    py: {
+        command: 'pyright-langserver',
+        args: ['--stdio'],
+        languageId: 'python',
+        probe: 'pyright-langserver',
+    },
+    go: {
+        command: 'gopls',
+        args: [],
+        languageId: 'go',
+        probe: 'gopls',
+    },
+    rust: {
+        command: 'rust-analyzer',
+        args: [],
+        languageId: 'rust',
+        probe: 'rust-analyzer',
+    },
+};
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+/**
+ * Returned by `startLspClient`. Methods are async; every method honors
+ * the optional `CancellationToken` parameter.
+ */
+export class LspClient {
+    cwd;
+    child;
+    server;
+    openedFiles = new Set();
+    pending = new Map();
+    diagnosticsByUri = new Map();
+    requestTimeoutMs;
+    nextId = 1;
+    buffer = Buffer.alloc(0);
+    stopped = false;
+    constructor(child, server, opts) {
+        this.child = child;
+        this.server = server;
+        this.cwd = opts.cwd;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        child.stdout.on('data', (chunk) => this.onStdout(chunk));
+        // Stderr is the server's diagnostic channel; we swallow it so a
+        // chatty server (e.g. tsserver `debug:` lines) does not leak into
+        // the operator-facing CLI stream. Operators can re-run with
+        // `PUGI_LSP_DEBUG=1` to surface stderr.
+        if (process.env.PUGI_LSP_DEBUG === '1') {
+            child.stderr.on('data', (chunk) => process.stderr.write(chunk));
+        }
+        else {
+            child.stderr.on('data', () => { });
+        }
+        child.on('exit', () => this.onExit());
+        // R1 fix (2026-05-26, PR r1, P2 #11): mirror onExit for the
+        // 'error' event. A late-fired spawn error (EIO, ENOMEM, etc.) or
+        // any unhandled child-process error would otherwise leave
+        // in-flight pending requests dangling until their per-request
+        // timer fired, which can be up to `requestTimeoutMs` later.
+        // Failing fast here matches the exit-time semantics.
+        child.on('error', () => this.onExit());
+    }
+    /**
+     * Send `shutdown` + `exit`, then SIGKILL after a 1s grace window so
+     * a hung server never blocks CLI termination. Idempotent.
+     */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        try {
+            await this.sendRequest('shutdown', null, undefined);
+            this.sendNotification('exit', null);
+        }
+        catch {
+            // Best-effort. A server that ignored shutdown gets the SIGKILL
+            // path below.
+        }
+        const killTimer = setTimeout(() => {
+            try {
+                this.child.kill('SIGKILL');
+            }
+            catch {
+                // already exited
+            }
+        }, 1_000);
+        killTimer.unref();
+        // Reject any in-flight requests so callers do not hang on the
+        // shutdown path. We drain the map first to avoid the reject
+        // callback re-entering and mutating the map mid-iteration.
+        const snapshot = Array.from(this.pending.entries());
+        this.pending.clear();
+        for (const [, entry] of snapshot) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error('lsp_stopped'));
+        }
+    }
+    async hover(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/hover', {
+                textDocument: { uri },
+                position: pos,
+            }, token);
+            if (raw === null || raw === undefined)
+                return { ok: true, value: null };
+            const value = normalizeHover(raw);
+            return { ok: true, value };
+        });
+    }
+    async definition(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/definition', {
+                textDocument: { uri },
+                position: pos,
+            }, token);
+            const locations = normalizeLocations(raw, this.cwd);
+            return { ok: true, value: locations };
+        });
+    }
+    async references(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/references', {
+                textDocument: { uri },
+                position: pos,
+                context: { includeDeclaration: true },
+            }, token);
+            const locations = normalizeLocations(raw, this.cwd);
+            return { ok: true, value: locations };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: document outline. Returns the LSP raw shape (either
+     * `DocumentSymbol[]` hierarchical or `SymbolInformation[]` flat); the
+     * symbol-tools layer normalizes both to the agent-facing flat form.
+     */
+    async documentSymbols(file, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/documentSymbol', { textDocument: { uri } }, token);
+            if (!Array.isArray(raw))
+                return { ok: true, value: [] };
+            return { ok: true, value: raw };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: workspace-wide symbol fuzzy search. The query is
+     * server-defined (substring / fuzzy / prefix); we forward verbatim.
+     * Files outside the workspace are kept as raw URIs — the symbol-tools
+     * layer surfaces them to the operator as-is.
+     */
+    async workspaceSymbols(query, token) {
+        // workspace/symbol does not need a document open, but we still
+        // honor the cancellation token. We call sendRequest directly via
+        // the typed internal accessor used by the handshake.
+        try {
+            const internal = this;
+            const raw = await internal.sendRequest('workspace/symbol', { query }, token);
+            if (!Array.isArray(raw))
+                return { ok: true, value: [] };
+            return { ok: true, value: raw };
+        }
+        catch (error) {
+            if (error instanceof OperatorAbortedError) {
+                return { ok: false, reason: 'operator_aborted', detail: error.message };
+            }
+            if (error instanceof Error && error.message === 'request_timeout') {
+                return { ok: false, reason: 'request_timeout', detail: 'workspace/symbol timed out' };
+            }
+            return {
+                ok: false,
+                reason: 'lsp_error',
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * PUGI-78 Phase 1: implementations of an interface / abstract method.
+     * LSP `textDocument/implementation` returns the same `Location[]` shape
+     * as `definition`, so we re-use `normalizeLocations`.
+     */
+    async implementations(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/implementation', { textDocument: { uri }, position: pos }, token);
+            const locations = normalizeLocations(raw, this.cwd);
+            return { ok: true, value: locations };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: type-definition (vs value-definition). Same wire
+     * shape as `definition` — server reports the location of the symbol's
+     * type declaration, not its instantiation site.
+     */
+    async typeDefinition(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/typeDefinition', { textDocument: { uri }, position: pos }, token);
+            const locations = normalizeLocations(raw, this.cwd);
+            return { ok: true, value: locations };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: signature help at a call site. Returns the active
+     * overload's label, parameters, and active-parameter index. Null when
+     * the server reports no signature (cursor is not inside a call).
+     */
+    async signatureHelp(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/signatureHelp', { textDocument: { uri }, position: pos }, token);
+            return { ok: true, value: normalizeSignatureHelp(raw) };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: prepare a rename. Returns the range LSP says the
+     * symbol occupies; the dispatcher uses this to confirm the cursor is
+     * actually on a renameable token before issuing the full rename.
+     */
+    async prepareRename(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            try {
+                const raw = await this.sendRequest('textDocument/prepareRename', { textDocument: { uri }, position: pos }, token);
+                if (!raw)
+                    return { ok: true, value: null };
+                // LSP allows { range, placeholder } OR a raw Range; surface
+                // either as a flat Range.
+                if (typeof raw === 'object' && raw && 'start' in raw && 'end' in raw) {
+                    const range = parseRange(raw);
+                    return { ok: true, value: range ?? null };
+                }
+                if (typeof raw === 'object' && raw && 'range' in raw) {
+                    const range = parseRange(raw.range);
+                    return { ok: true, value: range ?? null };
+                }
+                return { ok: true, value: null };
+            }
+            catch (error) {
+                // Some servers (pyright pre-1.1) lack prepareRename support and
+                // return a JSON-RPC error. The dispatcher should still be able
+                // to attempt the rename — surface null instead of bubbling the
+                // failure as the agent surface treats null as "skip prepare".
+                if (error instanceof Error && /method not (found|supported)/i.test(error.message)) {
+                    return { ok: true, value: null };
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: atomic rename refactor. Returns the workspace edit
+     * the server proposes; the dispatcher previews + applies in a future
+     * ticket (Phase 2). For Phase 1 the agent surface lists affected files
+     * + line:character of each edit so the model can summarize the impact.
+     */
+    async rename(file, pos, newName, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/rename', { textDocument: { uri }, position: pos, newName }, token);
+            return { ok: true, value: normalizeWorkspaceEdit(raw, this.cwd) };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: quick-fix list at a range. The server returns either
+     * `Command[]` (legacy) or `CodeAction[]` (modern); we normalize to the
+     * union shape so the surface stays stable.
+     */
+    async codeActions(file, range, token) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/codeAction', {
+                textDocument: { uri },
+                range,
+                context: { diagnostics: [] },
+            }, token);
+            return { ok: true, value: normalizeCodeActions(raw) };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: formatter. Returns the text edits the server would
+     * apply for `textDocument/formatting`. The dispatcher composes them
+     * into a single rewrite in a future ticket; Phase 1 surfaces the edits
+     * for inspection.
+     */
+    async formatting(file, token, options) {
+        return this.withDocument(file, async (uri) => {
+            const raw = await this.sendRequest('textDocument/formatting', {
+                textDocument: { uri },
+                options: {
+                    tabSize: options?.tabSize ?? 2,
+                    insertSpaces: options?.insertSpaces ?? true,
+                },
+            }, token);
+            return { ok: true, value: normalizeTextEdits(raw) };
+        });
+    }
+    /**
+     * PUGI-78 Phase 1: call hierarchy at a symbol position. The LSP wire
+     * is a two-step protocol — first `prepareCallHierarchy` to get the
+     * item handle, then `incomingCalls` and `outgoingCalls`. We surface
+     * both edges in a single call.
+     */
+    async callHierarchy(file, pos, token) {
+        return this.withDocument(file, async (uri) => {
+            const prepared = await this.sendRequest('textDocument/prepareCallHierarchy', { textDocument: { uri }, position: pos }, token);
+            if (!Array.isArray(prepared) || prepared.length === 0) {
+                return { ok: true, value: { incoming: [], outgoing: [] } };
+            }
+            const item = prepared[0];
+            const incomingRaw = await this.sendRequest('callHierarchy/incomingCalls', { item }, token);
+            const outgoingRaw = await this.sendRequest('callHierarchy/outgoingCalls', { item }, token);
+            return {
+                ok: true,
+                value: {
+                    incoming: normalizeCallHierarchyEdges(incomingRaw, 'from', this.cwd),
+                    outgoing: normalizeCallHierarchyEdges(outgoingRaw, 'to', this.cwd),
+                },
+            };
+        });
+    }
+    /**
+     * Diagnostics in LSP arrive as PUSH (`textDocument/publishDiagnostics`)
+     * not pull. We open the document, wait one short tick for the server
+     * to drain its first analysis pass, and return what is cached.
+     * Servers that emit diagnostics asynchronously (gopls, rust-analyzer)
+     * may take longer; the caller can extend `requestTimeoutMs` to allow
+     * for the cold start.
+     */
+    async diagnostics(file, token) {
+        return this.withDocument(file, async (uri) => {
+            // Give the server one analysis cycle before reading the cache.
+            // 200ms is enough for a warm tsserver; a cold server returns the
+            // empty array and the caller can re-poll.
+            await new Promise((res) => {
+                const wait = setTimeout(res, 200);
+                wait.unref();
+                if (token) {
+                    token.onAbort(() => {
+                        clearTimeout(wait);
+                        res();
+                    });
+                }
+            });
+            if (token && token.isAborted) {
+                return { ok: false, reason: 'operator_aborted', detail: 'lspDiagnostics aborted' };
+            }
+            const cached = this.diagnosticsByUri.get(uri) ?? [];
+            return { ok: true, value: cached };
+        });
+    }
+    /**
+     * Ensure the file is open server-side, then run `op`. The first call
+     * for a path sends `textDocument/didOpen` with the on-disk content;
+     * subsequent calls skip the open.
+     */
+    async withDocument(file, op) {
+        let absPath;
+        try {
+            absPath = resolve(this.cwd, file);
+            if (!absPath.startsWith(this.cwd + sep) && absPath !== this.cwd) {
+                return {
+                    ok: false,
+                    reason: 'lsp_error',
+                    detail: `path escapes workspace: ${file}`,
+                };
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: 'lsp_error',
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+        // R1 fix (2026-05-26, PR r1, Fix 8): realpath containment.
+        // Without this gate, a workspace-local symlink (e.g. `alias` ->
+        // `/etc/passwd`) passed the lexical `absPath.startsWith(cwd)`
+        // check, then `readFileSync(absPath, 'utf8')` happily followed the
+        // symlink and shipped `/etc/passwd` into the LSP `textDocument/didOpen`
+        // payload. Parity with `applySecurityGate`'s symlink-escape rule:
+        // when the file exists, the realpath MUST stay inside the workspace
+        // realpath. Missing files (newly-typed paths the operator is
+        // querying) skip the check — there's no symlink target to escape.
+        if (existsSync(absPath)) {
+            try {
+                const realRoot = realpathSync.native(this.cwd);
+                const realTarget = realpathSync.native(absPath);
+                if (realTarget !== realRoot && !realTarget.startsWith(realRoot + sep)) {
+                    return {
+                        ok: false,
+                        reason: 'lsp_error',
+                        detail: `symlink escapes workspace: ${file} -> ${realTarget}`,
+                    };
+                }
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    reason: 'lsp_error',
+                    detail: `cannot realpath ${file}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+        const uri = pathToFileURL(absPath).toString();
+        if (!this.openedFiles.has(uri)) {
+            try {
+                const text = readFileSync(absPath, 'utf8');
+                this.sendNotification('textDocument/didOpen', {
+                    textDocument: {
+                        uri,
+                        languageId: this.server.languageId,
+                        version: 1,
+                        text,
+                    },
+                });
+                this.openedFiles.add(uri);
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    reason: 'lsp_error',
+                    detail: `cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+        try {
+            return await op(uri);
+        }
+        catch (error) {
+            if (error instanceof OperatorAbortedError) {
+                return { ok: false, reason: 'operator_aborted', detail: error.message };
+            }
+            if (error instanceof Error && error.message === 'request_timeout') {
+                return { ok: false, reason: 'request_timeout', detail: 'lsp request timed out' };
+            }
+            return {
+                ok: false,
+                reason: 'lsp_error',
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    sendRequest(method, params, token) {
+        const id = this.nextId++;
+        const payload = { jsonrpc: '2.0', id, method, params };
+        return new Promise((resolveFn, rejectFn) => {
+            const timer = setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    rejectFn(new Error('request_timeout'));
+                }
+            }, this.requestTimeoutMs);
+            timer.unref();
+            this.pending.set(id, { resolve: resolveFn, reject: rejectFn, timer });
+            if (token) {
+                token.onAbort(() => {
+                    if (this.pending.has(id)) {
+                        this.pending.delete(id);
+                        clearTimeout(timer);
+                        // Best-effort cancel notification to the server. Some
+                        // servers ignore $/cancelRequest; the local reject below
+                        // is what frees the caller.
+                        try {
+                            this.sendNotification('$/cancelRequest', { id });
+                        }
+                        catch {
+                            // server may already be gone
+                        }
+                        rejectFn(new OperatorAbortedError('lsp_request'));
+                    }
+                });
+            }
+            try {
+                this.writeMessage(payload);
+            }
+            catch (error) {
+                this.pending.delete(id);
+                clearTimeout(timer);
+                rejectFn(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    sendNotification(method, params) {
+        this.writeMessage({ jsonrpc: '2.0', method, params });
+    }
+    writeMessage(payload) {
+        const body = JSON.stringify(payload);
+        const message = `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`;
+        this.child.stdin.write(message, 'utf8');
+    }
+    onStdout(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        while (true) {
+            const headerEnd = this.buffer.indexOf('\r\n\r\n');
+            if (headerEnd < 0)
+                return;
+            const headerText = this.buffer.subarray(0, headerEnd).toString('ascii');
+            const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
+            if (!lengthMatch || lengthMatch[1] === undefined) {
+                // R1 fix (2026-05-26, PR r1, Fix 7): malformed header —
+                // instead of nuking the entire buffer (which would discard ANY
+                // subsequent valid messages already queued in `this.buffer`),
+                // scan forward for the next `Content-Length:` marker and resync
+                // from there. A misbehaving server that emits one bad header
+                // followed by a normal stream of responses must not freeze the
+                // client. When no recoverable next marker is in the buffer, we
+                // keep the buffer as-is and wait for more data — the broken
+                // bytes will be re-evaluated on the next chunk.
+                const nextHeaderIdx = this.buffer.indexOf(Buffer.from('Content-Length:'), 1);
+                if (nextHeaderIdx > 0) {
+                    this.buffer = this.buffer.subarray(nextHeaderIdx);
+                    continue;
+                }
+                // No next marker visible — wait for more data, do not nuke the
+                // buffer. A subsequent chunk may complete a valid header.
+                return;
+            }
+            const length = Number.parseInt(lengthMatch[1], 10);
+            const bodyStart = headerEnd + 4;
+            if (this.buffer.length < bodyStart + length)
+                return;
+            const bodyText = this.buffer.subarray(bodyStart, bodyStart + length).toString('utf8');
+            this.buffer = this.buffer.subarray(bodyStart + length);
+            try {
+                const message = JSON.parse(bodyText);
+                this.handleMessage(message);
+            }
+            catch {
+                // Garbage body — drop and continue parsing the next message.
+            }
+        }
+    }
+    handleMessage(message) {
+        // Response — has `id` and either `result` or `error`.
+        if (typeof message['id'] === 'number') {
+            const id = message['id'];
+            const entry = this.pending.get(id);
+            if (!entry)
+                return;
+            this.pending.delete(id);
+            clearTimeout(entry.timer);
+            if ('error' in message && message['error']) {
+                const err = message['error'];
+                entry.reject(new Error(`lsp_error code=${err.code ?? 'unknown'}: ${err.message ?? 'no message'}`));
+                return;
+            }
+            entry.resolve(message['result'] ?? null);
+            return;
+        }
+        // Notification from server.
+        if (message['method'] === 'textDocument/publishDiagnostics') {
+            const params = message['params'];
+            if (!params)
+                return;
+            const uri = typeof params.uri === 'string' ? params.uri : null;
+            if (!uri)
+                return;
+            const raw = Array.isArray(params.diagnostics) ? params.diagnostics : [];
+            const normalized = [];
+            for (const item of raw) {
+                const parsed = normalizeDiagnostic(item);
+                if (parsed)
+                    normalized.push(parsed);
+            }
+            this.diagnosticsByUri.set(uri, normalized);
+        }
+    }
+    onExit() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        const snapshot = Array.from(this.pending.entries());
+        this.pending.clear();
+        for (const [, entry] of snapshot) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error('lsp_server_exited'));
+        }
+    }
+}
+/**
+ * Map a short LSP language slug to the settings.json key. β7 L9 — the
+ * settings schema spells out the full language name (`typescript`,
+ * `python`, ...) for human readability; the short slug (`ts`, `py`) is
+ * what every internal call site uses. Keep this map narrow and explicit.
+ */
+const SETTINGS_KEY_BY_LANG = {
+    ts: 'typescript',
+    js: 'javascript',
+    py: 'python',
+    go: 'go',
+    rust: 'rust',
+};
+/**
+ * Report whether the operator has explicitly disabled this language via
+ * `.pugi/settings.json::lsp.<language> = false`. Absent section or
+ * absent key means "enabled by default" — backwards-compatible with the
+ * surface that ignored settings entirely. Returns true ONLY when
+ * the operator explicitly set the value to false.
+ */
+export function isLspLanguageDisabled(lang, lspSettings) {
+    if (!lspSettings)
+        return false;
+    const key = SETTINGS_KEY_BY_LANG[lang];
+    return lspSettings[key] === false;
+}
+/**
+ * Probe every registered language server. Operator-facing helper for
+ * `pugi lsp servers` — returns one row per language with the binary
+ * name, whether it was found on PATH, and whether the settings toggle
+ * has explicitly disabled it.
+ */
+export function inspectLspServers(lspSettings) {
+    const out = [];
+    for (const lang of Object.keys(LANGUAGE_SERVERS)) {
+        const server = LANGUAGE_SERVERS[lang];
+        out.push({
+            language: lang,
+            command: server.command + (server.args.length > 0 ? ` ${server.args.join(' ')}` : ''),
+            available: detectBinary(server.probe),
+            enabled: !isLspLanguageDisabled(lang, lspSettings),
+        });
+    }
+    return out;
+}
+/**
+ * Start an LSP client for the given language. Returns either an `LspClient`
+ * ready to use, or a structured failure (`lsp_unavailable`,
+ * `language_unsupported`).
+ *
+ * β7 L9: respects `.pugi/settings.json::lsp.<language> = false` —
+ * a disabled language reports `lsp_disabled` so the caller surface can
+ * tell the operator the binary IS available but settings says no.
+ */
+export async function startLspClient(lang, opts) {
+    const server = opts.serverOverride ?? LANGUAGE_SERVERS[lang];
+    if (!server) {
+        return {
+            ok: false,
+            reason: 'language_unsupported',
+            detail: `no LSP server registered for language: ${lang}`,
+        };
+    }
+    if (!opts.serverOverride && isLspLanguageDisabled(lang, opts.lspSettings)) {
+        return {
+            ok: false,
+            reason: 'lsp_disabled',
+            detail: `${lang} is disabled in .pugi/settings.json::lsp.${SETTINGS_KEY_BY_LANG[lang]}. ` +
+                `Remove the override (or set it to true) to enable.`,
+        };
+    }
+    if (!opts.serverOverride) {
+        const available = detectBinary(server.probe);
+        if (!available) {
+            return {
+                ok: false,
+                reason: 'lsp_unavailable',
+                detail: `${server.probe} not found on PATH. ` +
+                    `Install the language server first ` +
+                    `(see https://pugi.io/docs/cli/lsp for per-language commands).`,
+            };
+        }
+    }
+    let child;
+    try {
+        child = spawn(server.command, [...server.args], {
+            cwd: opts.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: 'lsp_unavailable',
+            detail: `failed to spawn ${server.command}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // `child_process.spawn` reports a missing binary asynchronously via
+    // the 'error' event, NOT via a synchronous throw — the synchronous
+    // spawn returns a ChildProcess object even when the binary does not
+    // exist. Attach an error listener immediately so the missing-binary
+    // case never becomes an uncaught exception. Wait one microtask tick
+    // for the event-loop to fire the 'error' event before we attempt
+    // the handshake; if the spawn failed, return early with
+    // `lsp_unavailable`.
+    let spawnError = null;
+    child.on('error', (err) => {
+        spawnError = err;
+    });
+    // Yield one tick so Node's spawn-error path lands before we
+    // proceed. The error event lives on the same nextTick queue as the
+    // initial spawn handshake, so a single setImmediate-equivalent
+    // delay is enough to observe it.
+    await new Promise((resolveFn) => {
+        setImmediate(resolveFn);
+    });
+    if (spawnError) {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            // ignore — process never started
+        }
+        return {
+            ok: false,
+            reason: 'lsp_unavailable',
+            detail: `failed to spawn ${server.command}: ${spawnError.message}`,
+        };
+    }
+    const client = new LspClient(child, server, opts);
+    try {
+        await initializeHandshake(client, opts.cwd);
+    }
+    catch (error) {
+        await client.stop();
+        if (spawnError) {
+            return {
+                ok: false,
+                reason: 'lsp_unavailable',
+                detail: `failed to spawn ${server.command}: ${spawnError.message}`,
+            };
+        }
+        return {
+            ok: false,
+            reason: 'lsp_error',
+            detail: `initialize failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { ok: true, value: client };
+}
+async function initializeHandshake(client, cwd) {
+    const rootUri = pathToFileURL(cwd).toString();
+    // Reach the private send-request / send-notification surface through
+    // a typed accessor cast. The two methods are intentionally not part
+    // of the public class surface (callers should use `hover`/`definition`
+    // etc.), but the handshake is a single-shot bootstrap and exposing
+    // the raw methods would weaken the type story.
+    const internal = client;
+    await internal.sendRequest('initialize', {
+        processId: process.pid,
+        rootUri,
+        capabilities: {
+            textDocument: {
+                hover: { contentFormat: ['plaintext', 'markdown'] },
+                definition: { linkSupport: false },
+                references: {},
+                publishDiagnostics: { relatedInformation: false },
+                // PUGI-78 Phase 1: full 13-tool symbol surface. Each block
+                // mirrors the LSP §3.17 dynamic capability advertisement so
+                // the server enables the corresponding feature (e.g. pyright
+                // gates `workspace/symbol` on this flag). `dynamicRegistration`
+                // stays false for every entry — we never register a capability
+                // post-initialize; the static block is the only handshake.
+                documentSymbol: {
+                    hierarchicalDocumentSymbolSupport: true,
+                    symbolKind: { valueSet: Array.from({ length: 26 }, (_, i) => i + 1) },
+                },
+                signatureHelp: { signatureInformation: { documentationFormat: ['plaintext', 'markdown'] } },
+                implementation: { linkSupport: false },
+                typeDefinition: { linkSupport: false },
+                rename: { prepareSupport: true },
+                codeAction: { codeActionLiteralSupport: { codeActionKind: { valueSet: ['', 'quickfix', 'refactor', 'source'] } } },
+                formatting: {},
+                callHierarchy: {},
+            },
+            workspace: {
+                symbol: { symbolKind: { valueSet: Array.from({ length: 26 }, (_, i) => i + 1) } },
+                workspaceEdit: { documentChanges: true },
+            },
+        },
+        workspaceFolders: [{ uri: rootUri, name: 'pugi-workspace' }],
+    }, undefined);
+    internal.sendNotification('initialized', {});
+}
+function detectBinary(name) {
+    // Cross-platform `which` — spawnSync of the binary with --version is
+    // too aggressive (some servers don't honor --version). Use `which`
+    // on POSIX and `where` on Windows. Failures are non-fatal — we just
+    // report unavailable.
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const result = spawnSync(probe, [name], { stdio: 'ignore' });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeHover(raw) {
+    // LSP `Hover.contents` can be:
+    //  - string
+    //  - { kind: 'markdown' | 'plaintext', value: string }
+    //  - Array<string | { language: string, value: string }>
+    if (!raw || typeof raw !== 'object') {
+        return { content: String(raw ?? ''), raw };
+    }
+    const obj = raw;
+    const range = parseRange(obj.range);
+    const body = obj.contents;
+    const result = (() => {
+        if (typeof body === 'string')
+            return { content: body, raw, ...(range ? { range } : {}) };
+        if (Array.isArray(body)) {
+            const parts = [];
+            for (const item of body) {
+                if (typeof item === 'string')
+                    parts.push(item);
+                else if (item && typeof item === 'object' && 'value' in item) {
+                    const value = item.value;
+                    if (typeof value === 'string')
+                        parts.push(value);
+                }
+            }
+            return { content: parts.join('\n'), raw, ...(range ? { range } : {}) };
+        }
+        if (body && typeof body === 'object' && 'value' in body) {
+            const value = body.value;
+            return { content: typeof value === 'string' ? value : '', raw, ...(range ? { range } : {}) };
+        }
+        return { content: '', raw, ...(range ? { range } : {}) };
+    })();
+    return result;
+}
+function normalizeLocations(raw, cwd) {
+    if (!raw)
+        return [];
+    const items = Array.isArray(raw) ? raw : [raw];
+    const out = [];
+    for (const item of items) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const uri = typeof obj.uri === 'string' ? obj.uri : typeof obj.targetUri === 'string' ? obj.targetUri : null;
+        const range = parseRange(obj.range ?? obj.targetRange);
+        if (!uri || !range)
+            continue;
+        let path = '';
+        try {
+            const url = new URL(uri);
+            if (url.protocol === 'file:') {
+                const abs = decodeURIComponent(url.pathname);
+                if (abs.startsWith(cwd + sep) || abs === cwd) {
+                    path = abs.slice(cwd.length + 1);
+                }
+            }
+        }
+        catch {
+            path = '';
+        }
+        out.push({ uri, path, range });
+    }
+    return out;
+}
+function parseRange(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const obj = raw;
+    const start = parsePosition(obj.start);
+    const end = parsePosition(obj.end);
+    if (!start || !end)
+        return undefined;
+    return { start, end };
+}
+function parsePosition(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const obj = raw;
+    if (typeof obj.line !== 'number' || typeof obj.character !== 'number')
+        return undefined;
+    return { line: obj.line, character: obj.character };
+}
+function normalizeDiagnostic(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const range = parseRange(obj.range);
+    if (!range)
+        return null;
+    if (typeof obj.message !== 'string')
+        return null;
+    const severityRaw = typeof obj.severity === 'number' ? obj.severity : 1;
+    const severity = (severityRaw >= 1 && severityRaw <= 4 ? severityRaw : 1);
+    const labels = {
+        1: 'error',
+        2: 'warning',
+        3: 'info',
+        4: 'hint',
+    };
+    const out = {
+        severity,
+        severityLabel: labels[severity],
+        message: obj.message,
+        range,
+        ...(typeof obj.source === 'string' ? { source: obj.source } : {}),
+        ...(typeof obj.code === 'string' || typeof obj.code === 'number' ? { code: obj.code } : {}),
+    };
+    return out;
+}
+/**
+ * PUGI-78 Phase 1: collapse a `textDocument/signatureHelp` response to
+ * one active overload. LSP returns `{ signatures, activeSignature,
+ * activeParameter }`; we surface the active overload's label, params,
+ * and the active-param index. Returns null when the server reports no
+ * signatures (cursor not at a call site).
+ */
+function normalizeSignatureHelp(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    if (!Array.isArray(obj.signatures) || obj.signatures.length === 0)
+        return null;
+    const idx = typeof obj.activeSignature === 'number' && obj.activeSignature >= 0
+        ? Math.min(obj.activeSignature, obj.signatures.length - 1)
+        : 0;
+    const sig = obj.signatures[idx];
+    if (!sig || typeof sig !== 'object')
+        return null;
+    const sigObj = sig;
+    if (typeof sigObj.label !== 'string')
+        return null;
+    const params = [];
+    if (Array.isArray(sigObj.parameters)) {
+        for (const p of sigObj.parameters) {
+            if (!p || typeof p !== 'object')
+                continue;
+            const po = p;
+            // LSP allows `label` as string OR [start,end] tuple of offsets;
+            // we surface the string form, and for tuple form we slice the
+            // signature label.
+            let label = '';
+            if (typeof po.label === 'string')
+                label = po.label;
+            else if (Array.isArray(po.label) && po.label.length === 2 && typeof po.label[0] === 'number' && typeof po.label[1] === 'number') {
+                label = sigObj.label.slice(po.label[0], po.label[1]);
+            }
+            if (!label)
+                continue;
+            const doc = extractMarkupString(po.documentation);
+            params.push({ label, ...(doc ? { documentation: doc } : {}) });
+        }
+    }
+    const docTop = extractMarkupString(sigObj.documentation);
+    const out = {
+        label: sigObj.label,
+        parameters: params,
+        raw,
+        ...(docTop ? { documentation: docTop } : {}),
+        ...(typeof obj.activeParameter === 'number' ? { activeParameter: obj.activeParameter } : {}),
+    };
+    return out;
+}
+/**
+ * LSP `MarkupContent | string` -> string. Used by both signature help
+ * (top-level docs + per-param docs) and hover normalization.
+ */
+function extractMarkupString(raw) {
+    if (typeof raw === 'string')
+        return raw.length > 0 ? raw : undefined;
+    if (raw && typeof raw === 'object' && 'value' in raw) {
+        const value = raw.value;
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * PUGI-78 Phase 1: collapse a `textDocument/rename` `WorkspaceEdit` to
+ * the agent-facing flat list. Handles BOTH shapes:
+ *   - legacy `changes: { [uri]: TextEdit[] }`
+ *   - modern `documentChanges: (TextDocumentEdit | FileOp)[]`
+ *
+ * File-op entries (`CreateFile`, `RenameFile`, `DeleteFile`) are NOT
+ * surfaced in Phase 1 — the only renames Pugi enables out of the box
+ * are symbol-level. Phase 2 wires the file-op variants.
+ */
+function normalizeWorkspaceEdit(raw, cwd) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const edits = [];
+    const fileSet = new Set();
+    const pushEdit = (uri, edit) => {
+        if (!edit || typeof edit !== 'object')
+            return;
+        const editObj = edit;
+        const range = parseRange(editObj.range);
+        if (!range)
+            return;
+        const newText = typeof editObj.newText === 'string' ? editObj.newText : '';
+        const file = uriToWorkspacePath(uri, cwd);
+        if (!file)
+            return;
+        fileSet.add(file);
+        edits.push({ file, line: range.start.line, character: range.start.character, newText });
+    };
+    if (obj.changes && typeof obj.changes === 'object') {
+        for (const [uri, list] of Object.entries(obj.changes)) {
+            if (!Array.isArray(list))
+                continue;
+            for (const edit of list)
+                pushEdit(uri, edit);
+        }
+    }
+    if (Array.isArray(obj.documentChanges)) {
+        for (const docChange of obj.documentChanges) {
+            if (!docChange || typeof docChange !== 'object')
+                continue;
+            const dc = docChange;
+            // Skip file-op entries — they have a `kind` discriminator.
+            if (typeof dc.kind === 'string' && dc.kind !== '')
+                continue;
+            const td = dc.textDocument;
+            if (!td || typeof td !== 'object')
+                continue;
+            const uri = td.uri;
+            if (typeof uri !== 'string')
+                continue;
+            if (Array.isArray(dc.edits)) {
+                for (const edit of dc.edits)
+                    pushEdit(uri, edit);
+            }
+        }
+    }
+    if (fileSet.size === 0)
+        return null;
+    return { files: Array.from(fileSet).sort(), edits, raw };
+}
+/**
+ * Convert an LSP `file://` URI to a workspace-relative path. Empty
+ * string when the URI escapes the workspace; the caller decides whether
+ * to drop the edit or surface the raw URI.
+ */
+function uriToWorkspacePath(uri, cwd) {
+    try {
+        const url = new URL(uri);
+        if (url.protocol !== 'file:')
+            return uri;
+        const abs = decodeURIComponent(url.pathname);
+        if (abs === cwd)
+            return '.';
+        if (abs.startsWith(cwd + sep))
+            return abs.slice(cwd.length + 1);
+        return uri;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * PUGI-78 Phase 1: parse `textDocument/codeAction` response. Server
+ * returns either `Command[]` or `CodeAction[]`. Both have `title`;
+ * `CodeAction` additionally carries `kind` + `isPreferred` + `edit`.
+ */
+function normalizeCodeActions(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        if (typeof obj.title !== 'string' || obj.title.length === 0)
+            continue;
+        out.push({
+            title: obj.title,
+            ...(typeof obj.kind === 'string' ? { kind: obj.kind } : {}),
+            ...(typeof obj.isPreferred === 'boolean' ? { isPreferred: obj.isPreferred } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * PUGI-78 Phase 1: parse a `TextEdit[]` payload returned by the
+ * formatter. Skips rows with missing range or non-string newText.
+ */
+function normalizeTextEdits(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const range = parseRange(obj.range);
+        if (!range)
+            continue;
+        const newText = typeof obj.newText === 'string' ? obj.newText : '';
+        out.push({ range, newText });
+    }
+    return out;
+}
+/**
+ * PUGI-78 Phase 1: collapse `callHierarchy/{incoming,outgoing}Calls`.
+ * The two response shapes share the same `from`/`to` field for the
+ * counterpart item; `fromRanges`/`toRanges` flatten to `callRanges`.
+ */
+function normalizeCallHierarchyEdges(raw, itemKey, cwd) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const rangeKey = itemKey === 'from' ? 'fromRanges' : 'toRanges';
+    for (const row of raw) {
+        if (!row || typeof row !== 'object')
+            continue;
+        const rowObj = row;
+        const item = rowObj[itemKey];
+        if (!item || typeof item !== 'object')
+            continue;
+        const itemObj = item;
+        if (typeof itemObj.name !== 'string' || itemObj.name.length === 0)
+            continue;
+        const kind = typeof itemObj.kind === 'number' ? itemObj.kind : 0;
+        if (!kind)
+            continue;
+        const uri = typeof itemObj.uri === 'string' ? itemObj.uri : '';
+        if (!uri)
+            continue;
+        const file = uriToWorkspacePath(uri, cwd);
+        const selRange = parseRange(itemObj.selectionRange) ?? parseRange(itemObj.range);
+        if (!selRange)
+            continue;
+        const rangesRaw = rowObj[rangeKey];
+        const callRanges = [];
+        if (Array.isArray(rangesRaw)) {
+            for (const r of rangesRaw) {
+                const parsed = parseRange(r);
+                if (parsed)
+                    callRanges.push(parsed);
+            }
+        }
+        out.push({
+            name: itemObj.name,
+            kind,
+            file,
+            line: selRange.start.line,
+            character: selRange.start.character,
+            callRanges,
+        });
+    }
+    return out;
+}
+/**
+ * Test-only surface so specs can hand-craft an `LspClient` over a mock
+ * stdio pipe without paying for the real `startLspClient` spawn cost.
+ * The exported shape mirrors what the constructor needs.
+ */
+export const __test__ = {
+    LANGUAGE_SERVERS,
+    normalizeHover,
+    normalizeLocations,
+    normalizeDiagnostic,
+    normalizeSignatureHelp,
+    normalizeWorkspaceEdit,
+    normalizeCodeActions,
+    normalizeTextEdits,
+    normalizeCallHierarchyEdges,
+    uriToWorkspacePath,
+};
+//# sourceMappingURL=client.js.map