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

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

@@ -0,0 +1,66 @@
+/**
+ * Language-from-extension detection — .
+ *
+ * Single source of truth for "given a file path, which `LspLanguage`
+ * slug do we route to". The `runtime/commands/lsp.ts` shipped its
+ * own inline `inferLanguage` switch; L15 (post-edit auto-diagnostics)
+ * needs the same lookup from `core/engine/tool-bridge.ts`, so we lift
+ * the table into a dedicated module to avoid a second copy drifting
+ * out of sync.
+ *
+ * Returning `undefined` is the calling code's signal to silently skip
+ * LSP — an unsupported extension is NOT an error, it just means "no
+ * diagnostics for this file". The tool-bridge hook treats this as a
+ * no-op envelope tail.
+ *
+ * Adding a new language requires THREE coordinated changes:
+ *  1. Add the `LspLanguage` slug + server descriptor in `client.ts`.
+ *  2. Map its extensions here.
+ *  3. Add a `lsp-language-matrix` spec row exercising the new ext.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { extname } from 'node:path';
+/**
+ * Lower-case extension (including the dot) → LSP language slug.
+ * Mirror of the switch in `runtime/commands/lsp.ts::inferLanguage`.
+ * The table form lets tests assert coverage and lets new languages
+ * land with one edit instead of two.
+ */
+export const EXTENSION_TO_LANGUAGE = {
+    '.ts': 'ts',
+    '.tsx': 'ts',
+    '.mts': 'ts',
+    '.cts': 'ts',
+    '.js': 'js',
+    '.jsx': 'js',
+    '.mjs': 'js',
+    '.cjs': 'js',
+    '.py': 'py',
+    '.pyi': 'py',
+    '.go': 'go',
+    '.rs': 'rust',
+};
+/**
+ * Infer the `LspLanguage` for a workspace-relative or absolute path.
+ * Returns `undefined` for unmapped extensions — the caller decides
+ * whether that is silently skipped (post-edit hook) or surfaced as
+ * `language_unsupported` (`pugi lsp` CLI).
+ */
+export function languageForFile(file) {
+    const ext = extname(file).toLowerCase();
+    if (!ext)
+        return undefined;
+    return EXTENSION_TO_LANGUAGE[ext];
+}
+/**
+ * Return every extension currently mapped to the given language.
+ * Used by the matrix spec to assert coverage without re-typing the
+ * extension list.
+ */
+export function extensionsForLanguage(lang) {
+    return Object.entries(EXTENSION_TO_LANGUAGE)
+        .filter(([, value]) => value === lang)
+        .map(([ext]) => ext);
+}
+//# sourceMappingURL=language-detect.js.map

package/dist/core/lsp/post-edit-diagnostics.js

@@ -0,0 +1,171 @@
+/**
+ * Post-edit diagnostics — .
+ *
+ * the upstream tool's leak intel surfaced this pattern: after a `FileEdit` /
+ * `Write` tool call lands, an LSP diagnostic pass runs on the touched
+ * file and the result is appended to the tool envelope before the
+ * model sees it. The model then self-corrects in the same turn —
+ * "TS2304: Cannot find name 'undef'" comes back, the model fixes the
+ * typo in the next tool call, no operator round-trip needed.
+ *
+ * This module is the Pugi side of that pattern:
+ *
+ *  1. The tool-bridge calls `runPostEditDiagnostics(path, ctx)` after
+ *     a successful `edit` / `write` / `multi_edit`.
+ *  2. We infer the language from the extension (`language-detect`).
+ *     Unsupported extension → `{ skip: true }` and the bridge appends
+ *     nothing.
+ *  3. We borrow (or lazily start) the per-language cached client
+ *     from `cache.ts`. A spawn failure → `{ skip: true }` and the
+ *     envelope stays clean. Silence on failure is intentional: an
+ *     operator who has not installed `typescript-language-server`
+ *     should not see an LSP nag on every edit.
+ *  4. We pull diagnostics with a hard 5s ceiling. A timeout logs a
+ *     warning on stderr (gated on `PUGI_LSP_DEBUG=1`) and skips —
+ *     the envelope is never blocked on LSP.
+ *  5. We format the surviving diagnostics into a readable tail
+ *     mirroring the leak format:
+ *
+ *        LSP DIAGNOSTICS (typescript):
+ *          foo.ts:42:5 error TS2304: Cannot find name 'undef'.
+ *          foo.ts:51:1 warn TS6133: 'unused' is declared.
+ *
+ * The bridge concatenates this tail onto its existing `wrote ...` /
+ * `edited ...` body with a single newline separator. When there are
+ * zero diagnostics we return `{ skip: true }` so the existing body
+ * is unchanged — the "no news is good news" path stays terse.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { isAbsolute, relative, resolve } from 'node:path';
+import { getOrStartLspClient } from './cache.js';
+import { languageForFile } from './language-detect.js';
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Hard cap on how many diagnostics we surface to the model. A file
+ * with 200 errors after a broken bulk edit would otherwise blow the
+ * context window; the model can re-run `pugi lsp diagnostics` if
+ * it needs the full list.
+ */
+const MAX_DIAGNOSTICS = 25;
+export async function runPostEditDiagnostics(filePath, opts) {
+    const lang = languageForFile(filePath);
+    if (!lang) {
+        return { skip: true, reason: 'unsupported_language' };
+    }
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const clientResult = await loadClient(lang, opts);
+    if (!clientResult.ok) {
+        return { skip: true, reason: mapStartFailure(clientResult.reason) };
+    }
+    // Run diagnostics with a hard timeout. The underlying LspClient has
+    // its own per-request timeout (5s default) but a slow handshake
+    // can blow past it; we belt-and-suspenders here so the agent loop
+    // never blocks on LSP.
+    const relPath = toWorkspaceRelative(filePath, opts.cwd);
+    const diagnosticsPromise = clientResult.client.diagnostics(relPath);
+    let timer;
+    const timeoutPromise = new Promise((resolveFn) => {
+        timer = setTimeout(() => resolveFn({ timedOut: true }), timeoutMs);
+        timer.unref();
+    });
+    const race = await Promise.race([
+        diagnosticsPromise.then((value) => ({ timedOut: false, value })),
+        timeoutPromise,
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (race.timedOut) {
+        const writeFn = opts.debugWrite ?? ((line) => {
+            if (process.env.PUGI_LSP_DEBUG === '1')
+                process.stderr.write(`${line}\n`);
+        });
+        writeFn(`[pugi-lsp] post-edit diagnostics for ${relPath} timed out after ${timeoutMs}ms (lang=${lang})`);
+        return { skip: true, reason: 'timeout' };
+    }
+    const diag = race.value;
+    if (!diag.ok) {
+        return { skip: true, reason: 'lsp_error' };
+    }
+    if (diag.value.length === 0) {
+        return { skip: true, reason: 'no_diagnostics' };
+    }
+    const tail = formatDiagnosticsTail(relPath, lang, diag.value);
+    return { skip: false, tail, count: diag.value.length, language: lang };
+}
+async function loadClient(lang, opts) {
+    if (opts.clientLoader) {
+        return opts.clientLoader(lang);
+    }
+    const { cwd, timeoutMs, clientLoader: _ignoredA, debugWrite: _ignoredB, ...rest } = opts;
+    const result = await getOrStartLspClient(lang, { cwd, ...rest });
+    if (!result.ok) {
+        return { ok: false, reason: result.reason, detail: result.detail };
+    }
+    return { ok: true, client: result.client };
+}
+function mapStartFailure(reason) {
+    if (reason === 'lsp_unavailable' || reason === 'language_unsupported')
+        return 'lsp_unavailable';
+    if (reason === 'lsp_disabled')
+        return 'lsp_disabled';
+    return 'lsp_error';
+}
+/**
+ * Convert an absolute or workspace-relative path into the form the
+ * LSP client expects — same shape as `runtime/commands/lsp.ts` uses.
+ */
+function toWorkspaceRelative(filePath, cwd) {
+    if (!isAbsolute(filePath))
+        return filePath;
+    const rel = relative(cwd, resolve(cwd, filePath));
+    return rel || filePath;
+}
+/**
+ * Format diagnostics into the leak-shaped envelope tail. Pure function
+ * exported for unit tests to assert the line format independent of
+ * any LSP plumbing.
+ */
+export function formatDiagnosticsTail(relPath, lang, diagnostics) {
+    const visible = diagnostics.slice(0, MAX_DIAGNOSTICS);
+    const truncated = diagnostics.length > visible.length;
+    const lines = [`LSP DIAGNOSTICS (${LANGUAGE_LABELS[lang]}):`];
+    for (const diag of visible) {
+        const line = diag.range.start.line + 1; // LSP is zero-based; humans expect 1-based.
+        const col = diag.range.start.character + 1;
+        const severity = SEVERITY_LABELS[diag.severityLabel];
+        const code = diag.code !== undefined && diag.code !== '' ? ` ${diag.code}` : '';
+        const source = diag.source ? `${diag.source}` : '';
+        const head = source ? `${severity}${code} (${source}):` : `${severity}${code}:`;
+        lines.push(` ${relPath}:${line}:${col} ${head} ${diag.message}`);
+    }
+    if (truncated) {
+        lines.push(` ... ${diagnostics.length - visible.length} more diagnostic(s) — re-run pugi lsp diagnostics ${relPath} for the full list`);
+    }
+    return lines.join('\n');
+}
+const LANGUAGE_LABELS = {
+    ts: 'typescript',
+    js: 'javascript',
+    py: 'python',
+    go: 'go',
+    rust: 'rust',
+};
+/**
+ * Map LSP severity label → the short token the leak envelope uses.
+ * "warn" is shorter than "warning" and matches the upstream tool's leak
+ * verbatim; the rest mirror LSP terminology.
+ */
+const SEVERITY_LABELS = {
+    error: 'error',
+    warning: 'warn ',
+    info: 'info ',
+    hint: 'hint ',
+};
+/** Test-only surface so specs can poke the pure helpers without LSP. */
+export const __test__ = {
+    formatDiagnosticsTail,
+    MAX_DIAGNOSTICS,
+    DEFAULT_TIMEOUT_MS,
+};
+//# sourceMappingURL=post-edit-diagnostics.js.map

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