@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/lsp/client.js

@@ -1,55 +1,55 @@
 /**
- * LSP client wrapper — α7.7 Phase 1 (LSP tool + worktree + apply_patch).
+ * 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)
+ *  - 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.
+ *  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`)
+ *  - 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.
+ *  `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.
+ *  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
+ * . 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
@@ -130,7 +130,7 @@ export class LspClient {
             child.stderr.on('data', () => { });
         }
         child.on('exit', () => this.onExit());
-        // R1 fix (2026-05-26, PR #413 r1, P2 #11): mirror onExit for the
+        // 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
@@ -206,6 +206,189 @@ export class LspClient {
             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
@@ -260,7 +443,7 @@ export class LspClient {
                 detail: error instanceof Error ? error.message : String(error),
             };
         }
-        // R1 fix (2026-05-26, PR #413 r1, Fix 8): realpath containment.
+        // 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
@@ -385,7 +568,7 @@ export class LspClient {
             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 #413 r1, Fix 7): malformed header —
+                // 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
@@ -465,10 +648,59 @@ export class LspClient {
         }
     }
 }
+/**
+ * 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];
@@ -479,6 +711,14 @@ export async function startLspClient(lang, opts) {
             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) {
@@ -575,6 +815,27 @@ async function initializeHandshake(client, cwd) {
                 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' }],
@@ -597,9 +858,9 @@ function detectBinary(name) {
 }
 function normalizeHover(raw) {
     // LSP `Hover.contents` can be:
-    //   - string
-    //   - { kind: 'markdown' | 'plaintext', value: string }
-    //   - Array<string | { language: string, value: string }>
+    //  - string
+    //  - { kind: 'markdown' | 'plaintext', value: string }
+    //  - Array<string | { language: string, value: string }>
     if (!raw || typeof raw !== 'object') {
         return { content: String(raw ?? ''), raw };
     }
@@ -705,6 +966,249 @@ function normalizeDiagnostic(raw) {
     };
     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.
@@ -715,5 +1219,11 @@ export const __test__ = {
     normalizeHover,
     normalizeLocations,
     normalizeDiagnostic,
+    normalizeSignatureHelp,
+    normalizeWorkspaceEdit,
+    normalizeCodeActions,
+    normalizeTextEdits,
+    normalizeCallHierarchyEdges,
+    uriToWorkspacePath,
 };
 //# sourceMappingURL=client.js.map