@skyramp/mcp 0.2.6 → 0.2.150-rc.mntnc

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/actionsTool.js

@@ -6,6 +6,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { toolError } from "../../utils/utils.js";
+import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRegenerateStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
 /**
  * Compute a suggested new filename when an endpoint is renamed.
@@ -365,6 +366,15 @@ export function registerActionsTool(server) {
                 });
                 llmInstructionsObj.regenerate_strategy = buildRegenerateStrategy();
             }
+            // Stage UPDATE and REGENERATE target paths so testbot's re-stage step
+            // commits the agent's edits even when files are outside testDirectory.
+            const stagedPaths = [
+                ...updateRecommendations.map((r) => r.testFile),
+                ...regenerateRecommendations.map((r) => r.testFile),
+            ];
+            for (const p of stagedPaths) {
+                await stageGeneratedPaths(p).catch((e) => logger.warning(`Failed to stage maintained file ${p}: ${e.message}`));
+            }
             const llmInstructions = JSON.stringify(llmInstructionsObj, null, 2);
             const contentBlocks = [
                 {

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

@@ -0,0 +1,26 @@
+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>;
+    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

@@ -24,6 +24,32 @@ import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analy
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
 import { parsePRComments } from "../../utils/pr-comment-parser.js";
+// Generic module names that appear as imports in virtually every router file.
+// Matching against these would extract ALL prefix= tokens from mount files,
+// flooding changedResources with unrelated resources.
+const GENERIC_MODULE_NAMES = new Set([
+    "models", "utils", "helpers", "schemas", "types", "constants",
+    "config", "settings", "exceptions", "errors", "base", "common",
+    "app", "main", "index", "server", "init", "deps", "dependencies",
+]);
+function resolveMountPrefixTokens(mountFileContents, changedFiles) {
+    const tokens = changedFiles.flatMap((file) => {
+        const mod = path.basename(file).replace(/\.[^.]+$/, "").toLowerCase();
+        if (GENERIC_MODULE_NAMES.has(mod))
+            return [];
+        const modRe = new RegExp(`\\b${mod.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+        return mountFileContents.flatMap((content) => {
+            if (!modRe.test(content.toLowerCase()))
+                return [];
+            const matches = [...content.matchAll(/prefix\s*=\s*["'](\/?[^"']+)/g)];
+            return matches.flatMap((m) => {
+                const token = extractResourceFromPath(m[1]);
+                return token !== "unknown" ? [token] : [];
+            });
+        });
+    });
+    return [...new Set(tokens)];
+}
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
 export function buildTraceFileEntry(tracePath, result) {
     return {
@@ -339,17 +365,40 @@ export const analyzeChangesInputSchema = {
         .number()
         .optional()
         .describe("GitHub PR number. When provided, fetches previous TestBot comments on this PR and skips re-recommending tests already suggested in earlier commits — reduces duplicate recommendations across multiple pushes to the same PR."),
-    stateOutputFile: z
-        .string()
-        .refine((v) => path.isAbsolute(v), { message: "stateOutputFile must be an absolute path" })
-        .optional()
-        .describe("Absolute path where the state file should be written. When provided, overrides the default auto-generated temp path so the caller can locate it without log parsing."),
     testsRepoDir: z
         .string()
         .refine((v) => path.isAbsolute(v), { message: "testsRepoDir must be an absolute path" })
         .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: {
@@ -540,6 +589,30 @@ export function registerAnalyzeChangesTool(server) {
             // testsRepoDir is a cross-repo path override — honour it when set.
             // Otherwise always scan the full repo root.
             const testDir = params.testsRepoDir ?? undefined;
+            const routerMountContext = grepRouterMountingContext(params.repositoryPath);
+            // Read contents once — used for token extraction and LLM prompt injection.
+            const ROUTER_INLINE_LIMIT = 4096;
+            const routerMountContextContents = routerMountContext.map((f) => {
+                try {
+                    const abs = path.isAbsolute(f) ? f : path.join(params.repositoryPath, f);
+                    if (fs.statSync(abs).size > ROUTER_INLINE_LIMIT * 10)
+                        return ""; // skip very large files
+                    return fs.readFileSync(abs, "utf-8");
+                }
+                catch {
+                    return "";
+                }
+            });
+            // Size-capped subset for LLM prompt injection.
+            const ROUTER_INLINE_MAX_FILES = 3;
+            const routerFileContents = routerMountContext
+                .slice(0, ROUTER_INLINE_MAX_FILES)
+                .flatMap((f, i) => {
+                const content = routerMountContextContents[i] ?? "";
+                if (!content || content.length > ROUTER_INLINE_LIMIT)
+                    return [];
+                return [{ file: f, content: content.trimEnd() }];
+            });
             // Compute changedResources from classified endpoints for test discovery filtering.
             // undefined    → full-repo mode (no diff context)
             // []           → PR mode, no endpoints found → skip external tests
@@ -568,14 +641,22 @@ export function registerAnalyzeChangesTool(server) {
                     }
                     else {
                         // All endpoints resolved to "unknown" (e.g. NestJS relative paths) —
-                        // extract resource names from changed file paths instead.
-                        const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
-                            ? classifiedEndpoints.unmatchedFiles
-                            : classifiedEndpoints.changedFiles ?? [];
-                        const fromFiles = candidateFiles
-                            .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
-                            .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                        changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
+                        // first try to extract resource names from router mount prefixes.
+                        const changedSourceFiles = classifiedEndpoints.changedFiles ?? [];
+                        const mountedResources = resolveMountPrefixTokens(routerMountContextContents, changedSourceFiles);
+                        if (mountedResources.length > 0) {
+                            changedResources = mountedResources;
+                        }
+                        else {
+                            // Fall back to extracting resource names from changed file paths.
+                            const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
+                                ? classifiedEndpoints.unmatchedFiles
+                                : classifiedEndpoints.changedFiles ?? [];
+                            const fromFiles = candidateFiles
+                                .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                                .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                            changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
+                        }
                     }
                 }
                 else if (classifiedEndpoints.unmatchedFiles.length > 0) {
@@ -594,7 +675,15 @@ export function registerAnalyzeChangesTool(server) {
                     changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
                 }
                 else {
-                    changedResources = [];
+                    // No endpoints and no unmatched files — the diff touches only non-route
+                    // files (e.g. schema, model, DTO). Extract resource tokens from the
+                    // changed file paths so tests that import the changed symbol are still
+                    // surfaced for drift assessment. Fall back to [] only if extraction
+                    // yields nothing (e.g. a file with a non-resource name like utils.py).
+                    const fromChangedFiles = (classifiedEndpoints.changedFiles ?? [])
+                        .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                        .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                    changedResources = fromChangedFiles.length > 0 ? fromChangedFiles : [];
                 }
             }
             let existingTests = [];
@@ -875,10 +964,15 @@ export function registerAnalyzeChangesTool(server) {
                         sourceFile: m.sourceFile ?? "",
                     })))
                     : [];
+            const removedEndpointsForDrafting = classifiedEndpoints?.removedEndpoints.flatMap((ep) => ep.methods.map((m) => ({
+                method: m,
+                path: ep.path,
+                sourceFile: ep.sourceFile,
+            }))) ?? [];
             const codeInferredScenarios = draftScenariosFromEndpoints(skeletonEndpoints, scenarioDraftSeed, wsAuthType, {
                 changedEndpoints: changedEndpointsForSecurityExpansion,
                 securityRelevantDiff,
-            });
+            }, removedEndpointsForDrafting);
             let allDraftedScenarios = codeInferredScenarios;
             if (traceResult && traceResult.userFlows.length > 0) {
                 const traceScenarios = traceResult.userFlows
@@ -1081,7 +1175,6 @@ export function registerAnalyzeChangesTool(server) {
             // can be persisted to the state file for downstream tools (health, drift).
             // Without them, analyzeTestHealth would work only off the static catalog
             // which has wrong paths for nested resources and unsupported frameworks.
-            const routerMountContext = grepRouterMountingContext(params.repositoryPath);
             const routeLikeUnmatchedFiles = [];
             for (const file of classifiedEndpoints?.unmatchedFiles ?? []) {
                 const routeLike = SOURCE_EXTS.test(file) &&
@@ -1110,25 +1203,6 @@ export function registerAnalyzeChangesTool(server) {
                 diffFilePath = path.join(os.tmpdir(), `skyramp-diff-${sessionId}.diff`);
                 await fs.promises.writeFile(diffFilePath, diffData.diffContent, { encoding: "utf-8", mode: 0o600 });
             }
-            // Read router mount files server-side (size-capped) so the LLM has them
-            // inline and doesn't need an extra read step when no spec is available.
-            const ROUTER_INLINE_LIMIT = 4096; // bytes — skip files larger than ~4 KB
-            const ROUTER_INLINE_MAX_FILES = 3;
-            const routerFileContents = routerMountContext
-                .slice(0, ROUTER_INLINE_MAX_FILES)
-                .flatMap((f) => {
-                try {
-                    const absPath = path.isAbsolute(f) ? f : path.join(params.repositoryPath, f);
-                    const stat = fs.statSync(absPath);
-                    if (stat.size > ROUTER_INLINE_LIMIT)
-                        return [];
-                    const content = fs.readFileSync(absPath, "utf-8").trimEnd();
-                    return [{ file: f, content }];
-                }
-                catch {
-                    return [];
-                }
-            });
             // Compute UI context from the diff's changed files using the shared
             // `isFrontendFile` classifier. Persisting this in the stateFile lets
             // skyramp_analyze_test_health and the recommendation prompt consume the
@@ -1136,9 +1210,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 +1223,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 +1235,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,
@@ -1215,17 +1298,14 @@ export function registerAnalyzeChangesTool(server) {
                     relevantExternalTestPaths,
                 },
             };
-            // Clean up old state files (>24 hours) before creating new one
-            const stateDir = params.stateOutputFile
-                ? path.dirname(path.resolve(params.stateOutputFile))
-                : undefined;
+            // Clean up old state files (>24 hours) before creating new one.
             try {
-                await StateManager.cleanupOldFiles(24, stateDir);
+                await StateManager.cleanupOldFiles(24);
             }
             catch (error) {
                 logger.warning(`Failed to cleanup old state files: ${error.message}`);
             }
-            const stateManager = new StateManager("analysis", sessionId, undefined, params.stateOutputFile);
+            const stateManager = new StateManager("analysis", sessionId);
             await stateManager.writeData(unifiedState, {
                 repositoryPath: params.repositoryPath,
                 step: "analyze_changes",
@@ -1348,7 +1428,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", () => {
@@ -78,68 +99,35 @@ describe("isSecurityRelevantDiff", () => {
         expect(isSecurityRelevantDiff("move compression middleware to server setup")).toBe(false);
     });
 });
-describe("analyzeChangesInputSchema — stateOutputFile validation", () => {
-    it("accepts a valid absolute path", () => {
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "/tmp/analyze-changes-state.json",
-        });
-        expect(result.success).toBe(true);
-    });
-    it("rejects a relative path for stateOutputFile", () => {
-        // stateOutputFile must be absolute so the caller can guarantee the file location.
-        // Relative paths are silently ambiguous and should be rejected.
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "relative/path/state.json",
-        });
-        expect(result.success).toBe(false);
-    });
-    it("accepts absence of stateOutputFile (optional field)", () => {
-        const result = schema.safeParse({ repositoryPath: "/repo" });
-        expect(result.success).toBe(true);
-    });
-});
 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;
     });
-    it("calls cleanupOldFiles with default temp dir when no stateOutputFile provided", async () => {
-        // This test verifies the cleanup call is made without stateDir when using default location
+    it("calls cleanupOldFiles with default temp dir", async () => {
         expect(StateManager.cleanupOldFiles).toBeDefined();
         await StateManager.cleanupOldFiles(24, undefined);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined);
     });
-    it("calls cleanupOldFiles with custom dir when stateOutputFile is provided", async () => {
-        // This test verifies the cleanup call is made with the directory of stateOutputFile
+    it("calls cleanupOldFiles with custom dir", async () => {
         const customPath = "/custom/dir";
         await StateManager.cleanupOldFiles(24, customPath);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, customPath);
     });
-    it("calls cleanupOldFiles with empty stateTypes to restrict to diff files only", async () => {
-        // analyzeTestHealthTool passes [] so state files (skyramp-analysis-*, skyramp-recommendation-*)
-        // are never deleted — the caller still needs args.stateFile for skyramp_actions.
+    it("calls cleanupOldFiles with empty stateTypes", async () => {
         await StateManager.cleanupOldFiles(24, undefined, []);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined, []);
     });
     it("continues execution if cleanup fails", async () => {
-        // Cleanup failures should not crash the analyze flow
         cleanupOldFilesSpy.mockRejectedValue(new Error("permission denied"));
-        await expect(StateManager.cleanupOldFiles(24).catch(() => {
-            // In the real code, this is caught and logged as a warning
-            return Promise.resolve();
-        })).resolves.toBeUndefined();
+        await expect(StateManager.cleanupOldFiles(24).catch(() => Promise.resolve())).resolves.toBeUndefined();
     });
 });
 // ─────────────────────────────────────────────────────────────────────────────
 // 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 +212,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 +287,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 +375,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 +412,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/analyzeTestHealthTool.js

@@ -15,11 +15,11 @@ export function registerAnalyzeTestHealthTool(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow. Optionally execute tests with skyramp_execute_test before calling skyramp_actions to capture beforeStatus.`,
+        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.`,
         inputSchema: {
             stateFile: z
                 .string()
-                .describe("Path to state file from skyramp_analyze_changes. Assessment results exist only in the LLM's reasoning context — this tool does not write back to the stateFile."),
+                .describe("Path to the analyze-changes-state.json file returned by skyramp_analyze_changes (the stateFile field in its output). Do NOT pass summaryOutputFile or testbot-result.txt here."),
         },
         outputSchema: {
             prompt: z.string().describe("LLM drift analysis prompt and assessment instructions."),
@@ -37,7 +37,10 @@ export function registerAnalyzeTestHealthTool(server) {
                 return toolError(`State file is empty or invalid: ${args.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
             }
             if (!repositoryPath || typeof repositoryPath !== "string") {
-                return toolError(`repositoryPath not found in state file metadata. The state file was likely created by an older version — re-run skyramp_analyze_changes to regenerate it.`);
+                return toolError(`repositoryPath not found in state file metadata. The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt. Re-run skyramp_analyze_changes to regenerate it.`);
+            }
+            if (!Array.isArray(stateData.existingTests)) {
+                return toolError(`stateFile does not contain test discovery data (existingTests missing). The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt.`);
             }
             // Skyramp tests: full drift analysis + all actions permitted.
             // Relevant external tests (user-written, relevant to this PR's endpoints): drift analysis