btcp-browser-agent 0.1.0

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

@@ -0,0 +1,41 @@
+/**
+ * eval command - Execute JavaScript in page context
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const evalCommand: CommandHandler = {
+  name: 'eval',
+  description: 'Execute JavaScript in the page context',
+  usage: 'eval <code>',
+  examples: [
+    'eval document.title',
+    'eval "window.scrollTo(0, 0)"',
+    'eval "document.querySelectorAll(\'a\').length"',
+  ],
+
+  async execute(client, args) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('JavaScript code required', 'eval <code>');
+    }
+
+    const script = args.join(' ');
+
+    const response = await client.execute({
+      id: `cmd_${Date.now()}`,
+      action: 'evaluate',
+      script,
+    } as any);
+
+    if (response.success) {
+      const result = (response as any).data?.result;
+      return {
+        success: true,
+        data: result !== undefined ? String(result) : '(undefined)',
+      };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

@@ -0,0 +1,30 @@
+/**
+ * fill command - Fill an input field
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const fillCommand: CommandHandler = {
+  name: 'fill',
+  description: 'Fill an input field (sets value directly)',
+  usage: 'fill <selector> <value>',
+  examples: ['fill @ref:1 "john@example.com"', 'fill #email test@test.com'],
+
+  async execute(client, args) {
+    if (args.length < 2) {
+      throw new InvalidArgumentsError('Selector and value required', 'fill <selector> <value>');
+    }
+
+    const selector = args[0];
+    const value = args.slice(1).join(' ');
+
+    const response = await client.fill(selector, value);
+
+    if (response.success) {
+      return { success: true, message: `Filled: ${selector}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * forward command - Go forward in browser history
+ */
+
+import type { CommandHandler } from '../types.js';
+
+export const forwardCommand: CommandHandler = {
+  name: 'forward',
+  description: 'Go forward in browser history',
+  usage: 'forward',
+  examples: ['forward'],
+
+  async execute(client) {
+    const response = await client.forward();
+
+    if (response.success) {
+      return { success: true, message: 'Navigated forward' };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

@@ -0,0 +1,34 @@
+/**
+ * goto command - Navigate to a URL
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const gotoCommand: CommandHandler = {
+  name: 'goto',
+  description: 'Navigate to a URL',
+  usage: 'goto <url>',
+  examples: ['goto https://example.com', 'goto github.com'],
+
+  async execute(client, args) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('URL required', 'goto <url>');
+    }
+
+    let url = args[0];
+
+    // Add https:// if no protocol specified
+    if (!url.match(/^https?:\/\//i)) {
+      url = `https://${url}`;
+    }
+
+    const response = await client.navigate(url);
+
+    if (response.success) {
+      return { success: true, message: `Navigated to ${url}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

@@ -0,0 +1,162 @@
+/**
+ * help command - Show help information
+ */
+
+import type { CommandHandler } from '../types.js';
+import { formatCommandHelp } from '../formatter.js';
+import { commands } from './index.js';
+import { commandCategories, findSimilarCommands } from '../suggestions.js';
+
+/**
+ * Format categorized help
+ */
+function formatCategorizedHelp(): string {
+  let output = 'BTCP Browser CLI - Available Commands\n';
+  output += '═'.repeat(40) + '\n\n';
+
+  for (const [, category] of Object.entries(commandCategories)) {
+    output += `▸ ${category.name}\n`;
+    output += `  ${category.description}\n\n`;
+
+    for (const cmdName of category.commands) {
+      const cmd = commands[cmdName];
+      if (cmd) {
+        const padding = ' '.repeat(Math.max(0, 12 - cmdName.length));
+        output += `    ${cmdName}${padding}${cmd.description}\n`;
+      }
+    }
+    output += '\n';
+  }
+
+  output += '─'.repeat(40) + '\n';
+  output += 'Tips:\n';
+  output += '  • Type "help <command>" for detailed usage\n';
+  output += '  • Type "help category <name>" for category commands\n';
+  output += '  • Use @ref:N selectors from snapshot output\n';
+  output += '  • Comments start with # in multi-line input\n';
+
+  return output;
+}
+
+/**
+ * Format category-specific help
+ */
+function formatCategoryHelp(categoryKey: string): string | null {
+  const category = commandCategories[categoryKey as keyof typeof commandCategories];
+  if (!category) return null;
+
+  let output = `${category.name}\n`;
+  output += '─'.repeat(30) + '\n';
+  output += `${category.description}\n\n`;
+  output += 'Commands:\n\n';
+
+  for (const cmdName of category.commands) {
+    const cmd = commands[cmdName];
+    if (cmd) {
+      output += `  ${cmd.usage}\n`;
+      output += `    ${cmd.description}\n`;
+      if (cmd.examples && cmd.examples.length > 0) {
+        output += `    Example: ${cmd.examples[0]}\n`;
+      }
+      output += '\n';
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Format quick reference
+ */
+function formatQuickRef(): string {
+  let output = 'Quick Reference\n';
+  output += '═'.repeat(40) + '\n\n';
+
+  output += 'Common Workflow:\n';
+  output += '  goto <url>        Navigate to page\n';
+  output += '  snapshot          See page elements\n';
+  output += '  click @ref:N      Click element\n';
+  output += '  type @ref:N "..." Type into input\n';
+  output += '  fill @ref:N "..." Fill input field\n\n';
+
+  output += 'Selectors:\n';
+  output += '  @ref:5            Element ref from snapshot\n';
+  output += '  #id               CSS ID selector\n';
+  output += '  .class            CSS class selector\n';
+  output += '  button            Tag name selector\n\n';
+
+  output += 'Multi-line:\n';
+  output += '  Commands can be separated by newlines\n';
+  output += '  Lines starting with # are comments\n';
+  output += '  Execution stops on first error\n';
+
+  return output;
+}
+
+export const helpCommand: CommandHandler = {
+  name: 'help',
+  description: 'Show help information',
+  usage: 'help [command|category <name>|quick]',
+  examples: [
+    'help',
+    'help goto',
+    'help category navigation',
+    'help quick',
+  ],
+
+  async execute(_client, args) {
+    if (args.length === 0) {
+      return { success: true, data: formatCategorizedHelp() };
+    }
+
+    const first = args[0].toLowerCase();
+
+    // Quick reference
+    if (first === 'quick' || first === 'ref') {
+      return { success: true, data: formatQuickRef() };
+    }
+
+    // Category help
+    if (first === 'category' || first === 'cat') {
+      if (args.length < 2) {
+        const categories = Object.keys(commandCategories).join(', ');
+        return {
+          success: true,
+          data: `Available categories: ${categories}\n\nUsage: help category <name>`,
+        };
+      }
+      const categoryHelp = formatCategoryHelp(args[1].toLowerCase());
+      if (categoryHelp) {
+        return { success: true, data: categoryHelp };
+      }
+      const categories = Object.keys(commandCategories).join(', ');
+      return {
+        success: false,
+        error: `Unknown category: ${args[1]}\n\nAvailable: ${categories}`,
+      };
+    }
+
+    // Command help
+    const cmdName = first;
+    const cmd = commands[cmdName];
+
+    if (cmd) {
+      return { success: true, data: formatCommandHelp(cmd) };
+    }
+
+    // Suggest similar commands
+    const similar = findSimilarCommands(cmdName);
+    if (similar.length > 0) {
+      const suggestions = similar.map((s) => `  ${s}`).join('\n');
+      return {
+        success: false,
+        error: `Unknown command: ${cmdName}\n\nDid you mean:\n${suggestions}\n\nType "help" for all commands`,
+      };
+    }
+
+    return {
+      success: false,
+      error: `Unknown command: ${cmdName}\n\nType "help" to see available commands`,
+    };
+  },
+};

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

@@ -0,0 +1,34 @@
+/**
+ * hover command - Hover over an element
+ */
+
+import type { CommandHandler, CommandClient } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const hoverCommand: CommandHandler = {
+  name: 'hover',
+  description: 'Hover over an element',
+  usage: 'hover <selector>',
+  examples: ['hover @ref:5', 'hover .menu-item'],
+
+  async execute(client, args) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('Selector required', 'hover <selector>');
+    }
+
+    const selector = args[0];
+
+    // Use execute for hover since it may not be in the simplified client interface
+    const response = await client.execute({
+      id: `cmd_${Date.now()}`,
+      action: 'hover',
+      selector,
+    } as any);
+
+    if (response.success) {
+      return { success: true, message: `Hovered: ${selector}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

@@ -0,0 +1,129 @@
+/**
+ * Command registry - exports all available commands
+ */
+
+import type { CommandHandler } from '../types.js';
+
+// Navigation
+import { gotoCommand } from './goto.js';
+import { backCommand } from './back.js';
+import { forwardCommand } from './forward.js';
+import { reloadCommand } from './reload.js';
+import { urlCommand } from './url.js';
+import { titleCommand } from './title.js';
+
+// Snapshot & Screenshot
+import { snapshotCommand } from './snapshot.js';
+import { screenshotCommand } from './screenshot.js';
+
+// DOM Interaction
+import { clickCommand } from './click.js';
+import { typeCommand } from './type.js';
+import { fillCommand } from './fill.js';
+import { clearCommand } from './clear.js';
+import { hoverCommand } from './hover.js';
+import { scrollCommand } from './scroll.js';
+import { pressCommand } from './press.js';
+import { focusCommand } from './focus.js';
+import { checkCommand } from './check.js';
+import { uncheckCommand } from './uncheck.js';
+import { selectCommand } from './select.js';
+
+// Tab Management
+import { tabsCommand } from './tabs.js';
+import { tabCommand } from './tab.js';
+import { newtabCommand } from './newtab.js';
+import { closetabCommand } from './closetab.js';
+
+// Utility
+import { waitCommand } from './wait.js';
+import { evalCommand } from './eval.js';
+import { textCommand } from './text.js';
+import { helpCommand } from './help.js';
+
+/**
+ * Command registry - map of command name to handler
+ */
+export const commands: Record<string, CommandHandler> = {
+  // Navigation
+  goto: gotoCommand,
+  back: backCommand,
+  forward: forwardCommand,
+  reload: reloadCommand,
+  url: urlCommand,
+  title: titleCommand,
+
+  // Snapshot & Screenshot
+  snapshot: snapshotCommand,
+  screenshot: screenshotCommand,
+
+  // DOM Interaction
+  click: clickCommand,
+  type: typeCommand,
+  fill: fillCommand,
+  clear: clearCommand,
+  hover: hoverCommand,
+  scroll: scrollCommand,
+  press: pressCommand,
+  focus: focusCommand,
+  check: checkCommand,
+  uncheck: uncheckCommand,
+  select: selectCommand,
+
+  // Tab Management
+  tabs: tabsCommand,
+  tab: tabCommand,
+  newtab: newtabCommand,
+  closetab: closetabCommand,
+
+  // Utility
+  wait: waitCommand,
+  eval: evalCommand,
+  text: textCommand,
+  help: helpCommand,
+};
+
+/**
+ * Get a command handler by name
+ */
+export function getCommand(name: string): CommandHandler | undefined {
+  return commands[name.toLowerCase()];
+}
+
+/**
+ * Get all command handlers
+ */
+export function getAllCommands(): CommandHandler[] {
+  return Object.values(commands);
+}
+
+// Re-export individual commands for direct imports
+export {
+  gotoCommand,
+  backCommand,
+  forwardCommand,
+  reloadCommand,
+  urlCommand,
+  titleCommand,
+  snapshotCommand,
+  screenshotCommand,
+  clickCommand,
+  typeCommand,
+  fillCommand,
+  clearCommand,
+  hoverCommand,
+  scrollCommand,
+  pressCommand,
+  focusCommand,
+  checkCommand,
+  uncheckCommand,
+  selectCommand,
+  tabsCommand,
+  tabCommand,
+  newtabCommand,
+  closetabCommand,
+  waitCommand,
+  evalCommand,
+  textCommand,
+  helpCommand,
+};

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

@@ -0,0 +1,35 @@
+/**
+ * newtab command - Open a new tab
+ */
+
+import type { CommandHandler } from '../types.js';
+import { getFlagBool } from '../parser.js';
+
+export const newtabCommand: CommandHandler = {
+  name: 'newtab',
+  description: 'Open a new tab',
+  usage: 'newtab [url] [--background]',
+  examples: ['newtab', 'newtab https://example.com', 'newtab github.com --background'],
+
+  async execute(client, args, flags) {
+    let url = args[0];
+
+    // Add https:// if URL provided without protocol
+    if (url && !url.match(/^https?:\/\//i)) {
+      url = `https://${url}`;
+    }
+
+    const background = getFlagBool(flags, 'background');
+
+    const result = await client.tabNew({
+      url,
+      active: !background,
+    });
+
+    return {
+      success: true,
+      message: `Opened new tab [${result.tabId}]${url ? `: ${url}` : ''}`,
+      data: result,
+    };
+  },
+};

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

@@ -0,0 +1,40 @@
+/**
+ * press command - Press a keyboard key
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+
+export const pressCommand: CommandHandler = {
+  name: 'press',
+  description: 'Press a keyboard key',
+  usage: 'press <key> [selector]',
+  examples: [
+    'press Enter',
+    'press Tab',
+    'press Escape',
+    'press Enter @ref:1',
+  ],
+
+  async execute(client, args) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('Key required', 'press <key> [selector]');
+    }
+
+    const key = args[0];
+    const selector = args[1];
+
+    const response = await client.execute({
+      id: `cmd_${Date.now()}`,
+      action: 'press',
+      key,
+      selector,
+    } as any);
+
+    if (response.success) {
+      return { success: true, message: `Pressed: ${key}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

@@ -0,0 +1,25 @@
+/**
+ * reload command - Reload the current page
+ */
+
+import type { CommandHandler } from '../types.js';
+import { getFlagBool } from '../parser.js';
+
+export const reloadCommand: CommandHandler = {
+  name: 'reload',
+  description: 'Reload the current page',
+  usage: 'reload [--hard]',
+  examples: ['reload', 'reload --hard'],
+
+  async execute(client, _args, flags) {
+    const bypassCache = getFlagBool(flags, 'hard');
+    const response = await client.reload({ bypassCache });
+
+    if (response.success) {
+      const msg = bypassCache ? 'Hard reloaded page' : 'Reloaded page';
+      return { success: true, message: msg };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

@@ -0,0 +1,27 @@
+/**
+ * screenshot command - Capture visible tab
+ */
+
+import type { CommandHandler } from '../types.js';
+import { getFlagString, getFlagNumber } from '../parser.js';
+import { formatScreenshot } from '../formatter.js';
+
+export const screenshotCommand: CommandHandler = {
+  name: 'screenshot',
+  description: 'Capture screenshot of visible tab',
+  usage: 'screenshot [--format png|jpeg] [--quality <0-100>]',
+  examples: ['screenshot', 'screenshot --format jpeg --quality 80'],
+
+  async execute(client, _args, flags) {
+    const formatFlag = getFlagString(flags, 'format');
+    const format = formatFlag === 'jpeg' ? 'jpeg' : 'png';
+    const quality = getFlagNumber(flags, 'quality');
+
+    const dataUrl = await client.screenshot({ format, quality });
+    return {
+      success: true,
+      message: formatScreenshot(dataUrl),
+      data: dataUrl,
+    };
+  },
+};

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

@@ -0,0 +1,64 @@
+/**
+ * scroll command - Scroll the page
+ */
+
+import type { CommandHandler } from '../types.js';
+import { getFlagNumber } from '../parser.js';
+
+export const scrollCommand: CommandHandler = {
+  name: 'scroll',
+  description: 'Scroll the page',
+  usage: 'scroll <direction> [amount] | scroll <selector>',
+  examples: [
+    'scroll down',
+    'scroll up 500',
+    'scroll down 200',
+    'scroll @ref:5',
+  ],
+
+  async execute(client, args, flags) {
+    if (args.length === 0) {
+      // Default to scroll down
+      const response = await client.execute({
+        id: `cmd_${Date.now()}`,
+        action: 'scroll',
+        direction: 'down',
+        amount: 300,
+      } as any);
+      return response.success
+        ? { success: true, message: 'Scrolled down' }
+        : { success: false, error: response.error };
+    }
+
+    const first = args[0].toLowerCase();
+
+    // Check if it's a direction
+    if (['up', 'down', 'left', 'right'].includes(first)) {
+      const direction = first as 'up' | 'down' | 'left' | 'right';
+      const amount = args[1] ? parseInt(args[1], 10) : 300;
+
+      const response = await client.execute({
+        id: `cmd_${Date.now()}`,
+        action: 'scroll',
+        direction,
+        amount: isNaN(amount) ? 300 : amount,
+      } as any);
+
+      return response.success
+        ? { success: true, message: `Scrolled ${direction}` }
+        : { success: false, error: response.error };
+    }
+
+    // It's a selector - scroll element into view
+    const selector = args[0];
+    const response = await client.execute({
+      id: `cmd_${Date.now()}`,
+      action: 'scrollIntoView',
+      selector,
+    } as any);
+
+    return response.success
+      ? { success: true, message: `Scrolled to: ${selector}` }
+      : { success: false, error: response.error };
+  },
+};