mcpbrowser 0.3.34 → 0.3.36

package/src/plugins/gmail/helpers.js

@@ -0,0 +1,419 @@
+/**
+ * helpers.js — Shared tiered utilities for the Gmail plugin.
+ *
+ * Provides URL-based navigation (T1), keyboard shortcut verification (T2),
+ * ARIA/data-attr DOM utilities (T3), and CSS-selector data extraction (T4).
+ *
+ * All helpers are stateless — they inspect the page at invocation time
+ * per FR-017. No internal state is maintained between calls.
+ */
+
+import { MCPResponse } from '../../core/responses.js';
+import * as sel from './selectors.js';
+import logger from '../../core/logger.js';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Default timeout for waiting on Gmail content (FR-012) */
+export const DEFAULT_TIMEOUT = 10_000;
+
+/** Gmail view states detected from URL hash + DOM (FR-024) */
+export const VIEW = Object.freeze({
+  EMAIL_LIST: 'email_list',
+  THREAD: 'thread',
+  COMPOSE: 'compose',
+  SEARCH_RESULTS: 'search_results',
+  LOADING: 'loading',
+  NOT_GMAIL: 'not_gmail',
+  NOT_READY: 'not_ready'
+});
+
+/** Standard Gmail folder hashes */
+const STANDARD_FOLDERS = new Set([
+  'inbox', 'sent', 'drafts', 'trash', 'spam', 'starred', 'all', 'important'
+]);
+
+// ============================================================================
+// T1: URL-BASED NAVIGATION (FR-020)
+// ============================================================================
+
+/**
+ * Extract the Google account index from a Gmail URL.
+ * Handles /u/0/, /u/1/, /u/2/, etc. Defaults to '0' if not found.
+ * @param {string} url - Current page URL
+ * @returns {string} Account index (e.g., '0', '1', '2')
+ */
+export function getAccountIndex(url) {
+  const match = url.match(/\/u\/(\d+)\//);
+  return match ? match[1] : '0';
+}
+
+/**
+ * Navigate to a Gmail URL hash, preserving the current account index.
+ * @param {import('puppeteer-core').Page} page
+ * @param {string} hash - Hash fragment (e.g., '#inbox', '#search/query', '#inbox/threadId')
+ * @returns {Promise<void>}
+ */
+export async function gmailNavigate(page, hash) {
+  const currentUrl = page.url();
+  const accountIndex = getAccountIndex(currentUrl);
+  const targetUrl = `https://mail.google.com/mail/u/${accountIndex}/${hash}`;
+  logger.debug(`gmailNavigate: ${targetUrl}`);
+  await page.goto(targetUrl, { waitUntil: 'networkidle2', timeout: DEFAULT_TIMEOUT });
+}
+
+/**
+ * Build a Gmail URL hash for a folder name.
+ * Standard folders use #folder, custom labels use #label/Name.
+ * @param {string} folder - Folder name (inbox, sent, etc.) or label name
+ * @returns {string} Hash fragment
+ */
+export function folderToHash(folder) {
+  const lower = folder.toLowerCase();
+  if (STANDARD_FOLDERS.has(lower)) {
+    return `#${lower}`;
+  }
+  return `#label/${encodeURIComponent(folder)}`;
+}
+
+// ============================================================================
+// VIEW DETECTION (FR-024 — URL hash primary, DOM fallback)
+// ============================================================================
+
+/**
+ * Detect the current Gmail view by inspecting the URL hash first (T1),
+ * then falling back to DOM inspection for ambiguous cases (T3).
+ * Also detects CAPTCHA/interstitial states returning NOT_READY.
+ * @param {import('puppeteer-core').Page} page
+ * @returns {Promise<string>} One of VIEW enum values
+ */
+export async function detectView(page) {
+  const url = page.url();
+
+  // Not Gmail at all
+  if (!url.includes('mail.google.com')) {
+    logger.debug('detectView: not Gmail');
+    return VIEW.NOT_GMAIL;
+  }
+
+  // Check for CAPTCHA / security interstitial (edge case)
+  const hasInterstitial = await page.evaluate(() => {
+    const body = document.body?.textContent || '';
+    return body.includes('Confirm it') ||
+           !!document.querySelector('iframe[src*="accounts.google.com"]') ||
+           !!document.querySelector('#captcha');
+  });
+  if (hasInterstitial) {
+    logger.debug('detectView: not_ready (interstitial/CAPTCHA)');
+    return VIEW.NOT_READY;
+  }
+
+  // Parse URL hash
+  const hashMatch = url.match(/#(.+)/);
+  const hash = hashMatch ? hashMatch[1] : '';
+
+  // Check for compose overlay via DOM (compose can appear over any view)
+  const hasComposeDialog = await page.evaluate(() =>
+    !!document.querySelector('div[role="dialog"]')
+  );
+  if (hasComposeDialog) {
+    logger.debug('detectView: compose (dialog overlay)');
+    return VIEW.COMPOSE;
+  }
+
+  // Search results
+  if (hash.startsWith('search/')) {
+    logger.debug('detectView: search_results');
+    return VIEW.SEARCH_RESULTS;
+  }
+
+  // Thread view — hash contains folder/threadId pattern
+  if (/^(inbox|sent|all|drafts|trash|spam|starred|important|label\/[^/]+)\/[A-Za-z0-9]+/.test(hash)) {
+    logger.debug('detectView: thread');
+    return VIEW.THREAD;
+  }
+
+  // Standard folder or label view
+  if (hash === '' || hash === 'inbox' || STANDARD_FOLDERS.has(hash) || hash.startsWith('label/')) {
+    // Check if content has loaded
+    const hasMain = await page.evaluate(() =>
+      !!document.querySelector('div[role="main"]')
+    );
+    if (!hasMain) {
+      logger.debug('detectView: loading');
+      return VIEW.LOADING;
+    }
+    logger.debug('detectView: email_list');
+    return VIEW.EMAIL_LIST;
+  }
+
+  // Fallback — check if main content exists
+  const hasMain = await page.evaluate(() =>
+    !!document.querySelector('div[role="main"]')
+  );
+  if (hasMain) {
+    logger.debug('detectView: email_list (fallback)');
+    return VIEW.EMAIL_LIST;
+  }
+
+  logger.debug('detectView: loading (no main container)');
+  return VIEW.LOADING;
+}
+
+// ============================================================================
+// T2: KEYBOARD SHORTCUT VERIFICATION (FR-019)
+// ============================================================================
+
+/**
+ * Check whether Gmail keyboard shortcuts are enabled.
+ * Sends '?' to trigger the shortcuts help dialog, then detects it.
+ * @param {import('puppeteer-core').Page} page
+ * @returns {Promise<{enabled: boolean, error?: string}>}
+ */
+export async function checkKeyboardShortcuts(page) {
+  try {
+    // Ensure no input is focused before sending shortcut
+    await page.evaluate(() => {
+      if (document.activeElement && document.activeElement.tagName !== 'BODY') {
+        document.activeElement.blur();
+      }
+    });
+
+    // Send ? (Shift+/) to open shortcuts help
+    await page.keyboard.down('Shift');
+    await page.keyboard.press('/');
+    await page.keyboard.up('Shift');
+
+    // Wait briefly for the dialog
+    const dialog = await page.waitForSelector(
+      'div[role="dialog"]',
+      { timeout: 2000 }
+    ).catch(() => null);
+
+    if (dialog) {
+      // Close the help dialog
+      await page.keyboard.press('Escape');
+      return { enabled: true };
+    }
+
+    return {
+      enabled: false,
+      error: 'Gmail keyboard shortcuts are disabled. Enable them in Gmail Settings → General → Keyboard shortcuts → ON, then reload Gmail.'
+    };
+  } catch {
+    return {
+      enabled: false,
+      error: 'Could not verify Gmail keyboard shortcuts. Ensure Gmail is fully loaded.'
+    };
+  }
+}
+
+// ============================================================================
+// PRECONDITION CHECKING (FR-025)
+// ============================================================================
+
+/**
+ * Validate a precondition before sending a keyboard shortcut.
+ * Fails early with an actionable error if the precondition is not met.
+ * @param {import('puppeteer-core').Page} page
+ * @param {'on_gmail'|'thread_open'|'list_view'} requirement
+ * @returns {Promise<{met: boolean, error?: string, suggestion?: string}>}
+ */
+export async function checkPrecondition(page, requirement) {
+  const url = page.url();
+
+  switch (requirement) {
+    case 'on_gmail': {
+      if (!url.includes('mail.google.com')) {
+        return {
+          met: false,
+          error: 'Gmail is not the active page.',
+          suggestion: "Use fetch_webpage({ url: 'https://mail.google.com' }) to navigate to Gmail first."
+        };
+      }
+      return { met: true };
+    }
+
+    case 'thread_open': {
+      const hash = url.match(/#(.+)/)?.[1] || '';
+      const isThread = /^(inbox|sent|all|drafts|trash|spam|starred|important|label\/[^/]+)\/[A-Za-z0-9]+/.test(hash);
+      if (!isThread) {
+        return {
+          met: false,
+          error: 'No email thread is currently open.',
+          suggestion: "Use plugin_action({ plugin: 'gmail', action: 'read_email', params: { index: 0 } }) to open an email first."
+        };
+      }
+      return { met: true };
+    }
+
+    case 'list_view': {
+      const view = await detectView(page);
+      if (view !== VIEW.EMAIL_LIST && view !== VIEW.SEARCH_RESULTS) {
+        return {
+          met: false,
+          error: 'Not in email list view.',
+          suggestion: "Use plugin_action({ plugin: 'gmail', action: 'list_emails' }) to return to the email list."
+        };
+      }
+      return { met: true };
+    }
+
+    default:
+      return { met: false, error: `Unknown precondition: ${requirement}` };
+  }
+}
+
+// ============================================================================
+// CONTENT WAITING (FR-012 — 10s timeout with diagnostics)
+// ============================================================================
+
+/**
+ * Wait for a Gmail element to appear, with timeout and diagnostic error.
+ * Timeout errors include the selector name per Constitution IV.
+ * @param {import('puppeteer-core').Page} page
+ * @param {string} selector - CSS selector to wait for
+ * @param {number} [timeout=DEFAULT_TIMEOUT]
+ * @returns {Promise<void>}
+ * @throws {Error} With selector name and tier in message on timeout
+ */
+export async function waitForGmail(page, selector, timeout = DEFAULT_TIMEOUT) {
+  try {
+    await page.waitForSelector(selector, { timeout });
+  } catch {
+    throw new Error(
+      `Gmail content did not load within ${timeout}ms. ` +
+      `Selector that failed: "${selector}". ` +
+      `The page may still be loading or Gmail's UI may have changed.`
+    );
+  }
+}
+
+// ============================================================================
+// EMAIL ROW SELECTION — Hybrid DOM+keyboard (FR-016)
+// ============================================================================
+
+/**
+ * Locate and select an email row by ID or positional index.
+ * Uses T3 (data-legacy-message-id, role="checkbox") with T4 fallback.
+ * Clicks the row's checkbox to select it for keyboard actions.
+ * @param {import('puppeteer-core').Page} page
+ * @param {{ index?: number, id?: string }} target
+ * @returns {Promise<{selected: boolean, error?: string}>}
+ */
+export async function selectEmailRow(page, { index, id } = {}) {
+  if (id !== undefined && id !== null) {
+    // T3: Prefer ID-based selection via data attribute
+    const row = await page.$(`tr[data-legacy-message-id="${id}"]`);
+    if (row) {
+      const checkbox = await row.$('div[role="checkbox"]');
+      if (checkbox) {
+        await checkbox.click();
+        logger.debug(`selectEmailRow: selected by ID "${id}"`);
+        return { selected: true };
+      }
+    }
+    logger.debug(`selectEmailRow: ID "${id}" not found, trying index fallback`);
+  }
+
+  if (index !== undefined && index !== null) {
+    // T4: Positional index via CSS class selector
+    const rows = await page.$$(sel.EMAIL_ROW);
+    if (index >= 0 && index < rows.length) {
+      const checkbox = await rows[index].$('div[role="checkbox"]');
+      if (checkbox) {
+        await checkbox.click();
+        logger.debug(`selectEmailRow: selected by index ${index}`);
+        return { selected: true };
+      }
+    }
+    return {
+      selected: false,
+      error: `Email index ${index} is out of range. There are ${(await page.$$(sel.EMAIL_ROW)).length} visible emails.`
+    };
+  }
+
+  return { selected: false, error: 'No index or id provided for email selection.' };
+}
+
+// ============================================================================
+// EMAIL ROW EXTRACTION — T3+T4 data extraction
+// ============================================================================
+
+/**
+ * Extract structured email summary data from visible email rows.
+ * Uses T3 (span[email], [data-legacy-message-id]) and T4 (CSS selectors).
+ * @param {import('puppeteer-core').Page} page
+ * @param {number} [limit=25]
+ * @returns {Promise<Array>} Array of EmailSummary objects per data-model.md
+ */
+export async function extractEmailRows(page, limit = 25) {
+  return page.evaluate((selectors, lim) => {
+    const rows = document.querySelectorAll(selectors.emailRow);
+    const results = [];
+    const count = Math.min(rows.length, lim);
+
+    for (let i = 0; i < count; i++) {
+      const row = rows[i];
+      // T3: span[email] for sender data
+      const senderEl = row.querySelector('span[email]');
+      // T4: CSS class selectors for subject, snippet, date
+      const subjectEl = row.querySelector(selectors.subjectSpan);
+      const snippetEl = row.querySelector(selectors.snippetSpan);
+      const dateEl = row.querySelector(selectors.dateCell);
+      // T4: Unread detection via class
+      const isUnread = row.classList.contains(selectors.unreadClass);
+      // T3: data attribute for ID
+      const id = row.getAttribute('data-legacy-message-id') || undefined;
+
+      results.push({
+        index: i,
+        id,
+        sender: senderEl?.getAttribute('name') || senderEl?.textContent?.trim() || '',
+        senderEmail: senderEl?.getAttribute('email') || '',
+        subject: subjectEl?.textContent?.trim() || '',
+        snippet: snippetEl?.textContent?.trim() || '',
+        date: dateEl?.getAttribute('title') || dateEl?.textContent?.trim() || '',
+        isUnread
+      });
+    }
+    return results;
+  }, {
+    emailRow: sel.EMAIL_ROW,
+    subjectSpan: sel.SUBJECT_SPAN,
+    snippetSpan: sel.SNIPPET_SPAN,
+    dateCell: sel.DATE_CELL,
+    unreadClass: sel.EMAIL_ROW_UNREAD
+  }, limit);
+}
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Gmail-specific response class extending MCPResponse.
+ * Carries structured email data alongside nextSteps.
+ */
+export class GmailActionResponse extends MCPResponse {
+  /**
+   * @param {object} data - Structured data payload
+   * @param {string} summary - Human-readable summary text
+   * @param {string[]} nextSteps - Suggested next actions
+   */
+  constructor(data, summary, nextSteps) {
+    super(nextSteps);
+    this.data = data;
+    this._summary = summary;
+  }
+
+  _getAdditionalFields() {
+    return { ...this.data };
+  }
+
+  getTextSummary() {
+    return this._summary;
+  }
+}

package/src/plugins/gmail/index.js

@@ -0,0 +1,195 @@
+/**
+ * Gmail plugin — Site-specific automation for Gmail (mail.google.com).
+ * Implements the MCPBrowser plugin interface (interfaceVersion 1).
+ *
+ * Uses a tiered interaction strategy (FR-011):
+ *   T1: URL hash navigation for folders/search
+ *   T2: Keyboard shortcuts for actions (compose, reply, archive, etc.)
+ *   T3: ARIA / data attributes / name attrs for data extraction and form filling
+ *   T4: CSS class selectors (last resort, centralized in selectors.js)
+ */
+
+import { listEmails } from './actions/list-emails.js';
+import { readEmail } from './actions/read-email.js';
+import { searchEmails } from './actions/search-emails.js';
+import { composeEmail } from './actions/compose-email.js';
+import { replyEmail } from './actions/reply-email.js';
+import { forwardEmail } from './actions/forward-email.js';
+import { archiveEmail } from './actions/archive-email.js';
+import { deleteEmail } from './actions/delete-email.js';
+import { labelEmail } from './actions/label-email.js';
+import { markRead } from './actions/mark-read.js';
+import { markUnread } from './actions/mark-unread.js';
+
+// ============================================================================
+// MANIFEST
+// ============================================================================
+
+export const manifest = {
+  name: "gmail",
+  version: "1.0.0",
+  description: "Gmail plugin for MCPBrowser — email management with hybrid UI resilience (URL navigation, keyboard shortcuts, ARIA selectors, CSS fallback)",
+  interfaceVersion: 1,
+  urlPatterns: ["mail.google.com"],
+  domPatterns: ["div[data-ogsr-up]", ".aH2"]
+};
+
+// ============================================================================
+// DETECTION
+// ============================================================================
+
+/**
+ * Detect whether this plugin is applicable for the given page.
+ * @param {string} url - Current page URL
+ * @param {string} html - Extracted page HTML
+ * @returns {{ matched: boolean, confidence?: number }}
+ */
+export function matchesPage(url, html) {
+  try {
+    if (url && url.includes('mail.google.com')) {
+      return { matched: true, confidence: 1.0 };
+    }
+    if (html && (html.includes('data-ogsr-up') || html.includes('aH2'))) {
+      return { matched: true, confidence: 0.8 };
+    }
+    return { matched: false };
+  } catch {
+    return { matched: false };
+  }
+}
+
+// ============================================================================
+// ACTIONS
+// ============================================================================
+
+/**
+ * Return the complete list of actions this plugin provides.
+ * @returns {Array} ActionDescriptor[] per plugin interface contract
+ */
+export function getActions() {
+  return [
+    {
+      name: "list_emails",
+      description: "List visible emails from the current Gmail folder/view",
+      params: [
+        { name: "folder", type: "string", description: "Gmail folder: inbox, sent, drafts, trash, spam, or a label name", required: false },
+        { name: "limit", type: "number", description: "Maximum number of emails to return (default: 25)", required: false, default: 25 }
+      ],
+      execute: listEmails
+    },
+    {
+      name: "read_email",
+      description: "Open and read a specific email by index or ID",
+      params: [
+        { name: "index", type: "number", description: "0-based position in current email list", required: false },
+        { name: "id", type: "string", description: "Gmail internal message/thread ID", required: false }
+      ],
+      execute: readEmail
+    },
+    {
+      name: "search_emails",
+      description: "Search Gmail using URL hash navigation and return matching emails",
+      params: [
+        { name: "query", type: "string", description: "Gmail search query (supports from:, to:, subject:, has:attachment, etc.)", required: true },
+        { name: "limit", type: "number", description: "Maximum results to return (default: 25)", required: false, default: 25 }
+      ],
+      execute: searchEmails
+    },
+    {
+      name: "compose_email",
+      description: "Open Gmail compose window via keyboard shortcut and fill in email fields",
+      params: [
+        { name: "to", type: "string", description: "Recipient email address", required: true },
+        { name: "subject", type: "string", description: "Email subject", required: false, default: "" },
+        { name: "body", type: "string", description: "Email body text", required: false, default: "" },
+        { name: "cc", type: "string", description: "CC recipient email address", required: false },
+        { name: "send", type: "boolean", description: "If true, send immediately via Ctrl+Enter. Default: leave as draft", required: false, default: false }
+      ],
+      execute: composeEmail
+    },
+    {
+      name: "reply_email",
+      description: "Reply to the currently open email thread via keyboard shortcut",
+      params: [
+        { name: "body", type: "string", description: "Reply body text", required: true },
+        { name: "replyAll", type: "boolean", description: "If true, reply to all participants (keyboard 'a')", required: false, default: false },
+        { name: "send", type: "boolean", description: "If true, send immediately via Ctrl+Enter. Default: leave as draft", required: false, default: false }
+      ],
+      execute: replyEmail
+    },
+    {
+      name: "forward_email",
+      description: "Forward the currently open email thread via keyboard shortcut",
+      params: [
+        { name: "to", type: "string", description: "Recipient email address to forward to", required: true },
+        { name: "body", type: "string", description: "Additional body text above forwarded content", required: false, default: "" },
+        { name: "send", type: "boolean", description: "If true, send immediately via Ctrl+Enter. Default: leave as draft", required: false, default: false }
+      ],
+      execute: forwardEmail
+    },
+    {
+      name: "archive_email",
+      description: "Archive an email via keyboard shortcut (remove from inbox, keep in All Mail)",
+      params: [
+        { name: "index", type: "number", description: "0-based index in email list", required: false },
+        { name: "id", type: "string", description: "Gmail message/thread ID", required: false }
+      ],
+      execute: archiveEmail
+    },
+    {
+      name: "delete_email",
+      description: "Move an email to Trash via keyboard shortcut",
+      params: [
+        { name: "index", type: "number", description: "0-based index in email list", required: false },
+        { name: "id", type: "string", description: "Gmail message/thread ID", required: false }
+      ],
+      execute: deleteEmail
+    },
+    {
+      name: "label_email",
+      description: "Apply a Gmail label to an email via keyboard shortcut",
+      params: [
+        { name: "index", type: "number", description: "0-based index in email list", required: false },
+        { name: "id", type: "string", description: "Gmail message/thread ID", required: false },
+        { name: "label", type: "string", description: "Label name to apply", required: true }
+      ],
+      execute: labelEmail
+    },
+    {
+      name: "mark_read",
+      description: "Mark an email as read via keyboard shortcut (Shift+i)",
+      params: [
+        { name: "index", type: "number", description: "0-based index in email list", required: false },
+        { name: "id", type: "string", description: "Gmail message/thread ID", required: false }
+      ],
+      execute: markRead
+    },
+    {
+      name: "mark_unread",
+      description: "Mark an email as unread via keyboard shortcut (Shift+u)",
+      params: [
+        { name: "index", type: "number", description: "0-based index in email list", required: false },
+        { name: "id", type: "string", description: "Gmail message/thread ID", required: false }
+      ],
+      execute: markUnread
+    }
+  ];
+}
+
+// ============================================================================
+// INFO
+// ============================================================================
+
+/**
+ * Return high-level plugin context for the AI agent.
+ * @returns {object} PluginInfo per plugin interface contract
+ */
+export function getInfo() {
+  return {
+    recommendation: "Manage Gmail emails — list, read, search, compose, reply, forward, archive, delete, label, and mark as read/unread.",
+    description: "Gmail email management with hybrid UI resilience — list, read, search, compose, reply, forward, archive, delete, label, and mark emails using URL navigation (T1), keyboard shortcuts (T2), ARIA selectors (T3), and CSS fallback (T4).",
+    targetPages: ["Gmail inbox (mail.google.com)"],
+    authFlow: "User must be signed into Gmail in the browser before using plugin actions. The plugin does not handle Google account authentication.",
+    actions: getActions().map(({ name, description, params }) => ({ name, description, params }))
+  };
+}