@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

package/dist/core/lsp/client.js

@@ -1,1229 +0,0 @@
-/**
- * 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