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

package/dist/tools/mcp-tool.js

@@ -1,260 +0,0 @@
-import { callTool } from '../core/mcp/client.js';
-import { getMcpPermission, setMcpPermission, } from '../core/mcp/permission.js';
-/**
- * Tool dispatcher for MCP-invoked tools (β4 M1 + M3 + M5).
- *
- * Tool names use the `mcp__<server>__<tool>` namespace (double-underscore
- * separator, mirroring the upstream tool's MCP envelope). The triple-underscore
- * forms (`mcp__server__tool__sub`) collapse into the third segment when
- * the upstream server itself uses underscores in its tool names — `split`
- * on the first two `__` only, so any further `__` in the tool name part
- * survive intact (e.g. `mcp__github__create_issue` -> server=`github`,
- * tool=`create_issue`).
- *
- * Why double-underscore: native Pugi tools use single-token names
- * (`read`, `grep`, `edit`, `bash`). The double-underscore prefix
- * unambiguously segregates the MCP namespace from native names without
- * needing per-name regex matching at every dispatch site.
- *
- * Permission flow:
- *  1. Server trust gate (handled at registry-load time). If a server is
- *     not `trusted`, its tools never reach the engine loop.
- *  2. Per-(server, tool) permission cache (`./mcp/permission.ts`).
- *     Unset on first dispatch -> caller must prompt. Cached `allow_always`
- *     auto-passes; cached `deny` auto-refuses.
- *
- * This module is the bridge — it parses the namespaced name, finds the
- * live connection in the registry, consults the cache, and (when
- * approved) routes through `client.callTool`. Prompting is the executor's
- * responsibility; this module exposes the cache lookup + dispatch
- * primitives so the executor stays small.
- */
-/**
- * Prefix every MCP tool name carries on the engine-loop wire.
- */
-export const MCP_TOOL_PREFIX = 'mcp__';
-/**
- * Parse `mcp__<server>__<tool>` into `{ serverName, toolName }`. Returns
- * null when the input does not match the namespace — callers use this as
- * the "is this an MCP tool?" predicate.
- *
- * Server names cannot contain `__` by registry validation (they are JSON
- * object keys); tool names CAN (e.g. `create_issue` has a single `_` but
- * `read_directory` has none, so the only ambiguity is when an upstream
- * tool uses double-underscore in its slug — extremely rare, but if it
- * happens the second `__` boundary still parses correctly because we
- * split on the FIRST occurrence after the prefix).
- */
-export function parseMcpToolName(name) {
-    if (!name.startsWith(MCP_TOOL_PREFIX))
-        return null;
-    const tail = name.slice(MCP_TOOL_PREFIX.length);
-    const sep = tail.indexOf('__');
-    if (sep === -1)
-        return null;
-    const serverName = tail.slice(0, sep);
-    const toolName = tail.slice(sep + 2);
-    if (serverName.length === 0 || toolName.length === 0)
-        return null;
-    return { serverName, toolName };
-}
-/**
- * Build the namespaced tool name from a server + tool pair. Inverse of
- * `parseMcpToolName`. Used by `buildMcpToolDefs` to emit the schema.
- */
-export function buildMcpToolName(serverName, toolName) {
-    return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
-}
-/**
- * Build engine-loop tool definitions from every trusted server's
- * surfaced tools. Empty array when no MCP servers are trusted — the
- * schema builder can call this unconditionally without checking first.
- */
-export function buildMcpToolDefs(registry) {
-    if (!registry)
-        return [];
-    const defs = [];
-    for (const state of registry.servers.values()) {
-        if (state.trust !== 'trusted')
-            continue;
-        for (const tool of state.surfacedTools) {
-            defs.push({
-                name: buildMcpToolName(state.name, tool.name),
-                description: descriptionFor(state.name, tool),
-                // The upstream server returns its own JSON Schema in `inputSchema`.
-                // We surface it verbatim — the loop client passes it through to
-                // the model, and the model emits arguments matching the upstream
-                // shape. Default to `{ type: 'object' }` when missing so the
-                // OpenAI-shaped tool envelope still validates.
-                parameters: tool.inputSchema ?? { type: 'object' },
-            });
-        }
-    }
-    // Sort stable so the schema bundle hash (used for caching/audit) is
-    // deterministic regardless of Map iteration order.
-    return defs.sort((a, b) => a.name.localeCompare(b.name));
-}
-function descriptionFor(serverName, tool) {
-    const base = tool.description?.trim() ?? `MCP tool ${tool.name} on server ${serverName}.`;
-    return `[MCP:${serverName}] ${base}`;
-}
-/**
- * Look up the live connection + tool metadata for a parsed MCP tool name.
- * Returns null when the server is not trusted, not connected, or does
- * not expose the named tool. Callers MUST handle null — never throw,
- * because the model may emit stale tool names after a server restart.
- */
-export function resolveMcpTool(registry, parsed) {
-    if (!registry)
-        return null;
-    const state = registry.servers.get(parsed.serverName);
-    if (!state || state.trust !== 'trusted' || !state.connection)
-        return null;
-    const tool = state.surfacedTools.find((t) => t.name === parsed.toolName);
-    if (!tool)
-        return null;
-    return { state, connection: state.connection, tool };
-}
-/**
- * The default prompt — used when no interactive bridge is wired (CI,
- * non-TTY pipes). Returns `deny` so an unattended run never silently
- * fires an MCP call the operator never approved. The deny is NOT
- * persisted, so the next run with a wired prompt still has a chance to
- * approve.
- */
-export const defaultNonInteractiveMcpPrompt = async () => 'unset';
-/**
- * Dispatch one MCP tool call. The flow:
- *
- *  1. Parse the namespaced tool name. Return error string when
- *     malformed — the model sees the error and can self-correct.
- *  2. Resolve the live connection. Return error when the server is not
- *     trusted/connected or the tool is unknown.
- *  3. Consult the permission cache. `deny` short-circuits. `allow_always`
- *     proceeds. `unset` invokes the prompt; the operator's verdict is
- *     persisted (allow_always/deny) or used one-shot (allow_once).
- *  4. Parse the arguments string. Bad JSON -> error string.
- *  5. Call `client.callTool` and stringify the content for the model.
- *
- * Throws ONLY on unrecoverable transport failures (e.g. the connection
- * died mid-call). Tool-level errors from the upstream server are
- * surfaced as `[MCP error] <message>` strings so the model can recover.
- */
-export async function dispatchMcpTool(input) {
-    const parsed = parseMcpToolName(input.name);
-    if (!parsed) {
-        return `[MCP dispatch error] tool name "${input.name}" does not match the ${MCP_TOOL_PREFIX}<server>__<tool> namespace`;
-    }
-    const resolved = resolveMcpTool(input.registry, parsed);
-    if (!resolved) {
-        return `[MCP dispatch error] no trusted+connected server "${parsed.serverName}" exposes a tool named "${parsed.toolName}"`;
-    }
-    let args;
-    try {
-        args = parseArgumentsRaw(input.argumentsRaw);
-    }
-    catch (error) {
-        return `[MCP dispatch error] invalid JSON in arguments for ${input.name}: ${error instanceof Error ? error.message : String(error)}`;
-    }
-    // Permission gate.
-    const cached = getMcpPermission(parsed.serverName, parsed.toolName);
-    let effective = cached;
-    if (cached === 'unset') {
-        const verdict = await input.prompt({
-            serverName: parsed.serverName,
-            toolName: parsed.toolName,
-            toolDescription: resolved.tool.description ?? '',
-            callArguments: args,
-        });
-        effective = verdict;
-        if (verdict === 'allow_always' || verdict === 'deny') {
-            setMcpPermission(parsed.serverName, parsed.toolName, verdict, resolveDecidedBy(input.decidedBy));
-        }
-    }
-    if (effective === 'deny') {
-        return `[MCP refused] operator denied ${parsed.serverName}:${parsed.toolName}`;
-    }
-    if (effective !== 'allow_once' && effective !== 'allow_always') {
-        // Includes `unset` returned by the non-interactive default prompt.
-        return `[MCP refused] no operator approval for ${parsed.serverName}:${parsed.toolName} (run from a TTY to approve)`;
-    }
-    // Dispatch.
-    let result;
-    try {
-        result = await callTool(resolved.connection, parsed.toolName, args, {
-            ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
-        });
-    }
-    catch (error) {
-        // Transport-level failure (timeout, child died mid-call). Surface
-        // as a recoverable string so the model can degrade gracefully.
-        return `[MCP transport error] ${parsed.serverName}:${parsed.toolName}: ${error instanceof Error ? error.message : String(error)}`;
-    }
-    return renderMcpToolResult(result.content, result.isError, parsed);
-}
-function parseArgumentsRaw(raw) {
-    if (!raw || raw.trim() === '')
-        return {};
-    const parsed = JSON.parse(raw);
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('arguments must be a JSON object');
-    }
-    return parsed;
-}
-function resolveDecidedBy(override) {
-    return (override?.trim() ||
-        process.env.PUGI_TRUSTED_BY?.trim() ||
-        process.env.USER?.trim() ||
-        process.env.USERNAME?.trim() ||
-        'cli');
-}
-/**
- * Project the MCP `content` payload into a single text string the model
- * can ingest. MCP servers reply with `content: [{ type: 'text', text }]`
- * by convention; we concatenate every `type: text` chunk and surface a
- * `[MCP non-text content]` marker for other content kinds (images,
- * resource references) which are not yet wired into Pugi's loop.
- *
- * `isError: true` from the upstream maps to a `[MCP error] ...` prefix
- * so the model knows the call failed at the server, not at the
- * transport.
- */
-export function renderMcpToolResult(content, isError, parsed) {
-    const text = projectTextContent(content);
-    const prefix = isError ? `[MCP error ${parsed.serverName}:${parsed.toolName}] ` : '';
-    if (text === null) {
-        // Fallback to a JSON dump so the model sees SOMETHING — better than
-        // an opaque empty string when the upstream uses image / resource
-        // content kinds.
-        try {
-            return `${prefix}${JSON.stringify(content)}`;
-        }
-        catch {
-            return `${prefix}[MCP non-serialisable content]`;
-        }
-    }
-    return `${prefix}${text}`;
-}
-function projectTextContent(content) {
-    if (content === null || content === undefined)
-        return '';
-    if (typeof content === 'string')
-        return content;
-    if (!Array.isArray(content))
-        return null;
-    const parts = [];
-    for (const entry of content) {
-        if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
-            const obj = entry;
-            if (obj.type === 'text' && typeof obj.text === 'string') {
-                parts.push(obj.text);
-                continue;
-            }
-        }
-        // Non-text chunk — record a marker so the model knows something was
-        // dropped from the response.
-        parts.push('[MCP non-text content chunk]');
-    }
-    return parts.join('\n');
-}
-//# sourceMappingURL=mcp-tool.js.map

package/dist/tools/multi-edit.js

@@ -1,361 +0,0 @@
-/**
- * multi_edit tool — β7 .
- *
- * Dispatches an ordered batch of file edits as a single transaction. Each
- * edit is one Layer A (oldString -> newString) operation against one
- * workspace file. Either every edit lands, or none do — failures roll
- * the workspace back to the pre-dispatch state using the same journal +
- * snapshot machinery the β1b Pl8 transactional layer uses for the
- * marker-driven dispatcher.
- *
- * Why multi_edit when `edit` already exists:
- *
- *  The single-shot `edit` tool is the right primitive for one mutation;
- *  the model uses it dozens of times in a typical session. A coordinated
- *  refactor (rename across 8 files, add an import to 12 modules, peel a
- *  helper into 5 callers) is currently 8/12/5 separate `edit` calls.
- *  Each call is its own audit + permission check + atomic write, which
- *  is the right shape for the audit story but means the model can leave
- *  the workspace half-mutated when one of the calls fails partway. The
- *  model also pays the round-trip latency once per call.
- *
- *  `multi_edit` collapses the 8/12/5 calls into one tool dispatch with
- *  transactional semantics: snapshot every target file, attempt every
- *  edit against an in-memory buffer, then commit the writes only after
- *  all in-memory edits succeed. A failure rolls back via journal +
- *  in-memory snapshot — same code path as the dispatcher.
- *
- * Security: every target file routes through the same `applySecurityGate`
- * chokepoint Layer A/B/C inherit. A path that escapes the workspace,
- * points at a protected basename (`.env`, `*.pem`, ...), or symlinks
- * outside the tree is refused BEFORE any read.
- *
- * Concurrency: marked `concurrencySafe: false` in the tool registry. The
- * model MUST NOT issue another `multi_edit` (or any write tool) in
- * parallel with one in flight; the journal serialises one dispatch per
- * session.
- *
- * Output cap: a 50-edit batch is the soft ceiling. Beyond that the tool
- * refuses with `too_many_edits` — the operator can split the refactor.
- * Empirically a coordinated refactor that needs 50+ atomic edits should
- * be a per-file Layer C rewrite instead.
- *
- * Brand voice: ASCII only, no emoji, no banned words.
- */
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { applySecurityGate } from '../core/edits/security-gate.js';
-import { appendEntry, snapshotForDispatch, } from '../core/edits/journal.js';
-import { rollbackDispatch } from '../core/edits/dispatch.js';
-import { gateOnCancellation, OperatorAbortedError } from './file-tools.js';
-import { recordFileMutation, recordToolCall, recordToolResult } from '../core/session.js';
-/** Soft cap on per-dispatch edit count. See module docstring. */
-const MULTI_EDIT_MAX = 50;
-/**
- * Apply a batch of file edits transactionally. Returns a structured
- * result; never throws on operator-attributable failure (security,
- * missing file, no_match) — only on infrastructure error (filesystem
- * permission denied mid-write after the snapshot, etc.).
- */
-export function multiEdit(ctx, edits, opts = {}) {
-    const toolCallId = recordToolCall(ctx.session, 'multi_edit', `${edits.length} edits across ${new Set(edits.map((e) => e.file)).size} files`);
-    try {
-        gateOnCancellation(ctx, 'multi_edit');
-    }
-    catch (error) {
-        if (error instanceof OperatorAbortedError) {
-            recordToolResult(ctx.session, toolCallId, 'cancelled', error.message);
-            throw error;
-        }
-        throw error;
-    }
-    if (edits.length === 0) {
-        const result = {
-            ok: false,
-            filesChanged: [],
-            editsApplied: 0,
-            reason: 'empty_batch',
-            detail: 'multi_edit received zero edits',
-            perEdit: [],
-        };
-        recordToolResult(ctx.session, toolCallId, 'error', 'empty_batch');
-        return result;
-    }
-    if (edits.length > MULTI_EDIT_MAX) {
-        const result = {
-            ok: false,
-            filesChanged: [],
-            editsApplied: 0,
-            reason: 'too_many_edits',
-            detail: `multi_edit batch of ${edits.length} exceeds cap ${MULTI_EDIT_MAX}; split the refactor`,
-            perEdit: [],
-        };
-        recordToolResult(ctx.session, toolCallId, 'error', 'too_many_edits');
-        return result;
-    }
-    // SECURITY GATE pass over every distinct file BEFORE any read.
-    // A single rejected file aborts the whole batch — the transactional
-    // contract requires we never partial-mutate.
-    const uniqueFiles = Array.from(new Set(edits.map((e) => e.file)));
-    const resolvedByFile = new Map();
-    for (const f of uniqueFiles) {
-        const gate = applySecurityGate(f, { cwd: ctx.root, toolName: 'layer-c' });
-        if (!gate.ok) {
-            const result = {
-                ok: false,
-                filesChanged: [],
-                editsApplied: 0,
-                reason: gate.reason,
-                detail: `${f}: ${gate.detail}`,
-                perEdit: edits.map((e, i) => ({
-                    index: i,
-                    file: e.file,
-                    ok: false,
-                    reason: gate.reason,
-                    detail: e.file === f ? gate.detail : 'batch aborted by sibling security failure',
-                })),
-            };
-            recordToolResult(ctx.session, toolCallId, 'error', `${gate.reason}: ${f}`);
-            return result;
-        }
-        resolvedByFile.set(f, gate.absPath);
-    }
-    // Snapshot existing files BEFORE any in-memory edit so a partial-write
-    // rollback is deterministic. The snapshot also captures sha256 of each
-    // pre-existing file so post-failure restore can verify the in-memory
-    // buffer still matches.
-    const snapshot = snapshotForDispatch(ctx.root, uniqueFiles);
-    const preContent = new Map();
-    for (const entry of snapshot) {
-        if (!entry.existed)
-            continue;
-        const abs = resolvedByFile.get(entry.path);
-        if (!abs)
-            continue;
-        try {
-            preContent.set(entry.path, readFileSync(abs));
-        }
-        catch {
-            // Best-effort. A read failure here will surface again when the
-            // per-edit phase tries to read the same file — let that path
-            // produce the operator-facing error.
-        }
-    }
-    // In-memory edit phase. For each edit we work on the latest version
-    // of the file (so two edits against the same file stack). Failure
-    // here is the common case — `no_match`, `ambiguous_match`, missing
-    // file — and aborts the whole batch.
-    const bodyByFile = new Map();
-    const perEdit = [];
-    for (let i = 0; i < edits.length; i += 1) {
-        const edit = edits[i];
-        const abs = resolvedByFile.get(edit.file);
-        if (!abs) {
-            // Should be unreachable — every distinct file went through the
-            // gate above. Belt + braces.
-            perEdit.push({ index: i, file: edit.file, ok: false, reason: 'write_error', detail: 'no resolved path' });
-            const result = {
-                ok: false,
-                filesChanged: [],
-                editsApplied: 0,
-                reason: 'write_error',
-                detail: `${edit.file}: no resolved path`,
-                perEdit,
-            };
-            recordToolResult(ctx.session, toolCallId, 'error', 'write_error');
-            return result;
-        }
-        let body = bodyByFile.get(edit.file);
-        if (body === undefined) {
-            if (!existsSync(abs)) {
-                const detail = `file does not exist: ${edit.file}`;
-                perEdit.push({ index: i, file: edit.file, ok: false, reason: 'file_missing', detail });
-                const result = {
-                    ok: false,
-                    filesChanged: [],
-                    editsApplied: 0,
-                    reason: 'file_missing',
-                    detail,
-                    perEdit,
-                };
-                recordToolResult(ctx.session, toolCallId, 'error', 'file_missing');
-                return result;
-            }
-            try {
-                body = readFileSync(abs, 'utf8');
-            }
-            catch (error) {
-                const detail = error instanceof Error ? error.message : String(error);
-                perEdit.push({ index: i, file: edit.file, ok: false, reason: 'write_error', detail });
-                const result = {
-                    ok: false,
-                    filesChanged: [],
-                    editsApplied: 0,
-                    reason: 'write_error',
-                    detail: `${edit.file}: ${detail}`,
-                    perEdit,
-                };
-                recordToolResult(ctx.session, toolCallId, 'error', 'write_error');
-                return result;
-            }
-        }
-        if (edit.oldString === edit.newString) {
-            perEdit.push({
-                index: i,
-                file: edit.file,
-                ok: false,
-                reason: 'identical_replacement',
-                detail: 'oldString and newString are identical',
-            });
-            const result = {
-                ok: false,
-                filesChanged: [],
-                editsApplied: 0,
-                reason: 'identical_replacement',
-                detail: `edit ${i} (${edit.file}): oldString and newString are identical`,
-                perEdit,
-            };
-            recordToolResult(ctx.session, toolCallId, 'error', 'identical_replacement');
-            return result;
-        }
-        const matches = countOccurrences(body, edit.oldString);
-        if (matches === 0) {
-            const detail = `edit ${i} (${edit.file}): oldString not found`;
-            perEdit.push({ index: i, file: edit.file, ok: false, reason: 'no_match', detail });
-            const result = {
-                ok: false,
-                filesChanged: [],
-                editsApplied: 0,
-                reason: 'no_match',
-                detail,
-                perEdit,
-            };
-            recordToolResult(ctx.session, toolCallId, 'error', 'no_match');
-            return result;
-        }
-        if (matches > 1) {
-            const detail = `edit ${i} (${edit.file}): oldString matches ${matches} times — expand context to make it unique`;
-            perEdit.push({ index: i, file: edit.file, ok: false, reason: 'ambiguous_match', detail });
-            const result = {
-                ok: false,
-                filesChanged: [],
-                editsApplied: 0,
-                reason: 'ambiguous_match',
-                detail,
-                perEdit,
-            };
-            recordToolResult(ctx.session, toolCallId, 'error', 'ambiguous_match');
-            return result;
-        }
-        body = body.replace(edit.oldString, edit.newString);
-        bodyByFile.set(edit.file, body);
-        perEdit.push({ index: i, file: edit.file, ok: true });
-    }
-    if (opts.dryRun) {
-        const result = {
-            ok: true,
-            filesChanged: Array.from(bodyByFile.keys()),
-            editsApplied: edits.length,
-            perEdit,
-        };
-        recordToolResult(ctx.session, toolCallId, 'success', `dry-run ${edits.length} edits ok`);
-        return result;
-    }
-    // Persist the snapshot to the journal BEFORE the first write. A crash
-    // mid-write then has a recoverable trail in `.pugi/sessions/<id>/journal.jsonl`.
-    // Best-effort; a journal write failure does not block the edits (the
-    // in-memory rollback path still covers same-process failures).
-    if (ctx.session.enabled) {
-        appendEntry(ctx.root, ctx.session.id, {
-            ts: Date.now(),
-            taskId: `multi_edit-${toolCallId}`,
-            files: snapshot,
-        });
-    }
-    // Commit phase. Atomic writes one file at a time. A failure rolls
-    // back via the same dispatcher rollback used by the marker layer.
-    const written = [];
-    for (const [file, body] of bodyByFile) {
-        const abs = resolvedByFile.get(file);
-        try {
-            atomicWrite(abs, body);
-            written.push(file);
-        }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            // Roll back every file we already touched plus restore the
-            // not-yet-touched ones that existed before (defensive — the
-            // rollback function is idempotent on untouched paths).
-            const rollback = rollbackDispatch(ctx.root, snapshot, preContent);
-            if (!rollback.ok) {
-                const result = {
-                    ok: false,
-                    filesChanged: [],
-                    editsApplied: 0,
-                    reason: 'rollback_failed',
-                    detail: `${file}: ${detail}; rollback also failed: ${rollback.detail}`,
-                    perEdit,
-                };
-                recordToolResult(ctx.session, toolCallId, 'error', 'rollback_failed');
-                return result;
-            }
-            const result = {
-                ok: false,
-                filesChanged: [],
-                editsApplied: 0,
-                reason: 'write_error',
-                detail: `${file}: ${detail}`,
-                perEdit,
-            };
-            recordToolResult(ctx.session, toolCallId, 'error', `write_error: ${detail}`);
-            return result;
-        }
-    }
-    for (const file of written) {
-        recordFileMutation(ctx.session, {
-            toolCallId,
-            path: file,
-            operation: 'update',
-        });
-    }
-    recordToolResult(ctx.session, toolCallId, 'success', `applied ${edits.length} edits across ${written.length} files`);
-    return {
-        ok: true,
-        filesChanged: written,
-        editsApplied: edits.length,
-        perEdit,
-    };
-}
-function countOccurrences(haystack, needle) {
-    if (needle.length === 0)
-        return 0;
-    let count = 0;
-    let from = 0;
-    while (true) {
-        const idx = haystack.indexOf(needle, from);
-        if (idx === -1)
-            return count;
-        count += 1;
-        from = idx + needle.length;
-    }
-}
-/** Atomic write helper — mirrors Layer A / Layer D. */
-function atomicWrite(absPath, contents) {
-    const suffix = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    const tmp = `${absPath}.pugi-tmp-${suffix}`;
-    try {
-        writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
-        renameSync(tmp, absPath);
-    }
-    catch (error) {
-        try {
-            unlinkSync(tmp);
-        }
-        catch {
-            // tmp file may not exist if writeFileSync itself failed.
-        }
-        throw error;
-    }
-}
-/** Test-only surface. */
-export const __test__ = { MULTI_EDIT_MAX };
-//# sourceMappingURL=multi-edit.js.map