@getripple/mcp 1.0.4

package/dist/tools.js

@@ -0,0 +1,706 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRippleMcpToolHost = exports.RippleMcpToolHost = exports.RIPPLE_MCP_TOOLS = void 0;
+const path = __importStar(require("path"));
+const core_1 = require("@getripple/core");
+const MCP_CONTROL_MODES = ["brainstorm", "function", "file", "task", "pr"];
+const MCP_AUDIT_MODES = ["staged", "changed"];
+const MCP_APPROVAL_GATES = ["before-risky-edit", "before-merge"];
+exports.RIPPLE_MCP_TOOLS = [
+    {
+        name: "ripple_doctor",
+        description: "Return Ripple readiness diagnostics for graph scanning, git, CI workflow, and latest change intent.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_check_changed",
+        description: "Return Ripple's changed-file safety check for JS/TS changes against a base git ref.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                baseRef: {
+                    type: "string",
+                    description: "Git base ref to diff against, for example HEAD or origin/main.",
+                },
+                tokenBudget: {
+                    type: "number",
+                    description: "Maximum context token budget per changed file.",
+                },
+                intentPath: {
+                    type: "string",
+                    description: "Optional saved Ripple change intent path, id, or latest.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_check_staged",
+        description: "Return Ripple's staged-file safety check for currently staged JS/TS changes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tokenBudget: {
+                    type: "number",
+                    description: "Maximum context token budget per staged file.",
+                },
+                intentPath: {
+                    type: "string",
+                    description: "Optional saved Ripple change intent path, id, or latest.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_audit_change",
+        description: "Return one compact audit report: saved intent, current policy, drift check, repair plan, and final decision.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mode: {
+                    type: "string",
+                    enum: MCP_AUDIT_MODES,
+                    description: "Audit staged files by default, or changed files against baseRef.",
+                },
+                baseRef: {
+                    type: "string",
+                    description: "Git base ref for mode=changed, for example HEAD or origin/main.",
+                },
+                tokenBudget: {
+                    type: "number",
+                    description: "Maximum context token budget per audited file.",
+                },
+                intentPath: {
+                    type: "string",
+                    description: "Saved Ripple change intent path, id, or latest. Defaults to latest.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_gate",
+        description: "Return the compact continue/stop gate decision for a saved Ripple intent without the full audit report.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mode: {
+                    type: "string",
+                    enum: MCP_AUDIT_MODES,
+                    description: "Gate staged files by default, or changed files against baseRef.",
+                },
+                baseRef: {
+                    type: "string",
+                    description: "Git base ref for mode=changed, for example HEAD or origin/main.",
+                },
+                tokenBudget: {
+                    type: "number",
+                    description: "Maximum context token budget per gated file.",
+                },
+                intentPath: {
+                    type: "string",
+                    description: "Saved Ripple change intent path, id, or latest. Defaults to latest.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_get_approval_status",
+        description: "Return whether the saved Ripple change intent has a valid, missing, stale, or not-required human approval record.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                intentPath: {
+                    type: "string",
+                    description: "Saved Ripple change intent path, id, or latest. Defaults to latest.",
+                },
+                gate: {
+                    type: "string",
+                    enum: MCP_APPROVAL_GATES,
+                    description: "Optional approval gate override.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_repair_intent_drift",
+        description: "Return a concrete repair plan for staged changes that drifted from a saved Ripple change intent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tokenBudget: {
+                    type: "number",
+                    description: "Maximum context token budget per staged file.",
+                },
+                intentPath: {
+                    type: "string",
+                    description: "Saved Ripple change intent path, id, or latest.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_get_agent_workflow",
+        description: "Return the Ripple agent workflow protocol and command/output contracts.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_get_focus",
+        description: "Return focused architectural context for one target file.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filePath: {
+                    type: "string",
+                    description: "Project-relative or absolute path to a JS/TS file.",
+                },
+            },
+            required: ["filePath"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_get_blast_radius",
+        description: "Return direct downstream files affected by changing one file.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filePath: {
+                    type: "string",
+                    description: "Project-relative or absolute path to a JS/TS file.",
+                },
+            },
+            required: ["filePath"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_explain_policy",
+        description: "Return the repo trust-boundary policy that applies to one target file before an agent plans or edits.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filePath: {
+                    type: "string",
+                    description: "Project-relative or absolute target file path.",
+                },
+                targetFile: {
+                    type: "string",
+                    description: "Alias for filePath.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_plan_context",
+        description: "Return a token-budgeted read plan for a task and target file, optionally saving an agent control boundary.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "Short description of the coding task.",
+                },
+                filePath: {
+                    type: "string",
+                    description: "Project-relative or absolute target file path.",
+                },
+                targetFile: {
+                    type: "string",
+                    description: "Alias for filePath.",
+                },
+                tokenBudget: {
+                    type: "number",
+                    description: "Maximum context token budget.",
+                },
+                mode: {
+                    type: "string",
+                    enum: MCP_CONTROL_MODES,
+                    description: "Agent control boundary for the saved intent. Defaults to file.",
+                },
+                controlMode: {
+                    type: "string",
+                    enum: MCP_CONTROL_MODES,
+                    description: "Alias for mode.",
+                },
+                symbol: {
+                    type: "string",
+                    description: "Allowed symbol name for function mode.",
+                },
+                allowedSymbols: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Allowed symbol ids or names for function mode.",
+                },
+                saveIntent: {
+                    type: "boolean",
+                    description: "When true, save a Ripple change intent for later staged-check validation.",
+                },
+                intentPath: {
+                    type: "string",
+                    description: "Optional path or id for the saved change intent. Defaults to latest.",
+                },
+            },
+            required: ["task"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ripple_get_recent_changes",
+        description: "Return recent Ripple history groups for this workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of history groups to return.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+class RippleMcpToolHost {
+    constructor(options) {
+        this.scanned = false;
+        this.workspaceRoot = path.resolve(options.workspaceRoot);
+        this.engine = new core_1.GraphEngine(this.workspaceRoot);
+    }
+    listTools() {
+        return exports.RIPPLE_MCP_TOOLS;
+    }
+    async initialize() {
+        if (this.scanned) {
+            return;
+        }
+        await runWithQuietConsoleLog(() => this.engine.initialScan());
+        this.scanned = true;
+    }
+    dispose() {
+        this.engine.dispose();
+    }
+    async callTool(name, args = {}) {
+        if (name === "ripple_get_agent_workflow") {
+            return {
+                tool: name,
+                data: (0, core_1.getAgentWorkflowSummary)(),
+            };
+        }
+        if (name === "ripple_explain_policy") {
+            return {
+                tool: name,
+                data: this.explainPolicy(args),
+            };
+        }
+        if (name === "ripple_get_approval_status") {
+            return {
+                tool: name,
+                data: this.getApprovalStatus(args),
+            };
+        }
+        await this.initialize();
+        if (name === "ripple_get_focus") {
+            return {
+                tool: name,
+                data: this.getFocus(args),
+            };
+        }
+        if (name === "ripple_doctor") {
+            return {
+                tool: name,
+                data: this.getReadiness(),
+            };
+        }
+        if (name === "ripple_get_blast_radius") {
+            return {
+                tool: name,
+                data: this.getBlastRadius(args),
+            };
+        }
+        if (name === "ripple_plan_context") {
+            return {
+                tool: name,
+                data: this.planContext(args),
+            };
+        }
+        if (name === "ripple_check_staged") {
+            return {
+                tool: name,
+                data: this.checkStaged(args),
+            };
+        }
+        if (name === "ripple_check_changed") {
+            return {
+                tool: name,
+                data: this.checkChanged(args),
+            };
+        }
+        if (name === "ripple_audit_change") {
+            return {
+                tool: name,
+                data: this.auditChange(args),
+            };
+        }
+        if (name === "ripple_gate") {
+            return {
+                tool: name,
+                data: this.gateChange(args),
+            };
+        }
+        if (name === "ripple_repair_intent_drift") {
+            return {
+                tool: name,
+                data: this.repairIntentDrift(args),
+            };
+        }
+        if (name === "ripple_get_recent_changes") {
+            return {
+                tool: name,
+                data: this.getRecentChanges(args),
+            };
+        }
+        const exhaustiveCheck = name;
+        throw new Error(`Unknown Ripple MCP tool: ${exhaustiveCheck}`);
+    }
+    getFocus(args) {
+        const filePath = requiredString(args, "filePath");
+        const focus = this.engine.getFileFocusSummary(filePath);
+        if (!focus) {
+            throw new Error(`File is not in the Ripple graph: ${filePath}`);
+        }
+        return focus;
+    }
+    getReadiness() {
+        return (0, core_1.buildRippleReadinessSummary)(this.workspaceRoot, this.engine);
+    }
+    getBlastRadius(args) {
+        const filePath = requiredString(args, "filePath");
+        const blastRadius = this.engine.getBlastRadiusSummary(filePath);
+        if (!blastRadius) {
+            throw new Error(`File is not in the Ripple graph: ${filePath}`);
+        }
+        return blastRadius;
+    }
+    explainPolicy(args) {
+        const filePath = optionalString(args, "filePath") ?? optionalString(args, "targetFile");
+        if (!filePath) {
+            throw new Error("ripple_explain_policy requires filePath or targetFile.");
+        }
+        return (0, core_1.explainRipplePolicyForTarget)((0, core_1.loadRipplePolicy)(this.workspaceRoot), normalizeProjectPath(filePath));
+    }
+    planContext(args) {
+        const parsed = parsePlanContextArgs(args);
+        const targetFile = parsed.filePath ?? parsed.targetFile;
+        if (!targetFile) {
+            throw new Error("ripple_plan_context requires filePath or targetFile.");
+        }
+        const plan = this.engine.planContext(parsed.task ?? "", targetFile, parsed.tokenBudget);
+        if (!plan) {
+            throw new Error(`File is not in the Ripple graph: ${targetFile}`);
+        }
+        const loadedPolicy = (0, core_1.loadRipplePolicy)(this.workspaceRoot);
+        const policyExplanation = (0, core_1.explainRipplePolicyForTarget)(loadedPolicy, plan.targetFile, {
+            controlMode: parsed.controlMode ?? parsed.mode,
+        });
+        if (!parsed.saveIntent) {
+            return {
+                ...plan,
+                policyExplanation,
+            };
+        }
+        const policy = (0, core_1.resolveRipplePolicyForTarget)(loadedPolicy, plan.targetFile);
+        const changeIntent = (0, core_1.buildChangeIntent)(plan, {
+            controlMode: parsed.controlMode ?? parsed.mode,
+            allowedSymbols: uniqueItems([
+                ...(parsed.allowedSymbols ?? []),
+                ...(parsed.symbol ? [parsed.symbol] : []),
+            ]),
+            policy,
+            policyExplanation,
+        });
+        const savedPath = (0, core_1.saveChangeIntent)(this.workspaceRoot, changeIntent, parsed.intentPath);
+        const readiness = (0, core_1.buildRippleReadinessSummary)(this.workspaceRoot, this.engine);
+        changeIntent.readinessSnapshot = (0, core_1.buildChangeIntentReadinessSnapshot)(readiness);
+        (0, core_1.saveChangeIntent)(this.workspaceRoot, changeIntent, savedPath);
+        return {
+            ...plan,
+            policyExplanation,
+            changeIntent,
+            changeIntentPath: formatWorkspacePath(this.workspaceRoot, savedPath),
+        };
+    }
+    getRecentChanges(args) {
+        return this.engine.getRecentHistorySummary(optionalPositiveInteger(args, "limit", 10));
+    }
+    getApprovalStatus(args) {
+        const intentPath = optionalString(args, "intentPath") ?? "latest";
+        const intent = (0, core_1.loadChangeIntent)(this.workspaceRoot, intentPath);
+        return approvalStatusWithIntent(intent, (0, core_1.resolveRippleApprovalStatus)(this.workspaceRoot, intent, optionalApprovalGate(args, "gate")));
+    }
+    checkStaged(args) {
+        const stagedSummary = (0, core_1.buildStagedCheckSummary)(this.engine, {
+            workspaceRoot: this.workspaceRoot,
+            stagedFiles: (0, core_1.listGitStagedFiles)(this.workspaceRoot),
+            tokenBudget: optionalPositiveInteger(args, "tokenBudget", 4000),
+        });
+        const intentPath = optionalString(args, "intentPath");
+        if (!intentPath) {
+            return stagedSummary;
+        }
+        const intent = (0, core_1.loadChangeIntent)(this.workspaceRoot, intentPath);
+        return (0, core_1.validateStagedCheckAgainstIntent)(stagedSummary, intent, {
+            currentPolicyExplanation: this.currentPolicyExplanationForIntent(intent),
+            currentReadinessSnapshot: this.currentReadinessSnapshot(),
+        });
+    }
+    checkChanged(args) {
+        const baseRef = optionalString(args, "baseRef") ?? "HEAD";
+        const changedSummary = (0, core_1.buildStagedCheckSummary)(this.engine, {
+            workspaceRoot: this.workspaceRoot,
+            stagedFiles: (0, core_1.listGitChangedFiles)(this.workspaceRoot, baseRef),
+            mode: "changed",
+            baseRef,
+            tokenBudget: optionalPositiveInteger(args, "tokenBudget", 4000),
+        });
+        const intentPath = optionalString(args, "intentPath");
+        if (!intentPath) {
+            return changedSummary;
+        }
+        const intent = (0, core_1.loadChangeIntent)(this.workspaceRoot, intentPath);
+        return (0, core_1.validateStagedCheckAgainstIntent)(changedSummary, intent, {
+            currentPolicyExplanation: this.currentPolicyExplanationForIntent(intent),
+            currentReadinessSnapshot: this.currentReadinessSnapshot(),
+        });
+    }
+    auditChange(args) {
+        const mode = optionalAuditMode(args, "mode") ?? "staged";
+        const baseRef = optionalString(args, "baseRef") ?? "HEAD";
+        const intentPath = optionalString(args, "intentPath") ?? "latest";
+        const intent = (0, core_1.loadChangeIntent)(this.workspaceRoot, intentPath);
+        const currentPolicyExplanation = this.currentPolicyExplanationForIntent(intent);
+        const stagedCheck = (0, core_1.buildStagedCheckSummary)(this.engine, {
+            workspaceRoot: this.workspaceRoot,
+            stagedFiles: mode === "changed"
+                ? (0, core_1.listGitChangedFiles)(this.workspaceRoot, baseRef)
+                : (0, core_1.listGitStagedFiles)(this.workspaceRoot),
+            mode,
+            baseRef: mode === "changed" ? baseRef : undefined,
+            tokenBudget: optionalPositiveInteger(args, "tokenBudget", 4000),
+        });
+        const validatedCheck = (0, core_1.validateStagedCheckAgainstIntent)(stagedCheck, intent, {
+            currentPolicyExplanation,
+            currentReadinessSnapshot: this.currentReadinessSnapshot(),
+        });
+        const repairPlan = (0, core_1.buildIntentDriftRepairPlan)(validatedCheck);
+        return (0, core_1.buildRippleAuditSummary)({
+            workspaceRoot: this.workspaceRoot,
+            mode,
+            baseRef: mode === "changed" ? baseRef : undefined,
+            stagedCheck: validatedCheck,
+            repairPlan,
+            intent,
+            currentPolicyExplanation,
+        });
+    }
+    gateChange(args) {
+        return (0, core_1.buildRippleGateSummary)(this.auditChange(args));
+    }
+    repairIntentDrift(args) {
+        const intentPath = optionalString(args, "intentPath") ?? "latest";
+        const stagedSummary = this.checkStaged({
+            tokenBudget: optionalPositiveInteger(args, "tokenBudget", 4000),
+            intentPath,
+        });
+        return (0, core_1.buildIntentDriftRepairPlan)(stagedSummary);
+    }
+    currentPolicyExplanationForIntent(intent) {
+        return (0, core_1.explainRipplePolicyForIntent)((0, core_1.loadRipplePolicy)(this.workspaceRoot), intent);
+    }
+    currentReadinessSnapshot() {
+        return (0, core_1.buildChangeIntentReadinessSnapshot)((0, core_1.buildRippleReadinessSummary)(this.workspaceRoot, this.engine));
+    }
+}
+exports.RippleMcpToolHost = RippleMcpToolHost;
+function createRippleMcpToolHost(options) {
+    return new RippleMcpToolHost(options);
+}
+exports.createRippleMcpToolHost = createRippleMcpToolHost;
+function requiredString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return value;
+}
+function optionalString(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string.`);
+    }
+    return value;
+}
+function optionalControlMode(args, key) {
+    const value = optionalString(args, key);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (MCP_CONTROL_MODES.includes(value)) {
+        return value;
+    }
+    throw new Error(`${key} must be one of: ${MCP_CONTROL_MODES.join(", ")}.`);
+}
+function optionalAuditMode(args, key) {
+    const value = optionalString(args, key);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (MCP_AUDIT_MODES.includes(value)) {
+        return value;
+    }
+    throw new Error(`${key} must be one of: ${MCP_AUDIT_MODES.join(", ")}.`);
+}
+function optionalApprovalGate(args, key) {
+    const value = optionalString(args, key);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (MCP_APPROVAL_GATES.includes(value)) {
+        return value;
+    }
+    throw new Error(`${key} must be one of: ${MCP_APPROVAL_GATES.join(", ")}.`);
+}
+function optionalStringArray(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`${key} must be an array of strings.`);
+    }
+    return value;
+}
+function optionalPositiveInteger(args, key, fallback) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new Error(`${key} must be a positive integer.`);
+    }
+    return value;
+}
+function optionalBoolean(args, key, fallback) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${key} must be a boolean.`);
+    }
+    return value;
+}
+function parsePlanContextArgs(args) {
+    return {
+        task: optionalString(args, "task"),
+        filePath: optionalString(args, "filePath"),
+        targetFile: optionalString(args, "targetFile"),
+        tokenBudget: optionalPositiveInteger(args, "tokenBudget", 4000),
+        mode: optionalControlMode(args, "mode"),
+        controlMode: optionalControlMode(args, "controlMode"),
+        symbol: optionalString(args, "symbol"),
+        allowedSymbols: optionalStringArray(args, "allowedSymbols"),
+        saveIntent: optionalBoolean(args, "saveIntent", false),
+        intentPath: optionalString(args, "intentPath"),
+    };
+}
+function uniqueItems(items) {
+    const seen = new Set();
+    return items.filter((item) => {
+        if (seen.has(item)) {
+            return false;
+        }
+        seen.add(item);
+        return true;
+    });
+}
+function approvalStatusWithIntent(intent, status) {
+    return {
+        ...status,
+        intent: {
+            id: intent.id,
+            task: intent.task,
+            targetFile: intent.targetFile,
+            controlMode: intent.controlMode,
+            humanGate: intent.humanGate,
+            boundaryRisk: intent.boundaryRisk,
+        },
+    };
+}
+function formatWorkspacePath(workspaceRoot, filePath) {
+    const relative = path.relative(workspaceRoot, filePath);
+    if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+        return relative.split(path.sep).join("/");
+    }
+    return filePath;
+}
+function normalizeProjectPath(filePath) {
+    return filePath.replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+async function runWithQuietConsoleLog(task) {
+    const originalLog = console.log;
+    const originalStdoutWrite = process.stdout.write;
+    const stderrWrite = process.stderr.write;
+    console.log = (...args) => {
+        console.error(...args);
+    };
+    process.stdout.write = ((...args) => {
+        return stderrWrite.apply(process.stderr, args);
+    });
+    try {
+        return await task();
+    }
+    finally {
+        console.log = originalLog;
+        process.stdout.write = originalStdoutWrite;
+    }
+}
+//# sourceMappingURL=tools.js.map