@skyramp/mcp 0.3.1 → 0.3.2-rc.pom-2

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

@@ -1,3 +1,4 @@
+import { TOOL_BATCH_SCENARIO_TEST_GENERATION } from "../../toolNames.js";
 import { z } from "zod";
 import path from "path";
 import { ScenarioGenerationService } from "../../services/ScenarioGenerationService.js";
@@ -7,6 +8,10 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getWorkspaceAuthConfig, WorkspaceAuthType, getDefaultAuthHeader, isAuthorizationHeaderName, getAuthScheme } from "../../utils/workspaceAuth.js";
 import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
+import { guardScenarioApproved } from "./planGuard.js";
+import { lintScenarioChaining } from "./scenarioLint.js";
+import { scenarioFileNameFor } from "./scenarioFileIdentity.js";
+import { toolError } from "../../utils/utils.js";
 function isJsonValue(v) {
     if (v === undefined || v === null)
         return true;
@@ -18,6 +23,19 @@ function isJsonValue(v) {
         return false;
     }
 }
+/** Resolve a gjson-style dot path ("name", "nested.id", "items.0.sku") against parsed JSON.
+ *  The Go generator silently skips uniqueFields paths that don't resolve, which would
+ *  quietly disable the SKYR-3882 run-unique protection — so a typo must fail loudly here.
+ *  `seg in cur` covers arrays too (in-bounds numeric indices are own properties). */
+function resolvesInJson(obj, dotPath) {
+    let cur = obj;
+    for (const seg of dotPath.split(".")) {
+        if (cur === null || typeof cur !== "object" || !(seg in cur))
+            return false;
+        cur = cur[seg];
+    }
+    return true;
+}
 function isJsonObject(v) {
     if (v === undefined || v === null)
         return true;
@@ -67,6 +85,7 @@ CRITICAL: For search/filter/list endpoints (e.g., GET /products/search?q=bear&li
     responseBody: z
         .string()
         .optional()
+        .refine(isJsonValue, { message: "responseBody must be valid JSON (e.g. '{\"id\": 1}'). The backend extracts chaining identifiers by parsing it — a malformed body silently disables chaining for every later step." })
         .describe("JSON string of the expected response body. For steps that produce an id used by later steps, include that id field with a realistic UUID generated fresh for this scenario — the backend chains by value-matching any subsequent step path or requestBody that contains the same UUID."),
     statusCode: z
         .number()
@@ -76,26 +95,69 @@ CRITICAL: For search/filter/list endpoints (e.g., GET /products/search?q=bear&li
         .record(z.array(z.string()))
         .optional()
         .describe("Response headers as a JSON object. Defaults to Content-Type: application/json."),
+    uniqueFields: z
+        .array(z.string().min(1, { message: "uniqueFields paths must be non-empty" }))
+        .min(1, { message: "uniqueFields, when provided, must list at least one field path" })
+        .optional()
+        .describe("For POST/PUT create steps: request-body field paths (gjson notation, e.g. \"name\", \"slug\", \"nested.id\") "
+        + "that carry a UNIQUE constraint in the target's data model. The generated test injects a run-unique value "
+        + "for each so re-runs don't fail with HTTP 409 'already exists'. Identify these from the source schema "
+        + "(e.g. Django unique=True, SQL UNIQUE, Pydantic/DTO). Omit for GET/DELETE steps and non-unique fields."),
 }).superRefine((step, ctx) => {
     const isBodyMethod = ["POST", "PUT", "PATCH"].includes(step.method);
-    if (isBodyMethod && step.requestBody) {
-        let parsed;
-        try {
-            parsed = JSON.parse(step.requestBody);
-        }
-        catch {
-            // JSON parse errors are already caught by the isJsonValue refine above
-            return;
+    // Parse once for every body-shape check below; malformed JSON is already
+    // rejected by the isJsonValue refine, so an unparseable body just skips them.
+    let parsedBody;
+    try {
+        parsedBody = step.requestBody ? JSON.parse(step.requestBody) : undefined;
+    }
+    catch {
+        parsedBody = undefined;
+    }
+    // uniqueFields only applies to create-style requests that carry a body — the
+    // run-unique value is injected into a request-body field. Reject it on GET/DELETE
+    // (or a body method with no requestBody) so a misplaced hint fails loudly.
+    if (step.uniqueFields && step.uniqueFields.length > 0) {
+        if (!isBodyMethod) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["uniqueFields"],
+                message: `uniqueFields is only valid on POST/PUT/PATCH steps (got ${step.method} ${step.path}). `
+                    + `Omit it for GET/DELETE steps.`,
+            });
         }
-        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length === 0) {
+        else if (!step.requestBody) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
-                path: ["requestBody"],
-                message: `requestBody for ${step.method} ${step.path} is an empty object {}. `
-                    + `Provide actual field values from the source code schema (Pydantic model, Zod type, DTO) — `
-                    + `do not send an empty body for ${step.method} requests.`,
+                path: ["uniqueFields"],
+                message: `uniqueFields is set for ${step.method} ${step.path} but there is no requestBody `
+                    + `containing those fields.`,
             });
         }
+        else if (parsedBody !== undefined) {
+            for (const fieldPath of step.uniqueFields) {
+                if (!resolvesInJson(parsedBody, fieldPath)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["uniqueFields"],
+                        message: `uniqueFields path "${fieldPath}" does not resolve in the requestBody of `
+                            + `${step.method} ${step.path}. The generator silently skips unresolvable paths, `
+                            + `disabling the run-unique protection — fix the path (gjson dot notation, e.g. `
+                            + `"name", "nested.id", "items.0.sku") to match an existing body field.`,
+                    });
+                }
+            }
+        }
+    }
+    if (isBodyMethod && parsedBody !== null && typeof parsedBody === "object"
+        && !Array.isArray(parsedBody) && Object.keys(parsedBody).length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["requestBody"],
+            message: `requestBody for ${step.method} ${step.path} is an empty object {}. `
+                + `Provide actual field values from the source code schema (Pydantic model, Zod type, DTO) — `
+                + `do not send an empty body for ${step.method} requests.`,
+        });
     }
 });
 const batchScenarioSchema = {
@@ -141,7 +203,7 @@ const batchScenarioSchema = {
         + `${AUTH_PLACEHOLDER_TOKEN} for all auth headers (Authorization, X-API-Key, Cookie, etc.). `
         + `Only provide this when you need a custom value (e.g., 'session=${AUTH_PLACEHOLDER_TOKEN}' for Cookie).`),
 };
-const TOOL_NAME = "skyramp_batch_scenario_test_generation";
+const TOOL_NAME = TOOL_BATCH_SCENARIO_TEST_GENERATION;
 export function registerBatchScenarioTestTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `Generate a synthetic scenario trace file for a multi-step API workflow scenario — use this before skyramp_integration_test_generation.
@@ -167,6 +229,13 @@ If a step fails, the error shows which step (N/total), method+path, and reason.
 Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\` path. Do NOT also pass \`apiSchema\` or \`endpointURL\` — the scenario file already contains all endpoint information and passing both will cause test generation to fail.`,
         inputSchema: batchScenarioSchema,
     }, async (params) => {
+        const guardMessage = await guardScenarioApproved({
+            scenarioName: params.scenarioName,
+            testType: "integration",
+        });
+        if (guardMessage) {
+            return { content: [{ type: "text", text: guardMessage }], isError: true };
+        }
         if (params.authHeader === undefined) {
             try {
                 const repoPath = params.outputDir || process.cwd();
@@ -319,8 +388,7 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
         }
         const service = new ScenarioGenerationService();
         const steps = params.steps;
-        const scenarioSlug = params.scenarioName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "scenario";
-        const fileName = `scenario_${scenarioSlug}.json`;
+        const fileName = scenarioFileNameFor(params.scenarioName);
         const filePath = path.join(params.outputDir, fileName);
         const resolvedOut = path.resolve(params.outputDir);
         if (!path.resolve(filePath).startsWith(resolvedOut + path.sep) && path.resolve(filePath) !== resolvedOut) {
@@ -350,6 +418,7 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                 authHeader: params.authHeader ?? "",
                 authScheme: params.authScheme ?? "",
                 authToken: params.authToken,
+                uniqueFields: step.uniqueFields,
             };
             const traceRequest = service.generateTraceRequestFromInput(stepParams);
             if (!traceRequest) {
@@ -375,6 +444,29 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
             }
             traceRequests.push(traceRequest);
         }
+        // ── SKYR-3884: chaining lint ──
+        // The generated test chains FKs/path params by value-matching against
+        // PRIOR steps' responses; mis-ordered or missing "bait" values silently
+        // degrade to hardcoded literals. Lint the built TraceRequests — the
+        // artifact the Go reader actually consumes (post basePath/default
+        // transforms), not the raw tool input. Ordering mistakes are fixable →
+        // hard error before the file is written; unchainable/ambiguous
+        // references → warning on the success text.
+        const chainLint = lintScenarioChaining(traceRequests.map((t) => ({
+            method: t.Method,
+            path: t.Path,
+            requestBody: t.RequestBody,
+            responseBody: t.ResponseBody,
+        })));
+        if (chainLint.errors.length > 0) {
+            return toolError(`**Scenario step-ordering errors**\n\n`
+                + chainLint.errors.map((e) => `- ${e}`).join("\n")
+                + `\n\nReorder or fix the steps and resubmit the full batch.`);
+        }
+        const chainLintWarning = chainLint.warnings.length > 0
+            ? `\n\n⚠️ **Chaining warnings** — the generated test may hardcode these instead of chaining:\n`
+                + chainLint.warnings.map((w) => `  - ${w}`).join("\n")
+            : "";
         try {
             fs.writeFileSync(filePath, JSON.stringify(traceRequests, null, 2), "utf8");
         }
@@ -395,7 +487,8 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                         + `**Steps:**\n${steps.map((s, i) => `  ${i + 1}. ${s.method} ${s.path} → ${s.statusCode ?? "default"}`).join("\n")}\n\n`
                         + `**File:** ${filePath}\n\n`
                         + `**Next:** Call \`skyramp_integration_test_generation\` with \`scenarioFile: "${filePath}"\``
-                        + specValidationWarning,
+                        + specValidationWarning
+                        + chainLintWarning,
                 },
             ],
             isError: false,

package/build/tools/generate-tests/generateBatchScenarioRestTool.test.js

@@ -284,3 +284,150 @@ describe("generateBatchScenarioRestTool — spec URL fetch safety (comment 32030
         delete global.fetch;
     });
 });
+describe("stepSchema uniqueFields validation (SKYR-3882)", () => {
+    const base = { method: "POST", path: "/api/v1/providers/", requestBody: '{"name":"x"}' };
+    it("accepts uniqueFields on a POST with a body", () => {
+        expect(stepSchema.safeParse({ ...base, uniqueFields: ["name"] }).success).toBe(true);
+    });
+    it("rejects an empty uniqueFields array", () => {
+        expect(stepSchema.safeParse({ ...base, uniqueFields: [] }).success).toBe(false);
+    });
+    it("rejects empty-string paths in uniqueFields", () => {
+        expect(stepSchema.safeParse({ ...base, uniqueFields: [""] }).success).toBe(false);
+    });
+    it("rejects uniqueFields on a non-body method (GET)", () => {
+        expect(stepSchema.safeParse({ method: "GET", path: "/x", uniqueFields: ["name"] }).success).toBe(false);
+    });
+    it("rejects uniqueFields on a POST with no requestBody", () => {
+        expect(stepSchema.safeParse({ method: "POST", path: "/api/v1/providers/", uniqueFields: ["name"] }).success).toBe(false);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// SKYR-3884 write-side validations
+// ─────────────────────────────────────────────────────────────────────────────
+describe("stepSchema — responseBody JSON validation (SKYR-3884)", () => {
+    it("rejects a responseBody that is not valid JSON", () => {
+        const result = stepSchema.safeParse({
+            method: "POST",
+            path: "/api/v1/products",
+            requestBody: JSON.stringify({ name: "W" }),
+            responseBody: "{id: 1, oops",
+        });
+        expect(result.success).toBe(false);
+        const issue = result.error?.issues.find((i) => i.path.includes("responseBody"));
+        expect(issue?.message).toContain("valid JSON");
+    });
+    it("accepts a valid JSON responseBody and an omitted one", () => {
+        expect(stepSchema.safeParse({
+            method: "POST",
+            path: "/api/v1/products",
+            requestBody: JSON.stringify({ name: "W" }),
+            responseBody: JSON.stringify({ id: 1 }),
+        }).success).toBe(true);
+        expect(stepSchema.safeParse({ method: "GET", path: "/api/v1/products" }).success).toBe(true);
+    });
+});
+describe("stepSchema — uniqueFields paths must resolve in requestBody (SKYR-3884)", () => {
+    it("rejects a uniqueFields path that does not resolve in the requestBody", () => {
+        const result = stepSchema.safeParse({
+            method: "POST",
+            path: "/api/v1/products",
+            requestBody: JSON.stringify({ name: "W", slug: "w" }),
+            uniqueFields: ["nmae"],
+        });
+        expect(result.success).toBe(false);
+        const issue = result.error?.issues.find((i) => i.path.includes("uniqueFields"));
+        expect(issue?.message).toContain("nmae");
+    });
+    it("accepts top-level, nested, and array-indexed uniqueFields paths that resolve", () => {
+        const result = stepSchema.safeParse({
+            method: "POST",
+            path: "/api/v1/products",
+            requestBody: JSON.stringify({ name: "W", nested: { slug: "w" }, items: [{ sku: "S1" }] }),
+            uniqueFields: ["name", "nested.slug", "items.0.sku"],
+        });
+        expect(result.success).toBe(true);
+    });
+});
+describe("generateBatchScenarioRestTool — chaining lint (SKYR-3884)", () => {
+    let handler;
+    let writeFileSyncSpy;
+    const baseParams = {
+        scenarioName: "test_scenario",
+        destination: "localhost",
+        outputDir: "/tmp/skyramp-test",
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+        handler = captureHandler();
+        writeFileSyncSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => { });
+        // The lint inspects the BUILT TraceRequests (the artifact the Go reader
+        // consumes), so the mock must pass the step through in TraceRequest shape.
+        ScenarioGenerationService.mockImplementation(() => ({
+            generateTraceRequestFromInput: jest.fn((p) => ({
+                Method: p.method,
+                Path: p.path,
+                RequestBody: p.requestBody ?? "",
+                ResponseBody: p.responseBody ?? "",
+            })),
+        }));
+    });
+    afterEach(() => {
+        writeFileSyncSpy.mockRestore();
+    });
+    it("hard-rejects a scenario whose FK reference is produced only by a later step", async () => {
+        const result = await handler({
+            ...baseParams,
+            steps: [
+                {
+                    method: "POST",
+                    path: "/api/circuits/provider-accounts/",
+                    requestBody: JSON.stringify({ provider: 1, name: "A" }),
+                    responseBody: JSON.stringify({ id: 7 }),
+                },
+                {
+                    method: "POST",
+                    path: "/api/circuits/providers/",
+                    requestBody: JSON.stringify({ name: "P" }),
+                    responseBody: JSON.stringify({ id: 1 }),
+                },
+            ],
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain("later step");
+        expect(writeFileSyncSpy).not.toHaveBeenCalled();
+    });
+    it("appends a chaining warning (does not reject) for unchainable path values", async () => {
+        const result = await handler({
+            ...baseParams,
+            steps: [
+                {
+                    method: "POST",
+                    path: "/api/circuits/providers/",
+                    requestBody: JSON.stringify({ name: "P" }),
+                    responseBody: JSON.stringify({ id: 1 }),
+                },
+                { method: "GET", path: "/api/circuits/providers/999/summary/" },
+            ],
+        });
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text).toContain("Chaining warning");
+        expect(result.content[0].text).toContain("999");
+    });
+    it("emits no chaining output for a well-chained scenario", async () => {
+        const result = await handler({
+            ...baseParams,
+            steps: [
+                {
+                    method: "POST",
+                    path: "/api/circuits/providers/",
+                    requestBody: JSON.stringify({ name: "P" }),
+                    responseBody: JSON.stringify({ id: 1 }),
+                },
+                { method: "GET", path: "/api/circuits/providers/1/summary/" },
+            ],
+        });
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text).not.toContain("Chaining warning");
+    });
+});

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

@@ -1,10 +1,13 @@
 import path from "path";
+import { TOOL_CONTRACT_TEST_GENERATION } from "../../toolNames.js";
 import { z } from "zod";
 import { baseTestSchema, TestType } from "../../types/TestTypes.js";
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getPersonaPrefix } from "../../prompts/personas.js";
 import { isContractConsumerModeEnabled, isTestbotEnabled } from "../../utils/featureFlags.js";
+import { guardScenarioApproved, pathFromEndpointURL } from "./planGuard.js";
+import { toolError } from "../../utils/utils.js";
 // SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE gates BOTH:
 //   1. Consumer-side contract test generation (`consumerMode` /
 //      `consumerOutput` schema fields, validation, post-gen instructions,
@@ -353,7 +356,7 @@ The generated consumer contract test contains a stub test function that uses Sky
         return baseOptions;
     }
 }
-const TOOL_NAME = "skyramp_contract_test_generation";
+const TOOL_NAME = TOOL_CONTRACT_TEST_GENERATION;
 const MODES_SECTION = CONSUMER_MODE_ENABLED
     ? `**Modes:**
 - Default (no mode set): both \`providerMode\` and \`consumerMode\` default to false. This generates both provider and consumer contract tests — equivalent to setting both modes to true.
@@ -413,6 +416,13 @@ ${CHAINING_SECTION}
 `,
         inputSchema: contractTestSchema,
     }, async (params) => {
+        const guardMessage = await guardScenarioApproved({
+            testType: "contract",
+            method: params.method || undefined,
+            path: pathFromEndpointURL(params.endpointURL),
+        });
+        if (guardMessage)
+            return toolError(guardMessage);
         const service = new ContractTestService();
         const result = await service.generateTest(params);
         AnalyticsService.pushTestGenerationToolEvent(TOOL_NAME, result, params).catch(() => {

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

@@ -1,3 +1,4 @@
+import { TOOL_INTEGRATION_TEST_GENERATION } from "../../toolNames.js";
 import { z } from "zod";
 import { baseTestSchema, baseTraceSchema, TestType, codeRefactoringSchema, } from "../../types/TestTypes.js";
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
@@ -5,6 +6,9 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { AUTH_CONFLICT_ERROR_MSG } from "../../prompts/test-recommendation/recommendationSections.js";
 import { getPersonaPrefix } from "../../prompts/personas.js";
 import { isTestbotEnabled } from "../../utils/featureFlags.js";
+import { guardScenarioApproved, pathFromEndpointURL } from "./planGuard.js";
+import { readScenarioNameFromFile } from "./scenarioFileIdentity.js";
+import { toolError } from "../../utils/utils.js";
 const ADD_ASSERTIONS_DEFAULT = isTestbotEnabled();
 const integrationTestSchema = z
     .object({
@@ -76,7 +80,7 @@ Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path o
         return null;
     }
 }
-const TOOL_NAME = "skyramp_integration_test_generation";
+const TOOL_NAME = TOOL_INTEGRATION_TEST_GENERATION;
 export function registerIntegrationTestTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
@@ -122,6 +126,25 @@ Generate an integration test from a scenario file or a live endpoint trace.
                 isError: true,
             };
         }
+        let guardMessage = null;
+        if (params.scenarioFile) {
+            // Guard even when scenarioName can't be derived (fail closed): skipping
+            // the check for an unreadable/malformed scenarioFile would let any such
+            // file bypass the hard gate. With no derivable identity the query can't
+            // match, so an active plan rejects it; standalone usage (no active
+            // run / no plan) is still allowed by guardScenarioApproved itself.
+            const scenarioName = readScenarioNameFromFile(params.scenarioFile);
+            guardMessage = await guardScenarioApproved({ scenarioName, testType: "integration" });
+        }
+        else {
+            guardMessage = await guardScenarioApproved({
+                testType: "integration",
+                method: params.method || undefined,
+                path: pathFromEndpointURL(params.endpointURL),
+            });
+        }
+        if (guardMessage)
+            return toolError(guardMessage);
         const service = new IntegrationTestService();
         const result = await service.generateTest(params);
         AnalyticsService.pushTestGenerationToolEvent(TOOL_NAME, result, params).catch(() => {

package/build/tools/generate-tests/generateIntegrationRestTool.test.d.ts

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

package/build/tools/generate-tests/generateIntegrationRestTool.test.js

@@ -0,0 +1,159 @@
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+// TestGenerationService transitively loads the @skyramp/skyramp native library
+// (blocks 180s waiting for the platform dylib) — stub the base class out.
+jest.unstable_mockModule("../../services/TestGenerationService.js", () => ({
+    TestGenerationService: class {
+        async generateTest() {
+            return { content: [{ type: "text", text: "generated" }] };
+        }
+        buildBaseGenerationOptions() {
+            return {};
+        }
+    },
+}));
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: {
+        pushTestGenerationToolEvent: jest.fn().mockResolvedValue(undefined),
+    },
+}));
+jest.unstable_mockModule("../../utils/logger.js", () => ({
+    logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warning: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+const { registerIntegrationTestTool, IntegrationTestService } = await import("./generateIntegrationRestTool.js");
+const { setActiveRunStatePath, clearActiveRunStatePath } = await import("../../utils/AnalysisStateManager.js");
+const { CandidateSource } = await import("../../types/Recommendation.js");
+/** Build a minimal mock McpServer, register the tool, and return the captured handler. */
+function captureHandler() {
+    let capturedHandler;
+    const mockServer = {
+        registerTool: jest.fn((_name, _meta, handler) => {
+            capturedHandler = handler;
+        }),
+    };
+    registerIntegrationTestTool(mockServer);
+    return capturedHandler;
+}
+const APPROVED_ITEM = {
+    candidateId: "orders-workflow-abcd1234",
+    scenarioName: "orders_workflow",
+    testType: "integration",
+    category: "business_rule",
+    source: CandidateSource.AGENT,
+    matchKeys: ["name:orders-workflow", "ep:integration:POST:/api/v1/orders"],
+};
+async function writeStateFile(dir, approvedPlan) {
+    const stateFile = path.join(dir, "analyze-changes-state.json");
+    await fs.writeFile(stateFile, JSON.stringify({
+        existingTests: [],
+        analysisScope: "current_branch_diff",
+        newEndpoints: [],
+        approvedPlan,
+        metadata: {
+            sessionId: "test-session",
+            stateType: "analysis",
+            createdAt: "2026-01-01T00:00:00.000Z",
+            updatedAt: "2026-01-01T00:00:00.000Z",
+        },
+    }), "utf-8");
+    return stateFile;
+}
+const PLAN = {
+    planId: "plan-int-1",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    generate: [APPROVED_ITEM],
+    additional: [],
+    demotions: [],
+};
+describe("skyramp_integration_test_generation — plan guard on scenarioFile mode", () => {
+    let handler;
+    let generateSpy;
+    let tmpDirs = [];
+    const originalRunnerTemp = process.env.RUNNER_TEMP;
+    beforeEach(() => {
+        handler = captureHandler();
+        generateSpy = jest
+            .spyOn(IntegrationTestService.prototype, "generateTest")
+            .mockResolvedValue({ content: [{ type: "text", text: "generated" }] });
+    });
+    afterEach(async () => {
+        generateSpy.mockRestore();
+        clearActiveRunStatePath();
+        process.env.RUNNER_TEMP = originalRunnerTemp;
+        for (const dir of tmpDirs) {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+        tmpDirs = [];
+    });
+    async function mkTmpDir() {
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), "integration-guard-test-"));
+        tmpDirs.push(dir);
+        return dir;
+    }
+    it("allows a scenarioFile whose scenarioName matches an approved GENERATE item", async () => {
+        const dir = await mkTmpDir();
+        setActiveRunStatePath(await writeStateFile(dir, PLAN));
+        const scenarioFile = path.join(dir, "scenario_orders-workflow.json");
+        await fs.writeFile(scenarioFile, JSON.stringify([{ scenarioName: "orders_workflow", method: "POST" }]), "utf-8");
+        const result = await handler({ scenarioFile });
+        expect(result.isError).toBeUndefined();
+        expect(generateSpy).toHaveBeenCalled();
+    });
+    it("rejects (fail closed) when scenarioFile is unreadable and an approved plan is active — no gate bypass", async () => {
+        const dir = await mkTmpDir();
+        setActiveRunStatePath(await writeStateFile(dir, PLAN));
+        const result = await handler({
+            scenarioFile: path.join(dir, "does-not-exist.json"),
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain("plan-int-1");
+        expect(generateSpy).not.toHaveBeenCalled();
+    });
+    it("rejects (fail closed) when scenarioFile parses but carries no scenarioName and an approved plan is active", async () => {
+        const dir = await mkTmpDir();
+        setActiveRunStatePath(await writeStateFile(dir, PLAN));
+        const scenarioFile = path.join(dir, "scenario_nameless.json");
+        await fs.writeFile(scenarioFile, JSON.stringify([{ method: "POST", path: "/api/v1/orders" }]), "utf-8");
+        const result = await handler({ scenarioFile });
+        expect(result.isError).toBe(true);
+        expect(generateSpy).not.toHaveBeenCalled();
+    });
+    it("still allows an unreadable scenarioFile when there is no active run state (standalone back-compat)", async () => {
+        clearActiveRunStatePath();
+        delete process.env.RUNNER_TEMP;
+        const result = await handler({
+            scenarioFile: "/nonexistent/scenario.json",
+        });
+        expect(result.isError).toBeUndefined();
+        expect(generateSpy).toHaveBeenCalled();
+    });
+    // SKYR-3884 — filename fallback for files with no embedded scenarioName.
+    it("allows a scenario file with no embedded scenarioName when its filename slug matches the plan (files written by MCP <= 0.3.1)", async () => {
+        const dir = await mkTmpDir();
+        setActiveRunStatePath(await writeStateFile(dir, PLAN));
+        // Bare TraceRequest array — exactly what ScenarioGenerationService wrote
+        // before scenarioName embedding. Identity must come from the file name.
+        const scenarioFile = path.join(dir, "scenario_orders-workflow.json");
+        await fs.writeFile(scenarioFile, JSON.stringify([{ Method: "POST", Path: "/api/v1/orders" }]), "utf-8");
+        const result = await handler({ scenarioFile });
+        expect(result.isError).toBeUndefined();
+        expect(generateSpy).toHaveBeenCalled();
+    });
+    it("still rejects when neither embedded name nor filename slug matches the plan", async () => {
+        const dir = await mkTmpDir();
+        setActiveRunStatePath(await writeStateFile(dir, PLAN));
+        const scenarioFile = path.join(dir, "scenario_unrelated-flow.json");
+        await fs.writeFile(scenarioFile, JSON.stringify([{ Method: "POST", Path: "/api/v1/orders" }]), "utf-8");
+        const result = await handler({ scenarioFile });
+        expect(result.isError).toBe(true);
+        expect(generateSpy).not.toHaveBeenCalled();
+    });
+});

package/build/tools/generate-tests/planGuard.d.ts

@@ -0,0 +1,13 @@
+import { PlanMatchQuery } from "../../utils/planMatchKeys.js";
+export type PlanGuardQuery = PlanMatchQuery;
+/** Extract the URL path from a generation tool's `endpointURL` param — used
+ *  for contract/direct-mode integration guard queries. Falls back to treating
+ *  the value as a bare path when it isn't a parseable absolute URL, and to
+ *  undefined (no path-based match attempted) when it's neither. */
+export declare function pathFromEndpointURL(endpointURL: string | undefined): string | undefined;
+/**
+ * Returns null when the generation call is allowed, or a human-readable error
+ * message (for `toolError`) when it must be rejected because it doesn't match
+ * any item in the approved plan's GENERATE list.
+ */
+export declare function guardScenarioApproved(query: PlanGuardQuery): Promise<string | null>;