btcp-browser-agent 0.1.0

package/packages/cli/src/commands/select.ts

@@ -0,0 +1,35 @@
+/**
+ * select command - Select dropdown option
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const selectCommand: CommandHandler = {
+  name: 'select',
+  description: 'Select a dropdown option',
+  usage: 'select <selector> <value>',
+  examples: ['select @ref:5 "Option 1"', 'select #country US'],
+
+  async execute(client, args) {
+    if (args.length < 2) {
+      throw new InvalidArgumentsError('Selector and value required', 'select <selector> <value>');
+    }
+
+    const selector = args[0];
+    const value = args.slice(1).join(' ');
+
+    const response = await client.execute({
+      id: `cmd_${Date.now()}`,
+      action: 'select',
+      selector,
+      values: value,
+    } as any);
+
+    if (response.success) {
+      return { success: true, message: `Selected "${value}" in: ${selector}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

package/packages/cli/src/commands/snapshot.ts

@@ -0,0 +1,21 @@
+/**
+ * snapshot command - Get page accessibility tree
+ */
+
+import type { CommandHandler } from '../types.js';
+import { getFlagString, getFlagNumber } from '../parser.js';
+
+export const snapshotCommand: CommandHandler = {
+  name: 'snapshot',
+  description: 'Get page accessibility tree',
+  usage: 'snapshot [--selector <css>] [--depth <n>]',
+  examples: ['snapshot', 'snapshot --selector main', 'snapshot --depth 5'],
+
+  async execute(client, _args, flags) {
+    const selector = getFlagString(flags, 'selector');
+    const maxDepth = getFlagNumber(flags, 'depth');
+
+    const result = await client.snapshot({ selector, maxDepth });
+    return { success: true, data: result };
+  },
+};

package/packages/cli/src/commands/tab.ts

@@ -0,0 +1,32 @@
+/**
+ * tab command - Switch to a tab
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const tabCommand: CommandHandler = {
+  name: 'tab',
+  description: 'Switch to a tab by ID',
+  usage: 'tab <id>',
+  examples: ['tab 123'],
+
+  async execute(client, args) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('Tab ID required', 'tab <id>');
+    }
+
+    const tabId = parseInt(args[0], 10);
+    if (isNaN(tabId)) {
+      throw new InvalidArgumentsError('Invalid tab ID', 'tab <id>');
+    }
+
+    const response = await client.tabSwitch(tabId);
+
+    if (response.success) {
+      return { success: true, message: `Switched to tab ${tabId}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

package/packages/cli/src/commands/tabs.ts

@@ -0,0 +1,26 @@
+/**
+ * tabs command - List all tabs
+ */
+
+import type { CommandHandler } from '../types.js';
+
+export const tabsCommand: CommandHandler = {
+  name: 'tabs',
+  description: 'List all open tabs',
+  usage: 'tabs',
+  examples: ['tabs'],
+
+  async execute(client) {
+    const tabs = await client.tabList();
+
+    const formatted = tabs
+      .map((tab) => {
+        const marker = tab.active ? '*' : ' ';
+        const title = tab.title || '(untitled)';
+        return `${marker} [${tab.id}] ${title}\n    ${tab.url || ''}`;
+      })
+      .join('\n');
+
+    return { success: true, data: formatted || 'No tabs' };
+  },
+};

package/packages/cli/src/commands/text.ts

@@ -0,0 +1,27 @@
+/**
+ * text command - Get text content of an element
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const textCommand: CommandHandler = {
+  name: 'text',
+  description: 'Get text content of an element',
+  usage: 'text <selector>',
+  examples: ['text @ref:5', 'text #heading', 'text .message'],
+
+  async execute(client, args) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('Selector required', 'text <selector>');
+    }
+
+    const selector = args[0];
+    const text = await client.getText(selector);
+
+    return {
+      success: true,
+      data: text !== null ? text : '(element not found)',
+    };
+  },
+};

package/packages/cli/src/commands/title.ts

@@ -0,0 +1,17 @@
+/**
+ * title command - Get current page title
+ */
+
+import type { CommandHandler } from '../types.js';
+
+export const titleCommand: CommandHandler = {
+  name: 'title',
+  description: 'Get the current page title',
+  usage: 'title',
+  examples: ['title'],
+
+  async execute(client) {
+    const title = await client.getTitle();
+    return { success: true, data: title };
+  },
+};

package/packages/cli/src/commands/type.ts

@@ -0,0 +1,38 @@
+/**
+ * type command - Type text into an element
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+import { getFlagNumber, getFlagBool } from '../parser.js';
+
+export const typeCommand: CommandHandler = {
+  name: 'type',
+  description: 'Type text into an element (character by character)',
+  usage: 'type <selector> <text> [--delay <ms>] [--clear]',
+  examples: [
+    'type @ref:1 "hello world"',
+    'type #search hello',
+    'type @ref:2 "test" --delay 50',
+    'type @ref:3 "new text" --clear',
+  ],
+
+  async execute(client, args, flags) {
+    if (args.length < 2) {
+      throw new InvalidArgumentsError('Selector and text required', 'type <selector> <text>');
+    }
+
+    const selector = args[0];
+    const text = args.slice(1).join(' ');
+    const delay = getFlagNumber(flags, 'delay');
+    const clear = getFlagBool(flags, 'clear');
+
+    const response = await client.type(selector, text, { delay, clear });
+
+    if (response.success) {
+      return { success: true, message: `Typed "${text}" into: ${selector}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

package/packages/cli/src/commands/uncheck.ts

@@ -0,0 +1,33 @@
+/**
+ * uncheck command - Uncheck a checkbox
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const uncheckCommand: CommandHandler = {
+  name: 'uncheck',
+  description: 'Uncheck a checkbox',
+  usage: 'uncheck <selector>',
+  examples: ['uncheck @ref:5', 'uncheck #newsletter'],
+
+  async execute(client, args) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('Selector required', 'uncheck <selector>');
+    }
+
+    const selector = args[0];
+
+    const response = await client.execute({
+      id: `cmd_${Date.now()}`,
+      action: 'uncheck',
+      selector,
+    } as any);
+
+    if (response.success) {
+      return { success: true, message: `Unchecked: ${selector}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

package/packages/cli/src/commands/url.ts

@@ -0,0 +1,17 @@
+/**
+ * url command - Get current page URL
+ */
+
+import type { CommandHandler } from '../types.js';
+
+export const urlCommand: CommandHandler = {
+  name: 'url',
+  description: 'Get the current page URL',
+  usage: 'url',
+  examples: ['url'],
+
+  async execute(client) {
+    const url = await client.getUrl();
+    return { success: true, data: url };
+  },
+};

package/packages/cli/src/commands/wait.ts

@@ -0,0 +1,54 @@
+/**
+ * wait command - Wait for duration or element
+ */
+
+import type { CommandHandler } from '../types.js';
+import { getFlagString, getFlagNumber } from '../parser.js';
+
+export const waitCommand: CommandHandler = {
+  name: 'wait',
+  description: 'Wait for duration (ms) or element state',
+  usage: 'wait <ms> | wait <selector> [--state visible|hidden]',
+  examples: [
+    'wait 1000',
+    'wait @ref:5',
+    'wait @ref:5 --state visible',
+    'wait #loading --state hidden',
+  ],
+
+  async execute(client, args, flags) {
+    if (args.length === 0) {
+      // Default wait
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      return { success: true, message: 'Waited 1000ms' };
+    }
+
+    const first = args[0];
+
+    // Check if it's a number (duration)
+    const duration = parseInt(first, 10);
+    if (!isNaN(duration) && String(duration) === first) {
+      await new Promise((resolve) => setTimeout(resolve, duration));
+      return { success: true, message: `Waited ${duration}ms` };
+    }
+
+    // It's a selector - wait for element
+    const selector = first;
+    const state = getFlagString(flags, 'state') as 'visible' | 'hidden' | undefined;
+    const timeout = getFlagNumber(flags, 'timeout', 30000);
+
+    const response = await client.execute({
+      id: `cmd_${Date.now()}`,
+      action: 'wait',
+      selector,
+      state: state || 'visible',
+      timeout,
+    } as any);
+
+    if (response.success) {
+      return { success: true, message: `Element ready: ${selector}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

package/packages/cli/src/errors.ts

@@ -0,0 +1,164 @@
+/**
+ * @btcp/cli - Error classes with contextual feedback
+ */
+
+/**
+ * Base CLI error with optional suggestions
+ */
+export class CLIError extends Error {
+  /** Suggestions for fixing the error */
+  public suggestions?: string[];
+  /** Usage hint */
+  public usage?: string;
+  /** Related command */
+  public command?: string;
+
+  constructor(
+    message: string,
+    options?: {
+      suggestions?: string[];
+      usage?: string;
+      command?: string;
+    }
+  ) {
+    super(message);
+    this.name = 'CLIError';
+    this.suggestions = options?.suggestions;
+    this.usage = options?.usage;
+    this.command = options?.command;
+  }
+
+  /**
+   * Format error with suggestions for display
+   */
+  toFormattedString(): string {
+    let output = this.message;
+
+    if (this.usage) {
+      output += `\n\nUsage: ${this.usage}`;
+    }
+
+    if (this.suggestions && this.suggestions.length > 0) {
+      output += '\n\nSuggestions:';
+      for (const suggestion of this.suggestions) {
+        output += `\n  - ${suggestion}`;
+      }
+    }
+
+    return output;
+  }
+}
+
+/**
+ * Command not found error with similar command suggestions
+ */
+export class CommandNotFoundError extends CLIError {
+  constructor(
+    public readonly commandName: string,
+    similarCommands?: string[]
+  ) {
+    const suggestions = similarCommands?.length
+      ? similarCommands.map((cmd) => `Did you mean '${cmd}'?`)
+      : ['Type "help" to see available commands'];
+
+    super(`Unknown command: ${commandName}`, {
+      suggestions,
+      command: commandName,
+    });
+    this.name = 'CommandNotFoundError';
+  }
+}
+
+/**
+ * Invalid arguments error with usage hint
+ */
+export class InvalidArgumentsError extends CLIError {
+  constructor(
+    message: string,
+    usage?: string,
+    examples?: string[]
+  ) {
+    const suggestions = examples?.map((ex) => `Example: ${ex}`);
+    super(message, { usage, suggestions });
+    this.name = 'InvalidArgumentsError';
+  }
+}
+
+/**
+ * Parse error with syntax help
+ */
+export class ParseError extends CLIError {
+  constructor(message: string, hint?: string) {
+    const suggestions = hint ? [hint] : [
+      'Commands should be: <command> [args] [--flags]',
+      'Use quotes for text with spaces: type @ref:1 "hello world"',
+    ];
+    super(message, { suggestions });
+    this.name = 'ParseError';
+  }
+}
+
+/**
+ * Execution error with recovery suggestions
+ */
+export class ExecutionError extends CLIError {
+  constructor(
+    message: string,
+    options?: {
+      suggestions?: string[];
+      command?: string;
+    }
+  ) {
+    super(message, options);
+    this.name = 'ExecutionError';
+  }
+}
+
+/**
+ * Element not found error
+ */
+export class ElementNotFoundError extends CLIError {
+  constructor(selector: string) {
+    super(`Element not found: ${selector}`, {
+      suggestions: [
+        'Run "snapshot" to see available elements with @ref IDs',
+        `Wait for element: wait ${selector} --state visible`,
+        'Check if the element is inside an iframe',
+      ],
+    });
+    this.name = 'ElementNotFoundError';
+  }
+}
+
+/**
+ * Navigation error
+ */
+export class NavigationError extends CLIError {
+  constructor(url: string, reason?: string) {
+    super(`Navigation failed: ${reason || url}`, {
+      suggestions: [
+        'Ensure URL includes protocol (https://)',
+        'Check if the URL is accessible',
+        'Try: goto https://example.com',
+      ],
+    });
+    this.name = 'NavigationError';
+  }
+}
+
+/**
+ * Timeout error
+ */
+export class TimeoutError extends CLIError {
+  constructor(operation: string, selector?: string) {
+    const suggestions = [
+      'Increase wait time: wait 5000',
+      'Check if element exists: snapshot',
+    ];
+    if (selector) {
+      suggestions.push(`Wait for element: wait ${selector} --state visible`);
+    }
+    super(`Timeout: ${operation}`, { suggestions });
+    this.name = 'TimeoutError';
+  }
+}

package/packages/cli/src/executor.ts

@@ -0,0 +1,68 @@
+/**
+ * @btcp/cli - Command executor
+ *
+ * Executes parsed commands using the client.
+ */
+
+import type { ParsedCommand, CommandResult, CommandClient } from './types.js';
+import { getCommand } from './commands/index.js';
+import { CommandNotFoundError, ExecutionError, CLIError } from './errors.js';
+import { findSimilarCommands, getContextualSuggestion } from './suggestions.js';
+
+/**
+ * Execute a parsed command
+ */
+export async function executeCommand(
+  client: CommandClient,
+  command: ParsedCommand
+): Promise<CommandResult> {
+  const handler = getCommand(command.name);
+
+  if (!handler) {
+    // Find similar commands for suggestion
+    const similar = findSimilarCommands(command.name);
+    throw new CommandNotFoundError(command.name, similar);
+  }
+
+  try {
+    const result = await handler.execute(client, command.args, command.flags);
+
+    // Add contextual suggestions on error
+    if (!result.success && result.error) {
+      const suggestion = getContextualSuggestion(command.name, result.error, command.args);
+      if (suggestion) {
+        return {
+          ...result,
+          error: `${result.error}\n\n${suggestion}`,
+        };
+      }
+    }
+
+    return result;
+  } catch (error) {
+    if (error instanceof CLIError) {
+      throw error;
+    }
+
+    // Wrap unexpected errors with contextual suggestions
+    const message = error instanceof Error ? error.message : String(error);
+    const suggestion = getContextualSuggestion(command.name, message, command.args);
+
+    throw new ExecutionError(message, {
+      suggestions: suggestion ? [suggestion] : undefined,
+      command: command.name,
+    });
+  }
+}
+
+/**
+ * Execute a raw command string
+ */
+export async function executeCommandString(
+  client: CommandClient,
+  input: string,
+  parse: (input: string) => ParsedCommand
+): Promise<CommandResult> {
+  const command = parse(input);
+  return executeCommand(client, command);
+}