@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.50

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

@@ -0,0 +1,66 @@
+/**
+ * Language-from-extension detection — Leak L15.
+ *
+ * Single source of truth for "given a file path, which `LspLanguage`
+ * slug do we route to". The α7.7 `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 — Leak L15.
+ *
+ * Claude Code'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 Claude Code'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/mcp/client.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
 import { z } from 'zod';
 /**
  * Minimal JSON-RPC 2.0 over stdio MCP client for Pugi CLI M1.
@@ -34,6 +35,15 @@ import { z } from 'zod';
  */
 export const mcpServerConfigSchema = z.object({
     command: z.string().min(1),
+    /**
+     * β4 r2 P1 #1 — operator's literal `command` argument as supplied to
+     * `pugi mcp install`. `command` above is now the RESOLVED absolute path
+     * we actually spawn. `originalCommand` is preserved for display/audit
+     * (`pugi mcp list`, audit logs) so operators can still see how they
+     * typed the install. Optional because pre-r2 mcp.json files do not
+     * carry the field — the loader treats absence as "use command directly".
+     */
+    originalCommand: z.string().min(1).optional(),
     args: z.array(z.string()).default([]),
     env: z.record(z.string()).default({}),
     /**
@@ -70,6 +80,22 @@ export async function connect(serverName, config, options = {}) {
         env: { ...process.env, ...config.env },
         stdio: ['pipe', 'pipe', 'pipe'],
     });
+    // L13: optional stderr → log file. We open the stream lazily so a bad
+    // path surfaces synchronously to the caller instead of getting buried
+    // in the child's stderr handler. `mkdir -p` of the parent dir is the
+    // caller's responsibility (the registry does it once per session).
+    let logStream;
+    if (options.logFile) {
+        try {
+            logStream = createWriteStream(options.logFile, { flags: 'a' });
+        }
+        catch {
+            // Log directory missing or unwritable — degrade silently rather
+            // than refuse the handshake. The operator still gets the same
+            // surface they had pre-L13 (stderr dropped on the floor).
+            logStream = undefined;
+        }
+    }
     const connection = {
         serverName,
         child,
@@ -77,6 +103,8 @@ export async function connect(serverName, config, options = {}) {
         pending: new Map(),
         nextId: 1,
         closed: false,
+        ...(logStream ? { logStream } : {}),
+        startedAt: Date.now(),
     };
     // Attach the spawn-error handler BEFORE the reader: ENOENT and similar
     // are emitted asynchronously on the next tick, and without this
@@ -184,11 +212,25 @@ export async function callTool(connection, name, args, options = {}) {
  * SIGKILL if the child has not exited. Safe to call multiple times.
  */
 export async function disconnect(connection) {
-    if (connection.closed)
+    const closeLogStream = () => {
+        const stream = connection.logStream;
+        if (!stream)
+            return;
+        try {
+            stream.end();
+        }
+        catch {
+            // Best-effort — stream may already be destroyed.
+        }
+    };
+    if (connection.closed) {
+        closeLogStream();
         return;
+    }
     const { child } = connection;
     if (child.exitCode !== null || child.killed) {
         connection.closed = true;
+        closeLogStream();
         return;
     }
     return new Promise((resolveDone) => {
@@ -198,6 +240,7 @@ export async function disconnect(connection) {
                 return;
             settled = true;
             connection.closed = true;
+            closeLogStream();
             resolveDone();
         };
         child.once('exit', settle);
@@ -223,6 +266,22 @@ export async function disconnect(connection) {
         }, SHUTDOWN_GRACE_MS);
     });
 }
+/**
+ * L13: cheap liveness probe for `pugi mcp doctor`. True when the child
+ * process is still running AND the connection has not been torn down.
+ * Does NOT issue a JSON-RPC call — that would race with in-flight tool
+ * dispatch and the doctor surface is read-only.
+ */
+export function isAlive(connection) {
+    if (connection.closed)
+        return false;
+    const { child } = connection;
+    if (child.killed)
+        return false;
+    if (child.exitCode !== null)
+        return false;
+    return true;
+}
 function writeFrame(connection, message) {
     if (connection.closed) {
         throw new Error(`mcp server "${connection.serverName}" connection is closed`);
@@ -274,11 +333,21 @@ function attachReader(connection) {
             newlineIndex = buffer.indexOf('\n');
         }
     });
-    // stderr is captured but never thrown. Some MCP servers log diagnostics
-    // there even on success; we route it to nowhere so the CLI stdout stays
-    // pure JSON envelope output. A future iteration may forward this to the
-    // audit log.
-    connection.child.stderr.on('data', () => { });
+    // stderr is captured and (when `connect({ logFile })` was set) mirrored
+    // to a per-server log file under `.pugi/logs/`. Operators can tail the
+    // file via `pugi mcp logs <server>`. Default sink remains "drop on the
+    // floor" so the CLI stdout stays pure JSON envelope output.
+    connection.child.stderr.on('data', (chunk) => {
+        const stream = connection.logStream;
+        if (!stream || stream.destroyed)
+            return;
+        try {
+            stream.write(typeof chunk === 'string' ? chunk : chunk);
+        }
+        catch {
+            // Disk full / fd revoked — drop silently. Mirroring is best-effort.
+        }
+    });
 }
 function handleLine(connection, line) {
     let parsed;