@skyramp/mcp 0.2.8 → 0.2.150-rc.local.de

package/build/tools/one-click/oneClickTool.js

@@ -1,8 +1,16 @@
 import { z } from "zod";
+import fs from "fs/promises";
+import path from "path";
+import { LOCAL_DEV_SKILL_CONTENT } from "../../commands/localDevTestChangesCommand.js";
 import { lookupCommand, getAllCommands } from "../../commands/commandLibrary.js";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const TOOL_NAME = "skyramp_one_click_tool";
+export var CallingAgentIde;
+(function (CallingAgentIde) {
+    CallingAgentIde["Cursor"] = "cursor";
+    CallingAgentIde["Claude"] = "claude";
+})(CallingAgentIde || (CallingAgentIde = {}));
 /**
  * Generates the `workflow` parameter description from the live command library.
  * The LLM reads this when filling the tool call, matches the user's intent against
@@ -10,6 +18,91 @@ const TOOL_NAME = "skyramp_one_click_tool";
  * matching workflow ID. No hardcoded enum — adding a new workflow to the library
  * automatically updates this description.
  */
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertRepositoryPathIsSafe(repositoryPath) {
+    const stat = await fs.stat(repositoryPath).catch(() => undefined);
+    if (!stat?.isDirectory()) {
+        throw new Error(`repositoryPath must be an existing directory: ${repositoryPath}`);
+    }
+    if (!(await pathExists(path.join(repositoryPath, ".git")))) {
+        throw new Error(`repositoryPath must point to a git repository: ${repositoryPath}`);
+    }
+}
+function normalizeCallingAgentIde(callingAgent) {
+    switch (callingAgent?.trim().toLowerCase()) {
+        case CallingAgentIde.Cursor:
+            return CallingAgentIde.Cursor;
+        case CallingAgentIde.Claude:
+            return CallingAgentIde.Claude;
+        default:
+            return undefined;
+    }
+}
+function resolveLocalDevSkillTarget(repositoryPath, callingAgent) {
+    switch (callingAgent) {
+        case CallingAgentIde.Cursor:
+            return {
+                agent: CallingAgentIde.Cursor,
+                skillPath: path.join(repositoryPath, ".cursor", "skills", "local-dev", "SKILL.md"),
+            };
+        case CallingAgentIde.Claude:
+            return {
+                agent: CallingAgentIde.Claude,
+                skillPath: path.join(repositoryPath, ".claude", "skills", "local-dev", "SKILL.md"),
+            };
+        default:
+            return undefined;
+    }
+}
+async function ensureLocalDevSkillFile(repositoryPath, callingAgent) {
+    await assertRepositoryPathIsSafe(repositoryPath);
+    const target = resolveLocalDevSkillTarget(repositoryPath, callingAgent);
+    if (!target)
+        return {};
+    if (await pathExists(target.skillPath))
+        return { target };
+    await fs.mkdir(path.dirname(target.skillPath), { recursive: true });
+    await fs.writeFile(target.skillPath, LOCAL_DEV_SKILL_CONTENT, "utf8");
+    return { target, installed: target.skillPath };
+}
+async function buildLocalDevBootstrapStatus(params) {
+    if (params.workflow !== "local_dev_test_changes")
+        return "";
+    const skillResult = await ensureLocalDevSkillFile(params.repositoryPath, params.callingAgent);
+    const workspacePath = path.join(params.repositoryPath, ".skyramp", "workspace.yml");
+    const workspaceExists = await pathExists(workspacePath);
+    const hasUnsupportedCallingAgent = params.rawCallingAgent !== undefined && params.callingAgent === undefined;
+    const skillStatus = skillResult.installed
+        ? `Installed local-dev skill file for ${skillResult.target?.agent}:
+- ${skillResult.installed}`
+        : skillResult.target
+            ? `Local-dev skill file already installed for ${skillResult.target.agent}: ${skillResult.target.skillPath}`
+            : hasUnsupportedCallingAgent
+                ? "Local-dev skill file not installed: this agent does not support repo-local skills, so skill creation was skipped."
+                : "Local-dev skill file not installed: pass `callingAgent` as `cursor` or `claude` to install a repo-local skill. Agents without repo-local skill support can ignore this step.";
+    return `
+## Bootstrap Status
+
+${skillStatus}
+
+Base branch: ${params.baseBranch ?? "main"}
+Services to mock: ${params.servicesToMock ?? "not specified"}
+Real services: ${params.realServices ?? "not specified"}
+Mock protocols: ${params.mockProtocols ?? "not specified"}
+Calling agent: ${params.rawCallingAgent ?? params.callingAgent ?? "not specified"}
+
+Workspace config: ${workspaceExists ? `found at ${workspacePath}` : `missing at ${workspacePath}`}
+
+`;
+}
 function buildWorkflowParamDescription() {
     const commands = getAllCommands();
     const sections = commands.map((cmd) => {
@@ -29,32 +122,86 @@ function buildWorkflowParamDescription() {
     return (`The workflow to execute. Match the user's intent against the available workflows below and pass the matching workflow ID.\n\n` +
         `Available workflows:\n${sections.join("\n\n")}`);
 }
-const oneClickSchema = z.object({
-    workflow: z.string().describe(buildWorkflowParamDescription()),
-    repositoryPath: z
-        .string()
-        .describe("Absolute path to the repository (e.g., /Users/dev/my-repo). Required for all commands."),
-    endpointURL: z
-        .string()
-        .optional()
-        .describe("Full URL of the endpoint to test. Used by test_given_endpoint_comprehensively and full_repo_scan_recommend_generate_and_execute_top_n_tests. If omitted, use api.baseUrl + path from workspace or recommendation."),
-    apiSchema: z
-        .string()
-        .optional()
-        .describe("Path or URL to OpenAPI/Swagger schema. If omitted, use schema from workspace or analysis."),
-    topN: z
-        .number()
-        .optional()
-        .describe("Number of top recommended test types to generate (e.g. 3–5). Default is 3. Used by full_repo_scan_recommend_generate_and_execute_top_n_tests."),
-    token: z
-        .string()
-        .optional()
-        .describe("Authentication/session token for test execution. Always pass this to skyramp_execute_test to avoid auth errors; use empty string '' if no auth required."),
-});
+function isLocalDevWorkflowAvailable() {
+    return getAllCommands().some((cmd) => cmd.id === "local_dev_test_changes");
+}
+function buildToolDescription() {
+    const localDevInstructions = isLocalDevWorkflowAvailable()
+        ? `- When the user asks to run Skyramp local-dev, test local changes, validate a feature branch, test a branch against a base/prod/main branch, or mock downstream services for local testing: MUST call this tool with workflow \`local_dev_test_changes\`, \`callingAgent\` set to the current MCP client (\`cursor\` or \`claude\` for skill installation; VS Code does not support repo-local Agent Skills), \`repositoryPath\`, and \`baseBranch\`. Do NOT self-orchestrate — call this tool first and follow the returned instructions.\n`
+        : "";
+    return `Execute predefined, multi-step testing workflows with a single tool call.
+
+**Purpose**: The One-Click Commands tool provides a mechanism to define and execute complex, multi-step testing workflows by orchestrating multiple MCP tools in sequence. Commands enable users to accomplish high-level testing goals (e.g., "comprehensively test this endpoint") through a single invocation, without requiring new MCP tool implementations for each workflow.
+
+**When to use**:
+${localDevInstructions}- When the user names a specific endpoint and explicitly asks for comprehensive, thorough, or deep testing (e.g. "comprehensively test this endpoint", "thoroughly test the products endpoint"): MUST call this tool with workflow \`test_given_endpoint_comprehensively\`. Do NOT self-orchestrate — call this tool first and follow the returned instructions.
+- When the user wants to scan the entire repo (no specific endpoint, no PR diff) to get ranked recommendations, generate top N types, and execute: MUST call this tool with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
+- Do NOT invoke these workflows for simple single-tool requests such as "generate a smoke test" or "run this test" — call the relevant tool directly instead.
+
+**How it works**: Pass the \`workflow\` ID that matches the user's intent (see the \`workflow\` parameter description for available workflows and their trigger phrases). The tool returns a **workflow specification** (step-by-step instructions). You must then **execute that workflow** by calling the listed MCP tools in order, passing outputs (e.g. state file paths) from one step as inputs to the next. The tool does not execute other tools itself; it provides the declarative workflow for you to run.
+
+**Design**:
+- **MCP-only**: Workflows orchestrate only MCP tools; no CLI execution.
+- **Declarative**: Workflows are sequences of tool calls with dependencies.
+- **State-efficient**: State files are created only by recommendation/map tools (in system temp, e.g. /tmp); do not create any state files in the user repository.
+- **Composable**: Complex workflows are built from existing Skyramp tools.`;
+}
+function buildOneClickSchema() {
+    const schema = {
+        workflow: z.string().describe(buildWorkflowParamDescription()),
+        repositoryPath: z
+            .string()
+            .describe("Absolute path to the repository (e.g., /Users/dev/my-repo). Required for all commands."),
+        endpointURL: z
+            .string()
+            .optional()
+            .describe("Full URL of the endpoint to test. Used by test_given_endpoint_comprehensively and full_repo_scan_recommend_generate_and_execute_top_n_tests. If omitted, use api.baseUrl + path from workspace or recommendation."),
+        apiSchema: z
+            .string()
+            .optional()
+            .describe("Path or URL to OpenAPI/Swagger schema. If omitted, use schema from workspace or analysis."),
+        topN: z
+            .number()
+            .optional()
+            .describe("Number of top recommended test types to generate (e.g. 3–5). Default is 3. Used by full_repo_scan_recommend_generate_and_execute_top_n_tests."),
+        token: z
+            .string()
+            .optional()
+            .describe("Authentication/session token for test execution. Always pass this to skyramp_execute_test to avoid auth errors; use empty string '' if no auth required."),
+    };
+    if (!isLocalDevWorkflowAvailable()) {
+        return z.object(schema);
+    }
+    return z.object({
+        ...schema,
+        baseBranch: z
+            .string()
+            .optional()
+            .default("main")
+            .describe("Base branch, commit SHA, or tag to diff against. Used by local_dev_test_changes workflow. Default: 'main'. If the user names a branch such as 'prod branch', pass that exact branch only when it exists or ask for clarification; do not silently substitute main."),
+        servicesToMock: z
+            .string()
+            .optional()
+            .describe("Comma-separated downstream service names the user explicitly wants mocked in the local_dev_test_changes workflow. When the user says 'mock all', 'mock everything', 'mock all downstream', or 'mock all except X', pass the sentinel value \"all\" (not an empty string and not omitted). Omit only when the user did not express any intent to mock services."),
+        realServices: z
+            .string()
+            .optional()
+            .describe("Comma-separated service names that should receive real traffic in the local_dev_test_changes workflow, such as infrastructure, the service under test, or first-party local dependencies."),
+        mockProtocols: z
+            .string()
+            .optional()
+            .describe("Comma-separated protocols the user explicitly wants mocked in local_dev_test_changes, such as 'rest', 'grpc', or 'kafka'. Omit to use the workflow default of mocking only true third-party downstream services."),
+        callingAgent: z
+            .string()
+            .optional()
+            .describe("Calling MCP client for local_dev_test_changes. Pass 'cursor' or 'claude' to install only that agent's local-dev skill file under .cursor or .claude. Pass 'vscode' if calling from VS Code; skill creation will be skipped."),
+    });
+}
 /**
  * Build workflow instruction text from any command definition and params.
+ * Optional `stepsPreamble` is inserted between the intro header and Step 0.
  */
-function buildWorkflowFromCommand(cmd, params) {
+function buildWorkflowFromCommand(cmd, params, stepsPreamble = "") {
     const getParamDisplay = (key) => {
         const v = params[key];
         if (v === undefined || v === null)
@@ -108,6 +255,7 @@ Execute the following steps in order. Pass outputs (e.g. state file path) from o
 
 `;
     return (intro +
+        stepsPreamble +
         stepLines.join("\n\n---\n\n") +
         `
 
@@ -122,23 +270,9 @@ Execute the following steps in order. Pass outputs (e.g. state file path) from o
 `);
 }
 export function registerOneClickTool(server) {
+    const oneClickSchema = buildOneClickSchema();
     server.registerTool(TOOL_NAME, {
-        description: `Execute predefined, multi-step testing workflows with a single tool call.
-
-**Purpose**: The One-Click Commands tool provides a mechanism to define and execute complex, multi-step testing workflows by orchestrating multiple MCP tools in sequence. Commands enable users to accomplish high-level testing goals (e.g., "comprehensively test this endpoint") through a single invocation, without requiring new MCP tool implementations for each workflow.
-
-**When to use**:
-- When the user names a specific endpoint and explicitly asks for comprehensive, thorough, or deep testing (e.g. "comprehensively test this endpoint", "thoroughly test the products endpoint"): MUST call this tool with workflow \`test_given_endpoint_comprehensively\`. Do NOT self-orchestrate — call this tool first and follow the returned instructions.
-- When the user wants to scan the entire repo (no specific endpoint, no PR diff) to get ranked recommendations, generate top N types, and execute: MUST call this tool with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
-- Do NOT invoke these workflows for simple single-tool requests such as "generate a smoke test" or "run this test" — call the relevant tool directly instead.
-
-**How it works**: Pass the \`workflow\` ID that matches the user's intent (see the \`workflow\` parameter description for available workflows and their trigger phrases). The tool returns a **workflow specification** (step-by-step instructions). You must then **execute that workflow** by calling the listed MCP tools in order, passing outputs (e.g. state file paths) from one step as inputs to the next. The tool does not execute other tools itself; it provides the declarative workflow for you to run.
-
-**Design**:
-- **MCP-only**: Workflows orchestrate only MCP tools; no CLI execution.
-- **Declarative**: Workflows are sequences of tool calls with dependencies.
-- **State-efficient**: State files are created only by recommendation/map tools (in system temp, e.g. /tmp); do not create any state files in the user repository.
-- **Composable**: Complex workflows are built from existing Skyramp tools.`,
+        description: buildToolDescription(),
         inputSchema: oneClickSchema.shape,
     }, async (params) => {
         let errorResult;
@@ -148,6 +282,7 @@ export function registerOneClickTool(server) {
                 repositoryPath: params.repositoryPath,
             });
             const cmd = lookupCommand(params.workflow);
+            const normalizedCallingAgent = normalizeCallingAgentIde(params.callingAgent);
             const oneClickParams = {
                 workflow: params.workflow,
                 repositoryPath: params.repositoryPath,
@@ -155,8 +290,15 @@ export function registerOneClickTool(server) {
                 apiSchema: params.apiSchema,
                 topN: params.topN ?? 3,
                 token: params.token ?? "",
+                baseBranch: params.baseBranch,
+                servicesToMock: params.servicesToMock,
+                realServices: params.realServices,
+                mockProtocols: params.mockProtocols,
+                callingAgent: normalizedCallingAgent,
+                rawCallingAgent: params.callingAgent,
             };
-            const workflowText = buildWorkflowFromCommand(cmd, oneClickParams);
+            const bootstrapStatus = await buildLocalDevBootstrapStatus(oneClickParams);
+            const workflowText = buildWorkflowFromCommand(cmd, oneClickParams, bootstrapStatus);
             return {
                 content: [
                     {

package/build/tools/one-click/oneClickTool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/one-click/oneClickTool.test.js

@@ -0,0 +1,204 @@
+import { jest, describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+}));
+const { registerOneClickTool } = await import("./oneClickTool.js");
+function registerToolForTest() {
+    let registered;
+    const server = {
+        registerTool: jest.fn((name, config, handler) => {
+            registered = { name, config, handler };
+        }),
+    };
+    registerOneClickTool(server);
+    if (!registered)
+        throw new Error("tool was not registered");
+    return registered;
+}
+describe("skyramp_one_click_tool", () => {
+    let tmpDir;
+    let originalLocalDevEnv;
+    beforeEach(() => {
+        originalLocalDevEnv = process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = "1";
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-one-click-"));
+        execFileSync("git", ["init"], { cwd: tmpDir, stdio: "ignore" });
+    });
+    afterEach(() => {
+        if (originalLocalDevEnv === undefined) {
+            delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+        }
+        else {
+            process.env.SKYRAMP_FEATURE_LOCAL_DEV = originalLocalDevEnv;
+        }
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("routes local-dev requests and installs local-dev skill files", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "cursor",
+            baseBranch: "checkr-prod-flow",
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain("Bootstrap Status");
+        expect(text).toContain("Installed local-dev skill file for cursor");
+        expect(text).toContain("Workspace config: missing");
+        expect(text).toContain('baseCommit`: from user input');
+        expect(text).toContain('Base branch: checkr-prod-flow');
+        expect(text).toContain('Services to mock: not specified');
+        expect(text).toContain('Real services: not specified');
+        expect(text).toContain('Mock protocols: not specified');
+        expect(text).toContain('Calling agent: cursor');
+        const cursorSkill = fs.readFileSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"), "utf-8");
+        expect(cursorSkill).toContain("mock only true third-party downstream services");
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("installs only the Claude local-dev skill file", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "claude",
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain("Installed local-dev skill file for claude");
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("skips skill creation for agents without repo-local skill support", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "vscode",
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain("this agent does not support repo-local skills, so skill creation was skipped");
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("does not install a skill file without a recognized calling agent", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "unknown",
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain("this agent does not support repo-local skills, so skill creation was skipped");
+        expect(text).toContain("Calling agent: unknown");
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("asks for a supported calling agent when callingAgent is omitted", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain("pass `callingAgent` as `cursor` or `claude`");
+        expect(text).toContain("Calling agent: not specified");
+        expect(text).not.toContain("this agent does not support repo-local skills");
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("surfaces local-dev mock routing parameters in workflow text", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "cursor",
+            baseBranch: "checkr-prod-flow",
+            servicesToMock: "stripe",
+            realServices: "partner-accounts,redpanda",
+            mockProtocols: "rest",
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain("Services to mock: stripe");
+        expect(text).toContain("Real services: partner-accounts,redpanda");
+        expect(text).toContain("Mock protocols: rest");
+    });
+    it("does not install local-dev skill files outside an existing git repository", async () => {
+        const tool = registerToolForTest();
+        const nonRepo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-one-click-nonrepo-"));
+        try {
+            const result = await tool.handler({
+                workflow: "local_dev_test_changes",
+                repositoryPath: nonRepo,
+                callingAgent: "cursor",
+            });
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("repositoryPath must point to a git repository");
+            expect(result.content[0].text).not.toContain("before installing local-dev skills");
+            expect(fs.existsSync(path.join(nonRepo, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(nonRepo, { recursive: true, force: true });
+        }
+    });
+    it("validates repositoryPath even when skill creation is skipped", async () => {
+        const tool = registerToolForTest();
+        const nonRepo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-one-click-nonrepo-"));
+        try {
+            const result = await tool.handler({
+                workflow: "local_dev_test_changes",
+                repositoryPath: nonRepo,
+                callingAgent: "vscode",
+            });
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("repositoryPath must point to a git repository");
+            expect(fs.existsSync(path.join(nonRepo, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(nonRepo, { recursive: true, force: true });
+        }
+    });
+    it("advertises local-dev as a one-click workflow instead of self-orchestration", () => {
+        const tool = registerToolForTest();
+        expect(String(tool.config.description)).toContain("workflow `local_dev_test_changes`");
+        expect(String(tool.config.description)).toContain("Do NOT self-orchestrate");
+    });
+    it("hides local-dev workflow when the feature flag is disabled", async () => {
+        delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+        const tool = registerToolForTest();
+        expect(String(tool.config.description)).not.toContain("local_dev_test_changes");
+        expect(String(tool.config.inputSchema)).not.toContain("local_dev_test_changes");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("baseBranch");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("servicesToMock");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("realServices");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("mockProtocols");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("callingAgent");
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Unknown workflow: "local_dev_test_changes"');
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+});

package/build/tools/preflightMockCheckTool.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPreflightMockCheckTool(server: McpServer): void;

package/build/tools/preflightMockCheckTool.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { validateMockCompatibility, MockProtocol, } from "../utils/mockCompatibility.js";
+const warningSchema = z.object({
+    code: z.string().describe("Warning code identifier (e.g. REST_LOOPBACK_URL, GRPC_PERSISTENT_CONN)."),
+    message: z.string().describe("Human-readable description of the issue."),
+    suggestion: z.string().describe("Recommended action to resolve or work around the issue."),
+    affectedMocks: z.array(z.string()).describe("Mock identifiers (service name or endpoint URL) affected by this warning."),
+    blocking: z.boolean().optional().describe("When true, the affected mocks cannot intercept traffic and must not be generated or deployed."),
+});
+const preflightOutputSchema = {
+    hasBlockers: z.boolean().describe("True when at least one warning is blocking. Blocking mocks must be removed from the generation list before proceeding."),
+    warnings: z.array(warningSchema).describe("All compatibility warnings. Inspect the blocking field on each entry; blocking ones must be skipped, advisory ones may proceed with caution."),
+};
+const TOOL_NAME = "skyramp_preflight_mock_check";
+const mockSpecSchema = z.object({
+    protocol: z.nativeEnum(MockProtocol).describe("The protocol of the mock"),
+    endpointURL: z.string().describe("The endpoint URL for the mock"),
+    method: z.string().optional().describe("HTTP method (for REST mocks)"),
+    grpcServiceName: z.string().optional().describe("gRPC service name (for gRPC mocks)"),
+    kafkaTopic: z.string().optional().describe("Kafka topic (for Kafka mocks)"),
+});
+const inputSchema = {
+    mocks: z
+        .array(mockSpecSchema)
+        .min(1)
+        .describe("Array of mock specifications to validate for compatibility"),
+};
+function formatWarning(warning) {
+    const icon = warning.blocking ? "🚫" : "⚠️ ";
+    return [
+        `${icon} [${warning.code}]${warning.blocking ? " BLOCKING — do not generate or deploy these mocks" : ""}`,
+        `   ${warning.message}`,
+        `   Suggestion: ${warning.suggestion}`,
+        `   Affected: ${warning.affectedMocks.join(", ")}`,
+    ].join("\n");
+}
+export function registerPreflightMockCheckTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: "Pre-flight compatibility check for mock deployments. Validates that a set of mocks " +
+            "can be deployed together without known protocol conflicts (e.g., REST loopback URLs in Docker local-dev " +
+            "and gRPC persistent connection caveats). Returns two classes of " +
+            "issues: advisory warnings (mocks are deployable but may exhibit runtime issues) and " +
+            "blocking warnings (mocks cannot intercept traffic and must not be generated or deployed). " +
+            "Check hasBlockers in the result and the blocking flag on each warning before proceeding.",
+        inputSchema,
+        outputSchema: preflightOutputSchema,
+    }, async (params) => {
+        const mocks = params.mocks;
+        const result = validateMockCompatibility(mocks, { dockerLocalDev: true });
+        let text;
+        if (result.warnings.length === 0) {
+            text = [
+                "✅ Pre-flight check passed — all clear.",
+                "",
+                `${mocks.length} mock(s) validated. No known compatibility issues detected.`,
+                "Safe to deploy in a single apply_mock() call.",
+            ].join("\n");
+        }
+        else {
+            const blockingCount = result.warnings.filter((w) => w.blocking).length;
+            const advisoryCount = result.warnings.length - blockingCount;
+            const headerParts = [];
+            if (blockingCount > 0)
+                headerParts.push(`${blockingCount} blocking`);
+            if (advisoryCount > 0)
+                headerParts.push(`${advisoryCount} advisory`);
+            text = [
+                `⚠️  Pre-flight check: ${result.warnings.length} issue(s) detected (${headerParts.join(", ")}).`,
+                "",
+                ...result.warnings.map(formatWarning),
+                "",
+                result.hasBlockers
+                    ? "🚫 Blocking mocks must be removed from the generation list — they cannot intercept traffic. Advisory mocks may still be deployed with the caveats noted above."
+                    : "Advisory warnings only — mocks are deployable, but consider the suggestions above to avoid runtime issues.",
+            ].join("\n");
+        }
+        return {
+            structuredContent: {
+                hasBlockers: result.hasBlockers,
+                warnings: result.warnings.map((w) => ({
+                    code: w.code,
+                    message: w.message,
+                    suggestion: w.suggestion,
+                    affectedMocks: w.affectedMocks,
+                    ...(w.blocking !== undefined ? { blocking: w.blocking } : {}),
+                })),
+            },
+            content: [{ type: "text", text }],
+        };
+    });
+}

package/build/tools/test-management/analyzeChangesTool.d.ts

@@ -15,11 +15,12 @@ export declare const analyzeChangesInputSchema: {
     scope: z.ZodOptional<z.ZodDefault<z.ZodEnum<["full_repo", "branch_diff"]>>>;
     baseBranch: z.ZodOptional<z.ZodString>;
     testDirectory: z.ZodOptional<z.ZodString>;
-    topN: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    topN: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     maxGenerate: z.ZodOptional<z.ZodNumber>;
     prNumber: z.ZodOptional<z.ZodNumber>;
     repository: z.ZodOptional<z.ZodString>;
     testsRepoDir: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    includeUncommitted: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };
 export declare const NO_UI_INSTRUCTIONS = "No UI changes detected \u2014 no blueprint capture needed.";
 export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (workspace baseUrl missing or no router files matched). UI recommendations will be source-grounded only.";