@skyramp/mcp 0.2.1 → 0.2.3

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

@@ -44,6 +44,10 @@ var import_skyRampExport = require("../test/skyRampExport");
 var import_exportTool = require("./exportTool");
 var import_assertTool = require("./assertTool");
 var import_assertApiRequestTool = require("./assertApiRequestTool");
+var import_loadTraceTool = require("./loadTraceTool");
+var import_skyRampImport = require("./skyRampImport");
+var import_mouseActionTool = require("./mouseActionTool");
+var import_utils = require("playwright-core/lib/utils");
 var import_types = require("./types");
 const traceDebug = (0, import_utilsBundle.debug)("pw:mcp:trace");
 class TraceRecordingBackend {
@@ -116,7 +120,7 @@ class TraceRecordingBackend {
   }
   async listTools() {
     const browserTools = await this._browserBackend.listTools();
-    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)()];
+    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)(), (0, import_mouseActionTool.mouseActionMcpTool)()];
   }
   async callTool(name, args, progress) {
     if (!this._initialized)
@@ -139,6 +143,14 @@ class TraceRecordingBackend {
       }
       return exportResult;
     }
+    if (name === import_loadTraceTool.loadTraceSchema.name) {
+      const parsed = import_loadTraceTool.loadTraceSchema.inputSchema.parse(args || {});
+      return this._handleLoadTrace(parsed);
+    }
+    if (name === import_mouseActionTool.mouseActionSchema.name) {
+      const parsed = import_mouseActionTool.mouseActionSchema.inputSchema.parse(args || {});
+      return this._handleMouseAction(parsed);
+    }
     if (name === import_assertTool.assertToolSchema.name) {
       const parsed = import_assertTool.assertToolSchema.inputSchema.parse(args || {});
       return this._handleAssert(parsed);
@@ -313,6 +325,280 @@ Reloaded current page: ${currentUrl}
   serverClosed() {
     void this._autoExportAndClose().catch(import_log.logUnhandledError);
   }
+  /**
+   * Execute a coordinate-based mouse action and track each decomposed sub-action
+   * (mouse.move/down/up/wheel or a position click) into _trackedActions so it is
+   * exported into the combined JSONL trace. The JSONL field shapes come straight
+   * from common/mouseActions, which is the single source of truth shared with
+   * the export and seeding paths.
+   */
+  async _handleMouseAction(params) {
+    const page = this._browserBackend.context?.currentTab()?.page;
+    const timestamp = Date.now();
+    const pageAlias = this._currentPageAlias;
+    const { result, actions } = await (0, import_mouseActionTool.executeMouseAction)(page, params);
+    if (result.isError)
+      return result;
+    actions.forEach((a, i) => {
+      this._trackedActions.push({
+        toolName: "browser_mouse_action",
+        args: a,
+        code: "",
+        // Stagger timestamps so a decomposed drag keeps its move<down<move<up order.
+        timestamp: timestamp + i,
+        pageAlias
+      });
+    });
+    traceDebug(`Tracked ${actions.length} mouse sub-action(s) for "${params.action}" on ${pageAlias}`);
+    return result;
+  }
+  /**
+   * Load a prior Skyramp trace and replay it against the live browser, honoring
+   * an optional stop point, then seed _trackedActions with the replayed actions
+   * so the model can continue recording and export a combined trace.
+   */
+  async _handleLoadTrace(params) {
+    const stopParams = ["stopAtStep", "stopAtUrl", "stopBefore"].filter((k) => {
+      const v = params[k];
+      return v !== void 0 && v !== "";
+    });
+    if (stopParams.length > 1)
+      return { content: [{ type: "text", text: `### Error
+Pass at most ONE of stopAtStep / stopAtUrl / stopBefore (got ${stopParams.join(", ")}). Omit all three to replay the whole trace.` }], isError: true };
+    let loadedActions;
+    try {
+      loadedActions = await (0, import_skyRampImport.actionsFromPath)(params.path);
+    } catch (e) {
+      return { content: [{ type: "text", text: `### Error
+Failed to load trace from ${params.path}: ${e.message}` }], isError: true };
+    }
+    if (!loadedActions.length)
+      return { content: [{ type: "text", text: `### Error
+No actions found in ${params.path}.` }], isError: true };
+    if (params.dryRun) {
+      const stepList = loadedActions.map((a, i) => (0, import_loadTraceTool.describeStep)(a, i)).join("\n");
+      return {
+        content: [{
+          type: "text",
+          text: `### Trace loaded (dry run)
+${loadedActions.length} steps in ${params.path}. Nothing was replayed.
+
+Steps:
+${stepList}
+
+Call skyramp_load_trace again with stopAtStep / stopAtUrl / stopBefore (or none of them to replay all) to replay.`
+        }]
+      };
+    }
+    try {
+      await this._browserBackend.context.ensureTab();
+    } catch {
+    }
+    let result;
+    try {
+      result = await (0, import_loadTraceTool.replayActions)(loadedActions, { pageForAlias: (alias) => this._pageForAlias(alias) }, params);
+    } catch (e) {
+      return { content: [{ type: "text", text: `### Error
+Replay failed: ${e.message}` }], isError: true };
+    }
+    for (let i = 0; i < result.stopIndex; i++)
+      this._seedTrackedAction(loadedActions[i]);
+    if (result.stopIndex > 0)
+      this._currentPageAlias = loadedActions[result.stopIndex - 1].frame.pageAlias || "page";
+    const remaining = (0, import_loadTraceTool.listStepsFrom)(loadedActions, result.stopIndex);
+    const stoppedNote = (0, import_loadTraceTool.describeStopReason)(result);
+    const errorNote = result.error ? `
+
+\u26A0\uFE0F Replay stopped at step ${result.error.stepIndex} (${result.error.actionName}): ${result.error.message}
+You can continue recording from this point or fix the issue.` : "";
+    return {
+      content: [{
+        type: "text",
+        text: `### Trace replayed
+${result.completedCount} of ${loadedActions.length} steps replayed from ${params.path}. ${stoppedNote}${errorNote}
+
+Remaining steps (NOT replayed):
+${remaining}
+
+Continue recording with browser_* tools, then call skyramp_export_zip to write the combined trace.`
+      }],
+      isError: result.stopReason === "error"
+    };
+  }
+  /**
+   * Resolve a JSONL page alias to a live page. Numeric aliases ('page',
+   * 'pageN') map by tab index; semantic aliases ('popupPage') match by the
+   * popup URL pattern, falling back to the most recently opened tab.
+   */
+  _pageForAlias(alias) {
+    const tabs = this._browserBackend.context?.tabs() ?? [];
+    if (!tabs.length)
+      return void 0;
+    const numeric = alias === "page" ? 0 : /^page(\d+)$/.exec(alias)?.[1];
+    if (numeric !== void 0 && numeric !== null) {
+      const idx = Number(numeric);
+      return (tabs[idx] ?? tabs[tabs.length - 1]).page;
+    }
+    const popupTab = tabs.find((t) => /chrome-extension:\/\/[a-p]{32}\/popup\//.test(t.page.url()));
+    return (popupTab ?? tabs[tabs.length - 1]).page;
+  }
+  /**
+   * Convert a replayed ActionInContext back into a TrackedAction so it merges
+   * with freshly-recorded actions. The export pipeline (buildJsonlContent)
+   * re-derives the JSONL selector from the `code` field, so we regenerate clean
+   * Playwright code from the stored internal: selector via asLocator.
+   */
+  _seedTrackedAction(action) {
+    const a = action.action;
+    const pageAlias = action.frame.pageAlias || "page";
+    if (a.name === "navigate") {
+      this._trackedActions.push({
+        toolName: "browser_navigate",
+        args: { url: a.url },
+        code: "",
+        timestamp: action.startTime,
+        pageAlias
+      });
+      return;
+    }
+    const locatorExpr = a.selector ? (0, import_utils.asLocator)("javascript", a.selector) : "";
+    const seeded = this._seedTrackedActionFields(a, locatorExpr);
+    if (!seeded)
+      return;
+    this._trackedActions.push({
+      ...seeded,
+      timestamp: action.startTime,
+      pageAlias,
+      framePath: action.frame.framePath?.length ? action.frame.framePath : void 0
+    });
+  }
+  /**
+   * Build the { toolName, code, args } triple a seeded (replayed) action must
+   * carry so it round-trips through skyRampExport.buildJsonlContent exactly as
+   * a freshly-recorded action would. toolName, code and args are emitted
+   * together (not via separate mappers) because export keys on all three:
+   * trackedActionToJsonl dispatches on toolName, derives the locator from code,
+   * and reads specific args (checked, values, type). A mismatch silently
+   * mis-exports (e.g. hover as click) or drops the action.
+   *
+   * Code uses single quotes to match the live recorder's format
+   * (extractFillText / extractSelectOptions only match single-quoted calls).
+   * Returns null for unsupported actions so they are skipped, never defaulted.
+   */
+  _seedTrackedActionFields(a, locatorExpr) {
+    const sq = (s) => `'${String(s).replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}'`;
+    if (a.name === "mouse.move" || a.name === "mouse.down" || a.name === "mouse.up" || a.name === "mouse.wheel") {
+      const args = this._seedMouseActionArgs(a);
+      if (!args)
+        return null;
+      return { toolName: "browser_mouse_action", code: "", args };
+    }
+    if (a.name === "click" && a.position && (!a.selector || a.selector === "body"))
+      return { toolName: "browser_mouse_action", code: "", args: { name: "click", selector: "body", position: a.position, button: a.button ?? "left", modifiers: a.modifiers ?? 0, clickCount: a.clickCount ?? 1 } };
+    const SELECTOR_REQUIRED = /* @__PURE__ */ new Set(["click", "hover", "fill", "pressSequentially", "check", "uncheck", "select"]);
+    if (SELECTOR_REQUIRED.has(a.name) && !locatorExpr)
+      return null;
+    const root = a.frameUrlMatch ? `page.frames().find(f => f.url().includes(${sq(a.frameUrlMatch)}))!` : "page";
+    switch (a.name) {
+      case "click": {
+        const isDouble = (a.clickCount ?? 1) > 1;
+        const verb = isDouble ? "dblclick" : "click";
+        const args = {};
+        if (a.button && a.button !== "left")
+          args.button = a.button;
+        const mods = (0, import_loadTraceTool.decodeModifiers)(a.modifiers);
+        if (mods.length)
+          args.modifiers = mods;
+        return { toolName: "browser_click", code: `await ${root}.${locatorExpr}.${verb}();`, args };
+      }
+      case "hover":
+        return { toolName: "browser_hover", code: `await ${root}.${locatorExpr}.hover();`, args: {} };
+      case "fill":
+        return { toolName: "browser_type", code: `await ${root}.${locatorExpr}.fill(${sq(a.text ?? "")});`, args: { text: a.text ?? "" } };
+      case "pressSequentially":
+        return { toolName: "browser_type", code: `await ${root}.${locatorExpr}.pressSequentially(${sq(a.text ?? "")});`, args: { text: a.text ?? "", slowly: true } };
+      case "press": {
+        const args = { key: a.key };
+        const mods = (0, import_loadTraceTool.decodeModifiers)(a.modifiers);
+        if (mods.length)
+          args.modifiers = mods;
+        return { toolName: "browser_press_key", code: "", args };
+      }
+      case "assertApiRequest":
+        return { toolName: "browser_assert_api_request", code: "", args: {} };
+      case "waitForTimeout":
+        return { toolName: "browser_wait_for", code: "", args: { time: (a.duration ?? 0) / 1e3 } };
+      case "check":
+        return { toolName: "browser_set_checked", code: `await ${root}.${locatorExpr}.check();`, args: { checked: true } };
+      case "uncheck":
+        return { toolName: "browser_set_checked", code: `await ${root}.${locatorExpr}.uncheck();`, args: { checked: false } };
+      case "select":
+        return { toolName: "browser_select_option", code: `await ${root}.${locatorExpr}.selectOption(${sq((a.options ?? [])[0] ?? "")});`, args: { values: a.options ?? [] } };
+      case "waitForSelector": {
+        const sel = a.selector ?? "";
+        const m = /^text=(.*)$/.exec(sel);
+        if (!m)
+          return null;
+        return a.state === "hidden" ? { toolName: "browser_wait_for", code: "", args: { textGone: m[1] } } : { toolName: "browser_wait_for", code: "", args: { text: m[1] } };
+      }
+      case "dragAndDrop":
+      case "dragTo": {
+        const srcSel = a.source ?? a.selector;
+        const tgtSel = a.target ?? a.targetSelector;
+        if (!srcSel || !tgtSel)
+          return null;
+        const srcExpr = (0, import_utils.asLocator)("javascript", srcSel);
+        const tgtExpr = (0, import_utils.asLocator)("javascript", tgtSel);
+        return { toolName: "browser_drag", code: `await page.${srcExpr}.dragTo(page.${tgtExpr});`, args: {} };
+      }
+      // Assertions are encoded the same way _handleAssert encodes them, so
+      // assertActionToJsonl in skyRampExport parses them identically. That
+      // parser dispatches on toolName === 'browser_assert' and keys on args.type.
+      // Assertions pass selector/expected as structured args (unambiguous even
+      // when the value contains ':'). assertActionToJsonl reads these directly;
+      // the legacy colon-encoded code string is kept only as a human-readable
+      // breadcrumb / backward-compat fallback.
+      case "assertText":
+        return { toolName: "browser_assert", code: `assertText:${a.selector}:${a.text}:${a.substring ?? true}`, args: { type: "text", selector: a.selector, expected: a.text, substring: a.substring ?? true } };
+      case "assertValue":
+        return { toolName: "browser_assert", code: `assertValue:${a.selector}:${a.value}`, args: { type: "value", selector: a.selector, expected: a.value } };
+      case "assertChecked":
+        return { toolName: "browser_assert", code: `assertChecked:${a.selector}:${!!a.checked}`, args: { type: "checked", selector: a.selector, checked: !!a.checked } };
+      case "assertVisible":
+        return { toolName: "browser_assert", code: `assertVisible:${a.selector}`, args: { type: "visible", selector: a.selector } };
+      default:
+        return null;
+    }
+  }
+  /**
+   * Build the normalized JSONL args for a re-seeded coordinate mouse action
+   * (mouse.move/down/up/wheel), following the MouseJsonlAction contract in
+   * common/mouseActions.ts. Only known fields are emitted (so stray fields from
+   * the loaded trace line are not forwarded), wheel deltas/modifiers default to
+   * 0, and a move/wheel missing its position is rejected (returns null) so the
+   * caller skips it rather than exporting an invalid shape for the Go consumer.
+   */
+  _seedMouseActionArgs(a) {
+    switch (a.name) {
+      case "mouse.move": {
+        if (!a.position)
+          return null;
+        const args = { name: "mouse.move", position: a.position };
+        if (a.steps !== void 0)
+          args.steps = a.steps;
+        return args;
+      }
+      case "mouse.down":
+      case "mouse.up":
+        return a.button && a.button !== "left" ? { name: a.name, button: a.button } : { name: a.name };
+      case "mouse.wheel":
+        if (!a.position)
+          return null;
+        return { name: "mouse.wheel", position: a.position, deltaX: a.deltaX ?? 0, deltaY: a.deltaY ?? 0, modifiers: a.modifiers ?? 0 };
+      default:
+        return null;
+    }
+  }
   /**
    * Handle browser_select_option with automatic fallback for custom dropdowns.
    * 1. Try native selectOption first.
@@ -437,14 +723,26 @@ Could not extract selector from hover result.` }], isError: true };
     }
     const locatorExpr = locatorMatch[1].trim();
     let parsed = this._codeToLocator(locatorExpr);
-    if (!parsed) {
+    const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
+    if (snapResult.isError) {
+      const errText = snapResult.content?.[0]?.type === "text" ? snapResult.content[0].text : "";
       return { content: [{ type: "text", text: `### Assertion Failed
-Could not parse locator: ${locatorExpr}` }], isError: true };
+Could not capture page snapshot to verify the assertion. ${errText}` }], isError: true };
     }
-    const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
     const snapText = snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
     const snapLines = snapText.split("\n");
     const refLine = snapLines.find((l) => l.includes(`[ref=${params.ref}]`)) || "";
+    if (!parsed || parsed.locator.kind === "css") {
+      const fromSnapshot = this._extractLocatorForRef(refLine);
+      if (fromSnapshot) {
+        traceDebug(`Resolved assert selector from snapshot accessible name (hover code was ${parsed ? "brittle CSS" : "unparseable"}: ${locatorExpr})`);
+        parsed = fromSnapshot;
+      }
+    }
+    if (!parsed) {
+      return { content: [{ type: "text", text: `### Assertion Failed
+Could not parse locator: ${locatorExpr}` }], isError: true };
+    }
     const textMatch = refLine.match(/^\s*-\s*\w+\s+"([^"]*)"/);
     const elementText = textMatch?.[1] || "";
     const valueMatch = refLine.match(/\]:\s*(.+)$/);
@@ -473,7 +771,10 @@ Could not parse locator: ${locatorExpr}` }], isError: true };
         const assertName = params.type === "value" ? "assertValue" : "assertText";
         this._trackedActions.push({
           toolName: "browser_assert",
-          args: { type: params.type, ref: params.ref, expected: params.expected },
+          // Pass selector/expected as structured args so assertActionToJsonl can
+          // decode unambiguously (the colon-encoded code below corrupts values
+          // that contain ':', e.g. URLs). The code string is a fallback only.
+          args: { type: params.type, ref: params.ref, selector: parsed.selector, expected: params.expected, ...params.type === "text" ? { substring: params.substring } : {} },
           code: `${assertName}:${parsed.selector}:${params.expected}${params.type === "text" ? ":" + params.substring : ""}`,
           timestamp
         });
@@ -519,6 +820,13 @@ ${details}` }]
     if (ariaRefMatch) {
       return null;
     }
+    const cssMatch = expr.match(/locator\(\s*['"]([#.][^'"]+)['"]\s*\)/);
+    if (cssMatch) {
+      return {
+        selector: cssMatch[1],
+        locator: { kind: "css", body: cssMatch[1], options: {} }
+      };
+    }
     return null;
   }
   /**

package/node_modules/playwright/lib/mcp/test/skyRampExport.js

@@ -226,7 +226,12 @@ function trackedActionToJsonl(action, pageGuid, timestamp) {
     return null;
   }
   if (toolName === "browser_press_key")
-    return JSON.stringify({ name: "press", key: args.key, selector: "", ...base });
+    return JSON.stringify({ name: "press", key: args.key, modifiers: modifiersArrayToMask(args.modifiers), selector: "", ...base });
+  if (toolName === "browser_mouse_action") {
+    if (!args.name)
+      return null;
+    return JSON.stringify({ ...args, ...base });
+  }
   if (!code)
     return null;
   const extracted = extractLocatorFromCode(code);
@@ -304,23 +309,34 @@ function assertActionToJsonl(action, pageGuid, timestamp) {
     signals: [],
     timestamp: String(timestamp),
     pageGuid,
-    pageAlias: DEFAULT_PAGE_ALIAS,
-    framePath: DEFAULT_FRAME_PATH
+    pageAlias: action.pageAlias ?? DEFAULT_PAGE_ALIAS,
+    framePath: action.framePath ?? DEFAULT_FRAME_PATH
   };
-  const parts = code.split(":");
-  const selectorPart = parts[1] || "";
   let selector = "";
   let expected = "";
   let substring = true;
-  if (assertType === "visible") {
-    selector = parts.slice(1).join(":");
-  } else if (assertType === "text") {
-    substring = parts[parts.length - 1] === "true";
-    expected = parts[parts.length - 2] || "";
-    selector = parts.slice(1, parts.length - 2).join(":");
-  } else if (assertType === "value") {
-    expected = parts[parts.length - 1] || "";
-    selector = parts.slice(1, parts.length - 1).join(":");
+  if (args.selector !== void 0) {
+    selector = args.selector;
+    if (assertType === "text") {
+      expected = args.expected ?? "";
+      substring = args.substring !== false;
+    } else if (assertType === "value") {
+      expected = args.expected ?? "";
+    } else if (assertType === "checked") {
+      expected = String(args.checked === true || args.expected === "true" || args.expected === true);
+    }
+  } else {
+    const parts = code.split(":");
+    if (assertType === "visible") {
+      selector = parts.slice(1).join(":");
+    } else if (assertType === "text") {
+      substring = parts[parts.length - 1] === "true";
+      expected = parts[parts.length - 2] || "";
+      selector = parts.slice(1, parts.length - 2).join(":");
+    } else if (assertType === "value" || assertType === "checked") {
+      expected = parts[parts.length - 1] || "";
+      selector = parts.slice(1, parts.length - 1).join(":");
+    }
   }
   const locator = selectorToLocator(selector);
   switch (assertType) {
@@ -330,6 +346,8 @@ function assertActionToJsonl(action, pageGuid, timestamp) {
       return JSON.stringify({ name: "assertVisible", selector, locator, ...base });
     case "value":
       return JSON.stringify({ name: "assertValue", selector, value: expected, locator, ...base });
+    case "checked":
+      return JSON.stringify({ name: "assertChecked", selector, checked: expected === "true", locator, ...base });
     default:
       return null;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",