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

package/dist/runtime/commands/mcp.js

@@ -1,935 +0,0 @@
-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 { buildOrchestratorTools } from '../../core/mcp/orchestrator-tools.js';
-import { resolveOrchestratorConfig, describeOrchestratorConfig, } from '../../core/mcp/orchestrator-config.js';
-import { serveHttp } from '../../core/mcp/http-server.js';
-import { resolveActiveCredential, DEFAULT_API_URL } from '../../core/credentials.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).',
-    '   --orchestrator             Expose pugi.run / pugi.read / pugi.write /',
-    '                               pugi.dispatch / pugi.publish / pugi.deploy instead of',
-    '                               the engine surface. Designed for external the upstream tool',
-    '                               / Cursor sessions driving fix-publish-test loops.',
-    '   --orchestrator-bundle      Single-flag form (Trust Sprint item 7). Equivalent to',
-    '                               --orchestrator --allow-bash with PUGI_MCP_EXEC_ENABLED=1',
-    '                               and auto-resolves the pugi binary from PATH (or the',
-    '                               local dev binary when invoked from the monorepo).',
-    '                               Also enabled by setting PUGI_MCP_ORCHESTRATOR=1.',
-    '                               Legacy gates still work as deprecated aliases:',
-    '                                 PUGI_MCP_EXEC_ENABLED=1    enables pugi.run',
-    '                                 PUGI_MCP_PUBLISH_ENABLED=1 enables pugi.publish',
-    '                                 PUGI_MCP_DEPLOY_ENABLED=1  enables pugi.deploy',
-    '                                 PUGI_MCP_WORKSPACE_ROOT=... overrides cwd for path validation',
-    ' 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;
-    // Trust Sprint item 7 — resolve orchestrator config FIRST so it can
-    // contribute to bash gating downstream. The resolver collapses the
-    // legacy multi-knob mode (PUGI_MCP_EXEC_ENABLED + --allow-bash +
-    // PUGI_MCP_PUGI_BIN) into one toggle (PUGI_MCP_ORCHESTRATOR=1 or
-    // --orchestrator-bundle).
-    const orchestratorConfig = flags.orchestrator
-        ? resolveOrchestratorConfig({
-            env: process.env,
-            bundleFlag: flags.orchestratorBundle,
-            bashFlag: flags.bashAllowed,
-            workspaceRoot: ctx.workspaceRoot,
-        })
-        : null;
-    const writeAllowed = !readOnly && flags.writeAllowed;
-    // Bundle implies bash. We OR the resolver's decision into the
-    // bash-gating knob so a customer who set PUGI_MCP_ORCHESTRATOR=1 does
-    // not also need to pass --allow-bash (item 7 acceptance criterion).
-    const bashAllowed = !readOnly && (flags.bashAllowed || (orchestratorConfig?.bashAllowed ?? false));
-    // P1 — when `--orchestrator` is set the surface swaps to the
-    // CLI-orchestrator family (pugi.run / pugi.read / pugi.write /
-    // pugi.dispatch / pugi.publish / pugi.deploy). The engine surface is
-    // intentionally dropped — the two are mutually exclusive on the wire
-    // to keep tool-name resolution unambiguous on the consumer side.
-    const tools = flags.orchestrator
-        ? buildOrchestratorTools(buildOrchestratorContext(ctx.workspaceRoot, orchestratorConfig))
-        : 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,
-            surface: flags.orchestrator ? 'orchestrator' : 'engine',
-            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, ${flags.orchestrator ? 'orchestrator' : 'engine'}): ${tools.length} tool(s) — ${tools.map((t) => t.name).join(', ')}\n`);
-    // Trust Sprint item 7 — when the orchestrator surface is live, surface
-    // the resolved capability table on stderr so the operator can confirm
-    // which gates ended up armed without running `pugi doctor` in another
-    // pane. Each line is prefixed for grep-ability.
-    if (orchestratorConfig) {
-        for (const line of describeOrchestratorConfig(orchestratorConfig)) {
-            process.stderr.write(`pugi-mcp orchestrator: ${line}\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,
-        orchestrator: false,
-        orchestratorBundle: 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 === '--orchestrator') {
-            flags.orchestrator = true;
-        }
-        else if (arg === '--orchestrator-bundle') {
-            // Trust Sprint item 7 — single-flag form. Implies orchestrator
-            // surface + bash + exec. Mutual upgrade with --orchestrator: if
-            // both are passed the bundle wins (it is a strict superset).
-            flags.orchestrator = true;
-            flags.orchestratorBundle = true;
-            flags.bashAllowed = true;
-        }
-        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;
-        // `network` is the permission class used by orchestrator tools
-        // (pugi.dispatch / pugi.publish / pugi.deploy). The env capability
-        // gates inside each tool's `execute` body provide the per-family
-        // kill switch, so the serve-time gate is permissive here. The
-        // server's overall `permissionGate` is already deny-most-other —
-        // adding a third boolean knob (`networkAllowed`) would create more
-        // ways to misconfigure than to protect. P1 .
-        return true;
-    };
-}
-/**
- * Build the OrchestratorToolContext for `pugi mcp serve --orchestrator`.
- * Reads from process.env + the credentials store. Encapsulated so tests
- * never need to mock the resolveActiveCredential path — they call
- * `buildOrchestratorTools` directly with a hand-rolled context.
- *
- * P1 .
- */
-function buildOrchestratorContext(workspaceRoot, resolved = null) {
-    const envRoot = process.env.PUGI_MCP_WORKSPACE_ROOT;
-    const root = envRoot && envRoot.length > 0 ? resolve(envRoot) : workspaceRoot;
-    const credential = resolveActiveCredential();
-    // Trust Sprint item 7 — when `resolved` is provided we honour the
-    // consolidated capability bits. When absent (legacy direct call from
-    // a test) we fall back to the raw env so existing harnesses keep
-    // working untouched.
-    const execEnabled = resolved
-        ? resolved.execEnabled
-        : process.env.PUGI_MCP_EXEC_ENABLED === '1';
-    const publishEnabled = resolved
-        ? resolved.publishEnabled
-        : process.env.PUGI_MCP_PUBLISH_ENABLED === '1';
-    const deployEnabled = resolved
-        ? resolved.deployEnabled
-        : process.env.PUGI_MCP_DEPLOY_ENABLED === '1';
-    const pugiBin = resolved
-        ? resolved.pugiBin
-        : (process.env.PUGI_MCP_PUGI_BIN ?? 'pugi');
-    return {
-        workspaceRoot: root,
-        pugiBin,
-        apiUrl: credential?.apiUrl ?? DEFAULT_API_URL,
-        apiKey: credential?.apiKey ?? null,
-        capabilities: {
-            exec: execEnabled,
-            publish: publishEnabled,
-            deploy: deployEnabled,
-        },
-        sshAlias: process.env.PUGI_MCP_SSH_ALIAS ?? 'codeforge',
-    };
-}
-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