@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/lsp/client.js

@@ -0,0 +1,776 @@
+/**
+ * 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 };
+        });
+    }
+    /**
+     * 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 },
+            },
+        },
+        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;
+}
+/**
+ * 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,
+};
+//# sourceMappingURL=client.js.map