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

package/dist/core/lsp/server-detect.js

@@ -0,0 +1,173 @@
+/**
+ * PUGI-78 Phase 1: LSP server discovery via `~/.pugi/lsp-config.json`
+ * + PATH probe.
+ *
+ * The base `LANGUAGE_SERVERS` registry in `client.ts` ships sane
+ * defaults (TypeScript via npx, pyright/gopls/rust-analyzer assumed on
+ * PATH). Operators who run a non-standard layout (NixOS, asdf, custom
+ * monorepo binaries) override per-language commands via a small JSON
+ * file at `$HOME/.pugi/lsp-config.json`:
+ *
+ * ```json
+ * {
+ *   "typescript": {
+ *     "command": "/usr/local/bin/typescript-language-server",
+ *     "args": ["--stdio"]
+ *   },
+ *   "python": {
+ *     "command": "pylsp",
+ *     "args": []
+ *   }
+ * }
+ * ```
+ *
+ * The file is loaded once per process; failures are non-fatal (missing
+ * file => empty override map, parse error => log + empty override).
+ * The standard registry stays the fallback. The operator-facing CLI
+ * surface (`pugi lsp servers`) reports both detected binaries (via
+ * `inspectLspServers` in client.ts) and any operator overrides loaded
+ * from this module.
+ *
+ * Why a JSON file (not a flag): the operator may have several distinct
+ * LSP layouts (e.g. one for the monorepo, one for an isolated package).
+ * A central config in `~/.pugi/` lets every workspace inherit the same
+ * defaults without re-typing flags on every `pugi` invocation; the
+ * workspace-local `.pugi/settings.json::lsp` toggle (already shipped
+ * in β7 L9) layers on top to disable specific languages per-workspace.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { homedir } from 'node:os';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+/**
+ * Settings file path. Computed lazily so a spec can inject `HOME` via
+ * `process.env.HOME = '/tmp/test'` before importing this module.
+ */
+export function lspConfigPath() {
+    return join(homedir(), '.pugi', 'lsp-config.json');
+}
+/**
+ * Load the operator override map from `$HOME/.pugi/lsp-config.json`.
+ * Non-fatal failures: missing file -> empty map; malformed JSON ->
+ * empty map + stderr warning when `PUGI_LSP_DEBUG=1`. Returns the
+ * parsed map; any unrecognized language slug is dropped silently.
+ *
+ * Synchronous because this is a one-shot bootstrap path called from
+ * the CLI surface before any LSP client spawn; the file is tiny (<2 KB
+ * in practice) so the sync read cost is negligible.
+ */
+export function loadOperatorOverrides(path) {
+    const resolved = path ?? lspConfigPath();
+    if (!existsSync(resolved))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(resolved, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        if (process.env.PUGI_LSP_DEBUG === '1') {
+            process.stderr.write(`[pugi lsp] ignored ${resolved} - invalid JSON\n`);
+        }
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    const out = {};
+    const supported = ['ts', 'js', 'py', 'go', 'rust'];
+    // Accept both short slug ("ts") and long name ("typescript") on the
+    // operator side - long names are friendlier in a hand-edited file.
+    const longNameMap = {
+        typescript: 'ts',
+        javascript: 'js',
+        python: 'py',
+        go: 'go',
+        rust: 'rust',
+        ts: 'ts',
+        js: 'js',
+        py: 'py',
+        rs: 'rust',
+    };
+    for (const [key, value] of Object.entries(parsed)) {
+        const lang = longNameMap[key.toLowerCase()];
+        if (!lang || !supported.includes(lang))
+            continue;
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const v = value;
+        if (typeof v.command !== 'string' || v.command.length === 0)
+            continue;
+        const args = [];
+        if (Array.isArray(v.args)) {
+            for (const a of v.args) {
+                if (typeof a === 'string')
+                    args.push(a);
+            }
+        }
+        out[lang] = { command: v.command, args };
+    }
+    return out;
+}
+/**
+ * Discover every supported language's server given the registry defaults
+ * + the operator override map. `defaultRegistry` is injected so the
+ * caller (the CLI surface) can pass the live `LANGUAGE_SERVERS` from
+ * `client.ts` without forming a circular module dep.
+ */
+export function detectServers(defaultRegistry, overrides = loadOperatorOverrides()) {
+    const out = [];
+    for (const lang of Object.keys(defaultRegistry)) {
+        const base = defaultRegistry[lang];
+        const override = overrides[lang];
+        if (override) {
+            out.push({
+                language: lang,
+                source: 'override',
+                command: override.command,
+                args: override.args,
+                available: detectBinaryOnPath(override.command),
+            });
+        }
+        else {
+            out.push({
+                language: lang,
+                source: 'default',
+                command: base.command,
+                args: base.args,
+                available: detectBinaryOnPath(base.probe),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Cross-platform binary detection. POSIX = `which`, Windows = `where`.
+ * Failures are non-fatal — we just report unavailable. We avoid
+ * `spawnSync(name, ['--version'])` because some servers (gopls, older
+ * pyright) do not honor `--version` and exit non-zero, which would
+ * mis-flag them as missing.
+ */
+export function detectBinaryOnPath(name) {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const result = spawnSync(probe, [name], { stdio: 'ignore' });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Test-only — direct access to the long-name accepting map. */
+export const __test__ = {
+    detectBinaryOnPath,
+    lspConfigPath,
+};
+//# sourceMappingURL=server-detect.js.map

package/dist/core/lsp/symbol-cache.js

@@ -0,0 +1,162 @@
+/** Default TTL for cached entries. 5 minutes matches the spec target. */
+export const DEFAULT_TTL_MS = 5 * 60 * 1000;
+/** Default size cap. Empirically large enough for a heavy navigate session. */
+export const DEFAULT_MAX_ENTRIES = 1000;
+/**
+ * Generic TTL cache. The unknown value type is intentional — the cache
+ * stores serialized result objects produced by the 13 symbol tools; we
+ * surface them back to the caller as the SAME unknown so the cache
+ * does not encode the result schema.
+ *
+ * Thread-safety: Node single-threaded, no concurrent writes possible
+ * inside one `pugi` invocation. The cache is NOT shared across
+ * spawned subagents — each subagent runs its own LspClient + cache.
+ */
+export class SymbolCache {
+    store = new Map();
+    ttlMs;
+    maxEntries;
+    now;
+    metrics = { hits: 0, misses: 0, evictions: 0, size: 0 };
+    constructor(options) {
+        this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.now = options?.now ?? (() => Date.now());
+    }
+    /**
+     * Build a canonical key from the dispatch coordinates. Workspace +
+     * language scopes the cache so two different repos opened in the same
+     * REPL session do not pollute each other.
+     */
+    static makeKey(lang, workspace, verb, args) {
+        // Sort keys deterministically so `{file: 'a', line: 1}` and
+        // `{line: 1, file: 'a'}` map to the same cache entry.
+        const sorted = {};
+        for (const key of Object.keys(args).sort()) {
+            sorted[key] = args[key];
+        }
+        return `${lang}::${workspace}::${verb}::${JSON.stringify(sorted)}`;
+    }
+    /**
+     * Look up a cached value. Returns undefined when:
+     *
+     *  - the key is not in the cache
+     *  - the entry has aged past `ttlMs` (the entry is deleted in this
+     *    case so the eviction counter is accurate)
+     *
+     * Hit updates the entry's `lastAccessed` so the LRU policy keeps
+     * frequently-touched entries warm.
+     */
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            this.metrics.misses++;
+            return undefined;
+        }
+        const now = this.now();
+        if (now - entry.storedAt > this.ttlMs) {
+            this.store.delete(key);
+            this.metrics.evictions++;
+            this.metrics.misses++;
+            this.metrics.size = this.store.size;
+            return undefined;
+        }
+        entry.lastAccessed = now;
+        this.metrics.hits++;
+        return entry.result;
+    }
+    /**
+     * Store a value. Evicts the LRU entry when the cache hits `maxEntries`.
+     * The eviction counter increments for each LRU drop AND each TTL drop
+     * so the operator surface can distinguish "cache too small" from "TTL
+     * too short".
+     */
+    set(key, value) {
+        const now = this.now();
+        if (this.store.size >= this.maxEntries && !this.store.has(key)) {
+            // Find the LRU entry.
+            let oldestKey;
+            let oldestAccess = Number.POSITIVE_INFINITY;
+            for (const [k, entry] of this.store) {
+                if (entry.lastAccessed < oldestAccess) {
+                    oldestAccess = entry.lastAccessed;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey !== undefined) {
+                this.store.delete(oldestKey);
+                this.metrics.evictions++;
+            }
+        }
+        this.store.set(key, { result: value, storedAt: now, lastAccessed: now });
+        this.metrics.size = this.store.size;
+    }
+    /**
+     * Invalidate every entry for a workspace. Called by the post-edit
+     * hook so a successful `edit`/`write` clears stale symbol locations.
+     * Returns the number of entries dropped.
+     */
+    invalidateWorkspace(workspace) {
+        const prefix = `${workspace}::`;
+        // Two prefix forms: `<lang>::<workspace>::...` — we scan the full
+        // store and drop entries whose key contains the workspace literal.
+        let dropped = 0;
+        for (const key of Array.from(this.store.keys())) {
+            // The key shape is `lang::workspace::verb::args` — split on `::`
+            // and check the second segment. Avoid substring match because a
+            // workspace path could legally contain `::` (e.g. a Windows
+            // network path).
+            const parts = key.split('::');
+            if (parts.length >= 2 && parts[1] === workspace) {
+                this.store.delete(key);
+                dropped++;
+            }
+            else if (parts.length >= 2 && parts[1]?.startsWith(prefix)) {
+                this.store.delete(key);
+                dropped++;
+            }
+        }
+        if (dropped > 0) {
+            this.metrics.evictions += dropped;
+            this.metrics.size = this.store.size;
+        }
+        return dropped;
+    }
+    /** Drop every cached entry. */
+    clear() {
+        this.metrics.evictions += this.store.size;
+        this.store.clear();
+        this.metrics.size = 0;
+    }
+    /** Snapshot of the current metrics. The returned record is a copy. */
+    snapshot() {
+        return { ...this.metrics, size: this.store.size };
+    }
+    /** Test-only: reset metrics counters without dropping entries. */
+    resetMetrics() {
+        this.metrics = { hits: 0, misses: 0, evictions: 0, size: this.store.size };
+    }
+    /** Test-only: number of entries currently stored. */
+    size() {
+        return this.store.size;
+    }
+}
+/**
+ * Process-global symbol cache, lazily constructed on first access. The
+ * CLI surface picks this up via `getGlobalSymbolCache()` so every
+ * subagent / tool invocation in the same process shares the same cache.
+ * Subagents spawned in a fresh child process get a fresh cache (by
+ * design — the cache is process-scoped, not user-scoped).
+ */
+let globalCache;
+export function getGlobalSymbolCache(options) {
+    if (!globalCache) {
+        globalCache = new SymbolCache(options);
+    }
+    return globalCache;
+}
+/** Test-only: drop the singleton so a spec starts with a fresh cache. */
+export function __resetGlobalSymbolCache() {
+    globalCache = undefined;
+}
+//# sourceMappingURL=symbol-cache.js.map

package/dist/core/lsp/symbol-tools.js

@@ -67,15 +67,28 @@ export function symbolKindLabel(kind) {
     return SYMBOL_KIND_LABELS[kind] ?? 'unknown';
 }
 /**
- * Build a `SymbolToolsTransport` from a real `LspClient`. Production
- * wire-up. `documentSymbols` / `workspaceSymbols` are omitted on
- * purpose — the `LspClient` does not expose them, so the Phase 1
- * surface degrades to `[]`. Phase 2 follows.
+ * Build a `SymbolToolsTransport` from a real `LspClient`. PUGI-78 Phase
+ * 1: wires every method the client exposes (13 total). Methods the
+ * `LspClient` does NOT support yet stay omitted on the returned
+ * transport so the symbol-tools surface degrades to null / [] without
+ * forcing the caller to wrap.
  */
 export function transportFromLspClient(client) {
     return {
         definition: (file, pos) => client.definition(file, pos),
         references: (file, pos) => client.references(file, pos),
+        documentSymbols: (file) => client.documentSymbols(file),
+        workspaceSymbols: (query) => client.workspaceSymbols(query),
+        hover: (file, pos) => client.hover(file, pos),
+        signatureHelp: (file, pos) => client.signatureHelp(file, pos),
+        implementations: (file, pos) => client.implementations(file, pos),
+        typeDefinition: (file, pos) => client.typeDefinition(file, pos),
+        rename: (file, pos, newName) => client.rename(file, pos, newName),
+        prepareRename: (file, pos) => client.prepareRename(file, pos),
+        codeActions: (file, range) => client.codeActions(file, range),
+        formatting: (file, options) => client.formatting(file, undefined, options),
+        diagnostics: (file) => client.diagnostics(file),
+        callHierarchy: (file, pos) => client.callHierarchy(file, pos),
     };
 }
 /**
@@ -222,6 +235,284 @@ export async function findWorkspaceSymbol(transport, query) {
     }
     return out;
 }
+/**
+ * PUGI-78 Phase 1: hover (type info + docstring). Returns null when:
+ *
+ *  - `filePath` is empty / whitespace
+ *  - `line` / `character` non-finite or negative
+ *  - the transport does not implement `hover`
+ *  - `ok: false` from the transport
+ *  - the server reports no hover (cursor not on a symbol)
+ *  - the transport throws
+ *
+ * Caps the body at 4 KB so a verbose generic type signature does not
+ * blow the agent's context window. The cap mirrors the `lspHover`
+ * tool's 8 KB cap halved — the symbol surface is closer to "give me
+ * one sentence" than the full hover blob.
+ */
+export async function hoverSymbol(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!transport.hover)
+        return null;
+    let result;
+    try {
+        result = await transport.hover(filePath, { line, character });
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    if (!result.value)
+        return null;
+    const HOVER_CAP_BYTES = 4 * 1024;
+    const raw = result.value.content;
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    const truncated = bytes > HOVER_CAP_BYTES;
+    const content = truncated
+        ? Buffer.from(raw, 'utf8').subarray(0, HOVER_CAP_BYTES).toString('utf8') + '\n... [truncated]'
+        : raw;
+    return {
+        content,
+        ...(result.value.range ? { range: result.value.range } : {}),
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+/**
+ * PUGI-78 Phase 1: function signature at a call site. Returns null when
+ * the transport does not implement `signatureHelp` OR the server
+ * reports no signature OR the transport fails / throws.
+ */
+export async function signatureAt(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!transport.signatureHelp)
+        return null;
+    let result;
+    try {
+        result = await transport.signatureHelp(filePath, { line, character });
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    if (!result.value)
+        return null;
+    const out = { label: result.value.label, parameters: result.value.parameters };
+    if (result.value.documentation)
+        out.documentation = result.value.documentation;
+    if (typeof result.value.activeParameter === 'number')
+        out.activeParameter = result.value.activeParameter;
+    return out;
+}
+/**
+ * PUGI-78 Phase 1: implementations of an interface / abstract method.
+ * Returns `[]` on any failure mode (parity with `findReferences`).
+ */
+export async function findImplementations(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return [];
+    if (!transport.implementations)
+        return [];
+    let result;
+    try {
+        result = await transport.implementations(filePath, { line, character });
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return collapseLocations(result.value);
+}
+/**
+ * PUGI-78 Phase 1: type-definition (vs value-definition). Returns null
+ * matching `findDefinition`'s contract.
+ */
+export async function findTypeDefinition(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!transport.typeDefinition)
+        return null;
+    let result;
+    try {
+        result = await transport.typeDefinition(filePath, { line, character });
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    const first = result.value[0];
+    if (!first)
+        return null;
+    const file = pickFilePath(first);
+    if (!isNonEmptyString(file))
+        return null;
+    return { file, line: first.range.start.line, character: first.range.start.character };
+}
+export async function renameSymbol(transport, filePath, line, character, newName) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!isNonEmptyString(newName))
+        return null;
+    if (!transport.rename)
+        return null;
+    // Best-effort prepare-rename precheck. If the server says the cursor
+    // is not on a renameable token, we return null without dispatching
+    // the full rename — saves a wasted round-trip + avoids returning a
+    // misleading "0 edits" preview.
+    if (transport.prepareRename) {
+        try {
+            const prep = await transport.prepareRename(filePath, { line, character });
+            if (prep.ok && prep.value === null)
+                return null;
+        }
+        catch {
+            // Continue — some servers fail prepare-rename but still execute
+            // the full rename. Phase 1 honors the looser fallback.
+        }
+    }
+    let result;
+    try {
+        result = await transport.rename(filePath, { line, character }, newName);
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    if (!result.value)
+        return null;
+    if (result.value.edits.length === 0)
+        return null;
+    return { files: result.value.files, edits: result.value.edits };
+}
+/**
+ * PUGI-78 Phase 1: code-action / quick-fix list at a range. Returns
+ * `[]` on any failure mode.
+ */
+export async function codeActionsAt(transport, filePath, startLine, startChar, endLine, endChar) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!isFiniteNonNegativeInt(startLine) ||
+        !isFiniteNonNegativeInt(startChar) ||
+        !isFiniteNonNegativeInt(endLine) ||
+        !isFiniteNonNegativeInt(endChar)) {
+        return [];
+    }
+    if (!transport.codeActions)
+        return [];
+    const range = {
+        start: { line: startLine, character: startChar },
+        end: { line: endLine, character: endChar },
+    };
+    let result;
+    try {
+        result = await transport.codeActions(filePath, range);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return [...result.value];
+}
+/**
+ * PUGI-78 Phase 1: formatter — returns the text edits the server would
+ * apply. Returns `[]` on any failure mode.
+ */
+export async function formatFile(transport, filePath, options) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!transport.formatting)
+        return [];
+    let result;
+    try {
+        result = await transport.formatting(filePath, options);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return [...result.value];
+}
+/**
+ * PUGI-78 Phase 1: diagnostics for `filePath`. Returns `[]` on any
+ * failure mode. Mirrors the agent surface of `lspDiagnostics` but
+ * folded into the symbols.* namespace for ergonomic discoverability.
+ */
+export async function diagnosticsFor(transport, filePath) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!transport.diagnostics)
+        return [];
+    let result;
+    try {
+        result = await transport.diagnostics(filePath);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return [...result.value];
+}
+/**
+ * PUGI-78 Phase 1: call hierarchy at a symbol position. Returns the
+ * incoming and outgoing edges. Empty arrays on any failure mode.
+ */
+export async function callHierarchyAt(transport, filePath, line, character) {
+    const empty = { incoming: [], outgoing: [] };
+    if (!isNonEmptyString(filePath))
+        return empty;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return empty;
+    if (!transport.callHierarchy)
+        return empty;
+    let result;
+    try {
+        result = await transport.callHierarchy(filePath, { line, character });
+    }
+    catch {
+        return empty;
+    }
+    if (!result.ok)
+        return empty;
+    return { incoming: [...result.value.incoming], outgoing: [...result.value.outgoing] };
+}
+/**
+ * Internal: collapse `LspLocation[]` to flat references the agent
+ * surface ships. Identical to the `findReferences` loop body — lifted
+ * to avoid a second copy.
+ */
+function collapseLocations(locations) {
+    const out = [];
+    for (const loc of locations) {
+        const file = pickFilePath(loc);
+        if (!isNonEmptyString(file))
+            continue;
+        out.push({
+            file,
+            line: loc.range.start.line,
+            character: loc.range.start.character,
+        });
+    }
+    return out;
+}
 // -- internals ---------------------------------------------------------------
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
@@ -368,5 +659,6 @@ export const __test__ = {
     pickRangeStart,
     symbolKindLabel,
     walkDocumentSymbol,
+    collapseLocations,
 };
 //# sourceMappingURL=symbol-tools.js.map

package/dist/core/mcp/server.js

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'node:events';
 /**
  * Pugi MCP server (β4 M2) — exposes Pugi's native tool surface to other
- * agents (the upstream tool, peer tooling, Codex CLI, any client that speaks
+ * agents (the upstream tool, peer tooling, peer CLI, any client that speaks
  * MCP).
  *
  * Transport-agnostic core. The stdio entry-point lives at the bottom of

package/dist/core/repl/ask.js

@@ -4,7 +4,7 @@
  * Pugi's persona prompt teaches Pugi to emit two structured XML envelopes
  * when she would otherwise have to guess. Operator chat then pauses on a
  * modal until the operator answers, eliminating the "fabricate a default
- * silently" failure mode that Codex CLI, the upstream tool, and Gemini CLI all
+ * silently" failure mode that peer CLI, the upstream tool, and Gemini CLI all
  * trip on with low-confidence intents.
  *
  *  <pugi-ask>