explorbot 0.5.2 → 0.5.4

package/src/ai/rerunner.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { relative, resolve } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
 import { tool } from 'ai';
 import { createBashTool } from 'bash-tool';
 import chalk from 'chalk';
@@ -19,6 +19,7 @@ import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { isInternalStep } from '../utils/step-analyzer.ts';
+import { ensureCodeceptResolvable } from '../utils/test-files.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
@@ -135,6 +136,7 @@ export class Rerunner extends TaskAgent implements Agent {
       codeceptjs.container.createMocha();
       const mocha = codeceptjs.container.mocha();
       mocha.reporter(class {});
+      ensureCodeceptResolvable(dirname(absPath));
       mocha.files = [absPath];
       mocha.loadFiles();
 

package/src/ai/researcher.ts

@@ -103,8 +103,8 @@ export class Researcher extends ResearcherBase implements Agent {
     `;
   }
 
-  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; _retriesLeft?: number } = {}): Promise<string> {
-    const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
+  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; light?: boolean; _retriesLeft?: number } = {}): Promise<string> {
+    const { screenshot = false, force = false, deep = false, data = false, fix = true, light = false } = opts;
     const maxRetries = this.settings.retries ?? 2;
     let retriesLeft = opts._retriesLeft ?? maxRetries;
     this.actionResult = ActionResult.fromState(state);
@@ -133,6 +133,7 @@ export class Researcher extends ResearcherBase implements Agent {
     return Observability.run(sessionName, { tags: ['researcher'], sessionId: stateHash }, async () => {
       const displayUrl = state.fullUrl || state.url;
       tag('info').log(`Researching ${displayUrl} to understand the context...`);
+      if (light) tag('info').log('Light research: single pass, locator verification skipped');
       setActivity(`${this.emoji} Researching...`, 'action');
 
       await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
@@ -171,7 +172,7 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       const isOnCurrentState = this.actionResult!.getStateHash() === this.stateManager.getCurrentState()?.hash;
-      this.hasScreenshotToAnalyze = screenshot && this.provider.hasVision() && isOnCurrentState;
+      this.hasScreenshotToAnalyze = !light && screenshot && this.provider.hasVision() && isOnCurrentState;
 
       const conversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
 
@@ -205,13 +206,13 @@ export class Researcher extends ResearcherBase implements Agent {
       result.parseLocators();
       debugLog(`Extracted ${result.locators.length} locators from research`);
 
-      if (!interrupted() && result.locators.length === 0 && retriesLeft > 0) {
+      if (!light && !interrupted() && result.locators.length === 0 && retriesLeft > 0) {
         tag('warning').log(`No locators parsed, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
         await new Promise((r) => setTimeout(r, 1000));
         return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 } as any);
       }
 
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         const brokenContainers = await this.resolveContainers(result);
         const containerCount = result.containers.length;
         if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
@@ -232,7 +233,7 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       // Stage 3: Fix broken sections via AI conversation continuation
-      if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
+      if (!light && !interrupted() && fix && result.locators.some((l) => l.valid === false)) {
         await this.fixBrokenSections(result, activeConversation);
       }
 
@@ -273,12 +274,12 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       // Stage 5: Backfill broken elements
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         await this.backfillCoordinates(result);
         await this.backfillBrokenLocators(result);
       }
 
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         await this.detectPagination(result);
       }
 
@@ -309,7 +310,7 @@ export class Researcher extends ResearcherBase implements Agent {
       result.cleanup();
 
       let researchFile: string | null = null;
-      if (stateHash) {
+      if (stateHash && !light) {
         researchFile = saveResearch(researchState, result.text, combinedHtml);
       }
 

package/src/ai/rules.ts

@@ -237,7 +237,7 @@ export const unexpectedPopupRule = dedent`
   If a modal/popup appeared that you didn't expect, dismiss it first before continuing with original task.
   If elements become hidden or unclickable (timeout errors on visible elements), a dialog or overlay may have appeared on top.
   If a click error mentions "intercepts pointer events", another element is covering the target — dismiss it first.
-  If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
+  If buttons are disabled unexpectedly, trust any explanation the app gives (tooltip, hint text) over your own guess; otherwise check for a blocking popup or empty required fields.
 
   Dismiss strategy (try in order):
   1. I.pressKey('Escape') — press Escape to dismiss

package/src/ai/tester.ts

@@ -752,6 +752,16 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   getSystemMessage(): string {
+    let judgeRule = '';
+    if (this.agentTools?.judge) {
+      judgeRule = dedent`
+        <judge_rule>
+        For a quick judgement about the current page (did the last action already take effect, which element the scenario means), ask judge() before see().
+        Keep see() for what only a screenshot shows.
+        </judge_rule>
+      `;
+    }
+
     return dedent`
     <role>
     You are a senior test automation engineer with expertise in CodeceptJS and exploratory testing.
@@ -851,6 +861,8 @@ export class Tester extends TaskAgent implements Agent {
 
     ${capabilityGroundingRule}
 
+    ${judgeRule}
+
     ${dataProtectionRules}
 
     ${this.provider.getSystemPromptForAgent('tester', this.stateManager.getCurrentState()?.url) || ''}

package/src/ai/tools.ts

@@ -112,7 +112,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
         let ambiguityError: Error | null = null;
 
         for (let i = 0; i < commands.length; i++) {
-          const command = transformContainsCommand(commands[i]);
+          let command = transformContainsCommand(commands[i]);
           let success = await action.attempt(command, explanation);
 
           const attempt: { command: string; success: boolean; error?: string } = { command, success };
@@ -125,10 +125,14 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
               const labels = (await extractWebElements(ambiguityError))?.map((el) => el.label) || [];
               const index = await judge.pick(PICK_ELEMENT_QUESTION, labels, { intent: explanation, task: task.description });
               if (index) success = await action.attemptExactElementIndex(command, index, explanation);
+              if (success) command = action.executedSteps.map((step) => step.command).join('\n') || command;
             }
           }
 
           if (success) {
+            attempt.command = command;
+            attempt.success = true;
+            attempt.error = undefined;
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
 
             if (!hasObservablePageChange(toolResult)) {
@@ -156,17 +160,22 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
         const suggestion = clickFailureSuggestion(attempts);
+        const data: Record<string, any> = { ...toolResult, attempts, suggestion };
+        const clickError = ambiguityError || action.lastError;
+
+        for (const disabled of attempts.filter((a) => a.error?.includes('not enabled'))) {
+          const hoverCommand = disabled.command.replace('I.click(', 'I.moveCursorTo(');
+          const beforeHover = ActionResult.fromState(stateManager.getCurrentState()!);
+          if (!(await action.attempt(hoverCommand, 'Hover the disabled element to reveal why it is disabled'))) continue;
+          const hoverResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(beforeHover, hoverCommand);
+          const shown = hoverResult.pageDiff?.messages;
+          if (!shown?.length) break;
+          data.disabledReason = shown;
+          data.suggestion = `Element is DISABLED. Hovering it showed: "${shown.join(' | ')}". That is why — act on it or report it, do not guess another cause.`;
+          break;
+        }
 
-        return failedToolResult(
-          'click',
-          'All click commands failed',
-          {
-            ...toolResult,
-            attempts,
-            suggestion,
-          },
-          ambiguityError || action.lastError
-        );
+        return failedToolResult('click', 'All click commands failed', data, clickError);
       },
     }),
 
@@ -1356,7 +1365,7 @@ export function clickFailureSuggestion(attempts: Array<{ error?: string }>): str
   const errors = attempts.map((a) => a.error || '');
 
   if (errors.some((e) => e.includes('not enabled'))) {
-    return 'Element exists but is DISABLED — clicking it again cannot work. A precondition is unmet: a required field is empty, nothing is selected, or a dialog is blocking. Satisfy it, then retry.';
+    return 'Element exists but is DISABLED — clicking it again cannot work. Find the precondition the page shows as unmet, then retry.';
   }
 
   if (errors.some((e) => e.includes('intercepts pointer events'))) {

package/src/config.ts

@@ -327,6 +327,7 @@ export class ConfigParser {
   private site: SiteRecord | null = null;
   private siteStartPath = '/';
   private siteConfigPath: string | null = null;
+  private runBase: RunBase | null = null;
 
   private constructor() {}
 
@@ -368,6 +369,7 @@ export class ConfigParser {
     if (this.config && !options?.config && !options?.path && this.runtimeTarget === target) {
       return this.config;
     }
+    this.runBase = parseRunBase(options?.baseUrl);
 
     // Store the initial working directory for reference
     if (!process.env.INITIAL_CWD) {
@@ -404,14 +406,21 @@ export class ConfigParser {
         let envUrl = options?.baseUrl;
         if (!envUrl && target?.startsWith('http')) envUrl = target;
 
-        const outputRoot = resolveOutputRoot(process.env.EXPLORBOT_URL || envUrl);
+        if (options?.baseUrl) {
+          const envOrigin = URL.parse(process.env.EXPLORBOT_URL || '')?.origin;
+          const baseOrigin = URL.parse(options.baseUrl)?.origin;
+          if (envOrigin && envOrigin !== baseOrigin) {
+            tag('warning').log(`--base-url ${baseOrigin} selects the site for this run — EXPLORBOT_URL ${envOrigin} is ignored`);
+          }
+        }
+        const outputRoot = resolveOutputRoot(options?.baseUrl || process.env.EXPLORBOT_URL || envUrl);
         loadedConfig = await this.buildEnvConfig(envUrl, outputRoot);
         sourcePath = join(outputRoot, 'explorbot.config.js');
 
         log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
       }
 
-      let config = this.resolveConfig(loadedConfig as ExplorbotConfig, options);
+      let config = this.resolveConfig(loadedConfig as ExplorbotConfig);
       await resolveConfigModels(config.ai);
       this.site = null;
       this.siteConfigPath = null;
@@ -484,6 +493,22 @@ export class ConfigParser {
     return this.siteConfigPath;
   }
 
+  public applyBasePath(target: string): string {
+    const base = this.runBase?.path;
+    if (!base) return target;
+    if (!target.startsWith('/')) return target;
+    if (target === base || target.startsWith(`${base}/`) || target.startsWith(`${base}?`)) return target;
+    return `${base}${target}`;
+  }
+
+  public getBaseQuery(): string {
+    return this.runBase?.query || '';
+  }
+
+  public getBasePath(): string {
+    return this.runBase?.path || '';
+  }
+
   public resolveTargetPath(target?: string): string {
     if (!this.site) {
       const configured = this.config?.playwright?.url || this.config?.web?.url;
@@ -492,12 +517,13 @@ export class ConfigParser {
       if (targetOrigin && baseOrigin && targetOrigin !== baseOrigin) {
         tag('warning').log(`Exploring ${targetOrigin} but base URL is ${baseOrigin}. Relative navigation resolves against the base URL — set web.url to ${targetOrigin} to avoid it.`);
       }
-      return target || '/';
+      return this.applyBasePath(target || '/');
     }
     if (!target) return this.siteStartPath;
 
     const resolved = resolveSiteTarget(target, this.site.url);
     if (resolved.baseUrl !== this.site.url) return target;
+    if (target.startsWith('/')) return this.applyBasePath(resolved.path);
     return resolved.path;
   }
 
@@ -524,6 +550,7 @@ export class ConfigParser {
       ConfigParser.instance.site = null;
       ConfigParser.instance.siteStartPath = '/';
       ConfigParser.instance.siteConfigPath = null;
+      ConfigParser.instance.runBase = null;
     }
   }
 
@@ -694,15 +721,15 @@ export class ConfigParser {
     }
   }
 
-  private resolveConfig(config: ExplorbotConfig, options?: { baseUrl?: string }): ExplorbotConfig {
+  private resolveConfig(config: ExplorbotConfig): ExplorbotConfig {
     if (config.web?.url && !config.playwright?.url) {
       config.playwright = config.playwright || { browser: 'chromium', url: '' };
       config.playwright.url = config.web.url;
     }
 
-    if (options?.baseUrl) {
+    if (this.runBase) {
       config.playwright = config.playwright || { browser: 'chromium', url: '' };
-      config.playwright.url = options.baseUrl;
+      config.playwright.url = this.runBase.origin;
     }
 
     resolveLangfuse(config.ai);
@@ -936,8 +963,23 @@ export async function createModel(provider: string, modelId: string): Promise<an
   return (await info.load())(modelId);
 }
 
+function parseRunBase(baseUrl?: string): RunBase | null {
+  if (!baseUrl) return null;
+
+  const url = URL.parse(baseUrl);
+  if (!url) throw new Error(`Base URL must be a full URL like https://app.example.com/team/acme, got "${baseUrl}"`);
+
+  return { origin: url.origin, path: url.pathname.replace(/\/+$/, ''), query: url.search };
+}
+
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
 
+interface RunBase {
+  origin: string;
+  path: string;
+  query: string;
+}
+
 interface ConfiguredModel {
   name: string;
   provider: string;

package/src/explorbot.ts

@@ -155,7 +155,7 @@ export class ExplorBot {
   }
 
   async visit(url: string): Promise<void> {
-    return this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
+    await this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
   }
 
   async openTab(): Promise<void> {
@@ -517,6 +517,8 @@ export class ExplorBot {
   setCurrentPlan(plan?: Plan): void {
     this.currentPlan = plan;
     if (!plan) return;
+    if (plan.url) plan.url = this.configParser.applyBasePath(plan.url);
+    for (const test of plan.tests) test.startUrl = this.configParser.applyBasePath(test.startUrl);
     if (!this.sessionPlans.includes(plan)) {
       this.sessionPlans.push(plan);
     }

package/src/explorer.ts

@@ -6,7 +6,7 @@ import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
 import dedent from 'dedent';
-import type { Browser, BrowserContextOptions, Page } from 'playwright';
+import type { Browser, BrowserContextOptions, Page, Route } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import type { RequestStore } from './api/request-store.ts';
@@ -103,6 +103,7 @@ class Explorer {
     if (!this.playwrightHelper) {
       throw new Error('Playwright helper not available');
     }
+    this.applyBasePathToHelper();
     await this.connectOrLaunchBrowser();
     const hasSession = !this.options?.attachedBrowser && this.options?.session && existsSync(this.options.session);
     await this.openContextPage();
@@ -163,7 +164,7 @@ class Explorer {
 
   async visit(url: string, opts: CaptureOpts = {}): Promise<ActionResult> {
     return this.runWithRecovery('visit', async () => {
-      const action = await this.visitOnce(url);
+      const action = await this.visitOnce(ConfigParser.getInstance().applyBasePath(url));
       if (opts.screenshot) return action.capturePageState({ includeScreenshot: true });
       return action.getActionResult() ?? action.capturePageState();
     });
@@ -347,6 +348,7 @@ class Explorer {
     const attached = this.options?.attachedBrowser;
     if (!attached) {
       await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+      await this.pinBaseQuery();
       return;
     }
 
@@ -356,6 +358,39 @@ class Explorer {
     this.playwrightHelper.browserContext = context;
     await this.playwrightHelper._setPage(page);
     debugLog(`Adopted attached browser page: ${page.url()}`);
+    await this.pinBaseQuery();
+  }
+
+  private applyBasePathToHelper(): void {
+    if (!ConfigParser.getInstance().getBasePath()) return;
+
+    const helper = this.playwrightHelper;
+    const original = helper.amOnPage.bind(helper);
+    helper.amOnPage = (url: string) => original(ConfigParser.getInstance().applyBasePath(url));
+  }
+
+  private async pinBaseQuery(): Promise<void> {
+    const query = ConfigParser.getInstance().getBaseQuery();
+    if (!query) return;
+
+    const pinned = new URLSearchParams(query);
+    const origin = URL.parse(this.config.playwright.url)?.origin;
+
+    await this.playwrightHelper.browserContext.route('**/*', async (route: Route) => {
+      const request = route.request();
+      if (request.resourceType() !== 'document') return route.continue();
+
+      const url = URL.parse(request.url());
+      if (!url || url.origin !== origin) return route.continue();
+
+      const missing = [...pinned].filter(([key]) => !url.searchParams.has(key));
+      if (!missing.length) return route.continue();
+
+      for (const [key, value] of missing) url.searchParams.set(key, value);
+      return route.continue({ url: url.toString() });
+    });
+
+    tag('info').log(`Every page load of ${origin} carries ${query}`);
   }
 
   private createBrowserContextOptions(): BrowserContextOptions {

package/src/global-config.ts

@@ -131,7 +131,7 @@ export function resolveSiteTarget(target?: string, defaultBaseUrl?: string): Sit
   }
 
   if (raw.startsWith('/')) {
-    const base = defaultBaseUrl || process.env.EXPLORBOT_URL;
+    const base = process.env.EXPLORBOT_URL || defaultBaseUrl;
     if (!base) {
       throw new Error(withSites(`Cannot resolve path "${raw}" without a site.`));
     }

package/src/test-plan.ts

@@ -66,6 +66,29 @@ export class ActiveNote {
   }
 }
 
+export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
+
+export class SettledExpectation {
+  constructor(
+    readonly text: string,
+    readonly status: SettledStatus,
+    readonly evidence?: string,
+    readonly resolution?: string
+  ) {}
+
+  get failed(): boolean {
+    return this.status === 'failed';
+  }
+
+  get contradicted(): boolean {
+    return this.status === 'contradiction';
+  }
+
+  resolve(status: SettledStatus, resolution: string): SettledExpectation {
+    return new SettledExpectation(this.text, status, this.evidence, resolution);
+  }
+}
+
 export interface StepData {
   text: string;
   duration?: number;

package/src/utils/code-extractor.ts

@@ -3,6 +3,9 @@ import { createDebug } from './logger.js';
 const debugLog = createDebug('explorbot:code-extractor');
 
 const JS_LANGUAGES = new Set(['', 'js', 'javascript']);
+const QUOTES = ["'", '"', '`'];
+const OPENING_BRACKETS = ['(', '[', '{'];
+const CLOSING_BRACKETS = [')', ']', '}'];
 
 export function extractCodeBlocks(aiResponse: string): string[] {
   const codeBlockRegex = /```([^\n`]*)\n([\s\S]*?)\n```/g;
@@ -24,3 +27,41 @@ export function extractCodeBlocks(aiResponse: string): string[] {
 
   return codeBlocks;
 }
+
+export function splitTopLevel(code: string, separator: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+  let quote = '';
+
+  for (let i = 0; i < code.length; i++) {
+    const char = code[i];
+
+    if (quote) {
+      current += char;
+      if (char === '\\') current += code[++i] || '';
+      if (char === quote) quote = '';
+      continue;
+    }
+
+    if (char === '/' && code[i + 1] === '/') {
+      while (i + 1 < code.length && code[i + 1] !== '\n') i++;
+      continue;
+    }
+
+    if (char === separator && depth <= 0) {
+      parts.push(current);
+      current = '';
+      depth = 0;
+      continue;
+    }
+
+    current += char;
+    if (QUOTES.includes(char)) quote = char;
+    if (OPENING_BRACKETS.includes(char)) depth++;
+    if (CLOSING_BRACKETS.includes(char)) depth--;
+  }
+
+  parts.push(current);
+  return parts;
+}

package/src/utils/html.ts

@@ -88,6 +88,7 @@ export const EXPLORBOT_ATTRS = {
   coveredBy: 'data-explorbot-covered-by',
   context: 'data-explorbot-context',
   eidx: 'data-explorbot-eidx',
+  hidden: 'data-explorbot-hidden',
   hit: 'data-explorbot-hit',
   variant: 'data-explorbot-variant',
 } as const;
@@ -189,6 +190,17 @@ export function captureHtmlForSnapshot(): string {
     }
   }
 
+  const liveElements = Array.from(document.body?.querySelectorAll('*') || []);
+  const clonedElements = Array.from(clone.querySelector('body')?.querySelectorAll('*') || []);
+  for (let i = 0; i < liveElements.length; i++) {
+    const source = liveElements[i];
+    if (source.matches('input, textarea, select, option, optgroup')) continue;
+    if (source.checkVisibility()) continue;
+    if (!source.parentElement?.checkVisibility()) continue;
+    if (getComputedStyle(source).display === 'contents') continue;
+    clonedElements[i]?.setAttribute('data-explorbot-hidden', 'true');
+  }
+
   return clone.outerHTML;
 }
 
@@ -1493,7 +1505,27 @@ function getAttribute(element: parse5TreeAdapter.Element, name: string): string
   return attr?.value;
 }
 
+function getImgAlt(element: parse5TreeAdapter.Element): string {
+  let alt = '';
+
+  function processNode(node: parse5TreeAdapter.Node) {
+    if (alt) return;
+    if ('tagName' in node) {
+      const el = node as parse5TreeAdapter.Element;
+      if (el.tagName.toLowerCase() === 'img') {
+        alt = getAttribute(el, 'alt') || '';
+        return;
+      }
+    }
+    if ('childNodes' in node) node.childNodes.forEach(processNode);
+  }
+
+  processNode(element);
+  return alt;
+}
+
 function hasHiddenClass(element: parse5TreeAdapter.Element): boolean {
+  if (getAttribute(element, EXPLORBOT_ATTRS.hidden)) return true;
   const classAttr = element.attrs.find((attr) => attr.name === 'class');
   if (!classAttr) return false;
 
@@ -1553,7 +1585,7 @@ export function extractLinks(html: string): ExtractedLink[] {
         if (href) {
           const shouldSkip = skipPrefixes.some((prefix) => href.startsWith(prefix));
           if (!shouldSkip) {
-            const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element);
+            const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element) || getImgAlt(element);
             const title = sanitizeLinkTitle(rawTitle);
             if (title && title.length <= 100) {
               const key = `${href}|${title}`;

package/src/utils/mdq/cli.ts

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync } from 'node:fs';
-import { Command } from 'commander';
+import { Command, type CommanderError } from 'commander';
 import { type MarkdownQuery, MdqError, mdq } from './query.ts';
 
 const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend', 'append', 'addRow', 'addItem', 'set'] as const;
@@ -7,7 +7,7 @@ const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend
 export async function runMdq(argv: string[], readStdin: StdinReader): Promise<CliResult> {
   const program = new Command();
   program
-    .name('mdq')
+    .name('mdq-cli')
     .description('query and edit markdown')
     .argument('[selector]', 'markdown selector')
     .argument('[file]', 'file to read; stdin when omitted')
@@ -31,6 +31,7 @@ export async function runMdq(argv: string[], readStdin: StdinReader): Promise<Cl
   try {
     program.parse(argv, { from: 'user' });
   } catch (error) {
+    if ((error as CommanderError).code === 'commander.helpDisplayed') return { output: program.helpInformation(), code: 0 };
     return { output: String((error as Error).message), code: 2 };
   }
 

package/src/utils/test-files.ts

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import chalk from 'chalk';
 import { highlight } from 'cli-highlight';
@@ -9,6 +10,8 @@ import store from 'codeceptjs/lib/store';
 import figureSet from 'figures';
 import { ConfigParser } from '../config.ts';
 
+const nodeRequire = createRequire(import.meta.url);
+
 export function listTestFiles(testsDir: string): string[] {
   if (!existsSync(testsDir)) return [];
 
@@ -17,10 +20,32 @@ export function listTestFiles(testsDir: string): string[] {
     .map((f) => path.resolve(testsDir, f));
 }
 
+/**
+ * Generated tests import `codeceptjs/steps`, but in global mode they lie in ~/.explorbot,
+ * far from any node_modules. Link the bot's own codeceptjs next to them so Node resolves it.
+ */
+export function ensureCodeceptResolvable(dir: string): void {
+  const link = path.join(dir, 'node_modules', 'codeceptjs');
+  if (existsSync(link)) return;
+  let target: string;
+  try {
+    target = path.dirname(nodeRequire.resolve('codeceptjs/package.json'));
+  } catch {
+    return;
+  }
+  try {
+    mkdirSync(path.dirname(link), { recursive: true });
+    symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch {
+    // Best effort: a project install already resolves codeceptjs without the link.
+  }
+}
+
 export function loadTestSuites(testsDir: string): any[] {
   const jsFiles = listTestFiles(testsDir);
   if (jsFiles.length === 0) return [];
 
+  ensureCodeceptResolvable(testsDir);
   codeceptjs.container.createMocha();
   const mocha = codeceptjs.container.mocha();
   mocha.files = jsFiles;
@@ -93,6 +118,7 @@ export async function dryRunTestFile(filePath: string): Promise<void> {
   codeceptjs.container.createMocha();
   const mocha = codeceptjs.container.mocha();
   mocha.reporter(class {});
+  ensureCodeceptResolvable(path.dirname(absPath));
   mocha.files = [absPath];
   mocha.loadFiles();