@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/runtime/commands/mcp.js

@@ -0,0 +1,824 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { FileReadCache } from '../../core/file-cache.js';
+import { openSession } from '../../core/session.js';
+import { loadSettings } from '../../core/settings.js';
+import { isAlive } from '../../core/mcp/client.js';
+import { loadMcpRegistry, mcpLogPath } from '../../core/mcp/registry.js';
+import { listMcpTrust, setMcpTrust } from '../../core/mcp/trust.js';
+import { createPugiMcpServer, serveStdio } from '../../core/mcp/server.js';
+import { buildPugiMcpTools } from '../../core/mcp/server-tools.js';
+import { serveHttp } from '../../core/mcp/http-server.js';
+import { listMcpPermissions, clearMcpPermission, } from '../../core/mcp/permission.js';
+export async function runMcpCommand(args, ctx) {
+    const sub = args[0] ?? 'list';
+    switch (sub) {
+        case 'list':
+            return runMcpList(ctx);
+        case 'trust':
+            return runMcpFlip(args.slice(1), ctx, 'trusted');
+        case 'deny':
+            return runMcpFlip(args.slice(1), ctx, 'denied');
+        case 'install':
+            return runMcpInstall(args.slice(1), ctx);
+        case 'remove':
+        case 'uninstall':
+            return runMcpRemove(args.slice(1), ctx);
+        case 'doctor':
+            return runMcpDoctor(args.slice(1), ctx);
+        case 'logs':
+            return runMcpLogs(args.slice(1), ctx);
+        case 'restart':
+            return runMcpRestart(args.slice(1), ctx);
+        case 'serve':
+            return runMcpServe(args.slice(1), ctx);
+        case 'perms':
+            return runMcpPerms(args.slice(1), ctx);
+        case 'help':
+        case '--help':
+        case '-h':
+            ctx.writeOutput({ command: 'mcp', usage: USAGE_LINES }, USAGE_LINES.join('\n'));
+            return;
+        default:
+            throw new Error(`Unknown sub-command "pugi mcp ${sub}". Try one of: list, trust, deny, install, remove, doctor, logs, restart, serve, perms.`);
+    }
+}
+const USAGE_LINES = [
+    'Usage: pugi mcp <sub-command>',
+    '',
+    '  list                          List declared MCP servers + trust state + surfaced tools',
+    '  trust <name>                  Mark a server as trusted (operator-side ledger)',
+    '  deny <name>                   Mark a server as denied',
+    '  install <name> <command...>   Add a server to .pugi/mcp.json (workspace scope).',
+    '                                <command> must be an absolute path OR a binary',
+    '                                resolvable via `which` on the operator PATH.',
+    '  remove <name>                 Remove a server from .pugi/mcp.json (workspace scope).',
+    '                                Trust ledger entry is preserved — re-install reuses it.',
+    '  doctor [--connect]            Print per-server health (handshake, tool count, last error).',
+    '                                --connect actually spawns the children (slow, ~5s/server).',
+    '                                Without --connect, reports the declared state only.',
+    '  logs <name> [--tail N]        Tail the per-server log file at .pugi/logs/mcp-<name>.log.',
+    '                                Default tail is 40 lines.',
+    '  restart <name>                Bounce a server: tear down the connection, reload the',
+    '                                config, re-handshake. Surfaces the new tool count.',
+    '  serve [options]               Run Pugi as an MCP server',
+    '    --http :<port>              HTTP+SSE transport (default: stdio)',
+    '    --host <ip>                 HTTP bind host (default: 127.0.0.1)',
+    '    --token <bearer>            HTTP bearer token (env: PUGI_MCP_TOKEN).',
+    '                                Required for --http unless --print-token is set.',
+    '    --print-token               Auto-generate a random bearer token and print it',
+    '                                to stderr. Opt-in for ad-hoc local testing only.',
+    '    --read-only                 Expose read/grep/glob only (default for HTTP).',
+    '    --allow-write               Expose edit/write (default off — explicit opt-in).',
+    '    --allow-bash                Expose the bash tool (default off — explicit opt-in).',
+    '    --no-bash                   Deprecated alias (bash is already off by default).',
+    '  perms list                    Show cached per-(server, tool) decisions',
+    '  perms reset <server>:<tool>   Forget one cached decision',
+];
+/* ---------- list ------------------------------------------------------- */
+async function runMcpList(ctx) {
+    const registry = await loadMcpRegistry(ctx.workspaceRoot, { connect: false });
+    const declared = Array.from(registry.servers.values()).map((state) => ({
+        name: state.name,
+        command: state.config.command,
+        args: state.config.args,
+        trust: state.trust,
+        surfacedTools: state.surfacedTools.length,
+        lastError: state.lastError ?? null,
+    }));
+    const ledger = await listMcpTrust();
+    await registry.shutdown();
+    if (declared.length === 0) {
+        ctx.writeOutput({ command: 'mcp.list', servers: [], ledger }, 'No MCP servers declared. Add one with `pugi mcp install <name> <command...>`.');
+        return;
+    }
+    ctx.writeOutput({ command: 'mcp.list', servers: declared, ledger }, [
+        'MCP servers:',
+        ...declared.map((server) => `  ${server.name.padEnd(20)} ${server.trust.padEnd(8)} ${server.command} ${server.args.join(' ')}`),
+    ].join('\n'));
+}
+/* ---------- trust / deny ---------------------------------------------- */
+async function runMcpFlip(args, ctx, state) {
+    const name = args[0];
+    if (!name) {
+        throw new Error(`pugi mcp ${state === 'trusted' ? 'trust' : 'deny'} requires a server name.`);
+    }
+    const by = resolveDecidedBy();
+    await setMcpTrust(name, state, by);
+    ctx.writeOutput({ command: `mcp.${state === 'trusted' ? 'trust' : 'deny'}`, name, state, decidedBy: by }, state === 'trusted'
+        ? `MCP server "${name}" is now trusted.`
+        : `MCP server "${name}" is now denied.`);
+}
+/* ---------- install --------------------------------------------------- */
+async function runMcpInstall(args, ctx) {
+    const name = args[0];
+    const command = args[1];
+    const rest = args.slice(2);
+    if (!name || !command) {
+        throw new Error('Usage: pugi mcp install <name> <command> [args...]');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp install: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    // β4 r1 P1 #6 — validate the executable path. Trust ledger gating is
+    // not enough: a cloned-and-trusted repo could declare a relative
+    // command (`./malicious-shim.sh`) that resolves at runtime via the
+    // shell PATH or the workspace cwd. Require an ABSOLUTE path OR a
+    // `which`-resolvable binary so the operator sees the canonical
+    // executable before granting trust.
+    const resolved = resolveExecutablePath(command);
+    if (!resolved) {
+        throw new Error(`pugi mcp install: command "${command}" must be an absolute path or a binary on PATH. ` +
+            `Pass the full path (e.g. /usr/local/bin/node) or install the binary first.`);
+    }
+    // Reject shell metacharacters in args — they survive into the spawn
+    // call as positional args (no shell), but a metachar in the COMMAND
+    // slot would be a clearer foot-gun and we already validated above.
+    for (const arg of [command, ...rest]) {
+        if (containsShellMetachar(arg)) {
+            throw new Error(`pugi mcp install: argument "${arg}" contains shell metacharacters; pass tokens individually instead of a shell string.`);
+        }
+    }
+    const mcpJsonPath = resolve(ctx.workspaceRoot, '.pugi/mcp.json');
+    mkdirSync(resolve(ctx.workspaceRoot, '.pugi'), { recursive: true });
+    let existing = { servers: {} };
+    if (existsSync(mcpJsonPath)) {
+        try {
+            const raw = readFileSync(mcpJsonPath, 'utf8');
+            if (raw.trim().length > 0) {
+                const parsed = JSON.parse(raw);
+                existing = { servers: parsed.servers ?? {} };
+            }
+        }
+        catch (error) {
+            throw new Error(`pugi mcp install: cannot parse existing .pugi/mcp.json: ${error.message}. ` +
+                `Fix the file by hand or delete it and re-run.`);
+        }
+    }
+    if (existing.servers[name]) {
+        throw new Error(`pugi mcp install: server "${name}" already declared. Remove it from .pugi/mcp.json first.`);
+    }
+    // β4 r2 P1 #1 — persist the RESOLVED absolute path as `command`, not the
+    // original input. Before this fix the install path verified `resolved` but
+    // wrote the operator's literal `command` argument back to .pugi/mcp.json;
+    // the spawn at connect-time re-walked the PATH via `spawn(command, ...)`,
+    // which defeated the P1 #6 (β4 r1) hardening — a workspace-cwd shim
+    // (`./malicious-node`) inserted between install and trust could intercept
+    // the call because PATH search includes cwd on many shells.
+    //
+    // The original input is preserved as `originalCommand` for display / debug
+    // surfaces (`pugi mcp list`, audit logs) so operators can still see how
+    // they typed the install call. The runtime spawn path consumes `command`,
+    // so the absolute path is always what we actually exec.
+    existing.servers[name] = {
+        command: resolved,
+        originalCommand: command,
+        args: rest,
+        env: {},
+        // Workspace declarations start `pending` — trust must be granted
+        // explicitly via `pugi mcp trust <name>`. This matches the
+        // server-level trust ledger override semantics in registry.ts.
+        trust: 'pending',
+    };
+    writeFileSync(mcpJsonPath, `${JSON.stringify(existing, null, 2)}\n`, { mode: 0o600 });
+    // Surface the resolved binary loudly so the operator sees the canonical
+    // executable before granting trust. β4 r1 P1 #6.
+    process.stderr.write(`pugi mcp install: starting executable resolves to ${resolved}\n`);
+    ctx.writeOutput({
+        command: 'mcp.install',
+        name,
+        // `executable` keeps the legacy field name (= what we will actually
+        // spawn). `originalCommand` is the operator's literal input.
+        executable: resolved,
+        originalCommand: command,
+        executableResolved: resolved,
+        args: rest,
+        configPath: mcpJsonPath,
+    }, [
+        `Added MCP server "${name}" to ${mcpJsonPath}.`,
+        `Resolved executable: ${resolved}`,
+        `It starts as pending. Run \`pugi mcp trust ${name}\` to enable it.`,
+    ].join('\n'));
+}
+/**
+ * Resolve a command to its canonical executable path. Returns null if the
+ * input is neither an absolute path that exists nor a binary resolvable
+ * via `which` on the operator PATH.
+ */
+function resolveExecutablePath(command) {
+    if (isAbsolute(command)) {
+        return existsSync(command) ? command : null;
+    }
+    // Reject relative paths — `./shim.sh` could be a freshly-cloned
+    // attacker binary in the workspace cwd. Require absolute OR PATH.
+    if (command.includes('/') || command.includes('\\'))
+        return null;
+    try {
+        // `which` exits 0 with the path on stdout. We pass exactly one
+        // argument (the binary name we just validated) so no shell metachar
+        // path is possible.
+        const out = execFileSync('/usr/bin/which', [command], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 5000,
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function containsShellMetachar(value) {
+    // Reject the obvious shell control characters. We are not building a
+    // full lexer; the install path passes the args verbatim to spawn (no
+    // shell), so the goal here is purely surfacing operator surprise — a
+    // `;` in an arg almost always means the user thought they were typing
+    // a shell pipeline.
+    return /[;|&`$<>(){}\n\r]/.test(value);
+}
+/* ---------- remove ---------------------------------------------------- */
+async function runMcpRemove(args, ctx) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('Usage: pugi mcp remove <name>');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp remove: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    const mcpJsonPath = resolve(ctx.workspaceRoot, '.pugi/mcp.json');
+    if (!existsSync(mcpJsonPath)) {
+        throw new Error(`pugi mcp remove: no .pugi/mcp.json at ${mcpJsonPath}. Nothing to remove.`);
+    }
+    let existing;
+    try {
+        const raw = readFileSync(mcpJsonPath, 'utf8');
+        if (raw.trim().length === 0) {
+            existing = { servers: {} };
+        }
+        else {
+            const parsed = JSON.parse(raw);
+            existing = { servers: parsed.servers ?? {} };
+        }
+    }
+    catch (error) {
+        throw new Error(`pugi mcp remove: cannot parse .pugi/mcp.json: ${error.message}. ` +
+            `Fix the file by hand or delete it and re-run.`);
+    }
+    if (!existing.servers[name]) {
+        throw new Error(`pugi mcp remove: server "${name}" not declared in ${mcpJsonPath}. ` +
+            `Run \`pugi mcp list\` to see declared servers.`);
+    }
+    // Preserve the trust ledger entry on purpose — a re-install of the same
+    // server name should land back at its old trust state so the operator
+    // does not have to re-approve it. To wipe trust as well, run
+    // `pugi mcp deny <name>` (or edit ~/.pugi/trust-mcp.json by hand).
+    delete existing.servers[name];
+    writeFileSync(mcpJsonPath, `${JSON.stringify(existing, null, 2)}\n`, { mode: 0o600 });
+    ctx.writeOutput({
+        command: 'mcp.remove',
+        name,
+        configPath: mcpJsonPath,
+        remaining: Object.keys(existing.servers),
+    }, [
+        `Removed MCP server "${name}" from ${mcpJsonPath}.`,
+        `Trust ledger entry preserved — re-install reuses it.`,
+        `Remaining servers: ${Object.keys(existing.servers).length === 0 ? '(none)' : Object.keys(existing.servers).join(', ')}.`,
+    ].join('\n'));
+}
+/* ---------- doctor ---------------------------------------------------- */
+async function runMcpDoctor(args, ctx) {
+    // `--connect` forces the doctor to actually spawn children + handshake.
+    // Default behaviour is dry-run (config + trust ledger only) so a routine
+    // `pugi doctor` does not block on a misbehaving server's 5s timeout per
+    // entry. Operators investigating an outage pass `--connect` explicitly.
+    const wantsConnect = args.includes('--connect');
+    const registry = await loadMcpRegistry(ctx.workspaceRoot, { connect: wantsConnect });
+    const ledger = await listMcpTrust();
+    const rows = [];
+    for (const state of registry.servers.values()) {
+        const conn = state.connection;
+        let handshake;
+        if (!wantsConnect) {
+            handshake = 'not-attempted';
+        }
+        else if (state.lastError) {
+            handshake = 'failed';
+        }
+        else if (conn && isAlive(conn)) {
+            handshake = 'ok';
+        }
+        else {
+            handshake = 'failed';
+        }
+        rows.push({
+            name: state.name,
+            trust: state.trust,
+            handshake,
+            pid: conn?.child.pid ?? null,
+            tools: state.surfacedTools.length,
+            uptimeMs: conn ? Date.now() - conn.startedAt : null,
+            lastError: state.lastError ?? null,
+            logFile: mcpLogPath(ctx.workspaceRoot, state.name),
+        });
+    }
+    rows.sort((a, b) => a.name.localeCompare(b.name));
+    await registry.shutdown();
+    if (rows.length === 0) {
+        ctx.writeOutput({ command: 'mcp.doctor', rows, ledger, connectAttempted: wantsConnect }, 'No MCP servers declared. Add one with `pugi mcp install <name> <command...>`.');
+        return;
+    }
+    const headerLines = [
+        `MCP doctor (${wantsConnect ? 'live handshake' : 'declared state only — pass --connect for live probe'}):`,
+        '',
+        `  ${'NAME'.padEnd(20)} ${'TRUST'.padEnd(8)} ${'HANDSHAKE'.padEnd(14)} ${'TOOLS'.padEnd(6)} ${'PID'.padEnd(7)} NOTE`,
+    ];
+    for (const row of rows) {
+        const note = row.lastError
+            ? `error: ${truncate(row.lastError, 60)}`
+            : row.handshake === 'ok'
+                ? `uptime ${formatUptime(row.uptimeMs ?? 0)}`
+                : row.handshake === 'failed'
+                    ? 'see log file'
+                    : '';
+        headerLines.push(`  ${row.name.padEnd(20)} ${row.trust.padEnd(8)} ${row.handshake.padEnd(14)} ${String(row.tools).padEnd(6)} ${String(row.pid ?? '-').padEnd(7)} ${note}`);
+    }
+    headerLines.push('', `Log dir: ${resolve(ctx.workspaceRoot, '.pugi/logs')}`);
+    if (!wantsConnect) {
+        headerLines.push('Hint: pass --connect to actually spawn the children (slow, ~5s budget/server).');
+    }
+    ctx.writeOutput({ command: 'mcp.doctor', rows, ledger, connectAttempted: wantsConnect }, headerLines.join('\n'));
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}
+function formatUptime(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const sec = Math.floor(ms / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m${sec % 60}s`;
+    const hr = Math.floor(min / 60);
+    return `${hr}h${min % 60}m`;
+}
+/* ---------- logs ------------------------------------------------------ */
+async function runMcpLogs(args, ctx) {
+    const name = args[0];
+    if (!name || name.startsWith('--')) {
+        throw new Error('Usage: pugi mcp logs <name> [--tail N]');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp logs: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    // `--tail N` and `--tail=N` both supported. Default 40 lines — matches
+    // typical `tail -n 40` muscle memory.
+    let tail = 40;
+    for (let i = 1; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--tail') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('pugi mcp logs: --tail requires a value');
+            const n = Number.parseInt(next, 10);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`pugi mcp logs: --tail must be a positive integer (got "${next}")`);
+            }
+            tail = n;
+            i += 1;
+        }
+        else if (arg.startsWith('--tail=')) {
+            const n = Number.parseInt(arg.slice('--tail='.length), 10);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`pugi mcp logs: --tail must be a positive integer (got "${arg}")`);
+            }
+            tail = n;
+        }
+        else {
+            throw new Error(`pugi mcp logs: unknown flag "${arg}"`);
+        }
+    }
+    const path = mcpLogPath(ctx.workspaceRoot, name);
+    if (!existsSync(path)) {
+        ctx.writeOutput({ command: 'mcp.logs', name, path, tail, lines: [] }, `No log file at ${path}. The server has not produced stderr output yet (or has never been started).`);
+        return;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`pugi mcp logs: cannot read ${path}: ${error.message}.`);
+    }
+    const allLines = raw.split('\n');
+    // `split('\n')` of a trailing-newline file yields an empty last element.
+    // Drop it so the displayed tail matches `wc -l` expectations.
+    if (allLines.length > 0 && allLines[allLines.length - 1] === '') {
+        allLines.pop();
+    }
+    const tailed = allLines.slice(Math.max(0, allLines.length - tail));
+    const sizeBytes = (() => {
+        try {
+            return statSync(path).size;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    ctx.writeOutput({
+        command: 'mcp.logs',
+        name,
+        path,
+        tail,
+        totalLines: allLines.length,
+        sizeBytes,
+        lines: tailed,
+    }, [
+        `pugi mcp logs ${name} (${path}, ${sizeBytes} bytes, ${allLines.length} total lines, showing last ${Math.min(tail, allLines.length)}):`,
+        ...tailed,
+    ].join('\n'));
+}
+/* ---------- restart --------------------------------------------------- */
+async function runMcpRestart(args, ctx) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('Usage: pugi mcp restart <name>');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp restart: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    // `pugi mcp restart` is stateless from the CLI's perspective — the CLI
+    // process has no long-lived MCP registry of its own (the REPL owns it
+    // and tears it down on exit). What we DO here is: load the config,
+    // refuse if the server is not declared or not trusted, then probe-spawn
+    // the server with the live handshake. This proves it is reachable +
+    // surfaces the tool count for the operator. The REPL picks up the
+    // change on its next `loadMcpRegistry` cycle.
+    const registry = await loadMcpRegistry(ctx.workspaceRoot, { connect: false });
+    const state = registry.servers.get(name);
+    if (!state) {
+        await registry.shutdown();
+        throw new Error(`pugi mcp restart: server "${name}" not declared. Run \`pugi mcp list\` to see declared servers.`);
+    }
+    if (state.trust !== 'trusted') {
+        await registry.shutdown();
+        throw new Error(`pugi mcp restart: server "${name}" trust state is "${state.trust}". ` +
+            `Run \`pugi mcp trust ${name}\` first.`);
+    }
+    await registry.shutdown();
+    // Re-load WITH connect=true but scoped to a single-server probe via
+    // handshakeTimeoutMs (5s default keeps the CLI snappy). We use the same
+    // loadMcpRegistry path so log routing + error capture stay consistent.
+    const probe = await loadMcpRegistry(ctx.workspaceRoot, { connect: true });
+    const probed = probe.servers.get(name);
+    const lastError = probed?.lastError ?? null;
+    const toolCount = probed?.surfacedTools.length ?? 0;
+    const pid = probed?.connection?.child.pid ?? null;
+    await probe.shutdown();
+    if (lastError) {
+        ctx.writeOutput({
+            command: 'mcp.restart',
+            name,
+            ok: false,
+            error: lastError,
+            logFile: mcpLogPath(ctx.workspaceRoot, name),
+        }, [
+            `pugi mcp restart ${name}: FAILED`,
+            `  error: ${lastError}`,
+            `  log file: ${mcpLogPath(ctx.workspaceRoot, name)}`,
+        ].join('\n'));
+        return;
+    }
+    ctx.writeOutput({
+        command: 'mcp.restart',
+        name,
+        ok: true,
+        pid,
+        surfacedTools: toolCount,
+    }, [
+        `pugi mcp restart ${name}: OK`,
+        `  pid: ${pid ?? '-'}`,
+        `  surfaced tools: ${toolCount}`,
+    ].join('\n'));
+}
+async function runMcpServe(args, ctx) {
+    const flags = parseServeFlags(args);
+    const session = openSession(ctx.workspaceRoot);
+    const settings = loadSettings(ctx.workspaceRoot);
+    const toolCtx = {
+        root: ctx.workspaceRoot,
+        settings,
+        session,
+        readCache: new FileReadCache(),
+    };
+    // β4 r1 P1 #2 — surface defaults flip to deny-most-permissive. The
+    // previous defaults exposed every tool (read/edit/write/bash) on every
+    // transport; an HTTP listener with a leaked bearer = remote shell. We
+    // now require explicit opt-in for write + bash. `--read-only` remains
+    // the explicit "shrink to read/grep/glob" knob.
+    //
+    // β4 r2 P1 #2 — `--allow-bash` and `--allow-write` are now INDEPENDENT
+    // opt-ins. Before this fix `readOnly` collapsed to `true` whenever
+    // `--allow-write` was omitted, which forced `buildPugiMcpTools` to
+    // drop the `bash` tool even when the operator had explicitly set
+    // `--allow-bash`. The `readOnly` flag below now reflects ONLY the
+    // explicit `--read-only` request; the per-capability gates
+    // (`bashAllowed` / `writeAllowed`) handle the rest. The permission gate
+    // below (`buildServePermissionGate`) still refuses bash/edit per-tool
+    // when the corresponding capability is off, so a misconfigured
+    // `buildPugiMcpTools` call (advertising `bash` without the gate flag)
+    // would still be refused at dispatch.
+    const readOnly = flags.readOnly === true;
+    const writeAllowed = !readOnly && flags.writeAllowed;
+    const bashAllowed = !readOnly && flags.bashAllowed;
+    const tools = buildPugiMcpTools(toolCtx, {
+        bashAllowed,
+        // Keep the legacy contract: `readOnly` for the tool-builder means
+        // "do not advertise edit/write tools". Bash advertisement is gated
+        // by the independent `bashAllowed` knob. So the builder sees
+        // `readOnly = true` whenever the operator did not opt into write
+        // explicitly, which preserves the deny-by-default surface for
+        // edit/write but no longer accidentally suppresses bash.
+        readOnly: readOnly || !writeAllowed,
+    });
+    // β4 r1 P1 #2 — deny-by-default permissionGate. The MCP cache + FSM
+    // are consulted on every dispatch; allow_always-cached entries pass
+    // silently, allow_once entries pass and self-clear, deny entries
+    // refuse, and unset entries refuse with a hint (operator can grant
+    // out-of-band via `pugi mcp perm grant <tool>` — backlog).
+    const permissionGate = buildServePermissionGate({
+        bashAllowed,
+        writeAllowed,
+    });
+    const server = createPugiMcpServer({
+        tools,
+        permissionGate,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        log: (level, message) => {
+            // Stdio: keep stderr empty unless explicitly debugging. HTTP:
+            // route through writeOutput so operators see lifecycle in JSON
+            // mode. For now we honour stderr only — adding a --debug flag
+            // is backlog.
+            if (level === 'error')
+                process.stderr.write(`pugi-mcp: ${message}\n`);
+        },
+    });
+    if (flags.http) {
+        // β4 r1 P0 #1 — token resolution. Prefer explicit operator config;
+        // fall back to env; only auto-generate when `--print-token` is set.
+        // The auto-generated token NEVER lands in stdout — only stderr.
+        const envToken = process.env.PUGI_MCP_TOKEN?.trim();
+        const explicitToken = flags.bearerToken ?? (envToken && envToken.length > 0 ? envToken : null);
+        if (!explicitToken && !flags.printToken) {
+            throw new Error('pugi mcp serve --http requires a bearer token. Pass --token <value>, set ' +
+                'PUGI_MCP_TOKEN, or add --print-token to auto-generate one (printed to stderr).');
+        }
+        const handle = await serveHttp({
+            server,
+            port: flags.http.port,
+            host: flags.http.host,
+            ...(explicitToken ? { bearerToken: explicitToken } : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+            log: (_level, message) => {
+                process.stderr.write(`pugi-mcp-http: ${message}\n`);
+            },
+        });
+        // Bearer token: print to STDERR only if auto-generated (so it never
+        // lands in CI logs / session journals / Anvil events that capture
+        // stdout). Operators consuming the JSON envelope must read it from
+        // their controlling terminal. β4 r1 P0 #1.
+        if (handle.bearerTokenAutoGenerated) {
+            process.stderr.write(`pugi-mcp-http: AUTO-GENERATED BEARER TOKEN (use once; --print-token set):\n` +
+                `  ${handle.bearerToken}\n` +
+                `pugi-mcp-http: prefer --token / PUGI_MCP_TOKEN for persistent setups.\n`);
+        }
+        // Emit the URL + tool surface to stdout (JSON-safe). Bearer token
+        // is intentionally omitted from the JSON payload — operators who
+        // need it programmatically supply --token explicitly.
+        ctx.writeOutput({
+            command: 'mcp.serve',
+            transport: 'http',
+            url: handle.url,
+            bearerTokenSource: handle.bearerTokenAutoGenerated
+                ? 'auto-generated (see stderr)'
+                : explicitToken === envToken
+                    ? 'env:PUGI_MCP_TOKEN'
+                    : 'flag:--token',
+            tools: tools.map((t) => t.name),
+        }, [
+            `pugi mcp serve (http) — listening at ${handle.url}`,
+            handle.bearerTokenAutoGenerated
+                ? `Bearer token: see stderr (auto-generated, --print-token)`
+                : `Bearer token: configured via ${explicitToken === envToken ? 'PUGI_MCP_TOKEN env' : '--token flag'}`,
+            `Tools: ${tools.map((t) => t.name).join(', ')}`,
+            '',
+            'Endpoints:',
+            '  POST /mcp/v1/initialize',
+            '  POST /mcp/v1/list',
+            '  POST /mcp/v1/call',
+            '  POST /mcp/v1/rpc',
+            '  GET  /mcp/v1/events       (SSE)',
+            '  GET  /mcp/v1/health       (no auth)',
+            '',
+            'Press Ctrl-C to stop.',
+        ].join('\n'));
+        // Keep the process alive while the listener is up. The signal +
+        // SIGINT handlers below force a graceful close.
+        await new Promise((resolveExit) => {
+            const onSignal = async () => {
+                await handle.close();
+                resolveExit();
+            };
+            process.once('SIGINT', () => void onSignal());
+            process.once('SIGTERM', () => void onSignal());
+            if (ctx.signal) {
+                if (ctx.signal.aborted)
+                    void onSignal();
+                else
+                    ctx.signal.addEventListener('abort', () => void onSignal(), { once: true });
+            }
+        });
+        return;
+    }
+    // Stdio transport — default. The handshake + tools/list happen on
+    // the wire; nothing is printed unless the parent agent sends a
+    // request that returns a response. Operator sees one info line on
+    // stderr so they know the server is up.
+    process.stderr.write(`pugi-mcp (stdio): ${tools.length} tool(s) — ${tools.map((t) => t.name).join(', ')}\n`);
+    await serveStdio({
+        server,
+        stdin: ctx.stdin ?? process.stdin,
+        stdout: ctx.stdout ?? process.stdout,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+    });
+}
+function parseServeFlags(args) {
+    const flags = {
+        http: null,
+        bearerToken: null,
+        printToken: false,
+        readOnly: false,
+        writeAllowed: false,
+        bashAllowed: false,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--http' || arg === '-h') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('--http requires a port (e.g. --http :7100 or --http 7100)');
+            flags.http = parseHttpBinding(next);
+            i += 1;
+        }
+        else if (arg.startsWith('--http=')) {
+            flags.http = parseHttpBinding(arg.slice('--http='.length));
+        }
+        else if (arg === '--host') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('--host requires a value');
+            // Stash on a synthetic http config; binding-port may have been set
+            // earlier, OR we initialize with port 0 and require --http.
+            if (!flags.http) {
+                throw new Error('--host requires --http to be set first');
+            }
+            flags.http.host = next;
+            i += 1;
+        }
+        else if (arg === '--token') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('--token requires a value');
+            flags.bearerToken = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--token=')) {
+            flags.bearerToken = arg.slice('--token='.length);
+        }
+        else if (arg === '--print-token') {
+            flags.printToken = true;
+        }
+        else if (arg === '--read-only') {
+            flags.readOnly = true;
+        }
+        else if (arg === '--allow-write') {
+            flags.writeAllowed = true;
+        }
+        else if (arg === '--allow-bash') {
+            flags.bashAllowed = true;
+            // bash implies write capability is meaningless (bash runs anything);
+            // we still keep them orthogonal so an operator can grant bash
+            // without exposing the structured `edit` / `write` tools to the
+            // MCP surface (which would let an external agent rewrite files
+            // without going through the diff escalation pipeline).
+        }
+        else if (arg === '--no-bash') {
+            // Deprecated — bash is already off by default. Kept for back-compat
+            // so existing operator scripts do not error.
+            flags.bashAllowed = false;
+        }
+        else if (arg === '--help') {
+            // Caller renders USAGE_LINES. We surface the same via top-level
+            // dispatch — nothing to do here, just don't error.
+        }
+        else {
+            throw new Error(`pugi mcp serve: unknown flag "${arg}"`);
+        }
+    }
+    return flags;
+}
+/**
+ * Build the permission gate for `pugi mcp serve`. Default policy is
+ * deny-with-hint. The MCP cache layer at `~/.pugi/mcp-perms.json` is
+ * consulted for `allow_always` / `deny` decisions; shell-class tools
+ * (bash) can NEVER hold `allow_always` (enforced by `setMcpPermission`),
+ * so a cached approval still requires per-call FSM prompt.
+ *
+ * Wired here as a thin synchronous policy because the serve path runs
+ * in a long-lived non-TTY context (HTTP) — interactive prompts would
+ * block forever. The future TTY-mode interactive prompt lives on top
+ * of this gate in `pugi mcp serve --interactive` (backlog).
+ */
+function buildServePermissionGate(opts) {
+    return async (input) => {
+        const { tool } = input;
+        // Surface-level gate: even if the cache says allow_always, the
+        // operator's serve-flag opt-in is the ultimate authority. A
+        // misconfigured cache entry (legacy approval) cannot override the
+        // serve-time policy.
+        if (tool.permission === 'bash' && !opts.bashAllowed)
+            return false;
+        if (tool.permission === 'edit' && !opts.writeAllowed)
+            return false;
+        return true;
+    };
+}
+function parseHttpBinding(input) {
+    // Accept `:7100`, `7100`, or `host:7100`.
+    let host = '127.0.0.1';
+    let portStr = input;
+    if (input.startsWith(':')) {
+        portStr = input.slice(1);
+    }
+    else if (input.includes(':')) {
+        const idx = input.lastIndexOf(':');
+        host = input.slice(0, idx);
+        portStr = input.slice(idx + 1);
+    }
+    const port = Number.parseInt(portStr, 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`invalid --http port: "${input}" (expected :PORT or HOST:PORT)`);
+    }
+    return { host, port };
+}
+/* ---------- perms ------------------------------------------------------ */
+async function runMcpPerms(args, ctx) {
+    const sub = args[0] ?? 'list';
+    switch (sub) {
+        case 'list': {
+            const entries = listMcpPermissions();
+            ctx.writeOutput({ command: 'mcp.perms.list', entries }, entries.length === 0
+                ? 'No cached MCP permission decisions.'
+                : [
+                    'MCP permission cache:',
+                    ...entries.map((entry) => `  ${entry.server.padEnd(16)} ${entry.tool.padEnd(20)} ${entry.decision.padEnd(14)} ${entry.decidedAt}`),
+                ].join('\n'));
+            return;
+        }
+        case 'reset': {
+            const target = args[1];
+            if (!target || !target.includes(':')) {
+                throw new Error('Usage: pugi mcp perms reset <server>:<tool>');
+            }
+            const idx = target.indexOf(':');
+            const server = target.slice(0, idx);
+            const tool = target.slice(idx + 1);
+            const removed = clearMcpPermission(server, tool);
+            ctx.writeOutput({ command: 'mcp.perms.reset', server, tool, removed }, removed
+                ? `Forgot permission decision for ${server}:${tool}.`
+                : `No cached decision for ${server}:${tool}.`);
+            return;
+        }
+        default:
+            throw new Error(`Unknown "pugi mcp perms ${sub}". Try: list, reset.`);
+    }
+}
+function resolveDecidedBy() {
+    return (process.env.PUGI_TRUSTED_BY?.trim() ||
+        process.env.USER?.trim() ||
+        process.env.USERNAME?.trim() ||
+        'cli');
+}
+/**
+ * Resolve the effective user home for diagnostics (e.g. surfacing the
+ * trust ledger path in `pugi mcp list --verbose`). Mirrors registry.ts.
+ */
+export function pugiHome() {
+    return process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+}
+//# sourceMappingURL=mcp.js.map