@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.2

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

@@ -1,66 +0,0 @@
-/**
- * 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

@@ -1,171 +0,0 @@
-/**
- * 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

@@ -1,173 +0,0 @@
-/**
- * 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

@@ -1,162 +0,0 @@
-/** 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