@pugi/cli 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/core/lsp/client.js

@@ -1,631 +0,0 @@
-/**
- * LSP client wrapper — α7.7 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 α6.6+ 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
- * (α6.9). 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 { readFileSync } 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());
-    }
-    /**
-     * 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),
-            };
-        }
-        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) {
-                // Malformed header — drop the buffer and resync at the next message.
-                this.buffer = Buffer.alloc(0);
-                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'));
-        }
-    }
-}
-/**
- * Start an LSP client for the given language. Returns either an `LspClient`
- * ready to use, or a structured failure (`lsp_unavailable`,
- * `language_unsupported`).
- *
- * The returned client requires `await client.initialize()` BEFORE any
- * operation. We do not inline the initialize into the spawn so test
- * harnesses can intercept the handshake and assert on its contents.
- */
-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) {
-        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)}`,
-        };
-    }
-    const client = new LspClient(child, server, opts);
-    try {
-        await initializeHandshake(client, opts.cwd);
-    }
-    catch (error) {
-        await client.stop();
-        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();
-    // Use the public sendRequest path via a method call. We piggyback on
-    // `LspClient`'s internal `sendRequest` by exposing a single test-grade
-    // surface (`__lspRaw__`); production callers never need this.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    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;
-    if (typeof body === 'string') {
-        return { content: body, range, raw };
-    }
-    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'), range, raw };
-    }
-    if (body && typeof body === 'object' && 'value' in body) {
-        const value = body.value;
-        return { content: typeof value === 'string' ? value : '', range, raw };
-    }
-    return { content: '', range, raw };
-}
-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