explorbot 0.0.5 → 0.1.1

package/src/commands/test-command.ts

@@ -25,10 +25,10 @@ export class TestCommand extends BaseCommand {
     } else if (args === '*' || args === 'all') {
       toExecute.push(...requirePlan().getPendingTests());
     } else if (args.match(/^[\d,\-\s]+$/)) {
-      const pending = requirePlan().getPendingTests();
-      const indices = parseTestIndices(args, pending.length);
+      const visible = requirePlan().tests.filter((t) => t.enabled);
+      const indices = parseTestIndices(args, visible.length);
       for (const idx of indices) {
-        toExecute.push(pending[idx]);
+        toExecute.push(visible[idx]);
       }
     } else {
       const matching = plan?.getPendingTests().filter((test) => test.scenario.toLowerCase().includes(args.toLowerCase())) || [];

package/src/components/App.tsx

@@ -242,6 +242,14 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
         setShowPlanEditor(true);
         return;
       }
+      if (key.upArrow) {
+        setTaskScrollOffset((prev) => Math.max(0, prev - 1));
+        return;
+      }
+      if (key.downArrow) {
+        setTaskScrollOffset((prev) => prev + 1);
+        return;
+      }
     }
 
     if (!showInput && !showPlanEditor) {

package/src/config.ts

@@ -85,6 +85,22 @@ interface NavigatorAgentConfig extends AgentConfig {
   maxAttempts?: number;
 }
 
+type HealFn = (ctx: { I: any }) => Promise<void> | void;
+
+interface HealRecipe {
+  priority?: number;
+  steps?: string[];
+  fn: (context: { step: any; error: Error; prevSteps?: any[] }) => HealFn | Promise<HealFn | null> | null;
+}
+
+interface RerunnerAgentConfig extends AgentConfig {
+  healLimit?: number;
+  ariaSnapshotLimit?: number;
+  retryFailedStep?: Record<string, any>;
+  screenshotOnFail?: Record<string, any>;
+  recipes?: Record<string, HealRecipe>;
+}
+
 interface PlannerAgentConfig extends AgentConfig {
   styles?: string[];
   stylesDir?: string;
@@ -103,6 +119,7 @@ interface AgentsConfig {
   fisherman?: AgentConfig;
   chief?: AgentConfig;
   curler?: AgentConfig;
+  rerunner?: RerunnerAgentConfig;
 }
 
 interface AIConfig {
@@ -185,6 +202,7 @@ interface ExplorbotConfig {
   api?: ApiConfig;
   stepsFile?: string;
   files?: Record<string, string>;
+  dynamicPageRegex?: string;
 }
 
 const config: ExplorbotConfig = {
@@ -213,6 +231,8 @@ export type {
   ResearcherAgentConfig,
   NavigatorAgentConfig,
   PlannerAgentConfig,
+  RerunnerAgentConfig,
+  HealRecipe,
   Hook,
   HookConfig,
   HooksConfig,
@@ -327,6 +347,10 @@ export class ConfigParser {
     return outputPath('plans');
   }
 
+  public getTestsDir(): string {
+    return outputPath('tests');
+  }
+
   // For testing purposes only
   public static resetForTesting(): void {
     if (ConfigParser.instance) {

package/src/explorbot.ts

@@ -14,11 +14,13 @@ import { Planner } from './ai/planner.ts';
 import { AIProvider } from './ai/provider.ts';
 import { Quartermaster } from './ai/quartermaster.ts';
 import { Researcher } from './ai/researcher.ts';
+import { Rerunner } from './ai/rerunner.ts';
 import { Tester } from './ai/tester.ts';
 import { createAgentTools } from './ai/tools.ts';
 import type { ExplorbotConfig } from './config.js';
 import { ConfigParser } from './config.ts';
 import Explorer from './explorer.ts';
+import type { Suite } from './suite.ts';
 import { KnowledgeTracker } from './knowledge-tracker.ts';
 import { WebPageState } from './state-manager.ts';
 import { Plan } from './test-plan.ts';
@@ -108,7 +110,7 @@ export class ExplorBot {
   }
 
   getCurrentState(): WebPageState | null {
-    return this.explorer.getStateManager().getCurrentState();
+    return this.explorer?.getStateManager().getCurrentState() ?? null;
   }
 
   getExplorer(): Explorer {
@@ -245,6 +247,21 @@ export class ExplorBot {
     }));
   }
 
+  agentRerunner(): Rerunner {
+    if (!this.agents.rerunner) {
+      this.agents.rerunner = this.createAgent(({ ai, explorer }) => {
+        const researcher = this.agentResearcher();
+        const navigator = this.agentNavigator();
+        const tools = createAgentTools({ explorer, researcher, navigator });
+        return new Rerunner(explorer, ai, tools);
+      });
+      const qm = this.agentQuartermaster();
+      if (qm) this.agents.rerunner.setQuartermaster(qm);
+      this.agents.rerunner.setHistorian(this.agentHistorian());
+    }
+    return this.agents.rerunner;
+  }
+
   agentBosun(): Bosun {
     return (this.agents.bosun ||= this.createAgent(({ ai, explorer }) => {
       const researcher = this.agentResearcher();
@@ -291,6 +308,10 @@ export class ExplorBot {
     return this.currentPlan;
   }
 
+  getSuite(): Suite | null {
+    return this.agentPlanner().getSuite();
+  }
+
   getPlanFeature(): string | undefined {
     return this.planFeature;
   }

package/src/explorer.ts

@@ -19,6 +19,7 @@ import { Test } from './test-plan.ts';
 import { RequestStore } from './api/request-store.ts';
 import { XhrCapture } from './api/xhr-capture.ts';
 import { createDebug, log, tag } from './utils/logger.js';
+import { WebElement, extractElementData } from './utils/web-element.ts';
 
 declare global {
   namespace NodeJS {
@@ -308,35 +309,24 @@ class Explorer {
     return action;
   }
 
-  async annotateElements(): Promise<number> {
-    const page = this.playwrightHelper.page;
-    const roles = ['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem'];
-    let idx = 1;
-    for (const role of roles) {
-      const elements = await page.getByRole(role).all();
-      for (const el of elements) {
-        await el.evaluate((node: Element, i: number) => {
-          node.setAttribute('data-explorbot-eidx', String(i));
-        }, idx);
-        idx++;
-      }
-    }
-    return idx - 1;
+  async annotateElements(): Promise<WebElement[]> {
+    const { elements } = await annotatePageElements(this.playwrightHelper.page);
+    return elements;
   }
 
   async visuallyAnnotateElements(opts?: { containers?: Array<{ css: string; label: string }> }): Promise<number> {
     return visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []);
   }
 
-  async getEidxInContainer(containerCss: string | null): Promise<number[]> {
+  async getEidxInContainer(containerCss: string | null): Promise<string[]> {
     const page = this.playwrightHelper.page;
     try {
       const selector = containerCss ? `${containerCss} [data-explorbot-eidx]` : '[data-explorbot-eidx]';
       const elements = await page.locator(selector).all();
-      const result: number[] = [];
+      const result: string[] = [];
       for (const el of elements) {
         const attr = await el.getAttribute('data-explorbot-eidx');
-        if (attr) result.push(Number.parseInt(attr, 10));
+        if (attr) result.push(attr);
       }
       return result;
     } catch (error) {
@@ -348,13 +338,12 @@ class Explorer {
     }
   }
 
-  async getEidxByLocator(locator: string, container?: string | null): Promise<number | null> {
+  async getEidxByLocator(locator: string, container?: string | null): Promise<string | null> {
     try {
       const page = this.playwrightHelper.page;
       const base = container ? page.locator(container) : page;
       const el = locator.startsWith('//') ? base.locator(`xpath=${locator}`) : base.locator(locator);
-      const eidx = await el.first().getAttribute('data-explorbot-eidx');
-      return eidx ? Number.parseInt(eidx, 10) : null;
+      return await el.first().getAttribute('data-explorbot-eidx');
     } catch (error) {
       if (this.isFatalBrowserError(error)) {
         tag('warning').log(`getEidxByLocator: ${error instanceof Error ? error.message : error}`);
@@ -710,4 +699,63 @@ function toCodeceptjsTest(test: Test): any {
   return codeceptjsTest;
 }
 
+const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
+
+const ANNOTATABLE_ROLES = new Set(['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem']);
+
+function parseAriaRefs(ariaSnapshot: string): Array<{ role: string; name: string; ref: string }> {
+  const entries: Array<{ role: string; name: string; ref: string }> = [];
+  for (const line of ariaSnapshot.split('\n')) {
+    const match = line.match(REF_LINE_PATTERN);
+    if (!match) continue;
+    if (!ANNOTATABLE_ROLES.has(match[2])) continue;
+    entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
+  }
+  return entries;
+}
+
+export async function annotatePageElements(page: any): Promise<{ ariaSnapshot: string; elements: WebElement[] }> {
+  const ariaSnapshot: string = await page.locator('body').ariaSnapshot({ forAI: true });
+  const refEntries = parseAriaRefs(ariaSnapshot);
+
+  const byRole = new Map<string, Array<{ name: string; ref: string }>>();
+  for (const { role, name, ref } of refEntries) {
+    let list = byRole.get(role);
+    if (!list) {
+      list = [];
+      byRole.set(role, list);
+    }
+    list.push({ name, ref });
+  }
+
+  const elements: WebElement[] = [];
+  for (const [role, entries] of byRole) {
+    try {
+      const rawList = await page.getByRole(role).evaluateAll(
+        (domElements: Element[], [data, extractFnStr]: [Array<{ name: string; ref: string }>, string]) => {
+          const extract = new Function(`return ${extractFnStr}`)() as (el: Element) => any;
+          const results: any[] = [];
+          let ariaIdx = 0;
+          for (const el of domElements) {
+            if (ariaIdx >= data.length) break;
+            el.setAttribute('data-explorbot-eidx', data[ariaIdx].ref);
+            const elData = extract(el);
+            if (elData) results.push(elData);
+            ariaIdx++;
+          }
+          return results;
+        },
+        [entries, extractElementData.toString()]
+      );
+      for (const raw of rawList) {
+        elements.push(WebElement.fromRawData(raw, role));
+      }
+    } catch {
+      debugLog(`Failed to annotate role=${role}`);
+    }
+  }
+
+  return { ariaSnapshot, elements };
+}
+
 export default Explorer;

package/src/suite.ts

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { Reflection } from '@codeceptjs/reflection';
+import { ConfigParser } from './config.ts';
+import { normalizeUrl } from './state-manager.ts';
+import { parsePlanFromMarkdown } from './utils/test-plan-markdown.ts';
+import { createDebug } from './utils/logger.ts';
+
+const debugLog = createDebug('explorbot:suite');
+
+export class Suite {
+  readonly url: string;
+  private _automatedTests: AutomatedTest[] | null = null;
+  private _plannedScenarios: string[] | null = null;
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  getAutomatedTests(): AutomatedTest[] {
+    if (this._automatedTests !== null) return this._automatedTests;
+    this._automatedTests = this.loadAutomatedTests();
+    return this._automatedTests;
+  }
+
+  getPlannedScenarios(): string[] {
+    if (this._plannedScenarios !== null) return this._plannedScenarios;
+    this._plannedScenarios = this.loadPlannedScenarios();
+    return this._plannedScenarios;
+  }
+
+  getActiveScenarioTitles(): Set<string> {
+    return new Set(
+      this.getAutomatedTests()
+        .filter((t) => !t.pending)
+        .map((t) => t.title.toLowerCase())
+    );
+  }
+
+  get automatedTestCount(): number {
+    return this.getAutomatedTests().filter((t) => !t.pending).length;
+  }
+
+  getAutomatedTestNames(): string[] {
+    return this.getAutomatedTests()
+      .filter((t) => !t.pending)
+      .map((t) => t.title);
+  }
+
+  getAutomatedTestFiles(): string[] {
+    return [...new Set(this.getAutomatedTests().map((t) => t.file))];
+  }
+
+  private loadAutomatedTests(): AutomatedTest[] {
+    const testsDir = ConfigParser.getInstance().getTestsDir();
+    if (!existsSync(testsDir)) return [];
+
+    const jsFiles = readdirSync(testsDir)
+      .filter((f) => f.endsWith('.js'))
+      .map((f) => path.resolve(testsDir, f));
+
+    const results: AutomatedTest[] = [];
+
+    for (const filePath of jsFiles) {
+      const parsed = this.parseTestFile(filePath);
+      if (!parsed) continue;
+      if (normalizeUrl(parsed.url) !== normalizeUrl(this.url)) continue;
+      results.push(...parsed.tests);
+    }
+
+    return results;
+  }
+
+  private parseTestFile(filePath: string): { url: string; tests: AutomatedTest[] } | null {
+    try {
+      const scanned = Reflection.scanFile(filePath);
+      if (!scanned.suites?.length) return null;
+
+      const content = readFileSync(filePath, 'utf-8');
+
+      const suiteRef = Reflection.forSuite(scanned.suites[0]);
+      const beforeHooks = suiteRef.findHook('Before');
+      if (!beforeHooks?.length) return null;
+
+      const hookBody = content.slice(beforeHooks[0].range.start, beforeHooks[0].range.end);
+      const match = hookBody.match(/I\.amOnPage\(['"]([^'"]+)['"]\)/);
+      if (!match) return null;
+
+      const lines = content.split('\n');
+      const tests = (scanned.tests || []).map((t: any) => {
+        const line = lines[t.line - 1] || '';
+        const pending = line.includes('Scenario.skip') || line.includes('Scenario.todo');
+        return { title: t.title, pending, file: filePath };
+      });
+
+      return { url: match[1], tests };
+    } catch (err: any) {
+      debugLog('Failed to parse test file %s: %s', filePath, err.message);
+      return null;
+    }
+  }
+
+  private loadPlannedScenarios(): string[] {
+    try {
+      const plansDir = ConfigParser.getInstance().getPlansDir();
+      if (!existsSync(plansDir)) return [];
+
+      const mdFiles = readdirSync(plansDir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => path.resolve(plansDir, f));
+
+      const scenarios: string[] = [];
+
+      for (const filePath of mdFiles) {
+        const plan = parsePlanFromMarkdown(filePath);
+        if (!plan.url) continue;
+        if (normalizeUrl(plan.url) !== normalizeUrl(this.url)) continue;
+        for (const test of plan.tests) {
+          scenarios.push(test.scenario);
+        }
+      }
+
+      return scenarios;
+    } catch (err: any) {
+      debugLog('Failed to load planned scenarios: %s', err.message);
+      return [];
+    }
+  }
+}
+
+interface AutomatedTest {
+  title: string;
+  pending: boolean;
+  file: string;
+}

package/src/utils/html.ts

@@ -486,18 +486,14 @@ export function htmlMinimalUISnapshot(html: string, htmlConfig?: HtmlConfig['min
       node.attrs = node.attrs.filter((attr) => {
         const { name, value } = attr;
         if (name === 'class') {
-          // Remove classes containing digits
           attr.value = value
             .split(' ')
-            // remove classes containing digits/
             .filter((className) => !/\d/.test(className))
-            // remove popular trash classes
             .filter((className) => !className.match(trashHtmlClasses))
-            // remove classes with : and __ in them
             .filter((className) => !className.match(/(:|__)/))
-            // remove tailwind utility classes
             .filter((className) => !TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(className)))
             .join(' ');
+          if (attr.value === '') return false;
         }
 
         return allowedAttrs.includes(name) || name.startsWith('data-explorbot-');

package/src/utils/rules-loader.ts

@@ -65,29 +65,47 @@ export class RulesLoader {
     return { name, approach: styles[name] };
   }
 
-  static extractStyles(agentName: string, targetDir: string): string[] {
-    const sourceDir = join(BUILT_IN_DIR, agentName, 'styles');
-    if (!existsSync(sourceDir)) throw new Error(`No built-in styles found for agent: ${agentName}`);
+  static extractRules(agentName: string, targetDir: string): string[] {
+    const sourceDir = join(BUILT_IN_DIR, agentName);
+    if (!existsSync(sourceDir)) throw new Error(`No built-in rules found for agent: ${agentName}`);
 
+    const extracted: string[] = [];
+    copyMarkdownTree(sourceDir, targetDir, '', extracted);
+    return extracted;
+  }
+}
+
+function copyMarkdownTree(sourceDir: string, targetDir: string, relative: string, extracted: string[]): void {
+  const entries = readdirSync(sourceDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+
+  let dirCreated = false;
+  const ensureTargetDir = () => {
+    if (dirCreated) return;
     mkdirSync(targetDir, { recursive: true });
+    dirCreated = true;
+  };
 
-    const files = readdirSync(sourceDir)
-      .filter((f) => f.endsWith('.md'))
-      .sort();
-    const extracted: string[] = [];
+  for (const entry of entries) {
+    const sourcePath = join(sourceDir, entry.name);
+    const targetPath = join(targetDir, entry.name);
+    const relPath = relative ? `${relative}/${entry.name}` : entry.name;
 
-    for (const file of files) {
-      const target = join(targetDir, file);
-      if (existsSync(target)) {
-        tag('info').log(`Skipping ${file} (already exists)`);
-        continue;
-      }
-      writeFileSync(target, readFileSync(join(sourceDir, file), 'utf8'));
-      extracted.push(file);
-      tag('success').log(`Extracted ${file}`);
+    if (entry.isDirectory()) {
+      copyMarkdownTree(sourcePath, targetPath, relPath, extracted);
+      continue;
     }
 
-    return extracted;
+    if (!entry.name.endsWith('.md')) continue;
+
+    if (existsSync(targetPath)) {
+      tag('info').log(`Skipping ${relPath} (already exists)`);
+      continue;
+    }
+
+    ensureTargetDir();
+    writeFileSync(targetPath, readFileSync(sourcePath, 'utf8'));
+    extracted.push(relPath);
+    tag('success').log(`Extracted ${relPath}`);
   }
 }
 

package/src/utils/test-files.ts

@@ -0,0 +1,122 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import { highlight } from 'cli-highlight';
+import * as codeceptjs from 'codeceptjs';
+import store from 'codeceptjs/lib/store';
+import stepsListener from 'codeceptjs/lib/listener/steps';
+import storeListener from 'codeceptjs/lib/listener/store';
+import figureSet from 'figures';
+import { ConfigParser } from '../config.ts';
+
+export function loadTestSuites(testsDir: string): any[] {
+  if (!existsSync(testsDir)) return [];
+
+  const jsFiles = readdirSync(testsDir)
+    .filter((f) => f.endsWith('.js'))
+    .map((f) => path.resolve(testsDir, f));
+
+  if (jsFiles.length === 0) return [];
+
+  codeceptjs.container.createMocha();
+  const mocha = codeceptjs.container.mocha();
+  mocha.files = jsFiles;
+  mocha.loadFiles();
+
+  return mocha.suite.suites || [];
+}
+
+export function printTestList(suites: any[]): void {
+  if (suites.length === 0) {
+    console.log(chalk.yellow('No test files found. Run /explore first.'));
+    return;
+  }
+
+  let totalActive = 0;
+  let totalSkipped = 0;
+  let index = 0;
+
+  for (const suite of suites) {
+    const file = path.relative(process.cwd(), suite.file || '');
+    const active = suite.tests.filter((t: any) => !t.pending).length;
+    const skipped = suite.tests.filter((t: any) => t.pending).length;
+    totalActive += active;
+    totalSkipped += skipped;
+
+    console.log(`\n${chalk.bold.cyan(suite.title)}`);
+    console.log(chalk.gray(file));
+
+    for (const test of suite.tests) {
+      const idx = chalk.dim(`${++index}.`);
+      if (test.pending) {
+        console.log(chalk.gray(`  ${idx} ${figureSet.line} ${test.title} (skipped)`));
+      } else {
+        console.log(`  ${idx} ${chalk.green(figureSet.pointer)} ${test.title}`);
+      }
+    }
+  }
+
+  console.log(`\n${chalk.bold(`${totalActive + totalSkipped}`)} scenarios (${chalk.green(`${totalActive} active`)}, ${chalk.gray(`${totalSkipped} skipped`)})`);
+}
+
+export async function dryRunTestFile(filePath: string): Promise<void> {
+  const absPath = path.resolve(filePath);
+  if (!existsSync(absPath)) {
+    console.log(chalk.yellow(`File not found: ${absPath}`));
+    return;
+  }
+
+  const config = ConfigParser.getInstance().getConfig();
+  const configPath = ConfigParser.getInstance().getConfigPath();
+  const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
+
+  const codeceptConfig = {
+    helpers: {
+      Playwright: { browser: config.playwright.browser, url: config.playwright.url },
+    },
+  };
+
+  (global as any).output_dir = path.join(projectRoot, 'output', 'states');
+  (global as any).codecept_dir = projectRoot;
+
+  codeceptjs.container.create(codeceptConfig, {});
+  await codeceptjs.recorder.start();
+  await codeceptjs.container.started(null);
+
+  store.dryRun = true;
+  (global as any).container = codeceptjs.container;
+  storeListener();
+  stepsListener();
+
+  codeceptjs.container.createMocha();
+  const mocha = codeceptjs.container.mocha();
+  mocha.reporter(class {});
+  mocha.files = [absPath];
+  mocha.loadFiles();
+
+  let currentSuite = '';
+
+  codeceptjs.event.dispatcher.on('suite.before', (suite: any) => {
+    if (suite.title && suite.title !== currentSuite) {
+      currentSuite = suite.title;
+      console.log(`\n${chalk.bold.cyan(suite.title)}`);
+      console.log(chalk.gray(path.relative(process.cwd(), suite.file || absPath)));
+    }
+  });
+
+  codeceptjs.event.dispatcher.on('test.before', (t: any) => {
+    console.log(`\n  ${chalk.green(figureSet.pointer)} ${chalk.bold(t.title)}`);
+  });
+
+  codeceptjs.event.dispatcher.on('step.start', (step: any) => {
+    const code = highlight(step.toCode(), { language: 'javascript' });
+    console.log(chalk.dim(`    ${code}`));
+  });
+
+  await new Promise<void>((resolve) => {
+    const runner = mocha.run(() => resolve());
+    runner.on('pending', (t: any) => {
+      console.log(chalk.gray(`  ${figureSet.line} ${t.title} (skipped)`));
+    });
+  });
+}