btcp-browser-agent 0.1.0

package/packages/cli/src/formatter.ts

@@ -0,0 +1,215 @@
+/**
+ * @btcp/cli - Output formatter
+ *
+ * Formats command results for terminal display.
+ */
+
+import type { CommandResult, FormattedOutput } from './types.js';
+
+/**
+ * Format a command result for display
+ */
+export function formatResult(result: CommandResult): FormattedOutput {
+  if (result.success) {
+    if (result.message) {
+      return { type: 'success', content: `✓ ${result.message}` };
+    }
+    if (result.data !== undefined) {
+      return { type: 'data', content: formatData(result.data) };
+    }
+    return { type: 'success', content: '✓ Done' };
+  }
+
+  return {
+    type: 'error',
+    content: `✗ Error: ${result.error || 'Unknown error'}`,
+  };
+}
+
+/**
+ * Format data for display
+ */
+export function formatData(data: unknown): string {
+  if (data === null || data === undefined) {
+    return '';
+  }
+
+  if (typeof data === 'string') {
+    return data;
+  }
+
+  if (typeof data === 'number' || typeof data === 'boolean') {
+    return String(data);
+  }
+
+  if (Array.isArray(data)) {
+    return formatArray(data);
+  }
+
+  if (typeof data === 'object') {
+    return formatObject(data as Record<string, unknown>);
+  }
+
+  return String(data);
+}
+
+/**
+ * Format an array for display
+ */
+function formatArray(arr: unknown[]): string {
+  if (arr.length === 0) return '(empty)';
+
+  // Check if it's a simple array of primitives
+  if (arr.every((item) => typeof item !== 'object' || item === null)) {
+    return arr.map((item) => String(item)).join('\n');
+  }
+
+  // Complex array - format each item
+  return arr.map((item, i) => `[${i}] ${formatData(item)}`).join('\n');
+}
+
+/**
+ * Format an object for display
+ */
+function formatObject(obj: Record<string, unknown>): string {
+  const entries = Object.entries(obj);
+  if (entries.length === 0) return '{}';
+
+  // Check for specific known formats
+  if ('tabs' in obj && Array.isArray(obj.tabs)) {
+    // Tab list
+    return formatTabList(obj.tabs as TabInfo[]);
+  }
+
+  // Generic object formatting
+  return entries
+    .map(([key, value]) => {
+      const formattedValue = typeof value === 'object' ? JSON.stringify(value) : String(value);
+      return `${key}: ${formattedValue}`;
+    })
+    .join('\n');
+}
+
+interface TabInfo {
+  id: number;
+  url?: string;
+  title?: string;
+  active: boolean;
+  index: number;
+}
+
+/**
+ * Format tab list for display
+ */
+function formatTabList(tabs: TabInfo[]): string {
+  if (tabs.length === 0) return 'No tabs';
+
+  return tabs
+    .map((tab) => {
+      const active = tab.active ? '* ' : '  ';
+      const title = tab.title || '(untitled)';
+      const url = tab.url || '';
+      return `${active}[${tab.id}] ${title}\n     ${url}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Format help text
+ */
+export function formatHelp(commands: { name: string; description: string; usage: string }[]): string {
+  const maxNameLen = Math.max(...commands.map((c) => c.name.length));
+
+  return commands
+    .map((cmd) => {
+      const padding = ' '.repeat(maxNameLen - cmd.name.length + 2);
+      return `  ${cmd.name}${padding}${cmd.description}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Format command help with detailed information
+ */
+export function formatCommandHelp(command: {
+  name: string;
+  description: string;
+  usage: string;
+  examples?: string[];
+}): string {
+  let output = `${command.name}\n`;
+  output += '─'.repeat(30) + '\n\n';
+  output += `${command.description}\n\n`;
+  output += `Usage:\n  ${command.usage}\n`;
+
+  if (command.examples && command.examples.length > 0) {
+    output += '\nExamples:\n';
+    output += command.examples.map((ex) => `  ${ex}`).join('\n');
+  }
+
+  // Add selector help for commands that use selectors
+  const selectorCommands = ['click', 'type', 'fill', 'clear', 'hover', 'focus', 'check', 'uncheck', 'select', 'scroll', 'wait', 'text'];
+  if (selectorCommands.includes(command.name)) {
+    output += '\n\nSelectors:\n';
+    output += '  @ref:N    Element reference from snapshot\n';
+    output += '  #id       CSS ID selector\n';
+    output += '  .class    CSS class selector\n';
+    output += '  tag       HTML tag name';
+  }
+
+  return output;
+}
+
+/**
+ * Format screenshot as base64 data URL info
+ */
+export function formatScreenshot(dataUrl: string): string {
+  // Extract format and size from data URL
+  const match = dataUrl.match(/^data:image\/(\w+);base64,/);
+  if (match) {
+    const format = match[1];
+    const base64 = dataUrl.slice(match[0].length);
+    const sizeBytes = Math.ceil((base64.length * 3) / 4);
+    const sizeKb = (sizeBytes / 1024).toFixed(1);
+    return `Screenshot captured (${format}, ${sizeKb} KB)`;
+  }
+  return 'Screenshot captured';
+}
+
+/**
+ * Format error with suggestions
+ */
+export function formatErrorWithSuggestions(
+  error: string,
+  suggestions?: string[]
+): string {
+  let output = `✗ Error: ${error}`;
+
+  if (suggestions && suggestions.length > 0) {
+    output += '\n\nSuggestions:';
+    for (const suggestion of suggestions) {
+      output += `\n  • ${suggestion}`;
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Format success message with next steps
+ */
+export function formatSuccessWithNextSteps(
+  message: string,
+  nextSteps?: string[]
+): string {
+  let output = `✓ ${message}`;
+
+  if (nextSteps && nextSteps.length > 0) {
+    output += '\n\nNext steps:';
+    for (const step of nextSteps) {
+      output += `\n  ${step}`;
+    }
+  }
+
+  return output;
+}

package/packages/cli/src/index.ts

@@ -0,0 +1,257 @@
+/**
+ * @btcp/cli
+ *
+ * Browser-based CLI for browser automation.
+ * Commands are sent directly from Chrome extension.
+ *
+ * @example Single command:
+ * ```typescript
+ * import { createCLI } from '@btcp/cli';
+ * import { createClient } from '@btcp/extension';
+ *
+ * const client = createClient();
+ * const cli = createCLI(client);
+ *
+ * await cli.execute('goto https://example.com');
+ * await cli.execute('snapshot');
+ * await cli.execute('click @ref:1');
+ * ```
+ *
+ * @example Multiple commands (split by \n):
+ * ```typescript
+ * // Execute multiple commands - stops on first error
+ * await cli.execute(`
+ *   goto https://example.com
+ *   snapshot
+ *   click @ref:1
+ *   fill @ref:2 "hello"
+ * `);
+ *
+ * // Or use executeAll for detailed results
+ * const batch = await cli.executeAll(`
+ *   goto https://example.com
+ *   snapshot
+ *   click @ref:1
+ * `);
+ * console.log(batch.allSucceeded, batch.results);
+ *
+ * // Continue on error
+ * const batch2 = await cli.executeAll(commands, { continueOnError: true });
+ * ```
+ *
+ * @example With terminal UI:
+ * ```typescript
+ * import { createCLI, Terminal } from '@btcp/cli';
+ * import { createClient } from '@btcp/extension';
+ *
+ * const client = createClient();
+ * const cli = createCLI(client);
+ *
+ * const terminal = new Terminal(document.getElementById('terminal')!, {
+ *   onExecute: (input) => cli.execute(input),
+ * });
+ * ```
+ */
+
+import type { CLI, CommandClient, CommandResult, CommandHandler, BatchResult } from './types.js';
+import { parseCommand } from './parser.js';
+import { executeCommand } from './executor.js';
+import { formatResult, formatHelp, formatCommandHelp } from './formatter.js';
+import { getAllCommands, getCommand } from './commands/index.js';
+import { CLIError } from './errors.js';
+
+// Re-export types
+export type {
+  CLI,
+  CommandClient,
+  CommandResult,
+  CommandHandler,
+  BatchResult,
+  ParsedCommand,
+  FormattedOutput,
+  HistoryEntry,
+  TerminalConfig,
+} from './types.js';
+
+// Re-export utilities
+export { parseCommand, getFlagString, getFlagNumber, getFlagBool } from './parser.js';
+export { executeCommand } from './executor.js';
+export {
+  formatResult,
+  formatHelp,
+  formatCommandHelp,
+  formatData,
+  formatScreenshot,
+  formatErrorWithSuggestions,
+  formatSuccessWithNextSteps,
+} from './formatter.js';
+export { commands, getCommand, getAllCommands } from './commands/index.js';
+export {
+  CLIError,
+  CommandNotFoundError,
+  InvalidArgumentsError,
+  ParseError,
+  ExecutionError,
+  ElementNotFoundError,
+  NavigationError,
+  TimeoutError,
+} from './errors.js';
+export {
+  findSimilarCommands,
+  getContextualSuggestion,
+  getNextStepSuggestions,
+  commandCategories,
+  getCommandCategory,
+  workflowSuggestions,
+} from './suggestions.js';
+
+/**
+ * Execute a single command line
+ */
+async function executeSingle(client: CommandClient, line: string): Promise<CommandResult> {
+  const trimmed = line.trim();
+
+  if (!trimmed || trimmed.startsWith('#')) {
+    // Empty line or comment
+    return { success: true, message: '' };
+  }
+
+  try {
+    const command = parseCommand(trimmed);
+    return await executeCommand(client, command);
+  } catch (error) {
+    if (error instanceof CLIError) {
+      // Use formatted error with suggestions
+      return {
+        success: false,
+        error: error.toFormattedString(),
+      };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { success: false, error: message };
+  }
+}
+
+/**
+ * Create a CLI instance
+ */
+export function createCLI(client: CommandClient): CLI {
+  return {
+    async execute(input: string): Promise<CommandResult> {
+      const trimmed = input.trim();
+
+      if (!trimmed) {
+        return { success: true, message: '' };
+      }
+
+      // Check if input contains multiple commands (split by \n)
+      const lines = trimmed.split('\n').filter((line) => {
+        const l = line.trim();
+        return l && !l.startsWith('#');
+      });
+
+      if (lines.length === 0) {
+        return { success: true, message: '' };
+      }
+
+      // Single command - execute directly
+      if (lines.length === 1) {
+        return executeSingle(client, lines[0]);
+      }
+
+      // Multiple commands - execute sequentially, stop on first error
+      const results: CommandResult[] = [];
+      for (const line of lines) {
+        const result = await executeSingle(client, line);
+        results.push(result);
+
+        if (!result.success) {
+          // Return aggregated result on failure
+          return {
+            success: false,
+            error: `Command failed at line ${results.length}: ${result.error}`,
+            data: { results, failedAt: results.length - 1 },
+          };
+        }
+      }
+
+      // All commands succeeded - return last result with summary
+      const lastResult = results[results.length - 1];
+      return {
+        success: true,
+        message: lastResult.message || `Executed ${results.length} commands`,
+        data: lastResult.data ?? { results },
+      };
+    },
+
+    async executeAll(
+      input: string,
+      options?: { continueOnError?: boolean }
+    ): Promise<BatchResult> {
+      const trimmed = input.trim();
+      const continueOnError = options?.continueOnError ?? false;
+
+      if (!trimmed) {
+        return {
+          results: [],
+          allSucceeded: true,
+          firstFailedIndex: -1,
+          executed: 0,
+        };
+      }
+
+      // Split by newlines, filter empty lines and comments
+      const lines = trimmed.split('\n').filter((line) => {
+        const l = line.trim();
+        return l && !l.startsWith('#');
+      });
+
+      const results: CommandResult[] = [];
+      let firstFailedIndex = -1;
+
+      for (let i = 0; i < lines.length; i++) {
+        const result = await executeSingle(client, lines[i]);
+        results.push(result);
+
+        if (!result.success && firstFailedIndex === -1) {
+          firstFailedIndex = i;
+          if (!continueOnError) {
+            break;
+          }
+        }
+      }
+
+      return {
+        results,
+        allSucceeded: firstFailedIndex === -1,
+        firstFailedIndex,
+        executed: results.length,
+      };
+    },
+
+    getCommands(): CommandHandler[] {
+      return getAllCommands();
+    },
+
+    getHelp(commandName?: string): string {
+      if (commandName) {
+        const cmd = getCommand(commandName);
+        if (!cmd) {
+          return `Unknown command: ${commandName}`;
+        }
+        return formatCommandHelp(cmd);
+      }
+
+      const commandList = getAllCommands().map((cmd) => ({
+        name: cmd.name,
+        description: cmd.description,
+        usage: cmd.usage,
+      }));
+
+      return `BTCP Browser CLI - Available Commands\n\n${formatHelp(commandList)}\n\nType "help <command>" for more info`;
+    },
+  };
+}
+
+// Re-export terminal (will be created next)
+export { Terminal, type TerminalOptions } from './terminal/index.js';

package/packages/cli/src/parser.ts

@@ -0,0 +1,195 @@
+/**
+ * @btcp/cli - Command parser
+ *
+ * Parses CLI input strings into structured commands.
+ */
+
+import type { ParsedCommand } from './types.js';
+import { ParseError } from './errors.js';
+
+/**
+ * Parse a CLI input string into a structured command
+ *
+ * @example
+ * parseCommand('goto https://example.com')
+ * // { name: 'goto', args: ['https://example.com'], flags: {}, raw: '...' }
+ *
+ * @example
+ * parseCommand('click @ref:5 --wait 1000')
+ * // { name: 'click', args: ['@ref:5'], flags: { wait: '1000' }, raw: '...' }
+ *
+ * @example
+ * parseCommand('type @ref:1 "hello world"')
+ * // { name: 'type', args: ['@ref:1', 'hello world'], flags: {}, raw: '...' }
+ */
+export function parseCommand(input: string): ParsedCommand {
+  const raw = input;
+  const trimmed = input.trim();
+
+  if (!trimmed) {
+    throw new ParseError('Empty command');
+  }
+
+  const tokens = tokenize(trimmed);
+
+  if (tokens.length === 0) {
+    throw new ParseError('Empty command');
+  }
+
+  const name = tokens[0].toLowerCase();
+  const { args, flags } = parseArgs(tokens.slice(1));
+
+  return { name, args, flags, raw };
+}
+
+/**
+ * Tokenize input string, handling quoted strings
+ */
+function tokenize(input: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let inQuote: string | null = null;
+  let escapeNext = false;
+
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+
+    if (escapeNext) {
+      current += char;
+      escapeNext = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      escapeNext = true;
+      continue;
+    }
+
+    if (inQuote) {
+      if (char === inQuote) {
+        // End of quoted string
+        inQuote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      // Start of quoted string
+      inQuote = char;
+      continue;
+    }
+
+    if (char === ' ' || char === '\t') {
+      // Whitespace - end current token
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  // Handle unterminated quote
+  if (inQuote) {
+    throw new ParseError(`Unterminated ${inQuote === '"' ? 'double' : 'single'} quote`);
+  }
+
+  // Add final token
+  if (current) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+/**
+ * Parse tokens into args and flags
+ */
+function parseArgs(tokens: string[]): { args: string[]; flags: Record<string, string | boolean> } {
+  const args: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    if (token.startsWith('--')) {
+      // Long flag
+      const flagContent = token.slice(2);
+
+      if (flagContent.includes('=')) {
+        // --flag=value format
+        const [key, ...valueParts] = flagContent.split('=');
+        flags[key] = valueParts.join('=');
+      } else if (i + 1 < tokens.length && !tokens[i + 1].startsWith('-')) {
+        // --flag value format
+        flags[flagContent] = tokens[++i];
+      } else {
+        // Boolean flag
+        flags[flagContent] = true;
+      }
+    } else if (token.startsWith('-') && token.length === 2) {
+      // Short flag (e.g., -v)
+      const flagChar = token[1];
+
+      if (i + 1 < tokens.length && !tokens[i + 1].startsWith('-')) {
+        // -f value format
+        flags[flagChar] = tokens[++i];
+      } else {
+        // Boolean flag
+        flags[flagChar] = true;
+      }
+    } else {
+      // Positional argument
+      args.push(token);
+    }
+  }
+
+  return { args, flags };
+}
+
+/**
+ * Get flag value as string
+ */
+export function getFlagString(
+  flags: Record<string, string | boolean>,
+  name: string,
+  defaultValue?: string
+): string | undefined {
+  const value = flags[name];
+  if (value === undefined) return defaultValue;
+  if (typeof value === 'boolean') return defaultValue;
+  return value;
+}
+
+/**
+ * Get flag value as number
+ */
+export function getFlagNumber(
+  flags: Record<string, string | boolean>,
+  name: string,
+  defaultValue?: number
+): number | undefined {
+  const value = flags[name];
+  if (value === undefined) return defaultValue;
+  if (typeof value === 'boolean') return defaultValue;
+  const num = Number(value);
+  return isNaN(num) ? defaultValue : num;
+}
+
+/**
+ * Get flag value as boolean
+ */
+export function getFlagBool(
+  flags: Record<string, string | boolean>,
+  name: string,
+  defaultValue = false
+): boolean {
+  const value = flags[name];
+  if (value === undefined) return defaultValue;
+  if (typeof value === 'boolean') return value;
+  return value.toLowerCase() === 'true' || value === '1';
+}