@skyramp/mcp 0.0.63-rc.6 → 0.0.63-rc.7

package/build/index.js

@@ -23,6 +23,7 @@ import { registerRecommendTestsPrompt } from "./prompts/test-recommendation/regi
 import { registerModularizationTool } from "./tools/code-refactor/modularizationTool.js";
 import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerScenarioTestTool } from "./tools/generate-tests/generateScenarioRestTool.js";
+import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
 import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerExecuteTestsTool, registerActionsTool, registerStateCleanupTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt, registerTestbotResource, } from "./prompts/testbot/testbot-prompts.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
@@ -177,6 +178,7 @@ const testGenerationTools = [
     registerE2ETestTool,
     registerUITestTool,
     registerScenarioTestTool,
+    registerMockTool,
 ];
 testGenerationTools.forEach((registerTool) => registerTool(server));
 // Register modularization and code quality tools

package/build/prompts/test-recommendation/recommendationSections.js

@@ -20,13 +20,9 @@ export function getAuthSnippets(authHeaderValue) {
     }
     return { authSchemeSnippet: "", authTokenSnippet: "" };
 }
-export const PATH_PARAM_UUID_GUIDANCE = `**Path parameters in contract/fuzz tests:** for endpoints with path params (e.g. \`/coupons/{coupon_id}\`), ` +
-    `keep the placeholder in \`endpointURL\` — do NOT substitute it. ` +
-    `Pass the concrete value separately via \`pathParams\` (e.g. \`coupon_id=3fa85f64-5717-4562-b3fc-2c963f66afa6\`). ` +
-    `This lets the CLI derive a clean filename from the resource name (\`coupons_GET_...\`) instead of the UUID. ` +
-    `Prefer example values from the OpenAPI schema (\`example\`, \`x-example\`, or enum values). ` +
-    `If no example exists, use a realistic UUID with varied hex digits such as \`3fa85f64-5717-4562-b3fc-2c963f66afa6\`. ` +
-    `Never use all-same-digit patterns like \`00000000-0000-0000-0000-000000000000\` or \`22222222-2222-2222-2222-222222222222\` — these look like placeholders and are rarely valid resource IDs.`;
+export const PATH_PARAM_UUID_GUIDANCE = `**Path parameters:** keep the placeholder in \`endpointURL\` (e.g. \`/coupons/{coupon_id}\`). ` +
+    `Pass the value via \`pathParams\` (e.g. \`coupon_id=<random-uuid-v4>\`). ` +
+    `Use example values from the OpenAPI schema if available; otherwise generate a fresh random UUID v4 — not all-zeros or repeated-digit patterns.`;
 export function buildPrioritizationDimensions() {
     return `## Prioritization Dimensions (evaluate each candidate test)
 

package/build/prompts/test-recommendation/test-recommendation-prompt.test.js

@@ -2,7 +2,7 @@ jest.mock("@skyramp/skyramp", () => ({
     WorkspaceConfigManager: { create: jest.fn() },
 }));
 import { buildRecommendationPrompt } from "./test-recommendation-prompt.js";
-import { buildCoverageChecklist, MAX_CRITICAL_TESTS, MAX_TESTS_TO_GENERATE } from "./recommendationSections.js";
+import { buildCoverageChecklist, PATH_PARAM_UUID_GUIDANCE, MAX_CRITICAL_TESTS, MAX_TESTS_TO_GENERATE } from "./recommendationSections.js";
 // ---------------------------------------------------------------------------
 // Minimal fixtures
 // ---------------------------------------------------------------------------
@@ -287,3 +287,42 @@ describe("buildCoverageChecklist — Recommendation Stability section", () => {
         expect(checklist).toContain(`up to ${Math.min(MAX_CRITICAL_TESTS, MAX_TESTS_TO_GENERATE)} of the ${MAX_TESTS_TO_GENERATE} generated tests MUST be from critical categories`);
     });
 });
+// ---------------------------------------------------------------------------
+// Tests — PATH_PARAM_UUID_GUIDANCE (no hardcoded UUID anchor)
+// ---------------------------------------------------------------------------
+const UUID_V4_REGEX = /[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/i;
+describe("PATH_PARAM_UUID_GUIDANCE — no hardcoded UUID anchor", () => {
+    it("contains no hardcoded UUID that the LLM could anchor to", () => {
+        expect(PATH_PARAM_UUID_GUIDANCE).not.toMatch(UUID_V4_REGEX);
+    });
+    it("uses <random-uuid-v4> as the placeholder in the pathParams example", () => {
+        expect(PATH_PARAM_UUID_GUIDANCE).toContain("<random-uuid-v4>");
+    });
+    it("instructs the LLM to generate a fresh UUID v4", () => {
+        expect(PATH_PARAM_UUID_GUIDANCE).toContain("generate a fresh random UUID v4");
+    });
+    it("is included in the recommendation prompt for an endpoint with a UUID path param", () => {
+        const analysis = minimalAnalysis({
+            apiEndpoints: {
+                totalCount: 1,
+                baseUrl: "http://localhost:3000",
+                endpoints: [{
+                        path: "/api/items/{item_id}",
+                        resourceGroup: "items",
+                        pathParams: [{ name: "item_id", type: "string", required: true }],
+                        methods: [{
+                                method: "GET",
+                                description: "Get item by ID",
+                                queryParams: [],
+                                authRequired: false,
+                                sourceFile: "routes/items.ts",
+                                interactions: [{ description: "success", type: "success", request: {}, response: { statusCode: 200, description: "OK" } }],
+                            }],
+                    }],
+            },
+        });
+        const prompt = buildRecommendationPrompt(analysis, "current_branch_diff", 10);
+        expect(prompt).toContain("<random-uuid-v4>");
+        expect(prompt).not.toMatch(UUID_V4_REGEX);
+    });
+});

package/build/services/TestGenerationService.js

@@ -277,6 +277,7 @@ ${result}`;
             generateInsecure: params.insecure,
             entrypoint: getEntryPoint(),
             chainingKey: params.chainingKey,
+            mockPort: params.mockPort ?? 0,
         };
     }
 }

package/build/tools/generate-tests/generateContractRestTool.js

@@ -4,6 +4,13 @@ import { TestGenerationService, } from "../../services/TestGenerationService.js"
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const contractTestSchema = {
     ...baseTestSchema,
+    pathParams: z
+        .string()
+        .default("")
+        .describe("Comma-separated path parameter values in the form 'key=value,key2=value2' (e.g., 'id=1,name=John'). " +
+        "IMPORTANT: If the user-provided URL contains path parameter placeholders (e.g., '/products/{product_id}'), do NOT fill in values for them here — pass the URL as-is and leave pathParams empty. " +
+        "The backend resolves path parameters automatically via the parent provisioning mechanism (parentRequestData). " +
+        "Only populate this field if the user has explicitly stated specific path parameter values to use."),
     assertOptions: z
         .string()
         .optional()
@@ -57,6 +64,63 @@ export class ContractTestService extends TestGenerationService {
     getTestType() {
         return TestType.CONTRACT;
     }
+    async generateTest(params) {
+        const result = await super.generateTest(params);
+        if (result.isError)
+            return result;
+        const postInstructions = this.buildSampleDataInstructions(params);
+        if (!postInstructions)
+            return result;
+        return {
+            ...result,
+            content: [
+                ...result.content,
+                { type: "text", text: postInstructions },
+            ],
+        };
+    }
+    buildSampleDataInstructions(params) {
+        const sections = [];
+        sections.push("- **Request body sample data**: the inline JSON/dict literal passed as the request body in the test function.");
+        if (!params.skipProvisionParents) {
+            sections.push("- **Parent provisioning request data**: the inline JSON/dict literals passed as request bodies inside setup/teardown functions that create parent resources.");
+        }
+        return `
+⏭️ **CRITICAL NEXT STEP — Replace unrealistic placeholder values in sample data only:**
+
+Inspect the following locations in the generated file and replace any placeholder values with realistic ones:
+
+${sections.join("\n")}
+
+**A value is a placeholder if it is any of the following — regardless of where it came from:**
+- A JSON/OpenAPI type name: "string", "integer", "number", "boolean", "object", "array"
+- A format descriptor: "uuid", "date", "date-time", "email", "uri", "url", "binary", "byte", "password"
+- A generic filler: "example", "sample", "test", "foo", "bar", "baz", "value", "unknown", "none", "null", "N/A"
+- An integer that is exactly 0 or 1 with no semantic meaning from the field name
+- Any value that is clearly a type name or format name rather than a real datum
+
+**How to replace:**
+- Use the field name, OpenAPI schema descriptions/enums, and repository context to infer a realistic value.
+- Examples: an "email" field → "user@example.com"; a "price" field → 29.99; a "status" field → the first valid enum value from the spec; a "uuid" value for an "id" field → "a1b2c3d4-e5f6-7890-abcd-ef1234567890".
+
+**Exactly what to do:**
+1. Open the generated file.
+2. Find only the inline JSON/dict literals identified above.
+3. Replace every placeholder value using the rules above.
+4. Leave all realistic values unchanged.
+5. Write the updated file. Stop there.
+
+**What NOT to do — any of these is a violation:**
+- Do NOT change function signatures, method names, class names, imports, or variable names.
+- Do NOT add, remove, or reorder any functions, classes, or test cases.
+- Do NOT change assertion logic, HTTP methods, URLs, headers, or status code checks.
+- Do NOT reformat, reorder, or rewrite any code outside the identified JSON/dict literals.
+- Do NOT add comments or docstrings.
+- Do NOT extract, hoist, or expose any request body or data as a global variable, module-level constant, or shared fixture — keep all data inline exactly where it already is.
+- Do NOT reference or reuse request body data across functions for comparison or any other purpose.
+- Do NOT make any other "improvements" beyond the value replacements described above.
+`;
+    }
     validateInputs(params) {
         const errList = super.validateInputs(params);
         if (errList.isError)
@@ -115,10 +179,12 @@ Contract tests ensure your API implementation matches its OpenAPI/Swagger specif
 
 **IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. These files can be very large. Simply pass the path/URL to the tool - the backend will handle reading and processing the schema file.**
 
+**IMPORTANT: If the endpoint URL contains path parameter placeholders (e.g., \`/products/{product_id}/reviews\`), pass the URL exactly as provided — do NOT substitute values for the placeholders. Leave \`pathParams\` empty unless the user has explicitly provided specific values.**
+
 **Modes:**
-- Default (no mode set): generates a standard contract test against the API.
-- \`providerMode\`: generates a provider-side contract test that validates the API implementation against the contract. Optionally specify \`providerOutput\` for the output file path.
-- \`consumerMode\`: generates a consumer-side contract test that validates consumer expectations against the API. Optionally specify \`consumerOutput\` for the output file path.
+- Default (no mode set): both \`providerMode\` and \`consumerMode\` default to false. Do NOT set either unless the user explicitly mentions "provider" or "consumer".
+- \`providerMode\`: set to true ONLY if the user explicitly requests a provider-side contract test. Optionally specify \`providerOutput\` for the output file path.
+- \`consumerMode\`: set to true ONLY if the user explicitly requests a consumer-side contract test. Optionally specify \`consumerOutput\` for the output file path.
 - Both \`providerMode\` and \`consumerMode\` can be enabled simultaneously to generate both sides.
 
 **Chaining (requires \`apiSchema\`):**

package/build/tools/generate-tests/generateMockRestTool.js

@@ -0,0 +1,202 @@
+import { z } from "zod";
+import { baseSchema, TestType } from "../../types/TestTypes.js";
+import { TestGenerationService } from "../../services/TestGenerationService.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { getEntryPoint } from "../../utils/telemetry.js";
+const mockSchema = {
+    endpointURL: z
+        .string()
+        .describe("The base URL or endpoint URL to generate a mock for. " +
+        "If only a base URL is provided (e.g., https://api.example.com) and an apiSchema is given, mocks will be generated for ALL endpoints and methods in the schema — do NOT append paths to the URL. " +
+        "Only include a specific path (e.g., https://api.example.com/api/v1/products) if the user explicitly requests mocking a single endpoint."),
+    method: z
+        .string()
+        .default("")
+        .describe('HTTP method to mock. DEFAULT: Use empty string ("") to mock ALL available methods from the OpenAPI schema. Only specify a specific method (GET, POST, PUT, DELETE, etc.) if the user explicitly requests mocking a single method.'),
+    apiSchema: z
+        .string()
+        .default("")
+        .describe("MUST be absolute path (/path/to/openapi.json) to the OpenAPI/Swagger schema file or a URL to it. NOTE TO AI ASSISTANTS: Do not read the file — simply pass the path/URL to the tool."),
+    responseData: z
+        .string()
+        .optional()
+        .describe("Sample response body data to use in the mock, provided either as an inline JSON/YAML string or as an absolute file path prefixed with '@' (e.g., @/absolute/path/to/file)."),
+    responseStatusCode: z
+        .string()
+        .default("")
+        .describe("HTTP status code the mock should return (e.g., '200', '201'). DO NOT ASSUME a status code if not provided."),
+    requestData: z
+        .string()
+        .default("")
+        .describe("Sample request body data for request-aware mocks, provided either as an inline JSON/YAML string or as an absolute file path prefixed with '@' (e.g., @/absolute/path/to/file)."),
+    formParams: z
+        .string()
+        .default("")
+        .describe("Comma-separated form parameters in the form 'key=value,key2=value2' for mocking form-encoded endpoints."),
+    requestAware: z
+        .boolean()
+        .default(false)
+        .describe("When true, generates a dynamic mock that varies its response based on the incoming request data."),
+    trace: z
+        .string()
+        .optional()
+        .describe("MUST be absolute path to a trace file (e.g., /path/to/trace.json) to generate the mock from captured traffic."),
+    ...(({ authHeader, insecure, ...rest }) => rest)(baseSchema.shape),
+};
+export class MockGenerationService extends TestGenerationService {
+    getTestType() {
+        return TestType.MOCK;
+    }
+    async generateTest(params) {
+        const result = await super.generateTest(params);
+        if (result.isError)
+            return result;
+        if (!params.apiSchema)
+            return result;
+        return {
+            ...result,
+            content: [
+                ...result.content,
+                { type: "text", text: this.buildReorganizationInstructions(params) },
+            ],
+        };
+    }
+    buildReorganizationInstructions(params) {
+        const language = params.language ?? "python";
+        const isTypeScript = language === "typescript" || language === "javascript";
+        const ext = isTypeScript ? (language === "typescript" ? "ts" : "js") : "py";
+        const indexFile = isTypeScript ? `index.${ext}` : `__init__.${ext}`;
+        const importStyle = isTypeScript
+            ? "ES module imports (`import { ... } from './path'`)"
+            : "Python imports (`from mocks.path import ...`)";
+        return `
+⏭️ **CRITICAL NEXT STEP — Reorganize generated mock files into a structured directory layout:**
+
+The generated mock file(s) in \`${params.outputDir}\` must be reorganized as follows.
+
+---
+
+**Step 1 — Create the \`mocks/\` directory structure**
+
+For each endpoint path in the spec, derive its location using these rules:
+1. Strip the leading \`/\` and split the path by \`/\`.
+2. Remove all path parameter segments (anything matching \`{...}\`, e.g. \`{id}\`).
+3. Take at most the first 3 non-parameter segments. The last segment becomes the **filename** (with \`.${ext}\` extension); any preceding segments become **directories**.
+4. Group all HTTP methods that share the same effective file location into a single file.
+
+Examples (assuming \`.${ext}\` files):
+- \`/products\` → \`mocks/products.${ext}\`
+- \`/products/{id}\` → \`mocks/products.${ext}\` (same file as above — same resource)
+- \`/products/{id}/reviews\` → \`mocks/products/reviews.${ext}\`
+- \`/products/{id}/reviews/{review_id}\` → \`mocks/products/reviews.${ext}\` (same file as above)
+- \`/a/b/c/d/e\` → \`mocks/a/b/c.${ext}\` (truncated at 3 non-parameter segments)
+
+---
+
+**Step 2 — Write each mock file**
+
+Each file must:
+- Contain the mock definitions for all HTTP methods that map to it.
+- Be **independently importable** — include all necessary imports at the top of the file so it can be used standalone without the index file.
+- Export a function (e.g., \`apply_products_mock\` / \`applyProductsMock\`) that registers/applies all mocks in that file.
+
+---
+
+**Step 3 — Write the top-level index file at \`mocks/${indexFile}\`**
+
+This file must:
+- Import from every mock file created in Step 2 using ${importStyle}.
+- Export (or define) a single function (e.g., \`apply_all_mocks\` / \`applyAllMocks\`) that calls each individual apply function, so all mocks can be registered in one call.
+- Re-export each individual apply function so consumers can also import them directly from the index.
+
+---
+
+**Step 4 — Delete the original generated file(s)** from \`${params.outputDir}\` that were replaced by the structured layout (keep only the \`mocks/\` directory).
+
+---
+
+**What NOT to do:**
+- Do NOT nest directories more than 3 levels deep inside \`mocks/\`.
+- Do NOT create a separate file per HTTP method — group all methods for the same effective path in one file.
+- Do NOT introduce circular imports between mock files.
+- Do NOT modify any mock logic, response data, or function signatures — only reorganize and add import/export wiring.
+`;
+    }
+    buildGenerationOptions(params) {
+        return {
+            uri: params.endpointURL,
+            method: params.method,
+            apiSchema: params.apiSchema ? [params.apiSchema] : [],
+            language: params.language ?? "python",
+            framework: params.framework ?? "",
+            output: params.output,
+            outputDir: params.outputDir,
+            force: params.force ?? true,
+            deployDashboard: params.deployDashboard,
+            runtime: params.runtime,
+            dockerNetwork: params.dockerNetwork,
+            dockerWorkerPort: params.dockerWorkerPort?.toString() ?? "0",
+            k8sNamespace: params.k8sNamespace,
+            k8sConfig: params.k8sConfig,
+            k8sContext: params.k8sContext,
+            requestData: params.requestData,
+            responseData: params.responseData,
+            responseStatusCode: params.responseStatusCode,
+            formParams: params.formParams,
+            requestAware: params.requestAware,
+            traceFilePath: params.trace,
+            entrypoint: getEntryPoint(),
+            mockPort: params.mockPort ?? 0,
+        };
+    }
+    async executeGeneration(generateOptions) {
+        try {
+            const result = await this.client.generateRestMock(generateOptions);
+            if (result && result.length > 0) {
+                const lowerResult = result.toLowerCase();
+                if (!lowerResult.includes("success")) {
+                    throw new Error(`Mock generation failed: ${result}`);
+                }
+            }
+            return `
+**Generated Mock Details:**
+- Output Directory: ${generateOptions.outputDir}
+- Language: ${generateOptions.language}
+- Framework: ${generateOptions.framework}
+
+${result}`;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to execute mock generation: ${errorMessage}`);
+        }
+    }
+}
+const TOOL_NAME = "skyramp_mock_generation";
+export function registerMockTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Generate a mock server implementation using Skyramp's deterministic mock generation platform.
+
+Mocks simulate API endpoints so that consumers can develop and test against them without requiring a live backend. They are useful for parallel development, isolating dependencies, and simulating edge-case responses.
+
+**IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. Simply pass the path/URL to the tool — the backend will handle reading and processing the schema file.**
+
+**IMPORTANT: When an apiSchema is provided and the user has not requested a specific endpoint, pass only the base URL (e.g., \`https://api.example.com\`) — do NOT append any path. The backend will generate mocks for all endpoints and methods defined in the schema.**
+
+**Request-aware mocks:**
+- \`requestAware: true\` generates a dynamic mock that inspects the incoming request and varies its response accordingly. Use this when the consumer sends different request bodies and expects different responses.
+
+**Sources (in order of preference):**
+1. Trace file (\`trace\`): generates the mock from captured real traffic.
+2. OpenAPI schema (\`apiSchema\`): generates the mock from the spec.
+3. Inline response data (\`responseData\`): generates a static mock with a fixed response.`,
+        inputSchema: mockSchema,
+    }, async (params) => {
+        const service = new MockGenerationService();
+        const result = await service.generateTest(params);
+        AnalyticsService.pushTestGenerationToolEvent(TOOL_NAME, result, params).catch(() => {
+            // Silently ignore analytics errors
+        });
+        return result;
+    });
+}

package/build/types/TestRecommendation.js

@@ -9,6 +9,7 @@ export const TEST_TYPE_DOCS = {
     [TestType.LOAD]: "https://www.skyramp.dev/docs/load-tests",
     [TestType.E2E]: "https://www.skyramp.dev/docs/e2e-tests",
     [TestType.UI]: "https://www.skyramp.dev/docs/ui-tests",
+    [TestType.MOCK]: "https://www.skyramp.dev/docs/mocks",
 };
 // Zod schemas for validation
 export const specificTestSchema = z.object({

package/build/types/TestTypes.js

@@ -10,6 +10,7 @@ export var TestType;
     TestType["INTEGRATION"] = "integration";
     TestType["E2E"] = "e2e";
     TestType["UI"] = "ui";
+    TestType["MOCK"] = "mock";
 })(TestType || (TestType = {}));
 export const languageSchema = z.object({
     language: z
@@ -96,6 +97,10 @@ export const baseSchema = z.object({
         .boolean()
         .default(true)
         .describe("Whether to overwrite existing files in the output directory"),
+    mockPort: z
+        .number()
+        .default(0)
+        .describe("Port number for the mock server"),
     prompt: z.string().describe("The prompt user provided to generate the test"),
 });
 export const basePlaywrightSchema = z.object({
@@ -154,8 +159,9 @@ export const baseTestSchema = {
         .string()
         .default("")
         .describe("Comma-separated path parameter values in the form 'key=value,key2=value2' (e.g., 'id=1,name=John'). " +
-        "For contract tests where parentRequestData is provided, only include path parameters here that do NOT have a corresponding entry in parentRequestData — " +
-        "the two complement each other: parentRequestData covers path params whose parent resources need to be provisioned, while pathParams supplies static values for any remaining path params."),
+        "DO NOT populate this field unless the user has explicitly provided path parameter values. " +
+        "For contract tests, parent path parameters are automatically handled via the parent provisioning mechanism (parentRequestData) — do NOT invent or guess values for those here. " +
+        "Only supply this field if the user explicitly states specific path parameter values to use."),
     queryParams: z
         .string()
         .default("")

package/build/utils/language-helper.js

@@ -1,5 +1,35 @@
 export function getLanguageSteps(params) {
     const { language, testType } = params;
+    if (testType === "mock") {
+        switch (language) {
+            case "python":
+                return `
+# Install skyramp dependency
+pip3 install skyramp
+
+# Run the mock server
+python3 <mock-file>.py
+`;
+            case "typescript":
+                return `
+# Install dependencies
+npm install @skyramp/skyramp
+
+# Run the mock server
+npx ts-node <mock-file>.ts
+`;
+            case "javascript":
+                return `
+# Install dependencies
+npm install @skyramp/skyramp
+
+# Run the mock server
+node <mock-file>.js
+`;
+            default:
+                return "";
+        }
+    }
     let pythonSteps = "";
     switch (language) {
         case "python":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.0.63-rc.6",
+  "version": "0.0.63-rc.7",
   "main": "build/index.js",
   "type": "module",
   "bin": {