explorbot 0.2.1 → 0.2.3

package/boat/doc-collector/src/interaction-screenshots.ts

@@ -0,0 +1,160 @@
+import { writeFileSync } from 'node:fs';
+import pixelmatch from 'pixelmatch';
+import type { Page } from 'playwright';
+import { PNG } from 'pngjs';
+
+const REGION_PADDING = 30;
+const SCREENSHOT_OPTIONS = { animations: 'disabled', caret: 'hide' } as const;
+
+export async function captureInteractionBefore(page: Page): Promise<Buffer | null> {
+  await removeVisualAnnotations(page);
+  try {
+    return await page.screenshot(SCREENSHOT_OPTIONS);
+  } catch {
+    return null;
+  }
+}
+
+export async function captureInteractionAfter(page: Page, beforeScreenshot: Buffer | null, filePath: string, detectUnmarkedOverlay = false): Promise<InteractionCaptureResult> {
+  if (!beforeScreenshot) return 'failed';
+
+  await removeVisualAnnotations(page);
+  try {
+    const afterScreenshot = await page.screenshot(SCREENSHOT_OPTIONS);
+    const before = PNG.sync.read(beforeScreenshot);
+    const after = PNG.sync.read(afterScreenshot);
+    if (before.width !== after.width || before.height !== after.height) return 'failed';
+    const changedPixels = findChangedPixelBounds(before, after);
+    if (!changedPixels) return 'unchanged';
+    const fullViewportChanged = changedPixels.x === 0 && changedPixels.y === 0 && changedPixels.width === after.width && changedPixels.height === after.height;
+    const changedRegion = addPadding(changedPixels, after.width, after.height);
+    const overlayRegion = fullViewportChanged ? await findOverlayRegion(page, after, detectUnmarkedOverlay) : null;
+    saveRegion(after, overlayRegion || changedRegion, filePath);
+    return 'captured';
+  } catch {
+    return 'failed';
+  }
+}
+
+export function findChangedRegion(beforeScreenshot: Buffer, afterScreenshot: Buffer, padding = REGION_PADDING): ScreenshotRegion | null {
+  const before = PNG.sync.read(beforeScreenshot);
+  const after = PNG.sync.read(afterScreenshot);
+  if (before.width !== after.width || before.height !== after.height) return null;
+  const changedPixels = findChangedPixelBounds(before, after);
+  return changedPixels ? addPadding(changedPixels, before.width, before.height, padding) : null;
+}
+
+function saveRegion(after: PNG, region: ScreenshotRegion, filePath: string): void {
+  const cropped = new PNG({ width: region.width, height: region.height });
+  PNG.bitblt(after, cropped, region.x, region.y, region.width, region.height, 0, 0);
+  writeFileSync(filePath, PNG.sync.write(cropped));
+}
+
+function findChangedPixelBounds(before: PNG, after: PNG): ScreenshotRegion | null {
+  const diff = Buffer.alloc(before.width * before.height * 4);
+  const changedPixels = pixelmatch(before.data, after.data, diff, before.width, before.height, { diffMask: true });
+  if (changedPixels === 0) return null;
+
+  let left = before.width;
+  let top = before.height;
+  let right = 0;
+  let bottom = 0;
+
+  for (let y = 0; y < before.height; y++) {
+    for (let x = 0; x < before.width; x++) {
+      if (diff[(y * before.width + x) * 4 + 3] === 0) continue;
+      left = Math.min(left, x);
+      top = Math.min(top, y);
+      right = Math.max(right, x);
+      bottom = Math.max(bottom, y);
+    }
+  }
+
+  return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+}
+
+function addPadding(region: ScreenshotRegion, imageWidth: number, imageHeight: number, padding = REGION_PADDING): ScreenshotRegion {
+  const x = Math.max(0, region.x - padding);
+  const y = Math.max(0, region.y - padding);
+  const maxX = Math.min(imageWidth, region.x + region.width + padding);
+  const maxY = Math.min(imageHeight, region.y + region.height + padding);
+  return { x, y, width: maxX - x, height: maxY - y };
+}
+
+async function removeVisualAnnotations(page: Page): Promise<void> {
+  try {
+    await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+      for (const element of elements) element.remove();
+    });
+  } catch {}
+}
+
+async function findOverlayRegion(page: Page, image: PNG, detectUnmarkedOverlay: boolean): Promise<ScreenshotRegion | null> {
+  let box: { x: number; y: number; width: number; height: number } | null = null;
+  try {
+    const dialogs = page.locator('[role="dialog"]:visible, [role="alertdialog"]:visible, [aria-modal="true"]:visible');
+    if ((await dialogs.count()) > 0) box = await dialogs.last().boundingBox();
+  } catch {}
+
+  if (!box && detectUnmarkedOverlay) {
+    try {
+      box = await findUnmarkedOverlay(page);
+    } catch {}
+  }
+
+  try {
+    const viewport = page.viewportSize();
+    if (!box || !viewport) return null;
+
+    const scaleX = image.width / viewport.width;
+    const scaleY = image.height / viewport.height;
+    const x = Math.max(0, Math.floor(box.x * scaleX) - REGION_PADDING);
+    const y = Math.max(0, Math.floor(box.y * scaleY) - REGION_PADDING);
+    const maxX = Math.min(image.width, Math.ceil((box.x + box.width) * scaleX) + REGION_PADDING);
+    const maxY = Math.min(image.height, Math.ceil((box.y + box.height) * scaleY) + REGION_PADDING);
+    if (maxX <= x || maxY <= y) return null;
+    return { x, y, width: maxX - x, height: maxY - y };
+  } catch {
+    return null;
+  }
+}
+
+async function findUnmarkedOverlay(page: Page): Promise<{ x: number; y: number; width: number; height: number } | null> {
+  return page.evaluate(() => {
+    const elements = [...document.body.querySelectorAll('*')].map((element) => {
+      const style = getComputedStyle(element);
+      const box = element.getBoundingClientRect();
+      const zIndex = Number.parseInt(style.zIndex, 10);
+      return { element, style, box, zIndex, area: box.width * box.height };
+    });
+    const isVisibleLayer = ({ style, box, zIndex }: (typeof elements)[number]) => {
+      if (style.visibility === 'hidden' || style.display === 'none' || Number(style.opacity) === 0) return false;
+      if (box.width <= 0 || box.height <= 0) return false;
+      if (style.position !== 'fixed' && style.position !== 'absolute') return false;
+      return Number.isFinite(zIndex);
+    };
+    const backdropZIndex = elements.filter((item) => isVisibleLayer(item) && item.box.width >= window.innerWidth && item.box.height >= window.innerHeight).reduce((highest, item) => Math.max(highest, item.zIndex), Number.NEGATIVE_INFINITY);
+    if (!Number.isFinite(backdropZIndex)) return null;
+
+    const candidates = elements
+      .filter((item) => {
+        if (!isVisibleLayer(item)) return false;
+        if (item.box.width >= window.innerWidth && item.box.height >= window.innerHeight) return false;
+        if (item.zIndex < backdropZIndex) return false;
+        return item.element.matches('button, input, select, textarea, a[href]') || !!item.element.querySelector('button, input, select, textarea, a[href]');
+      })
+      .sort((left, right) => right.zIndex - left.zIndex || left.area - right.area);
+    const box = candidates[0]?.box;
+    if (!box) return null;
+    return { x: box.x, y: box.y, width: box.width, height: box.height };
+  });
+}
+
+export interface ScreenshotRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type InteractionCaptureResult = 'captured' | 'unchanged' | 'failed';

package/boat/doc-collector/src/screenshots.ts

@@ -3,10 +3,10 @@ import path from 'node:path';
 import { parseResearchSections } from '../../../src/ai/researcher/parser.ts';
 import type Explorer from '../../../src/explorer.ts';
 import type { WebPageState } from '../../../src/state-manager.ts';
-import { detectFocusArea } from '../../../src/utils/aria.ts';
 import { safeFilename, sanitizeFilename } from '../../../src/utils/strings.ts';
 import type { DocStateTransition } from './ai/tools.ts';
 import type { DocbotConfig } from './config.ts';
+import { captureInteractionAfter, captureInteractionBefore } from './interaction-screenshots.ts';
 
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
 
@@ -61,7 +61,7 @@ export function getScreenshotSections(research: string): ScreenshotSection[] {
   return sections;
 }
 
-export async function captureInteractionScreenshot(explorer: Explorer, state: WebPageState, transition: DocStateTransition, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
+export async function captureInteractionScreenshot(explorer: Explorer, beforeScreenshot: Buffer | null, state: WebPageState, transition: DocStateTransition, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
   const page = explorer.page;
   if (!page) {
     return null;
@@ -70,18 +70,11 @@ export async function captureInteractionScreenshot(explorer: Explorer, state: We
   mkdirSync(options.screenshotsDir, { recursive: true });
   const pageName = sanitizeFilename(state.url || 'page') || 'page';
   const stateName = sanitizeFilename(transition.targetState?.label || transition.action) || 'state';
-  const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}`, '.png'));
-  const focus = detectFocusArea(state.ariaSnapshot || null);
-
-  try {
-    if (focus.detected) {
-      await page.locator('[role="dialog"], [role="alertdialog"], [aria-modal="true"]').last().screenshot({ path: filePath });
-    } else {
-      await page.screenshot({ path: filePath });
-    }
-  } catch {
-    return null;
-  }
+  const stateId = state.id ? `_${state.id}` : '';
+  const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}${stateId}`, '.png'));
+  const result = await captureInteractionAfter(page, beforeScreenshot, filePath, transition.changes?.urlChanged !== true);
+  if (result === 'unchanged') return null;
+  if (result === 'failed' && !(await captureViewport(page, filePath))) return null;
 
   return {
     title: transition.targetState?.label || transition.action,
@@ -91,6 +84,21 @@ export async function captureInteractionScreenshot(explorer: Explorer, state: We
   };
 }
 
+export async function captureBeforeInteraction(explorer: Explorer): Promise<Buffer | null> {
+  const page = explorer.page;
+  if (!page) return null;
+  return captureInteractionBefore(page);
+}
+
+async function captureViewport(page: any, filePath: string): Promise<boolean> {
+  try {
+    await page.screenshot({ path: filePath });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function captureFullPageScreenshot(page: any, pageName: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
   const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
   try {

package/boat/doc-collector/src/state-diagram.ts

@@ -69,8 +69,12 @@ function buildStateGraph(outputDir: string, pages: DocumentedPage[]): StateGraph
         continue;
       }
 
-      const pairKey = `${sourceId}>${targetId}`;
-      if (adjacency.get(targetId)?.has(sourceId)) {
+      if (adjacency.get(sourceId)?.has(targetId)) {
+        continue;
+      }
+
+      if (createsCycle(sourceId, targetId, adjacency)) {
+        const pairKey = `${sourceId}>${targetId}`;
         if (drawnBack.has(pairKey)) {
           continue;
         }
@@ -78,10 +82,6 @@ function buildStateGraph(outputDir: string, pages: DocumentedPage[]): StateGraph
         edges.push({ source: sourceId, target: targetId, action: transition.action, isBack: true });
         continue;
       }
-
-      if (adjacency.get(sourceId)?.has(targetId) || createsCycle(sourceId, targetId, adjacency)) {
-        continue;
-      }
       adjacency.get(sourceId)?.add(targetId);
       edges.push({ source: sourceId, target: targetId, action: transition.action, isBack: false });
     }
@@ -104,8 +104,8 @@ function renderMermaidBody(outputDir: string, pages: DocumentedPage[]): string {
   return renderMermaidFromGraph(buildStateGraph(outputDir, pages));
 }
 
-function renderMermaidFromGraph(graph: StateGraph): string {
-  const lines: string[] = ['flowchart TD'];
+function renderMermaidFromGraph(graph: StateGraph, compact = false): string {
+  const lines: string[] = [compact ? 'flowchart LR' : 'flowchart TD'];
   if (graph.pages.length === 0) {
     lines.push('  empty["No documented states"]');
     return lines.join('\n');
@@ -117,6 +117,12 @@ function renderMermaidFromGraph(graph: StateGraph): string {
     if (!children || children.length === 0) {
       continue;
     }
+    if (compact) {
+      for (const child of children) {
+        lines.push(`  ${renderNodeLine(child)}`);
+      }
+      continue;
+    }
     lines.push(`  subgraph sg_${page.id} ["${escapeMermaidLabel(page.label)} — transient states"]`);
     for (const child of children) {
       lines.push(`    ${renderNodeLine(child)}`);
@@ -125,11 +131,12 @@ function renderMermaidFromGraph(graph: StateGraph): string {
   }
 
   for (const edge of graph.edges) {
-    let arrow = '-->';
-    if (edge.isBack) {
-      arrow = '-.->';
+    const arrow = edge.isBack ? '-.->' : '-->';
+    if (compact) {
+      lines.push(`  ${edge.source} ${arrow} ${edge.target}`);
+    } else {
+      lines.push(`  ${edge.source} ${arrow}|"${escapeMermaidLabel(edge.action)}"| ${edge.target}`);
     }
-    lines.push(`  ${edge.source} ${arrow}|"${escapeMermaidLabel(edge.action)}"| ${edge.target}`);
   }
 
   lines.push('  classDef page fill:#dbeafe,stroke:#2563eb,color:#0f172a;');
@@ -174,6 +181,46 @@ function renderStateMapFromGraph(graph: StateGraph): string {
   return rows.join('\n');
 }
 
+function renderPageStateDiagram(label: string, url: string, interactions: StateTransition[]): string {
+  const targets = new Map<string, { node: StateNode; action: string; screenshot?: { title: string; relativePath: string } }>();
+  let index = 0;
+  for (const interaction of interactions) {
+    const targetState = interaction.targetState;
+    if (!targetState) {
+      continue;
+    }
+    const key = `${targetState.kind}:${targetState.label}:${normalizeUrl(targetState.url)}`;
+    if (targets.has(key)) {
+      continue;
+    }
+    targets.set(key, {
+      node: { id: `target${index++}`, kind: targetState.kind, label: targetState.label, subLabel: targetState.kind },
+      action: interaction.action,
+      screenshot: interaction.screenshot,
+    });
+  }
+
+  if (targets.size === 0) {
+    return '';
+  }
+
+  const lines: string[] = ['flowchart LR'];
+  lines.push(`  ${renderNodeLine({ id: 'self', kind: 'page', label, subLabel: url })}`);
+  for (const target of targets.values()) {
+    lines.push(`  ${renderNodeLine(target.node)}`);
+  }
+  for (const target of targets.values()) {
+    lines.push(`  self -->|"${escapeMermaidLabel(target.action)}"| ${target.node.id}`);
+  }
+  for (const target of targets.values()) {
+    if (target.screenshot) {
+      lines.push(`  click ${target.node.id} "${target.screenshot.relativePath}" "${escapeMermaidLabel(target.screenshot.title)}"`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
 function renderNodeLine(node: StateNode): string {
   const label = `${escapeMermaidLabel(node.label)}<br/>${escapeMermaidLabel(node.subLabel)}`;
   if (node.kind === 'dialog' || node.kind === 'modal') {
@@ -207,7 +254,7 @@ function createsCycle(sourceId: string, targetId: string, adjacency: Map<string,
 }
 
 function escapeMermaidLabel(value: string): string {
-  return normalizeInlineText(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('|', '&#124;');
+  return normalizeInlineText(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('#', '&#35;').replaceAll('<', '&#60;').replaceAll('>', '&#62;').replaceAll('|', '&#124;');
 }
 
 function escapeTable(value: string): string {
@@ -277,5 +324,5 @@ interface StateGraph {
   classAssignment: Map<StateClass, string[]>;
 }
 
-export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderStateMapFromGraph };
+export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph };
 export type { DocumentedPage, SkippedPage, StateGraph, StateNode, StateEdge, StateClick };

package/boat/prima/bin/prima-cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { createPrimaCommands } from '../src/cli.ts';
+
+const program = createPrimaCommands('prima');
+program.parse();

package/boat/prima/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "prima",
+  "version": "1.0.0",
+  "description": "High-level browser driver CLI for orchestrating agents",
+  "type": "module",
+  "bin": { "prima": "./bin/prima-cli.ts" },
+  "scripts": {
+    "format": "biome format --write .",
+    "lint:fix": "biome lint --write .",
+    "check:fix": "biome check --write ."
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "dedent": "^1.6.0"
+  }
+}

package/boat/prima/src/cli.ts

@@ -0,0 +1,222 @@
+import { Command } from 'commander';
+import dedent from 'dedent';
+import { keepServerRunning } from '../../../src/browser-server.ts';
+import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
+import { setPreserveConsoleLogs } from '../../../src/utils/logger.ts';
+import { type EnvelopeData, renderEnvelope } from './envelope.ts';
+import { Prima, type PrimaOptions } from './prima.ts';
+
+const helpContract = dedent`
+  Prima drives a browser that is already open. One command per process; every command
+  prints a plain-text envelope on stdout and exits 0 when ok, 1 when not.
+
+  TIERS - choose by what you hold, not by how hard the step looks
+    pw <fn>        Precise. A Playwright function expression built from a locator you
+                   already verified. No AI on the happy path.
+                     prima pw "({ page }) => page.click('[data-test=submit]')"
+    click / fill   One action described in words; AI resolves it on the current page.
+                     prima click "the primary action button in the header"
+                     prima fill "the search box" "a search term"
+    do <steps...>  Several described steps, run tester-style in one process.
+                     prima do "open the account menu" "choose the settings entry"
+    Never pass a locator or a function expression to click/fill/do - describe the target.
+    Never pass a description to pw - it takes executable code only.
+
+  LOOP
+    prima go <url|path|words>  reach the page you want to work on
+    prima research             once per new page; returns verified locators
+    prima pw "..."             drive the page with those locators
+    prima verify "..."         assert the outcome (prima ask "..." to inspect instead)
+    Fall back to click/fill/do whenever research left you no locator to hold.
+
+  ENVELOPE
+    ### Result     ok, command, healed, used
+    ### Page       url, title, state hash, visit count
+    ### Changes    what the accessibility tree gained or lost
+    ### Answer | ### Research | ### Verdict   output of ask, research, verify
+    ### Failure    error, reasoning, healing attempts, compact ARIA of the page
+    ### Instance   the browser you are on and the other instances running
+    ### Artifacts  paths to the full aria.yml, page.html and network.jsonl
+    used: is code that already executed - CodeceptJS steps to copy as they are, except
+          for pw, whose Playwright expression a test needs inside I.usePlaywrightTo(...).
+    Log lines can precede the envelope; start parsing at the first ### line.
+
+  HEALING AND FAILURE
+    A failed action is retried by AI along a different route; healed: true means the
+    outcome was reached another way and used: holds the code that worked.
+    --no-heal skips that and fails fast.
+    Failures print compact ARIA inline, so retarget from the envelope itself and open
+    the artifact files only when the inline snapshot is not enough.
+
+  SESSIONS
+    By default prima attaches to the playwright-cli browser of this workspace and works
+    on the tabs it already has open; driving the same session from both tools is the
+    intended usage.
+    playwright-cli open <url>  the session prima attaches to
+    --pw-session <title>       which playwright-cli session, when several are open
+    --endpoint <ep>            attach to a browser server endpoint directly
+    prima browser start        a prima-owned browser instead, when no session is open
+    --instance <name>          which prima-owned browser you talk to; parallel work
+                               needs one each
+    --session [file]           cookies and storage persisted across processes; ignored
+                               while attached, the attached session keeps its own
+    Prima never launches a browser implicitly and never closes an attached one - it
+    disconnects. browser list shows both kinds; ### Instance names the one you are on.
+    Every browser is reached over a Playwright browser-server endpoint, which needs the
+    Node build - run prima as "npx explorbot prima ..." or through the published prima
+    bin; from source under Bun the connection does not open.
+    When no AI model is usable pw still works; for everything else drive
+    playwright-cli directly.
+    Parsed but not active yet: --framework, so reported code is CodeceptJS whatever
+    you pass.
+`;
+
+function buildOptions(options: any): PrimaOptions {
+  return {
+    verbose: options.verbose || options.debug,
+    config: options.config,
+    path: options.path,
+    instance: options.instance,
+    session: options.session,
+    heal: options.heal,
+    ephemeral: options.ephemeral,
+    framework: options.framework,
+    noVision: options.vision === false,
+    url: options.url,
+    baseUrl: options.baseUrl,
+    show: options.show,
+    headless: options.headless,
+    endpoint: options.endpoint,
+    pwSession: options.pwSession,
+  };
+}
+
+function addCommonOptions(cmd: Command): Command {
+  return cmd
+    .option('-v, --verbose', 'Enable verbose logging')
+    .option('--debug', 'Enable debug logging (same as --verbose)')
+    .option('-c, --config <path>', 'Path to explorbot configuration file')
+    .option('-p, --path <path>', 'Working directory path')
+    .option('-i, --instance <name>', 'Browser instance to drive')
+    .option('--session [file]', 'Persist cookies and storage to a session file')
+    .option('--no-heal', 'Fail immediately instead of letting AI retry a failed action')
+    .option('--ephemeral', 'Keep no state between runs; applies to config-free runs, where output goes to a temp directory')
+    .option('--framework <name>', 'Not active yet: framework the reported code targets, codeceptjs or playwright')
+    .option('--url <url>', 'Page to open when the session has no page yet')
+    .option('--endpoint <ep>', 'Websocket endpoint of a browser server to attach to, skipping discovery')
+    .option('--pw-session <title>', 'Title of the playwright-cli session to attach to');
+}
+
+function primaFor(options: any): Prima {
+  setPreserveConsoleLogs(true);
+  if (options.ephemeral) process.env.EXPLORBOT_EPHEMERAL = '1';
+  return new Prima(buildOptions(options));
+}
+
+async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>): Promise<void> {
+  const prima = primaFor(options);
+
+  let envelope: EnvelopeData;
+  try {
+    await prima.start();
+    envelope = await run(prima);
+  } catch (error) {
+    envelope = await prima.toolFailureEnvelope(command, error);
+  }
+
+  console.log(renderEnvelope(envelope));
+  await prima.stop().catch(() => {});
+  process.exit(envelope.ok ? 0 : 1);
+}
+
+async function runBrowser(options: any, run: (prima: Prima) => Promise<boolean>): Promise<void> {
+  let ok = false;
+  try {
+    ok = await run(primaFor(options));
+  } catch (error) {
+    console.error(browserErrorMessage(error));
+    process.exit(1);
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+export function createPrimaCommands(name = 'prima'): Command {
+  const cmd = new Command(name);
+  cmd.description('Drive an already-open browser one command at a time and report back in a plain-text envelope');
+  cmd.addHelpText('after', `\n${helpContract}`);
+
+  addCommonOptions(cmd.command('pw <fn>').description('Run a Playwright function expression against the open page')).action(async (fn, options) => {
+    await runPrima(options, `pw ${fn}`, (prima) => prima.pw(fn));
+  });
+
+  addCommonOptions(cmd.command('do <instructions...>').description('Run high-level instructions tester-style, one argument per instruction')).action(async (instructions, options) => {
+    await runPrima(options, `do ${instructions.join(' ')}`, (prima) => prima.do(instructions));
+  });
+
+  addCommonOptions(cmd.command('click <target>').description('Click an element described in plain words')).action(async (target, options) => {
+    await runPrima(options, `click ${target}`, (prima) => prima.click(target));
+  });
+
+  addCommonOptions(cmd.command('fill <field> <value>').description('Fill a field described in plain words')).action(async (field, value, options) => {
+    await runPrima(options, `fill ${field} ${value}`, (prima) => prima.fill(field, value));
+  });
+
+  addCommonOptions(cmd.command('ask <question>').description('Answer a question about the current page').option('--no-vision', 'Answer from page structure only, without a screenshot')).action(async (question, options) => {
+    await runPrima(options, `ask ${question}`, (prima) => prima.ask(question));
+  });
+
+  addCommonOptions(cmd.command('verify <assertion>').alias('assert').description('Assert a statement about the current page')).action(async (assertion, options) => {
+    await runPrima(options, `verify ${assertion}`, (prima) => prima.verify(assertion));
+  });
+
+  addCommonOptions(
+    cmd.command('research').description('Map the current page and return verified locators').option('--data', 'Include data extraction in the map').option('--deep', 'Expand hidden elements for a deeper map').option('--fresh', 'Ignore the cached map and research the page again')
+  ).action(async (options) => {
+    await runPrima(options, 'research', (prima) => prima.research({ data: options.data, deep: options.deep, fresh: options.fresh }));
+  });
+
+  addCommonOptions(cmd.command('go <target>').description('Navigate to a url, a path, or a page described in plain words')).action(async (target, options) => {
+    if (URL.canParse(target)) options.baseUrl = target;
+    await runPrima(options, `go ${target}`, (prima) => prima.go(target));
+  });
+
+  const browser = cmd.command('browser').description('Manage the browsers prima drives');
+
+  addCommonOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
+    .option('-s, --show', 'Launch the browser in a visible window')
+    .option('--headless', 'Launch the browser without a window')
+    .action(async (options) => {
+      await runBrowser(options, async (prima) => {
+        await prima.browserStart();
+        console.log(await prima.browserStatus());
+        return keepServerRunning(() => prima.browserStop());
+      });
+    });
+
+  addCommonOptions(browser.command('stop').description('Stop the browser of this instance'))
+    .option('--all', 'Stop every running instance')
+    .action(async (options) => {
+      await runBrowser(options, async (prima) => {
+        const stopped = await prima.browserStop(options.all);
+        console.log(await prima.browserStatus());
+        return stopped;
+      });
+    });
+
+  addCommonOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
+    await runBrowser(options, async (prima) => {
+      console.log(await prima.browserStatus());
+      return true;
+    });
+  });
+
+  addCommonOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
+    await runBrowser(options, async (prima) => {
+      console.log(await prima.browserList());
+      return true;
+    });
+  });
+
+  return cmd;
+}