@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -25,7 +25,7 @@ import { TOOL_RESOLVE_SCREEN } from "../../toolNames.js";
 import { logger } from "../../utils/logger.js";
 import { lastKnownBrowserUrl } from "../../playwright/blueprintDigestStore.js";
 import { readWorkspaceServices } from "../../prompts/prompt-utils.js";
-import { createScreenRouteLookup } from "../../utils/screenRoutes.js";
+import { createScreenRouteLookup, } from "../../utils/screenRoutes.js";
 // ── Route patterns ──────────────────────────────────────────────────────────
 /** A pattern segment, in the four spellings the frameworks this run meets use:
  *  TanStack `$id`, React/Vue `:id`, Next `[id]`, OpenAPI-ish `{id}`. Mirrors the
@@ -55,7 +55,9 @@ export function urlPath(raw) {
         return new URL(value).pathname.replace(/\/+$/, "") || "/";
     }
     catch {
-        return value.startsWith("/") ? value.split(/[?#]/)[0].replace(/\/+$/, "") || "/" : "";
+        return value.startsWith("/")
+            ? value.split(/[?#]/)[0].replace(/\/+$/, "") || "/"
+            : "";
     }
 }
 function origin(raw) {
@@ -112,7 +114,9 @@ export function bindFromLocation(location, patterns) {
         if (!best || literals > best.literals)
             best = { pattern, values, literals };
     }
-    return best ? { pattern: best.pattern, values: best.values, source: location.source } : undefined;
+    return best
+        ? { pattern: best.pattern, values: best.values, source: location.source }
+        : undefined;
 }
 /** The pattern with its bound parameters substituted, prefixed by the origin when
  *  one is known. An unbound parameter is left in its own spelling rather than
@@ -198,7 +202,13 @@ export function buildResolveScreenResult(input) {
             "and do not invent one — a plausible wrong id renders an empty page that looks real.");
     }
     lines.push("`mountChain` is the import path from the route file to the changed file: check it rather than trust it.");
-    return { status: "resolved", candidates: resolved, notOn, needs: [...needs], summary: lines.join(" ") };
+    return {
+        status: "resolved",
+        candidates: resolved,
+        notOn,
+        needs: [...needs],
+        summary: lines.join(" "),
+    };
 }
 // ── Workspace default for baseUrl ───────────────────────────────────────────
 /**
@@ -215,7 +225,11 @@ export async function workspaceUiBaseUrl(repositoryPath) {
         const services = (await readWorkspaceServices(repositoryPath));
         const withUrl = services.filter((service) => typeof service?.api?.baseUrl === "string" && service.api.baseUrl);
         const playwright = withUrl.filter((service) => service.framework === "playwright");
-        const chosen = playwright.length === 1 ? playwright[0] : withUrl.length === 1 ? withUrl[0] : undefined;
+        const chosen = playwright.length === 1
+            ? playwright[0]
+            : withUrl.length === 1
+                ? withUrl[0]
+                : undefined;
         return chosen ? origin(chosen.api?.baseUrl) : undefined;
     }
     catch {
@@ -224,7 +238,9 @@ export async function workspaceUiBaseUrl(repositoryPath) {
 }
 // ── Registration ────────────────────────────────────────────────────────────
 const inputSchema = {
-    repositoryPath: z.string().describe("Absolute path to the repository checkout that holds the frontend file."),
+    repositoryPath: z
+        .string()
+        .describe("Absolute path to the repository checkout that holds the frontend file."),
     changedFile: z
         .string()
         .describe("Repository-relative path of the frontend file the test is about — the file the diff changed, " +
@@ -244,14 +260,19 @@ const outputSchema = {
         .array(z.object({
         url: z.string(),
         routePattern: z.string(),
-        params: z.record(z.object({ value: z.string(), from: z.enum(["currentUrl", "blueprint", "unresolved"]) })),
+        params: z.record(z.object({
+            value: z.string(),
+            from: z.enum(["currentUrl", "blueprint", "unresolved"]),
+        })),
         mountChain: z.array(z.string()),
     }))
         .describe("Each route that renders the file, with the import chain from its route file down to the file."),
     notOn: z
         .array(z.string())
         .describe("The route the browser is currently on, when it is not one that renders the file."),
-    needs: z.array(z.string()).describe("Route parameters no known value fills. Read them off the app; never invent one."),
+    needs: z
+        .array(z.string())
+        .describe("Route parameters no known value fills. Read them off the app; never invent one."),
     summary: z.string().describe("The same answer in one paragraph."),
 };
 const DESCRIPTION = "Answer which page of the running app renders a changed frontend file, and give the url to open. " +
@@ -284,6 +305,9 @@ export function registerResolveScreenTool(server) {
             routes: result.candidates.length,
             needs: result.needs.length,
         });
-        return { structuredContent: { ...result }, content: [{ type: "text", text: result.summary }] };
+        return {
+            structuredContent: { ...result },
+            content: [{ type: "text", text: result.summary }],
+        };
     });
 }

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

@@ -0,0 +1,28 @@
+import { type DriftRecommendation, type TestAnalysisResult } from "../../types/TestAnalysis.js";
+/** One catalogued test, narrowed to what the gate reads. */
+export type GateCatalogRow = Pick<TestAnalysisResult, "testFile" | "language" | "source" | "executionBefore">;
+/** One recommendation, narrowed to what the gate reads. */
+export type GateRecommendation = Pick<DriftRecommendation, "testFilePath" | "action" | "reportOnly">;
+export interface TestsOwedBeforeRun {
+    /** Files this call would edit that have no usable pre-edit run. */
+    owed: string[];
+    /** Owed no run because skyramp_execute_test cannot run that language. */
+    exemptLanguage: number;
+}
+/**
+ * The tests this call edits that have no `phase: "before"` result.
+ *
+ * Only UPDATE reaches here. An external REGENERATE or DELETE is turned into a
+ * report-only recommendation before the gate runs, and a report-only row edits
+ * nothing, so neither owes a run.
+ *
+ * A recommendation with no catalog row is deliberately NOT gated. `skyramp_actions`
+ * accepts a real test file discovery missed and records a verdict for it rather than
+ * dropping it (SKYR-3906/SKYR-3938, the B1 test). Refusing it here for want of a
+ * before-run would reverse that: it has no catalog row, so it never has a recorded
+ * run, and the gate would refuse it on every call. Gating it is a change to B1's
+ * contract, not to this one.
+ */
+export declare function testsOwedBeforeRun(recommendations: readonly GateRecommendation[], catalogByFile: ReadonlyMap<string, GateCatalogRow>): TestsOwedBeforeRun;
+/** Every file, quoted, one list — the agent must run all of them. */
+export declare function formatOwedFiles(owed: readonly string[]): string;

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

@@ -0,0 +1,53 @@
+import { DriftAction, TestSource, } from "../../types/TestAnalysis.js";
+import { ProgrammingLanguage } from "../../types/TestTypes.js";
+import { TestExecutionStatus } from "../../types/TestExecution.js";
+/**
+ * The tests this call edits that have no `phase: "before"` result.
+ *
+ * Only UPDATE reaches here. An external REGENERATE or DELETE is turned into a
+ * report-only recommendation before the gate runs, and a report-only row edits
+ * nothing, so neither owes a run.
+ *
+ * A recommendation with no catalog row is deliberately NOT gated. `skyramp_actions`
+ * accepts a real test file discovery missed and records a verdict for it rather than
+ * dropping it (SKYR-3906/SKYR-3938, the B1 test). Refusing it here for want of a
+ * before-run would reverse that: it has no catalog row, so it never has a recorded
+ * run, and the gate would refuse it on every call. Gating it is a change to B1's
+ * contract, not to this one.
+ */
+export function testsOwedBeforeRun(recommendations, catalogByFile) {
+    const runnableLanguages = Object.values(ProgrammingLanguage);
+    let exemptLanguage = 0;
+    const owed = recommendations
+        .filter((rec) => {
+        if (rec.reportOnly)
+            return false;
+        if (rec.action !== DriftAction.Update)
+            return false;
+        const row = catalogByFile.get(rec.testFilePath);
+        if (!row || row.source !== TestSource.External)
+            return false;
+        // Unknown is the placeholder skyramp_execute_test reserves before it
+        // spawns the runner. A run that died there left no evidence, so the
+        // placeholder must not read as a recorded baseline.
+        if (row.executionBefore &&
+            row.executionBefore.status !== TestExecutionStatus.Unknown)
+            return false;
+        // A language skyramp_execute_test does not accept can never record a
+        // before-run. No name check follows it: discovery admits an external file
+        // only when its name identifies a test or it is a colocated snapshot, and
+        // a .snap is exempt by language here, so a second rule would be a copy
+        // that can go out of sync.
+        if (!runnableLanguages.includes(row.language)) {
+            exemptLanguage++;
+            return false;
+        }
+        return true;
+    })
+        .map((rec) => rec.testFilePath);
+    return { owed, exemptLanguage };
+}
+/** Every file, quoted, one list — the agent must run all of them. */
+export function formatOwedFiles(owed) {
+    return owed.map((f) => `"${f}"`).join(", ");
+}

package/build/tools/trace/startTraceCollectionTool.js

@@ -251,7 +251,9 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 prompt: params.prompt,
                 playwright: params.playwright.toString(),
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/trace/stopTraceCollectionTool.js

@@ -51,6 +51,10 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             prompt: params.prompt,
         });
         const client = new SkyrampClient();
+        // Declared outside the try so the catch below can report a leftover window
+        // too: traceCollect can throw after the terminal close already failed, and
+        // the user is still the only one who can close it.
+        let terminalAppendix = "";
         try {
             const stopTraceOptions = {
                 output: params.traceOutputFile,
@@ -90,14 +94,44 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             if (errList.content.length > 0) {
                 return errList;
             }
-            await closeProxyTerminal();
+            // Never throws: this sits inside the try that wraps traceCollect, so a
+            // throw here would lose the trace over a leftover window.
+            const terminalClose = await closeProxyTerminal();
+            // Built before traceCollect so the failure response below carries it
+            // too: an orphaned window outlives a failed trace just as it does a
+            // successful one, and the user is the only one who can close it.
+            //
+            // Named titles are the trigger, not `closed`. A stop that opened no
+            // terminal also reports closed: false, and telling the user to close a
+            // window that was never opened is worse than saying nothing.
+            const strandedTitles = [
+                ...(terminalClose.orphanedTitles ?? []),
+                ...(terminalClose.closed || !terminalClose.title
+                    ? []
+                    : [terminalClose.title]),
+            ];
+            if (strandedTitles.length) {
+                // Windows can name the exact windows, so it does.
+                terminalAppendix =
+                    `\n\nNote: ${strandedTitles.length === 1 ? "a trace collection terminal window" : `${strandedTitles.length} trace collection terminal windows`} could not be closed automatically and must be closed by hand: ` +
+                        strandedTitles.map((t) => `"${t}"`).join(", ") +
+                        `.${terminalClose.reason ? ` (${terminalClose.reason})` : ""}`;
+            }
+            else if (!terminalClose.closed) {
+                // macOS and Linux close by PID and have no title to quote, so the
+                // reason carries it. Without this arm a failed close on those
+                // platforms is invisible to the user, which is the whole bug.
+                terminalAppendix =
+                    `\n\nNote: the trace collection terminal could not be closed automatically and may still be open` +
+                        `${terminalClose.reason ? ` (${terminalClose.reason})` : ""}.`;
+            }
             const result = await client.traceCollect(stopTraceOptions);
             if (result.toLowerCase().includes("failed")) {
                 errorResult = {
                     content: [
                         {
                             type: "text",
-                            text: `Trace collection failed: ${result}`,
+                            text: `Trace collection failed: ${result}${terminalAppendix}`,
                         },
                     ],
                     isError: true,
@@ -108,7 +142,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             const sessionAppendix = savedSession
                 ? `\n\nPlaywright session storage saved to: ${savedSession}\nRe-use it by:\n` +
                     `• Pass \`playwrightStoragePath: "${savedSession}"\` to skyramp_start_trace_collection for future recordings (skips login).\n` +
-                    `• Generated tests that reference \`storageState: "${savedSession}"\` will auto-mount the file when run via skyramp_execute_test.`
+                    `• Generated tests that reference \`storageState: "${savedSession}"\` read it from that path when run via skyramp_execute_test.`
                 : "";
             errorResult = {
                 content: [
@@ -117,7 +151,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                         text: `Trace collection is stopped: ${result}. Trace is generated to given output file
 
               **IMPORTANT: GO THROUGH THE TRACE AND LET THE USER KNOW THE ENDPOINT DOMAINS CAPTURED AND MAKE SURE USER WANTS TO INCLUDE THEN FOR INTEGRATION/E2E/LOAD TEST GENERATION.
-              UI TESTS CAN BE GENERATED USING PLAYWRIGHT FILES ONLY.**${sessionAppendix}`,
+              UI TESTS CAN BE GENERATED USING PLAYWRIGHT FILES ONLY.**${sessionAppendix}${terminalAppendix}`,
                     },
                 ],
             };
@@ -128,7 +162,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 content: [
                     {
                         type: "text",
-                        text: `Trace generation result: ${error.message}`,
+                        text: `Trace generation result: ${error.message}${terminalAppendix}`,
                     },
                 ],
                 isError: true,
@@ -140,7 +174,9 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 prompt: params.prompt,
                 playwright: params.playwrightEnabled.toString(),
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/verifyTestDependenciesTool.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const VERIFY_TEST_DEPENDENCIES_TOOL = "skyramp_verify_test_dependencies";
+export declare function registerVerifyTestDependenciesTool(server: McpServer): void;

package/build/tools/verifyTestDependenciesTool.js

@@ -0,0 +1,54 @@
+import * as path from "path";
+import { z } from "zod";
+import { AnalyticsService } from "../services/AnalyticsService.js";
+import { logger } from "../utils/logger.js";
+import { verifyTestDependencyChanges } from "../utils/testDependencyPolicy.js";
+import { toolError } from "../utils/utils.js";
+export const VERIFY_TEST_DEPENDENCIES_TOOL = "skyramp_verify_test_dependencies";
+const schema = z.object({
+    repositoryPath: z
+        .string()
+        .refine((value) => path.isAbsolute(value), "repositoryPath must be an absolute path")
+        .describe("Absolute path to the repository whose working-tree dependency changes should be verified."),
+});
+export function registerVerifyTestDependenciesTool(server) {
+    server.registerTool(VERIFY_TEST_DEPENDENCIES_TOOL, {
+        description: "Verify that dependency changes made while fixing tests use only approved testing packages and development/test-only manifest scopes.",
+        inputSchema: schema.shape,
+        _meta: {
+            keywords: [
+                "dependencies",
+                "devDependencies",
+                "test dependencies",
+                "verification",
+            ],
+        },
+    }, async (params) => {
+        let result;
+        try {
+            const verification = await verifyTestDependencyChanges(params.repositoryPath);
+            result = verification.ok
+                ? {
+                    content: [
+                        {
+                            type: "text",
+                            text: `VERIFICATION PASSED — ${verification.checkedFiles.length} dependency file${verification.checkedFiles.length === 1 ? "" : "s"} checked.`,
+                        },
+                    ],
+                    isError: false,
+                }
+                : toolError("VERIFICATION FAILED — dependency changes are outside the safe test-only policy:\n" +
+                    verification.violations
+                        .map((violation) => `- ${violation}`)
+                        .join("\n") +
+                    "\nMove approved packages to the required development/test scope, remove unapproved or unrelated manifest edits, then run this verifier again.");
+        }
+        catch (error) {
+            result = toolError(`Test dependency verification failed: ${error.message}`);
+        }
+        AnalyticsService.pushMCPToolEvent(VERIFY_TEST_DEPENDENCIES_TOOL, result, {
+            repositoryPath: params.repositoryPath,
+        }).catch((error) => logger.warning("Analytics event failed", { error: String(error) }));
+        return result;
+    });
+}

package/build/tools/workspace/initScanWorkspaceTool.js

@@ -29,13 +29,17 @@ const initScanWorkspaceSchema = z.object({
 });
 export function registerInitScanWorkspaceTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: "PREREQUISITE for skyramp_init_workspace. " +
+        description: "Call this FIRST, before any other Skyramp tool (test generation, execution, analysis), whenever workspacePath is a git repository and .skyramp/workspace.yml does not exist at its root. " +
+            "PREREQUISITE for skyramp_init_workspace. " +
             "Scans a repository and returns instructions for discovering all services, along with a scanToken. " +
             "Follow the instructions to build the services array, then pass both to skyramp_init_workspace to create the workspace config.",
         inputSchema: initScanWorkspaceSchema.shape,
     }, async (params) => {
         let errorResult;
-        const recordParams = { workspacePath: params.workspacePath, force: String(params.force || false) };
+        const recordParams = {
+            workspacePath: params.workspacePath,
+            force: String(params.force || false),
+        };
         try {
             const manager = new WorkspaceConfigManager(params.workspacePath);
             if ((await manager.exists()) && !params.force) {
@@ -70,7 +74,9 @@ export function registerInitScanWorkspaceTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -273,7 +273,9 @@ export function registerInitializeWorkspaceTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/types/AssertionOutcome.d.ts

@@ -1,5 +1,5 @@
 import type { TestType } from "./TestTypes.js";
-import type { EnhanceType } from "../prompts/enhance-assertions/sharedAssertionRules.js";
+import type { EnhanceType } from "./EnhanceType.js";
 /**
  * Server-derived assertion-enhancement state. Lives in types/ (not beside
  * assertion-state.ts) because AnalysisStateManager embeds AssertionRecord in

package/build/types/EnhanceType.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The context an assertion enhancement runs in. Kept in its own leaf module so
+ * the run-state types, the verify layer, and the skill layer can all share the
+ * union without importing each other.
+ */
+export type EnhanceType = "generation" | "maintenance";

package/build/types/EnhanceType.js

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