explorbot 0.4.5 → 0.4.7

package/dist/src/api/spec-reader.js

@@ -42,13 +42,35 @@ export function extractEndpointDefinition(schema, endpoint, baseEndpoint) {
         throw new Error('OpenAPI spec has no paths defined');
     }
     const basePath = toBasePath(baseEndpoint);
-    const matched = collectMatchingPaths(schema, basePath, (normalized) => matchesEndpoint(normalized, endpoint));
+    const matched = collectEndpointPaths(schema, basePath, endpoint);
     if (!Object.keys(matched).length) {
         const available = listNormalizedPaths(schema, basePath);
         throw new Error(`Endpoint "${endpoint}" not found in spec. Available: ${available}`);
     }
     return safeStringify(matched);
 }
+export function resolveEndpoints(schema, pattern, baseEndpoint) {
+    if (!schema?.paths) {
+        throw new Error('OpenAPI spec has no paths defined');
+    }
+    const basePath = toBasePath(baseEndpoint);
+    const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+    const matched = normalized.filter((specPath) => matchesPattern(specPath, pattern));
+    if (!matched.length) {
+        throw new Error(`Endpoint "${pattern}" not found in spec. Available: ${listNormalizedPaths(schema, basePath)}`);
+    }
+    const roots = matched.map((specPath) => toCollection(specPath, normalized, pattern));
+    const resolved = [...new Set(roots.map((root) => fillParameters(root, pattern)))];
+    const endpoints = resolved.filter((specPath) => !specPath.includes('{'));
+    if (!endpoints.length) {
+        throw new Error(`Endpoint "${pattern}" leaves ${listParameters(resolved)} unresolved. Give the value in the endpoint or in the base endpoint.`);
+    }
+    const skipped = resolved.filter((specPath) => specPath.includes('{'));
+    if (skipped.length) {
+        tag('warning').log(`Skipped, no value for their parameters: ${skipped.join(', ')}`);
+    }
+    return endpoints;
+}
 export function searchEndpoints(schema, query, baseEndpoint) {
     if (!schema?.paths)
         return 'No endpoints available';
@@ -136,6 +158,76 @@ function stripBasePath(specPath, basePath) {
     }
     return `/${specSegments.slice(i).join('/')}`;
 }
+function collectEndpointPaths(schema, basePath, endpoint) {
+    const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+    const roots = resolveEndpoint(normalized, endpoint);
+    if (!roots.length)
+        return collectMatchingPaths(schema, basePath, (path) => matchesEndpoint(path, endpoint));
+    return collectMatchingPaths(schema, basePath, (path) => roots.some((root) => path === root || path.startsWith(`${root}/`)));
+}
+function resolveEndpoint(specPaths, endpoint) {
+    const wanted = toSegments(endpoint);
+    if (!wanted.length)
+        return [];
+    const matched = specPaths.filter((specPath) => {
+        const segments = toSegments(specPath);
+        if (segments.length !== wanted.length)
+            return false;
+        return segmentsMatch(segments, wanted);
+    });
+    const literals = matched.map((specPath) => toSegments(specPath).filter((segment, i) => segment === wanted[i]).length);
+    const best = Math.max(0, ...literals);
+    return matched.filter((_, i) => literals[i] === best);
+}
+function matchesPattern(specPath, pattern) {
+    const wanted = toSegments(pattern);
+    const segments = toSegments(specPath);
+    if (segments.length < wanted.length)
+        return false;
+    return segmentsMatch(segments, wanted);
+}
+function segmentsMatch(segments, wanted) {
+    return wanted.every((want, i) => want === '*' || segments[i] === want || segments[i].startsWith('{'));
+}
+function toCollection(specPath, specPaths, pattern) {
+    const segments = toSegments(specPath);
+    const filled = toSegments(fillParameters(specPath, pattern));
+    let deepest = segments.length;
+    const unfilled = filled.findIndex((segment) => segment.startsWith('{'));
+    if (unfilled >= 0)
+        deepest = unfilled;
+    for (let i = Math.max(1, Math.min(toSegments(pattern).length, deepest)); i <= deepest; i++) {
+        const prefix = `/${segments.slice(0, i).join('/')}`;
+        if (specPaths.includes(prefix))
+            return prefix;
+    }
+    return specPath;
+}
+function fillParameters(specPath, pattern) {
+    const wanted = toSegments(pattern);
+    const segments = toSegments(specPath);
+    for (let i = 0; i < wanted.length && i < segments.length; i++) {
+        if (wanted[i] === '*')
+            continue;
+        if (!segments[i].startsWith('{'))
+            continue;
+        segments[i] = wanted[i];
+    }
+    return `/${segments.join('/')}`;
+}
+function listParameters(specPaths) {
+    const found = new Set();
+    for (const specPath of specPaths) {
+        for (const segment of toSegments(specPath)) {
+            if (segment.startsWith('{'))
+                found.add(segment);
+        }
+    }
+    return [...found].join(', ');
+}
+function toSegments(path) {
+    return path.split('/').filter(Boolean);
+}
 function matchesEndpoint(specPath, endpoint) {
     if (specPath === endpoint)
         return true;

package/dist/src/commands/base-command.d.ts

@@ -7,15 +7,15 @@ export interface Suggestion {
     command?: string;
     hint: string;
 }
-export declare abstract class BaseCommand {
+export declare abstract class BaseCommand<T = ExplorBot> {
     abstract name: string;
     abstract description: string;
     aliases: string[];
     options: CommandOption[];
     tuiEnabled: boolean;
     suggestions: Suggestion[];
-    explorBot: ExplorBot;
-    constructor(explorBot: ExplorBot);
+    explorBot: T;
+    constructor(explorBot: T);
     abstract execute(args: string): Promise<void>;
     matches(commandName: string): boolean;
     printSuggestions(): void;

package/dist/src/commands/init-command.d.ts

@@ -1,6 +1,9 @@
+import { type ModelRole } from '../config.js';
+export declare function envTemplate(provider: string): string;
 export declare function runInit(options: InitCommandOptions): Promise<void>;
 export declare function writeGlobalConfig(provider: string, apiKey?: string): void;
 export declare function runInitCommand(options: InitCommandOptions): void;
+export declare function modelLines(provider: string, only?: ModelRole[]): string;
 type InitCommandOptions = {
     configPath?: string;
     force?: boolean;

package/dist/src/commands/init-command.js

@@ -37,7 +37,7 @@ ${modelLines(provider)}
 ${moduleExport}
 `;
 }
-function envTemplate(provider) {
+export function envTemplate(provider) {
     const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
         if (name === provider)
             return `${envKey}=`;
@@ -219,14 +219,17 @@ async function renderLocalProviderWizard() {
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
-function modelLines(provider) {
+export function modelLines(provider, only) {
     const recommended = ConfigParser.recommendedModels()[provider] || {};
     const roles = [
         ['model', 'fast model with tool calling capabilities'],
         ['visionModel', 'vision model for screenshot analysis'],
         ['agenticModel', 'agentic model for decision making'],
     ];
-    return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+    let selected = roles;
+    if (only)
+        selected = roles.filter(([role]) => only.includes(role));
+    return selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
 }
 function globalConfigTemplate(provider) {
     const { envKey } = PROVIDERS[provider];

package/dist/src/commands/options/ws-option.d.ts

@@ -3,5 +3,12 @@ import { BaseOption } from './base-option.js';
 export declare class WsOption extends BaseOption {
     flags: string;
     description: string;
+    /**
+     * An open socket holds the event loop, and `WebSocket` has no `unref` on
+     * either runtime — so a command that ends by returning rather than through
+     * `showStatsAndExit` would never exit once it is attached. The option that
+     * opened the connection is what closes it.
+     */
+    register(command: Command): void;
     apply(options: Record<string, any>, command: Command): void;
 }

package/dist/src/commands/options/ws-option.js

@@ -3,6 +3,20 @@ import { BaseOption } from './base-option.js';
 export class WsOption extends BaseOption {
     flags = '--ws <url>';
     description = 'Stream this run to a remote UI over WebSocket';
+    /**
+     * An open socket holds the event loop, and `WebSocket` has no `unref` on
+     * either runtime — so a command that ends by returning rather than through
+     * `showStatsAndExit` would never exit once it is attached. The option that
+     * opened the connection is what closes it.
+     */
+    register(command) {
+        super.register(command);
+        command.hook('postAction', async () => {
+            if (!remote.isAttached())
+                return;
+            await remote.close(0);
+        });
+    }
     apply(options, command) {
         const url = options.ws || process.env.EXPLORBOT_WS_URL;
         if (!url)

package/dist/src/config.d.ts

@@ -287,6 +287,7 @@ export declare function modelName(model: unknown): string;
 export declare function modelProvider(model: unknown): string;
 export declare function configuredModels(ai?: AIConfig): Record<string, ConfiguredModel>;
 export declare function resolveConfigModels(ai?: AIConfig): Promise<void>;
+export declare function resolveLangfuse(ai?: AIConfig): void;
 export declare function resolveOutputRoot(baseUrl?: string): string;
 export declare function resolveStateRoot(baseUrl: string, ephemeral?: boolean): string;
 export declare function materializeKnowledge(outputRoot: string): void;

package/dist/src/config.js

@@ -377,17 +377,7 @@ export class ConfigParser {
             config.playwright = config.playwright || { browser: 'chromium', url: '' };
             config.playwright.url = options.baseUrl;
         }
-        if (config.ai) {
-            const langfuse = config.ai.langfuse;
-            const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
-            const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
-            config.ai.langfuse = {
-                enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
-                publicKey,
-                secretKey,
-                baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
-            };
-        }
+        resolveLangfuse(config.ai);
         return config;
     }
     validateConfig(config) {
@@ -540,6 +530,19 @@ export async function resolveConfigModels(ai) {
             agent.model = await resolveModel(agent.model);
     }
 }
+export function resolveLangfuse(ai) {
+    if (!ai)
+        return;
+    const langfuse = ai.langfuse;
+    const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
+    const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
+    ai.langfuse = {
+        enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
+        publicKey,
+        secretKey,
+        baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
+    };
+}
 export function resolveOutputRoot(baseUrl) {
     if (cachedOutputRoot)
         return cachedOutputRoot;

package/dist/src/explorer.d.ts

@@ -39,7 +39,7 @@ declare class Explorer {
     testPageErrorHandler: ((error: Error) => void) | null;
     testConsoleHandler: ((message: any) => void) | null;
     testDialogHandler: ((dialog: any) => void) | null;
-    eventDispatcher: any;
+    eventDispatcher: NodeJS.EventEmitter<[never]>;
     constructor(config: ExplorbotConfig, options: ExplorerOptions | undefined, deps: ExplorerDeps);
     get actor(): CodeceptJS.I;
     get page(): Page | null;

package/dist/src/explorer.js

@@ -208,7 +208,7 @@ class Explorer {
         codeceptjs.container.create(this.convertToCodeceptConfig(this.config), {});
     }
     convertToCodeceptConfig(config) {
-        const playwrightConfig = { ...config.playwright };
+        const playwrightConfig = { visibleLocator: true, ...config.playwright };
         if (this.options?.show !== undefined) {
             playwrightConfig.show = this.options.show;
         }

package/dist/src/remote.d.ts

@@ -18,6 +18,7 @@ export declare class Remote implements LogDestination {
     asks: Map<string, (value: string | null) => void>;
     askCounter: number;
     lastActivity: string | null;
+    closing: Promise<void> | null;
     attach(url: string, command: string): void;
     isAttached(): boolean;
     send(type: string, data?: Record<string, unknown>): void;
@@ -30,6 +31,7 @@ export declare class Remote implements LogDestination {
      * back out of flattened text.
      */
     write(entry: TaggedLogEntry): void;
+    shutdown(exitCode: number): Promise<void>;
     connect(): void;
     reconnect(): void;
     flush(): Promise<void>;

package/dist/src/remote.js

@@ -26,6 +26,7 @@ export class Remote {
     asks = new Map();
     askCounter = 0;
     lastActivity = null;
+    closing = null;
     attach(url, command) {
         if (this.url)
             return;
@@ -68,23 +69,12 @@ export class Remote {
             });
         });
     }
-    async close(exitCode) {
+    close(exitCode) {
         if (!this.url)
-            return;
-        this.send('result', { ok: exitCode === 0, exitCode });
-        await this.flush();
-        this.url = null;
-        if (this.reconnectTimer)
-            clearTimeout(this.reconnectTimer);
-        // Whoever asks next has nobody to ask — leaving the callback installed would
-        // route them into a closed socket and park them until the ask times out.
-        executionController.clearInputCallback();
-        for (const resolve of this.asks.values())
-            resolve(null);
-        this.asks.clear();
-        this.queue = [];
-        this.socket?.close();
-        this.socket = null;
+            return Promise.resolve();
+        if (!this.closing)
+            this.closing = this.shutdown(exitCode);
+        return this.closing;
     }
     isEnabled() {
         return this.isAttached();
@@ -112,6 +102,23 @@ export class Remote {
             error: this.errorOf(entry.originalArgs),
         });
     }
+    async shutdown(exitCode) {
+        this.send('result', { ok: exitCode === 0, exitCode });
+        await this.flush();
+        this.url = null;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        // Whoever asks next has nobody to ask — leaving the callback installed would
+        // route them into a closed socket and park them until the ask times out.
+        executionController.clearInputCallback();
+        for (const resolve of this.asks.values())
+            resolve(null);
+        this.asks.clear();
+        this.queue = [];
+        this.socket?.close();
+        this.socket = null;
+        this.closing = null;
+    }
     connect() {
         if (!this.url)
             return;

package/dist/src/utils/aria.d.ts

@@ -16,4 +16,6 @@ export declare const LARGE_ARIA_CHANGE_THRESHOLD = 50;
 export interface AriaDiff {
     text: string | null;
     count: number;
+    added: number;
+    removed: number;
 }

package/dist/src/utils/aria.js

@@ -511,7 +511,12 @@ export const diffAriaSnapshots = (previous, current) => {
     const renames = detectRenames(prev, curr, prevTotals, currTotals);
     const added = [...byCount.added, ...renames.added];
     const removed = [...byCount.removed, ...renames.removed];
-    return { text: formatDiff(added, removed, toggled, typed), count: added.length + removed.length + toggled.length + typed.length };
+    return {
+        text: formatDiff(added, removed, toggled, typed),
+        count: added.length + removed.length + toggled.length + typed.length,
+        added: added.length,
+        removed: removed.length,
+    };
 };
 export const detectFocusArea = (snapshot) => {
     let tree = parseSnapshot(snapshot);

package/dist/src/utils/html-diff.js

@@ -4,7 +4,7 @@ import { isDynamicId, isGenericClass } from "./xpath.js";
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
 const SHELL_RATIO = 0.8;
 const ROOT_CONTENT_RATIO = 0.8;
-const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
+const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log', 'tooltip']);
 const TEXT_LINE_PREFIX = 'TEXT:';
 const MESSAGE_MAX_LENGTH = 200;
 const MESSAGE_LIMIT = 8;
@@ -447,6 +447,9 @@ function semanticSelectorFor(element, allElements) {
         const selector = buildContainerSelector(current, allElements);
         if (selector)
             return selector;
+        const classAttr = (current.attrs ?? []).find((a) => a.name === 'class')?.value;
+        if (classAttr && filterContainerClasses(classAttr.split(/\s+/).filter(Boolean)).length > 0)
+            return undefined;
         current = dominantChild(current);
     }
     return undefined;

package/dist/src/utils/markdown-query.d.ts

@@ -29,6 +29,8 @@ export declare class MarkdownQuery {
     text(): string;
     get(): string;
     toJson(): Record<string, string>[];
+    keyValue(): Record<string, string>;
+    setKeyValue(key: string, value: string | null): string;
     replace(content: string): string;
     replaceEach(replacer: (match: MarkdownQuery, index: number) => string): string;
     count(): number;

package/dist/src/utils/markdown-query.js

@@ -129,6 +129,12 @@ function matchText(text, matcher) {
     }
     return matcher.negated ? !result : result;
 }
+function entryKey(line) {
+    const separator = line.indexOf(':');
+    if (separator < 1)
+        return null;
+    return line.slice(0, separator).trim().toLowerCase();
+}
 function getTokenText(token) {
     const t = token;
     switch (token.type) {
@@ -340,6 +346,39 @@ export class MarkdownQuery {
         }
         return results;
     }
+    keyValue() {
+        const entries = {};
+        for (const range of this.matches) {
+            for (const line of getTokenText(range.token).split('\n')) {
+                const key = entryKey(line);
+                if (!key)
+                    continue;
+                const value = line.slice(line.indexOf(':') + 1).trim();
+                if (value)
+                    entries[key] = value;
+            }
+        }
+        return entries;
+    }
+    setKeyValue(key, value) {
+        return this.replaceEach((match) => {
+            const token = match.matches[0].token;
+            const lines = getTokenText(token)
+                .split('\n')
+                .map((line) => line.trim())
+                .filter(Boolean);
+            const index = lines.findIndex((line) => entryKey(line) === key.toLowerCase());
+            if (index < 0 && value)
+                lines.push(`${key}: ${value}`);
+            if (index >= 0 && value)
+                lines[index] = `${key}: ${value}`;
+            if (index >= 0 && !value)
+                lines.splice(index, 1);
+            if (token.type !== 'blockquote')
+                return lines.join('\n');
+            return lines.map((line) => `> ${line}`).join('\n');
+        });
+    }
     replace(content) {
         return this.replaceEach(() => content);
     }

package/dist/src/utils/pagination.d.ts

@@ -0,0 +1,16 @@
+export declare function inspectList(css: string): ListMeasure | null;
+export declare function restoreScroll({ css, scrollTop, pageScrollY }: ScrollPosition): void;
+export type PaginationStrategy = 'controls' | 'infinite';
+export interface ListMeasure {
+    hasPagingControls: boolean;
+    isFeed: boolean;
+    scrolls: boolean;
+    items: number;
+    scrollTop: number;
+    pageScrollY: number;
+}
+export interface ScrollPosition {
+    css: string;
+    scrollTop: number;
+    pageScrollY: number;
+}

package/dist/src/utils/pagination.js

@@ -0,0 +1,20 @@
+export function inspectList(css) {
+    const element = document.querySelector(css);
+    if (!element)
+        return null;
+    const rect = element.getBoundingClientRect();
+    return {
+        hasPagingControls: !!element.querySelector('a[rel="next"], a[rel="prev"]'),
+        isFeed: element.matches('[role="feed"]') || !!element.querySelector('[role="feed"]'),
+        scrolls: element.scrollHeight > element.clientHeight + 1 || rect.bottom > window.innerHeight,
+        items: element.querySelectorAll(':scope > *').length,
+        scrollTop: element.scrollTop,
+        pageScrollY: window.scrollY,
+    };
+}
+export function restoreScroll({ css, scrollTop, pageScrollY }) {
+    const element = document.querySelector(css);
+    if (element)
+        element.scrollTop = scrollTop;
+    window.scrollTo(0, pageScrollY);
+}

package/docs/api-testing/basics.md

@@ -66,7 +66,7 @@ npx explorbot api explore https://api.example.com/v1 \
   -H "Authorization: Bearer $TOKEN"
 ```
 
-`api explore` takes the base endpoint as its argument, so one line covers the whole run: it plans in every style, executes each plan, and reports the totals. The other commands take a path within the API and read the base from `--endpoint`:
+`api explore` takes an endpoint or a pattern as its argument, so one line covers the whole run: it plans, executes each plan, and reports the totals. Passing the base endpoint covers every collection the spec describes. The other commands take a path within the API and read the base from `--endpoint`:
 
 ```bash
 npx explorbot api plan /users \
@@ -81,7 +81,7 @@ The base endpoint keeps its path prefix: given `https://api.example.com/v1`, ste
 
 ### A dedicated API project
 
-If you don't have a web `explorbot.config.js`, run `npx explorbot api init`. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone `apibot.config.ts` (with an `ai` and `api` section) plus `output/` and `knowledge/` directories. When both files exist, `apibot.config.*` takes precedence over `explorbot.config.*`.
+If you don't have a web `explorbot.config.js`, run `npx explorbot api init`. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone `apibot.config.js` (with an `ai` and `api` section) plus `output/` and `knowledge/` directories. When both files exist, `apibot.config.*` takes precedence over `explorbot.config.*`.
 
 ## Your first run
 
@@ -99,6 +99,30 @@ npx explorbot api test output/plans/users.md
 
 Curler runs the scenarios and prints how many passed and failed.
 
+### Covering many endpoints
+
+`api explore` runs the whole loop for you: plan, test, re-plan. Given one endpoint it plans in every style.
+
+```bash
+npx explorbot api explore /users
+```
+
+The endpoint may be a pattern. `*` stands for one path segment, and a pattern also covers the paths below it, so `/users` and `/users/*` both cover `/users/{id}`. Quote it, or your shell will try to expand it first.
+
+```bash
+npx explorbot api explore '/projects/acme/*'
+```
+
+Explorbot explores collections, not raw paths: `/users/{id}` and `/users/{id}/posts` fold into `/users`, whose spec lookup brings them along anyway. When a pattern matches several collections the planning styles spread across them, one style per collection, so covering a whole API stays one plan per collection rather than one per style.
+
+Pass `/` to take every collection in the spec. The path parameters have to come from somewhere, so put them in the base endpoint.
+
+```bash
+npx explorbot api explore / --endpoint https://api.example.com/v2/acme
+```
+
+If a parameter is left with no value the run stops and names it, rather than sending requests to a literal `{project_id}`. Collections whose own parameters no pattern can fill, like `/analytics/stats/{kind}`, are listed and skipped.
+
 ## Output files
 
 | Output | Location | What it is |