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

package/dist/core/mcp/client.js

@@ -1,385 +0,0 @@
-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 :
- *  - 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
- * without a wire-format break — the request/response correlation table is
- * id-based and the transport is line-delimited JSON, so additions only
- * 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.
- *
- * 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.
- */
-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.
-     *
-     * 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
-     * source of truth and overrides the file-level value at load time.
-     */
-    trust: z.enum(['pending', 'trusted', 'denied']).default('pending'),
-});
-export const mcpToolSchema = z.object({
-    name: z.string().min(1),
-    description: z.string().optional(),
-    inputSchema: z.unknown().optional(),
-});
-const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
-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 caller is responsible for calling `disconnect` to free the child.
- */
-export async function connect(serverName, config, options = {}) {
-    const child = spawn(config.command, config.args, {
-        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,
-        capabilities: {},
-        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
-    // listener Node converts them to uncaughtException which crashes the
-    // test runner even when our caller already awaited the rejection.
-    let spawnError = null;
-    child.on('error', (error) => {
-        spawnError = error;
-        connection.closed = true;
-        for (const call of connection.pending.values()) {
-            clearTimeout(call.timeoutHandle);
-            call.reject(error);
-        }
-        connection.pending.clear();
-    });
-    attachReader(connection);
-    // Give the spawn `error` event a tick to fire if the binary cannot be
-    // started. Without this `child.pid` reads as undefined and we'd throw
-    // a different error message before the actual ENOENT surfaces.
-    await new Promise((tickResolve) => setImmediate(tickResolve));
-    if (spawnError) {
-        throw new Error(`mcp server "${serverName}" failed to spawn: ${spawnError.message}`);
-    }
-    // Surface spawn failures synchronously when possible. `child.pid` is
-    // undefined when the runtime could not start the binary at all.
-    if (!child.pid) {
-        throw new Error(`mcp server "${serverName}" failed to spawn: ${config.command}`);
-    }
-    child.on('exit', (code) => {
-        connection.closed = true;
-        for (const call of connection.pending.values()) {
-            clearTimeout(call.timeoutHandle);
-            call.reject(new Error(`mcp server "${serverName}" exited (code ${code ?? 'null'}) before responding to ${call.method}`));
-        }
-        connection.pending.clear();
-    });
-    const initResponse = await send(connection, 'initialize', {
-        protocolVersion: '2024-11-05',
-        capabilities: {
-            tools: {},
-        },
-        clientInfo: {
-            name: 'pugi-cli',
-            version: '0.1',
-        },
-    }, options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
-    if (initResponse && typeof initResponse === 'object' && !Array.isArray(initResponse)) {
-        const caps = initResponse.capabilities;
-        if (caps && typeof caps === 'object' && !Array.isArray(caps)) {
-            Object.assign(connection.capabilities, caps);
-        }
-    }
-    // MCP requires a `notifications/initialized` notification after the
-    // handshake response. We fire and forget — notifications have no id and
-    // no response to await.
-    writeFrame(connection, {
-        jsonrpc: '2.0',
-        method: 'notifications/initialized',
-        params: {},
-    });
-    return connection;
-}
-/**
- * List tools exposed by the connected MCP server.
- */
-export async function listTools(connection) {
-    const response = await send(connection, 'tools/list', {}, DEFAULT_REQUEST_TIMEOUT_MS);
-    if (!response || typeof response !== 'object' || Array.isArray(response)) {
-        throw new Error(`mcp server "${connection.serverName}" returned malformed tools/list response`);
-    }
-    const tools = response.tools;
-    if (!Array.isArray(tools)) {
-        throw new Error(`mcp server "${connection.serverName}" tools/list missing tools array`);
-    }
-    const parsed = [];
-    for (const candidate of tools) {
-        const result = mcpToolSchema.safeParse(candidate);
-        if (result.success) {
-            parsed.push(result.data);
-        }
-    }
-    return parsed;
-}
-/**
- * Invoke a tool exposed by the connected MCP server. Returns the raw
- * `content` payload from the server plus `isError` flag.
- */
-export async function callTool(connection, name, args, options = {}) {
-    const response = await send(connection, 'tools/call', { name, arguments: args }, options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
-    if (!response || typeof response !== 'object' || Array.isArray(response)) {
-        return {
-            content: response ?? null,
-            isError: true,
-        };
-    }
-    const obj = response;
-    const isError = obj.isError === true;
-    return {
-        content: obj.content ?? null,
-        isError,
-    };
-}
-/**
- * Tear down the connection: SIGTERM, wait up to SHUTDOWN_GRACE_MS, then
- * SIGKILL if the child has not exited. Safe to call multiple times.
- */
-export async function disconnect(connection) {
-    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) => {
-        let settled = false;
-        const settle = () => {
-            if (settled)
-                return;
-            settled = true;
-            connection.closed = true;
-            closeLogStream();
-            resolveDone();
-        };
-        child.once('exit', settle);
-        try {
-            child.kill('SIGTERM');
-        }
-        catch {
-            // Already dead. Still wait for the exit event so the caller does
-            // not see a partially-torn-down connection.
-        }
-        setTimeout(() => {
-            if (settled)
-                return;
-            try {
-                child.kill('SIGKILL');
-            }
-            catch {
-                // ignore — process is already gone
-            }
-            // Force-resolve even if the exit event never fires (extremely
-            // rare on a SIGKILL'd child, but defend against it).
-            setTimeout(settle, 200);
-        }, 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`);
-    }
-    const line = `${JSON.stringify(message)}\n`;
-    connection.child.stdin.write(line);
-}
-async function send(connection, method, params, timeoutMs) {
-    const id = connection.nextId++;
-    const request = {
-        jsonrpc: '2.0',
-        id,
-        method,
-        params,
-    };
-    return new Promise((resolveCall, rejectCall) => {
-        const timeoutHandle = setTimeout(() => {
-            connection.pending.delete(id);
-            rejectCall(new Error(`mcp server "${connection.serverName}" timed out after ${timeoutMs}ms on ${method}`));
-        }, timeoutMs);
-        connection.pending.set(id, {
-            resolve: resolveCall,
-            reject: rejectCall,
-            method,
-            timeoutHandle,
-        });
-        try {
-            writeFrame(connection, request);
-        }
-        catch (error) {
-            clearTimeout(timeoutHandle);
-            connection.pending.delete(id);
-            rejectCall(error instanceof Error ? error : new Error(String(error)));
-        }
-    });
-}
-function attachReader(connection) {
-    let buffer = '';
-    connection.child.stdout.setEncoding('utf8');
-    connection.child.stdout.on('data', (chunk) => {
-        buffer += chunk;
-        let newlineIndex = buffer.indexOf('\n');
-        while (newlineIndex !== -1) {
-            const line = buffer.slice(0, newlineIndex).trim();
-            buffer = buffer.slice(newlineIndex + 1);
-            if (line.length > 0) {
-                handleLine(connection, line);
-            }
-            newlineIndex = buffer.indexOf('\n');
-        }
-    });
-    // 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;
-    try {
-        parsed = JSON.parse(line);
-    }
-    catch {
-        // Malformed line from the server. Drop it and continue — a partial
-        // frame at the start of the stream is the common cause.
-        return;
-    }
-    if (!parsed || typeof parsed !== 'object')
-        return;
-    const message = parsed;
-    // Notifications (no `id`) are dropped at M1 — we do not subscribe to
-    // server-pushed events yet.
-    if (typeof message.id !== 'number')
-        return;
-    const pending = connection.pending.get(message.id);
-    if (!pending)
-        return;
-    clearTimeout(pending.timeoutHandle);
-    connection.pending.delete(message.id);
-    if ('error' in message && message.error) {
-        const err = message.error;
-        pending.reject(new Error(`mcp server "${connection.serverName}" returned error on ${pending.method}: ${err.message} (code ${err.code})`));
-        return;
-    }
-    if ('result' in message) {
-        pending.resolve(message.result);
-        return;
-    }
-    pending.reject(new Error(`mcp server "${connection.serverName}" sent response without result or error for ${pending.method}`));
-}
-//# sourceMappingURL=client.js.map