@skyramp/mcp 0.4.1-rc.2 → 0.4.2-rc.1

package/build/adapters/jestAdapter.js

@@ -36,7 +36,9 @@ export function parseJestJson(report, opts) {
         const noAssertions = (file.assertionResults ?? []).length === 0;
         const isExecFailure = noAssertions && (file.testExecError || file.status === "failed");
         if (isExecFailure) {
-            const raw = file.testExecError?.message ?? file.message ?? "test file failed to run";
+            const raw = file.testExecError?.message ??
+                file.message ??
+                "test file failed to run";
             results.push({
                 testId: `${name} › (file failed to run)`,
                 file: name,
@@ -48,7 +50,9 @@ export function parseJestJson(report, opts) {
         }
         for (const a of file.assertionResults ?? []) {
             const status = mapAssertion(a.status);
-            const titlePath = [...(a.ancestorTitles ?? []), a.title ?? ""].filter(Boolean).join(" › ");
+            const titlePath = [...(a.ancestorTitles ?? []), a.title ?? ""]
+                .filter(Boolean)
+                .join(" › ");
             const message = status === "fail" || status === "error"
                 ? stripVTControlCharacters((a.failureMessages ?? [])[0] ?? "").trim() || undefined
                 : undefined;
@@ -67,7 +71,13 @@ export function parseJestJson(report, opts) {
     const passed = results.filter((r) => r.status === "pass").length;
     return {
         results,
-        summary: { ran: passed + failed + errored, failed, errored, skipped, truncated: opts?.truncated ?? false },
+        summary: {
+            ran: passed + failed + errored,
+            failed,
+            errored,
+            skipped,
+            truncated: opts?.truncated ?? false,
+        },
         environmentHealthy: true,
     };
 }
@@ -95,7 +105,11 @@ function splitSelectors(selectors) {
 }
 export function buildJestArgs(input) {
     const { files, titles } = splitSelectors(input.selectors);
-    const args = [...files, "--json", `--outputFile=${input.reportPath}`];
+    const args = [
+        ...files,
+        "--json",
+        `--outputFile=${input.reportPath}`,
+    ];
     if (input.mode === "probe")
         args.push("--bail=1");
     if (titles.length > 0)
@@ -104,7 +118,11 @@ export function buildJestArgs(input) {
 }
 export function buildVitestArgs(input) {
     const { files, titles } = splitSelectors(input.selectors);
-    const args = [...files, "--reporter=json", `--outputFile=${input.reportPath}`];
+    const args = [
+        ...files,
+        "--reporter=json",
+        `--outputFile=${input.reportPath}`,
+    ];
     if (input.mode === "probe")
         args.push("--bail=1");
     if (titles.length > 0)

package/build/adapters/mochaAdapter.js

@@ -49,7 +49,13 @@ export function parseMochaJson(report, opts) {
     const passed = results.filter((r) => r.status === "pass").length;
     return {
         results,
-        summary: { ran: passed + failed + errored, failed, errored, skipped, truncated: opts?.truncated ?? false },
+        summary: {
+            ran: passed + failed + errored,
+            failed,
+            errored,
+            skipped,
+            truncated: opts?.truncated ?? false,
+        },
         environmentHealthy: true,
     };
 }

package/build/adapters/playwrightAdapter.js

@@ -111,7 +111,9 @@ export function parsePlaywrightJson(report, opts) {
                 }
                 continue; // never reported as a test result
             }
-            const titlePath = [...describePath, spec.title].filter(Boolean).join(" › ");
+            const titlePath = [...describePath, spec.title]
+                .filter(Boolean)
+                .join(" › ");
             const testId = `${file} › ${titlePath}` +
                 (multiProject && test.projectName ? ` [${test.projectName}]` : "");
             const durationMs = test.results?.[test.results.length - 1]?.duration ?? 0;

package/build/adapters/pytestAdapter.js

@@ -33,7 +33,9 @@ function messageOf(test) {
     return stripVTControlCharacters(raw).trim() || undefined;
 }
 function durationMsOf(test) {
-    const secs = (test.setup?.duration ?? 0) + (test.call?.duration ?? 0) + (test.teardown?.duration ?? 0);
+    const secs = (test.setup?.duration ?? 0) +
+        (test.call?.duration ?? 0) +
+        (test.teardown?.duration ?? 0);
     return Math.round(secs * 1000);
 }
 export function parsePytestJson(report, opts) {
@@ -52,7 +54,10 @@ export function parsePytestJson(report, opts) {
         };
     });
     const collectionErrors = (rep.collectors ?? []).filter((c) => c.outcome === "error" || c.outcome === "failed");
-    const lastLine = (raw) => stripVTControlCharacters(raw ?? "collection error").split("\n").filter(Boolean).slice(-1)[0] ?? "collection error";
+    const lastLine = (raw) => stripVTControlCharacters(raw ?? "collection error")
+        .split("\n")
+        .filter(Boolean)
+        .slice(-1)[0] ?? "collection error";
     // Surface each collection/import error as an errored result so a broken file is
     // never invisible — regardless of whether other selected files ran. A collection
     // error IS a real breakage (PR signal), counted in `errored`/`ran`.
@@ -83,7 +88,13 @@ export function parsePytestJson(report, opts) {
     const passed = results.filter((r) => r.status === "pass").length;
     return {
         results,
-        summary: { ran: passed + failed + errored, failed, errored, skipped, truncated: opts?.truncated ?? false },
+        summary: {
+            ran: passed + failed + errored,
+            failed,
+            errored,
+            skipped,
+            truncated: opts?.truncated ?? false,
+        },
         environmentHealthy,
         healthDetail,
         diagnostics: {

package/build/commands/localDevTestChangesCommand.js

@@ -118,6 +118,7 @@ Three rules apply in fallback mode at all times:
 `;
     const ctx = {
         repositoryPath: "<REPOSITORY_PATH>",
+        repository: "<OWNER/REPO of the checkout, from its origin remote>",
         baseCommit: "<BASE_BRANCH from one-click baseBranch, default main>",
         maxRecommendations: 8,
         maxGenerate: 5,

package/build/commands/recommendTestsAndExecuteCommand.js

@@ -67,7 +67,10 @@ const fullRepoRecommendGenerateExecuteSteps = [
             inputs: {
                 workspacePath: { source: "user", paramKey: "repositoryPath" },
                 language: { source: "literal", value: "from workspace" },
-                testType: { source: "literal", value: "from test file / recommendation" },
+                testType: {
+                    source: "literal",
+                    value: "from test file / recommendation",
+                },
                 testFile: {
                     source: "literal",
                     value: "path to a single generated test file; for each test path returned by generation tools in step 2, call skyramp_execute_test separately with testFile set to that path",
@@ -110,10 +113,6 @@ export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND = {
     steps: fullRepoRecommendGenerateExecuteSteps,
     inputParams: {
         required: ["repositoryPath"],
-        optional: [
-            "token",
-            "endpointURL",
-            "apiSchema",
-        ],
+        optional: ["token", "endpointURL", "apiSchema"],
     },
 };

package/build/commands/testThisEndpointCommand.js

@@ -75,7 +75,10 @@ const comprehensivelyTestGivenEndpointSteps = [
             inputs: {
                 workspacePath: { source: "user", paramKey: "repositoryPath" },
                 language: { source: "literal", value: "from workspace" },
-                testType: { source: "literal", value: "from generated test / recommendation" },
+                testType: {
+                    source: "literal",
+                    value: "from generated test / recommendation",
+                },
                 testFile: {
                     source: "literal",
                     value: "path to a single generated test file; for each test path returned by generation tools in step 3, call skyramp_execute_test separately with testFile set to that path",
@@ -108,9 +111,18 @@ const comprehensivelyTestGivenEndpointSteps = [
             description: "Optionally run existing tests individually; iterate over tests from stateFile and write results back",
             inputs: {
                 workspacePath: { source: "user", paramKey: "repositoryPath" },
-                testFile: { source: "literal", value: "path from stateFile existingTests array" },
-                language: { source: "literal", value: "language from stateFile existingTests array" },
-                testType: { source: "literal", value: "testType from stateFile existingTests array" },
+                testFile: {
+                    source: "literal",
+                    value: "path from stateFile existingTests array",
+                },
+                language: {
+                    source: "literal",
+                    value: "language from stateFile existingTests array",
+                },
+                testType: {
+                    source: "literal",
+                    value: "testType from stateFile existingTests array",
+                },
                 token: { source: "user", paramKey: "token" },
                 stateFile: { source: "step", stepIndex: 1, outputKey: "stateFile" },
             },

package/build/index.js

@@ -19,10 +19,13 @@ import { registerE2ETestTool } from "./tools/generate-tests/generateE2ERestTool.
 import { registerLoginTool } from "./tools/auth/loginTool.js";
 import { registerLogoutTool } from "./tools/auth/logoutTool.js";
 import { registerFixErrorTool } from "./tools/fixErrorTool.js";
+import { registerVerifyTestDependenciesTool } from "./tools/verifyTestDependenciesTool.js";
 import { registerRecommendTestsPrompt } from "./prompts/test-recommendation/registerRecommendTestsPrompt.js";
 import { registerModularizationTool } from "./tools/code-refactor/modularizationTool.js";
 import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerEnhanceAssertionsTool } from "./tools/code-refactor/enhanceAssertionsTool.js";
+import { registerAlignAssertionsTool } from "./tools/code-refactor/alignAssertionsTool.js";
+import { registerAssertionSnapshotTool, registerAssertionVerifyTool, } from "./tools/code-refactor/assertionSkillTools.js";
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
 import { registerBatchMockTool } from "./tools/generate-tests/batchMockGenerationTool.js";
@@ -68,6 +71,18 @@ else if (oneClickEnabled) {
 else if (localDevEnabled) {
     oneClickInstructions = localDevInstructions;
 }
+// Global workspace-init nudge for bare MCP usage. Suppressed in testbot mode,
+// which runs its own INIT_WORKSPACE step (buildWorkspaceInitSection()) instead.
+const workspaceInitInstructions = isTestbotEnabled() || oneClickEnabled || localDevEnabled
+    ? ""
+    : `
+## Workspace Initialization (REQUIRED before the first Skyramp tool call)
+If the workspace root is a git repo AND \`.skyramp/workspace.yml\` does not exist:
+1. Call \`skyramp_init_scan\` with \`workspacePath\` set to the current repository root → follow the returned instructions to discover all services.
+2. Call \`skyramp_init_workspace\` with that SAME \`workspacePath\`, \`services\`, and the \`scanToken\` from step 1.
+3. Proceed with the originally requested tool, if it is not one of the two workspace-init tools above.
+Skip only if: not a git repo, \`.skyramp/workspace.yml\` already exists, or user explicitly declines.
+`;
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -84,7 +99,7 @@ const server = new McpServer({
         },
     },
     instructions: `Skyramp MCP Server — generates and executes API tests (fuzz, contract, integration, E2E, UI).
-
+${workspaceInitInstructions}
 ## Rules
 - NEVER show CLI commands. NEVER attempt to install or configure the Skyramp CLI. ALWAYS use the MCP tools provided.
 - For UI and E2E tests, there are TWO recording modes:
@@ -172,12 +187,22 @@ const codeQualityTools = [
     registerModularizationTool,
     registerCodeReuseTool,
     registerEnhanceAssertionsTool,
+    registerAssertionVerifyTool,
+    registerVerifyTestDependenciesTool,
 ];
 // With the Skyramp plugin loaded the agent already has the
 // fix-test-import-errors skill; the tool would be a second copy of
 // the same text (SKYR-4296).
 if (!isSkillsLoaded()) {
-    codeQualityTools.push(registerFixErrorTool);
+    // Same reasoning as fix-test-import-errors: with the plugin loaded the agent
+    // has the validate-assertion-alignment-post-execution skill directly; this
+    // tool exists so an agent without skill support still gets the same
+    // procedure, rendered from the same markdown with real arguments filled in.
+    codeQualityTools.push(registerFixErrorTool, registerAlignAssertionsTool);
+}
+else {
+    // The enhance-assertions skill drives its own snapshot step itself (SKYR-4310).
+    codeQualityTools.push(registerAssertionSnapshotTool);
 }
 codeQualityTools.forEach((registerTool) => registerTool(server));
 // Register analysis resources (MCP Resources for enriched data access)
@@ -256,12 +281,17 @@ infrastructureTools.forEach((registerTool) => registerTool(server));
                 // Editing the repo's own Playwright config is the wrong instruction: a
                 // suite may have several, and none of them at the root.
                 logger.info("No testIdAttribute declared or discovered — capture stays on Playwright's data-testid. " +
-                    "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", { attributesSeenInSelectors: discovered.observed, filesScanned: discovered.filesScanned });
+                    "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", {
+                    attributesSeenInSelectors: discovered.observed,
+                    filesScanned: discovered.filesScanned,
+                });
             }
         }
     }
     catch (err) {
-        logger.warning("Could not determine this repository's testIdAttribute", { error: err });
+        logger.warning("Could not determine this repository's testIdAttribute", {
+            error: err,
+        });
     }
     await registerPlaywrightTools(server, { testIdAttribute });
 })().catch((err) => {

package/build/playwright/blueprintDigest.js

@@ -15,7 +15,9 @@ export function blueprintJsonSpan(text) {
 const MAX_DEPTH = 12;
 export const MAX_ELEMENTS = 2000;
 function text(value) {
-    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : undefined;
 }
 function rowText(value) {
     if (!Array.isArray(value))
@@ -32,13 +34,21 @@ function fillTemplate(template, parameters) {
     const values = parameters;
     return template.replace(/\{([^{}]+)\}/g, (placeholder, name) => {
         const value = values[name];
-        return typeof value === "string" || typeof value === "number" ? String(value) : placeholder;
+        return typeof value === "string" || typeof value === "number"
+            ? String(value)
+            : placeholder;
     });
 }
 function identity(element) {
     // Serialised rather than joined on a separator: a row's context text is page
     // content and can hold any character, so any separator could be in it.
-    return JSON.stringify([element.role, element.accessibleName, element.testId ?? "", element.stableId ?? "", element.contextText ?? []]);
+    return JSON.stringify([
+        element.role,
+        element.accessibleName,
+        element.testId ?? "",
+        element.stableId ?? "",
+        element.contextText ?? [],
+    ]);
 }
 /** Every element this record describes. A repeating one keeps BOTH its template
  *  and each filled-in row, because the agent lifts a row's rendered name. */
@@ -80,7 +90,9 @@ function collectElements(root) {
     const found = [];
     let truncated = false;
     const seen = new Set();
-    const stack = [{ value: root, depth: 0 }];
+    const stack = [
+        { value: root, depth: 0 },
+    ];
     while (stack.length > 0) {
         if (found.length >= MAX_ELEMENTS) {
             truncated = true;
@@ -117,12 +129,16 @@ function collectElements(root) {
 }
 function urlOf(parsed) {
     const blueprint = parsed.blueprint;
-    const inner = blueprint && typeof blueprint === "object" ? blueprint : undefined;
+    const inner = blueprint && typeof blueprint === "object"
+        ? blueprint
+        : undefined;
     return text(parsed.url) ?? (inner ? text(inner.url) : undefined);
 }
 function pageHashOf(parsed) {
     const blueprint = parsed.blueprint;
-    const inner = blueprint && typeof blueprint === "object" ? blueprint : undefined;
+    const inner = blueprint && typeof blueprint === "object"
+        ? blueprint
+        : undefined;
     return text(parsed.pageHash) ?? (inner ? text(inner.pageHash) : undefined);
 }
 /** The digest of one payload, or undefined when nothing in it keys to a page.
@@ -148,5 +164,10 @@ export function digestFromBlueprintText(payload, previousUrl) {
         return undefined;
     const pageHash = pageHashOf(record);
     const { elements, truncated } = collectElements(record);
-    return { url, ...(pageHash ? { pageHash } : {}), elements, ...(truncated ? { elementsTruncated: true } : {}) };
+    return {
+        url,
+        ...(pageHash ? { pageHash } : {}),
+        elements,
+        ...(truncated ? { elementsTruncated: true } : {}),
+    };
 }

package/build/playwright/registerPlaywrightTools.js

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
 import { blueprintJsonSpan } from "./blueprintDigest.js";
-import { recordBlueprintCapture, recordBrowserNavigation } from "./blueprintDigestStore.js";
+import { recordBlueprintCapture, recordBrowserNavigation, } from "./blueprintDigestStore.js";
 let _service = null;
 export function getPlaywrightTraceService() {
     return _service;
@@ -44,11 +44,16 @@ function withAssertReminder(result) {
     const content = result?.content ?? [];
     const last = content.map((block) => block?.type).lastIndexOf("text");
     if (last < 0) {
-        return { ...result, content: [...content, { type: "text", text: ASSERT_REMINDER }] };
+        return {
+            ...result,
+            content: [...content, { type: "text", text: ASSERT_REMINDER }],
+        };
     }
     return {
         ...result,
-        content: content.map((block, i) => i === last && block?.type === "text" ? { ...block, text: `${block.text}\n\n${ASSERT_REMINDER}` } : block),
+        content: content.map((block, i) => i === last && block?.type === "text"
+            ? { ...block, text: `${block.text}\n\n${ASSERT_REMINDER}` }
+            : block),
     };
 }
 /**
@@ -171,32 +176,32 @@ export async function registerPlaywrightTools(server, options) {
     // The widgetType field on blueprint elements still signals "custom" to
     // the agent — no guidance is lost.
     const ESSENTIAL_TOOLS = new Set([
-        'browser_navigate',
-        'browser_snapshot',
-        'browser_click',
-        'browser_type',
-        'browser_press_key',
-        'browser_select_option',
-        'browser_hover',
-        'browser_drag',
-        'browser_file_upload',
-        'browser_evaluate',
-        'browser_tabs',
-        'browser_navigate_back',
-        'browser_wait_for',
-        'browser_take_screenshot',
-        'browser_assert',
-        'browser_assert_hidden',
-        'browser_assert_api_request',
-        'browser_assert_table_cell',
-        'browser_mouse_action',
-        'browser_visual_snapshot',
-        'browser_gojs_add_node',
-        'browser_gojs_link',
-        'skyramp_export_zip',
-        'skyramp_load_trace',
+        "browser_navigate",
+        "browser_snapshot",
+        "browser_click",
+        "browser_type",
+        "browser_press_key",
+        "browser_select_option",
+        "browser_hover",
+        "browser_drag",
+        "browser_file_upload",
+        "browser_evaluate",
+        "browser_tabs",
+        "browser_navigate_back",
+        "browser_wait_for",
+        "browser_take_screenshot",
+        "browser_assert",
+        "browser_assert_hidden",
+        "browser_assert_api_request",
+        "browser_assert_table_cell",
+        "browser_mouse_action",
+        "browser_visual_snapshot",
+        "browser_gojs_add_node",
+        "browser_gojs_link",
+        "skyramp_export_zip",
+        "skyramp_load_trace",
         // DOM Analyzer: blueprint capture (capture-act-capture pattern)
-        'browser_blueprint',
+        "browser_blueprint",
     ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);

package/build/playwright/traceRecordingPrompt.js

@@ -55,11 +55,18 @@ These concepts drive the DOM Analyzer capture tools and constrain how their outp
 - **\`browser_blueprint\` — stable logical names**: logical names like \`add_order_btn\` and their derived \`getByRole\` locators survive page reloads and playback. Use them in generated test code. Call \`browser_blueprint\` before and after each meaningful action to capture state changes.
 
 ### Assertions
-Call \`browser_assert\` when assertions are needed. Always provide the \`expected\` value.
+Call \`browser_assert\` when assertions are needed. Provide \`expected\` for every type that takes one (all except \`visible\`).
 - \`type: "text"\` — verify an element contains expected text
 - \`type: "value"\` — verify an input field has an expected value
+- \`type: "css"\` — verify a computed style (\`property\` = the CSS property, e.g. \`background-color\`; \`expected\` = the value the app computes)
+- \`type: "class"\` — verify the element carries a class (\`expected\` = one class name)
+- \`type: "attribute"\` — verify an attribute value (\`property\` = the attribute name; \`expected\` = its value)
 
-**Visual / screenshot assertions.** When the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (as opposed to its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline image on every run. Do NOT use \`browser_take_screenshot\` for this: it only captures a throwaway image, is dropped at export (it produces no assertion), and will NOT appear in the generated test. Use \`browser_take_screenshot\` only to view the page yourself while recording — never to record a visual check. \`filename\` is optional: if the instruction names a baseline file (e.g. \`page-001.png\`) pass it as \`filename\`, otherwise omit it and \`browser_visual_snapshot\` auto-generates one per \`snapshotType\` (\`page-NNN.png\` for a page, \`el-NNN.png\` for an element, \`region-NNN.png\` for a region).
+**Visual / screenshot assertions.** When the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (as opposed to its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline image on every run.
+
+**When the change under test is how something looks** — a colour, class or attribute the diff changes — assert it directly with \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children); if it has no stable ref, note a recording gap rather than assert the wrong element. Order has no kind: \`flex-direction\` when the diff flipped it, else a \`boundingBox()\` comparison at enhance. \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
+
+Do NOT use \`browser_take_screenshot\` to record a visual check: it only captures a throwaway image, is dropped at export (it produces no assertion), and will NOT appear in the generated test. Use it only to view the page yourself while recording. \`filename\` is optional on \`browser_visual_snapshot\`: if the instruction names a baseline file (e.g. \`page-001.png\`) pass it as \`filename\`, otherwise omit it and one is auto-generated per \`snapshotType\` (\`page-NNN.png\` for a page, \`el-NNN.png\` for an element, \`region-NNN.png\` for a region).
 
 ### Tips
 - **Custom dropdowns (Radix, MUI, etc.)**: click the combobox trigger → \`browser_snapshot\` → click the option. Do NOT use \`browser_select_option\` — it only works on native \`<select>\` elements.