mcpbrowser 0.3.34 → 0.3.36

package/src/plugins/gcal/actions/check-availability.js

@@ -0,0 +1,185 @@
+/**
+ * check-availability.js — Check whether a time slot is free or busy.
+ *
+ * Tier usage:
+ *   T1: calendarNavigate + buildViewPath to navigate to day view for the date
+ *   T3: extractVisibleEvents for event data extraction
+ *   T4: EVENT_CHIP selector via waitForCalendar
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  calendarNavigate,
+  buildViewPath,
+  waitForCalendar,
+  extractVisibleEvents,
+  GCalActionResponse
+} from '../helpers.js';
+import { EVENT_CHIP } from '../selectors.js';
+
+/**
+ * Parse HH:MM time string to total minutes since midnight.
+ * @param {string} timeStr - Time in HH:MM format
+ * @returns {number} Minutes since midnight
+ */
+function timeToMinutes(timeStr) {
+  const [h, m] = timeStr.split(':').map(Number);
+  return h * 60 + m;
+}
+
+/**
+ * Format minutes since midnight back to HH:MM.
+ * @param {number} minutes
+ * @returns {string}
+ */
+function minutesToTime(minutes) {
+  const h = Math.floor(minutes / 60);
+  const m = minutes % 60;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+}
+
+/**
+ * Check availability for a given date and time window.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.date - ISO date to check (required)
+ * @param {string} opts.params.startTime - Window start time in HH:MM (required)
+ * @param {string} opts.params.endTime - Window end time in HH:MM (required)
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function checkAvailability({ page, params }) {
+  // Validate required params
+  if (!params.date) {
+    return new ErrorResponse(
+      'The "date" parameter is required to check availability.',
+      ['Provide a date: check_availability({ date: "2026-04-10", startTime: "09:00", endTime: "17:00" })']
+    );
+  }
+  if (!params.startTime) {
+    return new ErrorResponse(
+      'The "startTime" parameter is required to check availability.',
+      ['Provide a start time: check_availability({ date: "2026-04-10", startTime: "09:00", endTime: "17:00" })']
+    );
+  }
+  if (!params.endTime) {
+    return new ErrorResponse(
+      'The "endTime" parameter is required to check availability.',
+      ['Provide an end time: check_availability({ date: "2026-04-10", startTime: "09:00", endTime: "17:00" })']
+    );
+  }
+
+  // Validate startTime < endTime
+  const windowStart = timeToMinutes(params.startTime);
+  const windowEnd = timeToMinutes(params.endTime);
+  if (windowStart >= windowEnd) {
+    return new ErrorResponse(
+      `startTime (${params.startTime}) must be earlier than endTime (${params.endTime}).`,
+      ['Ensure the start time is before the end time, e.g. startTime: "09:00", endTime: "17:00"']
+    );
+  }
+
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  // T1: Navigate to the day view for the specified date
+  const path = buildViewPath('day', params.date);
+  await calendarNavigate(page, path);
+  logger.debug(`checkAvailability: navigated to day view for ${params.date}`);
+
+  // Wait for event chips (or empty day)
+  let events = [];
+  try {
+    await waitForCalendar(page, EVENT_CHIP);
+    events = await extractVisibleEvents(page, 100);
+  } catch {
+    // No events — the entire window is free
+    logger.debug('checkAvailability: no events found, entire window is free');
+  }
+
+  // Filter events that overlap with the requested time window
+  const busySlots = [];
+  for (const event of events) {
+    if (event.allDay) {
+      // All-day events occupy the full day but don't block time slots
+      continue;
+    }
+
+    // Parse event times (best-effort from extracted data)
+    if (event.startTime && event.endTime) {
+      const eventStart = timeToMinutes(event.startTime);
+      const eventEnd = timeToMinutes(event.endTime);
+
+      // Check overlap: event overlaps window if event starts before window ends
+      // AND event ends after window starts
+      if (eventStart < windowEnd && eventEnd > windowStart) {
+        busySlots.push({
+          title: event.title,
+          startTime: event.startTime,
+          endTime: event.endTime
+        });
+      }
+    }
+  }
+
+  // Compute free slots within the window
+  const freeSlots = [];
+  // Sort busy slots by start time
+  busySlots.sort((a, b) => timeToMinutes(a.startTime) - timeToMinutes(b.startTime));
+
+  let cursor = windowStart;
+  for (const busy of busySlots) {
+    const busyStart = timeToMinutes(busy.startTime);
+    const busyEnd = timeToMinutes(busy.endTime);
+
+    if (cursor < busyStart) {
+      freeSlots.push({
+        startTime: minutesToTime(cursor),
+        endTime: minutesToTime(Math.min(busyStart, windowEnd)),
+        durationMinutes: Math.min(busyStart, windowEnd) - cursor
+      });
+    }
+    cursor = Math.max(cursor, busyEnd);
+  }
+
+  // Final free slot after all busy periods
+  if (cursor < windowEnd) {
+    freeSlots.push({
+      startTime: minutesToTime(cursor),
+      endTime: minutesToTime(windowEnd),
+      durationMinutes: windowEnd - cursor
+    });
+  }
+
+  const isFree = busySlots.length === 0;
+  const summary = isFree
+    ? `${params.date} from ${params.startTime} to ${params.endTime} is completely free.`
+    : `${params.date} from ${params.startTime} to ${params.endTime} has ${busySlots.length} conflicting event(s) and ${freeSlots.length} free slot(s).`;
+
+  return new GCalActionResponse(
+    {
+      date: params.date,
+      windowStart: params.startTime,
+      windowEnd: params.endTime,
+      isFree,
+      busySlots,
+      freeSlots,
+      conflictCount: busySlots.length
+    },
+    summary,
+    isFree
+      ? [`Use create_event({ date: "${params.date}", startTime: "${params.startTime}" }) to book this slot`]
+      : [
+          'Use create_event to book one of the free slots',
+          'Use check_availability with a different time range to find open slots',
+          'Use list_events to see all events on this date'
+        ]
+  );
+}

package/src/plugins/gcal/actions/create-event.js

@@ -0,0 +1,238 @@
+/**
+ * create-event.js — Create a new calendar event with title, time, location,
+ * description, and attendees.
+ *
+ * Tier usage:
+ *   T2: 'c' keyboard shortcut to open creation form
+ *   T3: ARIA dialog / input targeting for form filling
+ *   T4: SAVE_BUTTON selector for conditional save
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  checkKeyboardShortcuts,
+  waitForCalendar,
+  GCalActionResponse
+} from '../helpers.js';
+import { SAVE_BUTTON } from '../selectors.js';
+
+/**
+ * Create a new calendar event, optionally saving it immediately.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.title - Event title (required)
+ * @param {string} [opts.params.date] - Event date in ISO format
+ * @param {string} [opts.params.startTime] - Start time in HH:MM format
+ * @param {string} [opts.params.endTime] - End time in HH:MM format
+ * @param {boolean} [opts.params.allDay=false] - Create an all-day event
+ * @param {string} [opts.params.location] - Event location
+ * @param {string} [opts.params.description] - Event description/notes
+ * @param {string[]} [opts.params.attendees] - Array of attendee email addresses
+ * @param {boolean} [opts.params.save=false] - If true, save the event (FR-015)
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function createEvent({ page, params }) {
+  // Validate required param
+  if (!params.title) {
+    return new ErrorResponse(
+      'The "title" parameter is required to create an event.',
+      ['Provide a title: create_event({ title: "Team Meeting", date: "2026-04-10", startTime: "10:00" })']
+    );
+  }
+
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  // T2: Verify keyboard shortcuts are enabled
+  const kb = await checkKeyboardShortcuts(page);
+  if (!kb.enabled) {
+    return new ErrorResponse(kb.error, [
+      'Enable keyboard shortcuts in Google Calendar Settings → Keyboard shortcuts → Enable keyboard shortcuts, then reload Calendar.'
+    ]);
+  }
+
+  // FR-023: Close any existing dialog before opening a new one
+  const existingDialog = await page.$('div[role="dialog"]');
+  if (existingDialog) {
+    logger.debug('createEvent: closing existing dialog');
+    await page.keyboard.press('Escape');
+    await new Promise(r => setTimeout(r, 300));
+  }
+
+  // Ensure nothing is focused that would swallow the keystroke
+  await page.evaluate(() => {
+    if (document.activeElement && document.activeElement.tagName !== 'BODY') {
+      document.activeElement.blur();
+    }
+  });
+
+  // T2: Press 'c' to open create event form
+  await page.keyboard.press('c');
+
+  // Wait for the quick-add dialog or full event form
+  try {
+    await waitForCalendar(page, 'div[role="dialog"]');
+  } catch {
+    return new ErrorResponse(
+      'Event creation form did not appear. Keyboard shortcut "c" may not have worked.',
+      [
+        'Ensure keyboard shortcuts are enabled in Calendar Settings',
+        'Try clicking the "+" button on the calendar manually'
+      ]
+    );
+  }
+
+  // T3: Fill in the title field — target the title input inside the dialog
+  const titleInput = await page.$('input[aria-label="Add title"]') ||
+                     await page.$('input[data-initial-value]') ||
+                     await page.$('div[role="dialog"] input[type="text"]');
+  if (titleInput) {
+    await titleInput.click({ clickCount: 3 }); // select all existing text
+    await titleInput.type(params.title);
+    logger.debug(`createEvent: typed title "${params.title}"`);
+  }
+
+  // Check if we need to expand to the full form for additional fields
+  const hasExtraFields = params.date || params.startTime || params.endTime ||
+    params.location || params.description || params.attendees || params.allDay;
+
+  if (hasExtraFields) {
+    // Click "More options" to open full form if in quick-add mode
+    const moreOptions = await page.$('button[aria-label="More options"]') ||
+                        await page.$('[data-moreactions]');
+    if (moreOptions) {
+      await moreOptions.click();
+      logger.debug('createEvent: expanded to full form');
+      await new Promise(r => setTimeout(r, 500));
+    }
+  }
+
+  // T3: Fill date field if provided
+  if (params.date) {
+    const dateInput = await page.$('input[aria-label*="date" i]') ||
+                      await page.$('input[data-date]');
+    if (dateInput) {
+      await dateInput.click({ clickCount: 3 });
+      await dateInput.type(params.date);
+      await page.keyboard.press('Tab');
+      logger.debug(`createEvent: set date "${params.date}"`);
+    }
+  }
+
+  // T3: Toggle all-day if requested
+  if (params.allDay) {
+    const allDayCheckbox = await page.$('input[aria-label*="all day" i]') ||
+                           await page.$('[data-allday] input[type="checkbox"]');
+    if (allDayCheckbox) {
+      await allDayCheckbox.click();
+      logger.debug('createEvent: toggled all-day');
+    }
+  }
+
+  // T3: Fill start time if provided (and not all-day)
+  if (params.startTime && !params.allDay) {
+    const startInput = await page.$('input[aria-label*="start time" i]') ||
+                       await page.$('input[aria-label*="Start time" i]');
+    if (startInput) {
+      await startInput.click({ clickCount: 3 });
+      await startInput.type(params.startTime);
+      await page.keyboard.press('Tab');
+      logger.debug(`createEvent: set startTime "${params.startTime}"`);
+    }
+  }
+
+  // T3: Fill end time if provided (and not all-day)
+  if (params.endTime && !params.allDay) {
+    const endInput = await page.$('input[aria-label*="end time" i]') ||
+                     await page.$('input[aria-label*="End time" i]');
+    if (endInput) {
+      await endInput.click({ clickCount: 3 });
+      await endInput.type(params.endTime);
+      await page.keyboard.press('Tab');
+      logger.debug(`createEvent: set endTime "${params.endTime}"`);
+    }
+  }
+
+  // T3: Fill location if provided
+  if (params.location) {
+    const locationInput = await page.$('input[aria-label*="location" i]') ||
+                          await page.$('[data-locationactionpanel] input');
+    if (locationInput) {
+      await locationInput.click();
+      await locationInput.type(params.location);
+      await page.keyboard.press('Tab');
+      logger.debug(`createEvent: set location "${params.location}"`);
+    }
+  }
+
+  // T3: Fill description if provided
+  if (params.description) {
+    const descInput = await page.$('div[aria-label*="description" i][contenteditable]') ||
+                      await page.$('textarea[aria-label*="description" i]') ||
+                      await page.$('[data-description] [contenteditable]');
+    if (descInput) {
+      await descInput.click();
+      await descInput.type(params.description);
+      logger.debug('createEvent: set description');
+    }
+  }
+
+  // T3: Add attendees if provided
+  if (params.attendees && params.attendees.length > 0) {
+    const guestInput = await page.$('input[aria-label*="guest" i]') ||
+                       await page.$('input[aria-label*="Add guests" i]');
+    if (guestInput) {
+      for (const email of params.attendees) {
+        await guestInput.click();
+        await guestInput.type(email);
+        await page.keyboard.press('Enter');
+        await new Promise(r => setTimeout(r, 200));
+      }
+      logger.debug(`createEvent: added ${params.attendees.length} attendee(s)`);
+    }
+  }
+
+  // FR-015: Conditionally save — default is false (leave for review)
+  const save = params.save === true;
+  if (save) {
+    const saveBtn = await page.$(SAVE_BUTTON) ||
+                    await page.$('button[aria-label="Save"]') ||
+                    await page.$('div[role="dialog"] button:has-text("Save")');
+    if (saveBtn) {
+      await saveBtn.click();
+      logger.debug('createEvent: clicked Save');
+      await new Promise(r => setTimeout(r, 500));
+    }
+  }
+
+  const status = save ? 'saved' : 'draft';
+  const summary = save
+    ? `Event "${params.title}" created and saved.`
+    : `Event "${params.title}" form filled. Review and save in Calendar.`;
+
+  return new GCalActionResponse(
+    {
+      status,
+      title: params.title,
+      date: params.date || 'today',
+      startTime: params.startTime || null,
+      endTime: params.endTime || null,
+      allDay: params.allDay || false,
+      location: params.location || null,
+      attendees: params.attendees || [],
+      save
+    },
+    summary,
+    save
+      ? ['Use list_events to see the updated calendar']
+      : ['Review the event form in Calendar and click Save manually', 'Use list_events to return to calendar view']
+  );
+}

package/src/plugins/gcal/actions/delete-event.js

@@ -0,0 +1,138 @@
+/**
+ * delete-event.js — Remove an event from Google Calendar.
+ *
+ * Tier usage:
+ *   T2: Delete/Backspace keyboard shortcut to delete event
+ *   T3: selectEvent for clicking event chip, ARIA dialog for confirmation
+ *
+ * FR-022: Precondition check before destructive keyboard action.
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  selectEvent,
+  waitForCalendar,
+  detectView,
+  VIEW,
+  GCalActionResponse
+} from '../helpers.js';
+
+/**
+ * Delete an event by index or event ID.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {number} [opts.params.index] - 0-based position in current event list
+ * @param {string} [opts.params.id] - Google Calendar event ID
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function deleteEvent({ page, params }) {
+  // Validate: at least one identifier required
+  if (params.index == null && params.id == null) {
+    return new ErrorResponse(
+      'Either index or id is required to delete an event.',
+      [
+        'Use list_events to see available events and their indices',
+        'Use search_events to find a specific event by keyword'
+      ]
+    );
+  }
+
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  // T3: Select (click) the target event to open detail popup
+  const sel = await selectEvent(page, { index: params.index, id: params.id });
+  if (!sel.selected) {
+    return new ErrorResponse(
+      sel.error || 'Could not select the event to delete.',
+      ['Use list_events to refresh the event list and check indices']
+    );
+  }
+
+  // Wait for detail popup
+  try {
+    await waitForCalendar(page, 'div[role="dialog"]');
+  } catch {
+    return new ErrorResponse(
+      'Event detail popup did not appear after clicking the event.',
+      ['Try list_events to refresh, then delete_event with a valid index']
+    );
+  }
+
+  // Detect recurring event dialog — if it appears, select "This event"
+  const recurringDialog = await page.evaluate(() => {
+    const buttons = Array.from(document.querySelectorAll('button, span[role="radio"]'));
+    return buttons.some(b => b.textContent?.includes('This event'));
+  });
+  let recurringNote = null;
+  if (recurringDialog) {
+    const thisEventBtn = await page.evaluateHandle(() => {
+      const elements = Array.from(document.querySelectorAll('button, span[role="radio"], label'));
+      return elements.find(el => el.textContent?.includes('This event'));
+    });
+    if (thisEventBtn && thisEventBtn.asElement()) {
+      await thisEventBtn.asElement().click();
+      await new Promise(r => setTimeout(r, 300));
+      recurringNote = 'Deleted this single occurrence of a recurring event.';
+      logger.debug('deleteEvent: selected "This event" for recurring event');
+    }
+  }
+
+  // FR-022: Precondition check — verify we're in the right context
+  // before sending destructive keyboard shortcut
+  const view = await detectView(page);
+  const hasDialog = await page.$('div[role="dialog"]');
+  if (!hasDialog && view === VIEW.NOT_CALENDAR) {
+    return new ErrorResponse(
+      'Cannot delete: lost context. The event dialog is no longer visible.',
+      ['Use list_events to refresh, then try delete_event again']
+    );
+  }
+
+  // T2: Click the "Delete event" button or press Delete/Backspace
+  const deleteBtn = await page.$('button[aria-label="Delete event"]') ||
+                    await page.$('button[aria-label*="delete" i]') ||
+                    await page.$('[data-deletebtn]');
+  if (deleteBtn) {
+    await deleteBtn.click();
+    logger.debug('deleteEvent: clicked Delete button');
+  } else {
+    // Fallback: use keyboard shortcut
+    await page.keyboard.press('Delete');
+    logger.debug('deleteEvent: pressed Delete key');
+  }
+
+  // Wait for confirmation or undo toast
+  await new Promise(r => setTimeout(r, 500));
+
+  // Check for confirmation dialog (some events require explicit confirmation)
+  const confirmBtn = await page.evaluateHandle(() => {
+    const buttons = Array.from(document.querySelectorAll('button'));
+    return buttons.find(b =>
+      b.textContent?.includes('Delete') ||
+      b.textContent?.includes('Remove')
+    );
+  });
+  if (confirmBtn && confirmBtn.asElement()) {
+    await confirmBtn.asElement().click();
+    logger.debug('deleteEvent: confirmed deletion');
+    await new Promise(r => setTimeout(r, 300));
+  }
+
+  return new GCalActionResponse(
+    {
+      deleted: true,
+      recurringNote
+    },
+    recurringNote || 'Event deleted successfully.',
+    ['Use list_events to see the updated calendar']
+  );
+}