@everydaydevopsio/pilot 0.6.2 → 0.7.0

package/src/browser/driver/cdp-driver.ts

@@ -0,0 +1,260 @@
+import type { Client } from 'chrome-remote-interface';
+import { BrowserManager } from '../browser-manager.js';
+import type { LaunchOptions, SessionInfo, TabInfo } from '../types.js';
+import { resetCssState } from '../inspect/styles.js';
+import { attachDialogHandler } from '../interaction/dialogs.js';
+import {
+  attachDownloadHandler,
+  enableDownloads
+} from '../interaction/downloads.js';
+import { attachNetworkMonitor } from '../network/network-monitor.js';
+import type { ConsoleMessage } from '../../mcp/console-buffer.js';
+import type { Config } from '../../util/config.js';
+import { applyViewport, type ViewportConfig } from '../../viewport.js';
+import { executeCheck, type CheckParams } from '../../commands/check.js';
+import { executeClick, type ClickParams } from '../../commands/click.js';
+import { executeDialog, type DialogParams } from '../../commands/dialog.js';
+import {
+  executeEvaluate,
+  type EvaluateParams
+} from '../../commands/evaluate.js';
+import { executeFill, type FillParams } from '../../commands/fill.js';
+import { executeFind, type FindQuery } from '../../commands/find.js';
+import { executeHover, type HoverParams } from '../../commands/hover.js';
+import {
+  executeNavigate,
+  type NavigateParams
+} from '../../commands/navigate.js';
+import { executeNetwork, type NetworkParams } from '../../commands/network.js';
+import { executePageInfo } from '../../commands/page_info.js';
+import {
+  executePerformance,
+  type PerformanceParams
+} from '../../commands/performance.js';
+import {
+  executePressKey,
+  type PressKeyParams
+} from '../../commands/press_key.js';
+import {
+  executeScreenshot,
+  type ScreenshotParams
+} from '../../commands/screenshot.js';
+import { executeScroll, type ScrollParams } from '../../commands/scroll.js';
+import { executeSelect, type SelectParams } from '../../commands/select.js';
+import { executeSnapshot } from '../../commands/snapshot.js';
+import { executeStyles, type StylesParams } from '../../commands/styles.js';
+import {
+  executeCloseTab,
+  executeListTabs,
+  executeNewTab,
+  executeSwitchTab,
+  type NewTabResult
+} from '../../commands/tabs.js';
+import { executeType, type TypeParams } from '../../commands/type.js';
+import { executeUpload, type UploadParams } from '../../commands/upload.js';
+import { executeWait, type WaitParams } from '../../commands/wait.js';
+import {
+  CAPABILITIES,
+  type BrowserDriver,
+  type Capability,
+  type ConnectExistingOptions,
+  type DriverSession,
+  type ViewportResizeParams
+} from './types.js';
+
+const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set(CAPABILITIES);
+
+/**
+ * Chrome driver over the Chrome DevTools Protocol. BrowserManager owns the
+ * Chrome process and CDP connection; this class wires CDP events into the
+ * session buffers and maps driver calls onto the CDP command implementations.
+ */
+export class CdpDriver implements BrowserDriver {
+  readonly kind = 'chrome' as const;
+  readonly capabilities = CDP_CAPABILITIES;
+  private monitoredClient: Client | null = null;
+
+  constructor(
+    private readonly session: DriverSession,
+    private readonly manager: BrowserManager
+  ) {
+    manager.setEventCallback((event, data) => this.onBrowserEvent(event, data));
+  }
+
+  static create(config: Config, session: DriverSession): CdpDriver {
+    return new CdpDriver(session, new BrowserManager(config));
+  }
+
+  private onBrowserEvent(event: string, data: unknown): void {
+    if (event === 'console_message') {
+      this.session.consoleBuffer.push(data as ConsoleMessage);
+    }
+    if (event === 'page_navigated') {
+      this.session.elementRefMap.invalidate();
+    }
+    if (event === 'browser_disconnected') {
+      this.monitoredClient = null;
+      resetCssState();
+      this.session.dialogQueue.clear();
+      this.session.downloadTracker.clear();
+      return;
+    }
+    // Covers browser_connected and tab switches, which swap the CDP client
+    // without emitting a connect event.
+    this.ensureMonitors();
+  }
+
+  private ensureMonitors(): void {
+    const client = this.manager.getClient();
+    if (!client || client === this.monitoredClient) return;
+    attachNetworkMonitor(client, this.session.networkBuffer);
+    attachDialogHandler(client, this.session.dialogQueue);
+    attachDownloadHandler(client, this.session.downloadTracker);
+    void enableDownloads(client).catch(() => {
+      // Download behavior setup may fail in some environments
+    });
+    this.monitoredClient = client;
+  }
+
+  private client(): Client {
+    const client = this.manager.getClient();
+    if (!client) {
+      throw new Error('Browser not started. Call browser_start first.');
+    }
+    return client;
+  }
+
+  launch(opts?: LaunchOptions) {
+    return this.manager.launch(opts);
+  }
+
+  connectExisting(opts: ConnectExistingOptions): Promise<{ tabs: TabInfo[] }> {
+    return this.manager.connectExisting(opts);
+  }
+
+  destroy(): Promise<void> {
+    return this.manager.destroy();
+  }
+
+  isConnected(): boolean {
+    return this.manager.isConnected();
+  }
+
+  getSessionInfo(): SessionInfo {
+    return { browser: this.kind, ...this.manager.getSessionInfo() };
+  }
+
+  listTabs(): Promise<TabInfo[]> {
+    return executeListTabs(this.manager);
+  }
+
+  newTab(url?: string): Promise<NewTabResult> {
+    return executeNewTab(this.manager, url);
+  }
+
+  closeTab(targetId: string): Promise<void> {
+    return executeCloseTab(this.manager, targetId);
+  }
+
+  switchTab(targetId: string): Promise<void> {
+    return executeSwitchTab(this.manager, targetId);
+  }
+
+  navigate(params: NavigateParams) {
+    return executeNavigate(this.client(), this.manager, params);
+  }
+
+  pageInfo() {
+    return executePageInfo(this.client());
+  }
+
+  evaluate(params: EvaluateParams) {
+    return executeEvaluate(this.client(), params);
+  }
+
+  wait(params: WaitParams) {
+    return executeWait(this.client(), this.manager, params);
+  }
+
+  screenshot(params: ScreenshotParams) {
+    return executeScreenshot(this.client(), params);
+  }
+
+  async resizeViewport(params: ViewportResizeParams): Promise<ViewportConfig> {
+    const client = this.client();
+    const current = this.manager.getViewportConfig();
+    const mobile = params.mobile ?? current?.mobile ?? false;
+    const config: ViewportConfig = {
+      width: params.width,
+      height: params.height,
+      deviceScaleFactor:
+        params.deviceScaleFactor ?? current?.deviceScaleFactor ?? 1,
+      mobile,
+      responsive: false,
+      ...(mobile && current?.userAgent && { userAgent: current.userAgent })
+    };
+    await applyViewport(client, config);
+    this.manager.setViewportConfig(config);
+    return config;
+  }
+
+  snapshot() {
+    return executeSnapshot(this.client(), this.session.elementRefMap);
+  }
+
+  find(query: FindQuery) {
+    return executeFind(this.client(), this.session.elementRefMap, query);
+  }
+
+  styles(params: StylesParams) {
+    return executeStyles(this.client(), this.session.elementRefMap, params);
+  }
+
+  click(params: ClickParams) {
+    return executeClick(this.client(), params, this.session.elementRefMap);
+  }
+
+  type(params: TypeParams) {
+    return executeType(this.client(), params, this.session.elementRefMap);
+  }
+
+  fill(params: FillParams) {
+    return executeFill(this.client(), this.session.elementRefMap, params);
+  }
+
+  hover(params: HoverParams) {
+    return executeHover(this.client(), this.session.elementRefMap, params);
+  }
+
+  pressKey(params: PressKeyParams) {
+    return executePressKey(this.client(), params);
+  }
+
+  select(params: SelectParams) {
+    return executeSelect(this.client(), this.session.elementRefMap, params);
+  }
+
+  check(params: CheckParams) {
+    return executeCheck(this.client(), this.session.elementRefMap, params);
+  }
+
+  scroll(params: ScrollParams) {
+    return executeScroll(this.client(), this.session.elementRefMap, params);
+  }
+
+  dialog(params: DialogParams) {
+    return executeDialog(this.client(), this.session.dialogQueue, params);
+  }
+
+  upload(params: UploadParams) {
+    return executeUpload(this.client(), this.session.elementRefMap, params);
+  }
+
+  network(params: NetworkParams) {
+    return executeNetwork(this.client(), this.session.networkBuffer, params);
+  }
+
+  performance(params: PerformanceParams) {
+    return executePerformance(this.client(), this.session.traceState, params);
+  }
+}

package/src/browser/driver/factory.ts

@@ -0,0 +1,33 @@
+import type { Config } from '../../util/config.js';
+import { CdpDriver } from './cdp-driver.js';
+import type { BrowserDriver, BrowserKind, DriverSession } from './types.js';
+
+/** Tracking issues for browsers that do not have a driver yet. */
+export const PLANNED_DRIVERS: Readonly<
+  Record<Exclude<BrowserKind, 'chrome'>, string>
+> = {
+  firefox: 'https://github.com/everydaydevopsio/pilot/issues/58',
+  safari: 'https://github.com/everydaydevopsio/pilot/issues/60',
+  webkit: 'https://github.com/everydaydevopsio/pilot/issues/61'
+};
+
+export class UnsupportedBrowserError extends Error {
+  constructor(readonly browser: Exclude<BrowserKind, 'chrome'>) {
+    super(
+      `Pilot does not support ${browser} yet; only chrome is available. ` +
+        `Progress is tracked in ${PLANNED_DRIVERS[browser]}.`
+    );
+    this.name = 'UnsupportedBrowserError';
+  }
+}
+
+export function createDriver(
+  kind: BrowserKind,
+  config: Config,
+  session: DriverSession
+): BrowserDriver {
+  if (kind === 'chrome') {
+    return CdpDriver.create(config, session);
+  }
+  throw new UnsupportedBrowserError(kind);
+}

package/src/browser/driver/index.ts

@@ -0,0 +1,22 @@
+export { CdpDriver } from './cdp-driver.js';
+export {
+  TOOL_CAPABILITIES,
+  CapabilityError,
+  assertToolSupported,
+  missingCapabilities,
+  unsupportedTools
+} from './capabilities.js';
+export {
+  createDriver,
+  PLANNED_DRIVERS,
+  UnsupportedBrowserError
+} from './factory.js';
+export { BROWSER_KINDS, CAPABILITIES } from './types.js';
+export type {
+  BrowserDriver,
+  BrowserKind,
+  Capability,
+  ConnectExistingOptions,
+  DriverSession,
+  ViewportResizeParams
+} from './types.js';

package/src/browser/driver/types.ts

@@ -0,0 +1,156 @@
+import type { ConsoleBuffer } from '../../mcp/console-buffer.js';
+import type { ElementRefMap } from '../inspect/element-ref.js';
+import type { DialogQueue } from '../interaction/dialogs.js';
+import type { DownloadTracker } from '../interaction/downloads.js';
+import type { NetworkBuffer } from '../network/network-buffer.js';
+import type { TraceState } from '../performance/trace.js';
+import type { LaunchOptions, SessionInfo, TabInfo } from '../types.js';
+import type { ViewportConfig } from '../../viewport.js';
+import type { CheckParams, CheckResult } from '../../commands/check.js';
+import type { ClickParams, ClickResult } from '../../commands/click.js';
+import type { DialogParams, DialogResult } from '../../commands/dialog.js';
+import type {
+  EvaluateParams,
+  EvaluateResult
+} from '../../commands/evaluate.js';
+import type { FillParams, FillResult } from '../../commands/fill.js';
+import type { FindCommandResult, FindQuery } from '../../commands/find.js';
+import type { HoverParams, HoverResult } from '../../commands/hover.js';
+import type {
+  NavigateParams,
+  NavigateResult
+} from '../../commands/navigate.js';
+import type { NetworkParams, NetworkResult } from '../../commands/network.js';
+import type { PageInfoResult } from '../../commands/page_info.js';
+import type {
+  PerformanceParams,
+  PerformanceResult
+} from '../../commands/performance.js';
+import type {
+  PressKeyParams,
+  PressKeyResult
+} from '../../commands/press_key.js';
+import type {
+  ScreenshotParams,
+  ScreenshotResult
+} from '../../commands/screenshot.js';
+import type { ScrollParams, ScrollResult } from '../../commands/scroll.js';
+import type { SelectParams, SelectResult } from '../../commands/select.js';
+import type { SnapshotCommandResult } from '../../commands/snapshot.js';
+import type {
+  StylesCommandResult,
+  StylesParams
+} from '../../commands/styles.js';
+import type { NewTabResult } from '../../commands/tabs.js';
+import type { TypeParams, TypeResult } from '../../commands/type.js';
+import type { UploadParams, UploadResult } from '../../commands/upload.js';
+import type { WaitParams, WaitResult } from '../../commands/wait.js';
+
+/** Browsers Pilot knows about. Only `chrome` has a driver today. */
+export const BROWSER_KINDS = ['chrome', 'firefox', 'safari', 'webkit'] as const;
+export type BrowserKind = (typeof BROWSER_KINDS)[number];
+
+/**
+ * Features a driver may or may not provide. Each MCP tool declares the
+ * capabilities it needs (see capabilities.ts); a tool whose capabilities the
+ * active driver lacks fails with a CapabilityError before touching the browser.
+ */
+export const CAPABILITIES = [
+  'tabs',
+  'navigation',
+  'evaluate',
+  'input',
+  'screenshot',
+  'viewport',
+  'accessibilitySnapshot',
+  'styles',
+  'console',
+  'network',
+  'dialogs',
+  'uploads',
+  'downloads',
+  'performanceTrace',
+  'connectExisting'
+] as const;
+export type Capability = (typeof CAPABILITIES)[number];
+
+/**
+ * Per-session buffers shared between a driver and the MCP tools. The driver
+ * fills them from browser events; tools such as browser_console read them
+ * directly.
+ */
+export interface DriverSession {
+  consoleBuffer: ConsoleBuffer;
+  elementRefMap: ElementRefMap;
+  networkBuffer: NetworkBuffer;
+  dialogQueue: DialogQueue;
+  downloadTracker: DownloadTracker;
+  traceState: TraceState;
+}
+
+export interface ConnectExistingOptions {
+  host?: string;
+  port?: number;
+}
+
+export interface ViewportResizeParams {
+  width: number;
+  height: number;
+  deviceScaleFactor?: number;
+  mobile?: boolean;
+}
+
+/**
+ * Browser-agnostic surface the MCP tools call. Each implementation owns its
+ * protocol (CDP, WebDriver BiDi, ...) and must not leak protocol types here.
+ */
+export interface BrowserDriver {
+  readonly kind: BrowserKind;
+  readonly capabilities: ReadonlySet<Capability>;
+
+  // Lifecycle
+  launch(
+    opts?: LaunchOptions
+  ): Promise<{ headless: boolean; viewport: string }>;
+  connectExisting(opts: ConnectExistingOptions): Promise<{ tabs: TabInfo[] }>;
+  destroy(): Promise<void>;
+  isConnected(): boolean;
+  getSessionInfo(): SessionInfo;
+
+  // Tabs
+  listTabs(): Promise<TabInfo[]>;
+  newTab(url?: string): Promise<NewTabResult>;
+  closeTab(targetId: string): Promise<void>;
+  switchTab(targetId: string): Promise<void>;
+
+  // Page
+  navigate(params: NavigateParams): Promise<NavigateResult>;
+  pageInfo(): Promise<PageInfoResult>;
+  evaluate(params: EvaluateParams): Promise<EvaluateResult>;
+  wait(params: WaitParams): Promise<WaitResult>;
+  screenshot(params: ScreenshotParams): Promise<ScreenshotResult>;
+  resizeViewport(params: ViewportResizeParams): Promise<ViewportConfig>;
+
+  // Inspection
+  snapshot(): Promise<SnapshotCommandResult>;
+  find(query: FindQuery): Promise<FindCommandResult>;
+  styles(params: StylesParams): Promise<StylesCommandResult>;
+
+  // Input
+  click(params: ClickParams): Promise<ClickResult>;
+  type(params: TypeParams): Promise<TypeResult>;
+  fill(params: FillParams): Promise<FillResult>;
+  hover(params: HoverParams): Promise<HoverResult>;
+  pressKey(params: PressKeyParams): Promise<PressKeyResult>;
+  select(params: SelectParams): Promise<SelectResult>;
+  check(params: CheckParams): Promise<CheckResult>;
+  scroll(params: ScrollParams): Promise<ScrollResult>;
+
+  // Files and dialogs
+  dialog(params: DialogParams): Promise<DialogResult>;
+  upload(params: UploadParams): Promise<UploadResult>;
+
+  // Diagnostics
+  network(params: NetworkParams): Promise<NetworkResult>;
+  performance(params: PerformanceParams): Promise<PerformanceResult>;
+}