@pugi/cli 0.1.0-beta.31 → 0.1.0-beta.36

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

@@ -0,0 +1,595 @@
+/**
+ * Pugi MCP server — orchestrator-tools surface (Wave 7 P1 / 2026-05-28).
+ *
+ * SCOPE — this module is intentionally orthogonal to `server-tools.ts`.
+ *
+ * - `server-tools.ts` exposes the *engine* surface (read / grep / glob /
+ *   edit / write / bash) — workspace-scoped, file-tools-backed, used by
+ *   "external agent borrows Pugi's in-process executor".
+ *
+ * - `orchestrator-tools.ts` (THIS FILE) exposes the *orchestrator*
+ *   surface — `pugi.run` / `pugi.read` / `pugi.write` / `pugi.dispatch`
+ *   / `pugi.publish` / `pugi.deploy`. These are CLI-level operations
+ *   used by an EXTERNAL Claude Code (or Cursor) session that wants to
+ *   loop fix-publish-test against the LIVE Pugi runtime. The motivating
+ *   use case is the 2026-05-28 CEO dogfood blocker: Pugi REPL emits
+ *   pseudo-tool-tags inline (no real file writes / no real shell exec);
+ *   the operator wants to drive a remote Claude Code session that
+ *   programmatically invokes Pugi against the engine VM, captures
+ *   output, edits source, republishes the CLI, and re-tests — all
+ *   without an interactive human at every step.
+ *
+ * SECURITY POSTURE — every orchestrator tool is gated by an env-var
+ * permission switch that defaults to OFF. The MCP server's
+ * `permissionGate` still applies on top (deny-by-default), but env
+ * gates are a coarser kill-switch the operator can flip per-machine
+ * without rebuilding the CLI.
+ *
+ *   - 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.read` / `pugi.write` / `pugi.dispatch` do not require an env
+ * gate (read+write enforce workspace + protected-path containment;
+ * dispatch only sends prompts to the operator's already-authenticated
+ * Anvil session). All three still pass through the MCP-server
+ * permissionGate, so an operator running `pugi mcp serve` without
+ * `--allow-write` still sees `pugi.write` refused at dispatch.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const execFileAsync = promisify(execFile);
+/**
+ * Protected basename patterns — mirror of
+ * `core/bash-classifier.ts::PROTECTED_BASENAME_PATTERNS`. We DO NOT
+ * import from there because that module is bash-classifier specific
+ * (the regex shapes there carry shell-quote boundaries). For path-only
+ * matching we use simpler RegExps anchored on the basename. Keeps the
+ * two modules independently auditable.
+ */
+const PROTECTED_BASENAMES = [
+    /^\.env$/,
+    /^\.env\.[A-Za-z0-9_-]+$/,
+    /^id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/,
+    /^\.npmrc$/,
+    /^\.pypirc$/,
+    /^\.gitconfig$/,
+    /^credentials(\.json)?$/,
+];
+const PROTECTED_DIR_SEGMENTS = new Set([
+    '.git',
+    '.ssh',
+    '.gnupg',
+    'node_modules',
+]);
+/**
+ * Resolve + validate a caller-supplied path against the workspace
+ * root. Refuses absolute paths outside the root, parent-traversal
+ * escapes, and protected basenames / dir segments.
+ *
+ * Exported so the spec can drive it directly — pinning the security
+ * boundary at a single audited entry point.
+ */
+export function resolveWorkspacePathOrThrow(ctx, requested) {
+    if (typeof requested !== 'string' || requested.length === 0) {
+        throw new Error('path must be a non-empty string');
+    }
+    if (requested.includes('\0')) {
+        throw new Error('path contains a null byte');
+    }
+    const root = resolve(ctx.workspaceRoot);
+    const candidate = isAbsolute(requested) ? requested : resolve(root, requested);
+    const absolute = resolve(candidate);
+    // Containment check — absolute must live under root. We use
+    // `relative` + `..` detection rather than `startsWith(root)` so a
+    // sibling dir whose name happens to share a prefix (e.g. /tmp/wsX
+    // vs /tmp/ws) does not accidentally pass.
+    const rel = relative(root, absolute);
+    if (rel === '' || rel === '.') {
+        throw new Error(`path "${requested}" resolves to the workspace root itself`);
+    }
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`path "${requested}" escapes the workspace root`);
+    }
+    // Protected segment / basename check — applied to EVERY component of
+    // the resolved path under the root. We split on the OS separator so
+    // Windows + POSIX share the same gate.
+    const segments = rel.split(sep);
+    for (const segment of segments) {
+        if (PROTECTED_DIR_SEGMENTS.has(segment)) {
+            throw new Error(`path "${requested}" touches protected segment "${segment}"`);
+        }
+        for (const pattern of PROTECTED_BASENAMES) {
+            if (pattern.test(segment)) {
+                throw new Error(`path "${requested}" touches protected basename "${segment}"`);
+            }
+        }
+    }
+    return { absolute, relativeToRoot: rel };
+}
+/**
+ * Build the orchestrator tool surface. The MCP server consumes the
+ * returned array via `createPugiMcpServer({ tools })`. Permission
+ * gating happens at TWO layers:
+ *
+ *   1. `capabilities.{exec,publish,deploy}` — env-var kill-switch
+ *      checked at tool-execute time. A tool whose capability is OFF
+ *      throws a deterministic refusal message; the MCP wire surfaces
+ *      it as `isError: true` content.
+ *
+ *   2. The MCP server's `permissionGate` — checked BEFORE execute
+ *      runs. The `pugi mcp serve` wiring in `runtime/commands/mcp.ts`
+ *      synthesises a default gate; callers (tests) can pass
+ *      `() => true` to bypass.
+ *
+ * The double-layer design is intentional — it lets an operator
+ * configure `PUGI_MCP_EXEC_ENABLED=1` system-wide AND still refuse a
+ * specific `pugi.run` call via the per-tool prompt without restarting
+ * the server.
+ */
+export function buildOrchestratorTools(ctx) {
+    const fetchImpl = ctx.fetchImpl ??
+        ((...args) => fetch(...args));
+    const execImpl = ctx.execFileImpl ?? execFileAsync;
+    const tools = [
+        {
+            name: 'pugi.run',
+            description: 'Execute a pugi CLI subcommand and capture stdout/stderr/exitCode. ' +
+                'Use for `--version`, `explain`, `smoke`, etc. ' +
+                'Requires PUGI_MCP_EXEC_ENABLED=1 at server boot.',
+            permission: 'bash',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command'],
+                properties: {
+                    command: {
+                        type: 'string',
+                        description: 'Whitespace-tokenised argv tail (e.g. "explain README.md").',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'Optional workspace-relative cwd; defaults to workspace root.',
+                    },
+                    timeoutMs: {
+                        type: 'number',
+                        minimum: 100,
+                        maximum: 300000,
+                        description: 'Hard timeout in ms (default 30000).',
+                    },
+                },
+            },
+            async execute(args) {
+                if (!ctx.capabilities.exec) {
+                    throw new Error('pugi.run: PUGI_MCP_EXEC_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_EXEC_ENABLED=1 to enable shell execution.');
+                }
+                const command = requireString(args, 'command');
+                const tokens = tokeniseArgv(command);
+                if (tokens.length === 0) {
+                    throw new Error('pugi.run: command tokenises to zero args');
+                }
+                const timeoutMs = optionalNumber(args, 'timeoutMs', 30000);
+                const cwdInput = optionalString(args, 'cwd');
+                const cwd = cwdInput
+                    ? resolveWorkspacePathOrThrow(ctx, cwdInput).absolute
+                    : ctx.workspaceRoot;
+                const started = Date.now();
+                try {
+                    const { stdout, stderr } = await execImpl(ctx.pugiBin, tokens, {
+                        cwd,
+                        timeout: timeoutMs,
+                        maxBuffer: 4 * 1024 * 1024,
+                        // Strip secret envs — orchestrator-driven CLI runs do NOT
+                        // need the operator's NPM_TOKEN / GH_TOKEN / OPENAI_API_KEY
+                        // visible. We pass through only PATH + HOME + a minimal
+                        // shell. Same posture as bashToolSync(source='mcp').
+                        env: sanitisedEnv(),
+                    });
+                    const durationMs = Date.now() - started;
+                    return JSON.stringify({
+                        stdout: clamp(stdout, 32 * 1024),
+                        stderr: clamp(stderr, 32 * 1024),
+                        exitCode: 0,
+                        durationMs,
+                    });
+                }
+                catch (err) {
+                    const e = err;
+                    const durationMs = Date.now() - started;
+                    return JSON.stringify({
+                        stdout: clamp(e.stdout ?? '', 32 * 1024),
+                        stderr: clamp(e.stderr ?? (e.message ?? ''), 32 * 1024),
+                        exitCode: typeof e.code === 'number' ? e.code : 1,
+                        durationMs,
+                        ...(e.signal ? { signal: e.signal } : {}),
+                        ...(e.killed ? { killed: true } : {}),
+                    });
+                }
+            },
+        },
+        {
+            name: 'pugi.read',
+            description: 'Read a file inside the configured workspace root. Refuses paths outside ' +
+                'the root, parent-traversal escapes, and protected basenames (.env / .git / ' +
+                '.ssh / id_rsa / .npmrc / credentials.json). Default cap 256KB.',
+            permission: 'read',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path'],
+                properties: {
+                    path: { type: 'string' },
+                },
+            },
+            async execute(args) {
+                const path = requireString(args, 'path');
+                const { absolute, relativeToRoot } = resolveWorkspacePathOrThrow(ctx, path);
+                const stat = statSync(absolute);
+                if (!stat.isFile()) {
+                    throw new Error(`pugi.read: "${relativeToRoot}" is not a regular file`);
+                }
+                const CAP = 256 * 1024;
+                const content = readFileSync(absolute, 'utf8');
+                const sizeBytes = Buffer.byteLength(content, 'utf8');
+                const truncated = sizeBytes > CAP;
+                return JSON.stringify({
+                    path: relativeToRoot,
+                    content: truncated ? content.slice(0, CAP) : content,
+                    sizeBytes,
+                    mtime: stat.mtime.toISOString(),
+                    ...(truncated ? { truncated: true, capBytes: CAP } : {}),
+                });
+            },
+        },
+        {
+            name: 'pugi.write',
+            description: 'Create or overwrite a workspace file using atomic tmp+rename. Refuses paths ' +
+                'outside the workspace root and protected basenames.',
+            permission: 'edit',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'content'],
+                properties: {
+                    path: { type: 'string' },
+                    content: { type: 'string' },
+                },
+            },
+            async execute(args) {
+                const path = requireString(args, 'path');
+                const content = requireString(args, 'content');
+                const { absolute, relativeToRoot } = resolveWorkspacePathOrThrow(ctx, path);
+                mkdirSync(dirname(absolute), { recursive: true });
+                const tmpPath = `${absolute}.pugi-mcp-tmp-${process.pid}-${Date.now()}`;
+                // Open with O_CREAT|O_EXCL so a concurrent writer cannot race
+                // a same-named tmp file out from under us. Mode 0o600 (operator
+                // only) — orchestrator writes are NOT shared artefacts.
+                const fd = openSync(tmpPath, 'wx', 0o600);
+                try {
+                    writeFileSync(fd, content, 'utf8');
+                    // fsync via fstatSync is a no-op on most kernels — the real
+                    // durability win comes from rename being atomic at the inode
+                    // layer. We still touch the fd to surface any late-EIO before
+                    // rename commits.
+                    fstatSync(fd);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                renameSync(tmpPath, absolute);
+                const bytesWritten = Buffer.byteLength(content, 'utf8');
+                return JSON.stringify({
+                    path: relativeToRoot,
+                    bytesWritten,
+                });
+            },
+        },
+        {
+            name: 'pugi.dispatch',
+            description: 'Send a prompt to the live Pugi engine (Anvil-routed). Returns the synthesised ' +
+                'response, tool calls, cost, duration, and file changes. Uses the operator’s ' +
+                'currently active credential — set PUGI_API_KEY or run `pugi login` first.',
+            permission: 'network',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['prompt'],
+                properties: {
+                    prompt: { type: 'string' },
+                    persona: {
+                        type: 'string',
+                        description: 'Persona id, default "mira".',
+                    },
+                    workspace: {
+                        type: 'string',
+                        description: 'Workspace label (logical, not a filesystem path).',
+                    },
+                },
+            },
+            async execute(args) {
+                const prompt = requireString(args, 'prompt');
+                const persona = optionalString(args, 'persona') ?? 'mira';
+                const workspace = optionalString(args, 'workspace');
+                if (!ctx.apiKey) {
+                    throw new Error('pugi.dispatch: no active credential. Set PUGI_API_KEY or run `pugi login`.');
+                }
+                const endpoint = `${ctx.apiUrl.replace(/\/+$/, '')}/api/pugi/engine`;
+                const started = Date.now();
+                const response = await fetchImpl(endpoint, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: `Bearer ${ctx.apiKey}`,
+                        'Content-Type': 'application/json',
+                        Accept: 'application/json',
+                        'User-Agent': 'pugi-mcp-orchestrator/1',
+                    },
+                    body: JSON.stringify({
+                        prompt,
+                        persona,
+                        ...(workspace ? { workspace } : {}),
+                    }),
+                });
+                const durationMs = Date.now() - started;
+                if (!response.ok) {
+                    const bodyText = await safeText(response);
+                    throw new Error(`pugi.dispatch: ${response.status} ${response.statusText} — ${clamp(bodyText, 2000)}`);
+                }
+                const parsed = (await response.json().catch(() => ({})));
+                return JSON.stringify({
+                    response: typeof parsed.response === 'string' ? parsed.response : '',
+                    toolCalls: Array.isArray(parsed.toolCalls) ? parsed.toolCalls : [],
+                    cost: typeof parsed.cost === 'number' ? parsed.cost : 0,
+                    durationMs,
+                    fileChanges: Array.isArray(parsed.fileChanges) ? parsed.fileChanges : [],
+                });
+            },
+        },
+        {
+            name: 'pugi.publish',
+            description: 'Bump @pugi/cli version + build + publish to npm. Use bumpType "beta" for ' +
+                'prerelease bumps (default) or "patch" for stable. Requires ' +
+                'PUGI_MCP_PUBLISH_ENABLED=1 AND a configured ~/.npmrc auth token.',
+            permission: 'network',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bumpType: {
+                        type: 'string',
+                        enum: ['patch', 'beta'],
+                        description: 'Default "beta" — pre-release bump.',
+                    },
+                },
+            },
+            async execute(args) {
+                if (!ctx.capabilities.publish) {
+                    throw new Error('pugi.publish: PUGI_MCP_PUBLISH_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_PUBLISH_ENABLED=1 to enable.');
+                }
+                const bumpType = optionalString(args, 'bumpType') ?? 'beta';
+                if (bumpType !== 'patch' && bumpType !== 'beta') {
+                    throw new Error(`pugi.publish: invalid bumpType "${bumpType}"`);
+                }
+                // npm version semantics: "patch" bumps z; "prerelease --preid beta"
+                // bumps the beta tag. We thread through `pnpm` because the
+                // monorepo build expects the workspace-aware variant.
+                const versionArgs = bumpType === 'beta'
+                    ? ['version', 'prerelease', '--preid', 'beta', '--no-git-tag-version']
+                    : ['version', 'patch', '--no-git-tag-version'];
+                const versionOut = await execImpl('npm', versionArgs, {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 60000,
+                    env: sanitisedEnv(),
+                });
+                const newVersion = (versionOut.stdout || '').trim().replace(/^v/, '');
+                const buildOut = await execImpl('pnpm', ['build'], {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 180000,
+                    env: sanitisedEnv(),
+                });
+                const publishOut = await execImpl('pnpm', ['publish', '--no-git-checks', '--access', 'public'], {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 180000,
+                    env: sanitisedEnv(),
+                });
+                return JSON.stringify({
+                    newVersion,
+                    registry: 'https://registry.npmjs.org',
+                    npmExitCode: 0,
+                    buildStdoutTail: clamp(buildOut.stdout, 2000),
+                    publishStdoutTail: clamp(publishOut.stdout, 2000),
+                });
+            },
+        },
+        {
+            name: 'pugi.deploy',
+            description: 'SSH-redeploy a Pugi service on the engine VM (admin-api / admin-web / ' +
+                'pugi-web / all). Runs git pull + pnpm install + build + pm2 restart. ' +
+                'Requires PUGI_MCP_DEPLOY_ENABLED=1.',
+            permission: 'network',
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['target'],
+                properties: {
+                    target: {
+                        type: 'string',
+                        enum: ['admin-api', 'admin-web', 'pugi-web', 'all'],
+                    },
+                },
+            },
+            async execute(args) {
+                if (!ctx.capabilities.deploy) {
+                    throw new Error('pugi.deploy: PUGI_MCP_DEPLOY_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_DEPLOY_ENABLED=1 to enable.');
+                }
+                const target = requireString(args, 'target');
+                const allowed = ['admin-api', 'admin-web', 'pugi-web', 'all'];
+                if (!allowed.includes(target)) {
+                    throw new Error(`pugi.deploy: invalid target "${target}" (allowed: ${allowed.join(', ')})`);
+                }
+                // The redeploy script lives on the engine VM at ~/deploy/<target>.sh.
+                // We do NOT inline the shell — the operator owns the remote
+                // script and can tune it without rebuilding the CLI.
+                const remoteCmd = `set -euo pipefail; ~/deploy/${target}.sh`;
+                const started = Date.now();
+                const { stdout, stderr } = await execImpl('ssh', [
+                    // BatchMode rejects password prompts so a misconfigured
+                    // ssh-agent fails fast instead of blocking the dispatch.
+                    '-o',
+                    'BatchMode=yes',
+                    '-o',
+                    'StrictHostKeyChecking=accept-new',
+                    ctx.sshAlias,
+                    remoteCmd,
+                ], {
+                    cwd: ctx.workspaceRoot,
+                    timeout: 300000,
+                    maxBuffer: 4 * 1024 * 1024,
+                    env: sanitisedEnv(),
+                });
+                const durationMs = Date.now() - started;
+                return JSON.stringify({
+                    host: ctx.sshAlias,
+                    target,
+                    gitPullHead: extractGitHead(stdout) ?? null,
+                    pm2Status: extractPm2Status(stdout, stderr) ?? null,
+                    durationMs,
+                    stdoutTail: clamp(stdout, 4000),
+                    stderrTail: clamp(stderr, 2000),
+                });
+            },
+        },
+    ];
+    return tools.sort((a, b) => a.name.localeCompare(b.name));
+}
+/* ---------- helpers ---------------------------------------------------- */
+function requireString(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`argument "${key}" must be a non-empty string`);
+    }
+    return v;
+}
+function optionalString(args, key) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'string') {
+        throw new Error(`argument "${key}" must be a string when set`);
+    }
+    return v;
+}
+function optionalNumber(args, key, fallback) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return fallback;
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new Error(`argument "${key}" must be a finite number when set`);
+    }
+    return v;
+}
+function clamp(s, max) {
+    if (typeof s !== 'string')
+        return '';
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}\n…(truncated at ${max} bytes)`;
+}
+/**
+ * Tokenise an argv tail the same way Claude Code's `pugi run` quoting
+ * convention does — whitespace-split with double-quote groups
+ * preserved. We do NOT eval a shell because that would let the model
+ * inject arbitrary commands (e.g. `; rm -rf ~`) into the orchestrator
+ * surface. Anything fancier (env-var expansion, globbing) must be
+ * delegated to the model via a `bash` capability flag — which is
+ * intentionally not part of this surface.
+ *
+ * Exported for the spec.
+ */
+export function tokeniseArgv(command) {
+    const out = [];
+    let buf = '';
+    let inQuotes = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+            continue;
+        }
+        if (ch === '\\' && command[i + 1] === '"') {
+            buf += '"';
+            i += 1;
+            continue;
+        }
+        if (!inQuotes && (ch === ' ' || ch === '\t')) {
+            if (buf.length > 0) {
+                out.push(buf);
+                buf = '';
+            }
+            continue;
+        }
+        buf += ch;
+    }
+    if (inQuotes) {
+        throw new Error('pugi.run: unterminated double-quote in command');
+    }
+    if (buf.length > 0)
+        out.push(buf);
+    return out;
+}
+function sanitisedEnv() {
+    // Allowlist — pass through only what `pugi` needs to find itself
+    // and the local toolchain. NPM_TOKEN is added back for
+    // `pugi.publish` via the npm CLI's own ~/.npmrc lookup — we do not
+    // pass it via env because that surface ends up in `ps` output on
+    // some kernels.
+    const allow = ['PATH', 'HOME', 'USER', 'SHELL', 'LANG', 'LC_ALL', 'TERM', 'NODE_OPTIONS'];
+    const out = {};
+    for (const key of allow) {
+        const value = process.env[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+async function safeText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '';
+    }
+}
+function extractGitHead(stdout) {
+    // Match "HEAD is now at <sha> …" or "<sha> commit message" — the
+    // remote redeploy script logs `git rev-parse HEAD` after pull.
+    const m = stdout.match(/(?:HEAD is now at|^|\n)([0-9a-f]{7,40})\b/);
+    return m ? m[1] : null;
+}
+function extractPm2Status(stdout, stderr) {
+    const haystack = `${stdout}\n${stderr}`;
+    // Match "[PM2] Process pugi-admin-api restarted" or "online" / "stopped"
+    const restart = haystack.match(/\[PM2\][^\n]+(restarted|online|stopped|errored)/i);
+    if (restart)
+        return restart[0].trim();
+    return null;
+}
+/* ---------- helper: load this module from compiled JS at runtime ------- */
+// `fileURLToPath(import.meta.url)` is used by sibling modules to find
+// fixtures at runtime; we re-export it here so the spec can build an
+// isolated workspace next to the compiled module without hard-coding
+// paths. Defensive — not currently used by the production wiring.
+export const ORCHESTRATOR_TOOLS_MODULE_FILE = (() => {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        return '';
+    }
+})();
+//# sourceMappingURL=orchestrator-tools.js.map