@skyramp/mcp 0.2.5 → 0.2.7

package/build/tools/submitReportTool.test.js

@@ -1,17 +1,19 @@
-// @ts-ignore
-import { registerSubmitReportTool, additionalRecommendationSchema } from "./submitReportTool.js";
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
 import { TestType } from "../types/TestTypes.js";
 import { DriftAction } from "../types/TestAnalysis.js";
-import { AnalyticsService } from "../services/AnalyticsService.js";
 import * as fs from "fs/promises";
 import * as path from "path";
 import * as os from "os";
-jest.mock("../utils/logger.js", () => ({
+jest.unstable_mockModule("../utils/logger.js", () => ({
     logger: { info: jest.fn(), error: jest.fn() },
 }));
-jest.mock("../services/AnalyticsService.js", () => ({
+jest.unstable_mockModule("../services/AnalyticsService.js", () => ({
     AnalyticsService: { pushMCPToolEvent: jest.fn().mockResolvedValue(undefined) },
 }));
+// @ts-ignore
+const { registerSubmitReportTool, additionalRecommendationSchema, newTestSchema, targetElementSchema, pageContextSchema } = await import("./submitReportTool.js");
+const { AnalyticsService } = await import("../services/AnalyticsService.js");
 const pushMCPToolEventMock = AnalyticsService.pushMCPToolEvent;
 function captureToolHandler() {
     let handler;
@@ -293,6 +295,214 @@ describe("registerSubmitReportTool", () => {
             expect(result.data.primaryEndpoint).toBeUndefined();
         }
     });
+    // Structured grounding fields for UI recommendations.
+    // ----------------------------------------------------------------------
+    // Sub-schemas — targetElement and pageContext — populated by the agent
+    // from a captured browser_blueprint element. UI-only via superRefine on
+    // the parent newTestSchema / additionalRecommendationSchema.
+    describe("targetElementSchema", () => {
+        const validTarget = {
+            role: "button",
+            accessibleName: "Save changes",
+            testId: "save-changes-btn",
+            stableId: null,
+            contextText: null,
+            mutability: "mutable",
+            widgetType: "native",
+        };
+        it("accepts a fully-populated targetElement", () => {
+            expect(targetElementSchema.safeParse(validTarget).success).toBe(true);
+        });
+        it("accepts a minimal targetElement (only required fields)", () => {
+            const result = targetElementSchema.safeParse({
+                role: "heading",
+                accessibleName: "Notifications",
+                testId: null,
+                stableId: null,
+                contextText: null,
+            });
+            expect(result.success).toBe(true);
+        });
+        it("accepts contextText as a string array (repeating-row case)", () => {
+            const result = targetElementSchema.safeParse({
+                ...validTarget,
+                contextText: ["customer@example.com", "$129.99", "Pending"],
+            });
+            expect(result.success).toBe(true);
+        });
+        it("rejects targetElement missing accessibleName", () => {
+            const { accessibleName, ...withoutName } = validTarget;
+            const result = targetElementSchema.safeParse(withoutName);
+            expect(result.success).toBe(false);
+        });
+        it("rejects targetElement missing role", () => {
+            const { role, ...withoutRole } = validTarget;
+            const result = targetElementSchema.safeParse(withoutRole);
+            expect(result.success).toBe(false);
+        });
+        it("rejects an invalid mutability enum value", () => {
+            const result = targetElementSchema.safeParse({ ...validTarget, mutability: "sometimes" });
+            expect(result.success).toBe(false);
+        });
+        it("rejects an invalid widgetType enum value", () => {
+            const result = targetElementSchema.safeParse({ ...validTarget, widgetType: "fancy" });
+            expect(result.success).toBe(false);
+        });
+    });
+    describe("pageContextSchema (UI recommendation grounding)", () => {
+        it("accepts pageContext with both url and pageHash", () => {
+            const result = pageContextSchema.safeParse({
+                url: "http://localhost:5173/orders/1",
+                pageHash: "10:434266447",
+            });
+            expect(result.success).toBe(true);
+        });
+        it("accepts pageContext without pageHash (optional)", () => {
+            const result = pageContextSchema.safeParse({ url: "http://localhost:5173/orders/1" });
+            expect(result.success).toBe(true);
+        });
+        it("rejects pageContext missing url", () => {
+            const result = pageContextSchema.safeParse({ pageHash: "10:abc" });
+            expect(result.success).toBe(false);
+        });
+    });
+    describe("newTestSchema with grounding fields (UI recommendation grounding)", () => {
+        const validTarget = {
+            role: "button",
+            accessibleName: "Save changes",
+            testId: "save-changes-btn",
+            stableId: null,
+            contextText: null,
+        };
+        const validPage = {
+            url: "http://localhost:5173/orders/1",
+            pageHash: "10:434266447",
+        };
+        const baseUITest = {
+            testId: "ui-edit-order-discount-validation",
+            testType: TestType.UI,
+            category: "business_rule",
+            endpoint: "PATCH /api/v1/orders/{id}",
+            fileName: "edit_order_discount.spec.ts",
+            description: "Navigates to the Edit Order form, enters a discount > 100, and asserts that the validation error appears and the Save button is disabled.",
+            reasoning: "Verifies the **Save changes** button (testid `save-changes-btn`) on the Edit Order form shows the validation error when discount > 100.",
+        };
+        it("accepts a UI test with single-element targetElements + pageContext", () => {
+            const result = newTestSchema.safeParse({
+                ...baseUITest,
+                targetElements: [validTarget],
+                pageContext: validPage,
+            });
+            expect(result.success).toBe(true);
+        });
+        it("accepts a UI test with multi-element targetElements (render-state test)", () => {
+            const result = newTestSchema.safeParse({
+                ...baseUITest,
+                targetElements: [
+                    {
+                        role: "heading",
+                        accessibleName: "Edit Order",
+                        testId: "edit-order-heading",
+                        stableId: null,
+                        contextText: null,
+                    },
+                    {
+                        role: "spinbutton",
+                        accessibleName: "Discount (%)",
+                        testId: "edit-order-input-discount",
+                        stableId: null,
+                        contextText: null,
+                    },
+                ],
+                pageContext: validPage,
+            });
+            expect(result.success).toBe(true);
+        });
+        it("rejects a UI test without targetElements (required for UI grounding)", () => {
+            const result = newTestSchema.safeParse(baseUITest);
+            expect(result.success).toBe(false);
+            expect(JSON.stringify(result.error?.issues)).toContain("targetElements is required for testType: 'ui'");
+        });
+        it("accepts a UI test with targetElements: null (fallback case)", () => {
+            const result = newTestSchema.safeParse({
+                ...baseUITest,
+                targetElements: null,
+                description: "[no-blueprint-data] Navigates to Edit Order form and checks discount validation error.",
+                reasoning: "[no-blueprint-data] Verifies the discount validation error appears on the Edit Order form when discount > 100.",
+            });
+            expect(result.success).toBe(true);
+        });
+        it("rejects a contract test that includes targetElements (UI-only)", () => {
+            const result = newTestSchema.safeParse({
+                testId: "contract-orders-patch",
+                testType: TestType.CONTRACT,
+                category: "business_rule",
+                endpoint: "PATCH /api/v1/orders/{id}",
+                fileName: "orders_patch_contract.py",
+                reasoning: "Validates request shape and 200/422 status codes",
+                targetElements: [validTarget],
+            });
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error.issues.some((i) => i.path.includes("targetElements"))).toBe(true);
+            }
+        });
+        it("rejects an integration test that includes pageContext (UI-only)", () => {
+            const result = newTestSchema.safeParse({
+                testId: "integration-orders",
+                testType: TestType.INTEGRATION,
+                category: "business_rule",
+                endpoint: "POST /api/v1/orders",
+                fileName: "orders_integration.py",
+                reasoning: "Multi-step order lifecycle",
+                pageContext: validPage,
+            });
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error.issues.some((i) => i.path.includes("pageContext"))).toBe(true);
+            }
+        });
+    });
+    describe("additionalRecommendationSchema with grounding fields (UI recommendation grounding)", () => {
+        const validTarget = {
+            role: "button",
+            accessibleName: "Save changes",
+            testId: "save-changes-btn",
+            stableId: null,
+            contextText: null,
+        };
+        const validPage = { url: "http://localhost:5173/orders/1" };
+        it("accepts a UI rec with targetElements + pageContext", () => {
+            const result = additionalRecommendationSchema.safeParse({
+                testId: "ui-edit-order-discount-validation",
+                testType: TestType.UI,
+                category: "business_rule",
+                steps: [{ description: "Open Edit Order, type 150 in discount, click Save" }],
+                description: "Verify discount > 100 shows validation error",
+                priority: "medium",
+                reasoning: "Verify that the **Save changes** button (testid `save-changes-btn`) on the Edit Order form shows the validation error when discount > 100.",
+                targetElements: [validTarget],
+                pageContext: validPage,
+            });
+            expect(result.success).toBe(true);
+        });
+        it("rejects a non-UI rec that includes targetElements", () => {
+            const result = additionalRecommendationSchema.safeParse({
+                testId: "integration-orders-patch",
+                testType: TestType.INTEGRATION,
+                category: "business_rule",
+                steps: [{ method: "PATCH", path: "/api/v1/orders/1", description: "Patch order" }],
+                description: "Verifies PATCH workflow",
+                priority: "high",
+                reasoning: "Catches mutation bugs",
+                targetElements: [validTarget],
+            });
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error.issues.some((i) => i.path.includes("targetElements"))).toBe(true);
+            }
+        });
+    });
     describe("analytics metrics", () => {
         beforeEach(() => {
             pushMCPToolEventMock.mockClear();

package/build/tools/test-management/actionsTool.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Compute a suggested new filename when an endpoint is renamed.
+ */
+export declare function computeRenamedTestFile(testFile: string, renames: Array<{
+    oldPath: string;
+    newPath: string;
+    method: string;
+}>): string | null;
+export declare function registerActionsTool(server: McpServer): void;

package/build/tools/test-management/analyzeChangesTool.d.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CandidateUiPage } from "../../utils/uiPageEnumerator.js";
+import { TraceFile } from "../../types/RepositoryAnalysis.js";
+import { ScannedEndpoint } from "../../utils/repoScanner.js";
+import { TraceParseResult } from "../../utils/trace-parser.js";
+/** Exported for testing: maps a parsed trace result to a TraceFile. */
+export declare function buildTraceFileEntry(tracePath: string, result: TraceParseResult): TraceFile;
+export declare function isSecurityRelevantDiff(diffContent: string): boolean;
+export declare function filterEndpointsBySpec(scannedEndpoints: ScannedEndpoint[], specPaths: Set<string>, specPathItems: Record<string, any>, diffChangedPaths: Set<string>): ScannedEndpoint[];
+export declare function isGraphQLFile(filePath: string, repositoryPath: string): Promise<boolean>;
+export declare function filterUnsupportedGraphQLEndpoints(endpoints: ScannedEndpoint[], repositoryPath: string): Promise<ScannedEndpoint[]>;
+export declare const analyzeChangesInputSchema: {
+    repositoryPath: z.ZodString;
+    scope: z.ZodOptional<z.ZodDefault<z.ZodEnum<["full_repo", "branch_diff"]>>>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    testDirectory: z.ZodOptional<z.ZodString>;
+    topN: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    maxGenerate: z.ZodOptional<z.ZodNumber>;
+    prNumber: z.ZodOptional<z.ZodNumber>;
+    stateOutputFile: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    testsRepoDir: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+};
+export declare const NO_UI_INSTRUCTIONS = "No UI changes detected \u2014 no blueprint capture needed.";
+export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (workspace baseUrl missing or no router files matched). UI recommendations will be source-grounded only.";
+export declare function buildCaptureInstructions(pages: CandidateUiPage[]): string;
+export declare function registerAnalyzeChangesTool(server: McpServer): void;

package/build/tools/test-management/analyzeChangesTool.js

@@ -350,6 +350,34 @@ export const analyzeChangesInputSchema = {
         .optional()
         .describe("Absolute path to a separate test repository clone. When set, existing test discovery scans this directory instead of repositoryPath. Used in cross-repo test delivery mode where tests live in a separate repo."),
 };
+// ── UI blueprint-capture instructions ──
+// Moved here from the former skyramp_ui_analyze_changes pre-flight tool. These
+// strings + buildCaptureInstructions are appended to the tool output so the
+// agent captures browser_blueprints on the candidate UI pages after this call.
+// The captures stay in its tool-result history and serve as element vocabulary
+// for UI recommendation reasoning (enforced at submit time by the Blueprint
+// Citation Invariant in the testbot prompt).
+export const NO_UI_INSTRUCTIONS = `No UI changes detected — no blueprint capture needed.`;
+export const NO_RESOLVABLE_URLS_INSTRUCTIONS = `Frontend changes detected but no candidate URLs could be resolved (workspace baseUrl missing or no router files matched). UI recommendations will be source-grounded only.`;
+export function buildCaptureInstructions(pages) {
+    const pagesYaml = pages
+        .map((p, i) => `  ${i + 1}. ${p.url}  (sourcedFrom: ${p.sourcedFrom.join(", ") || "(none)"}, strategy: ${p.strategy})`)
+        .join("\n");
+    return `Frontend changes detected. **Before writing any UI recommendation \`reasoning\`, capture blueprints on the candidate UI pages below.** Those captures stay in your tool-result history and serve as element vocabulary — the recommendation catalog further down gives you the authoring rules; you bring the observed elements.
+
+**Candidate URLs:**
+${pagesYaml}
+
+**For each candidate URL:**
+  - \`browser_navigate\` to the URL
+  - \`browser_blueprint\` to capture the page
+
+You don't need to thread the blueprints back into a tool call — they're in your context once captured.
+
+If a candidate URL 404s or redirects unexpectedly, navigate from the workspace baseUrl and explore (admin apps mount routes under base prefixes the source extraction can't see). If the page rendered but lacks the changed feature (gated UI: modal, dropdown, accordion), do NOT iterate further during this step — UI recs will fall back to source-grounded prose for those, and the agent's later trace recording (Task 2) will navigate into the gate via capture-act-capture.
+
+If \`browser_blueprint\` fails on every candidate URL (app unreachable, all 404s), proceed and log an \`issuesFound\` info entry. Recommendations will be source-grounded; non-UI work is unaffected.`;
+}
 export function registerAnalyzeChangesTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
@@ -1136,9 +1164,9 @@ export function registerAnalyzeChangesTool(server) {
             //
             // candidateUiPages is enumerated programmatically via the strategy
             // ladder in uiPageEnumerator (framework route grep, source-grounded
-            // routes, root fallback). The same enumeration powers the
-            // skyramp_ui_analyze_changes pre-flight tool that the testbot prompt
-            // calls before this tool, so both code paths see the same candidates.
+            // routes, root fallback). The agent uses these to capture
+            // browser_blueprints — see uiInstructions below, which this tool returns
+            // so the agent captures element vocabulary for UI rec reasoning.
             const uiContext = await (async () => {
                 const changedFiles = classifiedEndpoints?.changedFiles ?? [];
                 if (changedFiles.length === 0)
@@ -1149,9 +1177,8 @@ export function registerAnalyzeChangesTool(server) {
                 // enumeration in.
                 // Compute hasFlutterSdkDep once and pass it through so .dart files
                 // in a Flutter project are recognised as frontend. See Confluence
-                // "Flutter support in Testbot" — this is the second budget-driving
-                // call site that must thread the flag (the other is
-                // uiAnalyzeChangesTool). Both must agree to avoid silent divergence.
+                // "Flutter support in Testbot" — this is the budget-driving call site
+                // that must thread the flag so a Flutter PR enters the UI pipeline.
                 const flutterSdk = hasFlutterSdkDep(params.repositoryPath);
                 const frontendFiles = changedFiles.filter((f) => isFrontendFile(f, { hasFlutterSdkDep: flutterSdk }) && !isTestFile(f));
                 if (frontendFiles.length === 0)
@@ -1162,6 +1189,16 @@ export function registerAnalyzeChangesTool(server) {
                     candidateUiPages,
                 };
             })();
+            // Derive the UI blueprint-capture instructions the agent acts on after
+            // this call. Mirrors the branching of the former skyramp_ui_analyze_changes
+            // pre-flight tool, now folded in here so the agent makes one analysis call
+            // instead of two. The captures stay in the agent's tool-result history and
+            // serve as element vocabulary when it writes UI recommendation reasoning.
+            const uiInstructions = !uiContext || uiContext.changedFrontendFiles.length === 0
+                ? NO_UI_INSTRUCTIONS
+                : uiContext.candidateUiPages.length === 0
+                    ? NO_RESOLVABLE_URLS_INSTRUCTIONS
+                    : buildCaptureInstructions(uiContext.candidateUiPages);
             const unifiedState = {
                 existingTests,
                 newEndpoints: newEndpointsForDrafting,
@@ -1348,7 +1385,7 @@ export function registerAnalyzeChangesTool(server) {
                 content: [
                     {
                         type: "text",
-                        text: `\`\`\`json\n${structuredSummary}\n\`\`\`\n\n${outputText}\n\n---\n\n## Pre-built Test Catalog — Fill in placeholders from source code, then display verbatim\n⚠️ Do NOT reformat, rename sections, or generate a new catalog. Replace \`<…from source>\` values, then show this output exactly as-is, grouped by test type.\n\n${recommendationPrompt}`,
+                        text: `\`\`\`json\n${structuredSummary}\n\`\`\`\n\n## UI Blueprint Capture — do this BEFORE writing UI recommendation reasoning\n${uiInstructions}\n\n${outputText}\n\n---\n\n## Pre-built Test Catalog — Fill in placeholders from source code, then display verbatim\n⚠️ Do NOT reformat, rename sections, or generate a new catalog. Replace \`<…from source>\` values, then show this output exactly as-is, grouped by test type.\n\n${recommendationPrompt}`,
                     },
                 ],
                 isError: false,

package/build/tools/test-management/analyzeChangesTool.test.d.ts

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

package/build/tools/test-management/analyzeChangesTool.test.js

@@ -1,70 +1,91 @@
-// Mock all heavy dependencies so the module can be loaded in isolation
-jest.mock("@skyramp/skyramp", () => ({}));
-jest.mock("simple-git", () => ({ simpleGit: jest.fn() }));
-jest.mock("../../services/AnalyticsService.js", () => ({
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
+import { z } from "zod";
+// Mock all heavy dependencies so the module can be loaded in isolation.
+// Under native ESM, jest.mock is not hoisted — every mock the subject's import
+// graph touches must use unstable_mockModule before the dynamic import below.
+jest.unstable_mockModule("simple-git", () => ({ simpleGit: jest.fn() }));
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
     AnalyticsService: { pushMCPToolEvent: jest.fn() },
 }));
-jest.mock("../../prompts/test-recommendation/test-recommendation-prompt.js", () => ({
+jest.unstable_mockModule("../../prompts/test-recommendation/test-recommendation-prompt.js", () => ({
     buildRecommendationPrompt: jest.fn(),
 }));
-jest.mock("../../prompts/test-recommendation/recommendationSections.js", () => ({
+jest.unstable_mockModule("../../prompts/test-recommendation/recommendationSections.js", () => ({
     MAX_RECOMMENDATIONS: 10,
     MAX_TESTS_TO_GENERATE: 3,
 }));
-jest.mock("../../prompts/test-recommendation/analysisOutputPrompt.js", () => ({
+jest.unstable_mockModule("../../prompts/test-recommendation/analysisOutputPrompt.js", () => ({
     buildAnalysisOutputText: jest.fn(),
 }));
-jest.mock("../../services/TestDiscoveryService.js", () => ({
+jest.unstable_mockModule("../../services/TestDiscoveryService.js", () => ({
     TestDiscoveryService: jest.fn(),
 }));
-jest.mock("../../utils/branchDiff.js", () => ({
+jest.unstable_mockModule("../../utils/branchDiff.js", () => ({
     computeBranchDiff: jest.fn(),
 }));
-jest.mock("../../utils/routeParsers.js", () => ({
+jest.unstable_mockModule("../../utils/routeParsers.js", () => ({
     classifyEndpointsByChangedFiles: jest.fn(),
     extractResourceFromPath: jest.fn(),
     parseFileEndpoints: jest.fn(),
 }));
-jest.mock("../../utils/repoScanner.js", () => ({
+jest.unstable_mockModule("../../utils/repoScanner.js", () => ({
     scanAllRepoEndpoints: jest.fn(),
     scanRelatedEndpoints: jest.fn(),
     grepRouterMountingContext: jest.fn(),
     findCandidateRouteFiles: jest.fn(),
 }));
-jest.mock("../../utils/projectMetadata.js", () => ({
+jest.unstable_mockModule("../../utils/projectMetadata.js", () => ({
     detectProjectMetadata: jest.fn(),
 }));
-jest.mock("../../utils/scenarioDrafting.js", () => ({
+jest.unstable_mockModule("../../utils/scenarioDrafting.js", () => ({
     draftScenariosFromEndpoints: jest.fn(),
 }));
-jest.mock("../../utils/trace-parser.js", () => ({
+jest.unstable_mockModule("../../utils/trace-parser.js", () => ({
     parseTraceFile: jest.fn(),
     discoverTraceFiles: jest.fn(),
     discoverPlaywrightZips: jest.fn(),
 }));
-jest.mock("../../utils/pr-comment-parser.js", () => ({
+jest.unstable_mockModule("../../utils/pr-comment-parser.js", () => ({
     parsePRComments: jest.fn(),
 }));
-jest.mock("../../utils/AnalysisStateManager.js", () => ({
+jest.unstable_mockModule("../../utils/AnalysisStateManager.js", () => ({
     StateManager: jest.fn().mockImplementation(() => ({
         writeData: jest.fn(),
     })),
     registerSession: jest.fn(),
     storeSessionData: jest.fn(),
+    setTestsRepoDir: jest.fn(),
 }));
-jest.mock("../../utils/workspaceAuth.js", () => ({
+// Keep every real workspaceAuth export the subject's import graph needs
+// (readWorkspaceConfigRaw, getDefaultAuthHeader, WorkspaceAuthType, …) and
+// override only parseWorkspaceAuthType. requireActual can't load ESM
+// synchronously, so import the real module first (mock is not hoisted).
+const realWorkspaceAuth = await import("../../utils/workspaceAuth.js");
+jest.unstable_mockModule("../../utils/workspaceAuth.js", () => ({
+    ...realWorkspaceAuth,
     parseWorkspaceAuthType: jest.fn(),
 }));
-jest.mock("../../utils/logger.js", () => ({
+jest.unstable_mockModule("../../utils/logger.js", () => ({
     logger: { info: jest.fn(), debug: jest.fn(), error: jest.fn(), warn: jest.fn(), warning: jest.fn() },
 }));
-jest.mock("@modelcontextprotocol/sdk/server/mcp.js", () => ({
+jest.unstable_mockModule("@modelcontextprotocol/sdk/server/mcp.js", () => ({
     McpServer: jest.fn(),
 }));
-jest.mock("@modelcontextprotocol/sdk/types.js", () => ({}));
-jest.mock("@modelcontextprotocol/sdk/shared/protocol.js", () => ({}));
-import { z } from "zod";
-import { analyzeChangesInputSchema, isSecurityRelevantDiff } from "./analyzeChangesTool.js";
+jest.unstable_mockModule("@modelcontextprotocol/sdk/types.js", () => ({}));
+jest.unstable_mockModule("@modelcontextprotocol/sdk/shared/protocol.js", () => ({}));
+// All subject + mocked-module imports must be dynamic and live AFTER the
+// unstable_mockModule calls above — static imports hoist above the mocks under
+// native ESM, loading the real (heavy) modules unmocked.
+const { analyzeChangesInputSchema, isSecurityRelevantDiff, filterEndpointsBySpec, filterUnsupportedGraphQLEndpoints, isGraphQLFile, registerAnalyzeChangesTool, buildTraceFileEntry, buildCaptureInstructions, NO_UI_INSTRUCTIONS, NO_RESOLVABLE_URLS_INSTRUCTIONS, } = await import("./analyzeChangesTool.js");
+const { computeBranchDiff } = await import("../../utils/branchDiff.js");
+const { classifyEndpointsByChangedFiles } = await import("../../utils/routeParsers.js");
+const { scanRelatedEndpoints, scanAllRepoEndpoints } = await import("../../utils/repoScanner.js");
+const { StateManager } = await import("../../utils/AnalysisStateManager.js");
+const os = await import("os");
+const path = await import("path");
+const fsSync = await import("fs");
+const fsModule = fsSync;
 const schema = z.object(analyzeChangesInputSchema);
 describe("isSecurityRelevantDiff", () => {
     it("matches auth-specific middleware and admin-key signals", () => {
@@ -101,11 +122,9 @@ describe("analyzeChangesInputSchema — stateOutputFile validation", () => {
     });
 });
 describe("automatic old files cleanup", () => {
-    let StateManager;
     let cleanupOldFilesSpy;
     beforeEach(() => {
         jest.clearAllMocks();
-        StateManager = require("../../utils/AnalysisStateManager.js").StateManager;
         cleanupOldFilesSpy = jest.fn().mockResolvedValue(0);
         StateManager.cleanupOldFiles = cleanupOldFilesSpy;
     });
@@ -139,7 +158,6 @@ describe("automatic old files cleanup", () => {
 // ─────────────────────────────────────────────────────────────────────────────
 // filterEndpointsBySpec — spec filtering + merge logic (Step 4c / 4c-merge)
 // ─────────────────────────────────────────────────────────────────────────────
-import { filterEndpointsBySpec } from "./analyzeChangesTool.js";
 describe("filterEndpointsBySpec", () => {
     const makeEp = (path, methods = ["GET"]) => ({ path, methods, sourceFile: "" });
     it("removes scanned endpoints that are not in the spec and not diff-changed", () => {
@@ -224,10 +242,6 @@ describe("filterEndpointsBySpec", () => {
 // ─────────────────────────────────────────────────────────────────────────────
 // isGraphQLFile — unit tests
 // ─────────────────────────────────────────────────────────────────────────────
-import { filterUnsupportedGraphQLEndpoints, isGraphQLFile } from "./analyzeChangesTool.js";
-import * as os from "os";
-import * as path from "path";
-import * as fsSync from "fs";
 describe("isGraphQLFile", () => {
     const tmpDir = os.tmpdir();
     it("returns true for .graphql extension without reading content", async () => {
@@ -303,14 +317,6 @@ describe("filterUnsupportedGraphQLEndpoints", () => {
         readSpy.mockRestore();
     });
 });
-// ─────────────────────────────────────────────────────────────────────────────
-// analyzeChangesTool handler — GraphQL-only early return (handler-level)
-// ─────────────────────────────────────────────────────────────────────────────
-import { registerAnalyzeChangesTool, buildTraceFileEntry } from "./analyzeChangesTool.js";
-import { computeBranchDiff } from "../../utils/branchDiff.js";
-import { classifyEndpointsByChangedFiles } from "../../utils/routeParsers.js";
-import { scanRelatedEndpoints } from "../../utils/repoScanner.js";
-import * as fsModule from "fs";
 /** Register the tool against a minimal mock server and return the captured handler.
  *  The handler takes (params, extra) — extra is pre-filled with a no-op sendNotification. */
 function captureAnalyzeHandler() {
@@ -399,7 +405,6 @@ describe("analyzeChangesTool handler — GraphQL-only early return", () => {
         readSpy.mockRestore();
     });
     it("does NOT early-return when scope is full_repo (only fires for PR diffs)", async () => {
-        const { scanAllRepoEndpoints } = require("../../utils/repoScanner.js");
         scanAllRepoEndpoints.mockReturnValue([]);
         const handler = captureAnalyzeHandler();
         const result = await handler({ ...baseParams, scope: "full_repo" });
@@ -437,3 +442,35 @@ describe("buildTraceFileEntry", () => {
         expect(entry.userFlows).toEqual([]);
     });
 });
+describe("UI blueprint-capture instructions (merged from ui_analyze_changes)", () => {
+    it("NO_UI_INSTRUCTIONS signals no capture is needed and references no follow-up tool", () => {
+        expect(NO_UI_INSTRUCTIONS).toMatch(/no blueprint capture needed/i);
+        // The former pre-flight tool told the agent to "proceed to
+        // skyramp_analyze_changes" — that's redundant now we're inside it.
+        expect(NO_UI_INSTRUCTIONS).not.toMatch(/skyramp_analyze_changes/);
+    });
+    it("NO_RESOLVABLE_URLS_INSTRUCTIONS falls back to source-grounded", () => {
+        expect(NO_RESOLVABLE_URLS_INSTRUCTIONS).toMatch(/source-grounded/i);
+    });
+    it("buildCaptureInstructions numbers each candidate URL with its provenance", () => {
+        const pages = [
+            { url: "http://localhost:3000/notifications", sourcedFrom: ["app/routes.tsx"], strategy: "framework-route-grep" },
+            { url: "http://localhost:3000/settings", sourcedFrom: [], strategy: "root-fallback" },
+        ];
+        const text = buildCaptureInstructions(pages);
+        expect(text).toContain("1. http://localhost:3000/notifications");
+        expect(text).toContain("2. http://localhost:3000/settings");
+        expect(text).toContain("sourcedFrom: app/routes.tsx");
+        expect(text).toContain("sourcedFrom: (none)");
+        expect(text).toContain("browser_navigate");
+        expect(text).toContain("browser_blueprint");
+    });
+    it("buildCaptureInstructions does NOT emit a login step (uiCredentials dropped)", () => {
+        const pages = [
+            { url: "http://localhost:3000/x", sourcedFrom: [], strategy: "root-fallback" },
+        ];
+        const text = buildCaptureInstructions(pages);
+        expect(text).not.toMatch(/log in first/i);
+        expect(text).not.toMatch(/ui-credentials/i);
+    });
+});

package/build/tools/test-management/analyzeTestHealthTool.d.ts

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

package/build/tools/test-management/index.d.ts

@@ -0,0 +1,3 @@
+export { registerAnalyzeChangesTool } from "./analyzeChangesTool.js";
+export { registerAnalyzeTestHealthTool } from "./analyzeTestHealthTool.js";
+export { registerActionsTool } from "./actionsTool.js";

package/build/tools/test-management/index.js

@@ -1,4 +1,3 @@
 export { registerAnalyzeChangesTool } from "./analyzeChangesTool.js";
-export { registerUiAnalyzeChangesTool } from "./uiAnalyzeChangesTool.js";
 export { registerAnalyzeTestHealthTool } from "./analyzeTestHealthTool.js";
 export { registerActionsTool } from "./actionsTool.js";

package/build/tools/trace/resolveSaveStoragePath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve the user-supplied `playwrightSaveStoragePath` against `outputDir`:
+ *   - A bare filename (no separators, not absolute) is joined with `outputDir`.
+ *   - Anything else (absolute path, or a relative path containing separators)
+ *     is returned unchanged.
+ */
+export declare function resolveSaveStoragePath(input: string, outputDir: string | undefined): string;

package/build/tools/trace/resolveSaveStoragePath.test.d.ts

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

package/build/tools/trace/resolveSessionPaths.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SKYR-3321: pick which Playwright session-storage paths to pass to the
+ * recorder based on a single, explicit `sessionMode` signal.
+ *
+ * The original start-trace tool had an asymmetric default: it always
+ * resolved a save path (so every recording overwrote the session file on
+ * stop) but never auto-loaded. That was the root cause of the "load →
+ * 31-min idle → stop → session destroyed" regression that fills SKYR-3321.
+ * The mode vocabulary replaced that with the three real intents — capture a
+ * new session, reuse an existing one, or ignore session storage entirely.
+ *
+ * SKYR-3793: `auto` must never store credentials the user did not ask for.
+ * It loads an existing session if one is present in `outputDir` (reuse), but
+ * when none exists it does NOTHING — it does not auto-capture. Storing is
+ * opt-in only: `sessionMode=capture` or an explicit `saveOverride`.
+ *
+ * Both `loadOverride` and `saveOverride` are plain optional strings: when
+ * the LLM omits them they arrive as `undefined`, which means "use the
+ * mode's default". No sentinel values; explicit overrides win when given.
+ */
+export type SessionMode = "auto" | "capture" | "reuse" | "ignore";
+export interface ResolvedSessionPaths {
+    loadPath?: string;
+    savePath?: string;
+}
+export interface ResolveSessionPathsArgs {
+    mode: SessionMode;
+    /** Raw value of `playwrightStoragePath` (LLM may omit). */
+    loadOverride: string | undefined;
+    /** Raw value of `playwrightSaveStoragePath` (LLM may omit). */
+    saveOverride: string | undefined;
+    /** Workspace directory used to resolve relative paths and locate the default session file. */
+    outputDir: string;
+    /**
+     * Whether `<outputDir>/<SESSION_STORAGE_FILENAME>` exists on disk. Injected
+     * rather than read in-function so the resolver stays pure and testable.
+     */
+    sessionExists: boolean;
+}
+export declare function resolveSessionPaths(args: ResolveSessionPathsArgs): ResolvedSessionPaths;

package/build/tools/trace/resolveSessionPaths.test.d.ts

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