@skyramp/mcp 0.3.5 → 0.3.6-rc.1

package/build/utils/utils-verify/verify.js

@@ -0,0 +1,168 @@
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "../logger.js";
+import { locateUtilsFiles } from "./locate.js";
+import { parseUtilsFile } from "./parse.js";
+import { findSiblingInlineCallSites, } from "./call-sites.js";
+import { parseUtilsAllows } from "./allow.js";
+import { helperFamilyFor, scenarioNameViolation, utilsSpecFor, utilsSpecForFile, } from "./language-spec.js";
+/**
+ * Deterministic post-reuse check of the shared utils file(s) a spec depends on.
+ *
+ * Three invariants, each a class of drift measured in the SKYR-4196 Part B evals:
+ *  - `duplicate-helper`: two helpers for one method+path (run 4 — `create_product`
+ *    beside `create_list_reflect_product`); the shared file must hold one canonical
+ *    helper per step, extended with defaulted parameters rather than duplicated.
+ *  - `body-assertion`: any assertion other than a status-code comparison inside a
+ *    helper (runs 5 and 11 — `assert total_amount == 16.0` in `update_order`); a
+ *    body assertion carries one scenario's values into a function every scenario calls.
+ *  - `scenario-name` (ADVISORY only): a helper named for its scenario rather than its step.
+ *
+ * Analyses the utils files' INTERNAL invariants — unlike the POM verifier, which
+ * checks a spec's cross-file references — so it reads the utils files, not the spec,
+ * except to count what the spec imports.
+ */
+export async function verifyUtils(params) {
+    const spec = utilsSpecFor(params.language) ?? utilsSpecForFile(params.testFile);
+    const family = helperFamilyFor(params.testType);
+    const utilsFiles = spec
+        ? await locateUtilsFiles({
+            testFile: params.testFile,
+            language: spec.language,
+            cwd: params.cwd,
+        })
+        : [];
+    const result = {
+        ok: true,
+        utilsFiles,
+        helpers: 0,
+        imported: 0,
+        violations: [],
+        allowed: [],
+        advisories: [],
+        malformedAllows: [],
+        spec,
+        family,
+        inlineCallSites: [],
+    };
+    if (!spec || utilsFiles.length === 0)
+        return result;
+    let specContent = "";
+    try {
+        specContent = await fs.promises.readFile(params.testFile, "utf8");
+    }
+    catch {
+        /* the spec may be absent outside a run; import counting then reports 0 */
+    }
+    const allHelpers = [];
+    const importedNames = new Set();
+    // Route map spans every utils file: the reuse prompt allows the helpers to split
+    // across files, and the same method+path in two of them is still one duplicate.
+    const byRoute = new Map();
+    for (const file of utilsFiles) {
+        let content;
+        try {
+            content = await fs.promises.readFile(file, "utf8");
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                continue; // removed since locate
+            logger.warning("Could not read a located utils file", {
+                file,
+                error: String(err),
+            });
+            throw err; // the caller records a verify error, which fails OPEN — never a silent PASS
+        }
+        const helpers = parseUtilsFile(content, spec, (expr) => family.isAllowed(spec, expr));
+        allHelpers.push(...helpers);
+        const { allows, malformed } = parseUtilsAllows(content, spec);
+        result.helpers += helpers.length;
+        result.malformedAllows.push(...malformed.map((line) => ({ file, line })));
+        const stem = path.basename(file).replace(/\.[^.]+$/, "");
+        const defined = new Set(helpers.map((h) => h.name));
+        for (const n of spec.importedNames(specContent, stem))
+            if (defined.has(n))
+                importedNames.add(n);
+        // One marker documents ONE violation of that kind in that helper: a second,
+        // undocumented scenario claim in the same helper is not covered by the first
+        // decline. Markers are consumed in order.
+        const budget = new Map();
+        for (const a of allows) {
+            const k = `${a.kind}\0${a.helper}`;
+            budget.set(k, (budget.get(k) ?? 0) + 1);
+        }
+        for (const v of violationsIn(helpers, file, family, byRoute)) {
+            const k = `${v.kind}\0${v.helper}`;
+            const left = budget.get(k) ?? 0;
+            if (left > 0) {
+                budget.set(k, left - 1);
+                result.allowed.push(v);
+            }
+            else if (v.kind === "scenario-name") {
+                result.advisories.push(v);
+            }
+            else {
+                result.violations.push(v);
+            }
+        }
+    }
+    result.imported = importedNames.size;
+    result.ok =
+        result.violations.length === 0 && result.malformedAllows.length === 0;
+    // Integration only — the same gate as the prompt rule. `contract`, `load` and an
+    // absent type also resolve to the API family, but the reuse flow never targets them,
+    // so an advisory (and a report count) there would describe reuse the feature could
+    // not have taken.
+    if ((params.testType ?? "").toLowerCase() === "integration") {
+        try {
+            result.inlineCallSites = await findSiblingInlineCallSites(params.testFile, utilsFiles, allHelpers, spec);
+        }
+        catch {
+            /* advisory only — never fails a verify */
+        }
+    }
+    return result;
+}
+function violationsIn(helpers, file, family, byRoute) {
+    const out = [];
+    for (const h of helpers) {
+        if (family.routeDuplicates && h.method && h.normalizedPath) {
+            const key = `${h.method} ${h.normalizedPath}`;
+            const first = byRoute.get(key);
+            if (first) {
+                out.push({
+                    kind: "duplicate-helper",
+                    file,
+                    helper: h.name,
+                    line: h.line,
+                    detail: `${h.name} and ${first.name} (${path.basename(first.file)}:${first.line}) both wrap ${key}; keep one helper per method+path and lift the differing literals into defaulted parameters`,
+                });
+            }
+            else {
+                byRoute.set(key, { ...h, file });
+            }
+        }
+        for (const a of h.assertions) {
+            if (!a.allowed) {
+                out.push({
+                    kind: "body-assertion",
+                    file,
+                    helper: h.name,
+                    line: a.line,
+                    detail: `\`${a.text}\` — ${family.assertionRule}`,
+                });
+            }
+        }
+        const naming = scenarioNameViolation(h.name);
+        if (naming) {
+            out.push({
+                kind: "scenario-name",
+                file,
+                helper: h.name,
+                line: h.line,
+                detail: naming,
+            });
+        }
+    }
+    return out;
+}

package/build/utils/utils.d.ts

@@ -32,7 +32,9 @@ export declare function toolError(message: string): CallToolResult;
  *
  * 2. Each agent CLI testbot supports reads a different channel and none falls
  *    back to the other: Claude Code takes `structuredContent` and drops
- *    `content[]`; Cursor takes `content[]` and ignores `structuredContent`;
+ *    `content[]` WHEN BOTH ARE PRESENT — a content-only result still reaches it,
+ *    which is what SKYR-4267 relies on for `browser_blueprint`; Cursor takes
+ *    `content[]` and ignores `structuredContent`;
  *    GitHub Copilot CLI surfaces both and de-duplicates them only when the text
  *    is the literal JSON serialization of `structuredContent` (MCP spec 5.2.6),
  *    otherwise it concatenates. Hence `JSON.stringify` rather than the raw text,

package/build/utils/utils.js

@@ -49,7 +49,9 @@ export function toolError(message) {
  *
  * 2. Each agent CLI testbot supports reads a different channel and none falls
  *    back to the other: Claude Code takes `structuredContent` and drops
- *    `content[]`; Cursor takes `content[]` and ignores `structuredContent`;
+ *    `content[]` WHEN BOTH ARE PRESENT — a content-only result still reaches it,
+ *    which is what SKYR-4267 relies on for `browser_blueprint`; Cursor takes
+ *    `content[]` and ignores `structuredContent`;
  *    GitHub Copilot CLI surfaces both and de-duplicates them only when the text
  *    is the literal JSON serialization of `structuredContent` (MCP spec 5.2.6),
  *    otherwise it concatenates. Hence `JSON.stringify` rather than the raw text,

package/build/workspace/workspace.d.ts

@@ -55,26 +55,26 @@ export declare const serviceSchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         authHeader?: string | undefined;
         authScheme?: string | undefined;
+        authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+        baseUrl?: string | undefined;
         schemaPath?: string | undefined;
-        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
         queryParamOverrides?: {
             values: Record<string, string>;
             pathPattern: string;
         }[] | undefined;
-        baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     }, {
         authHeader?: string | undefined;
         authScheme?: string | undefined;
+        authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+        baseUrl?: string | undefined;
         schemaPath?: string | undefined;
-        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
         queryParamOverrides?: {
             values: Record<string, string>;
             pathPattern: string;
         }[] | undefined;
-        baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     }>>;
     runtimeDetails: z.ZodOptional<z.ZodObject<{
@@ -143,20 +143,20 @@ export declare const serviceSchema: z.ZodObject<{
     language?: "python" | "typescript" | "javascript" | "java" | undefined;
     framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
     repository?: string | undefined;
-    testDirectory?: string | undefined;
     api?: {
         authHeader?: string | undefined;
         authScheme?: string | undefined;
+        authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+        baseUrl?: string | undefined;
         schemaPath?: string | undefined;
-        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
         queryParamOverrides?: {
             values: Record<string, string>;
             pathPattern: string;
         }[] | undefined;
-        baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     } | undefined;
+    testDirectory?: string | undefined;
     runtimeDetails?: {
         runtime: import("../types/TestTypes.js").RuntimeEnvironment;
         dockerNetwork?: string | undefined;
@@ -178,20 +178,20 @@ export declare const serviceSchema: z.ZodObject<{
     language?: "python" | "typescript" | "javascript" | "java" | undefined;
     framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
     repository?: string | undefined;
-    testDirectory?: string | undefined;
     api?: {
         authHeader?: string | undefined;
         authScheme?: string | undefined;
+        authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+        baseUrl?: string | undefined;
         schemaPath?: string | undefined;
-        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
         queryParamOverrides?: {
             values: Record<string, string>;
             pathPattern: string;
         }[] | undefined;
-        baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     } | undefined;
+    testDirectory?: string | undefined;
     runtimeDetails?: {
         runtime?: unknown;
         dockerNetwork?: string | undefined;
@@ -292,26 +292,26 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         }, "strict", z.ZodTypeAny, {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         }, {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         }>>;
         runtimeDetails: z.ZodOptional<z.ZodObject<{
@@ -380,20 +380,20 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         language?: "python" | "typescript" | "javascript" | "java" | undefined;
         framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
         repository?: string | undefined;
-        testDirectory?: string | undefined;
         api?: {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
+        testDirectory?: string | undefined;
         runtimeDetails?: {
             runtime: import("../types/TestTypes.js").RuntimeEnvironment;
             dockerNetwork?: string | undefined;
@@ -415,20 +415,20 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         language?: "python" | "typescript" | "javascript" | "java" | undefined;
         framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
         repository?: string | undefined;
-        testDirectory?: string | undefined;
         api?: {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
+        testDirectory?: string | undefined;
         runtimeDetails?: {
             runtime?: unknown;
             dockerNetwork?: string | undefined;
@@ -463,20 +463,20 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         language?: "python" | "typescript" | "javascript" | "java" | undefined;
         framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
         repository?: string | undefined;
-        testDirectory?: string | undefined;
         api?: {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
+        testDirectory?: string | undefined;
         runtimeDetails?: {
             runtime: import("../types/TestTypes.js").RuntimeEnvironment;
             dockerNetwork?: string | undefined;
@@ -511,20 +511,20 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         language?: "python" | "typescript" | "javascript" | "java" | undefined;
         framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
         repository?: string | undefined;
-        testDirectory?: string | undefined;
         api?: {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
+        testDirectory?: string | undefined;
         runtimeDetails?: {
             runtime?: unknown;
             dockerNetwork?: string | undefined;
@@ -568,20 +568,20 @@ export declare function validateWorkspaceConfig(config: unknown): z.SafeParseRet
         language?: "python" | "typescript" | "javascript" | "java" | undefined;
         framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
         repository?: string | undefined;
-        testDirectory?: string | undefined;
         api?: {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
+        testDirectory?: string | undefined;
         runtimeDetails?: {
             runtime?: unknown;
             dockerNetwork?: string | undefined;
@@ -616,20 +616,20 @@ export declare function validateWorkspaceConfig(config: unknown): z.SafeParseRet
         language?: "python" | "typescript" | "javascript" | "java" | undefined;
         framework?: "playwright" | "pytest" | "robot" | "junit" | "vitest" | "jest" | "mocha" | "go" | "rspec" | "jasmine" | undefined;
         repository?: string | undefined;
-        testDirectory?: string | undefined;
         api?: {
             authHeader?: string | undefined;
             authScheme?: string | undefined;
+            authType?: "none" | "cookie" | "bearer" | "basic" | "oauth" | "apiKey" | "session" | "token" | undefined;
+            baseUrl?: string | undefined;
             schemaPath?: string | undefined;
-            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
             queryParamOverrides?: {
                 values: Record<string, string>;
                 pathPattern: string;
             }[] | undefined;
-            baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
+        testDirectory?: string | undefined;
         runtimeDetails?: {
             runtime: import("../types/TestTypes.js").RuntimeEnvironment;
             dockerNetwork?: string | undefined;

package/node_modules/playwright/lib/mcp/skyramp/assertTool.js

@@ -28,16 +28,20 @@ const assertToolSchema = {
   name: "browser_assert",
   title: "Assert element state",
   description: [
-    "Assert that an element has expected text, value, or is visible.",
+    "Assert that an element has expected text, value, or state.",
     "Use this after key actions to verify the page state is correct.",
     "The assertion is recorded in the trace for test generation.",
-    'Types: "text" checks element text content, "value" checks input field value.'
+    'Types: "text" checks element text content, "value" checks input field value,',
+    '"checked" checks checkbox/radio state, "disabled" checks disabled/enabled state,',
+    '"visible" checks the element is visible,',
+    `"count" counts elements sharing the referenced element's role (or exact text)`,
+    "across the page, e.g. ref one option of an open dropdown to assert the number of options."
   ].join(" "),
   inputSchema: import_mcpBundle.z.object({
-    type: import_mcpBundle.z.enum(["text", "value"]).describe('Type of assertion: "text" for text content, "value" for input field value'),
-    ref: import_mcpBundle.z.string().describe("Element reference from the latest snapshot"),
+    type: import_mcpBundle.z.enum(["text", "value", "checked", "disabled", "visible", "count"]).describe(`Type of assertion: "text" for text content, "value" for input field value, "checked" for checkbox/radio state, "disabled" for disabled/enabled state ("false" asserts the element is enabled), "visible" for element visibility, "count" for the number of elements with the referenced element's role`),
+    ref: import_mcpBundle.z.string().describe('Element reference from the latest snapshot. For "count", reference one exemplar element (e.g. one option in an open dropdown).'),
     element: import_mcpBundle.z.string().describe("Human-readable description of the element being asserted"),
-    expected: import_mcpBundle.z.string().describe("Expected text or value to assert"),
+    expected: import_mcpBundle.z.string().optional().describe('Expected text or value ("text"/"value"), "true"/"false" ("checked"/"disabled", default "true"; "disabled" with "false" asserts enabled), the expected element count ("count"). Not used for "visible".'),
     substring: import_mcpBundle.z.boolean().optional().default(true).describe("For text assertions: match as substring (true) or exact match (false)")
   }),
   type: "readOnly"

package/node_modules/playwright/lib/mcp/skyramp/loadTraceTool.js

@@ -370,6 +370,22 @@ async function performClientAction(page, actionInContext) {
         throw new Error(`assertVisible failed: element is not visible`);
       return;
     }
+    case "assertDisabled": {
+      if (typeof action.disabled !== "boolean")
+        throw new Error(`assertDisabled failed: trace line has no boolean "disabled" field`);
+      const disabled = await locator.isDisabled(opts);
+      if (disabled !== action.disabled)
+        throw new Error(`assertDisabled failed: expected disabled=${action.disabled}, got ${disabled}`);
+      return;
+    }
+    case "assertCount": {
+      await locator.first().waitFor(opts).catch(() => {
+      });
+      const count = await locator.count();
+      if (count !== action.count)
+        throw new Error(`assertCount failed: expected ${action.count} element(s), got ${count}`);
+      return;
+    }
     default:
       return;
   }

package/node_modules/playwright/lib/mcp/skyramp/skyRampImport.js

@@ -61,6 +61,8 @@ const ACTION_NAMES = /* @__PURE__ */ new Set([
   "assertValue",
   "assertChecked",
   "assertVisible",
+  "assertDisabled",
+  "assertCount",
   "assertSnapshot",
   "visualSnapshot",
   "assertTableCell",