@pugi/cli 0.1.0-beta.88 → 0.1.0-beta.89

package/dist/core/hooks/worktree-events.js

@@ -0,0 +1,158 @@
+/**
+ * Worktree lifecycle hooks - PUGI-487.
+ *
+ * Extends the existing hook lifecycle (`SessionStart` / `PreToolUse` /
+ * etc.) with two new events targeted at the user-facing `--worktree`
+ * flag:
+ *
+ *  - `WorktreeCreate`: fired when the operator runs
+ *    `pugi --worktree <name>` BEFORE git has touched the filesystem.
+ *    Receives a JSON document on stdin describing the requested
+ *    worktree. If the hook's stdout has a JSON envelope with a
+ *    `directory` field, the runtime uses that path instead of the
+ *    default `.claude/worktrees/<name>/` location. Non-zero exit aborts
+ *    worktree creation when `blocking: true` is set.
+ *
+ *  - `WorktreeRemove`: fired when the operator (or the cleanup sweep)
+ *    is about to delete a worktree. Receives a JSON document on stdin
+ *    describing the target. Non-zero exit aborts removal when
+ *    `blocking: true`.
+ *
+ * Both events follow the JSON-on-stdin pattern of the existing v2
+ * hook contract. The dispatcher is intentionally small because the
+ * heavy lifting (file load, schema validation, timeout enforcement)
+ * lives in `core/hooks/registry.ts` and `core/hooks/runner.ts`.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { DEFAULT_HOOK_TIMEOUT_MS } from './registry.js';
+/**
+ * Fire every hook configured for the given worktree event. Returns the
+ * aggregated outcome including any directory override and the
+ * blocking-failure short circuit.
+ *
+ * Each hook receives the JSON payload on stdin and is expected to
+ * produce its response on stdout. Hooks are run sequentially (not in
+ * parallel) so that ordering across a multi-hook chain stays
+ * deterministic - the first directory override wins.
+ */
+export function fireWorktreeHooks(config, event, payload, options = {}) {
+    const entries = config.list(event);
+    const spawn = options.spawn ?? defaultSpawn;
+    const results = [];
+    let directoryOverride;
+    let anyBlocked = false;
+    const json = JSON.stringify(payload);
+    for (const entry of entries) {
+        const start = Date.now();
+        const ret = spawn(entry.command, {
+            input: json,
+            encoding: 'utf8',
+            shell: '/bin/sh',
+            timeout: entry.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+            maxBuffer: 1 * 1024 * 1024,
+        });
+        const elapsedMs = Date.now() - start;
+        const stdout = bufToString(ret.stdout);
+        const stderr = bufToString(ret.stderr);
+        const ok = ret.status === 0;
+        const blocked = !ok && entry.blocking === true;
+        if (blocked)
+            anyBlocked = true;
+        let dirOverride;
+        if (event === 'WorktreeCreate' && ok && stdout.length > 0) {
+            dirOverride = extractDirectoryOverride(stdout);
+            if (dirOverride && !directoryOverride) {
+                directoryOverride = dirOverride;
+            }
+        }
+        results.push({
+            command: entry.command.slice(0, 200),
+            exitCode: ret.status,
+            stdout,
+            stderr,
+            elapsedMs,
+            ok,
+            blocked,
+            ...(dirOverride ? { directoryOverride: dirOverride } : {}),
+        });
+        if (blocked)
+            break;
+    }
+    return {
+        event,
+        results,
+        anyBlocked,
+        ...(directoryOverride ? { directoryOverride } : {}),
+    };
+}
+/**
+ * Extract a `directory` override from hook stdout. Two accepted shapes:
+ *
+ *   1. JSON object with `{ "directory": "<path>" }`.
+ *   2. Bare path string (trimmed first non-empty line) when the hook
+ *      writes plain text. We accept the trimmed line as the override
+ *      ONLY if it looks like a non-flag path (no leading `-`, no `\n`,
+ *      no shell metacharacters).
+ *
+ * Returns undefined when no override is detected.
+ */
+export function extractDirectoryOverride(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed &&
+                typeof parsed === 'object' &&
+                !Array.isArray(parsed) &&
+                typeof parsed.directory === 'string') {
+                const dir = parsed.directory.trim();
+                if (isSafePathToken(dir))
+                    return dir;
+            }
+        }
+        catch {
+            // fall through to bare-path detection
+        }
+    }
+    const firstLine = trimmed.split(/\r?\n/, 1)[0] ?? '';
+    if (firstLine.length === 0)
+        return undefined;
+    if (isSafePathToken(firstLine))
+        return firstLine;
+    return undefined;
+}
+/**
+ * Cheap defence-in-depth check: a directory override must not look
+ * like a shell injection vector. The override is later validated for
+ * containment (the runtime refuses paths that escape the repo root),
+ * but rejecting obvious metacharacters here surfaces a cleaner error.
+ */
+function isSafePathToken(value) {
+    if (value.length === 0)
+        return false;
+    if (value.startsWith('-'))
+        return false;
+    if (/[;`$&|<>\n\r\t]/.test(value))
+        return false;
+    return true;
+}
+function defaultSpawn(command, options) {
+    const result = spawnSync(command, [], options);
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+function bufToString(v) {
+    if (v === undefined || v === null)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    return v.toString('utf8');
+}
+//# sourceMappingURL=worktree-events.js.map

package/dist/core/lsp/client.js

@@ -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
@@ -632,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' }],
@@ -762,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.
@@ -772,5 +1219,11 @@ export const __test__ = {
     normalizeHover,
     normalizeLocations,
     normalizeDiagnostic,
+    normalizeSignatureHelp,
+    normalizeWorkspaceEdit,
+    normalizeCodeActions,
+    normalizeTextEdits,
+    normalizeCallHierarchyEdges,
+    uriToWorkspacePath,
 };
 //# sourceMappingURL=client.js.map