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

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>;

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

@@ -0,0 +1,78 @@
+/**
+ * SKYR-3879 Path B — hard gate wired into the generation tools' handlers.
+ * Conditional on an ACTIVE testbot run carrying an `approvedPlan`: standalone
+ * / IDE MCP usage (no active run) and runs that never pre-seeded or
+ * registered a plan are both unaffected (return null = allowed).
+ */
+import * as path from "path";
+import { getActiveRunStatePath, StateManager } from "../../utils/AnalysisStateManager.js";
+import { matchesApprovedPlan } from "../../utils/planMatchKeys.js";
+import { TOOL_REGISTER_TEST_PLAN } from "../../toolNames.js";
+/**
+ * Resolve the active run's state file path. `getActiveRunStatePath()` is only
+ * set by skyramp_analyze_changes for multi-repo runs (the ones carrying a
+ * `repository` param — see AnalysisStateManager.ts). Single-repo Testbot runs
+ * never set it, but their stateFile path is still deterministic in CI: the
+ * StateManager constructor roots "analysis"-type state under
+ * `$RUNNER_TEMP/skyramp/analyze-changes-state.json`. Falling back to that path
+ * covers single-repo Testbot runs without requiring a new anchor mechanism;
+ * standalone/IDE usage (no RUNNER_TEMP) still resolves to undefined.
+ */
+function resolveGuardStatePath() {
+    const anchored = getActiveRunStatePath();
+    if (anchored)
+        return anchored;
+    if (process.env.RUNNER_TEMP) {
+        return path.join(process.env.RUNNER_TEMP, "skyramp", "analyze-changes-state.json");
+    }
+    return undefined;
+}
+/** 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 function pathFromEndpointURL(endpointURL) {
+    if (!endpointURL)
+        return undefined;
+    try {
+        // new URL() percent-encodes {param} placeholders ({id} → %7Bid%7D), while
+        // register-time matchKeys are computed from raw scenario paths with braces
+        // intact — restore them or parameterized endpoints never match the plan.
+        return new URL(endpointURL).pathname.replace(/%7B/gi, "{").replace(/%7D/gi, "}");
+    }
+    catch {
+        return endpointURL.startsWith("/") ? endpointURL : 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 async function guardScenarioApproved(query) {
+    const statePath = resolveGuardStatePath();
+    if (!statePath)
+        return null;
+    let stateData;
+    try {
+        stateData = await StateManager.fromStatePath(statePath).readData();
+    }
+    catch {
+        // Unreadable/corrupt state must never block generation on an infra hiccup.
+        return null;
+    }
+    const approvedPlan = stateData?.approvedPlan;
+    if (!approvedPlan)
+        return null;
+    // GENERATE items, plus ADDITIONAL as the documented backfill pool — but only
+    // when there's a non-empty GENERATE list to backfill (see matchesApprovedPlan).
+    if (matchesApprovedPlan(approvedPlan, query))
+        return null;
+    const outstanding = approvedPlan.generate.length > 0
+        ? approvedPlan.generate.map((item) => `  - [${item.testType}] ${item.scenarioName}`).join("\n")
+        : "  (none)";
+    return (`This scenario is not in the approved plan from ${TOOL_REGISTER_TEST_PLAN} (plan ${approvedPlan.planId}) — neither its GENERATE nor its ADDITIONAL list.\n\n` +
+        `Outstanding approved GENERATE items:\n${outstanding}\n\n` +
+        `Call ${TOOL_REGISTER_TEST_PLAN} first with this candidate included in \`candidates\`, then retry generation using the ` +
+        `exact scenarioName/testType/endpoint from the returned GENERATE list.`);
+}

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

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

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

@@ -0,0 +1,185 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+const { guardScenarioApproved, pathFromEndpointURL } = await import("./planGuard.js");
+const { setActiveRunStatePath, clearActiveRunStatePath } = await import("../../utils/AnalysisStateManager.js");
+const { CandidateSource } = await import("../../types/Recommendation.js");
+async function writeStateFile(dir, data) {
+    const stateFile = path.join(dir, "analyze-changes-state.json");
+    await fs.writeFile(stateFile, JSON.stringify({
+        existingTests: [],
+        analysisScope: "current_branch_diff",
+        newEndpoints: [],
+        ...data,
+        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 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"],
+};
+describe("guardScenarioApproved — SKYR-3879 Path B hard gate", () => {
+    let tmpDirs = [];
+    const originalRunnerTemp = process.env.RUNNER_TEMP;
+    afterEach(async () => {
+        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(), "plan-guard-test-"));
+        tmpDirs.push(dir);
+        return dir;
+    }
+    it("allows (returns null) when there is no active run state at all", async () => {
+        clearActiveRunStatePath();
+        delete process.env.RUNNER_TEMP;
+        const result = await guardScenarioApproved({ scenarioName: "anything" });
+        expect(result).toBeNull();
+    });
+    it("allows when the active run's state has no approvedPlan (standalone / pre-registration back-compat)", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {});
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_workflow", testType: "integration" });
+        expect(result).toBeNull();
+    });
+    it("allows a scenarioName match against an approved GENERATE item", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_workflow", testType: "integration" });
+        expect(result).toBeNull();
+    });
+    it("allows a testType+method+path match against an approved GENERATE item (contract fallback key)", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ testType: "integration", method: "POST", path: "/api/v1/orders" });
+        expect(result).toBeNull();
+    });
+    it("allows a match against an approved ADDITIONAL item (documented backfill path)", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [
+                    {
+                        ...APPROVED_ITEM,
+                        candidateId: "backfill-efgh5678",
+                        scenarioName: "orders_backfill",
+                        matchKeys: ["name:orders-backfill", "ep:integration:GET:/api/v1/orders"],
+                    },
+                ],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_backfill", testType: "integration" });
+        expect(result).toBeNull();
+    });
+    it("rejects an ADDITIONAL match when the GENERATE list is empty — zero-budget plans have nothing to backfill", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-zero-budget",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [],
+                additional: [APPROVED_ITEM],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_workflow", testType: "integration" });
+        expect(result).not.toBeNull();
+        expect(result).toContain("plan-zero-budget");
+    });
+    it("rejects with the outstanding GENERATE list when nothing matches", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "unregistered_scenario", testType: "contract" });
+        expect(result).not.toBeNull();
+        expect(result).toContain("plan-1");
+        expect(result).toContain("orders_workflow");
+        expect(result).toContain("skyramp_register_test_plan");
+    });
+    it("falls back to the deterministic RUNNER_TEMP state path for single-repo Testbot runs (no active-run anchor set)", async () => {
+        const dir = await mkTmpDir();
+        process.env.RUNNER_TEMP = dir;
+        const skyrampDir = path.join(dir, "skyramp");
+        await fs.mkdir(skyrampDir, { recursive: true });
+        await fs.writeFile(path.join(skyrampDir, "analyze-changes-state.json"), JSON.stringify({
+            existingTests: [],
+            analysisScope: "current_branch_diff",
+            newEndpoints: [],
+            approvedPlan: {
+                planId: "ci-plan",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+            metadata: {
+                sessionId: "ci-session",
+                stateType: "analysis",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                updatedAt: "2026-01-01T00:00:00.000Z",
+            },
+        }), "utf-8");
+        clearActiveRunStatePath(); // simulate a single-repo run: never set
+        const matched = await guardScenarioApproved({ scenarioName: "orders_workflow" });
+        expect(matched).toBeNull();
+        const rejected = await guardScenarioApproved({ scenarioName: "something_else" });
+        expect(rejected).toContain("ci-plan");
+    });
+});
+describe("pathFromEndpointURL", () => {
+    it("preserves {param} placeholders that new URL() percent-encodes (seed-1 gate false-reject regression)", () => {
+        expect(pathFromEndpointURL("http://localhost:8092/api/circuits/providers/{id}/summary/")).toBe("/api/circuits/providers/{id}/summary/");
+    });
+    it("passes through bare paths and rejects non-URL garbage", () => {
+        expect(pathFromEndpointURL("/api/v1/products/{product_id}")).toBe("/api/v1/products/{product_id}");
+        expect(pathFromEndpointURL("not a url")).toBeUndefined();
+        expect(pathFromEndpointURL(undefined)).toBeUndefined();
+    });
+});

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

@@ -0,0 +1,10 @@
+/** File name the batch tool writes for a scenario: `scenario_<slug>.json`. */
+export declare function scenarioFileNameFor(scenarioName: string): string;
+/**
+ * Best-effort extraction of the scenarioName a scenario file belongs to, for
+ * plan-guard matching. Prefers the embedded `scenarioName` on the first
+ * entry; falls back to the filename slug after a successful parse. Returns
+ * undefined for unreadable/corrupt files — the guard then fails closed, so a
+ * malformed file can never bypass the gate.
+ */
+export declare function readScenarioNameFromFile(scenarioFile: string | undefined): string | undefined;

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

@@ -0,0 +1,46 @@
+/**
+ * SKYR-3884 — the scenario file's identity contract, in one place.
+ *
+ * A scenario file is a bare TraceRequest[] (the Go codegen's format, so no
+ * file-level wrapper is possible). Its identity — the scenarioName the plan
+ * guard matches against the approved plan — travels two ways:
+ *   1. embedded as `scenarioName` on each entry (writer: ScenarioGenerationService), and
+ *   2. encoded in the file name `scenario_<slug>.json` (writer: the batch tool).
+ * The reader prefers (1) and falls back to (2) for files written before the
+ * embedding existed (MCP <= 0.3.1, incl. files already committed to repos).
+ * Keeping the two writers and the reader in one module pins the naming
+ * convention so they cannot drift apart silently.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "../../utils/logger.js";
+/** File name the batch tool writes for a scenario: `scenario_<slug>.json`. */
+export function scenarioFileNameFor(scenarioName) {
+    const slug = scenarioName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "scenario";
+    return `scenario_${slug}.json`;
+}
+/**
+ * Best-effort extraction of the scenarioName a scenario file belongs to, for
+ * plan-guard matching. Prefers the embedded `scenarioName` on the first
+ * entry; falls back to the filename slug after a successful parse. Returns
+ * undefined for unreadable/corrupt files — the guard then fails closed, so a
+ * malformed file can never bypass the gate.
+ */
+export function readScenarioNameFromFile(scenarioFile) {
+    if (!scenarioFile)
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(scenarioFile, "utf-8"));
+        const first = Array.isArray(parsed) ? parsed[0] : undefined;
+        if (typeof first?.scenarioName === "string")
+            return first.scenarioName;
+        return /^scenario_(.+)\.json$/.exec(path.basename(scenarioFile))?.[1];
+    }
+    catch (error) {
+        logger.warning("could not read scenarioName from scenarioFile — plan guard will fail closed if a plan is active", {
+            scenarioFile,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * SKYR-3884 — write-side chaining lint for synthesized scenario files.
+ *
+ * The Go codegen chains FKs and path params by VALUE-matching a step's
+ * request against PRIOR steps' response bodies. The scenario schema therefore
+ * asks the agent to "plant" matching values (a create's responseBody id
+ * reused in later paths/bodies). When the bait is missing or mis-ordered the
+ * generated test silently degrades to hardcoded literals — the SKYR-3884
+ * failure family. This lint checks the bait at write time:
+ *
+ *  - a referenced value produced ONLY by a later step  → error (step order)
+ *  - a reference produced by no prior step at all      → warning (hardcode)
+ *  - a reference produced by multiple prior steps      → warning (ambiguous)
+ *
+ * Only id-like references are considered (numeric/UUID path segments; body
+ * fields with id-like keys, or keys resource-affine to a producing step's
+ * collection path) to keep noise down — mirroring the reader's own matching.
+ */
+export interface LintStep {
+    method?: string;
+    path?: string;
+    requestBody?: string;
+    responseBody?: string;
+}
+export interface ScenarioLintResult {
+    errors: string[];
+    warnings: string[];
+}
+export declare function parseJsonObject(raw: string | undefined): unknown;
+export declare function lintScenarioChaining(steps: LintStep[]): ScenarioLintResult;