mcpbrowser 0.3.34 → 0.3.36

package/src/plugins/gcal/selectors.js

@@ -0,0 +1,54 @@
+/**
+ * selectors.js — Tier 4 CSS class selectors for the Google Calendar plugin.
+ *
+ * TIER 4 ONLY — These are Closure Compiler-generated class names that may
+ * change when Google deploys Calendar updates. All other interaction tiers
+ * (T1: URL path navigation, T2: keyboard shortcuts, T3: ARIA / data attributes)
+ * are defined inline in helpers.js since they use stable identifiers.
+ *
+ * Per FR-021: All CSS class selectors are centralized here so a Calendar UI
+ * update can be resolved by updating values in ONE place.
+ *
+ * Per SC-008: No action file should import CSS class names directly.
+ * All CSS access goes through this module.
+ *
+ * Tier coverage (SC-007): ~75% of interactions use T1/T2 (URL + keyboard).
+ * These T4 selectors cover only data extraction from event chips and detail
+ * popups where no ARIA/data-attribute alternative exists.
+ *
+ * @version 2026-04-06 — Initial capture against Google Calendar web UI
+ */
+
+// CALENDAR VIEW — Event chips (used by extractVisibleEvents)
+// No ARIA alternative: event chip container uses generated classes
+export const EVENT_CHIP = '[data-eventchip]';
+// No ARIA alternative: title text within chip is plain span
+export const EVENT_TITLE_IN_CHIP = 'span';
+// No ARIA alternative: time text within chip lacks data attributes
+export const EVENT_TIME_IN_CHIP = 'span';
+
+// EVENT DETAIL POPUP — Fields in the detail popup (used by read_event)
+// No ARIA alternative: location line lacks role/data attributes
+export const EVENT_LOCATION_IN_DETAIL = '[data-location]';
+// No ARIA alternative: description area uses contenteditable without data-attr
+export const EVENT_DESCRIPTION_IN_DETAIL = '[data-description]';
+
+// ATTENDEES — Within event detail popup (used by read_event, rsvp_event)
+// No ARIA alternative: attendee rows lack role="listitem"
+export const ATTENDEE_ROW = '[data-guest-email]';
+// No ARIA alternative: RSVP icons use generated classes
+export const ATTENDEE_RSVP_STATUS = '[data-rsvp]';
+
+// RSVP BUTTONS — Within event detail popup (used by rsvp_event)
+// No ARIA alternative: RSVP buttons lack unique aria-label
+export const RSVP_YES_BUTTON = '[data-response="1"]';
+export const RSVP_NO_BUTTON = '[data-response="2"]';
+export const RSVP_MAYBE_BUTTON = '[data-response="3"]';
+
+// CALENDAR INDICATOR — Color dot on event chips
+// No ARIA alternative: color indicator is CSS-only
+export const CALENDAR_COLOR_DOT = '[data-calendar-color]';
+
+// FORM CONTROLS — Event creation/edit form (used by create_event, edit_event)
+// No ARIA alternative: save button lacks unique accessible name
+export const SAVE_BUTTON = '[data-savebtn]';

package/src/plugins/gmail/actions/archive-email.js

@@ -0,0 +1,65 @@
+/**
+ * archive-email.js — Archive an email, removing it from the inbox.
+ *
+ * Tier usage:
+ *   T2: 'e' keyboard shortcut to archive
+ *   T3: selectEmailRow for list view targeting
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  detectView,
+  selectEmailRow,
+  VIEW,
+  GmailActionResponse
+} from '../helpers.js';
+
+/**
+ * Archive an email from thread view or list view.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {number} [opts.params.index] - Email index in list view
+ * @param {string} [opts.params.id] - Email ID in list view
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function archiveEmail({ page, params }) {
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  const view = await detectView(page);
+
+  if (view === VIEW.THREAD) {
+    // In thread view, archive directly
+    await page.keyboard.press('e');
+    logger.debug('archiveEmail: pressed "e" in thread view');
+  } else if (view === VIEW.EMAIL_LIST || view === VIEW.SEARCH_RESULTS) {
+    // In list view, select the row first
+    const sel = await selectEmailRow(page, { index: params.index, id: params.id });
+    if (!sel.selected) {
+      return new ErrorResponse(sel.error || 'Could not select email to archive.', [
+        'Provide an index or id parameter to target a specific email.'
+      ]);
+    }
+    await page.keyboard.press('e');
+    logger.debug('archiveEmail: selected row and pressed "e"');
+  } else {
+    return new ErrorResponse(
+      'Cannot archive from the current view. Navigate to inbox or open an email first.',
+      ["Use list_emails to view the inbox, or read_email to open a thread."]
+    );
+  }
+
+  return new GmailActionResponse(
+    { archived: true },
+    'Email archived successfully.',
+    ['Use list_emails to return to inbox']
+  );
+}

package/src/plugins/gmail/actions/compose-email.js

@@ -0,0 +1,116 @@
+/**
+ * compose-email.js — Compose and optionally send a new email in Gmail.
+ *
+ * Tier usage:
+ *   T2: 'c' keyboard shortcut to open compose, Ctrl+Enter to send
+ *   T3: ARIA dialog, textarea[name], input[name], div[aria-label]
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  checkKeyboardShortcuts,
+  waitForGmail,
+  GmailActionResponse
+} from '../helpers.js';
+
+/**
+ * Compose a new email, optionally sending it immediately.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.to - Recipient email address (required)
+ * @param {string} [opts.params.cc] - CC recipients
+ * @param {string} [opts.params.subject] - Email subject
+ * @param {string} [opts.params.body] - Email body text
+ * @param {boolean} [opts.params.send] - If true, send immediately
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function composeEmail({ page, params }) {
+  // Validate required param
+  if (!params.to) {
+    return new ErrorResponse(
+      'The "to" parameter is required to compose an email.',
+      ['Provide a recipient: compose_email({ to: "user@example.com", subject: "Hello" })']
+    );
+  }
+
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  // Verify keyboard shortcuts are enabled
+  const kb = await checkKeyboardShortcuts(page);
+  if (!kb.enabled) {
+    return new ErrorResponse(kb.error, [
+      'Enable keyboard shortcuts in Gmail Settings → General → Keyboard shortcuts → ON, then reload Gmail.'
+    ]);
+  }
+
+  // Close any existing compose dialog
+  const existingDialog = await page.$('div[role="dialog"]');
+  if (existingDialog) {
+    logger.debug('composeEmail: closing existing compose dialog');
+    await page.keyboard.press('Escape');
+    await new Promise(r => setTimeout(r, 300));
+  }
+
+  // T2: Press 'c' to open compose
+  await page.keyboard.press('c');
+
+  // Wait for compose dialog to appear
+  await waitForGmail(page, 'div[role="dialog"]');
+
+  // Fill To field
+  await page.type('textarea[name="to"]', params.to);
+  await page.keyboard.press('Tab');
+
+  // Fill CC if provided
+  if (params.cc) {
+    const ccLink = await page.$('span[data-tooltip="Add Cc"]') ||
+                   await page.$('span.aB.gQ.pE');
+    if (ccLink) {
+      await ccLink.click();
+    }
+    await page.type('textarea[name="cc"]', params.cc);
+    await page.keyboard.press('Tab');
+  }
+
+  // Fill Subject
+  await page.type('input[name="subjectbox"]', params.subject || '');
+
+  // Fill Body
+  const bodyDiv = await page.$('div[aria-label="Message Body"]');
+  if (bodyDiv) {
+    await bodyDiv.click();
+    if (params.body) {
+      await page.type('div[aria-label="Message Body"]', params.body);
+    }
+  }
+
+  // Send if requested
+  if (params.send) {
+    await page.keyboard.down('Control');
+    await page.keyboard.press('Enter');
+    await page.keyboard.up('Control');
+    logger.debug('composeEmail: sent via Ctrl+Enter');
+  }
+
+  const status = params.send ? 'sent' : 'draft';
+  const summary = params.send
+    ? `Email sent to ${params.to}.`
+    : `Compose draft created for ${params.to}.`;
+
+  return new GmailActionResponse(
+    { status, to: params.to, subject: params.subject || '' },
+    summary,
+    params.send
+      ? ['Use list_emails to return to inbox']
+      : ['Review and send the draft manually in Gmail']
+  );
+}

package/src/plugins/gmail/actions/delete-email.js

@@ -0,0 +1,65 @@
+/**
+ * delete-email.js — Delete an email by moving it to trash.
+ *
+ * Tier usage:
+ *   T2: '#' keyboard shortcut to move to trash
+ *   T3: selectEmailRow for list view targeting
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  detectView,
+  selectEmailRow,
+  VIEW,
+  GmailActionResponse
+} from '../helpers.js';
+
+/**
+ * Delete an email (move to trash) from thread view or list view.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {number} [opts.params.index] - Email index in list view
+ * @param {string} [opts.params.id] - Email ID in list view
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function deleteEmail({ page, params }) {
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  const view = await detectView(page);
+
+  if (view === VIEW.THREAD) {
+    // In thread view, delete directly
+    await page.keyboard.type('#');
+    logger.debug('deleteEmail: typed "#" in thread view');
+  } else if (view === VIEW.EMAIL_LIST || view === VIEW.SEARCH_RESULTS) {
+    // In list view, select the row first
+    const sel = await selectEmailRow(page, { index: params.index, id: params.id });
+    if (!sel.selected) {
+      return new ErrorResponse(sel.error || 'Could not select email to delete.', [
+        'Provide an index or id parameter to target a specific email.'
+      ]);
+    }
+    await page.keyboard.type('#');
+    logger.debug('deleteEmail: selected row and typed "#"');
+  } else {
+    return new ErrorResponse(
+      'Cannot delete from the current view. Navigate to inbox or open an email first.',
+      ["Use list_emails to view the inbox, or read_email to open a thread."]
+    );
+  }
+
+  return new GmailActionResponse(
+    { deleted: true },
+    'Email moved to trash.',
+    ['Use list_emails to return to inbox']
+  );
+}

package/src/plugins/gmail/actions/forward-email.js

@@ -0,0 +1,95 @@
+/**
+ * forward-email.js — Forward the currently open email to another recipient.
+ *
+ * Tier usage:
+ *   T2: 'f' keyboard shortcut to open forward, Ctrl+Enter to send
+ *   T3: ARIA dialog, textarea[name="to"], div[aria-label="Message Body"]
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  checkKeyboardShortcuts,
+  waitForGmail,
+  GmailActionResponse
+} from '../helpers.js';
+
+/**
+ * Forward the currently open email thread.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.to - Recipient to forward to (required)
+ * @param {string} [opts.params.body] - Additional body text
+ * @param {boolean} [opts.params.send] - If true, send immediately
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function forwardEmail({ page, params }) {
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  // Precondition: must have a thread open
+  const threadPre = await checkPrecondition(page, 'thread_open');
+  if (!threadPre.met) {
+    return new ErrorResponse(threadPre.error, [
+      threadPre.suggestion || "Use read_email to open an email thread first."
+    ]);
+  }
+
+  // Verify keyboard shortcuts are enabled
+  const kb = await checkKeyboardShortcuts(page);
+  if (!kb.enabled) {
+    return new ErrorResponse(kb.error, [
+      'Enable keyboard shortcuts in Gmail Settings → General → Keyboard shortcuts → ON, then reload Gmail.'
+    ]);
+  }
+
+  // T2: Press 'f' to open forward
+  await page.keyboard.press('f');
+  logger.debug('forwardEmail: pressed "f" to open forward dialog');
+
+  // Wait for forward dialog
+  await waitForGmail(page, 'div[role="dialog"]');
+
+  // Fill To field
+  if (params.to) {
+    await page.type('textarea[name="to"]', params.to);
+    await page.keyboard.press('Tab');
+  }
+
+  // Fill additional body text if provided
+  if (params.body) {
+    const bodyDiv = await page.$('div[aria-label="Message Body"]');
+    if (bodyDiv) {
+      await bodyDiv.click();
+      await page.type('div[aria-label="Message Body"]', params.body);
+    }
+  }
+
+  // Send if requested
+  if (params.send) {
+    await page.keyboard.down('Control');
+    await page.keyboard.press('Enter');
+    await page.keyboard.up('Control');
+    logger.debug('forwardEmail: sent via Ctrl+Enter');
+  }
+
+  const status = params.send ? 'sent' : 'draft';
+  const summary = params.send
+    ? `Email forwarded to ${params.to || '(no recipient)'}.`
+    : `Forward draft created. Fill in recipients and send manually.`;
+
+  return new GmailActionResponse(
+    { status, to: params.to || '' },
+    summary,
+    params.send
+      ? ['Use list_emails to return to inbox']
+      : ['Review and send the forward draft manually in Gmail']
+  );
+}

package/src/plugins/gmail/actions/label-email.js

@@ -0,0 +1,107 @@
+/**
+ * label-email.js — Apply a label to an email using the label picker.
+ *
+ * Tier usage:
+ *   T2: 'l' keyboard shortcut to open label picker
+ *   T3: selectEmailRow for list view targeting
+ *   T4: LABEL_ITEM selector for matching labels
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  checkKeyboardShortcuts,
+  detectView,
+  selectEmailRow,
+  waitForGmail,
+  VIEW,
+  GmailActionResponse
+} from '../helpers.js';
+import { LABEL_ITEM } from '../selectors.js';
+
+/**
+ * Apply a label to an email.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.label - Label name to apply (required)
+ * @param {number} [opts.params.index] - Email index in list view
+ * @param {string} [opts.params.id] - Email ID in list view
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function labelEmail({ page, params }) {
+  // Validate required param
+  if (!params.label) {
+    return new ErrorResponse(
+      'The "label" parameter is required.',
+      ['Provide a label name: label_email({ label: "Important" })']
+    );
+  }
+
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  const view = await detectView(page);
+
+  // Select email row if in list view
+  if (view === VIEW.EMAIL_LIST || view === VIEW.SEARCH_RESULTS) {
+    const sel = await selectEmailRow(page, { index: params.index, id: params.id });
+    if (!sel.selected) {
+      return new ErrorResponse(sel.error || 'Could not select email to label.', [
+        'Provide an index or id parameter to target a specific email.'
+      ]);
+    }
+  }
+
+  // Verify keyboard shortcuts are enabled
+  const kb = await checkKeyboardShortcuts(page);
+  if (!kb.enabled) {
+    return new ErrorResponse(kb.error, [
+      'Enable keyboard shortcuts in Gmail Settings → General → Keyboard shortcuts → ON, then reload Gmail.'
+    ]);
+  }
+
+  // T2: Press 'l' to open label picker
+  await page.keyboard.press('l');
+  logger.debug('labelEmail: pressed "l" to open label picker');
+
+  // Wait for label picker overlay
+  await waitForGmail(page, LABEL_ITEM);
+
+  // Find matching label in the picker
+  const result = await page.evaluate((selector, targetLabel) => {
+    const items = document.querySelectorAll(selector);
+    const labels = [];
+    for (const item of items) {
+      const text = item.textContent?.trim() || '';
+      labels.push(text);
+      if (text.toLowerCase() === targetLabel.toLowerCase()) {
+        item.click();
+        return { found: true, label: text };
+      }
+    }
+    return { found: false, visibleLabels: labels };
+  }, LABEL_ITEM, params.label);
+
+  if (!result.found) {
+    return new ErrorResponse(
+      `Label "${params.label}" not found in the label picker.`,
+      [
+        `Available labels: ${(result.visibleLabels || []).join(', ') || '(none visible)'}`,
+        'Check the exact label name and try again.'
+      ]
+    );
+  }
+
+  return new GmailActionResponse(
+    { labeled: true, label: result.label },
+    `Label "${result.label}" applied to email.`,
+    ['Use list_emails to return to inbox']
+  );
+}

package/src/plugins/gmail/actions/list-emails.js

@@ -0,0 +1,61 @@
+/**
+ * list-emails.js — List emails from Gmail inbox or specified folder/label.
+ *
+ * Tier usage:
+ *   T1: gmailNavigate to folder hash
+ *   T4: EMAIL_ROW selector for waitForGmail + extractEmailRows
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import {
+  checkPrecondition,
+  gmailNavigate,
+  folderToHash,
+  waitForGmail,
+  extractEmailRows,
+  GmailActionResponse
+} from '../helpers.js';
+import { EMAIL_ROW } from '../selectors.js';
+
+/**
+ * List emails from the current Gmail view or a specific folder.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} [opts.params.folder] - Folder name (inbox, sent, drafts, label name, etc.)
+ * @param {number} [opts.params.limit=25] - Maximum emails to return
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function listEmails({ page, params }) {
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  const folder = params.folder || 'inbox';
+  const limit = params.limit || 25;
+
+  // T1: Navigate to the requested folder
+  if (params.folder) {
+    await gmailNavigate(page, folderToHash(params.folder));
+  }
+
+  // T4: Wait for email rows to appear
+  await waitForGmail(page, EMAIL_ROW);
+
+  // T3+T4: Extract visible email data
+  const emails = await extractEmailRows(page, limit);
+
+  return new GmailActionResponse(
+    { emails, folder, totalVisible: emails.length },
+    `Found ${emails.length} email(s) in ${folder}.`,
+    [
+      'Use read_email to open a specific email',
+      'Use search_emails to find specific messages',
+      'Use compose_email to write a new email'
+    ]
+  );
+}

package/src/plugins/gmail/actions/mark-read.js

@@ -0,0 +1,71 @@
+/**
+ * mark-read.js — Mark an email as read in list view.
+ *
+ * Tier usage:
+ *   T2: Shift+i keyboard shortcut to mark as read
+ *   T3: selectEmailRow for targeting
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  checkKeyboardShortcuts,
+  selectEmailRow,
+  GmailActionResponse
+} from '../helpers.js';
+
+/**
+ * Mark an email as read in list view.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {number} [opts.params.index] - Email index
+ * @param {string} [opts.params.id] - Email ID
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function markRead({ page, params }) {
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  // Precondition: must be in list view
+  const listPre = await checkPrecondition(page, 'list_view');
+  if (!listPre.met) {
+    return new ErrorResponse(listPre.error, [
+      listPre.suggestion || "Use list_emails to navigate to an email list first."
+    ]);
+  }
+
+  // Verify keyboard shortcuts are enabled
+  const kb = await checkKeyboardShortcuts(page);
+  if (!kb.enabled) {
+    return new ErrorResponse(kb.error, [
+      'Enable keyboard shortcuts in Gmail Settings → General → Keyboard shortcuts → ON, then reload Gmail.'
+    ]);
+  }
+
+  // Select the email row
+  const sel = await selectEmailRow(page, { index: params.index, id: params.id });
+  if (!sel.selected) {
+    return new ErrorResponse(sel.error || 'Could not select email.', [
+      'Provide an index or id parameter to target a specific email.'
+    ]);
+  }
+
+  // T2: Shift+i to mark as read
+  await page.keyboard.down('Shift');
+  await page.keyboard.press('KeyI');
+  await page.keyboard.up('Shift');
+  logger.debug('markRead: pressed Shift+i');
+
+  return new GmailActionResponse(
+    { markedRead: true },
+    'Email marked as read.',
+    ['Use list_emails to refresh the email list']
+  );
+}