@metamask/client-mcp-core 0.1.0

package/dist/mcp-server/session-manager.d.mts

@@ -0,0 +1,240 @@
+/**
+ * Generic Session Manager Interface for Browser Extension MCP Servers.
+ *
+ * This module defines the interface that concrete session managers must implement.
+ * The interface abstracts browser session management, page tracking, and extension state.
+ *
+ * Extension-specific implementations (e.g., MetaMaskSessionManager) should implement
+ * this interface and be injected into the core tool handlers.
+ */
+import type { Page, BrowserContext } from "@playwright/test";
+import type { TabRole, SessionState, SessionMetadata } from "./types/index.mjs";
+import type { EnvironmentMode } from "../capabilities/context.mjs";
+import type { ExtensionState, BuildCapability, FixtureCapability, ChainCapability, ContractSeedingCapability, StateSnapshotCapability, ScreenshotResult } from "../capabilities/types.mjs";
+/**
+ * Represents a tracked browser page with its role and URL.
+ */
+export type TrackedPage = {
+    role: TabRole;
+    url: string;
+    page: Page;
+};
+/**
+ * Configuration for launching a new browser session.
+ */
+export type SessionLaunchInput = {
+    /** State initialization mode */
+    stateMode?: 'default' | 'onboarding' | 'custom';
+    /** Name of a preset fixture to use when stateMode is 'custom' */
+    fixturePreset?: string;
+    /** Custom fixture data when stateMode is 'custom' */
+    fixture?: Record<string, unknown>;
+    /** Goal description for this session (used in knowledge store) */
+    goal?: string;
+    /** Flow tags for categorizing this session */
+    flowTags?: string[];
+    /** Free-form tags for ad-hoc filtering */
+    tags?: string[];
+    /** Path to extension directory */
+    extensionPath?: string;
+    /** Whether to auto-build extension if not found */
+    autoBuild?: boolean;
+    /** Slow down actions for debugging (ms) */
+    slowMo?: number;
+    /** Port configuration */
+    ports?: {
+        anvil?: number;
+        fixtureServer?: number;
+    };
+    /** Smart contracts to deploy on launch */
+    seedContracts?: string[];
+};
+/**
+ * Result of launching a new session.
+ */
+export type SessionLaunchResult = {
+    sessionId: string;
+    extensionId: string;
+    state: ExtensionState;
+};
+/**
+ * Screenshot options.
+ */
+export type SessionScreenshotOptions = {
+    name: string;
+    fullPage?: boolean;
+    selector?: string;
+};
+/**
+ * Interface for session manager implementations.
+ *
+ * This interface defines the contract that extension-specific session managers
+ * must fulfill. Tool handlers depend on this interface, allowing them to work
+ * with any compliant session manager implementation.
+ */
+export type ISessionManager = {
+    /**
+     * Check if there is an active session.
+     */
+    hasActiveSession(): boolean;
+    /**
+     * Get the current session ID, or undefined if no session.
+     */
+    getSessionId(): string | undefined;
+    /**
+     * Get the current session state.
+     */
+    getSessionState(): SessionState | undefined;
+    /**
+     * Get the current session metadata.
+     */
+    getSessionMetadata(): SessionMetadata | undefined;
+    /**
+     * Launch a new browser session.
+     *
+     * @throws If a session is already active
+     */
+    launch(input: SessionLaunchInput): Promise<SessionLaunchResult>;
+    /**
+     * Clean up the current session (browser, services, etc.).
+     *
+     * @returns true if cleanup was performed, false if no session was active
+     */
+    cleanup(): Promise<boolean>;
+    /**
+     * Get the current active page.
+     *
+     * @throws If no active session
+     */
+    getPage(): Page;
+    /**
+     * Set the active page for subsequent interactions.
+     */
+    setActivePage(page: Page): void;
+    /**
+     * Get all tracked pages in the current session.
+     */
+    getTrackedPages(): TrackedPage[];
+    /**
+     * Classify a page's role based on its URL.
+     */
+    classifyPageRole(page: Page, extensionId?: string): TabRole;
+    /**
+     * Get the browser context.
+     *
+     * @throws If no active session
+     */
+    getContext(): BrowserContext;
+    /**
+     * Get the current extension state.
+     *
+     * @throws If no active session
+     */
+    getExtensionState(): Promise<ExtensionState>;
+    /**
+     * Set the accessibility reference map (e1 -> selector).
+     */
+    setRefMap(map: Map<string, string>): void;
+    /**
+     * Get the current accessibility reference map.
+     */
+    getRefMap(): Map<string, string>;
+    /**
+     * Clear the accessibility reference map.
+     */
+    clearRefMap(): void;
+    /**
+     * Resolve an a11y ref (e.g., "e5") to a selector.
+     */
+    resolveA11yRef(ref: string): string | undefined;
+    /**
+     * Navigate to the extension home page.
+     */
+    navigateToHome(): Promise<void>;
+    /**
+     * Navigate to the extension settings page.
+     */
+    navigateToSettings(): Promise<void>;
+    /**
+     * Navigate to an external URL (opens new tab).
+     */
+    navigateToUrl(url: string): Promise<Page>;
+    /**
+     * Navigate to the notification page.
+     */
+    navigateToNotification(): Promise<Page>;
+    /**
+     * Wait for a notification page to appear.
+     */
+    waitForNotificationPage(timeoutMs: number): Promise<Page>;
+    /**
+     * Take a screenshot of the current page.
+     */
+    screenshot(options: SessionScreenshotOptions): Promise<ScreenshotResult>;
+    /**
+     * Get the build capability (if available).
+     */
+    getBuildCapability(): BuildCapability | undefined;
+    /**
+     * Get the fixture capability (if available).
+     */
+    getFixtureCapability(): FixtureCapability | undefined;
+    /**
+     * Get the chain capability (if available).
+     */
+    getChainCapability(): ChainCapability | undefined;
+    /**
+     * Get the contract seeding capability (if available).
+     */
+    getContractSeedingCapability(): ContractSeedingCapability | undefined;
+    /**
+     * Get the state snapshot capability (if available).
+     */
+    getStateSnapshotCapability(): StateSnapshotCapability | undefined;
+    /**
+     * Get the current environment mode.
+     *
+     * @returns 'e2e' for testing environment, 'prod' for production-like environment
+     */
+    getEnvironmentMode(): EnvironmentMode;
+    /**
+     * Set the current context (e2e or prod).
+     *
+     * @throws Error with code MM_CONTEXT_SWITCH_BLOCKED if session is active
+     */
+    setContext(context: 'e2e' | 'prod'): void;
+    /**
+     * Get current context information.
+     */
+    getContextInfo(): {
+        currentContext: 'e2e' | 'prod';
+        hasActiveSession: boolean;
+        sessionId: string | null;
+        capabilities: {
+            available: string[];
+        };
+        canSwitchContext: boolean;
+    };
+};
+/**
+ * Set the session manager instance.
+ *
+ * This should be called by extension-specific code during server initialization.
+ *
+ * @param manager The session manager implementation to inject
+ */
+export declare function setSessionManager(manager: ISessionManager): void;
+/**
+ * Get the session manager instance.
+ *
+ * @throws Error if no session manager has been set
+ * @returns The session manager instance
+ */
+export declare function getSessionManager(): ISessionManager;
+/**
+ * Check if a session manager has been set.
+ *
+ * @returns True if a session manager is set, false otherwise
+ */
+export declare function hasSessionManager(): boolean;
+//# sourceMappingURL=session-manager.d.mts.map

package/dist/mcp-server/session-manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.mts","sourceRoot":"","sources":["../../src/mcp-server/session-manager.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/session-manager.mjs

@@ -0,0 +1,48 @@
+/**
+ * Generic Session Manager Interface for Browser Extension MCP Servers.
+ *
+ * This module defines the interface that concrete session managers must implement.
+ * The interface abstracts browser session management, page tracking, and extension state.
+ *
+ * Extension-specific implementations (e.g., MetaMaskSessionManager) should implement
+ * this interface and be injected into the core tool handlers.
+ */
+/**
+ * Session manager instance holder.
+ *
+ * In the core package, this is undefined by default.
+ * Extension implementations should call setSessionManager() to inject
+ * their concrete implementation.
+ */
+let _sessionManager;
+/**
+ * Set the session manager instance.
+ *
+ * This should be called by extension-specific code during server initialization.
+ *
+ * @param manager The session manager implementation to inject
+ */
+export function setSessionManager(manager) {
+    _sessionManager = manager;
+}
+/**
+ * Get the session manager instance.
+ *
+ * @throws Error if no session manager has been set
+ * @returns The session manager instance
+ */
+export function getSessionManager() {
+    if (!_sessionManager) {
+        throw new Error('Session manager not initialized. Call setSessionManager() first.');
+    }
+    return _sessionManager;
+}
+/**
+ * Check if a session manager has been set.
+ *
+ * @returns True if a session manager is set, false otherwise
+ */
+export function hasSessionManager() {
+    return _sessionManager !== undefined;
+}
+//# sourceMappingURL=session-manager.mjs.map

package/dist/mcp-server/session-manager.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.mjs","sourceRoot":"","sources":["../../src/mcp-server/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+RH;;;;;;GAMG;AACH,IAAI,eAA4C,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAwB;IACxD,eAAe,GAAG,OAAO,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,kEAAkE,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,eAAe,KAAK,SAAS,CAAC;AACvC,CAAC","sourcesContent":["/**\n * Generic Session Manager Interface for Browser Extension MCP Servers.\n *\n * This module defines the interface that concrete session managers must implement.\n * The interface abstracts browser session management, page tracking, and extension state.\n *\n * Extension-specific implementations (e.g., MetaMaskSessionManager) should implement\n * this interface and be injected into the core tool handlers.\n */\n\nimport type { Page, BrowserContext } from '@playwright/test';\n\nimport type { TabRole, SessionState, SessionMetadata } from './types';\nimport type { EnvironmentMode } from '../capabilities/context.js';\nimport type {\n  ExtensionState,\n  BuildCapability,\n  FixtureCapability,\n  ChainCapability,\n  ContractSeedingCapability,\n  StateSnapshotCapability,\n  ScreenshotResult,\n} from '../capabilities/types.js';\n\n/**\n * Represents a tracked browser page with its role and URL.\n */\nexport type TrackedPage = {\n  role: TabRole;\n  url: string;\n  page: Page;\n};\n\n/**\n * Configuration for launching a new browser session.\n */\nexport type SessionLaunchInput = {\n  /** State initialization mode */\n  stateMode?: 'default' | 'onboarding' | 'custom';\n  /** Name of a preset fixture to use when stateMode is 'custom' */\n  fixturePreset?: string;\n  /** Custom fixture data when stateMode is 'custom' */\n  fixture?: Record<string, unknown>;\n  /** Goal description for this session (used in knowledge store) */\n  goal?: string;\n  /** Flow tags for categorizing this session */\n  flowTags?: string[];\n  /** Free-form tags for ad-hoc filtering */\n  tags?: string[];\n  /** Path to extension directory */\n  extensionPath?: string;\n  /** Whether to auto-build extension if not found */\n  autoBuild?: boolean;\n  /** Slow down actions for debugging (ms) */\n  slowMo?: number;\n  /** Port configuration */\n  ports?: {\n    anvil?: number;\n    fixtureServer?: number;\n  };\n  /** Smart contracts to deploy on launch */\n  seedContracts?: string[];\n};\n\n/**\n * Result of launching a new session.\n */\nexport type SessionLaunchResult = {\n  sessionId: string;\n  extensionId: string;\n  state: ExtensionState;\n};\n\n/**\n * Screenshot options.\n */\nexport type SessionScreenshotOptions = {\n  name: string;\n  fullPage?: boolean;\n  selector?: string;\n};\n\n/**\n * Interface for session manager implementations.\n *\n * This interface defines the contract that extension-specific session managers\n * must fulfill. Tool handlers depend on this interface, allowing them to work\n * with any compliant session manager implementation.\n */\nexport type ISessionManager = {\n  // -----------------------------------------------------------------------------\n  // Session Lifecycle\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Check if there is an active session.\n   */\n  hasActiveSession(): boolean;\n\n  /**\n   * Get the current session ID, or undefined if no session.\n   */\n  getSessionId(): string | undefined;\n\n  /**\n   * Get the current session state.\n   */\n  getSessionState(): SessionState | undefined;\n\n  /**\n   * Get the current session metadata.\n   */\n  getSessionMetadata(): SessionMetadata | undefined;\n\n  /**\n   * Launch a new browser session.\n   *\n   * @throws If a session is already active\n   */\n  launch(input: SessionLaunchInput): Promise<SessionLaunchResult>;\n\n  /**\n   * Clean up the current session (browser, services, etc.).\n   *\n   * @returns true if cleanup was performed, false if no session was active\n   */\n  cleanup(): Promise<boolean>;\n\n  // -----------------------------------------------------------------------------\n  // Page Management\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Get the current active page.\n   *\n   * @throws If no active session\n   */\n  getPage(): Page;\n\n  /**\n   * Set the active page for subsequent interactions.\n   */\n  setActivePage(page: Page): void;\n\n  /**\n   * Get all tracked pages in the current session.\n   */\n  getTrackedPages(): TrackedPage[];\n\n  /**\n   * Classify a page's role based on its URL.\n   */\n  classifyPageRole(page: Page, extensionId?: string): TabRole;\n\n  /**\n   * Get the browser context.\n   *\n   * @throws If no active session\n   */\n  getContext(): BrowserContext;\n\n  // -----------------------------------------------------------------------------\n  // Extension State\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Get the current extension state.\n   *\n   * @throws If no active session\n   */\n  getExtensionState(): Promise<ExtensionState>;\n\n  // -----------------------------------------------------------------------------\n  // A11y Reference Map\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Set the accessibility reference map (e1 -> selector).\n   */\n  setRefMap(map: Map<string, string>): void;\n\n  /**\n   * Get the current accessibility reference map.\n   */\n  getRefMap(): Map<string, string>;\n\n  /**\n   * Clear the accessibility reference map.\n   */\n  clearRefMap(): void;\n\n  /**\n   * Resolve an a11y ref (e.g., \"e5\") to a selector.\n   */\n  resolveA11yRef(ref: string): string | undefined;\n\n  // -----------------------------------------------------------------------------\n  // Navigation\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Navigate to the extension home page.\n   */\n  navigateToHome(): Promise<void>;\n\n  /**\n   * Navigate to the extension settings page.\n   */\n  navigateToSettings(): Promise<void>;\n\n  /**\n   * Navigate to an external URL (opens new tab).\n   */\n  navigateToUrl(url: string): Promise<Page>;\n\n  /**\n   * Navigate to the notification page.\n   */\n  navigateToNotification(): Promise<Page>;\n\n  /**\n   * Wait for a notification page to appear.\n   */\n  waitForNotificationPage(timeoutMs: number): Promise<Page>;\n\n  // -----------------------------------------------------------------------------\n  // Screenshots\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Take a screenshot of the current page.\n   */\n  screenshot(options: SessionScreenshotOptions): Promise<ScreenshotResult>;\n\n  // -----------------------------------------------------------------------------\n  // Capabilities (Optional - Extension-Specific)\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Get the build capability (if available).\n   */\n  getBuildCapability(): BuildCapability | undefined;\n\n  /**\n   * Get the fixture capability (if available).\n   */\n  getFixtureCapability(): FixtureCapability | undefined;\n\n  /**\n   * Get the chain capability (if available).\n   */\n  getChainCapability(): ChainCapability | undefined;\n\n  /**\n   * Get the contract seeding capability (if available).\n   */\n  getContractSeedingCapability(): ContractSeedingCapability | undefined;\n\n  /**\n   * Get the state snapshot capability (if available).\n   */\n  getStateSnapshotCapability(): StateSnapshotCapability | undefined;\n\n  // -----------------------------------------------------------------------------\n  // Environment Configuration\n  // -----------------------------------------------------------------------------\n\n  /**\n   * Get the current environment mode.\n   *\n   * @returns 'e2e' for testing environment, 'prod' for production-like environment\n   */\n  getEnvironmentMode(): EnvironmentMode;\n\n  /**\n   * Set the current context (e2e or prod).\n   *\n   * @throws Error with code MM_CONTEXT_SWITCH_BLOCKED if session is active\n   */\n  setContext(context: 'e2e' | 'prod'): void;\n\n  /**\n   * Get current context information.\n   */\n  getContextInfo(): {\n    currentContext: 'e2e' | 'prod';\n    hasActiveSession: boolean;\n    sessionId: string | null;\n    capabilities: {\n      available: string[];\n    };\n    canSwitchContext: boolean;\n  };\n};\n\n/**\n * Session manager instance holder.\n *\n * In the core package, this is undefined by default.\n * Extension implementations should call setSessionManager() to inject\n * their concrete implementation.\n */\nlet _sessionManager: ISessionManager | undefined;\n\n/**\n * Set the session manager instance.\n *\n * This should be called by extension-specific code during server initialization.\n *\n * @param manager The session manager implementation to inject\n */\nexport function setSessionManager(manager: ISessionManager): void {\n  _sessionManager = manager;\n}\n\n/**\n * Get the session manager instance.\n *\n * @throws Error if no session manager has been set\n * @returns The session manager instance\n */\nexport function getSessionManager(): ISessionManager {\n  if (!_sessionManager) {\n    throw new Error(\n      'Session manager not initialized. Call setSessionManager() first.',\n    );\n  }\n  return _sessionManager;\n}\n\n/**\n * Check if a session manager has been set.\n *\n * @returns True if a session manager is set, false otherwise\n */\nexport function hasSessionManager(): boolean {\n  return _sessionManager !== undefined;\n}\n"]}

package/dist/mcp-server/test-utils/flush-promises.cjs

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flushPromises = flushPromises;
+const scheduler = typeof setImmediate === 'function' ? setImmediate : setTimeout;
+async function flushPromises() {
+    return new Promise((resolve) => {
+        scheduler(resolve, 0);
+    });
+}
+//# sourceMappingURL=flush-promises.cjs.map

package/dist/mcp-server/test-utils/flush-promises.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-promises.cjs","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/flush-promises.ts"],"names":[],"mappings":";;AAGA,sCAIC;AAPD,MAAM,SAAS,GACb,OAAO,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;AAE1D,KAAK,UAAU,aAAa;IACjC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["const scheduler =\n  typeof setImmediate === 'function' ? setImmediate : setTimeout;\n\nexport async function flushPromises() {\n  return new Promise((resolve) => {\n    scheduler(resolve, 0);\n  });\n}\n"]}

package/dist/mcp-server/test-utils/flush-promises.d.cts

@@ -0,0 +1,2 @@
+export declare function flushPromises(): Promise<unknown>;
+//# sourceMappingURL=flush-promises.d.cts.map

package/dist/mcp-server/test-utils/flush-promises.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-promises.d.cts","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/flush-promises.ts"],"names":[],"mappings":"AAGA,wBAAsB,aAAa,qBAIlC"}

package/dist/mcp-server/test-utils/flush-promises.d.mts

@@ -0,0 +1,2 @@
+export declare function flushPromises(): Promise<unknown>;
+//# sourceMappingURL=flush-promises.d.mts.map

package/dist/mcp-server/test-utils/flush-promises.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-promises.d.mts","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/flush-promises.ts"],"names":[],"mappings":"AAGA,wBAAsB,aAAa,qBAIlC"}

package/dist/mcp-server/test-utils/flush-promises.mjs

@@ -0,0 +1,7 @@
+const scheduler = typeof setImmediate === 'function' ? setImmediate : setTimeout;
+export async function flushPromises() {
+    return new Promise((resolve) => {
+        scheduler(resolve, 0);
+    });
+}
+//# sourceMappingURL=flush-promises.mjs.map

package/dist/mcp-server/test-utils/flush-promises.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-promises.mjs","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/flush-promises.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GACb,OAAO,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;AAEjE,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["const scheduler =\n  typeof setImmediate === 'function' ? setImmediate : setTimeout;\n\nexport async function flushPromises() {\n  return new Promise((resolve) => {\n    scheduler(resolve, 0);\n  });\n}\n"]}

package/dist/mcp-server/test-utils/index.cjs

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flushPromises = exports.createMockBrowserContext = exports.createMockLocator = exports.createMockPage = exports.createMockKnowledgeStore = exports.createMockSessionManager = void 0;
+var mock_factories_js_1 = require("./mock-factories.cjs");
+Object.defineProperty(exports, "createMockSessionManager", { enumerable: true, get: function () { return mock_factories_js_1.createMockSessionManager; } });
+Object.defineProperty(exports, "createMockKnowledgeStore", { enumerable: true, get: function () { return mock_factories_js_1.createMockKnowledgeStore; } });
+var mock_playwright_js_1 = require("./mock-playwright.cjs");
+Object.defineProperty(exports, "createMockPage", { enumerable: true, get: function () { return mock_playwright_js_1.createMockPage; } });
+Object.defineProperty(exports, "createMockLocator", { enumerable: true, get: function () { return mock_playwright_js_1.createMockLocator; } });
+Object.defineProperty(exports, "createMockBrowserContext", { enumerable: true, get: function () { return mock_playwright_js_1.createMockBrowserContext; } });
+var flush_promises_js_1 = require("./flush-promises.cjs");
+Object.defineProperty(exports, "flushPromises", { enumerable: true, get: function () { return flush_promises_js_1.flushPromises; } });
+//# sourceMappingURL=index.cjs.map

package/dist/mcp-server/test-utils/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/index.ts"],"names":[],"mappings":";;;AAAA,0DAK6B;AAJ3B,6HAAA,wBAAwB,OAAA;AACxB,6HAAA,wBAAwB,OAAA;AAK1B,4DAO8B;AAN5B,oHAAA,cAAc,OAAA;AACd,uHAAA,iBAAiB,OAAA;AACjB,8HAAA,wBAAwB,OAAA;AAM1B,0DAAoD;AAA3C,kHAAA,aAAa,OAAA","sourcesContent":["export {\n  createMockSessionManager,\n  createMockKnowledgeStore,\n  type MockSessionManagerOptions,\n  type MockKnowledgeStoreOptions,\n} from './mock-factories.js';\n\nexport {\n  createMockPage,\n  createMockLocator,\n  createMockBrowserContext,\n  type MockPageOptions,\n  type MockLocatorOptions,\n  type MockBrowserContextOptions,\n} from './mock-playwright.js';\n\nexport { flushPromises } from './flush-promises.js';\n"]}

package/dist/mcp-server/test-utils/index.d.cts

@@ -0,0 +1,4 @@
+export { createMockSessionManager, createMockKnowledgeStore, type MockSessionManagerOptions, type MockKnowledgeStoreOptions, } from "./mock-factories.cjs";
+export { createMockPage, createMockLocator, createMockBrowserContext, type MockPageOptions, type MockLocatorOptions, type MockBrowserContextOptions, } from "./mock-playwright.cjs";
+export { flushPromises } from "./flush-promises.cjs";
+//# sourceMappingURL=index.d.cts.map

package/dist/mcp-server/test-utils/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,GAC/B,6BAA4B;AAE7B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,8BAA6B;AAE9B,OAAO,EAAE,aAAa,EAAE,6BAA4B"}

package/dist/mcp-server/test-utils/index.d.mts

@@ -0,0 +1,4 @@
+export { createMockSessionManager, createMockKnowledgeStore, type MockSessionManagerOptions, type MockKnowledgeStoreOptions, } from "./mock-factories.mjs";
+export { createMockPage, createMockLocator, createMockBrowserContext, type MockPageOptions, type MockLocatorOptions, type MockBrowserContextOptions, } from "./mock-playwright.mjs";
+export { flushPromises } from "./flush-promises.mjs";
+//# sourceMappingURL=index.d.mts.map

package/dist/mcp-server/test-utils/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,GAC/B,6BAA4B;AAE7B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,8BAA6B;AAE9B,OAAO,EAAE,aAAa,EAAE,6BAA4B"}

package/dist/mcp-server/test-utils/index.mjs

@@ -0,0 +1,4 @@
+export { createMockSessionManager, createMockKnowledgeStore } from "./mock-factories.mjs";
+export { createMockPage, createMockLocator, createMockBrowserContext } from "./mock-playwright.mjs";
+export { flushPromises } from "./flush-promises.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/mcp-server/test-utils/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EAGzB,6BAA4B;AAE7B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,EAIzB,8BAA6B;AAE9B,OAAO,EAAE,aAAa,EAAE,6BAA4B","sourcesContent":["export {\n  createMockSessionManager,\n  createMockKnowledgeStore,\n  type MockSessionManagerOptions,\n  type MockKnowledgeStoreOptions,\n} from './mock-factories.js';\n\nexport {\n  createMockPage,\n  createMockLocator,\n  createMockBrowserContext,\n  type MockPageOptions,\n  type MockLocatorOptions,\n  type MockBrowserContextOptions,\n} from './mock-playwright.js';\n\nexport { flushPromises } from './flush-promises.js';\n"]}

package/dist/mcp-server/test-utils/mock-factories.cjs

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Shared mock factory utilities for unit testing.
+ *
+ * Provides factory functions that return fresh mock instances following MetaMask testing guidelines:
+ * - Each factory call returns NEW object instances (test isolation)
+ * - Each factory creates fresh vi.fn() mocks (never reused)
+ * - Factories accept options for customization
+ * - Sensible defaults so most tests need no options
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMockSessionManager = createMockSessionManager;
+exports.createMockKnowledgeStore = createMockKnowledgeStore;
+const vitest_1 = require("vitest");
+/**
+ * Create a fresh mock ISessionManager instance.
+ *
+ * Each call returns a NEW object with fresh vi.fn() mocks.
+ * Follows the pattern from session-manager.test.ts:15-48.
+ *
+ * @param options - Customize mock behavior
+ * @returns Fresh ISessionManager mock
+ */
+function createMockSessionManager(options = {}) {
+    return {
+        // Session Lifecycle
+        hasActiveSession: vitest_1.vi.fn().mockReturnValue(options.hasActive ?? false),
+        getSessionId: vitest_1.vi.fn().mockReturnValue(options.sessionId ?? undefined),
+        getSessionState: vitest_1.vi.fn().mockReturnValue(options.sessionState ?? undefined),
+        getSessionMetadata: vitest_1.vi
+            .fn()
+            .mockReturnValue(options.sessionMetadata ?? undefined),
+        launch: vitest_1.vi.fn().mockResolvedValue(options.launchResult ?? {
+            sessionId: 'test-session-123',
+            extensionId: 'ext-123',
+            state: {
+                isLoaded: true,
+                currentUrl: 'chrome-extension://ext-123/home.html',
+                extensionId: 'ext-123',
+                isUnlocked: false,
+                currentScreen: 'home',
+                accountAddress: null,
+                networkName: null,
+                chainId: null,
+                balance: null,
+            },
+        }),
+        cleanup: vitest_1.vi.fn().mockResolvedValue(true),
+        // Page Management
+        getPage: vitest_1.vi.fn(),
+        setActivePage: vitest_1.vi.fn(),
+        getTrackedPages: vitest_1.vi.fn().mockReturnValue(options.trackedPages ?? []),
+        classifyPageRole: vitest_1.vi.fn().mockReturnValue('extension'),
+        getContext: vitest_1.vi.fn(),
+        // Extension State
+        getExtensionState: vitest_1.vi.fn().mockResolvedValue(options.extensionState ?? {
+            isLoaded: true,
+            currentUrl: 'chrome-extension://ext-123/home.html',
+            extensionId: 'ext-123',
+            isUnlocked: false,
+            currentScreen: 'home',
+            accountAddress: null,
+            networkName: null,
+            chainId: null,
+            balance: null,
+        }),
+        // A11y Reference Map
+        setRefMap: vitest_1.vi.fn(),
+        getRefMap: vitest_1.vi.fn().mockReturnValue(options.refMap ?? new Map()),
+        clearRefMap: vitest_1.vi.fn(),
+        resolveA11yRef: vitest_1.vi.fn(),
+        // Navigation
+        navigateToHome: vitest_1.vi.fn().mockResolvedValue(undefined),
+        navigateToSettings: vitest_1.vi.fn().mockResolvedValue(undefined),
+        navigateToUrl: vitest_1.vi.fn(),
+        navigateToNotification: vitest_1.vi.fn(),
+        waitForNotificationPage: vitest_1.vi.fn(),
+        // Screenshots
+        screenshot: vitest_1.vi.fn().mockResolvedValue({
+            path: '/path/to/screenshot.png',
+            width: 1280,
+            height: 720,
+        }),
+        // Capabilities
+        getBuildCapability: vitest_1.vi.fn().mockReturnValue(undefined),
+        getFixtureCapability: vitest_1.vi.fn().mockReturnValue(undefined),
+        getChainCapability: vitest_1.vi.fn().mockReturnValue(undefined),
+        getContractSeedingCapability: vitest_1.vi.fn().mockReturnValue(undefined),
+        getStateSnapshotCapability: vitest_1.vi.fn().mockReturnValue(undefined),
+        // Environment
+        getEnvironmentMode: vitest_1.vi
+            .fn()
+            .mockReturnValue(options.environmentMode ?? 'e2e'),
+        // Context
+        setContext: vitest_1.vi.fn().mockReturnValue(undefined),
+        getContextInfo: vitest_1.vi.fn().mockReturnValue({
+            currentContext: options.environmentMode ?? 'e2e',
+            hasActiveSession: options.hasActive ?? false,
+            sessionId: options.sessionId ?? null,
+            capabilities: { available: [] },
+            canSwitchContext: !(options.hasActive ?? false),
+        }),
+    };
+}
+/**
+ * Create a fresh mock KnowledgeStore instance.
+ *
+ * Returns an in-memory mock with sensible defaults.
+ * Each call creates fresh vi.fn() mocks.
+ *
+ * @param options - Customize mock behavior
+ * @returns Fresh KnowledgeStore mock
+ */
+function createMockKnowledgeStore(options = {}) {
+    return {
+        recordStep: vitest_1.vi.fn().mockResolvedValue(undefined),
+        getLastSteps: vitest_1.vi.fn().mockResolvedValue(options.lastSteps ?? []),
+        searchSteps: vitest_1.vi.fn().mockResolvedValue(options.searchResults ?? []),
+        summarizeSession: vitest_1.vi.fn().mockResolvedValue(options.sessionSummary ?? {
+            sessionId: 'test-session-123',
+            stepCount: 0,
+            recipe: [],
+        }),
+        listSessions: vitest_1.vi.fn().mockResolvedValue(options.sessions ?? []),
+        generatePriorKnowledge: vitest_1.vi.fn().mockResolvedValue(undefined),
+        writeSessionMetadata: vitest_1.vi.fn().mockResolvedValue('test-session-123'),
+    };
+}
+//# sourceMappingURL=mock-factories.cjs.map

package/dist/mcp-server/test-utils/mock-factories.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-factories.cjs","sourceRoot":"","sources":["../../../src/mcp-server/test-utils/mock-factories.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared mock factory utilities for unit testing.\n *\n * Provides factory functions that return fresh mock instances following MetaMask testing guidelines:\n * - Each factory call returns NEW object instances (test isolation)\n * - Each factory creates fresh vi.fn() mocks (never reused)\n * - Factories accept options for customization\n * - Sensible defaults so most tests need no options\n */\n\nimport { vi } from 'vitest';\n\nimport type { ExtensionState } from '../../capabilities/types.js';\nimport type { KnowledgeStore } from '../knowledge-store.js';\nimport type { TrackedPage, SessionLaunchResult } from '../session-manager.js';\nimport type { SessionState } from '../types/session.js';\nimport type { SessionMetadata } from '../types/step-record.js';\n\n/**\n * Options for customizing mock session manager behavior\n */\nexport type MockSessionManagerOptions = {\n  hasActive?: boolean;\n  sessionId?: string;\n  sessionState?: SessionState;\n  sessionMetadata?: SessionMetadata;\n  launchResult?: SessionLaunchResult;\n  trackedPages?: TrackedPage[];\n  extensionState?: ExtensionState;\n  refMap?: Map<string, string>;\n  environmentMode?: 'e2e' | 'prod';\n};\n\n/**\n * Options for customizing mock knowledge store behavior\n */\nexport type MockKnowledgeStoreOptions = {\n  lastSteps?: Record<string, unknown>[];\n  searchResults?: Record<string, unknown>[];\n  sessionSummary?: Record<string, unknown>;\n  sessions?: Record<string, unknown>[];\n};\n\n/**\n * Create a fresh mock ISessionManager instance.\n *\n * Each call returns a NEW object with fresh vi.fn() mocks.\n * Follows the pattern from session-manager.test.ts:15-48.\n *\n * @param options - Customize mock behavior\n * @returns Fresh ISessionManager mock\n */\nexport function createMockSessionManager(\n  options: MockSessionManagerOptions = {},\n) {\n  return {\n    // Session Lifecycle\n    hasActiveSession: vi.fn().mockReturnValue(options.hasActive ?? false),\n    getSessionId: vi.fn().mockReturnValue(options.sessionId ?? undefined),\n    getSessionState: vi.fn().mockReturnValue(options.sessionState ?? undefined),\n    getSessionMetadata: vi\n      .fn()\n      .mockReturnValue(options.sessionMetadata ?? undefined),\n    launch: vi.fn().mockResolvedValue(\n      options.launchResult ?? {\n        sessionId: 'test-session-123',\n        extensionId: 'ext-123',\n        state: {\n          isLoaded: true,\n          currentUrl: 'chrome-extension://ext-123/home.html',\n          extensionId: 'ext-123',\n          isUnlocked: false,\n          currentScreen: 'home',\n          accountAddress: null,\n          networkName: null,\n          chainId: null,\n          balance: null,\n        },\n      },\n    ),\n    cleanup: vi.fn().mockResolvedValue(true),\n\n    // Page Management\n    getPage: vi.fn(),\n    setActivePage: vi.fn(),\n    getTrackedPages: vi.fn().mockReturnValue(options.trackedPages ?? []),\n    classifyPageRole: vi.fn().mockReturnValue('extension'),\n    getContext: vi.fn(),\n\n    // Extension State\n    getExtensionState: vi.fn().mockResolvedValue(\n      options.extensionState ?? {\n        isLoaded: true,\n        currentUrl: 'chrome-extension://ext-123/home.html',\n        extensionId: 'ext-123',\n        isUnlocked: false,\n        currentScreen: 'home',\n        accountAddress: null,\n        networkName: null,\n        chainId: null,\n        balance: null,\n      },\n    ),\n\n    // A11y Reference Map\n    setRefMap: vi.fn(),\n    getRefMap: vi.fn().mockReturnValue(options.refMap ?? new Map()),\n    clearRefMap: vi.fn(),\n    resolveA11yRef: vi.fn(),\n\n    // Navigation\n    navigateToHome: vi.fn().mockResolvedValue(undefined),\n    navigateToSettings: vi.fn().mockResolvedValue(undefined),\n    navigateToUrl: vi.fn(),\n    navigateToNotification: vi.fn(),\n    waitForNotificationPage: vi.fn(),\n\n    // Screenshots\n    screenshot: vi.fn().mockResolvedValue({\n      path: '/path/to/screenshot.png',\n      width: 1280,\n      height: 720,\n    }),\n\n    // Capabilities\n    getBuildCapability: vi.fn().mockReturnValue(undefined),\n    getFixtureCapability: vi.fn().mockReturnValue(undefined),\n    getChainCapability: vi.fn().mockReturnValue(undefined),\n    getContractSeedingCapability: vi.fn().mockReturnValue(undefined),\n    getStateSnapshotCapability: vi.fn().mockReturnValue(undefined),\n\n    // Environment\n    getEnvironmentMode: vi\n      .fn()\n      .mockReturnValue(options.environmentMode ?? 'e2e'),\n\n    // Context\n    setContext: vi.fn().mockReturnValue(undefined),\n    getContextInfo: vi.fn().mockReturnValue({\n      currentContext: options.environmentMode ?? 'e2e',\n      hasActiveSession: options.hasActive ?? false,\n      sessionId: options.sessionId ?? null,\n      capabilities: { available: [] },\n      canSwitchContext: !(options.hasActive ?? false),\n    }),\n  };\n}\n\n/**\n * Create a fresh mock KnowledgeStore instance.\n *\n * Returns an in-memory mock with sensible defaults.\n * Each call creates fresh vi.fn() mocks.\n *\n * @param options - Customize mock behavior\n * @returns Fresh KnowledgeStore mock\n */\nexport function createMockKnowledgeStore(\n  options: MockKnowledgeStoreOptions = {},\n): Partial<KnowledgeStore> {\n  return {\n    recordStep: vi.fn().mockResolvedValue(undefined),\n    getLastSteps: vi.fn().mockResolvedValue(options.lastSteps ?? []),\n    searchSteps: vi.fn().mockResolvedValue(options.searchResults ?? []),\n    summarizeSession: vi.fn().mockResolvedValue(\n      options.sessionSummary ?? {\n        sessionId: 'test-session-123',\n        stepCount: 0,\n        recipe: [],\n      },\n    ),\n    listSessions: vi.fn().mockResolvedValue(options.sessions ?? []),\n    generatePriorKnowledge: vi.fn().mockResolvedValue(undefined),\n    writeSessionMetadata: vi.fn().mockResolvedValue('test-session-123'),\n  };\n}\n"]}