btcp-browser-agent 0.1.0 → 0.1.1

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

@@ -1,288 +0,0 @@
-/**
- * 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

@@ -1,255 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-/**
- * 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

@@ -1,31 +0,0 @@
-/**
- * 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 };
-  },
-};