btcp-browser-agent 0.1.0

package/packages/cli/src/__tests__/parser.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Parser tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  parseCommand,
+  getFlagString,
+  getFlagNumber,
+  getFlagBool,
+} from '../parser.js';
+import { ParseError } from '../errors.js';
+
+describe('parseCommand', () => {
+  describe('basic parsing', () => {
+    it('parses a simple command', () => {
+      const result = parseCommand('goto');
+      expect(result.name).toBe('goto');
+      expect(result.args).toEqual([]);
+      expect(result.flags).toEqual({});
+    });
+
+    it('parses command with one argument', () => {
+      const result = parseCommand('goto https://example.com');
+      expect(result.name).toBe('goto');
+      expect(result.args).toEqual(['https://example.com']);
+    });
+
+    it('parses command with multiple arguments', () => {
+      const result = parseCommand('type @ref:1 hello world');
+      expect(result.name).toBe('type');
+      expect(result.args).toEqual(['@ref:1', 'hello', 'world']);
+    });
+
+    it('converts command name to lowercase', () => {
+      const result = parseCommand('GOTO https://example.com');
+      expect(result.name).toBe('goto');
+    });
+
+    it('preserves original input in raw field', () => {
+      const input = 'goto https://example.com';
+      const result = parseCommand(input);
+      expect(result.raw).toBe(input);
+    });
+
+    it('trims whitespace', () => {
+      const result = parseCommand('  goto https://example.com  ');
+      expect(result.name).toBe('goto');
+      expect(result.args).toEqual(['https://example.com']);
+    });
+  });
+
+  describe('quoted strings', () => {
+    it('parses double-quoted strings', () => {
+      const result = parseCommand('type @ref:1 "hello world"');
+      expect(result.args).toEqual(['@ref:1', 'hello world']);
+    });
+
+    it('parses single-quoted strings', () => {
+      const result = parseCommand("type @ref:1 'hello world'");
+      expect(result.args).toEqual(['@ref:1', 'hello world']);
+    });
+
+    it('handles empty quoted strings (parsed but filtered as empty token)', () => {
+      // Note: empty quoted strings result in empty tokens which are filtered
+      const result = parseCommand('fill @ref:1 ""');
+      expect(result.args).toEqual(['@ref:1']);
+    });
+
+    it('preserves spaces in quoted strings', () => {
+      const result = parseCommand('type @ref:1 "hello   world"');
+      expect(result.args).toEqual(['@ref:1', 'hello   world']);
+    });
+
+    it('handles quotes within different quotes', () => {
+      const result = parseCommand('type @ref:1 "it\'s working"');
+      expect(result.args).toEqual(['@ref:1', "it's working"]);
+    });
+
+    it('throws on unterminated double quote', () => {
+      expect(() => parseCommand('type @ref:1 "hello')).toThrow(ParseError);
+      expect(() => parseCommand('type @ref:1 "hello')).toThrow('Unterminated double quote');
+    });
+
+    it('throws on unterminated single quote', () => {
+      expect(() => parseCommand("type @ref:1 'hello")).toThrow(ParseError);
+      expect(() => parseCommand("type @ref:1 'hello")).toThrow('Unterminated single quote');
+    });
+  });
+
+  describe('escape characters', () => {
+    it('handles escaped quotes', () => {
+      const result = parseCommand('type @ref:1 "hello \\"world\\""');
+      expect(result.args).toEqual(['@ref:1', 'hello "world"']);
+    });
+
+    it('handles escaped backslash', () => {
+      const result = parseCommand('type @ref:1 "path\\\\file"');
+      expect(result.args).toEqual(['@ref:1', 'path\\file']);
+    });
+  });
+
+  describe('flags', () => {
+    it('parses long flag with value', () => {
+      const result = parseCommand('wait @ref:1 --state visible');
+      expect(result.flags).toEqual({ state: 'visible' });
+    });
+
+    it('parses long flag with equals syntax', () => {
+      const result = parseCommand('wait @ref:1 --state=visible');
+      expect(result.flags).toEqual({ state: 'visible' });
+    });
+
+    it('parses boolean long flag', () => {
+      const result = parseCommand('reload --hard');
+      expect(result.flags).toEqual({ hard: true });
+    });
+
+    it('parses short flag with value', () => {
+      const result = parseCommand('screenshot -f png');
+      expect(result.flags).toEqual({ f: 'png' });
+    });
+
+    it('parses boolean short flag', () => {
+      const result = parseCommand('reload -h');
+      expect(result.flags).toEqual({ h: true });
+    });
+
+    it('parses multiple flags', () => {
+      const result = parseCommand('screenshot --format png --quality 80');
+      expect(result.flags).toEqual({ format: 'png', quality: '80' });
+    });
+
+    it('separates args and flags correctly', () => {
+      const result = parseCommand('click @ref:1 --button right');
+      expect(result.args).toEqual(['@ref:1']);
+      expect(result.flags).toEqual({ button: 'right' });
+    });
+
+    it('handles flag value with equals sign', () => {
+      const result = parseCommand('eval --script=a=b');
+      expect(result.flags).toEqual({ script: 'a=b' });
+    });
+  });
+
+  describe('edge cases', () => {
+    it('throws on empty input', () => {
+      expect(() => parseCommand('')).toThrow(ParseError);
+      expect(() => parseCommand('')).toThrow('Empty command');
+    });
+
+    it('throws on whitespace-only input', () => {
+      expect(() => parseCommand('   ')).toThrow(ParseError);
+    });
+
+    it('handles tabs as whitespace', () => {
+      const result = parseCommand('goto\thttps://example.com');
+      expect(result.name).toBe('goto');
+      expect(result.args).toEqual(['https://example.com']);
+    });
+
+    it('handles URLs with special characters', () => {
+      const result = parseCommand('goto https://example.com/path?query=value&foo=bar');
+      expect(result.args).toEqual(['https://example.com/path?query=value&foo=bar']);
+    });
+
+    it('handles @ref selectors', () => {
+      const result = parseCommand('click @ref:123');
+      expect(result.args).toEqual(['@ref:123']);
+    });
+
+    it('handles CSS selectors', () => {
+      const result = parseCommand('click #submit-button');
+      expect(result.args).toEqual(['#submit-button']);
+    });
+
+    it('handles class selectors', () => {
+      const result = parseCommand('click .btn.primary');
+      expect(result.args).toEqual(['.btn.primary']);
+    });
+  });
+});
+
+describe('getFlagString', () => {
+  it('returns string value for string flag', () => {
+    const flags = { format: 'png' };
+    expect(getFlagString(flags, 'format')).toBe('png');
+  });
+
+  it('returns undefined for missing flag', () => {
+    const flags = {};
+    expect(getFlagString(flags, 'format')).toBeUndefined();
+  });
+
+  it('returns default for missing flag', () => {
+    const flags = {};
+    expect(getFlagString(flags, 'format', 'jpeg')).toBe('jpeg');
+  });
+
+  it('returns default for boolean flag', () => {
+    const flags = { format: true };
+    expect(getFlagString(flags, 'format', 'jpeg')).toBe('jpeg');
+  });
+});
+
+describe('getFlagNumber', () => {
+  it('returns number for numeric string flag', () => {
+    const flags = { quality: '80' };
+    expect(getFlagNumber(flags, 'quality')).toBe(80);
+  });
+
+  it('returns undefined for missing flag', () => {
+    const flags = {};
+    expect(getFlagNumber(flags, 'quality')).toBeUndefined();
+  });
+
+  it('returns default for missing flag', () => {
+    const flags = {};
+    expect(getFlagNumber(flags, 'quality', 100)).toBe(100);
+  });
+
+  it('returns default for non-numeric string', () => {
+    const flags = { quality: 'high' };
+    expect(getFlagNumber(flags, 'quality', 100)).toBe(100);
+  });
+
+  it('returns default for boolean flag', () => {
+    const flags = { quality: true };
+    expect(getFlagNumber(flags, 'quality', 100)).toBe(100);
+  });
+
+  it('handles zero correctly', () => {
+    const flags = { offset: '0' };
+    expect(getFlagNumber(flags, 'offset')).toBe(0);
+  });
+
+  it('handles negative numbers', () => {
+    const flags = { offset: '-10' };
+    expect(getFlagNumber(flags, 'offset')).toBe(-10);
+  });
+
+  it('handles floating point', () => {
+    const flags = { scale: '1.5' };
+    expect(getFlagNumber(flags, 'scale')).toBe(1.5);
+  });
+});
+
+describe('getFlagBool', () => {
+  it('returns true for boolean true flag', () => {
+    const flags = { hard: true };
+    expect(getFlagBool(flags, 'hard')).toBe(true);
+  });
+
+  it('returns false for boolean false flag', () => {
+    const flags = { hard: false };
+    expect(getFlagBool(flags, 'hard')).toBe(false);
+  });
+
+  it('returns false for missing flag by default', () => {
+    const flags = {};
+    expect(getFlagBool(flags, 'hard')).toBe(false);
+  });
+
+  it('returns default for missing flag', () => {
+    const flags = {};
+    expect(getFlagBool(flags, 'hard', true)).toBe(true);
+  });
+
+  it('returns true for string "true"', () => {
+    const flags = { hard: 'true' };
+    expect(getFlagBool(flags, 'hard')).toBe(true);
+  });
+
+  it('returns true for string "1"', () => {
+    const flags = { hard: '1' };
+    expect(getFlagBool(flags, 'hard')).toBe(true);
+  });
+
+  it('returns false for other strings', () => {
+    const flags = { hard: 'yes' };
+    expect(getFlagBool(flags, 'hard')).toBe(false);
+  });
+
+  it('is case insensitive for "true"', () => {
+    const flags = { hard: 'TRUE' };
+    expect(getFlagBool(flags, 'hard')).toBe(true);
+  });
+});

package/packages/cli/src/__tests__/suggestions.test.ts

@@ -0,0 +1,255 @@
+/**
+ * Suggestions tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  findSimilarCommands,
+  getContextualSuggestion,
+  commandCategories,
+  getCommandCategory,
+  getNextStepSuggestions,
+} from '../suggestions.js';
+
+describe('findSimilarCommands', () => {
+  describe('exact prefix matching', () => {
+    it('finds commands starting with input', () => {
+      const results = findSimilarCommands('go');
+      expect(results).toContain('goto');
+    });
+
+    it('finds commands starting with input (tabs)', () => {
+      const results = findSimilarCommands('tab');
+      expect(results).toContain('tabs');
+      expect(results).toContain('tab');
+    });
+
+    it('prioritizes prefix matches', () => {
+      const results = findSimilarCommands('scr');
+      expect(results[0]).toBe('scroll');
+    });
+  });
+
+  describe('typo correction', () => {
+    it('suggests click for clck', () => {
+      const results = findSimilarCommands('clck');
+      expect(results).toContain('click');
+    });
+
+    it('suggests goto for gto', () => {
+      const results = findSimilarCommands('gto');
+      expect(results).toContain('goto');
+    });
+
+    it('suggests snapshot for snapshto', () => {
+      const results = findSimilarCommands('snapshto');
+      expect(results).toContain('snapshot');
+    });
+
+    it('suggests type for typ', () => {
+      const results = findSimilarCommands('typ');
+      expect(results).toContain('type');
+    });
+
+    it('suggests fill for fil', () => {
+      const results = findSimilarCommands('fil');
+      expect(results).toContain('fill');
+    });
+
+    it('suggests reload for relod', () => {
+      const results = findSimilarCommands('relod');
+      expect(results).toContain('reload');
+    });
+  });
+
+  describe('substring matching', () => {
+    it('finds commands containing input', () => {
+      const results = findSimilarCommands('shot');
+      expect(results).toContain('screenshot');
+    });
+
+    it('finds check in commands', () => {
+      const results = findSimilarCommands('check');
+      expect(results).toContain('check');
+      expect(results).toContain('uncheck');
+    });
+  });
+
+  describe('limits', () => {
+    it('returns at most maxSuggestions results', () => {
+      const results = findSimilarCommands('t', 2);
+      expect(results.length).toBeLessThanOrEqual(2);
+    });
+
+    it('returns empty for completely unrelated input', () => {
+      const results = findSimilarCommands('xyzabc123');
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  describe('case insensitivity', () => {
+    it('matches regardless of case', () => {
+      const results = findSimilarCommands('GOTO');
+      expect(results).toContain('goto');
+    });
+
+    it('matches mixed case', () => {
+      const results = findSimilarCommands('GoTo');
+      expect(results).toContain('goto');
+    });
+  });
+});
+
+describe('getContextualSuggestion', () => {
+  describe('element not found', () => {
+    it('provides suggestion for "not found" error', () => {
+      const suggestion = getContextualSuggestion('click', 'Element not found', ['@ref:5']);
+      expect(suggestion).toContain('snapshot');
+      expect(suggestion).toContain('@ref:5');
+    });
+
+    it('provides suggestion for "no element" error', () => {
+      const suggestion = getContextualSuggestion('click', 'No element matches selector', ['#btn']);
+      expect(suggestion).toContain('snapshot');
+    });
+  });
+
+  describe('invalid selector', () => {
+    it('provides suggestion for selector errors', () => {
+      const suggestion = getContextualSuggestion('click', 'Invalid selector', ['>>>']);
+      expect(suggestion).toContain('@ref:5');
+      expect(suggestion).toContain('#id');
+    });
+  });
+
+  describe('navigation errors', () => {
+    it('provides suggestion for navigation failures', () => {
+      const suggestion = getContextualSuggestion('goto', 'Failed to navigate', ['example.com']);
+      expect(suggestion).toContain('https://');
+    });
+
+    it('provides suggestion for URL errors', () => {
+      // Note: 'invalid' pattern matches first, giving selector advice
+      // Use 'navigate' or 'url' pattern for navigation-specific advice
+      const suggestion = getContextualSuggestion('goto', 'Failed to navigate to URL', ['not-a-url']);
+      expect(suggestion).toContain('https://');
+    });
+  });
+
+  describe('timeout errors', () => {
+    it('provides suggestion for timeout', () => {
+      const suggestion = getContextualSuggestion('wait', 'Timeout waiting for element', ['@ref:5']);
+      expect(suggestion).toContain('wait');
+      expect(suggestion).toContain('@ref:5');
+    });
+  });
+
+  describe('permission errors', () => {
+    it('provides suggestion for permission denied', () => {
+      const suggestion = getContextualSuggestion('click', 'Permission denied', ['#btn']);
+      expect(suggestion).toContain('Cross-origin');
+    });
+
+    it('provides suggestion for blocked actions', () => {
+      const suggestion = getContextualSuggestion('type', 'Action blocked by security policy', ['#input']);
+      expect(suggestion).toContain('iframe');
+    });
+  });
+
+  describe('no suggestion', () => {
+    it('returns null for unknown errors', () => {
+      const suggestion = getContextualSuggestion('click', 'Some random error', ['@ref:1']);
+      expect(suggestion).toBeNull();
+    });
+  });
+});
+
+describe('commandCategories', () => {
+  it('has navigation category', () => {
+    expect(commandCategories.navigation).toBeDefined();
+    expect(commandCategories.navigation.commands).toContain('goto');
+    expect(commandCategories.navigation.commands).toContain('back');
+  });
+
+  it('has inspection category', () => {
+    expect(commandCategories.inspection).toBeDefined();
+    expect(commandCategories.inspection.commands).toContain('snapshot');
+    expect(commandCategories.inspection.commands).toContain('screenshot');
+  });
+
+  it('has interaction category', () => {
+    expect(commandCategories.interaction).toBeDefined();
+    expect(commandCategories.interaction.commands).toContain('click');
+    expect(commandCategories.interaction.commands).toContain('type');
+  });
+
+  it('has forms category', () => {
+    expect(commandCategories.forms).toBeDefined();
+    expect(commandCategories.forms.commands).toContain('check');
+    expect(commandCategories.forms.commands).toContain('select');
+  });
+
+  it('has tabs category', () => {
+    expect(commandCategories.tabs).toBeDefined();
+    expect(commandCategories.tabs.commands).toContain('tabs');
+    expect(commandCategories.tabs.commands).toContain('newtab');
+  });
+
+  it('has utility category', () => {
+    expect(commandCategories.utility).toBeDefined();
+    expect(commandCategories.utility.commands).toContain('wait');
+    expect(commandCategories.utility.commands).toContain('help');
+  });
+
+  it('each category has name and description', () => {
+    for (const category of Object.values(commandCategories)) {
+      expect(category.name).toBeDefined();
+      expect(category.description).toBeDefined();
+      expect(category.commands.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('getCommandCategory', () => {
+  it('returns correct category for navigation commands', () => {
+    expect(getCommandCategory('goto')).toBe('navigation');
+    expect(getCommandCategory('back')).toBe('navigation');
+    expect(getCommandCategory('reload')).toBe('navigation');
+  });
+
+  it('returns correct category for interaction commands', () => {
+    expect(getCommandCategory('click')).toBe('interaction');
+    expect(getCommandCategory('type')).toBe('interaction');
+  });
+
+  it('returns correct category for inspection commands', () => {
+    expect(getCommandCategory('snapshot')).toBe('inspection');
+    expect(getCommandCategory('screenshot')).toBe('inspection');
+  });
+
+  it('returns null for unknown commands', () => {
+    expect(getCommandCategory('unknown')).toBeNull();
+  });
+});
+
+describe('getNextStepSuggestions', () => {
+  it('suggests snapshot after navigation', () => {
+    const suggestions = getNextStepSuggestions('goto');
+    expect(suggestions).toContain('snapshot     # See page structure and get element refs');
+  });
+
+  it('suggests actions after snapshot', () => {
+    const suggestions = getNextStepSuggestions('snapshot');
+    expect(suggestions.some((s) => s.includes('click'))).toBe(true);
+  });
+
+  it('suggests snapshot after click', () => {
+    const suggestions = getNextStepSuggestions('click');
+    expect(suggestions.some((s) => s.includes('snapshot'))).toBe(true);
+  });
+
+  it('returns empty for unknown commands', () => {
+    const suggestions = getNextStepSuggestions('unknown');
+    expect(suggestions).toHaveLength(0);
+  });
+});

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

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

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

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

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * click command - Click an element
+ */
+
+import type { CommandHandler } from '../types.js';
+import { InvalidArgumentsError } from '../errors.js';
+import { getFlagString } from '../parser.js';
+
+export const clickCommand: CommandHandler = {
+  name: 'click',
+  description: 'Click an element',
+  usage: 'click <selector> [--button left|right|middle]',
+  examples: ['click @ref:5', 'click #submit', 'click @ref:3 --button right'],
+
+  async execute(client, args, flags) {
+    if (args.length === 0) {
+      throw new InvalidArgumentsError('Selector required', 'click <selector>');
+    }
+
+    const selector = args[0];
+    const buttonFlag = getFlagString(flags, 'button');
+    const button = buttonFlag as 'left' | 'right' | 'middle' | undefined;
+
+    const response = await client.click(selector, { button });
+
+    if (response.success) {
+      return { success: true, message: `Clicked: ${selector}` };
+    }
+
+    return { success: false, error: response.error };
+  },
+};

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

@@ -0,0 +1,31 @@
+/**
+ * closetab command - Close a tab
+ */
+
+import type { CommandHandler } from '../types.js';
+
+export const closetabCommand: CommandHandler = {
+  name: 'closetab',
+  description: 'Close a tab (current tab if no ID specified)',
+  usage: 'closetab [id]',
+  examples: ['closetab', 'closetab 123'],
+
+  async execute(client, args) {
+    const tabId = args[0] ? parseInt(args[0], 10) : undefined;
+
+    if (args[0] && isNaN(tabId!)) {
+      return { success: false, error: 'Invalid tab ID' };
+    }
+
+    const response = await client.tabClose(tabId);
+
+    if (response.success) {
+      return {
+        success: true,
+        message: tabId ? `Closed tab ${tabId}` : 'Closed current tab',
+      };
+    }
+
+    return { success: false, error: response.error };
+  },
+};