@skyramp/mcp 0.2.6 → 0.2.150-rc.mntnc

package/build/prompts/testbot/testbot-prompts.test.js

@@ -1,13 +1,14 @@
-jest.mock("../../workspace/workspace.js", () => ({
+import { jest } from "@jest/globals";
+jest.unstable_mockModule("../../workspace/workspace.js", () => ({
     WorkspaceConfigManager: jest.fn(),
 }));
-jest.mock("../../services/AnalyticsService.js", () => ({
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
     AnalyticsService: { pushMCPToolEvent: jest.fn() },
 }));
-jest.mock("../../playwright/traceRecordingPrompt.js", () => ({
+jest.unstable_mockModule("../../playwright/traceRecordingPrompt.js", () => ({
     getTraceRecordingPromptText: () => "",
 }));
-import { getTestbotPrompt } from "./testbot-prompts.js";
+const { getTestbotPrompt, buildWorkspaceRecoveryPrefix } = await import("./testbot-prompts.js");
 // Minimal args to invoke getTestbotPrompt — only services matter for these tests
 const baseArgs = {
     prTitle: "Test PR",
@@ -24,26 +25,6 @@ function callWithServices(services) {
     undefined, // userPrompt
     services);
 }
-function callWithStateOutputFile(stateOutputFile) {
-    return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
-    undefined, // maxRecommendations
-    undefined, // maxGenerate
-    undefined, // maxCritical
-    undefined, // prNumber
-    undefined, // userPrompt
-    undefined, // services
-    stateOutputFile);
-}
-function callFollowUpWithStateOutputFile(stateOutputFile) {
-    return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
-    undefined, // maxRecommendations
-    undefined, // maxGenerate
-    undefined, // maxCritical
-    undefined, // prNumber
-    "add more tests", // userPrompt — triggers follow-up path
-    undefined, // services
-    stateOutputFile);
-}
 describe("buildServiceContext (via getTestbotPrompt)", () => {
     it("renders full service with all fields", () => {
         const prompt = callWithServices([
@@ -121,27 +102,6 @@ describe("buildServiceContext (via getTestbotPrompt)", () => {
         expect(prompt).toContain("</REPOSITORY PATH>\nUse the Skyramp MCP server tools");
     });
 });
-describe("stateOutputFile in getTestbotPrompt", () => {
-    it("includes stateOutputFile in skyramp_analyze_changes call for first-run prompt", () => {
-        const stateFile = "/tmp/skyramp/analyze-changes-state.json";
-        const prompt = callWithStateOutputFile(stateFile);
-        // The prompt must pass stateOutputFile to skyramp_analyze_changes
-        expect(prompt).toContain(`\`stateOutputFile\`: "${stateFile}"`);
-    });
-    it("includes stateOutputFile in skyramp_analyze_changes call for follow-up prompt", () => {
-        const stateFile = "/tmp/skyramp/analyze-changes-state.json";
-        const prompt = callFollowUpWithStateOutputFile(stateFile);
-        expect(prompt).toContain(`\`stateOutputFile\`: "${stateFile}"`);
-    });
-    it("omits stateOutputFile from skyramp_analyze_changes call when not provided", () => {
-        const prompt = callWithStateOutputFile(undefined);
-        expect(prompt).not.toContain("stateOutputFile");
-    });
-    it("omits stateOutputFile from follow-up prompt when not provided", () => {
-        const prompt = callFollowUpWithStateOutputFile(undefined);
-        expect(prompt).not.toContain("stateOutputFile");
-    });
-});
 describe("uiCredentials in getTestbotPrompt", () => {
     function callWithUiCredentials(uiCredentials) {
         return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
@@ -151,7 +111,6 @@ describe("uiCredentials in getTestbotPrompt", () => {
         undefined, // prNumber
         undefined, // userPrompt
         undefined, // services
-        undefined, // stateOutputFile
         uiCredentials);
     }
     // The instructions text references `<ui-credentials>` in prose (backticked);
@@ -216,13 +175,11 @@ describe("drift analysis — runtime tool call (step 3)", () => {
         const prompt = basePrompt();
         expect(prompt).toContain("skyramp_actions");
     });
-    it("step 3 appears inside Task 1, before Task 2", () => {
+    it("skyramp_analyze_test_health is referenced in the prompt", () => {
+        // After the unified maintenance refactor, analyze_test_health is referenced
+        // in the testMaintenance submission guidance rather than as an explicit step.
         const prompt = basePrompt();
-        const task1Pos = prompt.indexOf("## Task 1");
-        const healthPos = prompt.indexOf("skyramp_analyze_test_health");
-        const task2Pos = prompt.indexOf("## Task 2");
-        expect(healthPos).toBeGreaterThan(task1Pos);
-        expect(healthPos).toBeLessThan(task2Pos);
+        expect(prompt).toContain("skyramp_analyze_test_health");
     });
     it("does not contain the build-time embedded drift_analysis_rules content (Action Decision Tree)", () => {
         // The rules are now fetched at runtime via skyramp_analyze_test_health —
@@ -237,57 +194,7 @@ describe("drift analysis — runtime tool call (step 3)", () => {
         expect(prompt).not.toContain("You are acting as a Skyramp Integration Architect");
     });
 });
-describe("UI grounding via Task 2 capture-act-capture", () => {
-    it("surfaces uiContext as guidance, not a contract", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // uiContext fields are explained inline so the agent knows what to do with
-        // them. Step 1 provides candidate URLs but gives fallback instructions
-        // ("navigate from the workspace baseUrl and explore") for 404s/redirects,
-        // treating candidates as guidance not a rigid contract.
-        expect(prompt).toContain("uiContext");
-        expect(prompt).toContain("candidateUiPages");
-        expect(prompt).toContain("changedFrontendFiles");
-        expect(prompt).toMatch(/navigate from the workspace baseUrl and explore/i);
-    });
-    it("step 5 enforces Blueprint Citation Invariant in natural prose", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // Step 5 is the citation-invariant guardrail, not a "fill in tuples"
-        // post-processing step (slice 4 cleanup: recs are grounded upstream).
-        expect(prompt).toContain("Blueprint Citation Invariant");
-        // Reasoning must be natural prose, NOT internal-identifier syntax.
-        expect(prompt).toMatch(/natural prose/i);
-        expect(prompt).toMatch(/internal-identifier syntax/i);
-    });
-    it("Task 2 no longer instructs the agent to fill in tuples post-hoc", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // After slice 4 cleanup: Task 2 captures are for trace recording's own
-        // assertions, not for retroactively rewriting recommendation reasoning.
-        // The phrase "fill in tuples" must NOT appear anywhere in the prompt.
-        expect(prompt).not.toMatch(/fill in tuples/i);
-        expect(prompt).not.toMatch(/return to step 5 and fill/i);
-    });
-    it("Task 2 step 5 mentions possibleAssertions as available, NOT as required (slice 5.5 softening)", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // Slice 5: AFTER-action browser_blueprint response includes
-        // possibleAssertions[] — mechanically translated candidates.
-        expect(prompt).toContain("possibleAssertions");
-        // Slice 5.5: prompt explicitly tells the agent NOT to feel obligated.
-        // Two P09 runs with the prior "emit at least one" directive showed the
-        // agent over-using shallow visibility assertions at the expense of
-        // integration-test depth. The softened version says: read them, use
-        // when they happen to match what you'd write anyway, ignore otherwise.
-        expect(prompt).toMatch(/do not feel obligated/i);
-        expect(prompt).toMatch(/biased toward visibility/i);
-        // The candidate format is still documented.
-        expect(prompt).toMatch(/\bcode\b.*\brationale\b.*\btier\b/i);
-        // The pre-existing "at least one browser_assert per page navigated"
-        // rule should be preserved (it's about meaningful business-outcome
-        // assertions, not about possibleAssertions).
-        expect(prompt).toMatch(/at least one .browser_assert. per page navigated/i);
-    });
-});
 describe("buildWorkspaceRecoveryPrefix", () => {
-    const { buildWorkspaceRecoveryPrefix } = require("./testbot-prompts.js");
     it("includes repositoryPath in both init_scan and init_workspace instructions", () => {
         const prefix = buildWorkspaceRecoveryPrefix("/home/user/repo");
         expect(prefix).toContain('skyramp_init_scan with workspacePath "/home/user/repo"');
@@ -312,7 +219,6 @@ describe("testsRepoDir in getTestbotPrompt", () => {
         undefined, // prNumber
         undefined, // userPrompt
         undefined, // services
-        undefined, // stateOutputFile
         undefined, // uiCredentials
         testsRepoDir);
     }
@@ -324,7 +230,6 @@ describe("testsRepoDir in getTestbotPrompt", () => {
         undefined, // prNumber
         "add more tests", // userPrompt — triggers follow-up path
         undefined, // services
-        undefined, // stateOutputFile
         undefined, // uiCredentials
         testsRepoDir);
     }
@@ -348,20 +253,13 @@ describe("testsRepoDir in getTestbotPrompt", () => {
     });
 });
 describe("testbot prompt blueprint-grounded recommendations (slice 4)", () => {
-    it("instructs the agent to call skyramp_ui_analyze_changes before skyramp_analyze_changes", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        const uiacIdx = prompt.indexOf("skyramp_ui_analyze_changes");
-        const acIdx = prompt.indexOf("skyramp_analyze_changes");
-        expect(uiacIdx).toBeGreaterThan(-1);
-        expect(acIdx).toBeGreaterThan(uiacIdx);
-    });
-    it("Task 1 step 1 instructs the agent to capture blueprints (without threading them through a param)", () => {
+    it("uses a single skyramp_analyze_changes call (no separate pre-flight tool, no blueprint threading)", () => {
         const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // Captures stay in tool-result history; analyze_changes returns the
-        // authoring rules and the agent supplies the captured vocabulary.
-        expect(prompt).toMatch(/browser_blueprint`?\s*to capture/i);
-        expect(prompt).toMatch(/tool-result history/i);
-        // Make sure we removed the old capturedBlueprints threading directive.
+        // The standalone pre-flight tool is gone — its work folded into analyze_changes.
+        expect(prompt).not.toContain("skyramp_ui_analyze_changes");
+        expect(prompt).toContain("skyramp_analyze_changes");
+        // Captures stay in tool-result history — the old capturedBlueprints
+        // threading directive must be gone.
         expect(prompt).not.toMatch(/capturedBlueprints/);
     });
     // Flutter support — both the generalised UI trigger wording and the

package/build/resources/analysisResources.d.ts

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const ANALYSIS_URI_PREFIX = "skyramp://analysis";
+/**
+ * Register MCP Resources for analysis data access.
+ *
+ * Resources provide read-only, token-efficient access to analysis data
+ * via sessionId. The state file is an internal backing store.
+ *
+ * URI scheme:
+ *   skyramp://analysis/{sessionId}/summary
+ *   skyramp://analysis/{sessionId}/endpoints
+ *   skyramp://analysis/{sessionId}/endpoints/{+path}
+ *   skyramp://analysis/{sessionId}/endpoints/{+path}/{method}
+ *   skyramp://analysis/{sessionId}/scenarios
+ *   skyramp://analysis/{sessionId}/diff
+ */
+export declare function registerAnalysisResources(server: McpServer): void;

package/build/resources/progressResource.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerProgressResource(server: McpServer): void;

package/build/resources/sutSetupResource.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSutSetupResource(server: McpServer): void;

package/build/resources/sutSetupResource.js

@@ -0,0 +1,45 @@
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { logger } from "../utils/logger.js";
+import { resourceText } from "../utils/utils.js";
+import { AnalyticsService } from "../services/AnalyticsService.js";
+import { getAdaptWorkflowPrompt } from "../prompts/sut-setup/modes/adaptWorkflowPrompt.js";
+import { getDockerComposePrompt } from "../prompts/sut-setup/modes/dockerComposePrompt.js";
+import { SutSetupMode } from "../prompts/sut-setup/shared.js";
+export function registerSutSetupResource(server) {
+    logger.info("Registering SUT setup resource");
+    // RFC 6570 {+rest} (reserved expansion) captures the entire query string
+    // including the leading "?". This avoids the SDK's per-param regex which
+    // fails on empty query-param values.
+    const template = new ResourceTemplate("skyramp://prompts/skyramp_testbot_sut{+rest}", { list: undefined });
+    server.registerResource("skyramp_testbot_sut", template, {
+        title: "Skyramp Testbot SUT Setup",
+        description: "Returns mode-specific instructions for SUT (System Under Test) setup. " +
+            "Modes: none, adapt_workflow, docker_compose.",
+        mimeType: "text/plain",
+    }, async (uri) => {
+        const param = (name, fallback) => uri.searchParams.get(name) ?? fallback;
+        const mode = param("sutSetupMode", SutSetupMode.None);
+        const args = {
+            repositoryPath: param("repositoryPath", "."),
+            sutSetupMode: mode,
+            sutSourceWorkflowFile: param("sutSourceWorkflowFile", ""),
+            sutSourceDockerComposeFile: param("sutSourceDockerComposeFile", ""),
+        };
+        let prompt;
+        switch (mode) {
+            case SutSetupMode.AdaptWorkflow:
+                prompt = getAdaptWorkflowPrompt(args);
+                break;
+            case SutSetupMode.DockerCompose:
+                prompt = getDockerComposePrompt(args);
+                break;
+            case SutSetupMode.None:
+                prompt = "sutSetupMode is 'none'. No SUT setup required.";
+                break;
+            default:
+                prompt = `Unknown SUT setup mode: '${mode}'. Valid modes: none, adapt_workflow, docker_compose.`;
+        }
+        AnalyticsService.pushMCPToolEvent("skyramp_testbot_sut_resource", undefined, { mode }).catch(() => { });
+        return resourceText(uri.toString(), prompt);
+    });
+}

package/build/resources/testbotResource.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTestbotResource(server: McpServer): void;

package/build/resources/testbotResource.js

@@ -25,7 +25,7 @@ export function registerTestbotResource(server) {
         const maxCrit = parseInt(uri.searchParams.get("maxCritical") || "", 10);
         const repositoryPath = param("repositoryPath", ".");
         const services = await readWorkspaceServices(repositoryPath);
-        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("summaryOutputFile", ""), repositoryPath, uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen, isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit, isNaN(prNum) ? undefined : prNum, uri.searchParams.get("userPrompt") || undefined, services.length ? services : undefined, uri.searchParams.get("stateOutputFile") || undefined, uri.searchParams.get("uiCredentials") || undefined, uri.searchParams.get("testsRepoDir") || undefined);
+        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("summaryOutputFile", ""), repositoryPath, uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen, isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit, isNaN(prNum) ? undefined : prNum, uri.searchParams.get("userPrompt") || undefined, services.length ? services : undefined, uri.searchParams.get("uiCredentials") || undefined, uri.searchParams.get("testsRepoDir") || undefined);
         AnalyticsService.pushMCPToolEvent("skyramp_testbot_prompt", undefined, {}).catch(() => { });
         // Return the original URI — clients may use it to re-fetch the resource,
         // and the caller already has these params. Credentials never appear in

package/build/services/AnalyticsService.d.ts

@@ -0,0 +1,13 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare class AnalyticsService {
+    static pushTestGenerationToolEvent(toolName: string, result: CallToolResult, params: Record<string, any>): Promise<void>;
+    static pushMCPToolEvent(toolName: string, result: CallToolResult | undefined, params: Record<string, string>): Promise<void>;
+    /**
+     * Track server crash events
+     */
+    static pushServerCrashEvent(crashType: string, errorMessage: string, errorStack?: string): Promise<void>;
+    /**
+     * Track tool timeout events
+     */
+    static pushToolTimeoutEvent(toolName: string, timeoutMs: number, params: Record<string, string>): Promise<void>;
+}

package/build/services/AnalyticsService.test.d.ts

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

package/build/services/AnalyticsService.test.js

@@ -0,0 +1,86 @@
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+// AnalyticsService resolves the MCP version with
+// `fileURLToPath(import.meta.url)` at module scope. Under ts-jest's old
+// CommonJS transform that top-level import.meta failed to compile with TS1343,
+// so this module — and therefore this test — could not exist. The native-ESM
+// Jest config (SKYR-3799) is what makes it loadable.
+// pushToolEvent lives in @skyramp/skyramp, which pulls the native dylib. Mock
+// it so we can assert on the event payload without loading the binary. Under
+// native ESM jest.mock is not hoisted — use unstable_mockModule + dynamic
+// import of the subject below.
+const pushToolEvent = jest.fn();
+jest.unstable_mockModule("@skyramp/skyramp", () => ({ pushToolEvent }));
+jest.unstable_mockModule("../utils/telemetry.js", () => ({
+    getEntryPoint: jest.fn(() => "mcp"),
+    getCIPlatform: jest.fn(() => undefined),
+    getRepositoryInfo: jest.fn(async () => ({})),
+}));
+jest.unstable_mockModule("../utils/logger.js", () => ({
+    logger: { info: jest.fn(), error: jest.fn(), debug: jest.fn(), warn: jest.fn() },
+}));
+const { AnalyticsService } = await import("./AnalyticsService.js");
+const telemetry = await import("../utils/telemetry.js");
+// The version the production code should resolve: package.json two levels up
+// from this module's own location — the same lookup getMCPPackageVersion does
+// via import.meta.url. Computing it the same way here proves the test harness
+// itself supports import.meta now.
+const expectedVersion = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8")).version;
+describe("AnalyticsService — import.meta-based version resolution", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        telemetry.getEntryPoint.mockReturnValue("mcp");
+        telemetry.getCIPlatform.mockReturnValue(undefined);
+        telemetry.getRepositoryInfo.mockResolvedValue({});
+    });
+    it("stamps the package.json version (resolved via import.meta.url) into the event params", async () => {
+        const params = {};
+        await AnalyticsService.pushMCPToolEvent("skyramp_smoke_test_generation", undefined, params);
+        expect(pushToolEvent).toHaveBeenCalledTimes(1);
+        const [, toolName, , sentParams] = pushToolEvent.mock.calls[0];
+        expect(toolName).toBe("skyramp_smoke_test_generation");
+        expect(sentParams.mcpServerVersion).toBe(expectedVersion);
+        // Sanity: a real semver-ish string, not an empty/undefined fallback.
+        expect(sentParams.mcpServerVersion).toMatch(/^\d+\.\d+\.\d+/);
+    });
+    it("concatenates error text from an isError result into the event error message", async () => {
+        const result = {
+            isError: true,
+            content: [
+                { type: "text", text: "first failure" },
+                { type: "text", text: "second failure" },
+            ],
+        };
+        await AnalyticsService.pushMCPToolEvent("skyramp_execute_test", result, {});
+        const [, , errorMessage] = pushToolEvent.mock.calls[0];
+        expect(errorMessage).toBe("first failure, second failure");
+    });
+    it("sends an empty error message for a successful result", async () => {
+        const result = { isError: false, content: [{ type: "text", text: "ok" }] };
+        await AnalyticsService.pushMCPToolEvent("skyramp_execute_test", result, {});
+        const [, , errorMessage] = pushToolEvent.mock.calls[0];
+        expect(errorMessage).toBe("");
+    });
+    it("includes ciPlatform in the params when running in CI", async () => {
+        telemetry.getCIPlatform.mockReturnValue("github_actions");
+        const params = {};
+        await AnalyticsService.pushMCPToolEvent("skyramp_init_workspace", undefined, params);
+        const [, , , sentParams] = pushToolEvent.mock.calls[0];
+        expect(sentParams.ciPlatform).toBe("github_actions");
+    });
+    it("merges repository info into the params", async () => {
+        telemetry.getRepositoryInfo.mockResolvedValue({ repoName: "letsramp/mcp", repoOwner: "letsramp" });
+        const params = { repositoryPath: "/repo" };
+        await AnalyticsService.pushMCPToolEvent("skyramp_analyze_changes", undefined, params);
+        expect(telemetry.getRepositoryInfo).toHaveBeenCalledWith("/repo");
+        const [, , , sentParams] = pushToolEvent.mock.calls[0];
+        expect(sentParams.repoName).toBe("letsramp/mcp");
+    });
+    it("swallows errors from pushToolEvent (telemetry must never break a tool call)", async () => {
+        pushToolEvent.mockRejectedValueOnce(new Error("network down"));
+        await expect(AnalyticsService.pushMCPToolEvent("skyramp_smoke_test_generation", undefined, {})).resolves.toBeUndefined();
+    });
+});

package/build/services/ModularizationService.d.ts

@@ -0,0 +1,11 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export interface ModularizationParams {
+    testFile: string;
+    testType?: string;
+    language?: string;
+    isTraceBased?: boolean;
+    prompt?: string;
+}
+export declare class ModularizationService {
+    processModularizationRequest(params: ModularizationParams): Promise<CallToolResult>;
+}

package/build/services/ScenarioGenerationService.d.ts

@@ -0,0 +1,37 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export interface TraceRequest {
+    Source: string;
+    Destination: string;
+    RequestBody: string;
+    ResponseBody: string;
+    RequestHeaders: Record<string, string[]>;
+    ResponseHeaders: Record<string, string[]>;
+    Method: string;
+    Path: string;
+    QueryParams: Record<string, string[]>;
+    StatusCode: number;
+    Port: number;
+    Timestamp: string;
+    Scheme: string;
+}
+export interface ScenarioParams {
+    scenarioName: string;
+    destination: string;
+    apiSchema?: string;
+    baseURL?: string;
+    method: string;
+    path: string;
+    requestBody?: string;
+    queryParams?: string;
+    responseBody?: string;
+    statusCode?: number;
+    outputDir: string;
+    authHeader?: string;
+    authScheme?: string;
+    authToken?: string;
+    responseHeaders?: Record<string, string[]>;
+}
+export declare class ScenarioGenerationService {
+    parseScenario(params: ScenarioParams): Promise<CallToolResult>;
+    generateTraceRequestFromInput(params: ScenarioParams): TraceRequest | null;
+}

package/build/services/ScenarioGenerationService.integration.test.d.ts

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

package/build/services/ScenarioGenerationService.integration.test.js

@@ -4,10 +4,14 @@
  *
  * Requires: @skyramp/skyramp native dylib (skips if not available)
  */
+import { jest } from "@jest/globals";
 import fs from "fs";
 import path from "path";
 import os from "os";
+import { createRequire } from "module";
 import { ScenarioGenerationService } from "./ScenarioGenerationService.js";
+// Native dylib is a CommonJS addon — load it via createRequire under ESM.
+const require = createRequire(import.meta.url);
 let SkyrampClient;
 try {
     SkyrampClient = require("@skyramp/skyramp").SkyrampClient;

package/build/services/ScenarioGenerationService.test.d.ts

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

package/build/services/TestDiscoveryService.d.ts

@@ -0,0 +1,128 @@
+import { TestAnalysisResult } from "../types/TestAnalysis.js";
+interface TestDiscoveryResult {
+    tests: TestAnalysisResult[];
+    /** Paths of external files that were deemed relevant to the PR (score > 0). */
+    relevantExternalTestPaths: string[];
+}
+export interface TestDiscoveryOptions {
+    /**
+     * Resource names derived from endpoints in changed files (e.g. ["orders", "products"]).
+     * - Non-empty array: external files partitioned by relevance; only relevant files
+     *   get full endpoint extraction. May be the sentinel `["unknown"]` when endpoints
+     *   exist but resource names are unresolvable — treated as "endpoints present" to
+     *   avoid skipping external coverage. Also used for "add field" PRs where the changed
+     *   files have no endpoint definitions but the scanner found related endpoints nearby.
+     * - Empty array `[]`: PR mode with no endpoints from diff or scanner — external
+     *   tests are skipped entirely to avoid flooding context.
+     * - `undefined`: full-repo mode — external tests capped at MAX_EXTERNAL_FULL_REPO.
+     */
+    changedResources?: string[];
+}
+export declare class TestDiscoveryService {
+    private readonly EXCLUDED_DIRS;
+    private readonly SKYRAMP_MARKER;
+    private readonly SUPPORTED_EXTENSIONS;
+    private readonly MAX_CONCURRENT_OPERATIONS;
+    private readonly MAX_EXTERNAL_FULL_REPO;
+    private readonly TEST_FILE_PATTERNS;
+    private readonly TEST_DIR_PATTERNS;
+    /**
+     * Discover all tests under testDir — both Skyramp-generated and external (user-written).
+     * Uses fast-glob for cross-platform file scanning, then classifies discovered files
+     * as Skyramp-generated tests, external tests, or not-a-test during processing.
+     *
+     * External test handling depends on `options.changedResources`:
+     * - `string[]` with entries (PR mode, endpoints detected): partition by relevance.
+     * - `[]` empty array (PR mode, scanner found no endpoints): skip external tests entirely
+     *   rather than flooding context with irrelevant files.
+     * - `undefined` (full-repo mode, no diff): cap at MAX_EXTERNAL_FULL_REPO.
+     */
+    discoverTests(testDir: string, options?: TestDiscoveryOptions): Promise<TestDiscoveryResult>;
+    /**
+     * Score an external test file's relevance to a set of changed resource names.
+     * Tokenises the last two segments of the file path (split by /, \, -, _, .)
+     * and counts overlapping tokens with the changed resources.
+     * Example: "test_orders_api.py" vs ["orders"] → score 1.
+     */
+    private scoreRelevance;
+    /**
+     * Partition external test files into relevant (score > 0) and low-relevance (score = 0).
+     * Signal: path/name token overlap with changedResources.
+     */
+    private partitionByRelevance;
+    /**
+     * Process test files in parallel batches with concurrency control
+     * @param isExternal When true, uses external test metadata extraction
+     * @param contentCache Optional pre-read file contents from classification pass
+     */
+    private processFilesInBatches;
+    /**
+     * Classify candidate files as skyramp (has marker), external (test file without
+     * marker), or not-a-test. Caches file contents so downstream metadata extraction
+     * doesn't need to re-read from disk.
+     */
+    private classifyTestFiles;
+    /**
+     * Check if a file is an external (non-Skyramp) test file based on naming convention
+     * or directory placement.
+     */
+    private isExternalTestFile;
+    /**
+     * Extract metadata from a test file
+     * File is already confirmed to contain Skyramp marker by file search
+     * @param cachedContent Optional pre-read content from classification pass
+     */
+    private extractTestMetadata;
+    /**
+     * Extract the HTTP methods and paths covered by this test file.
+     * Returns a comma-separated string like "GET /orders/{id}, DELETE /orders/{id}".
+     * Handles Python (send_request / check_schema) and TypeScript/JS (sendRequest).
+     */
+    private extractCoveredEndpoints;
+    /**
+     * Extract metadata from an external (non-Skyramp) test file.
+     * Uses heuristic patterns for endpoint extraction, test type, and framework detection.
+     * @param cachedContent Optional pre-read content from classification pass
+     */
+    private extractExternalTestMetadata;
+    /**
+     * Extract HTTP endpoints from external (non-Skyramp) test files.
+     * Matches common patterns: requests.get, axios.post, fetch, supertest, RestAssured.
+     */
+    private extractExternalEndpoints;
+    /**
+     * Normalize an endpoint path extracted from test code.
+     * Strips base URL prefixes and returns only the path portion.
+     * Returns null if the path doesn't look like an API endpoint.
+     */
+    private normalizeEndpointPath;
+    /**
+     * Detect test type from external test file path and content.
+     * Falls back to directory/filename heuristics since external tests lack Skyramp command lines.
+     */
+    private detectExternalTestType;
+    /**
+     * Detect test framework from external test file content by checking imports.
+     */
+    private detectExternalFramework;
+    /**
+     * Detect programming language from file extension
+     */
+    private detectLanguage;
+    /**
+     * Detect test type from file content and name
+     * Checks Skyramp command line, filename, and content patterns
+     */
+    private detectTestType;
+    /**
+     * Extract API schema path from test content
+     * Looks for Skyramp command line first, then fallback to other patterns
+     */
+    private extractApiSchema;
+    /**
+     * Extract Framework from test content
+     * Looks for Skyramp command line first, then fallback to other patterns
+     */
+    private extractFramework;
+}
+export {};