explorbot 0.0.1 → 0.0.5

package/src/commands/base-command.ts

@@ -0,0 +1,27 @@
+import type { ExplorBot } from '../explorbot.js';
+
+export interface CommandOption {
+  flags: string;
+  description: string;
+}
+
+export abstract class BaseCommand {
+  abstract name: string;
+  abstract description: string;
+  aliases: string[] = [];
+  options: CommandOption[] = [];
+  tuiEnabled = true;
+  suggestions: string[] = [];
+
+  protected explorBot: ExplorBot;
+
+  constructor(explorBot: ExplorBot) {
+    this.explorBot = explorBot;
+  }
+
+  abstract execute(args: string): Promise<void>;
+
+  matches(commandName: string): boolean {
+    return this.name === commandName || this.aliases.includes(commandName);
+  }
+}

package/src/commands/clean-command.ts

@@ -0,0 +1,73 @@
+import { existsSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ConfigParser, outputPath } from '../config.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export const CLEAN_TARGETS: Record<string, { description: string; getDir: () => string }> = {
+  states: { description: 'page states', getDir: () => outputPath('states') },
+  research: { description: 'research cache', getDir: () => outputPath('research') },
+  plans: { description: 'test plans', getDir: () => outputPath('plans') },
+  experiences: { description: 'experience files', getDir: () => getExperienceDir() },
+  output: { description: 'all output files', getDir: () => outputPath() },
+};
+
+function getExperienceDir(): string {
+  const configParser = ConfigParser.getInstance();
+  const config = configParser.getConfig();
+  const configPath = configParser.getConfigPath();
+  if (configPath) {
+    return join(dirname(configPath), config.dirs?.experience || 'experience');
+  }
+  return config.dirs?.experience || 'experience';
+}
+
+function cleanDirectoryContents(dirPath: string): number {
+  if (!existsSync(dirPath)) return 0;
+  let count = 0;
+  for (const item of readdirSync(dirPath)) {
+    const itemPath = join(dirPath, item);
+    if (statSync(itemPath).isDirectory()) {
+      count += cleanDirectoryContents(itemPath);
+      rmSync(itemPath, { recursive: true });
+    } else {
+      unlinkSync(itemPath);
+      count++;
+    }
+  }
+  return count;
+}
+
+export class CleanCommand extends BaseCommand {
+  name = 'clean';
+  description = 'Clean files: clean [states|research|plans|experiences|output]';
+  suggestions = Object.keys(CLEAN_TARGETS).map((t) => `/clean ${t}`);
+
+  async execute(args: string): Promise<void> {
+    const target = args.trim().toLowerCase();
+
+    if (!target) {
+      this.cleanTarget('output');
+      this.cleanTarget('experiences');
+      return;
+    }
+
+    if (!CLEAN_TARGETS[target]) {
+      tag('error').log(`Unknown clean target: ${target}. Available: ${Object.keys(CLEAN_TARGETS).join(', ')}`);
+      return;
+    }
+
+    this.cleanTarget(target);
+  }
+
+  private cleanTarget(name: string): void {
+    const target = CLEAN_TARGETS[name];
+    const dir = target.getDir();
+    if (!existsSync(dir)) {
+      tag('info').log(`${name}: nothing to clean (${dir} not found)`);
+      return;
+    }
+    const count = cleanDirectoryContents(dir);
+    tag('success').log(`Cleaned ${count} ${target.description} files from ${dir}`);
+  }
+}

package/src/commands/context-aria-command.ts

@@ -0,0 +1,22 @@
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class ContextAriaCommand extends BaseCommand {
+  name = 'context:aria';
+  description = 'Print full ARIA snapshot for current page';
+
+  async execute(_args: string): Promise<void> {
+    const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+
+    if (!state) {
+      throw new Error('No active page to snapshot');
+    }
+
+    const ariaSnapshot = state.ariaSnapshot;
+    if (!ariaSnapshot) {
+      throw new Error('No ARIA snapshot available for current page');
+    }
+
+    tag('multiline').log(`ARIA Snapshot:\n\n${ariaSnapshot}`);
+  }
+}

package/src/commands/context-command.ts

@@ -0,0 +1,67 @@
+import { ActionResult } from '../action-result.js';
+import { Researcher } from '../ai/researcher.js';
+import { outputPath } from '../config.js';
+import { type ContextData, type ContextMode, formatContextSummary } from '../utils/context-formatter.js';
+import { tag } from '../utils/logger.js';
+import { extractValidContainers } from '../utils/research-parser.js';
+import { BaseCommand } from './base-command.js';
+
+export class ContextCommand extends BaseCommand {
+  name = 'context';
+  description = 'Show page context summary (URL, headings, experience, knowledge, ARIA, HTML, research)';
+  suggestions = ['context:aria', 'context:html', 'context:knowledge', 'context:experience', 'context:data'];
+
+  async execute(args: string): Promise<void> {
+    const explorer = this.explorBot.getExplorer();
+    const state = explorer.getStateManager().getCurrentState();
+
+    if (!state) {
+      throw new Error('No active page to show context for');
+    }
+
+    const isVisual = args.includes('--visual') || args.includes('--screenshot');
+
+    await explorer.annotateElements();
+
+    if (isVisual) {
+      const cachedResearch = Researcher.getCachedResearch(state);
+      const containers = cachedResearch ? extractValidContainers(cachedResearch) : [];
+      await explorer.visuallyAnnotateElements({ containers });
+    }
+
+    const actionResult = await explorer.createAction().capturePageState({ includeScreenshot: isVisual });
+    const experienceTracker = explorer.getStateManager().getExperienceTracker();
+    const knowledgeTracker = this.explorBot.getKnowledgeTracker();
+
+    let mode: ContextMode = 'compact';
+    if (args.includes('--full')) {
+      mode = 'full';
+    } else if (args.includes('--attached')) {
+      mode = 'attached';
+    }
+
+    const contextData: ContextData = {
+      url: actionResult.url,
+      title: actionResult.title,
+      headings: {
+        h1: actionResult.h1,
+        h2: actionResult.h2,
+        h3: actionResult.h3,
+        h4: actionResult.h4,
+      },
+      experience: experienceTracker.getRelevantExperience(actionResult),
+      knowledge: knowledgeTracker.getRelevantKnowledge(actionResult),
+      ariaSnapshot: actionResult.ariaSnapshot,
+      combinedHtml: mode === 'full' ? await actionResult.combinedHtml() : undefined,
+      research: Researcher.getCachedResearch(state),
+    };
+
+    const output = formatContextSummary(contextData, mode);
+    tag('multiline').log(output);
+
+    if (isVisual && actionResult.screenshotFile) {
+      const fullPath = outputPath('states', actionResult.screenshotFile);
+      tag('info').log(`Screenshot saved: file://${fullPath}`);
+    }
+  }
+}

package/src/commands/context-data-command.ts

@@ -0,0 +1,30 @@
+import { ActionResult } from '../action-result.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class ContextDataCommand extends BaseCommand {
+  name = 'context:data';
+  description = 'Extract structured data from current page';
+
+  async execute(_args: string): Promise<void> {
+    const explorer = this.explorBot.getExplorer();
+    const state = explorer.getStateManager().getCurrentState();
+
+    if (!state) {
+      throw new Error('No active page to extract data from');
+    }
+
+    const actionResult = ActionResult.fromState(state);
+
+    if (!actionResult.html || actionResult.html.trim().length < 100) {
+      tag('info').log('Capturing fresh page content...');
+      const freshResult = await explorer.createAction().capturePageState();
+      const table = await this.explorBot.agentResearcher().extractData(freshResult);
+      tag('multiline').log(table);
+      return;
+    }
+
+    const table = await this.explorBot.agentResearcher().extractData(state);
+    tag('multiline').log(table);
+  }
+}

package/src/commands/context-experience-command.ts

@@ -0,0 +1,48 @@
+import { basename } from 'node:path';
+import chalk from 'chalk';
+import { ActionResult } from '../action-result.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class ContextExperienceCommand extends BaseCommand {
+  name = 'context:experience';
+  description = 'Print all matching experience for current page';
+
+  async execute(_args: string): Promise<void> {
+    const explorer = this.explorBot.getExplorer();
+    const state = explorer.getStateManager().getCurrentState();
+
+    if (!state) {
+      throw new Error('No active page');
+    }
+
+    const actionResult = ActionResult.fromState(state);
+    const experienceTracker = explorer.getStateManager().getExperienceTracker();
+    const experience = experienceTracker.getRelevantExperience(actionResult);
+
+    if (experience.length === 0) {
+      tag('info').log(`No experience found for: ${actionResult.url}`);
+      return;
+    }
+
+    const lines: string[] = [];
+    lines.push(chalk.bold.cyan(`📁 Experience for ${actionResult.url} (${experience.length} files)`));
+    lines.push('');
+
+    for (const exp of experience) {
+      lines.push(chalk.yellow(`--- ${basename(exp.filePath)} ---`));
+      if (exp.data?.url) {
+        lines.push(chalk.gray(`URL: ${exp.data.url}`));
+      }
+      if (exp.data?.title) {
+        lines.push(chalk.gray(`Title: ${exp.data.title}`));
+      }
+      if (exp.content.trim()) {
+        lines.push(exp.content.trim());
+      }
+      lines.push('');
+    }
+
+    tag('multiline').log(lines.join('\n'));
+  }
+}

package/src/commands/context-html-command.ts

@@ -0,0 +1,33 @@
+import { ActionResult } from '../action-result.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class ContextHtmlCommand extends BaseCommand {
+  name = 'context:html';
+  description = 'Print combined HTML snapshot for current page';
+
+  async execute(_args: string): Promise<void> {
+    const explorer = this.explorBot.getExplorer();
+    const manager = explorer.getStateManager();
+    const state = manager.getCurrentState();
+
+    if (!state) {
+      throw new Error('No active page to snapshot');
+    }
+
+    let actionResult = ActionResult.fromState(state);
+
+    if (!actionResult.html || actionResult.html.trim().length < 100) {
+      tag('info').log('Capturing fresh page content...');
+      actionResult = await explorer.createAction().capturePageState();
+    }
+
+    const html = await actionResult.combinedHtml();
+
+    if (!html) {
+      throw new Error('No HTML snapshot available for current page');
+    }
+
+    tag('html').log(html);
+  }
+}

package/src/commands/context-knowledge-command.ts

@@ -0,0 +1,43 @@
+import { basename } from 'node:path';
+import chalk from 'chalk';
+import { ActionResult } from '../action-result.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class ContextKnowledgeCommand extends BaseCommand {
+  name = 'context:knowledge';
+  description = 'Print all matching knowledge for current page';
+
+  async execute(_args: string): Promise<void> {
+    const explorer = this.explorBot.getExplorer();
+    const state = explorer.getStateManager().getCurrentState();
+
+    if (!state) {
+      throw new Error('No active page');
+    }
+
+    const actionResult = ActionResult.fromState(state);
+    const knowledgeTracker = this.explorBot.getKnowledgeTracker();
+    const knowledge = knowledgeTracker.getRelevantKnowledge(actionResult);
+
+    if (knowledge.length === 0) {
+      tag('info').log(`No knowledge found for: ${actionResult.url}`);
+      return;
+    }
+
+    const lines: string[] = [];
+    lines.push(chalk.bold.cyan(`📚 Knowledge for ${actionResult.url} (${knowledge.length} files)`));
+    lines.push('');
+
+    for (const k of knowledge) {
+      lines.push(chalk.yellow(`--- ${basename(k.filePath)} ---`));
+      lines.push(chalk.gray(`Pattern: ${k.url}`));
+      if (k.content.trim()) {
+        lines.push(k.content.trim());
+      }
+      lines.push('');
+    }
+
+    tag('multiline').log(lines.join('\n'));
+  }
+}

package/src/commands/debug-command.ts

@@ -0,0 +1,13 @@
+import { isDebugMode, setDebugMode, tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class DebugCommand extends BaseCommand {
+  name = 'debug';
+  description = 'Toggle debug output';
+
+  async execute(_args: string): Promise<void> {
+    const enabled = !isDebugMode();
+    setDebugMode(enabled);
+    tag('info').log(`Debug mode ${enabled ? 'enabled' : 'disabled'}`);
+  }
+}

package/src/commands/drill-command.ts

@@ -0,0 +1,34 @@
+import { BaseCommand } from './base-command.js';
+
+export class DrillCommand extends BaseCommand {
+  name = 'drill';
+  description = 'Drill all components on current page to learn interactions';
+  aliases = ['bosun'];
+  suggestions = ['/research - to see UI map first', '/navigate <page> - to go to another page'];
+
+  async execute(args: string): Promise<void> {
+    const knowledgePath = this.parseKnowledgeArg(args);
+    const maxComponents = this.parseMaxArg(args);
+
+    const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+    if (!state) {
+      throw new Error('No active page to drill');
+    }
+
+    await this.explorBot.agentBosun().drill({
+      knowledgePath,
+      maxComponents,
+      interactive: true,
+    });
+  }
+
+  private parseKnowledgeArg(args: string): string | undefined {
+    const match = args.match(/--knowledge\s+(\S+)/);
+    return match ? match[1] : undefined;
+  }
+
+  private parseMaxArg(args: string): number | undefined {
+    const match = args.match(/--max\s+(\d+)/);
+    return match ? Number.parseInt(match[1], 10) : undefined;
+  }
+}

package/src/commands/exit-command.ts

@@ -0,0 +1,32 @@
+import { render } from 'ink';
+import React from 'react';
+import { StatusPane } from '../components/StatusPane.js';
+import { Stats } from '../stats.js';
+import { BaseCommand } from './base-command.js';
+
+export class ExitCommand extends BaseCommand {
+  name = 'exit';
+  description = 'Exit the application';
+  aliases = ['quit'];
+
+  async execute(_args: string): Promise<void> {
+    await this.explorBot.getExplorer().stop();
+
+    if (Stats.hasActivity()) {
+      await new Promise<void>((resolve) => {
+        const { unmount } = render(
+          React.createElement(StatusPane, {
+            onComplete: () => {
+              unmount();
+              resolve();
+            },
+          }),
+          { exitOnCtrlC: false, patchConsole: false }
+        );
+      });
+    }
+
+    console.log('\nGoodbye!');
+    process.exit(0);
+  }
+}

package/src/commands/explore-command.ts

@@ -0,0 +1,129 @@
+import figureSet from 'figures';
+import path from 'node:path';
+import { getStyles } from '../ai/planner/styles.js';
+import { getCliName } from '../utils/cli-name.ts';
+import type { Plan } from '../test-plan.js';
+import { jsonToTable } from '../utils/markdown-parser.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class ExploreCommand extends BaseCommand {
+  name = 'explore';
+  description = 'Start web exploration';
+  options = [{ flags: '--max-tests <number>', description: 'Maximum number of tests to run' }];
+  suggestions = ['/navigate <page> - to go to another page', '/research - to analyze', '/plan <feature> - to plan testing'];
+
+  maxTests?: number;
+  private testsRun = 0;
+  private completedPlans: Plan[] = [];
+
+  async execute(args: string): Promise<void> {
+    const maxTestsMatch = args.match(/--max-tests\s+(\d+)/);
+    if (maxTestsMatch) {
+      this.maxTests = Number.parseInt(maxTestsMatch[1], 10);
+      args = args.replace(/--max-tests\s+\d+/, '').trim();
+    }
+
+    const feature = args.trim() || undefined;
+    const mainUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url;
+
+    await this.runAllStyles(mainUrl, feature);
+    const mainPlan = this.explorBot.getCurrentPlan();
+    if (!mainPlan) return;
+    this.completedPlans.push(mainPlan);
+
+    if (!this.isLimitReached()) {
+      const planner = this.explorBot.agentPlanner();
+      while (true) {
+        if (this.isLimitReached()) break;
+
+        const candidates = planner.collectSubPageCandidates(mainPlan, mainUrl || '/');
+        if (candidates.length === 0) break;
+
+        const pick = await planner.pickNextSubPage(candidates);
+        if (!pick) break;
+
+        tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
+        try {
+          await this.explorBot.visit(pick.url);
+          await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans);
+          const subPlan = this.explorBot.getCurrentPlan();
+          if (subPlan) {
+            this.completedPlans.push(subPlan);
+          }
+        } catch (err) {
+          tag('warning').log(`Sub-page exploration failed: ${err instanceof Error ? err.message : err}`);
+        }
+      }
+    }
+
+    this.explorBot.setCurrentPlan(mainPlan);
+    if (mainUrl) await this.explorBot.visit(mainUrl);
+    const savedPath = this.explorBot.savePlans(this.completedPlans);
+    this.printResults(savedPath);
+  }
+
+  private async runAllStyles(pageUrl?: string, feature?: string, parentPlan?: Plan, completedPlans?: Plan[]): Promise<void> {
+    let fresh = true;
+    for (const style of Object.keys(getStyles())) {
+      if (!fresh && pageUrl) {
+        await this.explorBot.visit(pageUrl);
+      }
+      const opts: { fresh: boolean; style: string; extend?: Plan; completedPlans?: Plan[] } = { fresh, style, completedPlans };
+      if (fresh && parentPlan) opts.extend = parentPlan;
+      await this.explorBot.plan(feature, opts);
+      await this.runPendingTests();
+      fresh = false;
+    }
+  }
+
+  private printResults(savedPath?: string | null): void {
+    const allTests = this.completedPlans.flatMap((plan) => plan.tests.filter((t) => t.status !== 'pending').map((test) => ({ test, planTitle: plan.title })));
+
+    if (allTests.length === 0) return;
+
+    const hasSubPages = this.completedPlans.length > 1;
+    const rows = allTests.map(({ test, planTitle }, index) => {
+      const durationMs = test.getDurationMs();
+      const duration = durationMs != null ? `${(durationMs / 1000).toFixed(1)}s` : '-';
+      let status = 'failed';
+      if (test.isSuccessful) status = 'passed';
+      else if (test.isSkipped) status = 'skipped';
+      const row: Record<string, string> = {
+        '#': String(index + 1),
+        Status: status,
+        Title: test.scenario.replace(/\|/g, '-'),
+        Priority: test.priority,
+        Time: duration,
+        Steps: String(Object.keys(test.notes).length),
+      };
+      if (hasSubPages) {
+        row.Plan = planTitle;
+      }
+      return row;
+    });
+    const columns = ['#', 'Status', 'Title', 'Priority', 'Time', 'Steps'];
+    if (hasSubPages) columns.push('Plan');
+    tag('multiline').log(jsonToTable(rows, columns));
+    tag('info').log(`${figureSet.tick} ${allTests.length} tests completed`);
+
+    if (savedPath) {
+      const relativePath = path.relative(process.cwd(), savedPath);
+      tag('info').log(`Re-run tests: ${getCliName()} test ${relativePath} <index>`);
+    }
+  }
+
+  private isLimitReached(): boolean {
+    return this.maxTests != null && this.testsRun >= this.maxTests;
+  }
+
+  private async runPendingTests(): Promise<void> {
+    const plan = this.explorBot.getCurrentPlan();
+    if (!plan) return;
+    for (const test of plan.getPendingTests()) {
+      if (this.isLimitReached()) break;
+      await this.explorBot.agentTester().test(test);
+      this.testsRun++;
+    }
+  }
+}

package/src/commands/freesail-command.ts

@@ -0,0 +1,95 @@
+import { Planner } from '../ai/planner.js';
+import { Researcher } from '../ai/researcher.js';
+import { tag } from '../utils/logger.js';
+import { loop } from '../utils/loop.js';
+import { BaseCommand } from './base-command.js';
+import { ExploreCommand } from './explore-command.js';
+
+export class FreesailCommand extends BaseCommand {
+  name = 'freesail';
+  description = 'Continuously explore and navigate to new pages autonomously';
+  aliases = ['freeride'];
+  tuiEnabled = true;
+  options = [
+    { flags: '--deep', description: 'Use deep navigation strategy' },
+    { flags: '--shallow', description: 'Use shallow navigation strategy' },
+    { flags: '--scope <url>', description: 'Limit navigation to URLs starting with this prefix' },
+    { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
+  ];
+
+  async execute(args: string): Promise<void> {
+    const { strategy, scope, maxTests } = parseArgs(args);
+
+    await this.explorBot.visitInitialState();
+
+    let testsRun = 0;
+
+    await loop(
+      async (ctx) => {
+        if (maxTests != null && testsRun >= maxTests) ctx.stop();
+
+        const stateManager = this.explorBot.getExplorer().getStateManager();
+        const state = stateManager.getCurrentState();
+
+        if (state && !Researcher.getCachedResearch(state)) {
+          await this.explorBot.agentResearcher().research(state, { deep: true, screenshot: true });
+        }
+
+        const cachedPlan = state?.url ? Planner.getCachedPlan(state.url) : null;
+        if (cachedPlan?.tests.some((t) => t.result)) {
+          tag('info').log(`Page already tested (${cachedPlan.tests.length} tests in plan), skipping exploration`);
+        } else {
+          const exploreCmd = new ExploreCommand(this.explorBot);
+          if (maxTests != null) exploreCmd.maxTests = maxTests - testsRun;
+          await exploreCmd.execute('');
+
+          const plan = this.explorBot.getCurrentPlan();
+          if (plan) testsRun += plan.tests.filter((t) => t.hasFinished).length;
+        }
+
+        if (maxTests != null && testsRun >= maxTests) ctx.stop();
+
+        const navigator = this.explorBot.agentNavigator();
+        const visitedUrls = stateManager.getAllVisitedUrls();
+        const suggestion = await navigator.freeSail({ strategy, scope, visitedUrls });
+        if (!suggestion) {
+          tag('info').log('No navigation suggestion available');
+          return;
+        }
+
+        if (scope && !suggestion.target.startsWith(scope)) {
+          tag('warning').log(`Suggestion ${suggestion.target} is outside scope ${scope}, skipping`);
+          return;
+        }
+
+        tag('info').log(`Navigating to: ${suggestion.target} - ${suggestion.reason}`);
+        await this.explorBot.openFreshTab();
+        await this.explorBot.visit(suggestion.target);
+        this.explorBot.clearPlan();
+      },
+      { maxAttempts: Number.POSITIVE_INFINITY }
+    );
+  }
+}
+
+function parseArgs(args: string): { strategy: 'deep' | 'shallow' | undefined; scope: string | undefined; maxTests: number | undefined } {
+  const parts = args.trim().split(/\s+/);
+  let strategy: 'deep' | 'shallow' | undefined;
+  let scope: string | undefined;
+  let maxTests: number | undefined;
+
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '--deep') strategy = 'deep';
+    if (parts[i] === '--shallow') strategy = 'shallow';
+    if (parts[i] === '--scope' && parts[i + 1]) {
+      scope = parts[i + 1];
+      i++;
+    }
+    if (parts[i] === '--max-tests' && parts[i + 1]) {
+      maxTests = Number.parseInt(parts[i + 1], 10);
+      i++;
+    }
+  }
+
+  return { strategy, scope, maxTests };
+}

package/src/commands/help-command.ts

@@ -0,0 +1,8 @@
+import { BaseCommand } from './base-command.js';
+
+export class HelpCommand extends BaseCommand {
+  name = 'help';
+  description = 'Show available commands';
+
+  async execute(_args: string): Promise<void> {}
+}