explorbot 0.2.2 → 0.2.4

package/src/global-config.ts

@@ -0,0 +1,148 @@
+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(): string {
+  return join(os.homedir(), '.explorbot');
+}
+
+export function globalEnvPath(): string {
+  return join(globalDir(), '.env');
+}
+
+export function globalConfigPath(): string {
+  return join(globalDir(), 'config.js');
+}
+
+export function findGlobalConfig(): string | null {
+  for (const name of GLOBAL_CONFIG_NAMES) {
+    const fullPath = join(globalDir(), name);
+    if (existsSync(fullPath)) return fullPath;
+  }
+  return null;
+}
+
+export function isGlobalConfigPath(configPath: string): boolean {
+  return GLOBAL_CONFIG_NAMES.some((name) => join(globalDir(), name) === configPath);
+}
+
+export function sitesDir(): string {
+  return join(globalDir(), 'sites');
+}
+
+export function siteFolderName(url: string): string {
+  return new URL(url).host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+}
+
+export function listSites(): SiteRecord[] {
+  if (!existsSync(sitesDir())) return [];
+
+  return readdirSync(sitesDir(), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => readSite(entry.name))
+    .filter((site): site is SiteRecord => !!site)
+    .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
+}
+
+export function registerSite(baseUrl: string): SiteRecord {
+  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?: string, defaultBaseUrl?: string): SiteTarget {
+  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: string): SiteRecord | null {
+  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: string): SiteRecord | null {
+  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: string): string {
+  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');
+}
+
+interface SiteRecord {
+  folder: string;
+  dir: string;
+  url: string;
+  createdAt: string;
+  lastRunAt: string;
+}
+
+interface SiteTarget {
+  baseUrl: string;
+  path: string;
+}
+
+export type { SiteRecord, SiteTarget };

package/src/knowledge-tracker.ts

@@ -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.ts';
 import { ConfigParser } from './config.js';
 import { getCliName } from './utils/cli-name.ts';
 import { createDebug, pluralize, tag } from './utils/logger.js';
@@ -24,8 +25,9 @@ export class KnowledgeTracker {
   private knowledgeDir: string;
   private knowledgeFiles: Knowledge[] = [];
   private isLoaded = false;
+  private applicationSpec?: ApplicationSpec;
 
-  constructor() {
+  constructor(applicationSpecPath?: string) {
     const configParser = ConfigParser.getInstance();
     const config = configParser.getConfig();
     this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
@@ -33,6 +35,12 @@ export class KnowledgeTracker {
     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`);
+    }
   }
 
   private loadKnowledgeFiles(): void {
@@ -79,6 +87,14 @@ export class KnowledgeTracker {
     `;
   }
 
+  renderRelevantContext(state: ActionResult): string {
+    return [this.renderRelevantKnowledge(state), this.renderApplicationSpec(state)].filter(Boolean).join('\n\n');
+  }
+
+  renderApplicationSpec(state: ActionResult): string {
+    return this.applicationSpec?.renderFor(state) || '';
+  }
+
   addKnowledge(urlPattern: string, description: string): { filename: string; filePath: string; isNewFile: boolean } {
     const configParser = ConfigParser.getInstance();
     const configPath = configParser.getConfigPath();

package/src/playwright-recorder.ts

@@ -287,8 +287,31 @@ function formatSelectOption(options: any): string {
   return `[${values.map((v) => quote(v)).join(', ')}]`;
 }
 
+function assertionLocator(target: any): string | null {
+  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: { name: string; args: any[] }): string {
   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/src/remote.ts

@@ -0,0 +1,238 @@
+import type { Command } from 'commander';
+import stripAnsi from 'strip-ansi';
+import { type ActivityEntry, addActivityListener } from './activity.ts';
+import { executionController } from './execution-controller.ts';
+import { type LogDestination, type TaggedLogEntry, addDestination } from './utils/logger.ts';
+
+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 implements LogDestination {
+  private url: string | null = null;
+  private socket: WebSocket | null = null;
+  private queue: Frame[] = [];
+  private reconnectDelay = RECONNECT_BASE_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private asks = new Map<string, (value: string | null) => void>();
+  private askCounter = 0;
+  private lastActivity: string | null = null;
+
+  registerOption(program: Command): void {
+    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: string, command: string): void {
+    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(): boolean {
+    return !!this.url;
+  }
+
+  send(type: string, data: Record<string, unknown> = {}): void {
+    if (!this.url) return;
+    const frame: 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: string): Promise<string | null> {
+    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: number): Promise<void> {
+    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(): boolean {
+    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: TaggedLogEntry): void {
+    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),
+    });
+  }
+
+  private connect(): void {
+    if (!this.url) return;
+
+    let opening: WebSocket;
+    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: MessageEvent) => 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', () => {});
+  }
+
+  private reconnect(): void {
+    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?.();
+  }
+
+  private async flush(): Promise<void> {
+    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));
+    }
+  }
+
+  private drain(): void {
+    if (this.socket?.readyState !== WebSocket.OPEN) return;
+    const pending = this.queue;
+    this.queue = [];
+    for (const frame of pending) this.push(frame);
+  }
+
+  private push(frame: Frame): void {
+    try {
+      this.socket?.send(JSON.stringify(frame));
+    } catch {
+      this.queue.push(frame);
+    }
+  }
+
+  private receive(raw: string): void {
+    let frame: 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 as string | null) ?? null);
+  }
+
+  /** A new listener is primed with the current activity, which at attach time is
+   *  nothing — so skip repeats, the priming null included. */
+  private reportActivity(activity: ActivityEntry | null): void {
+    const message = activity?.message ?? null;
+    if (message === this.lastActivity) return;
+    this.lastActivity = message;
+    this.send('activity', { message, kind: activity?.type });
+  }
+
+  private errorOf(args: any[] | undefined): string | undefined {
+    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;
+  }
+
+  private commandPath(command: Command): string {
+    const parts: string[] = [];
+    let node: Command | null = command;
+    while (node) {
+      parts.unshift(node.name());
+      node = node.parent;
+    }
+    return parts.slice(1).join(' ') || parts.join(' ');
+  }
+}
+
+export const remote = new 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 };

package/src/reporter.ts

@@ -283,13 +283,19 @@ export class Reporter {
 
       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: string | null, testData: Record<string, unknown>): Promise<void> {
+    await this.startRun();
+    if (!this.isRunStarted) return;
+    await this.client.addTestRun(status, testData);
+  }
+
   async finishRun(): Promise<void> {
     if (!this.isRunStarted) {
       return;

package/src/state-manager.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';
 import { detectFocusArea } from './utils/aria.js';
@@ -46,6 +46,7 @@ export interface WebPageState {
   h4?: string;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
+  focusedElement?: FocusedElement | null;
   links?: Link[];
   verifications?: Record<string, boolean>;
 }

package/src/stats.ts

@@ -17,6 +17,7 @@ export class Stats {
   static plans = 0;
   static mode?: ExplorbotMode;
   static focus?: string;
+  static visionDisabled = false;
   static models: Record<string, TokenUsage> = {};
 
   static recordTokens(_agent: string, model: string, usage: TokenUsage): void {

package/src/test-plan.ts

@@ -27,6 +27,7 @@ export interface Note {
   endTime: number;
   screenshot?: string;
   log?: string;
+  observation?: boolean;
 }
 
 export class ActiveNote {
@@ -131,6 +132,14 @@ export class Task {
     this.notes[timestamp] = { message, status, startTime: now, endTime: now, screenshot, log };
   }
 
+  addObservation(message: string): void {
+    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: UrlNoteState, prevState?: { title?: string; h1?: string; h2?: string }): void {
     const fullUrl = state.fullUrl || state.url;
     if (!fullUrl) return;