@skyramp/mcp 0.2.8 → 0.2.150-rc.ldw-

package/build/commands/commandLibrary.d.ts

@@ -10,3 +10,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,30 +1,32 @@
+import { isLocalDevEnabled } 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 = { ...BASE_COMMAND_LIBRARY };
+    if (isLocalDevEnabled()) {
+        commands.local_dev_test_changes = LOCAL_DEV_TEST_CHANGES_COMMAND;
+    }
+    return commands;
+}
 export function getCommand(id) {
-    const cmd = COMMAND_LIBRARY[id];
+    const cmd = getCommandLibrary()[id];
     if (!cmd) {
         throw new Error(`Unknown one-click command: ${id}`);
     }
     return cmd;
 }
 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
@@ -32,7 +34,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}.`);
@@ -42,3 +44,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/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,188 @@
+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 automatically enables contract consumer mode too).`,
+        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"\`
+
+Setting SKYRAMP_FEATURE_LOCAL_DEV=1 automatically enables consumer contract tests (no separate flag needed). 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.",
+    },
+    {
+        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\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 contract scenarios: skyramp_contract_test_generation only; 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>
+
+Two rules apply in fallback mode at all times:
+1. **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.
+2. **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 **contract tests**: mocks are wired inline by the generation tool — do NOT call \`skyramp_enrich_test_with_mocks\` for contract tests. Consumer contract tests already include \`client.apply_mock(mock)\` in the generated test function.
+- 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"],
+    },
+};

package/build/index.js

@@ -24,24 +24,41 @@ 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 { 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.`;
+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.
+const oneClickInstructions = isTestbotEnabled()
+    ? (localDevEnabled ? localDevInstructions : "")
+    : oneClickEnabled
+        ? fullOneClickInstructions
+        : localDevEnabled
+            ? localDevInstructions
+            : "";
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -59,13 +76,6 @@ const server = new McpServer({
     },
     instructions: `Skyramp MCP Server — generates and executes API tests (fuzz, contract, integration, E2E, UI).
 
-## Workspace Initialization (REQUIRED before the first Skyramp tool call)
-If the workspace root is a git repo AND \`.skyramp/workspace.yml\` does not exist:
-1. Call \`skyramp_init_scan\` with \`workspacePath\` → follow the returned instructions to discover all services.
-2. Call \`skyramp_init_workspace\` with \`workspacePath\`, \`services\`, and the \`scanToken\` from step 1.
-3. Proceed with the originally requested tool.
-Skip only if: not a git repo, \`.skyramp/workspace.yml\` already exists, or user explicitly declines.
-  
 ## Rules
 - NEVER show CLI commands. NEVER attempt to install or configure the Skyramp CLI. ALWAYS use the MCP tools provided.
 - For UI and E2E tests, there are TWO recording modes:
@@ -128,6 +138,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
@@ -141,6 +155,7 @@ const testGenerationTools = [
     registerUITestTool,
     registerBatchScenarioTestTool,
     registerMockTool,
+    registerBatchMockTool,
 ];
 testGenerationTools.forEach((registerTool) => registerTool(server));
 // Register modularization and code quality tools
@@ -162,9 +177,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 = [
@@ -174,6 +194,10 @@ const infrastructureTools = [
     registerTraceTool,
     registerTraceStopTool,
 ];
+if (isLocalDevEnabled()) {
+    infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool);
+    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");
@@ -202,6 +226,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();
@@ -237,6 +293,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/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 <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>
@@ -143,9 +143,10 @@ Create one service entry per deployable unit. You MUST include every backend/API
    - 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
@@ -158,7 +159,7 @@ 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.
+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 <service-name>". 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.

package/build/prompts/local-dev/local-dev-plan.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PromptPlan-based local-dev workflow — 6 phases.
+ *
+ * Phases: ANALYZE → RECOMMEND → GENERATE → VERIFY → DEPLOY → EXECUTE
+ *
+ * Key design decisions:
+ * - Mock files are generated in the same language as tests (from workspace config) with get_all_mocks()
+ * - Tests import get_all_mocks from each mock file, collect into MOCK_SERVICES, deploy collectively
+ * - NO YAML mock files, NO CLI commands — ONLY MCP tools
+ * - Execution uses skyramp_execute_test MCP tool exclusively
+ * - The executor handles mock deployment from the test file automatically
+ */
+import { PromptPlan } from "../test-recommendation/promptPlan.js";
+export interface LocalDevPlanCtx {
+    repositoryPath: string;
+    baseCommit: string;
+    maxRecommendations: number;
+    maxGenerate: number;
+    stateOutputFile?: string;
+    sandboxWorkerUrl?: string;
+    schemaSourceGuidance: string;
+    serviceRoutingBlock: string;
+    serviceContext: string;
+}
+export declare const localDevPlan: PromptPlan<LocalDevPlanCtx>;