explorbot 0.0.5 → 0.1.1

package/dist/src/suite.js

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { Reflection } from '@codeceptjs/reflection';
+import { ConfigParser } from "./config.js";
+import { normalizeUrl } from "./state-manager.js";
+import { parsePlanFromMarkdown } from "./utils/test-plan-markdown.js";
+import { createDebug } from "./utils/logger.js";
+const debugLog = createDebug('explorbot:suite');
+export class Suite {
+    url;
+    _automatedTests = null;
+    _plannedScenarios = null;
+    constructor(url) {
+        this.url = url;
+    }
+    getAutomatedTests() {
+        if (this._automatedTests !== null)
+            return this._automatedTests;
+        this._automatedTests = this.loadAutomatedTests();
+        return this._automatedTests;
+    }
+    getPlannedScenarios() {
+        if (this._plannedScenarios !== null)
+            return this._plannedScenarios;
+        this._plannedScenarios = this.loadPlannedScenarios();
+        return this._plannedScenarios;
+    }
+    getActiveScenarioTitles() {
+        return new Set(this.getAutomatedTests()
+            .filter((t) => !t.pending)
+            .map((t) => t.title.toLowerCase()));
+    }
+    get automatedTestCount() {
+        return this.getAutomatedTests().filter((t) => !t.pending).length;
+    }
+    getAutomatedTestNames() {
+        return this.getAutomatedTests()
+            .filter((t) => !t.pending)
+            .map((t) => t.title);
+    }
+    getAutomatedTestFiles() {
+        return [...new Set(this.getAutomatedTests().map((t) => t.file))];
+    }
+    loadAutomatedTests() {
+        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 = [];
+        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;
+    }
+    parseTestFile(filePath) {
+        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) => {
+                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) {
+            debugLog('Failed to parse test file %s: %s', filePath, err.message);
+            return null;
+        }
+    }
+    loadPlannedScenarios() {
+        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 = [];
+            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) {
+            debugLog('Failed to load planned scenarios: %s', err.message);
+            return [];
+        }
+    }
+}

package/dist/src/utils/html.js

@@ -424,18 +424,15 @@ export function htmlMinimalUISnapshot(html, htmlConfig) {
             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/dist/src/utils/rules-loader.js

@@ -60,28 +60,44 @@ export class RulesLoader {
         const name = names[idx];
         return { name, approach: styles[name] };
     }
-    static extractStyles(agentName, targetDir) {
-        const sourceDir = join(BUILT_IN_DIR, agentName, 'styles');
+    static extractRules(agentName, targetDir) {
+        const sourceDir = join(BUILT_IN_DIR, agentName);
         if (!existsSync(sourceDir))
-            throw new Error(`No built-in styles found for agent: ${agentName}`);
-        mkdirSync(targetDir, { recursive: true });
-        const files = readdirSync(sourceDir)
-            .filter((f) => f.endsWith('.md'))
-            .sort();
+            throw new Error(`No built-in rules found for agent: ${agentName}`);
         const extracted = [];
-        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}`);
-        }
+        copyMarkdownTree(sourceDir, targetDir, '', extracted);
         return extracted;
     }
 }
+function copyMarkdownTree(sourceDir, targetDir, relative, extracted) {
+    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;
+    };
+    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;
+        if (entry.isDirectory()) {
+            copyMarkdownTree(sourcePath, targetPath, relPath, extracted);
+            continue;
+        }
+        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}`);
+    }
+}
 function loadFile(agentName, name, subdir) {
     const file = `${name}.md`;
     const segments = subdir ? [agentName, subdir, file] : [agentName, file];

package/dist/src/utils/test-files.js

@@ -0,0 +1,103 @@
+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.js";
+export function loadTestSuites(testsDir) {
+    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) {
+    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) => !t.pending).length;
+        const skipped = suite.tests.filter((t) => 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) {
+    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.output_dir = path.join(projectRoot, 'output', 'states');
+    global.codecept_dir = projectRoot;
+    codeceptjs.container.create(codeceptConfig, {});
+    await codeceptjs.recorder.start();
+    await codeceptjs.container.started(null);
+    store.dryRun = true;
+    global.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) => {
+        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) => {
+        console.log(`\n  ${chalk.green(figureSet.pointer)} ${chalk.bold(t.title)}`);
+    });
+    codeceptjs.event.dispatcher.on('step.start', (step) => {
+        const code = highlight(step.toCode(), { language: 'javascript' });
+        console.log(chalk.dim(`    ${code}`));
+    });
+    await new Promise((resolve) => {
+        const runner = mocha.run(() => resolve());
+        runner.on('pending', (t) => {
+            console.log(chalk.gray(`  ${figureSet.line} ${t.title} (skipped)`));
+        });
+    });
+}

package/dist/src/utils/web-element.js

@@ -3,6 +3,7 @@ const KEY_DISPLAY_ATTRS = ['role', 'id', 'class', 'aria-label'];
 const KEY_ATTRS = ['role', 'aria-label', 'id', 'name', 'type', 'href'];
 export class WebElement {
     tag;
+    role;
     xpath;
     clickXPath;
     attrs;
@@ -12,6 +13,7 @@ export class WebElement {
     y;
     constructor(data) {
         this.tag = data.tag;
+        this.role = data.role || data.attrs.role || '';
         this.xpath = data.xpath;
         this.clickXPath = data.clickXPath;
         this.attrs = data.attrs;
@@ -33,8 +35,7 @@ export class WebElement {
         return `(${this.x}, ${this.y})`;
     }
     get eidx() {
-        const val = this.attrs['data-explorbot-eidx'] || this.attrs.eidx;
-        return val ? Number.parseInt(val, 10) : null;
+        return this.attrs['data-explorbot-eidx'] || this.attrs.eidx || null;
     }
     get isNavigationLink() {
         if (this.tag !== 'a')
@@ -46,9 +47,10 @@ export class WebElement {
         const cls = this.attrs.class || '';
         return cls.split(/\s+/).filter((c) => c.length > 2 && !isDynamicId(c) && !isGenericClass(c));
     }
-    static fromRawData(d) {
+    static fromRawData(d, role) {
         return new WebElement({
             tag: d.tag,
+            role,
             xpath: '',
             clickXPath: buildClickableXPath({ tag: d.tag, allAttrs: d.allAttrs, text: d.text }),
             attrs: d.allAttrs,
@@ -111,7 +113,7 @@ export class WebElement {
         return { totalFound: result.totalFound, elements: result.matches.map((m) => WebElement.fromXPathMatch(m)) };
     }
 }
-function extractElementData(el) {
+export function extractElementData(el) {
     const rect = el.getBoundingClientRect();
     if (rect.width === 0 && rect.height === 0)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -66,6 +66,7 @@
     "@ai-sdk/groq": "^3.0",
     "@ai-sdk/openai": "^3.0",
     "@axe-core/playwright": "^4.11.0",
+    "@codeceptjs/reflection": "^0.5.2",
     "@inkjs/ui": "^2.0.0",
     "@langfuse/otel": "^4.5.1",
     "@openrouter/ai-sdk-provider": "^2.3.3",
@@ -77,7 +78,7 @@
     "@opentelemetry/sdk-trace-base": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.38.0",
     "@scalar/openapi-parser": "^0.25.6",
-    "@testomatio/reporter": "2.7.3",
+    "@testomatio/reporter": "^2.7.6",
     "ai": "^6.0.6",
     "axe-core": "^4.11.1",
     "bash-tool": "^1.3.15",

package/rules/rerunner/healing-approach.md

@@ -0,0 +1,19 @@
+<healing_approach>
+The failed step was NOT performed. You MUST execute a replacement action.
+Just waiting or diagnosing is NOT enough — you must perform the click/fill/press that was intended.
+
+1. FIRST: Check the page URL and ARIA — are you on the right page?
+   - If URL or ARIA shows login/error/404 page → call giveUp immediately
+2. If ARIA is empty/minimal → page may still be loading:
+   - Use xpathCheck() to detect spinners, loaders, or loading indicators on the page
+   - Use wait() to let the page load — it returns fresh ARIA automatically
+   - Then execute the replacement action with a working locator
+3. If the target element is visible in ARIA:
+   - Use click() with multiple fallback locators (ARIA, CSS, XPath)
+4. If element is NOT in ARIA but page is correct:
+   - Use xpathCheck() to search the full HTML
+   - Use research() to get a semantic UI map of the page if needed
+   - If found → click it
+   - If not → bash to check console logs → giveUp
+5. Call done() with the command that replaced the failed step
+</healing_approach>

package/src/action.ts

@@ -116,14 +116,16 @@ class Action {
 
       try {
         const page = this.playwrightHelper.page;
-        const serializedSnapshot = await page.locator('body').ariaSnapshot();
+        ariaSnapshot = await page.locator('body').ariaSnapshot();
+      } catch (err) {
+        debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
+      }
+
+      if (ariaSnapshot) {
         const ariaFileName = `${stateHash}_${timestamp}.aria.yaml`;
         const ariaPath = join(statesDir, ariaFileName);
-        fs.writeFileSync(ariaPath, serializedSnapshot, 'utf8');
-        ariaSnapshot = serializedSnapshot;
+        fs.writeFileSync(ariaPath, ariaSnapshot, 'utf8');
         ariaSnapshotFile = ariaFileName;
-      } catch (err) {
-        debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
       }
 
       const result = new ActionResult({
@@ -137,7 +139,7 @@ class Action {
         iframeSnapshots,
         ariaSnapshot,
         ariaSnapshotFile,
-        iframeURL: frame?.url?.() || undefined,
+        iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
       });
       this.stateManager.updateState(result);
       return result;

package/src/ai/historian.ts

@@ -1,9 +1,10 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.ts';
 import { ConfigParser } from '../config.ts';
+import { KnowledgeTracker } from '../knowledge-tracker.ts';
 import { ExperienceTracker, type SessionExperienceEntry, type SessionStep } from '../experience-tracker.ts';
 import { type Reporter, type ReporterStep } from '../reporter.ts';
 import type { StateManager } from '../state-manager.ts';
@@ -397,6 +398,7 @@ export class Historian {
     if (startUrl) {
       lines.push('Before(({ I }) => {');
       lines.push(`  I.amOnPage('${this.escapeString(startUrl)}');`);
+      lines.push(...this.getKnowledgeLines(startUrl));
       lines.push('});');
       lines.push('');
     }
@@ -425,8 +427,7 @@ export class Historian {
       lines.push('');
     }
 
-    const outputDir = ConfigParser.getInstance().getOutputDir();
-    const testsDir = join(outputDir, 'tests');
+    const testsDir = ConfigParser.getInstance().getTestsDir();
     mkdirSync(testsDir, { recursive: true });
 
     const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
@@ -437,6 +438,18 @@ export class Historian {
     return filePath;
   }
 
+  rewriteScenarioInFile(filePath: string, healedSteps: Array<{ test: string; original: string; healed: string }>): void {
+    let content = readFileSync(filePath, 'utf-8');
+
+    for (const step of healedSteps) {
+      if (!content.includes(step.original)) continue;
+      content = content.replace(step.original, step.healed);
+    }
+
+    writeFileSync(filePath, content);
+    tag('substep').log(`Updated test file with healed steps: ${filePath}`);
+  }
+
   private getExecutionLabel(exec: ToolExecution, fallback?: string): string {
     return exec.input?.explanation || exec.input?.assertion || exec.input?.note || fallback || '';
   }
@@ -445,6 +458,27 @@ export class Historian {
     return str.replace(/'/g, "\\'").replace(/\n/g, ' ');
   }
 
+  private getKnowledgeLines(url: string, indent = '  '): string[] {
+    const knowledgeTracker = new KnowledgeTracker();
+    const state = new ActionResult({ url });
+    const { wait, waitForElement, code } = knowledgeTracker.getStateParameters(state, ['wait', 'waitForElement', 'code']);
+
+    const lines: string[] = [];
+    if (wait !== undefined) {
+      lines.push(`${indent}I.wait(${wait});`);
+    }
+    if (waitForElement) {
+      lines.push(`${indent}I.waitForElement(${JSON.stringify(waitForElement)});`);
+    }
+    if (code) {
+      for (const codeLine of code.split('\n')) {
+        const trimmed = codeLine.trim();
+        if (trimmed) lines.push(`${indent}${trimmed}`);
+      }
+    }
+    return lines;
+  }
+
   private stripComments(code: string): string {
     return code
       .split('\n')

package/src/ai/navigator.ts

@@ -40,6 +40,18 @@ class Navigator implements Agent {
     You are given the web page and a message from user.
     You need to resolve the state of the page based on the message.
   </task>
+
+  ${locatorRule}
+
+  <constraints>
+    NEVER navigate away from the base URL domain. Stay on the same origin at all times.
+    NEVER attempt to rewrite, replace, mock, or spoof the URL via JavaScript, history API, location assignment, or any client-side trick.
+    NEVER use executeScript, executeAsyncScript, or any JS evaluation to change the URL, bypass redirects, or fake the page state.
+    If the target URL redirects to an authentication/login page, DO NOT try to force the original URL. Instead:
+      1. Look for credentials in the provided knowledge/hint context and perform a real login through the form.
+      2. If no credentials are available, ask the user for credentials or ask the user to log in manually.
+    A redirect to /login, /sign_in, /auth, or similar is a signal that authentication is required — treat it as such, never as an obstacle to bypass.
+  </constraints>
   `;
   private freeSailSystemPrompt = dedent`
   <role>
@@ -168,6 +180,14 @@ class Navigator implements Agent {
         ${message}
       </message>
 
+      <page>
+        ${actionResult.toAiContext()}
+
+        <page_html>
+        ${await actionResult.combinedHtml()}
+        </page_html>
+      </page>
+
       <task>
         Identify the actual request of the user.
         Identify what is expected by user.
@@ -178,25 +198,13 @@ class Navigator implements Agent {
         Try various ways to achieve the result
       </task>
 
-
-      <page>
-        ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.simplifiedHtml()}
-        </page_html>
-      </page>
-
-
-      ${knowledge}
-
       ${actionRule}
 
-      ${experience}
+      ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
 
-      ${locatorRule}
+      ${experience}
 
-      ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
+      ${knowledge}
     `;
 
     const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
@@ -234,7 +242,7 @@ class Navigator implements Agent {
               Previous solutions did not work. Here is the full HTML context:
 
               <page_html>
-              ${await actionResult.simplifiedHtml()}
+              ${await actionResult.combinedHtml()}
               </page_html>
 
               Please suggest new solutions based on this additional context.
@@ -265,6 +273,7 @@ class Navigator implements Agent {
 
         if (resolved) {
           tag('success').log('Navigation resolved successfully');
+          await this.experienceTracker.saveSuccessfulResolution(actionResult, message, codeBlock);
           stop();
           return;
         }
@@ -479,6 +488,14 @@ class Navigator implements Agent {
         ${message}
       </message>
 
+      <page>
+        ${actionResult.toAiContext()}
+
+        <page_html>
+        ${await actionResult.combinedHtml()}
+        </page_html>
+      </page>
+
       <task>
         Identify what assertion the user wants to verify on the page.
         Propose different CodeceptJS assertion code blocks to verify the expected state.
@@ -492,21 +509,11 @@ class Navigator implements Agent {
         Do not generate assertions that would pass even if the specific claim is false.
       </task>
 
-      <page>
-        ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.simplifiedHtml()}
-        </page_html>
-      </page>
-
-      ${knowledge}
-
       ${RulesLoader.loadRules('navigator', ['verification-actions'], actionResult.url || '')}
 
-      ${locatorRule}
-
       ${experience}
+
+      ${knowledge}
     `;
 
     debugLog('Sending verification prompt to AI provider');