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

package/build/tools/code-refactor/codeReuseTool.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { logger } from "../../utils/logger.js";
-import { getCodeReusePrompt } from "../../prompts/code-reuse.js";
+import { getCodeReusePrompt, isPomAwareTarget } from "../../prompts/code-reuse.js";
+import { selectScopedPoms } from "../../utils/pom-scope/index.js";
+import { verifyReuse } from "../../utils/pom-verify/index.js";
 import { codeRefactoringSchema, languageSchema, } from "../../types/TestTypes.js";
 import { SKYRAMP_UTILS_HEADER } from "../../utils/utils.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
@@ -14,8 +16,33 @@ const codeReuseSchema = z.object({
     modularizeCode: codeRefactoringSchema.shape.modularizeCode,
     prompt: z
         .string()
+        .default("")
         .describe("The code content to analyze and optimize for code reuse"),
+    verify: z
+        .boolean()
+        .default(false)
+        .describe("Verify a previously written refactored test's POM calls against source instead of returning the reuse prompt"),
 });
+/** Renders a `VerifyResult` (from `verifyReuse`) as the text report returned to the agent. */
+export function formatVerifyReport(r) {
+    if (r.ok) {
+        const lines = [`VERIFICATION PASSED — ${r.checkedCalls} calls checked.`];
+        if (r.unverifiable.length > 0) {
+            lines.push(`Unverifiable (informational): ${r.unverifiable.join(", ")}`);
+        }
+        return lines.join("\n");
+    }
+    const lines = ["VERIFICATION FAILED"];
+    for (const v of r.violations) {
+        const location = v.searched.length > 1 ? `${v.searched[0]} (+1-hop)` : v.searched[0];
+        lines.push(`${v.binding}.${v.member} — not found in ${location}. Available members: ${v.availableMembers.join(", ")}`);
+    }
+    if (r.parseError) {
+        lines.push(`Parse error (fix the syntax and re-verify): ${r.parseError}`);
+    }
+    lines.push("Each violation may be remapped AT MOST ONCE, and only to a member listed above. If it is flagged again, or you are not confident, restore the raw inline sequence (from your mapping table or `<testFile>.raw.bak`) with a `// kept inline: no matching POM method` comment. Re-run this verification after every fix pass. Do not finish until it reports PASSED.");
+    return lines.join("\n\n");
+}
 const TOOL_NAME = "skyramp_reuse_code";
 export function registerCodeReuseTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -51,8 +78,8 @@ export function registerCodeReuseTool(server) {
       **CRITICAL**: NON TRACE BASED TESTS ARE ALREADY MODULARIZED AND DO NOT NEED CODE REUSE.
       The tool will provide step-by-step instructions that MUST be followed exactly.
 
-      **POM-AWARE MODE (TypeScript/Playwright only):**
-      For projects with \`language: "typescript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization.`,
+      **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
+      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization.`,
         inputSchema: codeReuseSchema.shape,
         _meta: {
             keywords: [
@@ -66,6 +93,22 @@ export function registerCodeReuseTool(server) {
     }, async (params) => {
         let errorResult;
         try {
+            if (params.verify) {
+                try {
+                    const r = await verifyReuse(params.testFile, params.language);
+                    return { content: [{ type: "text", text: formatVerifyReport(r) }] };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `VERIFICATION ERROR (treat as unverified, do not retry more than once): ${String(err)}`,
+                            },
+                        ],
+                    };
+                }
+            }
             logger.info("Analyzing code for reuse opportunities", {
                 testFile: params.testFile,
                 language: params.language,
@@ -73,7 +116,36 @@ export function registerCodeReuseTool(server) {
             });
             // Stage so testbot includes the generated files in its output commit.
             await stageGeneratedPaths(params.testFile);
-            const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework);
+            // Deterministic POM pre-scoping (TS/JS+Playwright only). Never blocks:
+            // any error or empty result falls back to the agent-driven STEP 1.
+            let scopedPoms;
+            if (isPomAwareTarget(params.language, params.framework)) {
+                try {
+                    const t0 = Date.now();
+                    const { tier1, tier2, diagnostics } = await selectScopedPoms({
+                        testFile: params.testFile,
+                        specContent: params.prompt,
+                    });
+                    if (tier1.length + tier2.length > 0) {
+                        scopedPoms = { tier1, tier2 };
+                    }
+                    else if (diagnostics.selectors > 0 && diagnostics.discovery !== "skipped-too-large") {
+                        // A clean scan ran (glob or selector-grep) and found zero overlap — distinct from
+                        // "scoping wasn't attempted" (no selectors) or "scan was skipped" (repo too large).
+                        scopedPoms = { tier1: [], tier2: [], scannedNoOverlap: true };
+                    }
+                    logger.info("POM pre-scoping", {
+                        ...diagnostics,
+                        tier1: tier1.length,
+                        tier2: tier2.length,
+                        ms: Date.now() - t0,
+                    });
+                }
+                catch (err) {
+                    logger.warning("POM pre-scoping failed — falling back to agent-driven detection", { error: String(err) });
+                }
+            }
+            const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework, scopedPoms);
             return {
                 content: [
                     {

package/build/tools/code-refactor/codeReuseTool.test.d.ts

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

package/build/tools/code-refactor/codeReuseTool.test.js

@@ -0,0 +1,51 @@
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
+jest.unstable_mockModule("../../utils/logger.js", () => ({
+    logger: { info: jest.fn(), error: jest.fn(), warning: jest.fn(), debug: jest.fn() },
+}));
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: { pushMCPToolEvent: jest.fn().mockResolvedValue(undefined) },
+}));
+jest.unstable_mockModule("../../utils/gitStaging.js", () => ({
+    stageGeneratedPaths: jest.fn().mockResolvedValue(undefined),
+}));
+jest.unstable_mockModule("../../utils/pom-verify/index.js", () => ({
+    verifyReuse: jest.fn().mockResolvedValue({ ok: true, violations: [], unverifiable: [], checkedCalls: 3 }),
+}));
+const { registerCodeReuseTool, formatVerifyReport } = await import("./codeReuseTool.js");
+const { stageGeneratedPaths } = await import("../../utils/gitStaging.js");
+const { verifyReuse } = await import("../../utils/pom-verify/index.js");
+function captureToolHandler() {
+    let handler;
+    registerCodeReuseTool({ registerTool: (_n, _o, fn) => { handler = fn; } });
+    return handler;
+}
+describe("skyramp_reuse_code — verify mode", () => {
+    it("returns the verification report and skips prompt generation/staging when verify:true", async () => {
+        const handler = captureToolHandler();
+        const result = await handler({
+            testFile: "t.spec.ts",
+            language: "typescript",
+            framework: "playwright",
+            modularizeCode: false,
+            prompt: "",
+            verify: true,
+        });
+        expect(result.content[0].text).toBe("VERIFICATION PASSED — 3 calls checked.");
+        expect(verifyReuse).toHaveBeenCalledWith("t.spec.ts", "typescript");
+        expect(stageGeneratedPaths).not.toHaveBeenCalled();
+    });
+});
+describe("formatVerifyReport", () => {
+    it("reports a violation block with the fix-rule paragraph, not the passed message", () => {
+        const text = formatVerifyReport({
+            ok: false,
+            violations: [{ binding: "pm", member: "fakeMethod", searched: ["a.ts", "b.ts"], availableMembers: ["realMethod"] }],
+            unverifiable: [],
+            checkedCalls: 1,
+        });
+        expect(text).toContain("VERIFICATION FAILED");
+        expect(text).toContain("pm.fakeMethod — not found in a.ts (+1-hop). Available members: realMethod");
+        expect(text).toContain("Do not finish until it reports PASSED.");
+    });
+});

package/build/tools/executeSkyrampTestTool.js

@@ -7,7 +7,7 @@ import { makeProgressReporter } from "../utils/progress.js";
 import { TestExecutionStatus } from "../types/TestExecution.js";
 import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
 import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
-import { StateManager } from "../utils/AnalysisStateManager.js";
+import { StateManager, getTestsRepoDir } from "../utils/AnalysisStateManager.js";
 import { TestSource } from "../types/TestAnalysis.js";
 import { logger } from "../utils/logger.js";
 import { toolError } from "../utils/utils.js";
@@ -108,10 +108,15 @@ export function registerExecuteSkyrampTestTool(server) {
             }
             // Send initial progress
             await sendProgress(0, 100, "Starting test execution...");
+            // Cross-repo run (SKYR-3819): tests delivered under the run's testsRepoDir
+            // (set by skyramp_analyze_changes, run-scoped) live outside workspacePath.
+            // Thread it through so the executor mounts the test repo and service
+            // matching still resolves the SUT baseUrl/dockerNetwork.
+            const testRepoPath = getTestsRepoDir();
             // Always resolve workspace config for dockerNetwork (host networking)
             // and optionally inject SKYRAMP_TEST_BASE_URL if not already set.
             if (params.workspacePath) {
-                const { baseUrl, dockerNetwork, candidates } = await getWorkspaceBaseUrl(params.workspacePath, params.testFile, params.language);
+                const { baseUrl, dockerNetwork, candidates } = await getWorkspaceBaseUrl(params.workspacePath, params.testFile, params.language, testRepoPath);
                 useHostNetwork = !!dockerNetwork;
                 if (!process.env.SKYRAMP_TEST_BASE_URL) {
                     if (baseUrl) {
@@ -142,6 +147,7 @@ export function registerExecuteSkyrampTestTool(server) {
             const result = await executionService.executeTest({
                 testFile: params.testFile,
                 workspacePath: params.workspacePath,
+                testRepoPath,
                 language: params.language,
                 testType: params.testType,
                 token: effectiveToken,

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

@@ -6,9 +6,10 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     path: z.ZodString;
     requestBody: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
     queryParams: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
-    responseBody: z.ZodOptional<z.ZodString>;
+    responseBody: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
     statusCode: z.ZodOptional<z.ZodNumber>;
     responseHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    uniqueFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     path: string;
     method: HttpMethod;
@@ -17,6 +18,7 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }, {
     path: string;
     method: HttpMethod;
@@ -25,6 +27,7 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }>, {
     path: string;
     method: HttpMethod;
@@ -33,6 +36,7 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }, {
     path: string;
     method: HttpMethod;
@@ -41,5 +45,6 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }>;
 export declare function registerBatchScenarioTestTool(server: McpServer): void;

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(() => {