explorbot 0.2.2 → 0.2.4

package/dist/src/global-config.d.ts

@@ -0,0 +1,22 @@
+export declare function globalDir(): string;
+export declare function globalEnvPath(): string;
+export declare function globalConfigPath(): string;
+export declare function findGlobalConfig(): string | null;
+export declare function isGlobalConfigPath(configPath: string): boolean;
+export declare function sitesDir(): string;
+export declare function siteFolderName(url: string): string;
+export declare function listSites(): SiteRecord[];
+export declare function registerSite(baseUrl: string): SiteRecord;
+export declare function resolveSiteTarget(target?: string, defaultBaseUrl?: string): SiteTarget;
+interface SiteRecord {
+    folder: string;
+    dir: string;
+    url: string;
+    createdAt: string;
+    lastRunAt: string;
+}
+interface SiteTarget {
+    baseUrl: string;
+    path: string;
+}
+export type { SiteRecord, SiteTarget };

package/dist/src/global-config.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import { join } from 'node:path';
+const GLOBAL_CONFIG_NAMES = ['config.js', 'config.mjs', 'config.ts'];
+const SITE_DIRS = ['knowledge', 'experience', 'output'];
+export function globalDir() {
+    return join(os.homedir(), '.explorbot');
+}
+export function globalEnvPath() {
+    return join(globalDir(), '.env');
+}
+export function globalConfigPath() {
+    return join(globalDir(), 'config.js');
+}
+export function findGlobalConfig() {
+    for (const name of GLOBAL_CONFIG_NAMES) {
+        const fullPath = join(globalDir(), name);
+        if (existsSync(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+export function isGlobalConfigPath(configPath) {
+    return GLOBAL_CONFIG_NAMES.some((name) => join(globalDir(), name) === configPath);
+}
+export function sitesDir() {
+    return join(globalDir(), 'sites');
+}
+export function siteFolderName(url) {
+    return new URL(url).host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+}
+export function listSites() {
+    if (!existsSync(sitesDir()))
+        return [];
+    return readdirSync(sitesDir(), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => readSite(entry.name))
+        .filter((site) => !!site)
+        .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
+}
+export function registerSite(baseUrl) {
+    const folder = siteFolderName(baseUrl);
+    const dir = join(sitesDir(), folder);
+    for (const subDir of SITE_DIRS) {
+        mkdirSync(join(dir, subDir), { recursive: true, mode: 0o700 });
+    }
+    const now = new Date().toISOString();
+    const meta = {
+        url: baseUrl,
+        createdAt: readSite(folder)?.createdAt || now,
+        lastRunAt: now,
+    };
+    writeFileSync(join(dir, 'site.json'), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+    return { folder, dir, ...meta };
+}
+export function resolveSiteTarget(target, defaultBaseUrl) {
+    const raw = (target || process.env.EXPLORBOT_URL || defaultBaseUrl || '').trim();
+    if (!raw) {
+        throw new Error(withSites('No site to explore. Pass a URL to the command or set EXPLORBOT_URL.'));
+    }
+    if (raw.startsWith('http://') || raw.startsWith('https://')) {
+        const url = new URL(raw);
+        return { baseUrl: url.origin, path: `${url.pathname}${url.search}${url.hash}` };
+    }
+    if (raw.startsWith('/')) {
+        const base = defaultBaseUrl || process.env.EXPLORBOT_URL;
+        if (!base) {
+            throw new Error(withSites(`Cannot resolve path "${raw}" without a site.`));
+        }
+        return { baseUrl: new URL(base).origin, path: raw };
+    }
+    let reference = raw;
+    let path = '/';
+    const separator = raw.indexOf('/');
+    if (separator > -1) {
+        reference = raw.slice(0, separator);
+        path = raw.slice(separator);
+    }
+    const site = findSite(reference);
+    if (!site) {
+        throw new Error(withSites(`Unknown site "${reference}".`));
+    }
+    return { baseUrl: site.url, path };
+}
+function readSite(folder) {
+    const dir = join(sitesDir(), folder);
+    const metaPath = join(dir, 'site.json');
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+        new URL(meta.url);
+        return { folder, dir, url: meta.url, createdAt: meta.createdAt, lastRunAt: meta.lastRunAt };
+    }
+    catch {
+        return null;
+    }
+}
+function findSite(reference) {
+    const normalized = reference.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+    const sites = listSites();
+    const byFolder = sites.find((site) => site.folder === normalized);
+    if (byFolder)
+        return byFolder;
+    return sites.find((site) => new URL(site.url).host.toLowerCase() === reference.toLowerCase()) || null;
+}
+function withSites(message) {
+    const lines = [message];
+    const sites = listSites();
+    if (sites.length) {
+        lines.push('Registered sites:');
+        for (const site of sites)
+            lines.push(`  ${site.folder} → ${site.url}`);
+    }
+    lines.push('Explore a new site by passing its full URL, e.g. https://app.example.com/login');
+    return lines.join('\n');
+}

package/dist/src/knowledge-tracker.d.ts

@@ -1,4 +1,5 @@
 import { ActionResult } from './action-result.js';
+import { ApplicationSpec } from './application-spec.js';
 export interface Knowledge {
     filePath: string;
     url: string;
@@ -9,10 +10,13 @@ export declare class KnowledgeTracker {
     knowledgeDir: string;
     knowledgeFiles: Knowledge[];
     isLoaded: boolean;
-    constructor();
+    applicationSpec?: ApplicationSpec;
+    constructor(applicationSpecPath?: string);
     loadKnowledgeFiles(): void;
     getRelevantKnowledge(state: ActionResult): Knowledge[];
     renderRelevantKnowledge(state: ActionResult): string;
+    renderRelevantContext(state: ActionResult): string;
+    renderApplicationSpec(state: ActionResult): string;
     addKnowledge(urlPattern: string, description: string): {
         filename: string;
         filePath: string;

package/dist/src/knowledge-tracker.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import dedent from 'dedent';
 import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
+import { ApplicationSpec } from "./application-spec.js";
 import { ConfigParser } from './config.js';
 import { getCliName } from "./utils/cli-name.js";
 import { createDebug, pluralize, tag } from './utils/logger.js';
@@ -15,13 +16,19 @@ export class KnowledgeTracker {
     knowledgeDir;
     knowledgeFiles = [];
     isLoaded = false;
-    constructor() {
+    applicationSpec;
+    constructor(applicationSpecPath) {
         const configParser = ConfigParser.getInstance();
         const config = configParser.getConfig();
         this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
         if (!existsSync(this.knowledgeDir)) {
             mkdirSync(this.knowledgeDir, { recursive: true });
         }
+        const specPath = applicationSpecPath || config.dirs?.spec;
+        if (specPath) {
+            this.applicationSpec = new ApplicationSpec(specPath);
+            tag('info').log(`Loaded application spec with ${this.applicationSpec.pageCount} documented pages`);
+        }
     }
     loadKnowledgeFiles() {
         if (this.isLoaded)
@@ -60,6 +67,12 @@ export class KnowledgeTracker {
       </knowledge>
     `;
     }
+    renderRelevantContext(state) {
+        return [this.renderRelevantKnowledge(state), this.renderApplicationSpec(state)].filter(Boolean).join('\n\n');
+    }
+    renderApplicationSpec(state) {
+        return this.applicationSpec?.renderFor(state) || '';
+    }
     addKnowledge(urlPattern, description) {
         const configParser = ConfigParser.getInstance();
         const configPath = configParser.getConfigPath();

package/dist/src/playwright-recorder.js

@@ -292,8 +292,38 @@ function formatSelectOption(options) {
         return quote(values[0]);
     return `[${values.map((v) => quote(v)).join(', ')}]`;
 }
+function assertionLocator(target) {
+    if (typeof target === 'string')
+        return `page.locator(${JSON.stringify(target)})`;
+    if (!target || typeof target !== 'object')
+        return null;
+    const role = target.role || target.aria;
+    const name = target.text ?? target.name ?? target.label;
+    if (role && name)
+        return `page.getByRole(${JSON.stringify(String(role))}, { name: ${JSON.stringify(String(name))} })`;
+    if (role)
+        return `page.getByRole(${JSON.stringify(String(role))})`;
+    if (name)
+        return `page.getByText(${JSON.stringify(String(name))})`;
+    if (target.css)
+        return `page.locator(${JSON.stringify(String(target.css))})`;
+    if (target.xpath)
+        return `page.locator(${JSON.stringify(`xpath=${target.xpath}`)})`;
+    return null;
+}
 export function renderAssertion(assertion) {
     const args = assertion.args;
+    const target = assertionLocator(args[0]);
+    if (target) {
+        if (assertion.name === 'seeElement')
+            return `await expect(${target}).toBeVisible();`;
+        if (assertion.name === 'dontSeeElement')
+            return `await expect(${target}).toBeHidden();`;
+        if (assertion.name === 'seeInField' && args[1] !== undefined)
+            return `await expect(${target}).toHaveValue(${JSON.stringify(String(args[1]))});`;
+        if (assertion.name === 'dontSeeInField' && args[1] !== undefined)
+            return `await expect(${target}).not.toHaveValue(${JSON.stringify(String(args[1]))});`;
+    }
     if (assertion.name === 'see' && typeof args[0] === 'string') {
         return `await expect(page).toContainText(${JSON.stringify(args[0])});`;
     }

package/dist/src/remote.d.ts

@@ -0,0 +1,54 @@
+import type { Command } from 'commander';
+import { type ActivityEntry } from './activity.js';
+import { type LogDestination, type TaggedLogEntry } from './utils/logger.js';
+/**
+ * Streams a run to a remote UI over one WebSocket, dialling out so a child
+ * process and a CI bot are the same case.
+ *
+ * It **is** a LogDestination — that is the whole integration on the logger's
+ * side — and it answers asks by installing itself as the execution
+ * controller's input callback. Nothing else in explorbot knows it exists.
+ */
+export declare class Remote implements LogDestination {
+    url: string | null;
+    socket: WebSocket | null;
+    queue: Frame[];
+    reconnectDelay: number;
+    reconnectTimer: ReturnType<typeof setTimeout> | null;
+    asks: Map<string, (value: string | null) => void>;
+    askCounter: number;
+    lastActivity: string | null;
+    registerOption(program: Command): void;
+    attach(url: string, command: string): void;
+    isAttached(): boolean;
+    send(type: string, data?: Record<string, unknown>): void;
+    ask(prompt: string): Promise<string | null>;
+    close(exitCode: number): Promise<void>;
+    isEnabled(): boolean;
+    /**
+     * The entry as the logger already built it, so the `LogType` reaches the UI
+     * as the frame's level and each kind is styled there instead of being scraped
+     * back out of flattened text.
+     */
+    write(entry: TaggedLogEntry): void;
+    connect(): void;
+    reconnect(): void;
+    flush(): Promise<void>;
+    drain(): void;
+    push(frame: Frame): void;
+    receive(raw: string): void;
+    /** A new listener is primed with the current activity, which at attach time is
+     *  nothing — so skip repeats, the priming null included. */
+    reportActivity(activity: ActivityEntry | null): void;
+    errorOf(args: any[] | undefined): string | undefined;
+    commandPath(command: Command): string;
+}
+export declare const remote: Remote;
+/** Whatever the run wants to say. Not a schema — the UI renders what it knows
+ *  and ignores the rest, so either side can start sending more at any time. */
+type Frame = {
+    type: string;
+    ts: number;
+    [key: string]: unknown;
+};
+export {};

package/dist/src/remote.js

@@ -0,0 +1,229 @@
+import stripAnsi from 'strip-ansi';
+import { addActivityListener } from "./activity.js";
+import { executionController } from "./execution-controller.js";
+import { addDestination } from "./utils/logger.js";
+const QUEUE_CAP = 1000;
+const CONTENT_CAP = 8000;
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 10_000;
+const ASK_TIMEOUT_MS = 15 * 60_000;
+const FLUSH_TIMEOUT_MS = 3000;
+/**
+ * Streams a run to a remote UI over one WebSocket, dialling out so a child
+ * process and a CI bot are the same case.
+ *
+ * It **is** a LogDestination — that is the whole integration on the logger's
+ * side — and it answers asks by installing itself as the execution
+ * controller's input callback. Nothing else in explorbot knows it exists.
+ */
+export class Remote {
+    url = null;
+    socket = null;
+    queue = [];
+    reconnectDelay = RECONNECT_BASE_MS;
+    reconnectTimer = null;
+    asks = new Map();
+    askCounter = 0;
+    lastActivity = null;
+    registerOption(program) {
+        program.option('--ws <url>', 'Stream this run to a remote UI over WebSocket');
+        program.hook('preAction', (_thisCommand, actionCommand) => {
+            const url = actionCommand.optsWithGlobals().ws || process.env.EXPLORBOT_WS_URL;
+            if (!url)
+                return;
+            this.attach(String(url), this.commandPath(actionCommand));
+        });
+    }
+    attach(url, command) {
+        if (this.url)
+            return;
+        this.url = url;
+        this.connect();
+        this.send('hello', { command, cwd: process.cwd(), pid: process.pid });
+        addDestination(this);
+        executionController.setInputCallback((prompt) => this.ask(prompt));
+        addActivityListener((activity) => this.reportActivity(activity));
+    }
+    isAttached() {
+        return !!this.url;
+    }
+    send(type, data = {}) {
+        if (!this.url)
+            return;
+        const frame = { type, ts: Date.now(), ...data };
+        if (this.socket?.readyState === WebSocket.OPEN) {
+            this.push(frame);
+            return;
+        }
+        this.queue.push(frame);
+        if (this.queue.length > QUEUE_CAP)
+            this.queue.splice(0, this.queue.length - QUEUE_CAP);
+    }
+    ask(prompt) {
+        if (!this.url)
+            return Promise.resolve(null);
+        this.askCounter++;
+        const askId = `ask-${this.askCounter}`;
+        this.send('ask', { askId, prompt });
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.asks.delete(askId);
+                resolve(null);
+            }, ASK_TIMEOUT_MS);
+            this.asks.set(askId, (value) => {
+                clearTimeout(timer);
+                resolve(value);
+            });
+        });
+    }
+    async 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;
+    }
+    isEnabled() {
+        return this.isAttached();
+    }
+    /**
+     * The entry as the logger already built it, so the `LogType` reaches the UI
+     * as the frame's level and each kind is styled there instead of being scraped
+     * back out of flattened text.
+     */
+    write(entry) {
+        if (entry.type === 'html')
+            return;
+        let content = stripAnsi(entry.content ?? '');
+        if (content.length > CONTENT_CAP)
+            content = `${content.slice(0, CONTENT_CAP)}… (${content.length} chars)`;
+        this.send('log', {
+            level: entry.type,
+            content,
+            namespace: entry.namespace,
+            error: this.errorOf(entry.originalArgs),
+        });
+    }
+    connect() {
+        if (!this.url)
+            return;
+        let opening;
+        try {
+            opening = new WebSocket(this.url);
+        }
+        catch {
+            this.reconnect();
+            return;
+        }
+        this.socket = opening;
+        opening.addEventListener('open', () => {
+            this.reconnectDelay = RECONNECT_BASE_MS;
+            this.drain();
+        });
+        opening.addEventListener('message', (event) => this.receive(String(event.data)));
+        opening.addEventListener('close', () => {
+            if (this.socket !== opening)
+                return;
+            this.socket = null;
+            this.reconnect();
+        });
+        // A failed connection always closes too, which is where the retry is scheduled.
+        opening.addEventListener('error', () => { });
+    }
+    reconnect() {
+        if (!this.url || this.reconnectTimer)
+            return;
+        const delay = this.reconnectDelay;
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+    async flush() {
+        const deadline = Date.now() + FLUSH_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (this.socket?.readyState === WebSocket.OPEN) {
+                this.drain();
+                if (!this.queue.length && !this.socket.bufferedAmount)
+                    return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+    drain() {
+        if (this.socket?.readyState !== WebSocket.OPEN)
+            return;
+        const pending = this.queue;
+        this.queue = [];
+        for (const frame of pending)
+            this.push(frame);
+    }
+    push(frame) {
+        try {
+            this.socket?.send(JSON.stringify(frame));
+        }
+        catch {
+            this.queue.push(frame);
+        }
+    }
+    receive(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (frame.type === 'interrupt') {
+            executionController.interrupt();
+            return;
+        }
+        const resolve = this.asks.get(String(frame.askId));
+        if (!resolve)
+            return;
+        this.asks.delete(String(frame.askId));
+        resolve(frame.value ?? null);
+    }
+    /** A new listener is primed with the current activity, which at attach time is
+     *  nothing — so skip repeats, the priming null included. */
+    reportActivity(activity) {
+        const message = activity?.message ?? null;
+        if (message === this.lastActivity)
+            return;
+        this.lastActivity = message;
+        this.send('activity', { message, kind: activity?.type });
+    }
+    errorOf(args) {
+        const failure = args?.[1] ?? args?.[0]?.error;
+        if (!failure)
+            return undefined;
+        if (typeof failure === 'string')
+            return failure;
+        if (typeof failure.message === 'string')
+            return failure.message;
+        return undefined;
+    }
+    commandPath(command) {
+        const parts = [];
+        let node = command;
+        while (node) {
+            parts.unshift(node.name());
+            node = node.parent;
+        }
+        return parts.slice(1).join(' ') || parts.join(' ');
+    }
+}
+export const remote = new Remote();

package/dist/src/reporter.d.ts

@@ -26,6 +26,7 @@ export declare class Reporter {
     combineStepsAndNotes(test: Test, lastScreenshotFile?: string): Step[];
     buildVerificationStep(test: Test, lastScreenshotFile?: string): Step | undefined;
     reportTest(test: Test, meta?: ReporterMeta): Promise<void>;
+    reportTestData(status: string | null, testData: Record<string, unknown>): Promise<void>;
     finishRun(): Promise<void>;
     isEnabled(): boolean;
     setRunDescription(text: string): Promise<void>;

package/dist/src/reporter.js

@@ -242,13 +242,19 @@ export class Reporter {
                 time: durationMs != null ? Math.round(durationMs) : 0,
             };
             debugLog(testData);
-            await this.client.addTestRun(status, testData);
+            await this.reportTestData(status, testData);
             debugLog(`Test reported: ${test.scenario} - ${status}`);
         }
         catch (error) {
             debugLog('Failed to report test:', error);
         }
     }
+    async reportTestData(status, testData) {
+        await this.startRun();
+        if (!this.isRunStarted)
+            return;
+        await this.client.addTestRun(status, testData);
+    }
     async finishRun() {
         if (!this.isRunStarted) {
             return;

package/dist/src/state-manager.d.ts

@@ -1,4 +1,4 @@
-import { ActionResult } from './action-result.js';
+import { type FocusedElement, ActionResult } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
 export interface Link {
@@ -37,6 +37,7 @@ export interface WebPageState {
     h4?: string;
     ariaSnapshot?: string | null;
     ariaSnapshotFile?: string;
+    focusedElement?: FocusedElement | null;
     links?: Link[];
     verifications?: Record<string, boolean>;
 }

package/dist/src/stats.d.ts

@@ -13,6 +13,7 @@ export declare class Stats {
     static plans: number;
     static mode?: ExplorbotMode;
     static focus?: string;
+    static visionDisabled: boolean;
     static models: Record<string, TokenUsage>;
     static recordTokens(_agent: string, model: string, usage: TokenUsage): void;
     static getElapsedTime(): string;

package/dist/src/stats.js

@@ -7,6 +7,7 @@ export class Stats {
     static plans = 0;
     static mode;
     static focus;
+    static visionDisabled = false;
     static models = {};
     static recordTokens(_agent, model, usage) {
         if (!Stats.models[model]) {

package/dist/src/test-plan.d.ts

@@ -18,6 +18,7 @@ export interface Note {
     endTime: number;
     screenshot?: string;
     log?: string;
+    observation?: boolean;
 }
 export declare class ActiveNote {
     task: Task;
@@ -56,6 +57,7 @@ export declare class Task {
     getPrintableNotes(): string[];
     notesToString(): string;
     addNote(message: string, status?: TestResultType, screenshot?: string, log?: string): void;
+    addObservation(message: string): void;
     addUrlNote(state: UrlNoteState, prevState?: {
         title?: string;
         h1?: string;

package/dist/src/test-plan.js

@@ -91,6 +91,13 @@ export class Task {
         const timestamp = `${now}_${this.timestampCounter++}`;
         this.notes[timestamp] = { message, status, startTime: now, endTime: now, screenshot, log };
     }
+    addObservation(message) {
+        const isDuplicate = Object.values(this.notes).some((note) => note.message === message);
+        if (isDuplicate)
+            return;
+        const now = performance.now();
+        this.notes[`${now}_${this.timestampCounter++}`] = { message, status: TestResult.FAILED, startTime: now, endTime: now, observation: true };
+    }
     addUrlNote(state, prevState) {
         const fullUrl = state.fullUrl || state.url;
         if (!fullUrl)

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

@@ -3,17 +3,11 @@ export interface FocusAreaResult {
     type: 'dialog' | 'modal' | null;
     name: string | null;
 }
-export declare const compactAriaSnapshot: (snapshot: string | null, keepNamed?: boolean) => string;
+export type ValueOffload = (value: string) => string | undefined;
+export declare const compactAriaSnapshot: (snapshot: string | null, keepNamed?: boolean, offload?: ValueOffload) => string;
 export declare const diffAriaSnapshots: (previous: string | null, current: string | null) => AriaDiff;
 export declare const detectFocusArea: (snapshot: string | null) => FocusAreaResult;
 export declare const collectInteractiveNodes: (snapshot: string | null) => Array<Record<string, unknown>>;
-export interface FocusedElementInfo {
-    role: string;
-    name: string;
-    value?: string;
-    attributes?: string[];
-}
-export declare function extractFocusedElement(ariaSnapshot: string | null): FocusedElementInfo | null;
 export declare function parseAriaLocator(ariaStr: string): {
     role: string;
     text: string;