@yusufffararatt/dombridge-mcp 2.7.5

package/src/utils/state-validator.js

@@ -0,0 +1,354 @@
+/**
+ * State Validator
+ * Validates extension state for freshness, completeness, and consistency.
+ *
+ * Phase 2.4: Accepts either extensionData (in-process) or bridgeClient (thin client).
+ * Both provide the same property getters, so internal logic is unchanged.
+ *
+ * Uses workflow-state.js for per-tab timestamps where available.
+ */
+
+import { getTabState } from './workflow-state.js';
+
+/**
+ * Default max age for data freshness (15 minutes)
+ */
+const DEFAULT_MAX_AGE = 15 * 60 * 1000;
+
+/**
+ * State Validator Class
+ */
+export class StateValidator {
+  /**
+   * Validate selected element state
+   * @param {object} state - Extension state (extensionData or bridgeClient)
+   * @param {number} maxAge - Maximum age in ms
+   * @returns {object} - { valid, error, data }
+   */
+  static validateSelectedElement(state, maxAge = DEFAULT_MAX_AGE) {
+    if (!state.selectedElement) {
+      return {
+        valid: false,
+        error: 'No element selected',
+        suggestion: 'Use the Chrome extension or call get_element with a CSS/XPath selector',
+        nextStep: 'get_element({ selectorInfo: { css: "..." } })'
+      };
+    }
+
+    const el = state.selectedElement;
+
+    // Check required fields
+    if (!el.cssSelector || !el.xpath) {
+      return {
+        valid: false,
+        error: 'Selected element data incomplete',
+        suggestion: 'Re-select the element in Chrome extension'
+      };
+    }
+
+    // Check freshness
+    if (el.timestamp && !this.isDataFresh(el.timestamp, maxAge)) {
+      return {
+        valid: false,
+        error: `Selected element data is stale (${this.getAgeString(el.timestamp)})`,
+        suggestion: 'Re-select the element to get fresh data',
+        stale: true
+      };
+    }
+
+    return {
+      valid: true,
+      data: el
+    };
+  }
+
+  /**
+   * Validate network trace state
+   * @param {object} state - Extension state (extensionData or bridgeClient)
+   * @param {number} maxAge - Maximum age in ms
+   * @returns {object} - { valid, error, data }
+   */
+  static validateNetworkTrace(state, maxAge = DEFAULT_MAX_AGE) {
+    if (!state.networkTrace || state.networkTrace.totalMatches === 0) {
+      return {
+        valid: false,
+        error: 'No network trace available',
+        suggestion: 'Select a DOM element first to capture network trace',
+        nextStep: 'get_element → get_network_trace'
+      };
+    }
+
+    const trace = state.networkTrace;
+
+    // Check freshness
+    if (trace.timestamp && !this.isDataFresh(trace.timestamp, maxAge)) {
+      return {
+        valid: false,
+        error: `Network trace data is stale (${this.getAgeString(trace.timestamp)})`,
+        suggestion: 'Re-select the element to get fresh network trace',
+        stale: true
+      };
+    }
+
+    // Check data quality
+    if (!trace.matches || trace.matches.length === 0) {
+      return {
+        valid: false,
+        error: 'Network trace has no matches',
+        suggestion: 'The selected element may not be populated by API calls. Check Data Source Analysis in get_selected_element output.'
+      };
+    }
+
+    return {
+      valid: true,
+      data: trace
+    };
+  }
+
+  /**
+   * Validate WebSocket trace state
+   * @param {object} state - Extension state (extensionData or bridgeClient)
+   * @param {number} maxAge - Maximum age in ms
+   * @returns {object} - { valid, error, data }
+   */
+  static validateWebSocketTrace(state, maxAge = DEFAULT_MAX_AGE) {
+    if (!state.websocketTrace || state.websocketTrace.totalMatches === 0) {
+      return {
+        valid: false,
+        error: 'No WebSocket trace available',
+        suggestion: 'This page may not use WebSockets, or no matching messages found',
+        nextStep: 'Try get_network_trace for REST API calls instead'
+      };
+    }
+
+    const trace = state.websocketTrace;
+
+    // Check freshness
+    if (trace.timestamp && !this.isDataFresh(trace.timestamp, maxAge)) {
+      return {
+        valid: false,
+        error: `WebSocket trace data is stale (${this.getAgeString(trace.timestamp)})`,
+        suggestion: 'Re-select the element to get fresh WebSocket trace',
+        stale: true
+      };
+    }
+
+    return {
+      valid: true,
+      data: trace
+    };
+  }
+
+  /**
+   * Validate connection status.
+   * @param {object} state - Extension state (extensionData or bridgeClient)
+   * @param {string|number} [tabId] - Optional tab ID for per-tab navigation checks
+   * @returns {object} - { valid, error }
+   */
+  static validateConnection(state, tabId) {
+    if (!state.isConnected) {
+      return {
+        valid: false,
+        error: 'Extension not connected',
+        suggestion: 'Make sure the Chrome extension is installed and a tab is open',
+        nextStep: '1. Install Chrome extension\n2. Open any webpage\n3. Click extension icon'
+      };
+    }
+
+    // Check last update time
+    if (state.lastUpdateTime) {
+      const age = Date.now() - state.lastUpdateTime;
+      if (age > 25 * 60 * 1000) { // 25 minutes
+        return {
+          valid: false,
+          error: 'Extension connection seems inactive',
+          suggestion: 'Interact with the extension or refresh the page',
+          stale: true
+        };
+      }
+    }
+
+    // Attach tab-level context if available (informational, not blocking)
+    if (tabId) {
+      const tabState = getTabState(tabId);
+      return { valid: true, tabState };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Validate JS execution request
+   * @param {object} state - Extension state (extensionData or bridgeClient)
+   * @returns {object} - { valid, error, data }
+   */
+  static validateJsExecutionRequest(state) {
+    if (!state.jsExecutionRequest) {
+      return {
+        valid: false,
+        error: 'No pending JavaScript execution request',
+        suggestion: 'Call execute_js to execute code',
+        nextStep: 'execute_js'
+      };
+    }
+
+    const request = state.jsExecutionRequest;
+
+    // Check if request is too old (30 seconds timeout)
+    if (request.timestamp) {
+      const age = Date.now() - new Date(request.timestamp).getTime();
+      if (age > 30000) {
+        return {
+          valid: false,
+          error: 'Execution request timed out',
+          suggestion: 'Execute the code again with execute_js',
+          stale: true
+        };
+      }
+    }
+
+    return {
+      valid: true,
+      data: request
+    };
+  }
+
+  /**
+   * Validate that there's NO pending execution (prevents consecutive execute_js/query_dom calls)
+   * CRITICAL: This prevents LLMs from calling execute_js/query_dom multiple times without reading results
+   * @param {object} state - Extension state (extensionData or bridgeClient)
+   * @returns {object} - { valid, error }
+   */
+  static validateNoPendingExecution(state) {
+    // Check JavaScript execution
+    const jsRequest = state.jsExecutionRequest;
+    const jsResult = state.jsExecutionResult;
+
+    if (jsRequest && jsRequest.timestamp) {
+      const requestTime = new Date(jsRequest.timestamp).getTime();
+      const resultTime = jsResult?.timestamp ? new Date(jsResult.timestamp).getTime() : 0;
+
+      // If request is newer than result (or no result), there's a pending execution
+      if (requestTime > resultTime) {
+        return {
+          valid: false,
+          error: 'Previous execute_js call is still pending',
+          suggestion: '⚠️  CRITICAL: The previous code is still executing. Please wait a moment.',
+          nextStep: '1. Wait for the result to return automatically',
+          pendingType: 'execute_js',
+          requestId: jsRequest.id
+        };
+      }
+    }
+
+    return {
+      valid: true
+    };
+  }
+
+  /**
+   * Check if data is fresh
+   * @param {number} timestamp - Data timestamp
+   * @param {number} maxAge - Maximum age in ms
+   * @returns {boolean}
+   */
+  static isDataFresh(timestamp, maxAge = DEFAULT_MAX_AGE) {
+    if (!timestamp) return false;
+
+    const age = Date.now() - timestamp;
+    return age <= maxAge;
+  }
+
+  /**
+   * Get human-readable age string
+   * @param {number} timestamp - Data timestamp
+   * @returns {string}
+   */
+  static getAgeString(timestamp) {
+    if (!timestamp) return 'unknown age';
+
+    const age = Date.now() - timestamp;
+    const seconds = Math.floor(age / 1000);
+    const minutes = Math.floor(seconds / 60);
+
+    if (minutes > 0) {
+      return `${minutes} minute${minutes !== 1 ? 's' : ''} old`;
+    }
+
+    return `${seconds} second${seconds !== 1 ? 's' : ''} old`;
+  }
+
+  /**
+   * Validate generic state requirements
+   * @param {object} requirements - { required: string[], maxAge: number }
+   * @param {object} state - Extension state (extensionData or bridgeClient)
+   * @returns {object} - { valid, error, missing }
+   */
+  static validateGenericState(requirements, state) {
+    const missing = [];
+    const stale = [];
+
+    for (const field of requirements.required || []) {
+      // Check if field exists
+      if (!state[field]) {
+        missing.push(field);
+        continue;
+      }
+
+      // Check freshness if timestamp available
+      const data = state[field];
+      if (data.timestamp && requirements.maxAge) {
+        if (!this.isDataFresh(data.timestamp, requirements.maxAge)) {
+          stale.push({
+            field,
+            age: this.getAgeString(data.timestamp)
+          });
+        }
+      }
+    }
+
+    if (missing.length > 0) {
+      return {
+        valid: false,
+        error: `Missing required data: ${missing.join(', ')}`,
+        missing
+      };
+    }
+
+    if (stale.length > 0) {
+      return {
+        valid: false,
+        error: `Stale data detected: ${stale.map(s => `${s.field} (${s.age})`).join(', ')}`,
+        stale
+      };
+    }
+
+    return {
+      valid: true
+    };
+  }
+
+  /**
+   * Format validation error as MCP response
+   * @param {object} validation - Validation result
+   * @returns {object} - MCP response format
+   */
+  static formatValidationError(validation) {
+    let text = `❌ ${validation.error}\n`;
+
+    if (validation.suggestion) {
+      text += `\n💡 ${validation.suggestion}\n`;
+    }
+
+    if (validation.nextStep) {
+      text += `\n📋 NEXT STEPS:\n${validation.nextStep}\n`;
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text
+      }]
+    };
+  }
+}

package/src/utils/tab-resolver.js

@@ -0,0 +1,70 @@
+/**
+ * Tab Resolver
+ * Resolves tabId to URL by querying the extension for open tabs.
+ * Used by tools that need domain resolution for profile operations.
+ *
+ * Phase 2.4: Refactored from (extensionData, httpPort) to (bridgeClient).
+ * All tab resolution now goes through BridgeClient HTTP calls.
+ */
+
+import { getTabState, extractDomain } from './workflow-state.js';
+
+/**
+ * Fetch open tabs from extension via bridge daemon.
+ * @param {BridgeClient} bridgeClient
+ * @returns {Promise<Array<{id: number, url: string, title: string, active: boolean}>>}
+ */
+async function fetchTabs(bridgeClient) {
+    const requestId = `tabs-resolve-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+    try {
+        await bridgeClient.queueRequest('tabs', { id: requestId });
+        const result = await bridgeClient.waitForResult('tabs', requestId, 2000);
+        if (result && result.tabs) {
+            return result.tabs;
+        }
+    } catch {
+        // Non-critical — tab resolution is best-effort
+    }
+    return [];
+}
+
+/**
+ * Resolve a tabId to its page URL. Tries workflow-state cache first, then live query.
+ * @param {BridgeClient} bridgeClient
+ * @param {number} tabId
+ * @returns {Promise<string>} URL or empty string
+ */
+export async function resolveTabUrl(bridgeClient, tabId) {
+    // 1. Check workflow-state cache
+    const cached = getTabState(tabId);
+    if (cached?.url) return cached.url;
+
+    // 2. Live query to extension
+    const tabs = await fetchTabs(bridgeClient);
+    const match = tabs.find((t) => t.id === tabId);
+    return match?.url || '';
+}
+
+/**
+ * Get the correct domain for a given tool call, accounting for tabId.
+ * Falls back to activeTabUrl → selectedElement URLs if no tabId specified.
+ * @param {BridgeClient} bridgeClient
+ * @param {number|undefined} tabId
+ * @returns {Promise<string>} hostname or empty string
+ */
+export async function resolveActiveDomain(bridgeClient, tabId) {
+    // If tabId specified, resolve that tab's URL — do NOT fall back to active tab
+    // (falling back would silently save to wrong domain if tab resolution fails)
+    if (tabId !== undefined) {
+        const url = await resolveTabUrl(bridgeClient, tabId);
+        return url ? extractDomain(url) : '';
+    }
+
+    // Fallback: activeTabUrl → selectedElement URLs
+    const candidate = bridgeClient.activeTabUrl
+        || bridgeClient.selectedElement?.sessionInfo?.url
+        || bridgeClient.selectedElement?.pageUrl
+        || '';
+    return candidate ? extractDomain(candidate) : '';
+}

package/src/utils/workflow-helper.js

@@ -0,0 +1,292 @@
+/**
+ * Workflow Helper
+ * Manages tool dependencies, prerequisites, and workflow guidance for LLM agents.
+ *
+ * This module reads from workflow-state.js but does NOT modify it.
+ * State mutations happen inside tool handlers via the workflow-state API.
+ *
+ * References:
+ * - https://www.anthropic.com/engineering/code-execution-with-mcp
+ * - https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices
+ */
+
+import { getTabState, isProfileFresh } from './workflow-state.js';
+
+/**
+ * Tool dependency graph
+ * Defines which tools must be called before others.
+ */
+const ToolDependencies = {
+  // get_network_trace requires an element to have been selected first
+  'get_network_trace': {
+    description: 'Retrieves network API calls that match the selected DOM element',
+    requires: ['get_element']
+  },
+  // JavaScript execution workflow
+  'execute_js': {
+    description: 'Executes custom JavaScript code'
+  },
+};
+
+
+/**
+ * Validate tool prerequisites.
+ * @param {string} toolName - Name of the tool to validate
+ * @param {object} state - Current state (extensionData or bridgeClient)
+ * @param {object} [context] - Optional context: { tabId, domain }
+ * @returns {object} - { valid: boolean, missing: string[], suggestions: string[] }
+ */
+export function validatePrerequisites(toolName, state, context = {}) {
+  const dependency = ToolDependencies[toolName];
+
+  // No dependencies = always valid
+  if (!dependency) {
+    return { valid: true, missing: [], suggestions: [] };
+  }
+
+  const missing = [];
+  const suggestions = [];
+
+  // Check required dependencies
+  for (const requiredTool of dependency.requires || []) {
+    const isAvailable = checkToolDataAvailable(requiredTool, state);
+
+    if (!isAvailable) {
+      missing.push(requiredTool);
+      suggestions.push(`Call ${requiredTool} first`);
+    }
+  }
+
+  // Attach workflow state hints when context is available
+  const hints = buildWorkflowHints(toolName, context);
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    suggestions,
+    reason: dependency.description,
+    hints
+  };
+}
+
+/**
+ * Build soft hints based on workflow state (no blocking — informational only).
+ * @param {string} toolName
+ * @param {{ tabId?: string|number, domain?: string }} context
+ * @returns {string[]}
+ */
+function buildWorkflowHints(toolName, context) {
+  const hints = [];
+  const { tabId, domain } = context;
+
+  if (domain && isProfileFresh(domain)) {
+    if (toolName === 'discover_apis') {
+      hints.push(`A fresh profile exists for ${domain}. Consider load_site_profile to skip re-discovery.`);
+    }
+  }
+
+  if (tabId) {
+    const tabState = getTabState(tabId);
+    if (tabState.lastAnalyzeAt && toolName === 'analyze_page') {
+      const ageS = Math.round((Date.now() - tabState.lastAnalyzeAt) / 1000);
+      if (ageS < 60) {
+        hints.push(`analyze_page was called ${ageS}s ago on this tab — data is likely still fresh.`);
+      }
+    }
+  }
+
+  return hints;
+}
+
+/**
+ * Check if required data for a tool is available
+ * @param {string} toolName - Tool name
+ * @param {object} state - Extension state (extensionData or bridgeClient)
+ * @returns {boolean}
+ */
+function checkToolDataAvailable(toolName, state) {
+  switch (toolName) {
+    case 'get_element':
+      return state.selectedElement &&
+        state.selectedElement.cssSelector;
+
+    case 'get_network_trace':
+      return state.networkTrace &&
+        state.networkTrace.totalMatches > 0;
+
+    case 'execute_js':
+      // Pending request OR result present means execution has been issued
+      return state.jsExecutionRequest !== null ||
+        state.jsExecutionResult !== null;
+
+    default:
+      return true; // Unknown tool, assume available
+  }
+}
+
+/**
+ * Suggest next tools in workflow
+ * @param {string} currentTool - Current tool name
+ * @returns {Array} - Array of { tool, reason, priority }
+ */
+export function suggestNextTools(currentTool) {
+  const suggestions = [];
+
+  // After element selection - find which API populates it
+  if (currentTool === 'get_element') {
+    suggestions.push({
+      tool: 'get_network_trace',
+      reason: 'Find matching API calls and inspect details',
+      priority: 'high'
+    });
+  }
+
+
+  // After JS execution
+  if (currentTool === 'execute_js') {
+    // We don't suggest get_execution_results anymore as it's blocking
+    // But we might suggest analyzing the result or another JS execution
+  }
+
+  return suggestions;
+}
+
+
+/**
+ * Format a hard guard (missing prerequisites) as an MCP response object.
+ * Use this when a tool MUST be blocked.
+ * @param {string} toolName
+ * @param {object} validation - { missing: string[], suggestions: string[] }
+ * @returns {object} MCP content response
+ */
+export function formatHardGuard(toolName, validation) {
+  const next = validation.missing[0] || 'unknown';
+  const text =
+    `❌ Cannot run \`${toolName}\`: missing prerequisites.\n\n` +
+    `Required first: \`${validation.missing.join(' → ')}\`\n` +
+    `Next step: \`${next}\``;
+
+  return { content: [{ type: 'text', text }] };
+}
+
+/**
+ * Format a soft guard (stale-but-usable hint) as an MCP response object.
+ * Appends to existing output — does NOT block execution.
+ * @param {string[]} hints
+ * @returns {string} Text to append (empty string if no hints)
+ */
+export function formatSoftGuard(hints) {
+  if (!hints || hints.length === 0) return '';
+  return '\n\n' + hints.map(h => `💡 ${h}`).join('\n');
+}
+
+/**
+ * Evaluate soft guard for discover_apis.
+ * Returns hints array (empty = no soft guard triggered).
+ * @param {object} state - Extension state (extensionData or bridgeClient)
+ * @param {{ tabId?: string|number, domain?: string, force?: boolean }} context
+ * @returns {string[]}
+ */
+export function softGuardDiscoverApis(state, context = {}) {
+  const { domain, force } = context;
+  if (force) return [];
+  if (domain && isProfileFresh(domain)) {
+    return [
+      `A fresh profile exists for \`${domain}\`. ` +
+      `Consider \`load_site_profile({ domain: "${domain}" })\` to skip re-discovery. ` +
+      `Pass \`force: true\` to run anyway.`
+    ];
+  }
+  return [];
+}
+
+/**
+ * Evaluate soft guard for analyze_page.
+ * Returns hints array (empty = no soft guard triggered).
+ * @param {{ tabId?: string|number }} context
+ * @returns {string[]}
+ */
+export function softGuardAnalyzePage(context = {}) {
+  const { tabId } = context;
+  if (!tabId) return [];
+  const tabState = getTabState(tabId);
+  if (!tabState.lastAnalyzeAt) return [];
+  const ageS = Math.round((Date.now() - tabState.lastAnalyzeAt) / 1000);
+  if (ageS < 60) {
+    return [`analyze_page was called ${ageS}s ago on this tab — data is likely still fresh.`];
+  }
+  return [];
+}
+
+/**
+ * Evaluate soft guard for load_site_profile.
+ * Returns hints array (empty = no soft guard triggered).
+ * @param {string} domain
+ * @returns {string[]}
+ */
+export function softGuardLoadSiteProfile(domain) {
+  // No saved profile for this domain — suggest quick_scan
+  // Caller must check loadProfile result first; this just provides the hint text.
+  if (!domain) return [];
+  return [
+    `No saved profile for \`${domain}\`. ` +
+    `Run \`quick_scan\` to discover the site and build a profile automatically.`
+  ];
+}
+
+/**
+ * @deprecated Use formatHardGuard instead.
+ * Format prerequisite error message (kept for call sites not yet migrated).
+ */
+export function formatPrerequisiteError(toolName, validation) {
+  if (validation.valid) return null;
+  let message = `Cannot execute ${toolName}: Missing prerequisites\n\n`;
+  message += `Required: ${validation.missing.join(' -> ')}\n`;
+  message += `Next: ${validation.missing[0]}`;
+  return message;
+}
+
+/**
+ * Format workflow suggestion message
+ * @param {Array} suggestions - Next tool suggestions
+ * @returns {string} - Formatted suggestion message
+ */
+export function formatWorkflowSuggestions(suggestions) {
+  if (!suggestions || suggestions.length === 0) {
+    return '';
+  }
+
+  // Get the highest priority suggestion
+  const nextTool = suggestions.find(s => s.priority === 'high') || suggestions[0];
+  return `\nNext: ${nextTool.tool}`;
+}
+/**
+ * Wait for a result to appear in extensionData
+ * @deprecated Use bridgeClient.waitForResult(type, requestId, timeoutMs) instead.
+ * This function is kept for backward compatibility but should not be used in new code.
+ * @param {object} state - Extension state (extensionData or bridgeClient)
+ * @param {string} resultKey - Key to check (e.g., 'jsExecutionResult')
+ * @param {number} requestId - Request ID to match
+ * @param {number} timeoutMs - Max wait time
+ * @returns {Promise<object|null>} - Found result or null
+ */
+export async function waitForResult(state, resultKey, requestId, timeoutMs = 10000) {
+  const startTime = Date.now();
+  const pollInterval = 500; // 500ms
+
+  while (Date.now() - startTime < timeoutMs) {
+    const result = state[resultKey];
+
+    // Check if we have a result that matches our request
+    // Note: requestId might not be present in results from older extensions,
+    // so we also check timestamp if available.
+    if (result && (!requestId || result.id === requestId || result.requestId === requestId)) {
+      return result;
+    }
+
+    // Wait for next poll
+    await new Promise(resolve => setTimeout(resolve, pollInterval));
+  }
+
+  return null;
+}