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

package/dist/core/mcp/client.js

@@ -1,15 +1,16 @@
 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.
  *
  * Spec reference: https://modelcontextprotocol.io/specification
  *
- * Scope deliberately narrowed to what the CLI needs for α5.6:
- *   - initialize handshake (protocol version + capabilities exchange)
- *   - tools/list
- *   - tools/call
- *   - graceful shutdown (SIGTERM, 5s grace, SIGKILL)
+ * Scope deliberately narrowed to what the CLI needs for :
+ *  - initialize handshake (protocol version + capabilities exchange)
+ *  - tools/list
+ *  - tools/call
+ *  - graceful shutdown (SIGTERM, 5s grace, SIGKILL)
  *
  * NOT implemented for M1: resources, prompts, sampling, notifications, SSE
  * transport, batching, progress tokens. Those layer onto this surface later
@@ -18,29 +19,38 @@ import { z } from 'zod';
  * extend `RpcMethod` and the response parsers.
  *
  * Why hand-roll instead of `@modelcontextprotocol/sdk`:
- *   - The official SDK is ~3 MB compressed and pulls in 30+ transitive deps
- *     to support every transport. The CLI ships as `npm i -g pugi` and every
- *     dep is a maintenance + supply-chain risk. Hand-rolled JSON-RPC over
- *     stdio is <200 LOC; that is the right tradeoff for an alpha that ships.
- *   - We retain wire-level control to add Pugi-specific extensions later
- *     (per-call permission gates, trust-aware tool filtering at the
- *     transport layer) without forking the SDK.
+ *  - The official SDK is ~3 MB compressed and pulls in 30+ transitive deps
+ *    to support every transport. The CLI ships as `npm i -g pugi` and every
+ *    dep is a maintenance + supply-chain risk. Hand-rolled JSON-RPC over
+ *    stdio is <200 LOC; that is the right tradeoff for an alpha that ships.
+ *  - We retain wire-level control to add Pugi-specific extensions later
+ *    (per-call permission gates, trust-aware tool filtering at the
+ *    transport layer) without forking the SDK.
  *
  * Strict typing notes:
- *   - All wire messages parse through Zod before reaching consumer code.
- *   - `unknown` is preferred over `any` in every public surface.
- *   - Timeouts are mandatory; a stuck child process never blocks the CLI
- *     forever.
+ *  - All wire messages parse through Zod before reaching consumer code.
+ *  - `unknown` is preferred over `any` in every public surface.
+ *  - Timeouts are mandatory; a stuck child process never blocks the CLI
+ *    forever.
  */
 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({}),
     /**
      * Per-server trust state. Mirrors `trust.ts` ledger semantics:
-     *   - `pending` — declared but not yet approved. Connections refused.
-     *   - `trusted` — operator has approved this server's command line.
-     *   - `denied` — operator explicitly blocked it; never auto-connect.
+     *  - `pending` — declared but not yet approved. Connections refused.
+     *  - `trusted` — operator has approved this server's command line.
+     *  - `denied` — operator explicitly blocked it; never auto-connect.
      *
      * Note this is the runtime trust state stored INSIDE `.pugi/mcp.json` /
      * `~/.pugi/mcp.json`. The trust LEDGER at `~/.pugi/trust-mcp.json` is the
@@ -59,9 +69,9 @@ const SHUTDOWN_GRACE_MS = 5_000;
  * Spawn an MCP server child process and complete the initialize handshake.
  *
  * Throws if:
- *   - the child fails to spawn (ENOENT, permission denied, etc),
- *   - the initialize response does not arrive within the timeout,
- *   - the server returns a JSON-RPC error in response to initialize.
+ *  - the child fails to spawn (ENOENT, permission denied, etc),
+ *  - the initialize response does not arrive within the timeout,
+ *  - the server returns a JSON-RPC error in response to initialize.
  *
  * The caller is responsible for calling `disconnect` to free the child.
  */
@@ -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;