@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/core/mcp/client.js

@@ -0,0 +1,316 @@
+import { spawn } from 'node:child_process';
+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)
+ *
+ * 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),
+    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'],
+    });
+    const connection = {
+        serverName,
+        child,
+        capabilities: {},
+        pending: new Map(),
+        nextId: 1,
+        closed: false,
+    };
+    // 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) {
+    if (connection.closed)
+        return;
+    const { child } = connection;
+    if (child.exitCode !== null || child.killed) {
+        connection.closed = true;
+        return;
+    }
+    return new Promise((resolveDone) => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            connection.closed = true;
+            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);
+    });
+}
+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 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', () => { });
+}
+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

package/dist/core/mcp/registry.js

@@ -0,0 +1,171 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { connect, disconnect, listTools, mcpServerConfigSchema, } from './client.js';
+import { getMcpTrust } from './trust.js';
+/**
+ * MCP server registry — loads `.pugi/mcp.json` (workspace-scoped) and
+ * `~/.pugi/mcp.json` (user-scoped), merges with the user-level trust
+ * ledger, and surfaces approved tools into the toolRegistry shape.
+ *
+ * Load order:
+ *   1. User config (`~/.pugi/mcp.json`) — always loaded.
+ *   2. Workspace config (`<workspaceRoot>/.pugi/mcp.json`) — loaded if
+ *      present; workspace entries override user entries by name.
+ *
+ * Trust resolution:
+ *   - The trust state stored in `~/.pugi/trust-mcp.json` always wins.
+ *   - If no ledger entry exists, the file-level `trust` field acts as
+ *     the seed value (so a `~/.pugi/mcp.json` declaring `trust: trusted`
+ *     auto-approves servers the user already trusts).
+ *
+ * Surfaced tool shape (M1 minimum):
+ *   - `name`: `mcp.<server>.<tool>` (avoids collision with built-ins).
+ *   - `permission`: `mcp` (the permission engine's MCP route).
+ *   - `risk`: `medium` if server is trusted, `high` if pending/denied
+ *     (pending/denied tools are filtered before reaching surfaceTools,
+ *     so risk-high is a defensive backstop, not an exposed surface).
+ *   - `concurrencySafe`: false (MCP tools may have side effects; the
+ *     permission engine serializes them).
+ *   - `m1`: true (everything here ships in M1).
+ *
+ * The registry does NOT auto-connect to pending or denied servers. Tools
+ * surface only for `trusted` entries; everything else returns a state
+ * record with `connection: undefined` so the user can see the wiring
+ * intent without exposing pending servers to the engine loop.
+ */
+const mcpFileSchema = z.object({
+    servers: z.record(mcpServerConfigSchema).default({}),
+});
+/**
+ * Load and (optionally) connect every approved MCP server defined in the
+ * workspace + user configs. Pending and denied servers stay in the
+ * `servers` map but are NOT spawned.
+ */
+export async function loadMcpRegistry(workspaceRoot, options = {}) {
+    const shouldConnect = options.connect !== false;
+    const userConfig = readMcpFile(resolve(userHomeDir(), 'mcp.json'));
+    const workspaceConfig = readMcpFile(resolve(workspaceRoot, '.pugi/mcp.json'));
+    const merged = new Map();
+    for (const [name, config] of Object.entries(userConfig))
+        merged.set(name, config);
+    for (const [name, config] of Object.entries(workspaceConfig))
+        merged.set(name, config);
+    const servers = new Map();
+    for (const [name, config] of merged) {
+        const ledgerTrust = await getMcpTrust(name);
+        // Treat missing-ledger-entry (pending in the ledger) PLUS a trusted
+        // file-level seed as trusted. This lets a user pre-approve servers
+        // declared in their own user config without manually running the
+        // trust command for each one. Workspace-declared `trust: trusted`
+        // is NOT honoured this way — the workspace cannot opt itself in,
+        // which is the whole point of the gate.
+        const trust = await resolveTrust(name, config, ledgerTrust, userConfig);
+        const state = {
+            name,
+            config,
+            trust,
+            surfacedTools: [],
+        };
+        if (shouldConnect && trust === 'trusted') {
+            try {
+                const connection = await connect(name, config);
+                state.connection = connection;
+                state.surfacedTools = await listTools(connection);
+            }
+            catch (error) {
+                state.lastError = error instanceof Error ? error.message : String(error);
+                // Defensive: even if listTools failed mid-handshake, we still
+                // own the connection lifecycle. Tear it down so we do not leak.
+                if (state.connection) {
+                    await disconnect(state.connection).catch(() => { });
+                    delete state.connection;
+                }
+            }
+        }
+        servers.set(name, state);
+    }
+    return {
+        servers,
+        surfaceTools: () => surfaceToolDefinitions(servers),
+        shutdown: async () => {
+            await Promise.all(Array.from(servers.values()).map(async (state) => {
+                if (state.connection) {
+                    await disconnect(state.connection).catch(() => { });
+                }
+            }));
+        },
+    };
+}
+function userHomeDir() {
+    return process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+}
+function readMcpFile(path) {
+    if (!existsSync(path))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim() === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse MCP config at ${path}: ${error instanceof Error ? error.message : String(error)}. ` +
+            `Run \`pugi config mcp list\` to see the loaded servers.`);
+    }
+    const result = mcpFileSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+            .join('; ');
+        throw new Error(`MCP config at ${path} failed validation: ${issues}. ` +
+            `Expected shape: { "servers": { "<name>": { "command": "...", "args": [...], "env": {...}, "trust": "pending|trusted|denied" } } }`);
+    }
+    return result.data.servers;
+}
+async function resolveTrust(name, config, ledgerTrust, userConfig) {
+    // If the operator explicitly recorded a state, that wins.
+    // The ledger default (`pending`) only acts as the fallback when no
+    // entry exists. We cannot distinguish "no entry" from "entry says
+    // pending" via the public API by design — both are non-decisions and
+    // both should respect the seed value if it is `trusted` and the seed
+    // came from the user-level file.
+    const declaredInUserConfig = Object.prototype.hasOwnProperty.call(userConfig, name);
+    if (ledgerTrust !== 'pending')
+        return ledgerTrust;
+    if (declaredInUserConfig && config.trust === 'trusted')
+        return 'trusted';
+    if (declaredInUserConfig && config.trust === 'denied')
+        return 'denied';
+    return 'pending';
+}
+function surfaceToolDefinitions(servers) {
+    const out = [];
+    for (const state of servers.values()) {
+        if (state.trust !== 'trusted')
+            continue;
+        for (const tool of state.surfacedTools) {
+            out.push({
+                name: `mcp.${state.name}.${tool.name}`,
+                permission: 'mcp',
+                // Trusted MCP tools default to medium risk. Higher-risk
+                // classification (network egress, destructive ops) is a future
+                // iteration that requires per-tool metadata MCP does not yet
+                // standardise.
+                risk: 'medium',
+                concurrencySafe: false,
+                m1: true,
+            });
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/mcp/trust.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+/**
+ * MCP server trust ledger.
+ *
+ * Lives at `~/.pugi/trust-mcp.json` and is keyed by server name (the key
+ * used in `.pugi/mcp.json` / `~/.pugi/mcp.json` `servers` map).
+ *
+ * Trust states:
+ *   - `pending` — declared but not yet approved. Connection refused,
+ *     tools NOT surfaced to the agent.
+ *   - `trusted` — operator approved this server. Tools surface as
+ *     `mcp.<server>.<tool>` and the registry will spawn the child.
+ *   - `denied` — operator blocked this server. Connection refused.
+ *
+ * Why a separate ledger instead of mutating `.pugi/mcp.json` in place:
+ *   - `.pugi/mcp.json` is committed in some teams' workspaces. The trust
+ *     state is per-operator and must not bleed across users via git.
+ *   - `~/.pugi/trust-mcp.json` is the user-level source of truth and
+ *     overrides whatever trust value is declared in the workspace
+ *     `mcp.json`. A repo cannot opt itself in.
+ *
+ * The PUGI_HOME env var redirects the ledger path for tests.
+ */
+export const mcpTrustStateSchema = z.enum(['pending', 'trusted', 'denied']);
+const trustLedgerSchema = z.object({
+    schema: z.number().int().positive().default(1),
+    entries: z
+        .record(z.object({
+        state: mcpTrustStateSchema,
+        decidedAt: z.string().datetime(),
+        decidedBy: z.string().min(1).optional(),
+    }))
+        .default({}),
+});
+const TRUST_LEDGER_FILENAME = 'trust-mcp.json';
+function ledgerPath() {
+    const home = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(home, TRUST_LEDGER_FILENAME);
+}
+function readLedger() {
+    const path = ledgerPath();
+    if (!existsSync(path)) {
+        return { schema: 1, entries: {} };
+    }
+    const raw = readFileSync(path, 'utf8');
+    if (raw.trim() === '') {
+        return { schema: 1, entries: {} };
+    }
+    const parsed = JSON.parse(raw);
+    return trustLedgerSchema.parse(parsed);
+}
+function writeLedger(ledger) {
+    const path = ledgerPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // 0o600 — trust ledger reveals which MCP servers the operator has
+    // approved on this machine. Not secret per se, but no reason to make
+    // it world-readable either.
+    writeFileSync(path, `${JSON.stringify(ledger, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export async function getMcpTrust(serverName) {
+    const ledger = readLedger();
+    const entry = ledger.entries[serverName];
+    return entry ? entry.state : 'pending';
+}
+export async function setMcpTrust(serverName, state, decidedBy) {
+    const ledger = readLedger();
+    ledger.entries[serverName] = {
+        state,
+        decidedAt: new Date().toISOString(),
+        ...(decidedBy ? { decidedBy } : {}),
+    };
+    writeLedger(ledger);
+}
+export async function listMcpTrust() {
+    const ledger = readLedger();
+    return Object.entries(ledger.entries)
+        .map(([name, entry]) => ({
+        name,
+        state: entry.state,
+        decidedAt: entry.decidedAt,
+        ...(entry.decidedBy ? { decidedBy: entry.decidedBy } : {}),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+//# sourceMappingURL=trust.js.map