@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/core/mcp/server.js

@@ -1,397 +0,0 @@
-import { EventEmitter } from 'node:events';
-/**
- * Pugi MCP server (β4 M2) — exposes Pugi's native tool surface to other
- * agents (the upstream tool, peer tooling, peer CLI, any client that speaks
- * MCP).
- *
- * Transport-agnostic core. The stdio entry-point lives at the bottom of
- * this module (`serveStdio`); the HTTP+SSE wrapper lives in
- * `./http-server.ts` and feeds the same core via the synchronous
- * `handleMessage` entry-point.
- *
- * Spec: https://modelcontextprotocol.io/specification (2024-11-05).
- *
- * Methods implemented:
- *  - `initialize`              -> protocol handshake, server capabilities
- *  - `notifications/initialized` -> ack, no-op
- *  - `tools/list`              -> Pugi tool schemas
- *  - `tools/call`              -> dispatch to the underlying executor
- *  - `ping`                    -> liveness, returns `{}` (some MCP clients
- *                                  poll this on a HTTP transport)
- *
- * NOT yet implemented (deferred — these are not on the β4 acceptance
- * surface):
- *  - `resources/*`             — file resource browser
- *  - `prompts/*`               — server-supplied prompts
- *  - `sampling/*`              — agent sampling callbacks
- *  - `notifications/cancelled` — client-side cancellation (we honour
- *                                  the AbortSignal passed at construction
- *                                  instead)
- *
- * Why hand-rolled instead of `@modelcontextprotocol/sdk`:
- *  - The SDK ships every transport (stdio, HTTP, WebSocket, SSE) and
- *    drags in a 3 MB compressed dependency footprint. Pugi-CLI ships as
- *    `npm i -g pugi` and every transitive dep is supply-chain risk.
- *  - The core JSON-RPC envelope is <500 LOC and we already maintain the
- *    client-side variant in `./client.ts` — keeping the server matching
- *    hand-roll lets a code reviewer hold both sides of the wire in one
- *    head.
- *  - Pugi-specific extensions (permission FSM hooks on `tools/call`,
- *    bearer-auth attestation on HTTP, scope-limited tool filtering for
- *    paired-agent worktrees) drop in cleanly because we own the
- *    dispatch table.
- */
-/* ---------- protocol types (mirror client.ts conventions) ----------------- */
-export const PUGI_MCP_PROTOCOL_VERSION = '2024-11-05';
-export const PUGI_MCP_SERVER_NAME = 'pugi';
-export const PUGI_MCP_SERVER_VERSION = '0.1.0';
-/** JSON-RPC standard error codes used by the server. */
-export const MCP_ERROR_CODES = Object.freeze({
-    PARSE_ERROR: -32700,
-    INVALID_REQUEST: -32600,
-    METHOD_NOT_FOUND: -32601,
-    INVALID_PARAMS: -32602,
-    INTERNAL_ERROR: -32603,
-    /**
-     * Pugi-specific: operator-side permission gate refused this tool call.
-     * Distinct from generic INTERNAL_ERROR so MCP clients can surface a
-     * "permission denied" status to their user.
-     */
-    PERMISSION_REFUSED: -32001,
-    /**
-     * Pugi-specific: HTTP transport saw an invalid or missing bearer
-     * token. Stdio transport never emits this code (no auth).
-     */
-    AUTH_REQUIRED: -32002,
-});
-export class McpServerToolError extends Error {
-    code;
-    constructor(message, code = MCP_ERROR_CODES.INTERNAL_ERROR) {
-        super(message);
-        this.name = 'McpServerToolError';
-        this.code = code;
-    }
-}
-/**
- * Build a Pugi MCP server bound to a fixed tool surface. Stateless
- * between requests — the same instance can drive many concurrent stdio
- * connections (one per child process) without cross-talk.
- */
-export function createPugiMcpServer(options) {
-    const events = new EventEmitter();
-    // Build a lookup by name once at construction. Duplicate names are a
-    // programmer error and we throw eagerly so the bug surfaces in the
-    // boot path, not at the first `tools/call`.
-    const byName = new Map();
-    for (const tool of options.tools) {
-        // Reject names that would re-encode as MCP `mcp__<server>__<tool>`
-        // false-positively on the consumer side — a server name containing
-        // `__` makes parseMcpToolName misalign the split. We surface the
-        // bug here, not at first dispatch. β4 r1 P2.
-        if (tool.name.includes('__')) {
-            throw new Error(`pugi mcp server: tool name "${tool.name}" must not contain "__" (collides with mcp__<server>__<tool> naming)`);
-        }
-        if (byName.has(tool.name)) {
-            throw new Error(`pugi mcp server: duplicate tool name "${tool.name}" — every tool in the surface must be unique`);
-        }
-        byName.set(tool.name, tool);
-    }
-    const tools = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
-    const log = options.log ?? (() => { });
-    if (typeof options.permissionGate !== 'function') {
-        throw new Error('pugi mcp server: options.permissionGate is required (β4 r1 P1 #2 — no implicit allow-all default)');
-    }
-    const permissionGate = options.permissionGate;
-    const requireInitialized = options.requireInitialized !== false;
-    let initialized = false;
-    async function dispatch(method, params, clientId) {
-        switch (method) {
-            case 'initialize': {
-                // The MCP spec permits multiple `initialize` calls before
-                // `notifications/initialized` settles the handshake — we just
-                // re-affirm. After init, repeated `initialize` is harmless on
-                // our side and lets the client recover from a state desync.
-                return {
-                    protocolVersion: PUGI_MCP_PROTOCOL_VERSION,
-                    capabilities: {
-                        tools: { listChanged: false },
-                    },
-                    serverInfo: {
-                        name: PUGI_MCP_SERVER_NAME,
-                        version: PUGI_MCP_SERVER_VERSION,
-                    },
-                };
-            }
-            case 'ping': {
-                return {};
-            }
-            case 'tools/list': {
-                return {
-                    tools: tools.map((tool) => ({
-                        name: tool.name,
-                        description: tool.description,
-                        inputSchema: tool.inputSchema,
-                    })),
-                };
-            }
-            case 'tools/call': {
-                if (options.signal?.aborted) {
-                    throw new McpServerToolError('server shutting down', MCP_ERROR_CODES.INTERNAL_ERROR);
-                }
-                // β4 r1 P2 — require `initialize` + `notifications/initialized`
-                // handshake first. Without this, an attacker with the bearer
-                // token can dispatch a `tools/call` without ever advertising
-                // client capabilities; the MCP spec mandates the handshake.
-                if (requireInitialized && !initialized) {
-                    throw new McpServerToolError('tools/call: MCP handshake not complete — send `initialize` + `notifications/initialized` first', MCP_ERROR_CODES.INVALID_REQUEST);
-                }
-                const p = (params ?? {});
-                const rawName = p['name'];
-                if (typeof rawName !== 'string') {
-                    throw new McpServerToolError('tools/call: params.name (string) is required', MCP_ERROR_CODES.INVALID_PARAMS);
-                }
-                // Trim whitespace-only names so the lookup fails fast with
-                // METHOD_NOT_FOUND instead of silently matching an entry that
-                // happens to share leading/trailing whitespace. β4 r1 P2.
-                const toolName = rawName.trim();
-                if (toolName.length === 0) {
-                    throw new McpServerToolError('tools/call: params.name (string) is required', MCP_ERROR_CODES.INVALID_PARAMS);
-                }
-                const tool = byName.get(toolName);
-                if (!tool) {
-                    throw new McpServerToolError(`tools/call: tool "${toolName}" is not registered`, MCP_ERROR_CODES.METHOD_NOT_FOUND);
-                }
-                const rawArgs = p['arguments'];
-                let args;
-                if (rawArgs === undefined || rawArgs === null) {
-                    args = {};
-                }
-                else if (typeof rawArgs === 'object' && !Array.isArray(rawArgs)) {
-                    args = rawArgs;
-                }
-                else {
-                    throw new McpServerToolError('tools/call: params.arguments must be a JSON object', MCP_ERROR_CODES.INVALID_PARAMS);
-                }
-                const allowed = await permissionGate({
-                    tool,
-                    arguments: args,
-                    ...(clientId ? { clientId } : {}),
-                });
-                if (!allowed) {
-                    log('warn', `permission refused: ${tool.name}`);
-                    throw new McpServerToolError(`permission refused by operator: ${tool.name}`, MCP_ERROR_CODES.PERMISSION_REFUSED);
-                }
-                // Stamp clientId on emitted events so the HTTP transport can
-                // route them to the originating SSE listener instead of
-                // broadcasting to every bearer-holder (β4 r1 P1 #5).
-                events.emit('tool_call', {
-                    name: tool.name,
-                    args,
-                    ...(clientId ? { clientId } : {}),
-                });
-                try {
-                    const text = await tool.execute(args);
-                    events.emit('tool_result', {
-                        name: tool.name,
-                        ok: true,
-                        summary: text.slice(0, 200),
-                        ...(clientId ? { clientId } : {}),
-                    });
-                    return {
-                        content: [{ type: 'text', text }],
-                        isError: false,
-                    };
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    events.emit('tool_result', {
-                        name: tool.name,
-                        ok: false,
-                        summary: message.slice(0, 200),
-                        ...(clientId ? { clientId } : {}),
-                    });
-                    // Tool-level failures surface as MCP `isError: true` content —
-                    // the client knows the call ran but failed, distinct from a
-                    // protocol-level error (bad tool name, malformed params).
-                    return {
-                        content: [{ type: 'text', text: message }],
-                        isError: true,
-                    };
-                }
-            }
-            case 'notifications/initialized': {
-                initialized = true;
-                events.emit('initialized');
-                return null;
-            }
-            default: {
-                if (method.startsWith('notifications/')) {
-                    // Silently accept unknown notifications — the spec requires
-                    // they be ignored, not errored.
-                    return null;
-                }
-                throw new McpServerToolError(`method not found: ${method}`, MCP_ERROR_CODES.METHOD_NOT_FOUND);
-            }
-        }
-    }
-    async function handleMessage(request) {
-        const clientId = request.meta?.clientId;
-        // Notifications never get a response.
-        const isNotification = request.id === undefined || request.id === null;
-        if (isNotification) {
-            try {
-                await dispatch(request.method, request.params, clientId);
-            }
-            catch (error) {
-                log('error', `notification handler threw: ${error.message}`);
-            }
-            return null;
-        }
-        const id = request.id;
-        try {
-            const result = await dispatch(request.method, request.params, clientId);
-            // dispatch may return null for void responses (notifications) —
-            // but we already filtered those above. Treat null here as `{}`.
-            return {
-                jsonrpc: '2.0',
-                id,
-                result: result ?? {},
-            };
-        }
-        catch (error) {
-            const isToolError = error instanceof McpServerToolError;
-            const code = isToolError ? error.code : MCP_ERROR_CODES.INTERNAL_ERROR;
-            const message = error instanceof Error ? error.message : String(error);
-            log('error', `dispatch ${request.method} (id=${id}) failed: ${message}`);
-            return {
-                jsonrpc: '2.0',
-                id,
-                error: { code, message },
-            };
-        }
-    }
-    return {
-        handleMessage,
-        events,
-        listToolsSync() {
-            return tools.slice();
-        },
-        // Internal: exposed to tests via type assertion when they want to
-        // verify the initialized flag advanced. Not part of the public
-        // interface intentionally — production callers should listen on
-        // `events` instead.
-        // @ts-expect-error — debug accessor
-        _isInitialized() {
-            return initialized;
-        },
-    };
-}
-/**
- * Run the server on stdio. Reads one JSON-RPC line per request from
- * stdin, writes the response (or nothing for notifications) as one line
- * to stdout. Lines are `\n`-terminated UTF-8 JSON.
- *
- * Returns a promise that resolves when stdin closes. The caller can race
- * it against `signal` to force shutdown — the stdio reader is shielded
- * by the same signal, so an abort terminates the line loop cleanly.
- */
-export async function serveStdio(options) {
-    const stdin = options.stdin ?? process.stdin;
-    const stdout = options.stdout ?? process.stdout;
-    const { server, signal } = options;
-    return new Promise((resolve) => {
-        let buffer = '';
-        let closed = false;
-        const finish = () => {
-            if (closed)
-                return;
-            closed = true;
-            stdin.off('data', onData);
-            stdin.off('end', finish);
-            stdin.off('close', finish);
-            if (signal) {
-                signal.removeEventListener('abort', finish);
-            }
-            resolve();
-        };
-        const writeFrame = (response) => {
-            stdout.write(`${JSON.stringify(response)}\n`);
-        };
-        const writeParseError = (id, message) => {
-            writeFrame({
-                jsonrpc: '2.0',
-                id,
-                error: { code: MCP_ERROR_CODES.PARSE_ERROR, message },
-            });
-        };
-        const processLine = async (line) => {
-            const trimmed = line.trim();
-            if (trimmed.length === 0)
-                return;
-            let parsed;
-            try {
-                parsed = JSON.parse(trimmed);
-            }
-            catch (error) {
-                writeParseError(null, `invalid JSON: ${error.message}`);
-                return;
-            }
-            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-                writeParseError(null, 'request must be a JSON object');
-                return;
-            }
-            const candidate = parsed;
-            if (candidate.jsonrpc !== '2.0' || typeof candidate.method !== 'string') {
-                writeParseError(typeof candidate.id === 'number' || typeof candidate.id === 'string'
-                    ? candidate.id
-                    : null, 'invalid JSON-RPC envelope: jsonrpc=2.0 + string method required');
-                return;
-            }
-            // Stdio is a single-tenant transport — the parent process owns
-            // both ends — so we intentionally drop any inbound `meta.clientId`.
-            // Per-connection scoping only makes sense for HTTP+SSE.
-            const request = {
-                jsonrpc: '2.0',
-                method: candidate.method,
-                ...(candidate.id !== undefined ? { id: candidate.id } : {}),
-                ...(candidate.params !== undefined ? { params: candidate.params } : {}),
-            };
-            const response = await server.handleMessage(request);
-            if (response)
-                writeFrame(response);
-        };
-        const onData = (chunk) => {
-            buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
-            let newlineIndex = buffer.indexOf('\n');
-            while (newlineIndex !== -1) {
-                const line = buffer.slice(0, newlineIndex);
-                buffer = buffer.slice(newlineIndex + 1);
-                // Fire-and-forget the line handler; ordering of responses
-                // matches request ordering at the protocol level because the
-                // dispatch is microtask-serialized via the await above for
-                // each line — Node iterates `data` callbacks synchronously,
-                // and processLine awaits the dispatcher before returning so
-                // the next iteration of the loop sees the prior one settled.
-                void processLine(line);
-                newlineIndex = buffer.indexOf('\n');
-            }
-        };
-        if (signal) {
-            if (signal.aborted) {
-                finish();
-                return;
-            }
-            signal.addEventListener('abort', finish, { once: true });
-        }
-        if (!stdin.readable) {
-            // Stream already closed (e.g. parent piped EOF immediately).
-            finish();
-            return;
-        }
-        stdin.setEncoding('utf8');
-        stdin.on('data', onData);
-        stdin.on('end', finish);
-        stdin.on('close', finish);
-    });
-}
-//# sourceMappingURL=server.js.map

package/dist/core/mcp/trust.js

@@ -1,91 +0,0 @@
-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