explorbot 0.0.1 → 0.0.5

package/src/commands/index.ts

@@ -0,0 +1,69 @@
+import type { ExplorBot } from '../explorbot.js';
+import type { BaseCommand } from './base-command.js';
+import { CleanCommand } from './clean-command.js';
+import { DebugCommand } from './debug-command.js';
+import { ContextAriaCommand } from './context-aria-command.js';
+import { ContextCommand } from './context-command.js';
+import { ContextDataCommand } from './context-data-command.js';
+import { ContextExperienceCommand } from './context-experience-command.js';
+import { ContextHtmlCommand } from './context-html-command.js';
+import { ContextKnowledgeCommand } from './context-knowledge-command.js';
+import { DrillCommand } from './drill-command.js';
+import { ExitCommand } from './exit-command.js';
+import { ExploreCommand } from './explore-command.js';
+import { FreesailCommand } from './freesail-command.js';
+import { HelpCommand } from './help-command.js';
+import { AddRuleCommand } from './add-rule-command.js';
+import { LearnCommand } from './learn-command.js';
+import { KnowsCommand } from './knows-command.js';
+import { NavigateCommand } from './navigate-command.js';
+import { PathCommand } from './path-command.js';
+import { PlanClearCommand } from './plan-clear-command.js';
+import { PlanCommand } from './plan-command.js';
+import { PlanEditCommand } from './plan-edit-command.js';
+import { PlanLoadCommand } from './plan-load-command.js';
+import { PlanReloadCommand } from './plan-reload-command.js';
+import { PlanSaveCommand } from './plan-save-command.js';
+import { ResearchCommand } from './research-command.js';
+import { StartCommand } from './start-command.js';
+import { StatusCommand } from './status-command.tsx';
+import { TestCommand } from './test-command.js';
+
+export { BaseCommand } from './base-command.js';
+
+type CommandClass = new (explorBot: ExplorBot) => BaseCommand;
+
+const commandClasses: CommandClass[] = [
+  HelpCommand,
+  StartCommand,
+  ExploreCommand,
+  FreesailCommand,
+  DrillCommand,
+  CleanCommand,
+  ResearchCommand,
+  PlanCommand,
+  PlanSaveCommand,
+  PlanLoadCommand,
+  PlanReloadCommand,
+  PlanClearCommand,
+  PlanEditCommand,
+  NavigateCommand,
+  PathCommand,
+  LearnCommand,
+  KnowsCommand,
+  AddRuleCommand,
+  ContextCommand,
+  ContextAriaCommand,
+  ContextHtmlCommand,
+  ContextKnowledgeCommand,
+  ContextExperienceCommand,
+  ContextDataCommand,
+  TestCommand,
+  StatusCommand,
+  DebugCommand,
+  ExitCommand,
+];
+
+export function createCommands(explorBot: ExplorBot): BaseCommand[] {
+  return commandClasses.map((Cmd) => new Cmd(explorBot));
+}

package/src/commands/init-command.ts

@@ -0,0 +1,128 @@
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { log, tag } from '../utils/logger.js';
+import dedent from 'dedent';
+import { getCliName } from '../utils/cli-name.ts';
+
+const DEFAULT_CONFIG_TEMPLATE = `import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+// import { '<your provider here>' } from '<your provider package here>';
+
+// Vercel AI SDK is used to connect to AI providers.
+// Bring your own provider or use OpenRouter (one API key, many providers).
+// https://github.com/testomatio/explorbot/blob/main/docs/providers.md
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+const config = {
+  web: {
+    // use application host without path prefix (e.g., http://localhost:3000)
+    url: 'http://<your-app-host-here>',
+  },
+
+  ai: {
+    // fast model with tool calling capabilities
+    model: openrouter('<your base model here>'),
+    // vision model for screenshot analysis
+    visionModel: openrouter('<your vision model here>'),
+    // agentic model for decision making
+    agenticModel: openrouter('<your agentic model here>'),
+  },
+};
+
+export default config;
+`;
+
+const DEFAULT_ENV_TEMPLATE = dedent`
+# AI provider API keys
+OPENROUTER_API_KEY=
+
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GROQ_API_KEY=
+
+# Langfuse Tracing
+LANGFUSE_SECRET_KEY=
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_BASE_URL=
+
+# Testomat.io API key to publish run results
+TESTOMATIO=
+`;
+
+export function runInitCommand(options: InitCommandOptions): void {
+  const configPath = options.configPath ?? './explorbot.config.js';
+  const force = options.force ?? false;
+  const customPath = options.path;
+  const originalCwd = process.cwd();
+
+  if (customPath) {
+    const dir = resolve(customPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      log(`Created directory: ${dir}`);
+    }
+    process.chdir(dir);
+    log(`Working in directory: ${dir}`);
+  }
+
+  try {
+    let outPath = resolve(configPath);
+    if (existsSync(outPath) && statSync(outPath).isDirectory()) {
+      outPath = join(outPath, 'explorbot.config.js');
+    } else if (!extname(outPath)) {
+      outPath = join(outPath, 'explorbot.config.js');
+    }
+
+    const dir = dirname(outPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      log(`Created directory: ${dir}`);
+    }
+
+    if (existsSync(outPath) && !force) {
+      log(`Config file already exists: ${outPath}`);
+      log('Use --force to overwrite existing file');
+      process.exit(1);
+    }
+
+    writeFileSync(outPath, DEFAULT_CONFIG_TEMPLATE, 'utf8');
+    log(`Created config file: ${outPath}`);
+
+    const envPath = resolve(process.cwd(), '.env');
+    if (!existsSync(envPath)) {
+      writeFileSync(envPath, `${DEFAULT_ENV_TEMPLATE}\n`, 'utf8');
+      log(`Created env file: ${envPath}`);
+    } else {
+      log(`Env file already exists: ${envPath}`);
+    }
+
+    log('');
+    log('Next steps:');
+    log('1. Configure AI provider in .env');
+    log('2. Set AI models config file');
+    log('3. Set web application URL in the config file');
+    log('4. Add initial knowledge (how to authorize to the application, etc.)');
+    tag('substep').log(`${getCliName()} learn * 'to aurhorize use these credentials: admin@example.com / secret123'`);
+    log('5. Launch application on a relative URL');
+    tag('substep').log(`${getCliName()} start /dashboard`);
+
+    if (!existsSync('./output')) {
+      mkdirSync('./output', { recursive: true });
+      log('Created directory: ./output');
+    }
+  } catch (error) {
+    log('Failed to create config file:', error);
+    process.exit(1);
+  } finally {
+    if (process.cwd() !== originalCwd) {
+      process.chdir(originalCwd);
+    }
+  }
+}
+
+type InitCommandOptions = {
+  configPath?: string;
+  force?: boolean;
+  path?: string;
+};

package/src/commands/knows-command.ts

@@ -0,0 +1,68 @@
+import { log, tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export function formatKnowledgeList(knowledge: Array<{ url: string; firstLine: string }>, limit = 0): string {
+  const lines: string[] = [];
+  const display = limit > 0 ? knowledge.slice(0, limit) : knowledge;
+
+  for (const entry of display) {
+    const preview = entry.firstLine ? ` - ${entry.firstLine}` : '';
+    lines.push(`* \`${entry.url}\` ${preview}`);
+  }
+
+  if (limit > 0 && knowledge.length > limit) {
+    lines.push(`... and ${knowledge.length - limit} more`);
+  }
+
+  return lines.join('\n');
+}
+
+export class KnowsCommand extends BaseCommand {
+  name = 'knows';
+  description = 'List all knowledge URLs or show matching knowledge for a URL';
+
+  async execute(args: string, limit = 0): Promise<void> {
+    const url = args.trim();
+    const tracker = this.explorBot.getKnowledgeTracker();
+
+    if (!url) {
+      const allKnowledge = tracker.listAllKnowledge();
+
+      if (allKnowledge.length === 0) {
+        log('No knowledge files found. Use /learn to add knowledge about your application.');
+        return;
+      }
+
+      let output = `Found ${allKnowledge.length} knowledge entries:\n\n${formatKnowledgeList(allKnowledge, limit)}`;
+
+      const currentState = this.explorBot.getCurrentState();
+      if (currentState?.url) {
+        const currentMatching = tracker.getMatchingKnowledge(currentState.url);
+        if (currentMatching.length > 0) {
+          output += `\n\n**Knowledge for current page** (${currentState.url}):`;
+          for (const k of currentMatching) {
+            output += `\n\n\`${k.url}\`:\n${k.content.trim()}`;
+          }
+        }
+      }
+
+      output += '\n\nUse /learn to add knowledge';
+      tag('multiline').log(output);
+      return;
+    }
+
+    const matching = tracker.getMatchingKnowledge(url);
+
+    if (matching.length === 0) {
+      log(`No knowledge found for: ${url}`);
+      return;
+    }
+
+    const knowledgeList = matching.map((k) => {
+      const firstLine = k.content.trim().split('\n')[0] || '';
+      return { url: k.url, firstLine };
+    });
+
+    tag('multiline').log(`Found ${matching.length} matching knowledge entries for: ${url}\n\n${formatKnowledgeList(knowledgeList)}`);
+  }
+}

package/src/commands/learn-command.ts

@@ -0,0 +1,44 @@
+import { render } from 'ink';
+import React from 'react';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class LearnCommand extends BaseCommand {
+  name = 'learn';
+  description = 'Store knowledge for current page';
+  suggestions = ['/knows - to view all knowledge'];
+
+  async execute(args: string): Promise<void> {
+    const note = args.trim();
+
+    if (!note) {
+      const AddKnowledge = (await import('../components/AddKnowledge.js')).default;
+      const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+      const initialUrl = state?.url || '';
+
+      const { unmount } = render(
+        React.createElement(AddKnowledge, {
+          initialUrl,
+          onComplete: () => unmount(),
+          onCancel: () => unmount(),
+        }),
+        {
+          exitOnCtrlC: false,
+          patchConsole: false,
+        }
+      );
+      return;
+    }
+
+    const explorer = this.explorBot.getExplorer();
+    const state = explorer.getStateManager().getCurrentState();
+
+    if (!state) {
+      throw new Error('No active page to attach knowledge');
+    }
+
+    const targetUrl = state.url || state.fullUrl || '/';
+    explorer.getKnowledgeTracker().addKnowledge(targetUrl, note);
+    tag('success').log('Knowledge saved for current page');
+  }
+}

package/src/commands/navigate-command.ts

@@ -0,0 +1,18 @@
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class NavigateCommand extends BaseCommand {
+  name = 'navigate';
+  description = 'Navigate to URI or state using AI';
+  suggestions = ['/research - to analyze current page', '/plan <feature> - to plan testing'];
+
+  async execute(args: string): Promise<void> {
+    const destination = args.trim();
+    if (!destination) {
+      throw new Error('Navigate command requires a target URI or state');
+    }
+
+    await this.explorBot.agentNavigator().visit(destination);
+    tag('success').log(`Navigation requested: ${destination}`);
+  }
+}

package/src/commands/path-command.ts

@@ -0,0 +1,83 @@
+import type { Link } from '../state-manager.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+interface VisitedPage {
+  title: string;
+  url: string;
+  links: Link[];
+}
+
+export class PathCommand extends BaseCommand {
+  name = 'path';
+  description = 'Display ASCII graph of navigation paths during the session';
+  options = [{ flags: '--links', description: 'Show outgoing links from each page' }];
+
+  async execute(args: string): Promise<void> {
+    const showLinks = args.includes('--links');
+    const stateManager = this.explorBot.getExplorer().getStateManager();
+    const history = stateManager.getStateHistory();
+
+    if (history.length === 0) {
+      tag('multiline').log('No navigation history yet.');
+      return;
+    }
+
+    const visited: VisitedPage[] = [];
+    const seenUrls = new Set<string>();
+
+    const addState = (state: { url?: string; h1?: string; title?: string; links?: Link[] } | null) => {
+      if (!state) return;
+      const url = state.url || '/';
+      if (seenUrls.has(url)) return;
+      seenUrls.add(url);
+      const title = state.h1 || state.title || 'Untitled';
+      visited.push({ title, url, links: state.links || [] });
+    };
+
+    for (const transition of history) {
+      addState(transition.fromState);
+      addState(transition.toState);
+    }
+
+    if (visited.length === 0) {
+      tag('multiline').log('No unique paths visited.');
+      return;
+    }
+
+    const lines: string[] = [];
+    lines.push(`Navigation Path (${visited.length} unique pages):\n`);
+
+    for (let i = 0; i < visited.length; i++) {
+      const { title, url, links } = visited[i];
+      lines.push(title);
+      lines.push(url);
+
+      if (i < visited.length - 1) {
+        if (showLinks && links.length > 0) {
+          lines.push('   │');
+          for (const link of links.slice(0, 10)) {
+            lines.push(`   │ → ${link.title} ${link.url}`);
+          }
+          if (links.length > 10) {
+            lines.push(`   │   ... and ${links.length - 10} more links`);
+          }
+          lines.push('   │');
+          lines.push('   ↓');
+        } else {
+          lines.push('   ↓');
+        }
+      } else if (showLinks && links.length > 0) {
+        lines.push('   │');
+        for (const link of links.slice(0, 10)) {
+          lines.push(`   │ → ${link.title} ${link.url}`);
+        }
+        if (links.length > 10) {
+          lines.push(`   │   ... and ${links.length - 10} more links`);
+        }
+      }
+    }
+
+    tag('multiline').log(lines.join('\n'));
+  }
+}

package/src/commands/plan-clear-command.ts

@@ -0,0 +1,14 @@
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class PlanClearCommand extends BaseCommand {
+  name = 'plan:clear';
+  description = 'Clear current plan and create a new one';
+  suggestions = ['/test - to launch first test', '/test * - to launch all tests'];
+
+  async execute(args: string): Promise<void> {
+    this.explorBot.clearPlan();
+    tag('success').log('Plan cleared');
+    await this.explorBot.plan(args.trim() || undefined, { fresh: true });
+  }
+}

package/src/commands/plan-command.ts

@@ -0,0 +1,41 @@
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class PlanCommand extends BaseCommand {
+  name = 'plan';
+  description = 'Plan testing for a feature';
+  suggestions = ['/test - to launch first test', '/test * - to launch all tests', 'Edit the plan in file and call /plan:reload to update it'];
+  options = [
+    { flags: '--fresh', description: 'Regenerate plan from scratch' },
+    { flags: '--clear', description: 'Clear plan before regenerating' },
+    { flags: '--style <name>', description: 'Planning style (normal, curious, psycho, performer)' },
+  ];
+
+  async execute(args: string): Promise<void> {
+    const clear = args.includes('--clear');
+    const fresh = args.includes('--fresh') || clear;
+    const styleMatch = args.match(/--style\s+(\S+)/);
+    const style = styleMatch?.[1];
+    const focus = args
+      .replace('--clear', '')
+      .replace('--fresh', '')
+      .replace(/--style\s+\S+/, '')
+      .trim();
+
+    if (clear) {
+      this.explorBot.clearPlan();
+      tag('success').log('Plan cleared');
+    }
+
+    if (focus) {
+      tag('info').log(`Planning focus: ${focus}`);
+    }
+
+    await this.explorBot.plan(focus || undefined, { fresh, style });
+
+    const plan = this.explorBot.getCurrentPlan();
+    if (!plan?.tests.length) {
+      throw new Error('No test scenarios in the current plan.');
+    }
+  }
+}

package/src/commands/plan-edit-command.ts

@@ -0,0 +1,9 @@
+import { BaseCommand } from './base-command.js';
+
+export class PlanEditCommand extends BaseCommand {
+  name = 'plan:edit';
+  description = 'Open test plan editor';
+  suggestions = ['/plan:edit - toggle tests on/off'];
+
+  async execute(_args: string): Promise<void> {}
+}

package/src/commands/plan-load-command.ts

@@ -0,0 +1,18 @@
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class PlanLoadCommand extends BaseCommand {
+  name = 'plan:load';
+  description = 'Load plan from file';
+  suggestions = ['/test - to launch first test', '/test * - to launch all tests'];
+
+  async execute(args: string): Promise<void> {
+    const filename = args.trim();
+    if (!filename) {
+      throw new Error('Filename required. Usage: /plan:load <filename>');
+    }
+
+    const plan = this.explorBot.loadPlan(filename);
+    tag('success').log(`Plan loaded: ${plan.title} with ${plan.tests.length} tests`);
+  }
+}

package/src/commands/plan-reload-command.ts

@@ -0,0 +1,28 @@
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class PlanReloadCommand extends BaseCommand {
+  name = 'plan:reload';
+  description = 'Clear current plan and regenerate';
+  suggestions = ['/test - to launch first test', '/test * - to launch all tests'];
+
+  async execute(args: string): Promise<void> {
+    const currentPlan = this.explorBot.getCurrentPlan();
+    if (!currentPlan) {
+      throw new Error('No plan to reload. Run /plan first.');
+    }
+
+    const feature = args.trim() || this.explorBot.getPlanFeature();
+    this.explorBot.clearPlan();
+
+    tag('info').log('Plan cleared, regenerating...');
+    await this.explorBot.plan(feature);
+
+    const plan = this.explorBot.getCurrentPlan();
+    if (!plan?.tests.length) {
+      throw new Error('No test scenarios in the regenerated plan.');
+    }
+
+    tag('success').log(`Plan regenerated with ${plan.tests.length} tests`);
+  }
+}

package/src/commands/plan-save-command.ts

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class PlanSaveCommand extends BaseCommand {
+  name = 'plan:save';
+  description = 'Save current plan to file';
+  suggestions = ['/test - to launch first test'];
+
+  async execute(args: string): Promise<void> {
+    const plan = this.explorBot.getCurrentPlan();
+    if (!plan) {
+      throw new Error('No plan to save. Run /plan first.');
+    }
+
+    const filename = args.trim() || undefined;
+    const savedPath = this.explorBot.savePlan(filename);
+
+    if (savedPath) {
+      const relativePath = path.relative(process.cwd(), savedPath);
+      tag('success').log(`Plan saved to: ${relativePath}`);
+      tag('info').log(`Run /plan:load ${relativePath} to reload it`);
+    }
+  }
+}

package/src/commands/research-command.ts

@@ -0,0 +1,45 @@
+import { join } from 'node:path';
+import { ConfigParser } from '../config.ts';
+import { tag } from '../utils/logger.ts';
+import { BaseCommand } from './base-command.js';
+
+export class ResearchCommand extends BaseCommand {
+  name = 'research';
+  description = 'Research current page or navigate to URI and research. Use --deep to explore interactive elements by clicking them. Use --data to include page data.';
+  suggestions = ['/navigate <page> - to go to another page', '/plan <feature> - to plan testing'];
+
+  async execute(args: string): Promise<void> {
+    const includeData = args.includes('--data');
+    const enableDeep = args.includes('--deep');
+    const noFix = args.includes('--no-fix');
+    const target = args.replace('--data', '').replace('--deep', '').replace('--no-fix', '').trim();
+
+    if (target) {
+      await this.explorBot.agentNavigator().visit(target);
+    }
+
+    const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+    if (!state) {
+      throw new Error('No active page to research');
+    }
+
+    const result = await this.explorBot.agentResearcher().research(state, {
+      screenshot: true,
+      force: true,
+      data: includeData,
+      deep: enableDeep,
+      fix: !noFix,
+    });
+
+    tag('multiline').log(result);
+
+    if (state.hash) {
+      const outputDir = ConfigParser.getInstance().getOutputDir();
+      tag('info').log(`Research file: ${join(outputDir, 'research', `${state.hash}.md`)}`);
+    }
+
+    if (!enableDeep) {
+      this.suggestions = ['/research <page> --deep - analyze page for all expandable elements and interactions'];
+    }
+  }
+}

package/src/commands/start-command.ts

@@ -0,0 +1,13 @@
+import { BaseCommand } from './base-command.js';
+import { ExploreCommand } from './explore-command.js';
+
+export class StartCommand extends BaseCommand {
+  name = 'start';
+  aliases = ['sail'];
+  description = 'Start web exploration';
+  suggestions = ['/navigate <page> - to go to another page', '/research - to analyze', '/plan <feature> - to plan testing'];
+
+  async execute(args: string): Promise<void> {
+    await new ExploreCommand(this.explorBot).execute(args);
+  }
+}

package/src/commands/status-command.tsx

@@ -0,0 +1,23 @@
+import { render } from 'ink';
+import React from 'react';
+import { StatusPane } from '../components/StatusPane.js';
+import { BaseCommand } from './base-command.js';
+
+export class StatusCommand extends BaseCommand {
+  name = 'status';
+  description = 'Show session statistics and token usage';
+
+  async execute(_args: string): Promise<void> {
+    return new Promise((resolve) => {
+      const { unmount } = render(
+        React.createElement(StatusPane, {
+          onComplete: () => {
+            unmount();
+            resolve();
+          },
+        }),
+        { exitOnCtrlC: false, patchConsole: false }
+      );
+    });
+  }
+}