explorbot 0.3.2 → 0.3.4

package/src/ai/researcher/deep-analysis.ts

@@ -9,6 +9,7 @@ import { diffAriaSnapshots } from '../../utils/aria.ts';
 import { extractCodeBlocks } from '../../utils/code-extractor.ts';
 import { tag } from '../../utils/logger.js';
 import { mdq } from '../../utils/markdown-query.ts';
+import { truncate } from '../../utils/strings.ts';
 import type { Provider } from '../provider.js';
 import { getCachedResearch, getPreviousResearch, saveResearch } from './cache.ts';
 import { type Constructor, debugLog } from './mixin.ts';
@@ -16,6 +17,7 @@ import { type ResearchElement, parseResearchSections } from './parser.ts';
 import type { ResearchResult } from './research-result.ts';
 
 const DEFAULT_MAX_EXPANDABLE_CLICKS = 10;
+const MAX_HTML_DIFF_CHARS = 20_000;
 
 export function WithDeepAnalysis<T extends Constructor>(Base: T) {
   return class extends Base {
@@ -486,6 +488,9 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
         `;
       }
 
+      const cleanedParts = await diff.cleanedHtmlParts();
+      const htmlChanges = truncate(cleanedParts.map((p) => `[Container: ${p.container}]\n${p.subtree}`).join('\n\n'), MAX_HTML_DIFF_CHARS);
+
       const prompt = dedent`
         ${intro}
         Analyze the changes and produce a UI map section.
@@ -494,7 +499,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
         ${diff.ariaChanged || 'none'}
 
         HTML changes:
-        ${diff.htmlParts.map((p) => `[Container: ${p.container}]\n${p.subtree}`).join('\n\n') || 'none'}
+        ${htmlChanges || 'none'}
         ${alreadyHint}
 
         Respond with a SINGLE section in this format:

package/src/ai/researcher/sections.ts

@@ -111,7 +111,6 @@ export function WithSections<T extends Constructor>(Base: T) {
         - Do not copy global toolbar, navigation, list, or detail elements into this section unless they are descendants of this section container.
         - Every element with eidx inside this section's container MUST appear in the table.
         - Every row needs CSS; ARIA may be "-" for icon-only buttons.
-        - ARIA locator JSON uses keys "role" and "text" (NOT "name").
         - Elements marked data-explorbot-hit="covered" or "offscreen" are not directly actionable; describe the covering or focused UI first.
         - In split-pane pages, entity detail panels are active detail context; include close/back/pin controls in the detail panel section when present.
         </rules>

package/src/ai/researcher.ts

@@ -403,7 +403,6 @@ export class Researcher extends ResearcherBase implements Agent {
       - If an element has data-explorbot-hit="covered" or "offscreen", do not present it as directly actionable. Prefer the overlay, drawer, dialog, or focused section covering it, and mention what must be dismissed or revealed first.
       - Every element with an eidx attribute MUST appear in exactly one matching UI map section — describe icon-only buttons by their visual role.
       - Every UI map row needs a CSS selector; ARIA may be "-" for icon-only buttons, CSS must never be "-".
-      - ARIA locator JSON uses keys "role" and "text" (NOT "name").
       - Mark elements with likely hover interactions (title, aria-describedby, menu items with submenus) as "(hover)".
       </rules>
 

package/src/ai/rules.ts

@@ -71,7 +71,6 @@ const locatorStrategyRule = dedent`
 
   <bad_aria_locator_example>
   { "role": "button", "text": "" }  // INVALID - empty text is useless, use "-" instead
-  { "role": "button", "name": "Save" }  // WRONG key - use "text", not "name"
   </bad_aria_locator_example>
 
   NEVER include \`eidx\` attribute in any locator (ARIA, CSS, XPath). It is an internal annotation.

package/src/ai/tester.ts

@@ -65,6 +65,12 @@ export class Tester extends TaskAgent implements Agent {
   private stalledIterations = 0;
   private readonly MAX_STALLED_ITERATIONS = 3;
 
+  private skipResearch = (err: Error): string => {
+    if (err.name === 'AbortError') throw err;
+    tag('warning').log(`Research skipped: ${err.message}`);
+    return '';
+  };
+
   constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any) {
     super(deps);
     this.requestStore = deps.requestStore;
@@ -581,12 +587,7 @@ export class Tester extends TaskAgent implements Agent {
       const alreadySeenUiMap = this.seenUiMapUrls.has(currentUrl);
       let research = '';
       if (!alreadySeenUiMap) {
-        try {
-          research = await this.researcher.research(currentState);
-        } catch (err) {
-          if (!(err instanceof ErrorPageError)) throw err;
-          tag('warning').log(`Research skipped: ${err.message}`);
-        }
+        research = await this.researcher.research(currentState).catch(this.skipResearch);
       }
       this.pageStateHash = currentStateHash;
       this.pageActionResult = currentState;
@@ -627,7 +628,7 @@ export class Tester extends TaskAgent implements Agent {
     }
 
     if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
-      const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash);
+      const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash).catch(this.skipResearch);
       if (overlaySection) {
         context += dedent`
 

package/src/ai/tools.ts

@@ -1,6 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
+import type { ExecutedStep } from '../action.ts';
 import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
 import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
@@ -411,7 +412,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
             const message = errorText(action.lastError);
             await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
-            let formSuggestion = 'Look into error message and identify which commands passed and which failed. Continue execution using step-by-step approach using click() and form() tools.';
+            let formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
             if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
               const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
               if (disambiguated) {
@@ -421,10 +422,11 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
 
             return failedToolResult(
               'form',
-              `Form execution FAILED! ${message}`,
+              `Form execution FAILED! ${message}\n${formatExecutedSteps(action.executedSteps, codeLines.length)}`,
               {
                 ...toolResult,
                 code: codeBlock,
+                attempts: action.executedSteps,
                 suggestion: formSuggestion,
               },
               action.lastError
@@ -446,6 +448,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
               ...toolResult,
               message: `Form completed successfully with ${lines.length} commands.`,
               commandsExecuted: lines.length,
+              attempts: action.executedSteps,
               code: codeBlock,
               suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
             },
@@ -806,21 +809,26 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
           const actionResult = ActionResult.fromState(currentState);
           const experience = renderExperienceRecipes(explorer.activeTest?.getAppliedExperience(actionResult) ?? []);
           const success = await navigator.resolveState(instruction, actionResult, { experience });
+          const attempts = navigator.executedSteps;
+          let stepReport = '';
+          if (attempts.length) stepReport = `\n${formatExecutedSteps(attempts)}`;
 
           const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, instruction);
 
           if (success) {
             return successToolResult('interact', {
               ...toolResult,
-              message: `Successfully executed: ${instruction}`,
+              message: `Successfully executed: ${instruction}${stepReport}`,
+              attempts,
             });
           }
 
           let reason = '';
           if (navigator.lastFailureReason) reason = `: ${navigator.lastFailureReason}`;
 
-          return failedToolResult('interact', `Failed to execute: ${instruction}${reason}`, {
+          return failedToolResult('interact', `Failed to execute: ${instruction}${reason}${stepReport}`, {
             ...toolResult,
+            attempts,
             suggestion: 'The action could not be completed. Try a different instruction or use more specific element descriptions.',
           });
         } catch (error) {
@@ -1232,6 +1240,14 @@ export function hasFailedRequest(pageDiff: PageDiff): boolean {
   return (pageDiff.requests ?? []).some((request) => request.status >= 400);
 }
 
+export function formatExecutedSteps(steps: ExecutedStep[], requestedCount = steps.length): string {
+  if (!steps.length) return `No command ran of ${requestedCount} requested.`;
+  const lines = steps.map((step) => `  ${step.success ? 'OK' : 'FAILED'} ${step.command}`);
+  const notRun = requestedCount - steps.length;
+  if (notRun > 0) lines.push(`  NOT RUN ${notRun} more`);
+  return lines.join('\n');
+}
+
 function hasObservablePageChange(data?: Record<string, any>): boolean {
   if (!data?.pageDiff) return false;
   if (data.pageDiff.urlChanged === true) return true;

package/src/commands/init-command.ts

@@ -1,16 +1,18 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
-import dedent from 'dedent';
 import { ConfigParser, PROVIDERS } from '../config.ts';
 import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from '../global-config.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { log, tag } from '../utils/logger.js';
 import { relativeToCwd } from '../utils/next-steps.ts';
 
-function defaultConfigTemplate(): string {
+function defaultConfigTemplate(provider: string, esm: boolean): string {
+  let moduleExport = 'module.exports = config;';
+  if (esm) moduleExport = 'export default config;';
+
   return `// 'provider/model-id' uses a bundled provider.
-// It is also possible to import provider as a module from Vercel AI SDK.  
+// It is also possible to import provider as a module from Vercel AI SDK.
 // https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 
 const config = {
@@ -20,7 +22,7 @@ const config = {
   },
 
   ai: {
-${modelLines('openrouter')}
+${modelLines(provider)}
   },
 
   reporter: {
@@ -33,17 +35,18 @@ ${modelLines('openrouter')}
   },
 };
 
-export default config;
+${moduleExport}
 `;
 }
 
-const DEFAULT_ENV_TEMPLATE = dedent`
-# AI provider API keys
-OPENROUTER_API_KEY=
+function envTemplate(provider: string): string {
+  const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
+    if (name === provider) return `${envKey}=`;
+    return `# ${envKey}=`;
+  });
 
-# OPENAI_API_KEY=
-# ANTHROPIC_API_KEY=
-# GROQ_API_KEY=
+  return `# AI provider API keys
+${keyLines.join('\n')}
 
 # Langfuse Tracing
 LANGFUSE_SECRET_KEY=
@@ -51,11 +54,12 @@ LANGFUSE_PUBLIC_KEY=
 LANGFUSE_BASE_URL=
 
 # Testomat.io API key to publish run results
-TESTOMATIO=
-`;
+TESTOMATIO=`;
+}
 
 export async function runInit(options: InitCommandOptions): Promise<void> {
-  if (options.global || options.provider) {
+  const localRequested = !!(options.configPath || options.path);
+  if (options.global || (options.provider && !localRequested)) {
     await runGlobalInit(options);
     return;
   }
@@ -66,7 +70,12 @@ export async function runInit(options: InitCommandOptions): Promise<void> {
   }
 
   const choice = await renderInitWizard('choose');
-  if (choice === 'local') runInitCommand(options);
+  if (choice !== 'local') return;
+
+  const provider = await renderLocalProviderWizard();
+  if (!provider) return;
+
+  runInitCommand({ ...options, provider });
 }
 
 export function writeGlobalConfig(provider: string, apiKey?: string): void {
@@ -97,7 +106,7 @@ export function writeGlobalConfig(provider: string, apiKey?: string): void {
 }
 
 export function runInitCommand(options: InitCommandOptions): void {
-  const configPath = options.configPath ?? './explorbot.config.js';
+  const provider = options.provider || 'openrouter';
   const force = options.force ?? false;
   const customPath = options.path;
   const originalCwd = process.cwd();
@@ -112,12 +121,15 @@ export function runInitCommand(options: InitCommandOptions): void {
     log(`Working in directory: ${relativeToCwd(dir)}`);
   }
 
+  const configName = 'explorbot.config.js';
+  const configPath = options.configPath ?? `./${configName}`;
+
   try {
     let outPath = resolve(configPath);
     if (existsSync(outPath) && statSync(outPath).isDirectory()) {
-      outPath = join(outPath, 'explorbot.config.js');
+      outPath = join(outPath, configName);
     } else if (!extname(outPath)) {
-      outPath = join(outPath, 'explorbot.config.js');
+      outPath = join(outPath, configName);
     }
 
     const dir = dirname(outPath);
@@ -132,24 +144,30 @@ export function runInitCommand(options: InitCommandOptions): void {
       process.exit(1);
     }
 
-    writeFileSync(outPath, defaultConfigTemplate(), 'utf8');
+    const esm = extname(outPath) !== '.js' || isModuleProject(dirname(outPath));
+    writeFileSync(outPath, defaultConfigTemplate(provider, esm), 'utf8');
     log(`Created config file: ${relativeToCwd(outPath)}`);
 
     const envPath = resolve(process.cwd(), '.env');
     if (!existsSync(envPath)) {
-      writeFileSync(envPath, `${DEFAULT_ENV_TEMPLATE}\n`, 'utf8');
+      writeFileSync(envPath, `${envTemplate(provider)}\n`, 'utf8');
       log(`Created env file: ${relativeToCwd(envPath)}`);
     } else {
       log(`Env file already exists: ${relativeToCwd(envPath)}`);
     }
 
+    const missing = missingRoles(provider);
+    if (missing.length) {
+      tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
+    }
+
     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(chalk.yellow(`${getCliName()} learn * 'to aurhorize use these credentials: admin@example.com / secret123'`));
+    tag('substep').log(chalk.yellow(`${getCliName()} learn * 'to authorize use these credentials: admin@example.com / secret123'`));
     tag('substep').log('You can use ${env.LOGIN} and ${env.PASSWORD} to reference environment variables.');
 
     log('5. Launch application on a relative URL');
@@ -213,6 +231,28 @@ async function renderInitWizard(mode: 'choose' | 'global'): Promise<'local' | 'g
   });
 }
 
+async function renderLocalProviderWizard(): Promise<string | null> {
+  const [{ render }, React, InitWizard] = await Promise.all([import('ink'), import('react'), import('../components/InitWizard.js').then((m) => m.default)]);
+
+  return new Promise((resolve) => {
+    const finish = (provider: string | null) => {
+      unmount();
+      resolve(provider);
+    };
+    const { unmount } = render(
+      React.createElement(InitWizard, {
+        mode: 'local',
+        globalConfigExists: !!findGlobalConfig(),
+        onLocal: () => finish(null),
+        onComplete: () => finish(null),
+        onCancel: () => finish(null),
+        onLocalProvider: (provider: string) => finish(provider),
+      }),
+      { exitOnCtrlC: false, patchConsole: false }
+    );
+  });
+}
+
 function modelLines(provider: string): string {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
   const roles: Array<[ModelRoleName, string]> = [
@@ -245,10 +285,29 @@ ${modelLines(provider)}
   },
 };
 
-export default config;
+module.exports = config;
 `;
 }
 
+function isModuleProject(configDir: string): boolean {
+  let currentDir = resolve(configDir);
+
+  while (true) {
+    const packagePath = join(currentDir, 'package.json');
+    if (existsSync(packagePath)) {
+      try {
+        return JSON.parse(readFileSync(packagePath, 'utf8')).type === 'module';
+      } catch {
+        return false;
+      }
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) return false;
+    currentDir = parentDir;
+  }
+}
+
 function missingRoles(provider: string): string[] {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
   return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);

package/src/components/InitWizard.tsx

@@ -10,14 +10,15 @@ import InputReadline from './InputReadline.js';
 const PROVIDER_NAMES = Object.keys(PROVIDERS);
 
 interface InitWizardProps {
-  mode: 'choose' | 'global';
+  mode: 'choose' | 'global' | 'local';
   globalConfigExists: boolean;
   onLocal: () => void;
   onComplete: () => void;
   onCancel: () => void;
+  onLocalProvider?: (provider: string) => void;
 }
 
-const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLocal, onComplete, onCancel }) => {
+const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, onLocalProvider }) => {
   const [step, setStep] = useState<'target' | 'provider' | 'key' | 'validate'>(mode === 'choose' ? 'target' : 'provider');
   const [targetIndex, setTargetIndex] = useState(0);
   const [providerIndex, setProviderIndex] = useState(0);
@@ -78,7 +79,10 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
     if (step === 'provider') {
       if (key.upArrow) setProviderIndex((index) => Math.max(0, index - 1));
       if (key.downArrow) setProviderIndex((index) => Math.min(PROVIDER_NAMES.length - 1, index + 1));
-      if (key.return) setStep('key');
+      if (key.return) {
+        if (mode === 'local') onLocalProvider?.(provider);
+        else setStep('key');
+      }
       return;
     }
 
@@ -151,7 +155,7 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
 
       <Box marginTop={1}>
         <Text dimColor>
-          Config goes to {globalDir()} | {step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm'} | Ctrl+C: exit
+          Config goes to {mode === 'local' ? 'the current directory' : globalDir()} | {step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm'} | Ctrl+C: exit
         </Text>
       </Box>
     </Box>

package/src/explorer.ts

@@ -255,6 +255,7 @@ class Explorer {
     const projectRoot = configParser.getProjectRoot();
     (global as any).output_dir = configParser.getStatesDir();
     (global as any).codecept_dir = projectRoot;
+    (global as any).codeceptjs = codeceptjs;
 
     configParser.validateConfig(this.config);
 

package/src/knowledge-tracker.ts

@@ -95,7 +95,7 @@ export class KnowledgeTracker {
     return this.applicationSpec?.renderFor(state) || '';
   }
 
-  addKnowledge(urlPattern: string, description: string): { filename: string; filePath: string; isNewFile: boolean } {
+  addKnowledge(urlPattern: string, description: string, opts?: { replace?: boolean }): { filename: string; filePath: string; isNewFile: boolean } {
     const configParser = ConfigParser.getInstance();
     const configPath = configParser.getConfigPath();
 
@@ -130,10 +130,10 @@ export class KnowledgeTracker {
 
       // Append new knowledge with separator
       let newContent;
-      if (existingDescription) {
-        newContent = `${existingDescription}\n\n---\n\n${description}`;
-      } else {
+      if (opts?.replace || !existingDescription) {
         newContent = description;
+      } else {
+        newContent = `${existingDescription}\n\n---\n\n${description}`;
       }
 
       const fileContent = matter.stringify(newContent, frontmatter);

package/src/utils/aria.ts

@@ -586,7 +586,7 @@ export function parseAriaLocator(ariaStr: string): { role: string; text: string
   const trimmed = ariaStr.trim();
   if (trimmed === '-' || trimmed === '' || trimmed === '"-"') return null;
 
-  const match = trimmed.match(/\{\s*["']?role["']?\s*:\s*['"]([^'"]+)['"]\s*,\s*["']?text["']?\s*:\s*['"]([^'"]*)['"]\s*\}/);
+  const match = trimmed.match(/\{\s*["']?role["']?\s*:\s*['"]([^'"]+)['"]\s*,\s*["']?(?:text|name)["']?\s*:\s*['"]([^'"]*)['"]\s*\}/);
   if (!match) return null;
 
   return { role: match[1], text: match[2] };