@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/mcp/permission.js

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+/**
+ * Per-server-tool permission cache for MCP-invoked tools (β4 M4 + M5).
+ *
+ * Trust ledger (`~/.pugi/trust-mcp.json`, see `./trust.ts`) gates the
+ * SERVER. A trusted server can spawn and surface its tools to the engine
+ * loop. But each individual TOOL invocation still flows through the 6-mode
+ * permission FSM the same way native tools do — the operator's first
+ * `mcp__github__create_issue` call should prompt even if `github` is
+ * server-trusted.
+ *
+ * This module records the operator's per-(server, tool) decisions so the
+ * second invocation in the same FSM mode does not re-prompt. The cache
+ * lives at `~/.pugi/mcp-perms.json` and is keyed by `<server>:<tool>`.
+ *
+ * Decision states:
+ *  - `allow_once`  — approved for this dispatch only. NOT persisted;
+ *                     the cache key is removed after the call returns.
+ *                     Returned by `consumeOnceDecision` so the executor
+ *                     can flip back to `unset` mid-flight.
+ *  - `allow_always` — operator allowed every future call to this
+ *                     (server, tool) pair. Persisted.
+ *  - `deny`        — operator blocked every future call to this
+ *                     (server, tool) pair. Persisted.
+ *  - `unset`       — no decision yet. Caller MUST prompt.
+ *
+ * The cache is independent from the permission FSM mode (auto/manual/
+ * dry-run/etc). The FSM decides WHETHER to prompt; this cache only
+ * remembers the operator's answer for next time.
+ *
+ * Why a separate cache instead of folding into trust.ts:
+ *  - trust.ts tracks SERVER trust (one decision per server). Adding tool
+ *    keys there would explode the surface and confuse the (already
+ *    subtle) workspace-vs-ledger override rules.
+ *  - Tool-level decisions are cheaper to forget — the operator can blow
+ *    away `~/.pugi/mcp-perms.json` without losing server trust.
+ *
+ * The PUGI_HOME env var redirects the cache path for tests.
+ */
+export const mcpPermissionDecisionSchema = z.enum(['allow_once', 'allow_always', 'deny', 'unset']);
+const permissionCacheSchema = z.object({
+    schema: z.number().int().positive().default(1),
+    entries: z
+        .record(z.object({
+        // Cache only persists `allow_always` and `deny`. `allow_once` is
+        // removed after consumption; `unset` is the absence of an entry.
+        decision: z.enum(['allow_always', 'deny']),
+        decidedAt: z.string().datetime(),
+        decidedBy: z.string().min(1).optional(),
+    }))
+        .default({}),
+});
+const PERMISSION_CACHE_FILENAME = 'mcp-perms.json';
+function cachePath() {
+    const home = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(home, PERMISSION_CACHE_FILENAME);
+}
+function keyFor(serverName, toolName) {
+    // Colon-separated. Both halves are already non-empty (Zod-validated on
+    // the calling side), so collision via empty halves is impossible.
+    return `${serverName}:${toolName}`;
+}
+function readCache() {
+    const path = cachePath();
+    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 permissionCacheSchema.parse(parsed);
+}
+function writeCache(cache) {
+    const path = cachePath();
+    // 0o700 on the parent dir — same surface as `~/.ssh` / `~/.gnupg`.
+    // Other local users have no business knowing which MCP tools we approved.
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    // Atomic rewrite via tmp + rename. Mirrors the history.ts pattern.
+    // Without this, two concurrent `setMcpPermission` calls race — second
+    // writer truncates the file mid-flush of the first and one decision is
+    // silently lost. See β4 r1 P1 #3 (Backend Architect triple-review).
+    const tmpPath = `${path}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 10)}`;
+    // 0o600 — the cache leaks which (server, tool) pairs the operator has
+    // approved. Not secret, but no reason to expose to other local users.
+    writeFileSync(tmpPath, `${JSON.stringify(cache, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    renameSync(tmpPath, path);
+}
+/**
+ * Return the cached decision for `(serverName, toolName)`. Absence
+ * returns `unset` so the caller knows to prompt.
+ */
+export function getMcpPermission(serverName, toolName) {
+    const cache = readCache();
+    const entry = cache.entries[keyFor(serverName, toolName)];
+    return entry ? entry.decision : 'unset';
+}
+/**
+ * Tool names that accept free-form `command` strings (bash and any
+ * future shell-class tools). Granting `allow_always` to these turns the
+ * MCP cache into a permanent shell grant for the caller agent — a
+ * single approval becomes an unlimited remote-execution capability.
+ *
+ * Source of the lock: β4 r1 P1 #1 (Backend Architect triple-review).
+ * The classifier still runs per-invocation for ALL bash classes, but
+ * with `allow_always` cached the FSM never re-prompts on the next call,
+ * so the operator effectively pre-approves every future command the
+ * agent ships through that tool.
+ */
+const SHELL_LIKE_TOOL_NAMES = new Set([
+    'bash',
+    // Reserved for future shell-class tools (e.g. `exec`, `shell`,
+    // `run_shell`). Anything that ultimately spawns a process from
+    // attacker-controllable text belongs here.
+    'exec',
+    'shell',
+    'run_shell',
+]);
+/**
+ * Throw when an operator tries to grant `allow_always` to a tool that
+ * accepts free-form shell input. Pugi MCP server's built-in `bash` tool
+ * and any external MCP server's `bash` / `exec` tool are blocked from
+ * the always-allow escape. The operator must accept each command via
+ * `allow_once` (which forces the per-call classifier prompt).
+ */
+export function assertAllowAlwaysAllowed(toolName, decision) {
+    if (decision !== 'allow_always')
+        return;
+    if (SHELL_LIKE_TOOL_NAMES.has(toolName)) {
+        throw new Error(`pugi mcp: refusing to cache "allow_always" for shell-class tool "${toolName}". ` +
+            `Free-form shell tools must re-prompt per call. Use "allow_once" instead, or grant ` +
+            `the underlying capability via project settings.`);
+    }
+}
+/**
+ * Persist a long-lived decision. `allow_once` is never persisted — it is
+ * a transient state the caller manages in-process. Shell-class tools
+ * (bash and friends) refuse `allow_always` — see `assertAllowAlwaysAllowed`.
+ */
+export function setMcpPermission(serverName, toolName, decision, decidedBy) {
+    assertAllowAlwaysAllowed(toolName, decision);
+    const cache = readCache();
+    cache.entries[keyFor(serverName, toolName)] = {
+        decision,
+        decidedAt: new Date().toISOString(),
+        ...(decidedBy ? { decidedBy } : {}),
+    };
+    writeCache(cache);
+}
+/**
+ * Forget a previously-stored decision so the next invocation prompts
+ * again. Returns true when an entry existed, false otherwise. Used by
+ * `pugi mcp perms reset <server>:<tool>` (β4b, deferred) and by tests.
+ */
+export function clearMcpPermission(serverName, toolName) {
+    const cache = readCache();
+    const key = keyFor(serverName, toolName);
+    if (!(key in cache.entries))
+        return false;
+    delete cache.entries[key];
+    writeCache(cache);
+    return true;
+}
+/**
+ * List every persisted permission decision. Used by
+ * `pugi mcp perms list` (deferred) and by tests.
+ */
+export function listMcpPermissions() {
+    const cache = readCache();
+    return Object.entries(cache.entries)
+        .map(([key, entry]) => {
+        const idx = key.indexOf(':');
+        const server = idx === -1 ? key : key.slice(0, idx);
+        const tool = idx === -1 ? '' : key.slice(idx + 1);
+        return {
+            server,
+            tool,
+            decision: entry.decision,
+            decidedAt: entry.decidedAt,
+            ...(entry.decidedBy ? { decidedBy: entry.decidedBy } : {}),
+        };
+    })
+        .sort((a, b) => a.server === b.server ? a.tool.localeCompare(b.tool) : a.server.localeCompare(b.server));
+}
+//# sourceMappingURL=permission.js.map

package/dist/core/mcp/registry.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { z } from 'zod';
@@ -10,25 +10,25 @@ import { getMcpTrust } from './trust.js';
  * 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.
+ *  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).
+ *  - 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).
+ *  - `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
@@ -38,6 +38,13 @@ import { getMcpTrust } from './trust.js';
 const mcpFileSchema = z.object({
     servers: z.record(mcpServerConfigSchema).default({}),
 });
+/**
+ * L13: workspace-relative path for per-server log files. Surfaces in
+ * `pugi mcp logs <name>` and is mkdir -p'd before the first connect.
+ */
+export function mcpLogPath(workspaceRoot, serverName) {
+    return resolve(workspaceRoot, '.pugi/logs', `mcp-${serverName}.log`);
+}
 /**
  * Load and (optionally) connect every approved MCP server defined in the
  * workspace + user configs. Pending and denied servers stay in the
@@ -45,6 +52,7 @@ const mcpFileSchema = z.object({
  */
 export async function loadMcpRegistry(workspaceRoot, options = {}) {
     const shouldConnect = options.connect !== false;
+    const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5_000;
     const userConfig = readMcpFile(resolve(userHomeDir(), 'mcp.json'));
     const workspaceConfig = readMcpFile(resolve(workspaceRoot, '.pugi/mcp.json'));
     const merged = new Map();
@@ -52,6 +60,17 @@ export async function loadMcpRegistry(workspaceRoot, options = {}) {
         merged.set(name, config);
     for (const [name, config] of Object.entries(workspaceConfig))
         merged.set(name, config);
+    // L13: ensure the log dir exists once per session so per-server log
+    // streams can `append` without each one having to mkdir -p.
+    if (shouldConnect && merged.size > 0) {
+        try {
+            mkdirSync(resolve(workspaceRoot, '.pugi/logs'), { recursive: true });
+        }
+        catch {
+            // Workspace may be read-only (CI sandbox). Log routing degrades
+            // silently in that case — see `client.ts::connect`.
+        }
+    }
     const servers = new Map();
     for (const [name, config] of merged) {
         const ledgerTrust = await getMcpTrust(name);
@@ -70,7 +89,10 @@ export async function loadMcpRegistry(workspaceRoot, options = {}) {
         };
         if (shouldConnect && trust === 'trusted') {
             try {
-                const connection = await connect(name, config);
+                const connection = await connect(name, config, {
+                    timeoutMs: handshakeTimeoutMs,
+                    logFile: mcpLogPath(workspaceRoot, name),
+                });
                 state.connection = connection;
                 state.surfacedTools = await listTools(connection);
             }

package/dist/core/mcp/server-tools.js

@@ -0,0 +1,219 @@
+import { editTool, globTool, grepTool, readTool, writeTool, } from '../../tools/file-tools.js';
+import { bashToolSync } from '../../tools/bash.js';
+/**
+ * Native Pugi tool surface exposed via MCP server (β4 M2/M6).
+ *
+ * The shapes intentionally mirror the engine-loop tool schemas in
+ * `core/engine/tool-bridge.ts` so an MCP client and the Pugi engine see
+ * the same parameter contracts. This is the "Pugi as MCP server"
+ * surface — other agents (the upstream tool, Codex, OpenCode) call these to
+ * read / mutate the workspace through us, with all our security gates
+ * (path containment, plan-mode refusal, bash classifier, settings) in
+ * the loop.
+ *
+ * Why a separate builder instead of reusing buildExecutor:
+ *  - The engine loop expects an OpenAI-shaped tool-call envelope plus
+ *    a workspace session. The MCP server exposes named tools to
+ *    external agents with no Pugi session context — sessions live in
+ *    `.pugi/sessions/<id>/`, and they belong to a CLI run, not to a
+ *    long-lived MCP server. Forcing every MCP call into a synthetic
+ *    session would muddy the audit log.
+ *  - The MCP surface is intentionally narrower than the engine surface.
+ *    `ask_user_question`, `task_*`, `web_fetch`, `web_search`, the
+ *    skill loader, the LSP tools — none of these make sense when the
+ *    caller is another agent. We expose the six cornerstones (read /
+ *    grep / glob / edit / write / bash) and stop.
+ */
+/**
+ * Read-only tool surface — useful for paired-agent scenarios where the
+ * remote agent should browse but never mutate. Used by the future
+ * `pugi mcp serve --read-only` flag (deferred to β4b).
+ */
+export const PUGI_MCP_READ_ONLY_TOOL_NAMES = ['read', 'grep', 'glob'];
+/**
+ * Build the standard Pugi tool surface bound to a workspace. The
+ * returned tools resolve every path against `ctx.root` via the existing
+ * `file-tools` helpers, so the same path-containment rules that gate
+ * the engine loop apply to MCP-driven calls.
+ *
+ * `bashAllowed: false` drops the `bash` tool from the surface — useful
+ * when paired with an untrusted agent. The default surface includes
+ * `bash` because the typical operator wants full power for their own
+ * client (e.g. the upstream tool calling Pugi to compile and test).
+ */
+export function buildPugiMcpTools(ctx, options = {}) {
+    const bashAllowed = options.bashAllowed !== false;
+    const readOnly = options.readOnly === true;
+    const tools = [
+        {
+            name: 'read',
+            description: 'Read the contents of a workspace file. Returns the full UTF-8 text. Paths must be workspace-relative.',
+            permission: 'read',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path'],
+                properties: {
+                    path: { type: 'string', description: 'Workspace-relative file path.' },
+                },
+            },
+            async execute(args) {
+                const path = requireString(args, 'path');
+                const content = readTool(ctx, path);
+                const CAP = 32 * 1024;
+                if (content.length > CAP) {
+                    return `${content.slice(0, CAP)}\n(...truncated at ${CAP} bytes; use grep or glob to narrow the read)`;
+                }
+                return content;
+            },
+        },
+        {
+            name: 'grep',
+            description: 'Substring-match every workspace file. Returns up to 200 matches with {path, line, text}.',
+            permission: 'read',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['query'],
+                properties: {
+                    query: { type: 'string', description: 'Substring to search for.' },
+                },
+            },
+            async execute(args) {
+                const query = requireString(args, 'query');
+                const matches = grepTool(ctx, query);
+                if (matches.length === 0)
+                    return `no matches for ${query}`;
+                const head = matches.slice(0, 50);
+                const rendered = head.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n');
+                const more = matches.length > head.length ? `\n(... ${matches.length - head.length} more)` : '';
+                return `${matches.length} match(es):\n${rendered}${more}`;
+            },
+        },
+        {
+            name: 'glob',
+            description: 'List files matching a glob pattern (workspace-scoped, node_modules / dist / .git / .pugi excluded). Up to 500 paths.',
+            permission: 'read',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['pattern'],
+                properties: {
+                    pattern: { type: 'string', description: 'Glob pattern, e.g. "src/**/*.ts".' },
+                },
+            },
+            async execute(args) {
+                const pattern = requireString(args, 'pattern');
+                const results = globTool(ctx, pattern);
+                if (results.length === 0)
+                    return `no paths match ${pattern}`;
+                return `${results.length} path(s):\n${results.slice(0, 100).join('\n')}${results.length > 100 ? `\n(... ${results.length - 100} more)` : ''}`;
+            },
+        },
+    ];
+    if (!readOnly) {
+        tools.push({
+            name: 'edit',
+            description: 'Replace exactly one occurrence of oldString with newString inside an already-read file. Fails if the file changed since you read it or if oldString is missing/duplicate.',
+            permission: 'edit',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'oldString', 'newString'],
+                properties: {
+                    path: { type: 'string' },
+                    oldString: { type: 'string' },
+                    newString: { type: 'string' },
+                },
+            },
+            async execute(args) {
+                const path = requireString(args, 'path');
+                const oldString = requireString(args, 'oldString');
+                const newString = requireString(args, 'newString');
+                editTool(ctx, path, oldString, newString);
+                return `edited ${path}`;
+            },
+        }, {
+            name: 'write',
+            description: 'Create or overwrite a workspace file. Use for new files only — prefer edit for existing files.',
+            permission: 'edit',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'content'],
+                properties: {
+                    path: { type: 'string' },
+                    content: { type: 'string', description: 'Full new file contents (UTF-8).' },
+                },
+            },
+            async execute(args) {
+                const path = requireString(args, 'path');
+                const content = requireString(args, 'content');
+                writeTool(ctx, path, content);
+                return `wrote ${path} (${content.length} bytes)`;
+            },
+        });
+    }
+    // β4 r2 P1 #2 — bash advertisement is gated ONLY by `bashAllowed`. The
+    // previous `bashAllowed && !readOnly` coupling collapsed bash to off
+    // whenever `readOnly` was true, but the call site (`runMcpServe`)
+    // synthesized `readOnly` from `!writeAllowed`. Result: an operator who
+    // ran `pugi mcp serve --allow-bash` (no --allow-write) saw bash
+    // silently dropped because writeAllowed=false → readOnly=true.
+    // `bashAllowed` is now the sole knob; the call site is responsible for
+    // honoring `--read-only` by passing `bashAllowed=false` when the
+    // operator explicitly requested read-only mode (which it does:
+    // `bashAllowed = !readOnly && flags.bashAllowed`).
+    if (bashAllowed) {
+        tools.push({
+            name: 'bash',
+            description: 'Run a shell command inside the workspace root. Inherits a sanitized env (secrets stripped). 30s timeout. Output capped at 64KB.',
+            permission: 'bash',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command'],
+                properties: {
+                    command: { type: 'string', description: 'Single shell command to execute.' },
+                },
+            },
+            async execute(args) {
+                const command = requireString(args, 'command');
+                const result = bashToolSync({ cmd: command }, {
+                    root: ctx.root,
+                    settings: ctx.settings,
+                    session: ctx.session,
+                    // β4 r1 P1 #1 — MCP bash invocations carry the dedicated
+                    // `mcp` source so the destructive override (which already
+                    // requires `source === 'human'`) cannot fire and so the
+                    // audit log can distinguish remote-agent calls from the
+                    // in-process loop. Combined with `setMcpPermission` refusing
+                    // `allow_always` for shell-class tools, this closes the
+                    // permanent-shell-grant attack vector.
+                    source: 'mcp',
+                });
+                const parts = [
+                    `exit=${result.exitCode}`,
+                    result.stdout ? `stdout:\n${result.stdout}` : '',
+                    result.stderr ? `stderr:\n${result.stderr}` : '',
+                ];
+                if (result.artifactRef)
+                    parts.push(`artifactRef=${result.artifactRef}`);
+                if (result.truncated)
+                    parts.push('truncated=true');
+                if (result.timedOut)
+                    parts.push('timedOut=true');
+                return parts.filter(Boolean).join('\n') || '(no output)';
+            },
+        });
+    }
+    return tools.sort((a, b) => a.name.localeCompare(b.name));
+}
+function requireString(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string') {
+        throw new Error(`argument "${key}" must be a string`);
+    }
+    return v;
+}
+//# sourceMappingURL=server-tools.js.map