@skyramp/mcp 0.3.0 → 0.3.1-ldw-beta

package/build/commands/commandLibrary.d.ts

@@ -9,3 +9,4 @@ export declare function getCommandIds(): OneClickCommandId[];
 export declare function lookupCommand(id: string): OneClickCommandDef;
 export { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
 export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
+export { LOCAL_DEV_TEST_CHANGES_COMMAND } from "./localDevTestChangesCommand.js";

package/build/commands/commandLibrary.js

@@ -1,23 +1,28 @@
+import { isLocalDevEnabled, isOneClickEnabled } from "../utils/featureFlags.js";
 import { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
 import { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
-/**
- * To add a new predefined workflow:
- * 1. Add a new id to OneClickCommandId in types/OneClickCommands.ts
- * 2. Create a new file in commands/ (e.g. myWorkflowCommand.ts) with steps and export the command
- * 3. Import the command here and add it to COMMAND_LIBRARY
- * 4. The generic buildWorkflowFromCommand() will render detailed instructions from your steps
- *    (no schema changes needed in oneClickTool.ts — the workflow param description is generated dynamically)
- */
-/** All predefined one-click commands */
-const COMMAND_LIBRARY = {
+import { LOCAL_DEV_TEST_CHANGES_COMMAND } from "./localDevTestChangesCommand.js";
+/** Base predefined one-click commands */
+const BASE_COMMAND_LIBRARY = {
     test_given_endpoint_comprehensively: TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND,
     full_repo_scan_recommend_generate_and_execute_top_n_tests: FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND,
 };
+/** All enabled predefined one-click commands */
+function getCommandLibrary() {
+    const commands = {};
+    if (isOneClickEnabled()) {
+        Object.assign(commands, BASE_COMMAND_LIBRARY);
+    }
+    if (isLocalDevEnabled()) {
+        commands.local_dev_test_changes = LOCAL_DEV_TEST_CHANGES_COMMAND;
+    }
+    return commands;
+}
 export function getAllCommands() {
-    return Object.values(COMMAND_LIBRARY);
+    return Object.values(getCommandLibrary()).filter((cmd) => Boolean(cmd));
 }
 export function getCommandIds() {
-    return Object.keys(COMMAND_LIBRARY);
+    return getAllCommands().map((cmd) => cmd.id);
 }
 /**
  * Look up a command by its string ID. Accepts any string so the tool handler
@@ -25,7 +30,7 @@ export function getCommandIds() {
  * the ID is not found.
  */
 export function lookupCommand(id) {
-    const cmd = COMMAND_LIBRARY[id];
+    const cmd = getCommandLibrary()[id];
     if (!cmd) {
         const available = getCommandIds().join(", ");
         throw new Error(`Unknown workflow: "${id}". Valid workflow IDs: ${available}.`);
@@ -35,3 +40,4 @@ export function lookupCommand(id) {
 // Re-export commands for consumers that import from commandLibrary
 export { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
 export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
+export { LOCAL_DEV_TEST_CHANGES_COMMAND } from "./localDevTestChangesCommand.js";

package/build/commands/commandLibrary.test.d.ts

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

package/build/commands/commandLibrary.test.js

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it } from "@jest/globals";
+import { getCommandIds, lookupCommand } from "./commandLibrary.js";
+const originalOneClick = process.env.SKYRAMP_FEATURE_ONE_CLICK;
+const originalLocalDev = process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+function setFlags(oneClick, localDev) {
+    if (oneClick === undefined) {
+        delete process.env.SKYRAMP_FEATURE_ONE_CLICK;
+    }
+    else {
+        process.env.SKYRAMP_FEATURE_ONE_CLICK = oneClick;
+    }
+    if (localDev === undefined) {
+        delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+    }
+    else {
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = localDev;
+    }
+}
+afterEach(() => {
+    if (originalOneClick === undefined) {
+        delete process.env.SKYRAMP_FEATURE_ONE_CLICK;
+    }
+    else {
+        process.env.SKYRAMP_FEATURE_ONE_CLICK = originalOneClick;
+    }
+    if (originalLocalDev === undefined) {
+        delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+    }
+    else {
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = originalLocalDev;
+    }
+});
+describe("command library feature gates", () => {
+    it("exposes no one-click workflows when both one-click and local-dev are disabled", () => {
+        setFlags(undefined, undefined);
+        expect(getCommandIds()).toEqual([]);
+    });
+    it("exposes only base one-click workflows when one-click is enabled", () => {
+        setFlags("1", undefined);
+        expect(getCommandIds().sort()).toEqual([
+            "full_repo_scan_recommend_generate_and_execute_top_n_tests",
+            "test_given_endpoint_comprehensively",
+        ]);
+    });
+    it("exposes only local-dev when local-dev is enabled without general one-click", () => {
+        setFlags(undefined, "1");
+        expect(getCommandIds()).toEqual(["local_dev_test_changes"]);
+        expect(lookupCommand("local_dev_test_changes").id).toBe("local_dev_test_changes");
+        expect(() => lookupCommand("test_given_endpoint_comprehensively")).toThrow(/Unknown workflow/);
+    });
+    it("exposes base and local-dev workflows when both flags are enabled", () => {
+        setFlags("1", "1");
+        expect(getCommandIds().sort()).toEqual([
+            "full_repo_scan_recommend_generate_and_execute_top_n_tests",
+            "local_dev_test_changes",
+            "test_given_endpoint_comprehensively",
+        ]);
+    });
+});

package/build/commands/localDevTestChangesCommand.d.ts

@@ -0,0 +1,15 @@
+import type { OneClickCommandDef } from "../types/OneClickCommands.js";
+/**
+ * Predefined One-Click Command: Local Dev — Test Changes
+ *
+ * This is the BOOTSTRAPPER / ENTRY POINT for local-dev testing.
+ * It handles first-time setup (skills + workspace), then delegates
+ * the actual test workflow to the `skyramp_local_dev` MCP prompt.
+ *
+ * Flow:
+ *   Step 0: Install IDE skill into repo for the calling agent
+ *   Step 1: Ensure .skyramp/workspace.yml exists
+ *   Step 2: Invoke skyramp_local_dev prompt (which runs the full workflow)
+ */
+export declare const LOCAL_DEV_SKILL_CONTENT = "---\nname: local-dev\ndescription: Run the Skyramp MCP local-dev workflow to test local code changes against a base branch. Use when the user asks to test changes, mock downstream services, validate a feature branch, run local-dev, or verify a PR before merge.\nuser_invocable: true\n---\n\n# local-dev\n\nUse the Skyramp MCP local-dev workflow as the source of truth. Do not recreate the workflow steps from this skill.\n\n## Usage\n\n`/local-dev` \u2014 diff against main (default)\n`/local-dev main --mock stripe,billing --real postgres,redis`\n\n## Invocation\n\nCall the `skyramp_local_dev` MCP prompt with the user's intent preserved:\n- `baseCommit`: branch/SHA to diff against (default: main)\n- `repositoryPath`: absolute path to repo\n- `servicesToMock`: comma-separated services the user explicitly wants mocked\n- `realServices`: comma-separated services that should receive real traffic\n- `mockProtocols`: comma-separated protocols the user explicitly wants mocked (for example, `rest`)\n\nBy default, mock only true third-party downstream services. Keep the service under test, infrastructure, and local first-party services real unless the user explicitly asks to mock them.\n";
+export declare const LOCAL_DEV_TEST_CHANGES_COMMAND: OneClickCommandDef;

package/build/commands/localDevTestChangesCommand.js

@@ -0,0 +1,201 @@
+import { localDevPlan, } from "../prompts/local-dev/local-dev-plan.js";
+/**
+ * Predefined One-Click Command: Local Dev — Test Changes
+ *
+ * This is the BOOTSTRAPPER / ENTRY POINT for local-dev testing.
+ * It handles first-time setup (skills + workspace), then delegates
+ * the actual test workflow to the `skyramp_local_dev` MCP prompt.
+ *
+ * Flow:
+ *   Step 0: Install IDE skill into repo for the calling agent
+ *   Step 1: Ensure .skyramp/workspace.yml exists
+ *   Step 2: Invoke skyramp_local_dev prompt (which runs the full workflow)
+ */
+// ── Skill content (single source of truth) ──────────────────────────────────
+// These get written to user repos by Step 0. Edit here, not in separate files.
+export const LOCAL_DEV_SKILL_CONTENT = `---
+name: local-dev
+description: Run the Skyramp MCP local-dev workflow to test local code changes against a base branch. Use when the user asks to test changes, mock downstream services, validate a feature branch, run local-dev, or verify a PR before merge.
+user_invocable: true
+---
+
+# local-dev
+
+Use the Skyramp MCP local-dev workflow as the source of truth. Do not recreate the workflow steps from this skill.
+
+## Usage
+
+\`/local-dev\` — diff against main (default)
+\`/local-dev main --mock stripe,billing --real postgres,redis\`
+
+## Invocation
+
+Call the \`skyramp_local_dev\` MCP prompt with the user's intent preserved:
+- \`baseCommit\`: branch/SHA to diff against (default: main)
+- \`repositoryPath\`: absolute path to repo
+- \`servicesToMock\`: comma-separated services the user explicitly wants mocked
+- \`realServices\`: comma-separated services that should receive real traffic
+- \`mockProtocols\`: comma-separated protocols the user explicitly wants mocked (for example, \`rest\`)
+
+By default, mock only true third-party downstream services. Keep the service under test, infrastructure, and local first-party services real unless the user explicitly asks to mock them.
+`;
+const localDevTestChangesSteps = [
+    {
+        stepIndex: 0,
+        title: "Install local-dev skill into the repository",
+        description: `The \`skyramp_one_click_tool\` installs the local-dev skill file for the calling agent automatically when this workflow is invoked. Verify the matching file exists before continuing.
+
+File to check/create only if the tool did not already install it:
+- Cursor: \`.cursor/skills/local-dev/SKILL.md\`
+- Claude Code: \`.claude/skills/local-dev/SKILL.md\`
+Agents without repo-local skill support skip skill creation. Also ensure the MCP config has the required env vars set (SKYRAMP_FEATURE_LOCAL_DEV=1).`,
+        conditionalGuidance: `Create the skill file for the calling agent ONLY if it doesn't already exist — never overwrite.
+
+**Skill path for the calling agent only:**
+- Cursor: \`.cursor/skills/local-dev/SKILL.md\`
+- Claude Code: \`.claude/skills/local-dev/SKILL.md\`
+Agents without repo-local skill support should skip skill creation. Write this exact content to the matching Cursor or Claude Code file:
+${LOCAL_DEV_SKILL_CONTENT}
+
+**MCP config env vars** — also ensure the following env vars are set in the Skyramp MCP server config:
+- For Cursor: \`~/.cursor/mcp.json\` → add to the skyramp server's \`env\` block:
+  \`"SKYRAMP_FEATURE_LOCAL_DEV": "1"\`
+- For Claude Code: \`~/.claude/settings.json\` → add to the skyramp server's \`env\` block:
+  \`"SKYRAMP_FEATURE_LOCAL_DEV": "1"\`
+- For VS Code: add to the Skyramp MCP server's VS Code MCP config env block:
+  \`"SKYRAMP_FEATURE_LOCAL_DEV": "1"\`
+
+After updating the config, the user must restart the IDE or reload MCP servers for the change to take effect.
+
+After verifying or creating files, inform the user what was installed.`,
+    },
+    {
+        stepIndex: 1,
+        title: "Ensure Skyramp workspace is initialized",
+        description: "Check whether .skyramp/workspace.yml exists at repositoryPath. If it exists, read it to confirm it has services and dependencies configured. If it does not exist and .git exists, call skyramp_init_scan with workspacePath to discover services, then call skyramp_init_workspace with the scan results to create the workspace file.",
+        toolCall: {
+            toolName: "skyramp_init_scan",
+            description: "Scan repository for services if workspace not initialized",
+            inputs: {
+                workspacePath: { source: "user", paramKey: "repositoryPath" },
+            },
+        },
+        conditionalGuidance: `Only call skyramp_init_scan + skyramp_init_workspace if .skyramp/workspace.yml does NOT exist. If it already exists, skip this step entirely. The workspace.yml is required by the skyramp_local_dev prompt — it reads service URLs, dependencies, runtime config, and network settings from it.
+
+Turn efficiency — after skyramp_init_scan returns its instructions, follow them to build the services array and call skyramp_init_workspace. Do NOT manually explore the codebase, run git diff, or spawn sub-agents to read source files before calling skyramp_init_workspace — the analyze_changes tool in the next step handles diff analysis automatically.`,
+    },
+    {
+        stepIndex: 2,
+        title: "Invoke the skyramp_local_dev prompt",
+        description: "Call the `skyramp_local_dev` MCP prompt to run the full local-dev testing workflow.\n\nPass these parameters:\n- `baseCommit`: the one-click `baseBranch` value (default `main`)\n- `repositoryPath`: absolute path to the repo\n- `servicesToMock`: comma-separated list only when the user explicitly named services to mock\n- `realServices`: comma-separated list only when the user explicitly named services that should receive real traffic\n- `mockProtocols`: comma-separated list only when the user explicitly constrained mocked protocols (for example, `rest`)\n- `sandboxWorkerUrl`: the one-click `proxyUrl` value, only when provided — a Skyramp worker proxy URL (host:port or ingress route) to query for real recorded traffic\n- `proxyKubeconfig` / `proxyNamespace`: only when provided — reach the worker proxy in-cluster via kubectl port-forward instead of a URL\n\nWhen any proxy access is provided, the workflow calls `skyramp_query_proxy_mocks` during dependency discovery to derive mock request/response shapes from real recorded traffic instead of inferring them.\n\nThe one-click tool exposes `baseBranch` because that matches other workflow inputs; the `skyramp_local_dev` prompt argument is named `baseCommit`. Always map `baseBranch` → `baseCommit` when invoking the prompt.\n\nThe workflow generates the highest-value tests regardless of type. For integration scenarios with selected downstream mocks: skyramp_mock_generation → skyramp_integration_test_generation → skyramp_enrich_test_with_mocks. For provider contract scenarios: skyramp_contract_test_generation only; no mocks needed; do not enrich contract tests. Integration enrich is MANDATORY when the selected scenario has downstream mocks — it embeds MOCK_SERVICES into the test file.\n\nFollow the returned prompt instructions EXACTLY — do not skip steps or freelance.",
+        conditionalGuidance: renderFallbackGuidance(),
+    },
+];
+/**
+ * Render the fallback guidance from the canonical localDevPlan.
+ * This ensures the one-click command fallback stays in sync with the plan
+ * without maintaining a separate handwritten copy.
+ */
+function renderFallbackGuidance() {
+    const preamble = `The skyramp_local_dev prompt returns a detailed multi-step workflow. Follow it completely.
+
+If the prompt is NOT available as a callable prompt in this IDE, fall back to calling the individual tools in sequence. Replace <REPOSITORY_PATH> with the actual repository path and <BASE_BRANCH> with the user's one-click \`baseBranch\` value (default "main"). When the plan says \`baseCommit\`, use that same baseBranch value.
+
+Fallback service routing inputs from the one-click invocation:
+<SERVICE_ROUTING>
+  <MOCK_SERVICES><servicesToMock from one-click params, if provided; use all when the user requested mock all></MOCK_SERVICES>
+  <REAL_SERVICES><realServices from one-click params, if provided></REAL_SERVICES>
+  <MOCK_PROTOCOLS><mockProtocols from one-click params, if provided></MOCK_PROTOCOLS>
+</SERVICE_ROUTING>
+
+Three rules apply in fallback mode at all times:
+1. **No hand-written tests or mocks**: do NOT use Write, Edit, or any file-writing tool to create test or mock files manually. ALL test and mock files MUST be produced by Skyramp MCP generation tools (\`skyramp_batch_scenario_test_generation\`, \`skyramp_integration_test_generation\`, \`skyramp_generate_enriched_integration_test\`, \`skyramp_contract_test_generation\`, \`skyramp_mock_generation\`, \`skyramp_batch_mock_generation\`). If a generation tool fails, fix the inputs and retry — do not fall back to writing tests by hand.
+2. **Mock scope**: if the user said "mock all downstream services", "mock all", "mock everything", or "mock all except X", treat all discovered downstream dependencies as selected for mocking (same as passing \`servicesToMock: "all"\`). Do not silently default to the third-party-only policy when the user expressed broad mock intent.
+3. **No pytest fallback**: if \`skyramp_execute_test\` becomes unavailable at any point (tool not found, MCP disconnected, context compaction), stop immediately and ask the user to reconnect the Skyramp MCP server. Do not fall back to \`pytest\`, \`python3\`, or any direct runtime — doing so bypasses mock deployment and produces results that cannot be trusted as Skyramp-validated.
+
+---
+
+`;
+    const ctx = {
+        repositoryPath: "<REPOSITORY_PATH>",
+        baseCommit: "<BASE_BRANCH from one-click baseBranch, default main>",
+        maxRecommendations: 8,
+        maxGenerate: 5,
+        schemaSourceGuidance: "Use any OpenAPI spec found in the repository as the authoritative schema source. If no spec is available, infer request/response shapes from the implementation code.",
+        serviceRoutingBlock: `<SERVICE_ROUTING>
+  <MOCK_SERVICES><servicesToMock from one-click params, if provided; use all when the user requested mock all></MOCK_SERVICES>
+  <REAL_SERVICES><realServices from one-click params, if provided></REAL_SERVICES>
+  <MOCK_PROTOCOLS><mockProtocols from one-click params, if provided></MOCK_PROTOCOLS>
+</SERVICE_ROUTING>`,
+        serviceContext: `<SERVICE_CONTEXT>
+Read <REPOSITORY_PATH>/.skyramp/workspace.yml before classifying dependencies. Use its services, dependencies, runtime, ports, and docker network values as the local service inventory.
+</SERVICE_CONTEXT>`,
+    };
+    const planBody = localDevPlan.render(ctx);
+    const principles = `
+---
+
+## Key Principles
+- ALL output paths absolute inside repo. NEVER /tmp.
+- For **integration tests**: call \`skyramp_enrich_test_with_mocks\` after generating each test that uses selected downstream mocks. Each integration test with mocked dependencies MUST have MOCK_SERVICES embedded for third-party mocks or user-requested mocks.
+- For **provider contract tests**: no mocks needed — test hits the real endpoint directly. Do NOT call \`skyramp_enrich_test_with_mocks\` for contract tests.
+- Prioritize tests that catch real bugs and edge cases; test type is secondary to coverage value.
+- Present results directly to the user (no skyramp_submit_report).
+- **Prefer batch operations**: Use \`skyramp_batch_mock_generation\` over individual mock calls.
+- **Prefer combined tools**: Use \`skyramp_generate_enriched_integration_test\` over separate generate+enrich.
+- **Pre-flight first**: Call \`skyramp_preflight_mock_check\` before mock generation to catch protocol conflicts.
+- **Compact assertions**: Use \`skyramp_enhance_assertions\` with \`autoApply: true\` for shorter instructions.`;
+    return preamble + planBody + principles;
+}
+export const LOCAL_DEV_TEST_CHANGES_COMMAND = {
+    id: "local_dev_test_changes",
+    name: "Local Dev — Test Changes",
+    description: "Bootstrap and run the local-dev testing workflow: install the active agent's IDE skill into the repo, initialize workspace, then invoke skyramp_local_dev to diff local changes, generate mocks and exhaustive tests, execute, and report. First run sets up the repo for future `/local-dev` usage.",
+    intent: {
+        contextIndicators: [
+            "Use when the user wants to test their LOCAL code changes (committed or uncommitted) against a base branch",
+            "Use when the user asks to set up, initialize, or bootstrap Skyramp local-dev testing in their repo",
+            "Use when the user mentions mocking downstream services for local testing",
+            "Use when the user asks to validate a feature branch, generate tests for their diff, or run a local-dev workflow",
+            "First invocation installs the active agent's skill so future runs can use /local-dev directly",
+            "Do NOT use for testing a deployed/remote service — this is for LOCAL changes only",
+            "Do NOT use for a single test type request like 'generate a smoke test' — use the specific generation tool",
+        ],
+        purpose: "Bootstrap local-dev testing: install the active agent's IDE skill into repo, initialize workspace, then delegate to skyramp_local_dev prompt for the full test workflow (diff → mock → generate → execute → report).",
+        workflowSummary: "Install active agent skill → Init workspace → Invoke skyramp_local_dev prompt (which runs: analyze diff → recommend scenarios → generate mocks + tests → verify → deploy SUT + mocks → execute → report)",
+        examples: {
+            use: [
+                "test my local changes against main",
+                "setup skyramp local dev",
+                "initialize local dev testing",
+                "install skyramp skills",
+                "generate tests for my feature branch",
+                "run local-dev workflow",
+                "mock downstream services and test my diff",
+                "validate my changes before pushing",
+                "bootstrap skyramp testing in this repo",
+            ],
+            doNotUse: [
+                "test the products endpoint comprehensively → use test_given_endpoint_comprehensively instead",
+                "generate a smoke test for /api/users → use skyramp_smoke_test_generation directly",
+                "scan the full repo and run tests → use full_repo_scan_recommend_generate_and_execute_top_n_tests",
+                "run my existing tests → use skyramp_execute_test directly",
+            ],
+        },
+    },
+    steps: localDevTestChangesSteps,
+    inputParams: {
+        required: ["repositoryPath"],
+        optional: [
+            "baseBranch",
+            "servicesToMock",
+            "realServices",
+            "mockProtocols",
+            "endpointURL",
+            "token",
+            "proxyUrl",
+            "proxyKubeconfig",
+            "proxyNamespace",
+        ],
+    },
+};

package/build/index.js

@@ -24,24 +24,47 @@ import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerEnhanceAssertionsTool } from "./tools/code-refactor/enhanceAssertionsTool.js";
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
+import { registerBatchMockTool } from "./tools/generate-tests/batchMockGenerationTool.js";
 import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
 import { registerSutSetupResource } from "./resources/sutSetupResource.js";
 import { registerTestbotResource } from "./resources/testbotResource.js";
+import { registerLocalDevPrompt } from "./prompts/local-dev/local-dev-prompts.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
 import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
 import { registerInitScanWorkspaceTool } from "./tools/workspace/initScanWorkspaceTool.js";
 import { registerOneClickTool } from "./tools/one-click/oneClickTool.js";
+import { registerEnrichTestWithMocksTool } from "./tools/enrichTestWithMocksTool.js";
+import { registerPreflightMockCheckTool } from "./tools/preflightMockCheckTool.js";
+import { registerGenerateEnrichedIntegrationTestTool } from "./tools/generateEnrichedIntegrationTestTool.js";
+import { registerLocalDevWorkerComposeTool } from "./tools/localDevWorkerComposeTool.js";
+import { registerQueryProxyMocksTool } from "./tools/queryProxyMocksTool.js";
 import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { registerInitTriggerOnMCPInitialized } from "./utils/initAgent.js";
-import { isTestbotEnabled } from "./utils/featureFlags.js";
+import { isTestbotEnabled, isLocalDevEnabled } from "./utils/featureFlags.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
+// One-click routing instructions — injected into MCP server instructions so agents
+// know to delegate to the one-click tool rather than self-orchestrating.
+// Suppressed in testbot mode where the testbot prompt drives orchestration.
 const oneClickEnabled = process.env.SKYRAMP_FEATURE_ONE_CLICK === "1";
-const oneClickInstructions = oneClickEnabled
-    ? `\n- When the user asks to comprehensively, thoroughly, or deeply test a specific endpoint: MUST call \`skyramp_one_click_tool\` with workflow \`test_given_endpoint_comprehensively\` first. Do NOT self-orchestrate the steps manually.\n- When the user asks to scan the full repo, recommend, generate, and execute top N tests: MUST call \`skyramp_one_click_tool\` with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.`
-    : "";
+const localDevEnabled = isLocalDevEnabled();
+const localDevInstructions = `\n- When the user asks to test local changes, validate a feature branch, mock services and test, or run local-dev: MUST call \`skyramp_one_click_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\` (default "main"). Do NOT self-orchestrate — the one-click tool handles skill installation, workspace init, and prompt invocation.
+- **Proxy / K8s worker**: When the user mentions a Skyramp proxy, K8s worker, kubeconfig, namespace, or provides proxy setup instructions (helm deploy worker, kubectl port-forward, proxy intercepts, seed traffic), do NOT execute those steps manually with bash commands. Instead, pass \`proxyKubeconfig\` and \`proxyNamespace\` (or \`proxyUrl\`) to \`skyramp_one_click_tool\`. The MCP tools handle proxy access internally — \`skyramp_query_proxy_mocks\` runs kubectl port-forward and queries captured traffic automatically. Manual kubectl, helm, or curl commands for proxy setup are unnecessary and waste agent turns.`;
+const fullOneClickInstructions = `\n- When the user asks to comprehensively, thoroughly, or deeply test a specific endpoint: MUST call \`skyramp_one_click_tool\` with workflow \`test_given_endpoint_comprehensively\` first. Do NOT self-orchestrate the steps manually.\n- When the user asks to scan the full repo, recommend, generate, and execute top N tests: MUST call \`skyramp_one_click_tool\` with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.${localDevEnabled ? localDevInstructions : ""}`;
+// Testbot suppresses one-click workflows (it has its own orchestration via testbot prompt),
+// but local-dev routing is always active when the flag is set — they serve different use cases.
+let oneClickInstructions = "";
+if (isTestbotEnabled()) {
+    oneClickInstructions = localDevEnabled ? localDevInstructions : "";
+}
+else if (oneClickEnabled) {
+    oneClickInstructions = fullOneClickInstructions;
+}
+else if (localDevEnabled) {
+    oneClickInstructions = localDevInstructions;
+}
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -121,6 +144,10 @@ if (isTestbotEnabled()) {
     registerSutSetupResource(server);
     logger.info("Testbot SUT setup resource enabled via SKYRAMP_FEATURE_TESTBOT");
 }
+if (isLocalDevEnabled()) {
+    prompts.push(registerLocalDevPrompt);
+    logger.info("Local-dev prompt enabled via SKYRAMP_FEATURE_LOCAL_DEV");
+}
 prompts.forEach((registerPrompt) => registerPrompt(server));
 logger.info("All prompts registered successfully");
 // Register test generation tools
@@ -134,6 +161,7 @@ const testGenerationTools = [
     registerUITestTool,
     registerBatchScenarioTestTool,
     registerMockTool,
+    registerBatchMockTool,
 ];
 testGenerationTools.forEach((registerTool) => registerTool(server));
 // Register modularization and code quality tools
@@ -155,9 +183,14 @@ registerActionsTool(server);
 registerInitScanWorkspaceTool(server);
 registerInitializeWorkspaceTool(server);
 // Register one-click orchestrated workflows
-if (oneClickEnabled) {
+if (oneClickEnabled || localDevEnabled) {
     registerOneClickTool(server);
-    logger.info("One-click tools enabled via SKYRAMP_FEATURE_ONE_CLICK");
+    logger.info("One-click tools enabled", {
+        enabledBy: {
+            SKYRAMP_FEATURE_ONE_CLICK: oneClickEnabled,
+            SKYRAMP_FEATURE_LOCAL_DEV: localDevEnabled,
+        },
+    });
 }
 // Register other Skyramp tools
 const infrastructureTools = [
@@ -167,6 +200,10 @@ const infrastructureTools = [
     registerTraceTool,
     registerTraceStopTool,
 ];
+if (isLocalDevEnabled()) {
+    infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool, registerLocalDevWorkerComposeTool, registerQueryProxyMocksTool);
+    logger.info("Local-dev tools enabled via SKYRAMP_FEATURE_LOCAL_DEV");
+}
 if (isTestbotEnabled()) {
     infrastructureTools.push(registerSubmitReportTool);
     logger.info("Testbot tools enabled via SKYRAMP_FEATURE_TESTBOT");
@@ -195,6 +232,38 @@ process.on("uncaughtException", async (error) => {
     }
     process.exit(1);
 });
+// Handle unhandled promise rejections — without this handler Node.js 15+
+// terminates the process on any unhandled rejection, which drops the MCP
+// connection if e.g. a progress notification write fails on a broken transport.
+process.on("unhandledRejection", async (reason) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    // EPIPE means the client already disconnected — exit cleanly
+    if ("code" in error && error.code === "EPIPE") {
+        process.exit(0);
+    }
+    // gRPC/Docker connectivity errors — log and survive.
+    // These occur when Docker containers/networks are destroyed while the MCP
+    // server has pending gRPC calls to the Skyramp worker. The server should
+    // stay alive so non-Docker tools remain available.
+    const msg = error.message || "";
+    const isDockerDisconnect = /UNAVAILABLE|DEADLINE_EXCEEDED|ECONNREFUSED|ECONNRESET|connection reset|socket hang up|stream removed/i.test(msg);
+    if (isDockerDisconnect) {
+        logger.info("gRPC/Docker connection lost (container or network likely destroyed)", {
+            error: msg,
+        });
+        return;
+    }
+    logger.error("Unhandled promise rejection", {
+        error: error.message,
+        stack: error.stack,
+    });
+    try {
+        await AnalyticsService.pushServerCrashEvent("unhandledRejection", error.message, error.stack);
+    }
+    catch {
+        // Best effort — don't let telemetry failure cascade
+    }
+});
 // Start MCP server
 async function main() {
     const transport = new StdioServerTransport();
@@ -230,6 +299,11 @@ async function main() {
         logger.error("STDIN error, parent likely disconnected", { error: err });
         handleParentDisconnect("stdin error");
     });
+    // Handle stdout errors (EPIPE = client stopped reading, broken pipe)
+    process.stdout.on("error", (err) => {
+        logger.error("STDOUT error, client likely disconnected", { error: err });
+        handleParentDisconnect("stdout error");
+    });
     // Handle process termination signals
     process.on("SIGTERM", () => handleParentDisconnect("SIGTERM"));
     process.on("SIGINT", () => handleParentDisconnect("SIGINT"));

package/build/playwright/traceRecordingPrompt.js

@@ -54,6 +54,8 @@ Call \`browser_assert\` when assertions are needed. Always provide the \`expecte
 - \`type: "text"\` — verify an element contains expected text
 - \`type: "value"\` — verify an input field has an expected value
 
+**Visual / screenshot assertions.** When the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (as opposed to its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline image on every run. Do NOT use \`browser_take_screenshot\` for this: it only captures a throwaway image, is dropped at export (it produces no assertion), and will NOT appear in the generated test. Use \`browser_take_screenshot\` only to view the page yourself while recording — never to record a visual check. \`filename\` is optional: if the instruction names a baseline file (e.g. \`page-001.png\`) pass it as \`filename\`, otherwise omit it and \`browser_visual_snapshot\` auto-generates one per \`snapshotType\` (\`page-NNN.png\` for a page, \`el-NNN.png\` for an element, \`region-NNN.png\` for a region).
+
 ### Tips
 - **Custom dropdowns (Radix, MUI, etc.)**: click the combobox trigger → \`browser_snapshot\` → click the option. Do NOT use \`browser_select_option\` — it only works on native \`<select>\` elements.
 

package/build/prompts/enhance-assertions/sharedAssertionRules.d.ts

@@ -12,4 +12,5 @@ export interface AssertionEnrichmentRule {
     examples: AssertionEnrichmentExample[];
 }
 export declare function renderRule(index: number, rule: AssertionEnrichmentRule): string;
+export declare function renderSharedAssertionRules(): string;
 export declare function getAssertionsPrompt(specificRules: AssertionEnrichmentRule[], scope: string, testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/sharedAssertionRules.js

@@ -122,6 +122,20 @@ expect(getResponseValue(productsPostResponse, "created_at")).toMatch(/^\\d{4}-\\
             },
         ],
     },
+    {
+        title: "Use exact recorded JSON paths",
+        description: "Do not add object-wrapper prefixes or nested paths that are not present in the actual response body. Use the exact JSON path from the recorded response body.",
+        subPoints: [
+            `If the body is flat (\`{"id": "acc_...", "tax_exempt": true}\`), use \`"tax_exempt"\`, not \`"account.tax_exempt"\`.`,
+            "Only use dot notation when the recorded response genuinely nests the field under that key.",
+        ],
+        examples: [
+            {
+                language: "javascript",
+                code: `expect(getResponseValue(accountResponse, "tax_exempt")).toBe(true);`,
+            },
+        ],
+    },
     {
         title: "Computed response fields, derived using dynamic formulas",
         description: "When the response contains a field whose value is derived from a calculation, assert the result using a formula built from prior response values and request inputs, not a hardcoded literal.",
@@ -158,6 +172,9 @@ ${ex.code}
 function renderRules(rules) {
     return rules.map((rule, i) => renderRule(i + 1, rule)).join("\n\n");
 }
+export function renderSharedAssertionRules() {
+    return renderRules(SHARED_RULES);
+}
 export function getAssertionsPrompt(specificRules, scope, testFile, enhanceType) {
     const allRules = [...SHARED_RULES, ...specificRules];
     const ruleChecklistKeys = allRules

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -13,7 +13,7 @@ After scanning the workspace, before calling the skyramp_init_workspace tool, yo
     "framework": "<framework>",
     "testDirectory": "<path>",
     "api": { "schemaPath": "<path-or-url>", "baseUrl": "<url>", "authType": "<type>", "authHeader": "<header>" },
-    "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "dockerNetwork": "<network>" }
+    "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "serverStopCommand": "<docker stop command>", "dockerNetwork": "<network>" }
   }
 ]
 \`\`\`
@@ -68,7 +68,7 @@ API schemas (look inside the service directory and check known framework default
 <runtime_config>
 Inspect the repo root (and subdirectories like .devcontainer/) for shared runtime configuration:
 1. CLAUDE.md or AGENTS.md: if either file exists at the repo root, check it for dev/test/CI setup instructions including how to start services, required environment variables, and runtime configuration.
-2. Docker Compose files: scan for ALL compose files including docker-compose.yml, docker-compose.yaml, docker-compose.*.yml (such as docker-compose.testbot.yml or docker-compose.dev.yml), compose.yml, and compose.*.yaml in the repo root and subdirectories. Distinguish between application compose files and infrastructure-only compose files. Infrastructure compose files contain only supporting services like databases, Redis, Minio, mail servers, or message queues and do NOT run the application itself. Application compose files contain the actual application services that build from the repo source code (look for "build:" directives pointing to the repo, or services that map to discovered application directories). Only use application compose files for determining runtime and serverStartCommand. When a non-default compose file is found, the serverStartCommand must reference it explicitly (such as "docker compose -f docker-compose.testbot.yml up -d <service-name>"). Docker Compose ALWAYS prefixes the network name with the project name. If compose has "networks: { my-net: ... }", the actual network name is "<project-name>_my-net". If there is no explicit networks section, the default network is "<project-name>_default". The project name is the basename of the working directory where docker compose runs.
+2. Docker Compose files: scan for ALL compose files including docker-compose.yml, docker-compose.yaml, docker-compose.*.yml (such as docker-compose.testbot.yml or docker-compose.dev.yml), compose.yml, and compose.*.yaml in the repo root and subdirectories. Distinguish between application compose files and infrastructure-only compose files. Infrastructure compose files contain only supporting services like databases, Redis, Minio, mail servers, or message queues and do NOT run the application itself. Application compose files contain the actual application services that build from the repo source code (look for "build:" directives pointing to the repo, or services that map to discovered application directories). Only use application compose files for determining runtime, serverStartCommand, and serverStopCommand. When a non-default compose file is found, the serverStartCommand and serverStopCommand must reference it explicitly (such as "docker compose -f docker-compose.testbot.yml up -d --build <service-name>" and "docker compose -f docker-compose.testbot.yml stop <service-name>"). Docker Compose ALWAYS prefixes the network name with the project name. If compose has "networks: { my-net: ... }", the actual network name is "<project-name>_my-net". If there is no explicit networks section, the default network is "<project-name>_default". The project name is the basename of the working directory where docker compose runs.
 3. Makefile: extract start and dev targets.
 4. Root package.json scripts: extract workspace-level commands.
 </runtime_config>
@@ -135,18 +135,20 @@ Create one service entry per deployable unit. You MUST include every backend/API
 <runtime_fields>
 1. runtimeDetails.runtime (required): One of local, docker, or k8s. Detect per service:
    - If the service is listed in an application docker compose file (one that builds or runs the application, not infrastructure-only files containing only databases, caches, or queues) or has a Dockerfile as its intended run method, use "docker".
-   - If k8s manifests exist (charts/, k8s/, deploy/), use "k8s".
+   - If k8s manifests exist (charts/, k8s/, deploy/) AND the service is intended to run in K8s for local development, use "k8s".
    - If the service has no Docker or k8s configuration and is run directly via a language runtime (npm, python, java, etc.), use "local".
    A repo may have MIXED runtimes. A backend in docker-compose.yml uses "docker" while a frontend run with pnpm or npm locally uses "local". Include ALL services regardless of runtime.
    If the frontend is bundled inside the API Docker container (no separate frontend service in the compose file), both frontend and backend services should use runtime "docker", share the same baseUrl (the container's exposed URL), and use the same serverStartCommand since they run in the same container.
+   IMPORTANT — proxy parameters are NOT runtime indicators: If proxyKubeconfig, proxyNamespace, or proxyUrl appear in the conversation context, they are for a Skyramp proxy worker that collects traffic samples for mock generation. They do NOT indicate the repo's runtime. Do not use proxy K8s params to set runtime, k8sNamespace, or k8sContext. Determine the runtime solely from the repo's own files (docker-compose.yml, Dockerfile, k8s manifests that are part of the repo's own local dev workflow). Note that many repos have K8s deployment manifests for staging/production but use Docker Compose for local development — check which setup the repo actually uses for local dev.
 2. runtimeDetails.serverStartCommand: The command to start or deploy the service. It MUST match the runtime:
-   - For "docker" runtime: Use a Docker command such as "docker compose up -d <service-name>" for the default docker-compose.yml, or "docker compose -f <compose-file> up -d <service-name>" when using a non-default compose file. This is always derivable from the application docker compose file and service name.
+   - For "docker" runtime: Use a Docker command that rebuilds application services from the working tree before starting them, such as "docker compose up -d --build <service-name>" for the default docker-compose.yml, or "docker compose -f <compose-file> up -d --build <service-name>" when using a non-default compose file. This is always derivable from the application docker compose file and service name. If the compose service has no build context and only references an image, note that the command cannot rebuild local code.
    - For "k8s" runtime: Use a deploy command such as "kubectl apply -f deploy/", "helm install myrelease .", or "skaffold run". This is always derivable from the manifests or charts present in the repo.
    - For "local" runtime: Use an application command such as "uvicorn main:app", "npm run dev", or "java -jar app.jar". Derive from Makefile, package.json scripts, or README. If no start command is discoverable, omit this field entirely.
    NEVER mix runtime types with incompatible commands (for example, using "uvicorn" with runtime "docker" will cause errors). For "local" runtime, NEVER fabricate a command. Only use commands found in Makefile, package.json scripts, or README.
-3. runtimeDetails.dockerNetwork: Docker network name. ONLY set when runtime is "docker". NEVER set for "local" or "k8s".
-4. runtimeDetails.k8sNamespace: Kubernetes namespace. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
-5. runtimeDetails.k8sContext: Kubernetes context. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
+3. runtimeDetails.serverStopCommand: Optional command to stop the service after test execution. ONLY set when runtime is "docker" and serverStartCommand starts persistent Docker infrastructure. For docker compose starts, prefer matching stop/down commands from the same compose file. Omit this field for "local" and "k8s" runtimes, or when teardown is unsafe or not discoverable.
+4. runtimeDetails.dockerNetwork: Docker network name. ONLY set when runtime is "docker". NEVER set for "local" or "k8s".
+5. runtimeDetails.k8sNamespace: Kubernetes namespace. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
+6. runtimeDetails.k8sContext: Kubernetes context. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
 </runtime_fields>
 
 ### Verification
@@ -159,8 +161,8 @@ Before calling skyramp_init_workspace, confirm all of the following:
 5. Every service with authType apiKey has authHeader explicitly set to the actual custom header name (such as "X-API-Key" or "X-Admin-Key"). If you cannot find the header name in the source code, env vars, or README, do NOT use authType apiKey. Use authType none instead and add a YAML comment explaining auth is unresolved.
 6. framework matches language (python uses pytest or robot, typescript or javascript uses playwright, java uses junit).
 7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services).
-8. If serverStartCommand is provided, it matches the runtime.
-9. For services in docker-compose.yml: runtime MUST be "docker" and the command MUST be a docker command such as "docker compose up -d <service-name>". Always include it since it is derivable from the service name.
+8. If serverStartCommand is provided, it matches the runtime. If serverStopCommand is provided, runtime is "docker" and the command is a Docker command.
+9. For services in docker-compose.yml: runtime MUST be "docker" and the command MUST be a docker command such as "docker compose up -d --build <service-name>" when the service has a build context. Always include it since it is derivable from the service name.
 10. NEVER use application-level commands (uvicorn, npm, node, python, java, etc.) with runtime "docker".
 11. For "local" runtime: if no start command is discoverable from Makefile, package.json scripts, or README, omit serverStartCommand rather than guessing.
 12. dockerNetwork is set only when runtime is "docker".