@metamask/client-mcp-core 0.1.0

package/dist/launcher/extension-readiness.mjs

@@ -0,0 +1,43 @@
+import path from "path";
+/**
+ * Default MetaMask extension readiness configuration.
+ */
+export const DEFAULT_EXTENSION_READINESS_CONFIG = {
+    readySelectors: [
+        '[data-testid="unlock-password"]',
+        '[data-testid="onboarding-create-wallet"]',
+        '[data-testid="onboarding-import-wallet"]',
+        '[data-testid="account-menu-icon"]',
+        '[data-testid="get-started"]',
+        '[data-testid="onboarding-terms-checkbox"]',
+        '[data-testid="onboarding-privacy-policy"]',
+    ],
+    expectedStatesDescription: 'unlock page, onboarding page, or home page',
+};
+/**
+ * Wait for the extension UI to be ready by checking for expected selectors.
+ *
+ * @param deps - Dependencies including page, screenshot directory, and logger
+ * @param config - Configuration with ready selectors to wait for
+ * @param timeout - Maximum time to wait in milliseconds (default: 30000)
+ */
+export async function waitForExtensionUiReady(deps, config = DEFAULT_EXTENSION_READINESS_CONFIG, timeout = 30000) {
+    const { page, screenshotDir, log } = deps;
+    const { readySelectors, expectedStatesDescription } = config;
+    try {
+        await Promise.race(readySelectors.map(async (selector) => page.waitForSelector(selector, { timeout })));
+        log.info('Extension UI is ready');
+    }
+    catch {
+        const currentUrl = page.url();
+        const screenshotPath = path.join(screenshotDir, `ui-ready-failure-${Date.now()}.png`);
+        await page.screenshot({ path: screenshotPath, fullPage: true });
+        log.error(`Debug screenshot saved: ${screenshotPath}`);
+        const expectedStates = expectedStatesDescription ?? 'one of the expected ready states';
+        throw new Error(`Extension UI did not reach expected state within ${timeout}ms. ` +
+            `Current URL: ${currentUrl}. ` +
+            `Expected: ${expectedStates}. ` +
+            `Debug screenshot saved to: ${screenshotPath}`);
+    }
+}
+//# sourceMappingURL=extension-readiness.mjs.map

package/dist/launcher/extension-readiness.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-readiness.mjs","sourceRoot":"","sources":["../../src/launcher/extension-readiness.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,aAAa;AA2BxB;;GAEG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAA6B;IAC1E,cAAc,EAAE;QACd,iCAAiC;QACjC,0CAA0C;QAC1C,0CAA0C;QAC1C,mCAAmC;QACnC,6BAA6B;QAC7B,2CAA2C;QAC3C,2CAA2C;KAC5C;IACD,yBAAyB,EAAE,4CAA4C;CACxE,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAA4B,EAC5B,SAAmC,kCAAkC,EACrE,OAAO,GAAG,KAAK;IAEf,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,cAAc,EAAE,yBAAyB,EAAE,GAAG,MAAM,CAAC;IAE7D,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAChB,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CACpC,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,CAAC,CAC5C,CACF,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAC9B,aAAa,EACb,oBAAoB,IAAI,CAAC,GAAG,EAAE,MAAM,CACrC,CAAC;QACF,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,GAAG,CAAC,KAAK,CAAC,2BAA2B,cAAc,EAAE,CAAC,CAAC;QAEvD,MAAM,cAAc,GAClB,yBAAyB,IAAI,kCAAkC,CAAC;QAElE,MAAM,IAAI,KAAK,CACb,oDAAoD,OAAO,MAAM;YAC/D,gBAAgB,UAAU,IAAI;YAC9B,aAAa,cAAc,IAAI;YAC/B,8BAA8B,cAAc,EAAE,CACjD,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import type { Page } from '@playwright/test';\nimport path from 'path';\n\nexport type ExtensionReadinessDeps = {\n  page: Page;\n  screenshotDir: string;\n  log: {\n    info: (message: string) => void;\n    error: (message: string) => void;\n  };\n};\n\n/**\n * Configuration for extension readiness detection.\n * Allows different extensions to specify their own UI ready selectors.\n */\nexport type ExtensionReadinessConfig = {\n  /**\n   * CSS selectors that indicate the extension UI is ready.\n   * The function waits for ANY of these selectors to appear.\n   */\n  readySelectors: string[];\n  /**\n   * Human-readable description of expected states for error messages.\n   */\n  expectedStatesDescription?: string;\n};\n\n/**\n * Default MetaMask extension readiness configuration.\n */\nexport const DEFAULT_EXTENSION_READINESS_CONFIG: ExtensionReadinessConfig = {\n  readySelectors: [\n    '[data-testid=\"unlock-password\"]',\n    '[data-testid=\"onboarding-create-wallet\"]',\n    '[data-testid=\"onboarding-import-wallet\"]',\n    '[data-testid=\"account-menu-icon\"]',\n    '[data-testid=\"get-started\"]',\n    '[data-testid=\"onboarding-terms-checkbox\"]',\n    '[data-testid=\"onboarding-privacy-policy\"]',\n  ],\n  expectedStatesDescription: 'unlock page, onboarding page, or home page',\n};\n\n/**\n * Wait for the extension UI to be ready by checking for expected selectors.\n *\n * @param deps - Dependencies including page, screenshot directory, and logger\n * @param config - Configuration with ready selectors to wait for\n * @param timeout - Maximum time to wait in milliseconds (default: 30000)\n */\nexport async function waitForExtensionUiReady(\n  deps: ExtensionReadinessDeps,\n  config: ExtensionReadinessConfig = DEFAULT_EXTENSION_READINESS_CONFIG,\n  timeout = 30000,\n): Promise<void> {\n  const { page, screenshotDir, log } = deps;\n  const { readySelectors, expectedStatesDescription } = config;\n\n  try {\n    await Promise.race(\n      readySelectors.map(async (selector) =>\n        page.waitForSelector(selector, { timeout }),\n      ),\n    );\n    log.info('Extension UI is ready');\n  } catch {\n    const currentUrl = page.url();\n    const screenshotPath = path.join(\n      screenshotDir,\n      `ui-ready-failure-${Date.now()}.png`,\n    );\n    await page.screenshot({ path: screenshotPath, fullPage: true });\n    log.error(`Debug screenshot saved: ${screenshotPath}`);\n\n    const expectedStates =\n      expectedStatesDescription ?? 'one of the expected ready states';\n\n    throw new Error(\n      `Extension UI did not reach expected state within ${timeout}ms. ` +\n        `Current URL: ${currentUrl}. ` +\n        `Expected: ${expectedStates}. ` +\n        `Debug screenshot saved to: ${screenshotPath}`,\n    );\n  }\n}\n"]}

package/dist/launcher/index.cjs

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./retry.cjs"), exports);
+__exportStar(require("./console-error-buffer.cjs"), exports);
+__exportStar(require("./extension-readiness.cjs"), exports);
+__exportStar(require("./extension-id-resolver.cjs"), exports);
+//# sourceMappingURL=index.cjs.map

package/dist/launcher/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA2B;AAC3B,6DAA0C;AAC1C,4DAAyC;AACzC,8DAA2C","sourcesContent":["export * from './retry.js';\nexport * from './console-error-buffer.js';\nexport * from './extension-readiness.js';\nexport * from './extension-id-resolver.js';\n"]}

package/dist/launcher/index.d.cts

@@ -0,0 +1,5 @@
+export * from "./retry.cjs";
+export * from "./console-error-buffer.cjs";
+export * from "./extension-readiness.cjs";
+export * from "./extension-id-resolver.cjs";
+//# sourceMappingURL=index.d.cts.map

package/dist/launcher/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAAA,4BAA2B;AAC3B,2CAA0C;AAC1C,0CAAyC;AACzC,4CAA2C"}

package/dist/launcher/index.d.mts

@@ -0,0 +1,5 @@
+export * from "./retry.mjs";
+export * from "./console-error-buffer.mjs";
+export * from "./extension-readiness.mjs";
+export * from "./extension-id-resolver.mjs";
+//# sourceMappingURL=index.d.mts.map

package/dist/launcher/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAAA,4BAA2B;AAC3B,2CAA0C;AAC1C,0CAAyC;AACzC,4CAA2C"}

package/dist/launcher/index.mjs

@@ -0,0 +1,5 @@
+export * from "./retry.mjs";
+export * from "./console-error-buffer.mjs";
+export * from "./extension-readiness.mjs";
+export * from "./extension-id-resolver.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/launcher/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAAA,4BAA2B;AAC3B,2CAA0C;AAC1C,0CAAyC;AACzC,4CAA2C","sourcesContent":["export * from './retry.js';\nexport * from './console-error-buffer.js';\nexport * from './extension-readiness.js';\nexport * from './extension-id-resolver.js';\n"]}

package/dist/launcher/retry.cjs

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delay = delay;
+exports.retryUntil = retryUntil;
+/**
+ * Delay execution for a specified number of milliseconds.
+ *
+ * @param ms - Number of milliseconds to delay
+ */
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry an operation until it succeeds or max attempts are reached.
+ *
+ * @param operation - The async operation to retry
+ * @param isSuccess - Function to determine if the result is successful
+ * @param options - Retry configuration with attempts and delay
+ * @returns The result from the operation
+ */
+async function retryUntil(operation, isSuccess, options) {
+    const { attempts, delayMs } = options;
+    let lastResult;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        lastResult = await operation();
+        if (isSuccess(lastResult)) {
+            return lastResult;
+        }
+        if (attempt < attempts - 1) {
+            await delay(delayMs);
+        }
+    }
+    return lastResult;
+}
+//# sourceMappingURL=retry.cjs.map

package/dist/launcher/retry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.cjs","sourceRoot":"","sources":["../../src/launcher/retry.ts"],"names":[],"mappings":";;AAUA,sBAEC;AAUD,gCAqBC;AAtCD;;;;GAIG;AACI,KAAK,UAAU,KAAK,CAAC,EAAU;IACpC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,UAAU,CAC9B,SAAgC,EAChC,SAAsC,EACtC,OAAqB;IAErB,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEtC,IAAI,UAA8B,CAAC;IAEnC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,UAAU,GAAG,MAAM,SAAS,EAAE,CAAC;QAC/B,IAAI,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,IAAI,OAAO,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,UAAoB,CAAC;AAC9B,CAAC","sourcesContent":["export type RetryOptions = {\n  attempts: number;\n  delayMs: number;\n};\n\n/**\n * Delay execution for a specified number of milliseconds.\n *\n * @param ms - Number of milliseconds to delay\n */\nexport async function delay(ms: number): Promise<void> {\n  await new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Retry an operation until it succeeds or max attempts are reached.\n *\n * @param operation - The async operation to retry\n * @param isSuccess - Function to determine if the result is successful\n * @param options - Retry configuration with attempts and delay\n * @returns The result from the operation\n */\nexport async function retryUntil<Result>(\n  operation: () => Promise<Result>,\n  isSuccess: (result: Result) => boolean,\n  options: RetryOptions,\n): Promise<Result> {\n  const { attempts, delayMs } = options;\n\n  let lastResult: Result | undefined;\n\n  for (let attempt = 0; attempt < attempts; attempt++) {\n    lastResult = await operation();\n    if (isSuccess(lastResult)) {\n      return lastResult;\n    }\n\n    if (attempt < attempts - 1) {\n      await delay(delayMs);\n    }\n  }\n\n  return lastResult as Result;\n}\n"]}

package/dist/launcher/retry.d.cts

@@ -0,0 +1,20 @@
+export type RetryOptions = {
+    attempts: number;
+    delayMs: number;
+};
+/**
+ * Delay execution for a specified number of milliseconds.
+ *
+ * @param ms - Number of milliseconds to delay
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Retry an operation until it succeeds or max attempts are reached.
+ *
+ * @param operation - The async operation to retry
+ * @param isSuccess - Function to determine if the result is successful
+ * @param options - Retry configuration with attempts and delay
+ * @returns The result from the operation
+ */
+export declare function retryUntil<Result>(operation: () => Promise<Result>, isSuccess: (result: Result) => boolean, options: RetryOptions): Promise<Result>;
+//# sourceMappingURL=retry.d.cts.map

package/dist/launcher/retry.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.cts","sourceRoot":"","sources":["../../src/launcher/retry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,MAAM,EACrC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAChC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,EACtC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/launcher/retry.d.mts

@@ -0,0 +1,20 @@
+export type RetryOptions = {
+    attempts: number;
+    delayMs: number;
+};
+/**
+ * Delay execution for a specified number of milliseconds.
+ *
+ * @param ms - Number of milliseconds to delay
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Retry an operation until it succeeds or max attempts are reached.
+ *
+ * @param operation - The async operation to retry
+ * @param isSuccess - Function to determine if the result is successful
+ * @param options - Retry configuration with attempts and delay
+ * @returns The result from the operation
+ */
+export declare function retryUntil<Result>(operation: () => Promise<Result>, isSuccess: (result: Result) => boolean, options: RetryOptions): Promise<Result>;
+//# sourceMappingURL=retry.d.mts.map

package/dist/launcher/retry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.mts","sourceRoot":"","sources":["../../src/launcher/retry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,MAAM,EACrC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAChC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,EACtC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/launcher/retry.mjs

@@ -0,0 +1,31 @@
+/**
+ * Delay execution for a specified number of milliseconds.
+ *
+ * @param ms - Number of milliseconds to delay
+ */
+export async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry an operation until it succeeds or max attempts are reached.
+ *
+ * @param operation - The async operation to retry
+ * @param isSuccess - Function to determine if the result is successful
+ * @param options - Retry configuration with attempts and delay
+ * @returns The result from the operation
+ */
+export async function retryUntil(operation, isSuccess, options) {
+    const { attempts, delayMs } = options;
+    let lastResult;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        lastResult = await operation();
+        if (isSuccess(lastResult)) {
+            return lastResult;
+        }
+        if (attempt < attempts - 1) {
+            await delay(delayMs);
+        }
+    }
+    return lastResult;
+}
+//# sourceMappingURL=retry.mjs.map

package/dist/launcher/retry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.mjs","sourceRoot":"","sources":["../../src/launcher/retry.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU;IACpC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,SAAgC,EAChC,SAAsC,EACtC,OAAqB;IAErB,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEtC,IAAI,UAA8B,CAAC;IAEnC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,UAAU,GAAG,MAAM,SAAS,EAAE,CAAC;QAC/B,IAAI,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,IAAI,OAAO,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,UAAoB,CAAC;AAC9B,CAAC","sourcesContent":["export type RetryOptions = {\n  attempts: number;\n  delayMs: number;\n};\n\n/**\n * Delay execution for a specified number of milliseconds.\n *\n * @param ms - Number of milliseconds to delay\n */\nexport async function delay(ms: number): Promise<void> {\n  await new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Retry an operation until it succeeds or max attempts are reached.\n *\n * @param operation - The async operation to retry\n * @param isSuccess - Function to determine if the result is successful\n * @param options - Retry configuration with attempts and delay\n * @returns The result from the operation\n */\nexport async function retryUntil<Result>(\n  operation: () => Promise<Result>,\n  isSuccess: (result: Result) => boolean,\n  options: RetryOptions,\n): Promise<Result> {\n  const { attempts, delayMs } = options;\n\n  let lastResult: Result | undefined;\n\n  for (let attempt = 0; attempt < attempts; attempt++) {\n    lastResult = await operation();\n    if (isSuccess(lastResult)) {\n      return lastResult;\n    }\n\n    if (attempt < attempts - 1) {\n      await delay(delayMs);\n    }\n  }\n\n  return lastResult as Result;\n}\n"]}

package/dist/mcp-server/constants.cjs

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Constants for MCP server tool operations.
+ * Centralized to ensure consistency and easy tuning.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEXT_PREVIEW_MAX_LENGTH = exports.OBSERVATION_TESTID_LIMIT = exports.DEFAULT_TESTID_LIMIT = exports.DEFAULT_INTERACTION_TIMEOUT_MS = void 0;
+// ============================================================================
+// Timeouts
+// ============================================================================
+/** Default timeout for user interactions (click, type, wait_for) - 15 seconds */
+exports.DEFAULT_INTERACTION_TIMEOUT_MS = 15000;
+// ============================================================================
+// Limits
+// ============================================================================
+/** Default limit for testId collection in discovery tools */
+exports.DEFAULT_TESTID_LIMIT = 150;
+/** Limit for testIds collected during observation (lighter weight) */
+exports.OBSERVATION_TESTID_LIMIT = 50;
+/** Maximum length for text content preview in discovery */
+exports.TEXT_PREVIEW_MAX_LENGTH = 100;
+//# sourceMappingURL=constants.cjs.map

package/dist/mcp-server/constants.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.cjs","sourceRoot":"","sources":["../../src/mcp-server/constants.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,iFAAiF;AACpE,QAAA,8BAA8B,GAAG,KAAK,CAAC;AAEpD,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,6DAA6D;AAChD,QAAA,oBAAoB,GAAG,GAAG,CAAC;AAExC,sEAAsE;AACzD,QAAA,wBAAwB,GAAG,EAAE,CAAC;AAE3C,2DAA2D;AAC9C,QAAA,uBAAuB,GAAG,GAAG,CAAC","sourcesContent":["/**\n * Constants for MCP server tool operations.\n * Centralized to ensure consistency and easy tuning.\n */\n\n// ============================================================================\n// Timeouts\n// ============================================================================\n\n/** Default timeout for user interactions (click, type, wait_for) - 15 seconds */\nexport const DEFAULT_INTERACTION_TIMEOUT_MS = 15000;\n\n// ============================================================================\n// Limits\n// ============================================================================\n\n/** Default limit for testId collection in discovery tools */\nexport const DEFAULT_TESTID_LIMIT = 150;\n\n/** Limit for testIds collected during observation (lighter weight) */\nexport const OBSERVATION_TESTID_LIMIT = 50;\n\n/** Maximum length for text content preview in discovery */\nexport const TEXT_PREVIEW_MAX_LENGTH = 100;\n"]}

package/dist/mcp-server/constants.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Constants for MCP server tool operations.
+ * Centralized to ensure consistency and easy tuning.
+ */
+/** Default timeout for user interactions (click, type, wait_for) - 15 seconds */
+export declare const DEFAULT_INTERACTION_TIMEOUT_MS = 15000;
+/** Default limit for testId collection in discovery tools */
+export declare const DEFAULT_TESTID_LIMIT = 150;
+/** Limit for testIds collected during observation (lighter weight) */
+export declare const OBSERVATION_TESTID_LIMIT = 50;
+/** Maximum length for text content preview in discovery */
+export declare const TEXT_PREVIEW_MAX_LENGTH = 100;
+//# sourceMappingURL=constants.d.cts.map

package/dist/mcp-server/constants.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.cts","sourceRoot":"","sources":["../../src/mcp-server/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,iFAAiF;AACjF,eAAO,MAAM,8BAA8B,QAAQ,CAAC;AAMpD,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,2DAA2D;AAC3D,eAAO,MAAM,uBAAuB,MAAM,CAAC"}

package/dist/mcp-server/constants.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Constants for MCP server tool operations.
+ * Centralized to ensure consistency and easy tuning.
+ */
+/** Default timeout for user interactions (click, type, wait_for) - 15 seconds */
+export declare const DEFAULT_INTERACTION_TIMEOUT_MS = 15000;
+/** Default limit for testId collection in discovery tools */
+export declare const DEFAULT_TESTID_LIMIT = 150;
+/** Limit for testIds collected during observation (lighter weight) */
+export declare const OBSERVATION_TESTID_LIMIT = 50;
+/** Maximum length for text content preview in discovery */
+export declare const TEXT_PREVIEW_MAX_LENGTH = 100;
+//# sourceMappingURL=constants.d.mts.map

package/dist/mcp-server/constants.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.mts","sourceRoot":"","sources":["../../src/mcp-server/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,iFAAiF;AACjF,eAAO,MAAM,8BAA8B,QAAQ,CAAC;AAMpD,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,2DAA2D;AAC3D,eAAO,MAAM,uBAAuB,MAAM,CAAC"}

package/dist/mcp-server/constants.mjs

@@ -0,0 +1,19 @@
+/**
+ * Constants for MCP server tool operations.
+ * Centralized to ensure consistency and easy tuning.
+ */
+// ============================================================================
+// Timeouts
+// ============================================================================
+/** Default timeout for user interactions (click, type, wait_for) - 15 seconds */
+export const DEFAULT_INTERACTION_TIMEOUT_MS = 15000;
+// ============================================================================
+// Limits
+// ============================================================================
+/** Default limit for testId collection in discovery tools */
+export const DEFAULT_TESTID_LIMIT = 150;
+/** Limit for testIds collected during observation (lighter weight) */
+export const OBSERVATION_TESTID_LIMIT = 50;
+/** Maximum length for text content preview in discovery */
+export const TEXT_PREVIEW_MAX_LENGTH = 100;
+//# sourceMappingURL=constants.mjs.map

package/dist/mcp-server/constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.mjs","sourceRoot":"","sources":["../../src/mcp-server/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,iFAAiF;AACjF,MAAM,CAAC,MAAM,8BAA8B,GAAG,KAAK,CAAC;AAEpD,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,sEAAsE;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC","sourcesContent":["/**\n * Constants for MCP server tool operations.\n * Centralized to ensure consistency and easy tuning.\n */\n\n// ============================================================================\n// Timeouts\n// ============================================================================\n\n/** Default timeout for user interactions (click, type, wait_for) - 15 seconds */\nexport const DEFAULT_INTERACTION_TIMEOUT_MS = 15000;\n\n// ============================================================================\n// Limits\n// ============================================================================\n\n/** Default limit for testId collection in discovery tools */\nexport const DEFAULT_TESTID_LIMIT = 150;\n\n/** Limit for testIds collected during observation (lighter weight) */\nexport const OBSERVATION_TESTID_LIMIT = 50;\n\n/** Maximum length for text content preview in discovery */\nexport const TEXT_PREVIEW_MAX_LENGTH = 100;\n"]}

package/dist/mcp-server/discovery.cjs

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAriaSnapshotYaml = parseAriaSnapshotYaml;
+exports.collectTestIds = collectTestIds;
+exports.collectTrimmedA11ySnapshot = collectTrimmedA11ySnapshot;
+exports.resolveTarget = resolveTarget;
+exports.waitForTarget = waitForTarget;
+const constants_js_1 = require("./constants.cjs");
+const types_1 = require("./types/index.cjs");
+const utils_1 = require("./utils/index.cjs");
+const INCLUDED_ROLES_SET = new Set(types_1.INCLUDED_ROLES);
+/**
+ * Regular expression to parse a single ARIA snapshot line descriptor.
+ *
+ * Matches: `role` + optional `"name"` + optional `[attr]` / `[attr=value]` groups
+ *
+ * Examples:
+ *   - `button "Submit"`
+ *   - `heading "Title" [level=1]`
+ *   - `checkbox "Accept" [checked]`
+ *   - `listitem`
+ */
+const ARIA_LINE_RE = /^(?<role>[a-zA-Z]+)(?:\s+"(?<name>(?:[^"\\]|\\.)*)")?(?<attrs>(?:\s+\[[^\]]*\])*)(?<hasChildren>:?)$/u;
+/**
+ * Regular expression to match individual `[key]` or `[key=value]` attribute groups.
+ */
+const ATTR_RE = /\[(?<key>[a-zA-Z]+)(?:=(?<value>[^\]]*))?\]/gu;
+/**
+ * Parse a Playwright ariaSnapshot() YAML string into RawA11yNode[].
+ *
+ * The YAML format emitted by Playwright's `locator.ariaSnapshot()` (v1.49+)
+ * is a line-based, indentation-structured tree where each node line is:
+ *   `- role "name" [attr=value]:` (children follow indented)
+ *   `- role "name" [attr=value]`  (leaf node)
+ *   `- text: some text content`   (text node, ignored for our purposes)
+ *
+ * @param yaml The YAML string returned by Playwright's ariaSnapshot()
+ * @returns Array of parsed RawA11yNode trees
+ */
+function parseAriaSnapshotYaml(yaml) {
+    if (!yaml?.trim()) {
+        return [];
+    }
+    const lines = yaml.split('\n');
+    const roots = [];
+    const stack = [];
+    for (const line of lines) {
+        if (!line.trim()) {
+            continue;
+        }
+        const stripped = line.replace(/^ */u, '');
+        const indent = line.length - stripped.length;
+        if (!stripped.startsWith('- ')) {
+            continue;
+        }
+        const descriptor = stripped.slice(2);
+        if (descriptor.startsWith('text:') || descriptor === 'text') {
+            continue;
+        }
+        if (descriptor.startsWith('/')) {
+            continue;
+        }
+        const node = parseAriaNodeDescriptor(descriptor);
+        if (!node) {
+            continue;
+        }
+        while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+        if (stack.length === 0) {
+            roots.push(node);
+        }
+        else {
+            const parent = stack[stack.length - 1].node;
+            parent.children ?? (parent.children = []);
+            parent.children.push(node);
+        }
+        stack.push({ node, indent });
+    }
+    return roots;
+}
+/**
+ * Parse a single ARIA node descriptor string into a RawA11yNode.
+ *
+ * @param descriptor The descriptor after removing the `- ` prefix, e.g. `button "Submit" [disabled]:`
+ * @returns A parsed node, or null if the descriptor cannot be parsed
+ */
+function parseAriaNodeDescriptor(descriptor) {
+    let desc = descriptor;
+    // Strip trailing `:` (children indicator) or `: text` (inline text value)
+    const trailingColonMatch = desc.match(/^(?<main>(?:[a-zA-Z]+)(?:\s+"(?:[^"\\]|\\.)*")?(?:\s+\[[^\]]*\])*)(?::(?<text>.*))?$/u);
+    if (trailingColonMatch?.groups?.main) {
+        desc = trailingColonMatch.groups.main;
+    }
+    const match = ARIA_LINE_RE.exec(desc);
+    if (!match?.groups) {
+        return null;
+    }
+    const { role } = match.groups;
+    const rawName = match.groups.name;
+    const node = { role };
+    if (rawName !== undefined) {
+        node.name = rawName.replace(/\\"/gu, '"').replace(/\\\\/gu, '\\');
+    }
+    const attrsStr = match.groups.attrs;
+    if (attrsStr) {
+        let attrMatch;
+        ATTR_RE.lastIndex = 0;
+        while ((attrMatch = ATTR_RE.exec(attrsStr)) !== null) {
+            const key = attrMatch.groups?.key;
+            const value = attrMatch.groups?.value;
+            switch (key) {
+                case 'disabled':
+                    node.disabled = value !== 'false';
+                    break;
+                case 'checked':
+                    if (value === 'mixed') {
+                        node.checked = 'mixed';
+                    }
+                    else {
+                        node.checked = value !== 'false';
+                    }
+                    break;
+                case 'expanded':
+                    node.expanded = value !== 'false';
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+    return node;
+}
+/**
+ * Collect all visible test IDs from the current page.
+ *
+ * @param page The Playwright page to scan for test IDs
+ * @param limit Maximum number of test IDs to return (default: 150)
+ * @returns Array of test ID items with visibility and text content
+ */
+async function collectTestIds(page, limit = 150) {
+    await page.waitForLoadState('domcontentloaded').catch(() => undefined);
+    const locators = await page.locator('[data-testid]').all();
+    const results = [];
+    for (const locator of locators) {
+        if (results.length >= limit) {
+            break;
+        }
+        try {
+            const testId = await locator.getAttribute('data-testid');
+            if (!testId) {
+                continue;
+            }
+            const isVisible = await locator.isVisible().catch(() => false);
+            const textContent = await locator
+                .textContent()
+                .then((text) => text?.trim().substring(0, constants_js_1.TEXT_PREVIEW_MAX_LENGTH) ?? undefined)
+                .catch(() => undefined);
+            results.push({
+                testId,
+                tag: 'element',
+                text: textContent,
+                visible: isVisible,
+            });
+        }
+        catch (error) {
+            (0, utils_1.debugWarn)('discovery.collectTestIds', error);
+            continue;
+        }
+    }
+    return results;
+}
+/**
+ * Collect a trimmed accessibility tree snapshot with deterministic refs.
+ *
+ * @param page The Playwright page to snapshot
+ * @param rootSelector Optional CSS selector to scope the snapshot to a specific element
+ * @returns Object containing trimmed accessibility nodes and a reference map (e1, e2, etc.)
+ */
+async function collectTrimmedA11ySnapshot(page, rootSelector) {
+    const locator = rootSelector
+        ? page.locator(rootSelector).first()
+        : page.locator('body').first();
+    const snapshotYaml = await locator.ariaSnapshot();
+    if (!snapshotYaml) {
+        return { nodes: [], refMap: new Map() };
+    }
+    const parsedRoots = parseAriaSnapshotYaml(snapshotYaml);
+    if (parsedRoots.length === 0) {
+        return { nodes: [], refMap: new Map() };
+    }
+    const trimmedNodes = [];
+    const refMap = new Map();
+    let refCounter = 1;
+    /**
+     * Recursively traverse accessibility tree and collect included roles.
+     *
+     * @param node The current accessibility node to process
+     * @param ancestorPath The path of ancestor nodes for context
+     */
+    function traverseNode(node, ancestorPath) {
+        const role = node.role?.toLowerCase() ?? '';
+        const name = node.name ?? '';
+        if (INCLUDED_ROLES_SET.has(role)) {
+            const ref = `e${refCounter}`;
+            refCounter += 1;
+            const currentPath = [...ancestorPath];
+            if (role === 'dialog' || role === 'heading') {
+                currentPath.push(`${role}:${name}`);
+            }
+            const trimmedNode = {
+                ref,
+                role,
+                name,
+                path: currentPath,
+            };
+            if (node.disabled !== undefined) {
+                trimmedNode.disabled = node.disabled;
+            }
+            if (node.checked !== undefined) {
+                trimmedNode.checked = node.checked === true;
+            }
+            if (node.expanded !== undefined) {
+                trimmedNode.expanded = node.expanded;
+            }
+            trimmedNodes.push(trimmedNode);
+            const selector = buildA11ySelector(role, name);
+            refMap.set(ref, selector);
+        }
+        const updatedPath = role === 'dialog' || role === 'heading'
+            ? [...ancestorPath, `${role}:${name}`]
+            : ancestorPath;
+        if (node.children) {
+            for (const child of node.children) {
+                traverseNode(child, updatedPath);
+            }
+        }
+    }
+    for (const root of parsedRoots) {
+        traverseNode(root, []);
+    }
+    return { nodes: trimmedNodes, refMap };
+}
+/**
+ * Build an accessibility selector string from role and name.
+ *
+ * @param role The ARIA role for the selector
+ * @param name The accessible name to match
+ * @returns Formatted selector string (e.g., "role=button[name=\"Click me\"]")
+ */
+function buildA11ySelector(role, name) {
+    const escapedName = name.replace(/"/gu, '\\"');
+    return `role=${role}[name="${escapedName}"]`;
+}
+/**
+ * Resolve a target element to a Playwright Locator.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @returns Playwright Locator for the resolved element
+ */
+async function resolveTarget(page, targetType, targetValue, refMap) {
+    switch (targetType) {
+        case 'a11yRef': {
+            const selector = refMap.get(targetValue);
+            if (!selector) {
+                throw new Error(`Unknown a11yRef: ${targetValue}. ` +
+                    `Available refs: ${Array.from(refMap.keys()).join(', ')}`);
+            }
+            return page.locator(selector);
+        }
+        case 'testId':
+            return page.locator(`[data-testid="${targetValue}"]`);
+        case 'selector':
+            return page.locator(targetValue);
+        default: {
+            const exhaustiveCheck = targetType;
+            throw new Error(`Unknown target type: ${exhaustiveCheck}`);
+        }
+    }
+}
+/**
+ * Wait for a target element to become visible.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @param timeoutMs Maximum time to wait in milliseconds
+ * @returns Playwright Locator for the visible element
+ */
+async function waitForTarget(page, targetType, targetValue, refMap, timeoutMs) {
+    const locator = await resolveTarget(page, targetType, targetValue, refMap);
+    await locator.waitFor({ state: 'visible', timeout: timeoutMs });
+    return locator;
+}
+//# sourceMappingURL=discovery.cjs.map