explorbot 0.5.6 → 0.5.8

package/dist/src/utils/url-filter.js

@@ -0,0 +1,52 @@
+import { tag } from './logger.js';
+import { parseSpecPairs } from "./spec.js";
+import { matchesUrl } from "./url-matcher.js";
+export class UrlFilter {
+    include = [];
+    exclude = [];
+    sort;
+    limit = Number.POSITIVE_INFINITY;
+    admitted = new Set();
+    constructor(spec) {
+        for (const { key, value } of parseSpecPairs(spec)) {
+            if (key === 'filter') {
+                this.include.push(value);
+                continue;
+            }
+            if (key === 'exclude') {
+                this.exclude.push(value);
+                continue;
+            }
+            if (key === 'sort' && (value === 'priority' || value === 'lastmod')) {
+                this.sort = value;
+                continue;
+            }
+            if (key === 'limit' && Number.parseInt(value, 10) > 0) {
+                this.limit = Number.parseInt(value, 10);
+                continue;
+            }
+            tag('warning').log(`Ignoring URL filter pair ${key}:${value} (use filter|exclude:<url pattern>, sort:priority|lastmod, limit:<n>)`);
+        }
+    }
+    allows(url) {
+        const path = urlPath(url);
+        if (this.include.length > 0 && !this.include.some((pattern) => matchesUrl(pattern, path)))
+            return false;
+        return !this.exclude.some((pattern) => matchesUrl(pattern, path));
+    }
+    admit(url) {
+        if (!this.allows(url))
+            return false;
+        const path = urlPath(url);
+        if (this.admitted.has(path))
+            return true;
+        if (this.admitted.size >= this.limit)
+            return false;
+        this.admitted.add(path);
+        return true;
+    }
+}
+function urlPath(url) {
+    const parsed = new URL(url, 'http://localhost');
+    return `${parsed.pathname}${parsed.search}`;
+}

package/docs/basics/getting-started.md

@@ -15,21 +15,28 @@ You need Node.js 24+ (or Bun), an AI provider key, and a modern terminal — iTe
 
 ## 2. Configure
 
-Create the config files:
+Run the setup wizard:
 
 ```bash
 npx explorbot init
 ```
 
-This writes `explorbot.config.js`, an `.env` file for your keys, and an `output/` folder.
+It asks for your AI provider, its API key, and your app's URL, then writes everything for you: `explorbot.config.js`, an `.env` file with the key stored, and an `output/` folder. No manual file editing.
 
-Open `.env` and add your provider key:
+The generated config keeps models simple — one line picks the recommended set for your provider:
 
-```bash
-OPENROUTER_API_KEY=sk-...
+```javascript
+export default {
+  web: {
+    url: 'http://localhost:3000',
+  },
+  ai: {
+    recommendedModels: 'openrouter',
+  },
+};
 ```
 
-Then open `explorbot.config.js` and set your app's base URL — the host only, no path:
+`ai.recommendedModels` fills every model role from the provider's bundled recommendations. To pin a single role instead, write it as `'provider/model-id'` — it overrides the recommendation:
 
 ```javascript
 export default {
@@ -37,10 +44,8 @@ export default {
     url: 'http://localhost:3000',
   },
   ai: {
-    model: 'openrouter/openai/gpt-oss-20b:nitro',
-    visionModel: 'openrouter/openai/gpt-5.6-luna',
-    agenticModel: 'openrouter/anthropic/claude-haiku-5.5',
-    decisionModel: { provider: 'openrouter', model: 'typesafe/jev-latest' },
+    recommendedModels: 'openrouter',
+    agenticModel: 'groq/openai/gpt-oss-120b',
   },
 };
 ```
@@ -84,6 +89,14 @@ Explorbot uses three models. Pick each one for speed and cost:
 
 Captain and Pilot barely use tokens, so a smarter `agenticModel` improves results for almost no extra cost. OpenRouter is the simplest start — one key, many models. To use OpenAI, Anthropic, Groq, or others, see [Providers](./providers.md). For every config option, see [Configuration](../reference/configuration.md).
 
+Want to see Explorbot work before pointing it at your app? Run it on the sample app:
+
+```bash
+npx explorbot explore https://todomvc.com/examples/react/dist/
+```
+
+You can also run it from the [VS Code extension](https://testomat.ai/explorbot) — pick a site, start a bot, and watch it test without leaving the editor. Full documentation lives at [testomat.ai/docs/explorbot](https://testomat.ai/docs/explorbot).
+
 ## 3. Tell Explorbot how to log in
 
 Most apps need a login. Give Explorbot the credentials once, and it signs in on its own:

package/docs/basics/providers.md

@@ -4,6 +4,8 @@ Explorbot connects to AI providers through the [Vercel AI SDK](https://sdk.verce
 
 Every provider below is set up the classical way: install its package, import it, build the client. Explorbot bundles some of these packages — for those you can skip the install and name the model as `'provider/model-id'` instead. See [Getting Started](./getting-started.md#2-configure) for that list and the two styles side by side.
 
+A third, shortest style names just the provider: `ai: { recommendedModels: 'openrouter' }` fills every unset role from that provider's bundled recommendations. An explicit role set alongside it wins, so `recommendedModels` with a pinned `agenticModel` mixes both styles.
+
 > The `export default` config block inside each `<!-- START/END provider -->` marker is generated from [`models.json`](../../models.json). After editing that file, run `bunosh docs:sync`. Everything else — including the import blocks — is hand-written.
 
 ## Requirements

package/docs/reference/commands.md

@@ -920,7 +920,9 @@ npx explorbot init --config-path ./explorbot.config.js
 npx explorbot init --force
 ```
 
-Passing `--config-path` or `--path` means local, and so does running outside a terminal (agents, CI): the chooser is skipped and the project config is written as before.
+The local wizard picks the provider, takes the API key (optionally checked with one test AI call), and asks for your app's URL — then writes everything: the key goes into `.env`, the URL into `web.url`, and the models come from `ai.recommendedModels: '<provider>'`. Nothing is left to edit by hand.
+
+Passing `--config-path` or `--path` means local, and so does running outside a terminal (agents, CI): the chooser is skipped and the project config is written with placeholder values instead. Init then prints the exact paths of the files that still need attention, a demo command to try Explorbot on a sample app (`npx explorbot explore https://todomvc.com/examples/react/dist/`), and links to the [VS Code extension](https://testomat.ai/explorbot) and the [docs](https://testomat.ai/docs/explorbot).
 
 `--global` runs the global wizard instead — pick a provider, paste the API key, optionally check it with one test AI call. The wizard writes `~/.explorbot/config.js` with the recommended model ids of this Explorbot version and stores the key in `~/.explorbot/.env`.
 
@@ -939,7 +941,8 @@ The global config holds models and keys, never a site: every command names the s
 | `-p, --path <path>` | Working directory for initialization |
 | `-g, --global` | Configure `~/.explorbot` to run from anywhere |
 | `--provider <name>` | AI provider for the global config, skips the wizard |
-| `--api-key <key>` | API key stored in `~/.explorbot/.env` |
+| `--api-key <key>` | API key stored in `~/.explorbot/.env` (local init: written to the project `.env`) |
+| `--url <url>` | Web application URL written to `web.url` in the local config |
 
 See [Configuration](configuration.md#running-from-anywhere-the-global-installation) for the directory layout and how a site is resolved.
 

package/docs/reference/configuration.md

@@ -536,6 +536,7 @@ export default {
   // AI provider settings
   ai: {
     model: groq('openai/gpt-oss-20b'),   // Default model instance (required)
+    recommendedModels: 'openrouter',     // Fills every unset role from this provider's bundled recommendations; explicit roles win
     visionModel: groq('meta-llama/llama-4-scout-17b-16e-instruct'),  // Model for screenshot analysis; setting it enables vision features
     decisionModel: { provider: 'openrouter', model: 'typesafe/jev-1.13' }, // Optional; see providers docs
     config: {},                    // Additional provider config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/src/ai/navigator.ts

@@ -20,6 +20,7 @@ import { loop, pause } from '../utils/loop.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { normalizeInlineText } from '../utils/strings.ts';
 import { extractStatePath, isSameHostFamily, matchesNavigationUrl } from '../utils/url-matcher.js';
+import type { UrlFilter } from '../utils/url-filter.ts';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import { type Decision, JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
@@ -564,7 +565,7 @@ class Navigator implements Agent {
     return { learnExperience: createLearnExperienceTool({ getExperienceTracker: () => this.experienceTracker, getState }) };
   }
 
-  async freeSail(opts?: { strategy?: 'deep' | 'shallow'; scope?: string; visitedUrls?: Set<string> }, actionResult?: ActionResult): Promise<{ target: string; reason: string } | null> {
+  async freeSail(opts?: { strategy?: 'deep' | 'shallow'; scope?: string; visitedUrls?: Set<string>; urlFilter?: UrlFilter }, actionResult?: ActionResult): Promise<{ target: string; reason: string } | null> {
     const stateManager = this.stateManager;
     const state = stateManager.getCurrentState();
     if (!state) {
@@ -612,6 +613,12 @@ class Navigator implements Agent {
     if (opts?.scope) {
       scopeInstruction = `IMPORTANT: Only suggest URLs that start with "${opts.scope}". Do not suggest URLs outside this scope.`;
     }
+    if (opts?.urlFilter?.include.length) {
+      scopeInstruction += `\nOnly suggest URLs matching one of these patterns: ${opts.urlFilter.include.join(', ')}`;
+    }
+    if (opts?.urlFilter?.exclude.length) {
+      scopeInstruction += `\nNever suggest URLs matching these patterns: ${opts.urlFilter.exclude.join(', ')}`;
+    }
 
     const prompt = dedent`
       <research>
@@ -665,6 +672,11 @@ class Navigator implements Agent {
           return;
         }
 
+        if (opts?.urlFilter && !opts.urlFilter.allows(target)) {
+          conversation.addUserText(`"${target}" does not pass the URL filter. Suggest a URL that does.`);
+          return;
+        }
+
         if (!target.startsWith('/') && !target.startsWith('http')) {
           conversation.addUserText(`"${target}" is not a valid URL path. Suggest a URL path starting with "/".`);
           return;

package/src/ai/pilot.ts

@@ -615,7 +615,7 @@ export class Pilot implements Agent {
     if (finalState?.screenshot && this.provider.hasVision()) image = finalState.screenshot;
 
     const decided = (text: string): 'passed' | 'failed' => {
-      if (task.hasAchievedAny() && !task.getRemainingExpectations().includes(text)) return 'passed';
+      if (task.hasAchieved(text)) return 'passed';
       return 'failed';
     };
 
@@ -631,7 +631,7 @@ export class Pilot implements Agent {
       outcomes: z.array(
         z.object({
           expectation: z.string().describe('The expected outcome, repeated exactly as it was given'),
-          status: z.enum(['passed', 'failed', 'unverified', 'contradiction']).describe('passed = the evidence shows it happened, failed = the evidence shows it did not, unverified = the run never established either way, contradiction = the picture and the run disagree'),
+          status: z.enum(['passed', 'failed', 'unverified', 'contradiction']).describe('passed = the evidence shows it happened to the thing it names, failed = the evidence shows it did not, unverified = the run never established either way, contradiction = the picture and the run disagree'),
           evidence: z.string().nullable().describe('What settled it. For a contradiction, what each side shows. Null when there is nothing to add'),
         })
       ),
@@ -657,6 +657,10 @@ export class Pilot implements Agent {
     const userContent = dedent`
       A test run has finished. Decide, for each expected outcome, what the run established about it.
 
+      <scenario>
+      ${task.scenario}
+      </scenario>
+
       <expected_outcomes>
       ${undecided.map((text) => `- ${text}`).join('\n')}
       </expected_outcomes>
@@ -669,6 +673,9 @@ export class Pilot implements Agent {
 
       The log is written in the tester's own words, so an outcome can be satisfied by a step that describes it
       differently. Judge by what the steps show happened, not by whether the wording matches.
+      Wording may differ, the subject may not. An outcome refers to what the scenario names or chooses; it holds
+      only when that same thing appears. A different route or a different thing reaching a similar state is "failed",
+      and so is an outcome about something the run never managed to choose or create.
       Choose "unverified" only when the evidence neither shows the outcome happening nor shows it failing —
       that is a statement about the run, not about the application.
     `;

package/src/commands/explore-command.ts

@@ -9,7 +9,10 @@ import { getCliName } from '../utils/cli-name.ts';
 import { ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
+import { keepSiteUrls, readSitemap } from '../utils/sitemap.ts';
+import { parseSpecPairs } from '../utils/spec.ts';
 import { safeFilename } from '../utils/strings.ts';
+import { UrlFilter } from '../utils/url-filter.ts';
 import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
 
 const MAX_SUB_PAGE_ATTEMPTS = 30;
@@ -26,6 +29,8 @@ export class ExploreCommand extends BaseCommand {
     { flags: '--focus <feature>', description: 'Focus area for exploration' },
     { flags: '--configure <spec>', description: 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"' },
     { flags: '--dry-run', description: 'Mark picked tests as skipped without executing or generating new ones' },
+    { flags: '--sitemap <source>', description: 'Explore every page listed in a sitemap (file path, URL, or - for stdin) instead of discovering sub-pages' },
+    { flags: '--url-filter <spec>', description: 'Pick pages to explore: keys filter|exclude|limit, plus sort:priority|lastmod for a sitemap, e.g. "filter:/admin/*;exclude:/admin/logs/*;limit:20"' },
   ];
   suggestions: Suggestion[] = [
     { command: 'navigate <page>', hint: 'go to another page' },
@@ -37,6 +42,8 @@ export class ExploreCommand extends BaseCommand {
   maxDurationMinutes?: number;
   hardDeadlineAt?: number;
   dryRun = false;
+  sitemapUrls?: string[];
+  urlFilter = new UrlFilter();
   private testsRun = 0;
   private deadlineLogged = false;
   private completedPlans: Plan[] = [];
@@ -57,6 +64,8 @@ export class ExploreCommand extends BaseCommand {
     if (opts.maxDuration) {
       this.maxDurationMinutes = Number.parseInt(opts.maxDuration as string, 10);
     }
+    if (opts.urlFilter) this.urlFilter = new UrlFilter(opts.urlFilter as string);
+    if (opts.sitemap) this.sitemapUrls = await readSitemap(opts.sitemap as string, this.urlFilter);
     if (this.hardDeadlineAt == null && this.maxDurationMinutes != null) {
       this.hardDeadlineAt = Date.now() + this.maxDurationMinutes * 60_000 - DEADLINE_RESERVE_MS;
     }
@@ -76,13 +85,15 @@ export class ExploreCommand extends BaseCommand {
     Stats.focus ??= feature;
     const mainUrl = this.getCurrentPageUrl();
     const error = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
-    if (error) {
+    if (error && !this.sitemapUrls) {
       tag('warning').log(error.message);
       return;
     }
 
     try {
-      if (cfg.enabled) {
+      if (this.sitemapUrls) {
+        await this.runSitemapMode(this.sitemapUrls, feature, cfg.styles);
+      } else if (cfg.enabled) {
         await this.runReuseMode(mainUrl, feature, cfg);
       } else {
         await this.runFreshMode(mainUrl, feature, cfg.styles);
@@ -135,6 +146,20 @@ export class ExploreCommand extends BaseCommand {
     await this.discoverNewSubPages(mainPlan, mainUrl, styles, new Set());
   }
 
+  private async runSitemapMode(sitemapUrls: string[], feature: string | undefined, styles?: string[]): Promise<void> {
+    const urls = keepSiteUrls(sitemapUrls, this.explorBot.getConfig().playwright.url);
+    tag('info').log(`Sitemap: ${urls.length} page(s) to explore`);
+    for (const url of urls) {
+      if (this.isLimitReached()) break;
+      tag('info').log(`Exploring sitemap page: ${url}`);
+      try {
+        await this.explorePage(url, feature, undefined, styles);
+      } catch (err) {
+        tag('warning').log(`Sitemap page exploration failed: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
+
   private async runReuseMode(mainUrl: string | undefined, feature: string | undefined, cfg: ConfigureSpec): Promise<void> {
     const filename = cfg.fromPath || this.explorBot.generatePlanFilename(feature);
 
@@ -234,6 +259,7 @@ export class ExploreCommand extends BaseCommand {
       for (const subPlan of subPlans) {
         if (this.isLimitReached()) break;
         if (!subPlan.url) continue;
+        if (!this.urlFilter.admit(subPlan.url)) continue;
         try {
           if (!this.dryRun) await this.explorBot.visit(subPlan.url);
           await this.replanAndRun(subPlan.url, undefined, subPlan, cfg.styles);
@@ -264,27 +290,21 @@ export class ExploreCommand extends BaseCommand {
 
       const candidates = planner.collectSubPageCandidates(mainPlan, mainUrl || '/').filter((c) => {
         const norm = normalizeUrl(c.url);
-        return !this.failedSubPages.has(norm) && !knownUrls.has(norm);
+        return !this.failedSubPages.has(norm) && !knownUrls.has(norm) && this.urlFilter.allows(c.url);
       });
       if (candidates.length === 0) break;
 
       const pick = await planner.pickNextSubPage(candidates);
       if (!pick) break;
+      if (!this.urlFilter.admit(pick.url)) break;
 
       tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
       try {
-        await this.explorBot.visit(pick.url);
-        const errorPage = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
-        if (errorPage) {
-          tag('warning').log(`Skipping sub-page: ${errorPage.message}`);
+        const explored = await this.explorePage(pick.url, undefined, mainPlan, styles);
+        if (!explored) {
           this.failedSubPages.add(normalizeUrl(pick.url));
           continue;
         }
-        await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans, styles);
-        const subPlan = this.explorBot.getCurrentPlan();
-        if (subPlan?.tests.length && !this.completedPlans.includes(subPlan)) {
-          this.completedPlans.push(subPlan);
-        }
         knownUrls.add(normalizeUrl(pick.url));
       } catch (err) {
         this.failedSubPages.add(normalizeUrl(pick.url));
@@ -293,6 +313,21 @@ export class ExploreCommand extends BaseCommand {
     }
   }
 
+  private async explorePage(url: string, feature: string | undefined, parentPlan: Plan | undefined, styles?: string[]): Promise<boolean> {
+    await this.explorBot.visit(url);
+    const errorPage = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
+    if (errorPage) {
+      tag('warning').log(`Skipping page: ${errorPage.message}`);
+      return false;
+    }
+    await this.runAllStyles(url, feature, parentPlan, this.completedPlans, styles);
+    const plan = this.explorBot.getCurrentPlan();
+    if (plan?.tests.length && !this.completedPlans.includes(plan)) {
+      this.completedPlans.push(plan);
+    }
+    return true;
+  }
+
   private async replanAndRun(pageUrl: string | undefined, feature: string | undefined, existingPlan: Plan, styles?: string[]): Promise<void> {
     const styleList = styles ?? Object.keys(getStyles());
     for (const style of styleList) {
@@ -369,17 +404,7 @@ export class ExploreCommand extends BaseCommand {
     const validSubpages = new Set(['none', 'same', 'new', 'both']);
     let hasReuseSignal = false;
 
-    for (const pair of raw.split(';')) {
-      const trimmed = pair.trim();
-      if (!trimmed) continue;
-      const sepMatch = trimmed.match(/^([^:=]+)\s*[:=]\s*(.*)$/);
-      if (!sepMatch) {
-        tag('warning').log(`Ignoring malformed configure pair: ${trimmed}`);
-        continue;
-      }
-      const key = sepMatch[1].trim().toLowerCase();
-      const value = sepMatch[2].trim();
-
+    for (const { key, value } of parseSpecPairs(raw)) {
       if (key === 'new') {
         const ratio = parseRatio(value);
         if (ratio == null) {
@@ -558,6 +583,14 @@ export class ExploreCommand extends BaseCommand {
       });
     }
 
+    sections.push({
+      label: 'Explore more',
+      commands: [
+        { label: 'Whole site', command: `${cli} explore /` },
+        { label: 'Docs', command: 'https://testomat.ai/docs/explorbot' },
+      ],
+    });
+
     printNextSteps(sections);
   }
 

package/src/commands/freesail-command.ts

@@ -4,6 +4,7 @@ import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
 import { tag } from '../utils/logger.js';
 import { loop } from '../utils/loop.js';
+import { UrlFilter } from '../utils/url-filter.ts';
 import { BaseCommand } from './base-command.js';
 import { DEADLINE_RESERVE_MS, DEADLINE_TEST_ALLOWANCE_MS, ExploreCommand } from './explore-command.js';
 
@@ -18,6 +19,7 @@ export class FreesailCommand extends BaseCommand {
     { flags: '--scope <url>', description: 'Limit navigation to URLs starting with this prefix' },
     { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
     { flags: '--max-duration <number>', description: 'Wall-clock budget in minutes for the whole run' },
+    { flags: '--url-filter <spec>', description: 'Pick pages to explore: keys filter|exclude|limit, e.g. "filter:/admin/*;exclude:/admin/logs/*;limit:20"' },
   ];
 
   async execute(args: string): Promise<void> {
@@ -27,6 +29,7 @@ export class FreesailCommand extends BaseCommand {
     if (opts.deep) strategy = 'deep';
     if (opts.shallow) strategy = 'shallow';
     const scope = opts.scope as string | undefined;
+    const urlFilter = new UrlFilter(opts.urlFilter as string | undefined);
     const maxTests = opts.maxTests ? Number.parseInt(opts.maxTests as string, 10) : undefined;
     const maxDuration = opts.maxDuration ? Number.parseInt(opts.maxDuration as string, 10) : undefined;
     let hardDeadlineAt: number | undefined;
@@ -55,6 +58,7 @@ export class FreesailCommand extends BaseCommand {
           const exploreCmd = new ExploreCommand(this.explorBot);
           if (maxTests != null) exploreCmd.maxTests = maxTests - testsRun;
           if (hardDeadlineAt != null) exploreCmd.hardDeadlineAt = hardDeadlineAt;
+          exploreCmd.urlFilter = urlFilter;
           await exploreCmd.execute('');
 
           const plan = this.explorBot.getCurrentPlan();
@@ -65,7 +69,7 @@ export class FreesailCommand extends BaseCommand {
 
         const navigator = this.explorBot.agentNavigator();
         const visitedUrls = stateManager.getAllVisitedUrls();
-        const suggestion = await navigator.freeSail({ strategy, scope, visitedUrls });
+        const suggestion = await navigator.freeSail({ strategy, scope, visitedUrls, urlFilter });
         if (!suggestion) {
           tag('info').log('No navigation suggestion available');
           ctx.stop();
@@ -76,6 +80,11 @@ export class FreesailCommand extends BaseCommand {
           ctx.stop();
         }
 
+        if (!urlFilter.admit(suggestion.target)) {
+          tag('info').log(`URL filter allows no more pages (${suggestion.target} not admitted); stopping exploration`);
+          ctx.stop();
+        }
+
         const currentUrl = stateManager.getCurrentState()?.url;
         if (currentUrl && normalizeUrl(suggestion.target) === normalizeUrl(currentUrl)) {
           tag('info').log(`No new navigation target available after ${currentUrl}; stopping exploration`);