explorbot 0.2.4 → 0.3.0

package/bin/explorbot-cli.ts

@@ -15,7 +15,7 @@ import { remote } from '../src/remote.js';
 import { Stats } from '../src/stats.js';
 import { Plan } from '../src/test-plan.js';
 import { getCliName } from '../src/utils/cli-name.ts';
-import { log, setPreserveConsoleLogs } from '../src/utils/logger.js';
+import { isVerboseMode, log, setPreserveConsoleLogs, setQuietMode } from '../src/utils/logger.js';
 import { jsonToTable } from '../src/utils/markdown-parser.js';
 import { parseMarkdownToTerminal } from '../src/utils/markdown-terminal.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../src/utils/next-steps.ts';
@@ -436,6 +436,23 @@ addCommonOptions(
   await cmd.execute(args);
 });
 
+program
+  .command('config [url]')
+  .description('Show models, config file and paths used by this run')
+  .option('-c, --config <path>', 'Path to configuration file')
+  .option('-p, --path <path>', 'Working directory path')
+  .option('--json', 'Print the resolved config as JSON')
+  .action(async (url, options) => {
+    setQuietMode(!isVerboseMode());
+    const { ConfigCommand } = await import('../src/commands/config-command.js');
+    try {
+      console.log(await ConfigCommand.summary({ config: options.config, path: options.path, url, json: options.json }));
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : 'Unknown error');
+      process.exit(1);
+    }
+  });
+
 program
   .command('init')
   .description('Initialize configuration for a project or for this machine')
@@ -912,11 +929,6 @@ ${rows}
 `;
 };
 
-const addEnvHelp = (cmd: Command) => {
-  cmd.addHelpText('after', envHelp);
-  for (const sub of cmd.commands) addEnvHelp(sub);
-};
-
-addEnvHelp(program);
+program.addHelpText('after', envHelp);
 
 program.parse();

package/boat/api-tester/src/cli.ts

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
+import { ConfigCommand } from '../../../src/commands/config-command.ts';
+import { listSites } from '../../../src/global-config.ts';
 import { setPreserveConsoleLogs } from '../../../src/utils/logger.ts';
 import { getStyles } from './ai/chief/styles.ts';
 import { ApiBot, type ApibotOptions } from './apibot.ts';
+import { ApibotConfigParser } from './config.ts';
 
 function buildOptions(options: any): ApibotOptions {
   return {
@@ -82,6 +85,20 @@ export function createApiCommands(name = 'api'): Command {
     }
   });
 
+  addCommonOptions(cmd.command('config [endpoint]').description('Show models, config file and paths used by this run'))
+    .option('--json', 'Print the resolved config as JSON')
+    .action(async (endpoint, options) => {
+      const parser = ApibotConfigParser.getInstance();
+      const [site] = listSites();
+      try {
+        const config = await parser.loadConfig({ config: options.config, path: options.path, endpoint: endpoint || site?.url });
+        console.log(ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json: options.json }));
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+      }
+    });
+
   addCommonOptions(cmd.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1-3, *')).action(async (planfile, index, options) => {
     setPreserveConsoleLogs(true);
     try {

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

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
-import { setPreserveConsoleLogs } from '../../../src/utils/logger.ts';
+import { ConfigCommand } from '../../../src/commands/config-command.ts';
+import { isVerboseMode, setPreserveConsoleLogs, setQuietMode } from '../../../src/utils/logger.ts';
 import { DocBot, type DocbotOptions } from './docbot.ts';
 
 function buildOptions(options: any): DocbotOptions {
@@ -65,6 +66,18 @@ export function createDocsCommands(name = 'docs'): Command {
     }
   });
 
+  addCommonOptions(cmd.command('config [url]').description('Show models, config file and paths used by this run'))
+    .option('--json', 'Print the resolved config as JSON')
+    .action(async (url, options) => {
+      setQuietMode(!isVerboseMode());
+      try {
+        console.log(await ConfigCommand.summary({ config: options.config, path: options.path, url, json: options.json }));
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+      }
+    });
+
   cmd
     .command('init')
     .description('Initialize doc collector configuration')

package/boat/prima/README.md

@@ -0,0 +1,96 @@
+# prima-cli
+
+Prima is a high-level AI browser driver. You describe the behaviour you want checked, and it works out how to reach it — instead of writing selectors and step-by-step click paths.
+
+It drives a browser opened by [playwright-cli](https://www.npmjs.com/package/playwright-cli), or one of its own.
+
+```bash
+npx prima-cli check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
+```
+
+## Install
+
+```bash
+npx prima-cli --help          # no install
+npm install -g prima-cli      # or install it
+```
+
+Prima also ships inside [explorbot](https://www.npmjs.com/package/explorbot), so `npx explorbot prima <command>` runs the same tool if you already have it.
+
+Requires Node.js 24+. Playwright browsers come from `npx playwright install chromium`.
+
+## Session
+
+Prima needs a browser to drive. Either attach to a `playwright-cli` session:
+
+```bash
+playwright-cli open https://app.example.com
+prima-cli check "the settings page saves a changed theme"
+playwright-cli close
+```
+
+Or let prima own the browser:
+
+```bash
+prima-cli browser start --url https://app.example.com
+prima-cli do "open the account menu" "choose the settings entry"
+prima-cli browser stop
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `check <scenario>` | Run a scenario end to end as a test, verify it, and report the steps it took |
+| `do <instructions...>` | Run high-level instructions tester-style, one argument per instruction |
+| `verify <assertion>` | Assert a statement about the current page |
+| `ask <question>` | Answer a question about the current page |
+| `research` | Map the current page and return verified locators |
+| `go <target>` | Navigate to a url, a path, or a page described in plain words |
+| `pw <fn>` | Run a Playwright function expression against the open page |
+| `status <hash>` | Show the artifacts and page detail recorded for an earlier command |
+| `report` | Turn every command of a session into one html and markdown report |
+| `browser start\|stop\|status\|list` | Manage the browsers prima drives |
+| `config` | Show models, config file and paths used by this run |
+
+`check` takes an outcome rather than a click path. It runs on the page you are already on and never reloads it, so an open dialog survives the check. Each `--expected` outcome comes back as PASSED, FAILED, CONTRADICTION or not verified — settled against a screenshot of the whole page, because what a user can see is the proof.
+
+`do` accounts for every instruction you gave: each is reported as ok, FAIL or ??. Nothing runs past the last instruction.
+
+## AI model
+
+Prima needs a model, and takes it from the environment. There is no `init` to run and nothing is written for you.
+
+```bash
+export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b
+export OPENROUTER_API_KEY=your-key
+```
+
+The provider comes from the model name, so that is the whole setup. Fish uses `set -gx` instead of `export`. Since prima is usually run by a coding agent, the better home is the agent's own config — in `~/.claude/settings.json`, an `env` block reaches every command the agent runs:
+
+```json
+{
+  "env": {
+    "PRIMA_CLI_AI_MODEL": "openrouter/openai/gpt-oss-120b",
+    "OPENROUTER_API_KEY": "your-key"
+  }
+}
+```
+
+Screenshot analysis needs its own model — one is never guessed from the main model. Set `PRIMA_CLI_VISION_MODEL`, or pass `--vision-model` for a single run, as `--model` does for the main one. Without it prima still runs, but settles `check` outcomes from the run log rather than from the page as seen.
+
+Every `PRIMA_CLI_*` variable mirrors the `EXPLORBOT_*` one of the same name and wins over it, so prima can be pointed at a different provider, model or URL without disturbing an explorbot setup on the same machine. `PRIMA_CLI_AI_MODEL`, `PRIMA_CLI_URL`, `PRIMA_CLI_VISION_MODEL` and the rest all work this way.
+
+Where [explorbot](https://www.npmjs.com/package/explorbot) is already configured, prima reads its config too — a project's `explorbot.config.js` first, then `~/.explorbot/config.js`. Variables win over both. `prima config` prints what a directory resolves to, and `--ephemeral` keeps no state between runs, writing output to a temp directory.
+
+Providers: openai, anthropic, google, groq, mistral, openrouter, sambanova.
+
+Without a model `pw` still works, since it runs Playwright directly.
+
+## Agents
+
+Prima is built to be called by a coding agent: one call takes a whole job, and the reply is a compact report rather than a browser transcript. Point your agent at `prima-cli --help` and it will find its way.
+
+## License
+
+Elastic-2.0. Part of [explorbot](https://github.com/testomatio/explorbot).

package/boat/prima/package.json

@@ -1,16 +1,20 @@
 {
-  "name": "prima",
-  "version": "1.0.0",
+  "name": "prima-cli",
+  "version": "0.0.0",
   "description": "High-level browser driver CLI for orchestrating agents",
+  "license": "Elastic-2.0",
   "type": "module",
-  "bin": { "prima": "./bin/prima-cli.ts" },
-  "scripts": {
-    "format": "biome format --write .",
-    "lint:fix": "biome lint --write .",
-    "check:fix": "biome check --write ."
+  "bin": {
+    "prima-cli": "./dist/boat/prima/bin/prima-cli.js"
   },
-  "dependencies": {
-    "commander": "^14.0.1",
-    "dedent": "^1.6.0"
+  "files": ["dist/"],
+  "keywords": ["cli", "playwright", "browser", "ai", "agent", "testing"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/testomatio/explorbot",
+    "directory": "boat/prima"
+  },
+  "engines": {
+    "node": ">=24.0.0"
   }
 }

package/boat/prima/src/cli.ts

@@ -22,17 +22,27 @@ const helpContract = dedent`
 `;
 
 const checkHelp = dedent`
-  check takes an outcome rather than a click path, and works out how to reach it.
+  check takes an outcome rather than a click path, and works out how to reach it. It runs
+  on the page you are already on and never reloads it, so an open dialog survives the check.
   --expected  one outcome the run must reach, repeatable for several. Without it the
               scenario text is the single expected outcome. Each comes back under
-              ### Expected outcomes as PASSED, FAILED or not verified - "not verified"
-              means the run never checked it, which is not the same as false.
+              ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
+              "not verified" means the run never checked it, which is not the same
+              as false.
+  Outcomes are settled against a screenshot of the whole page: what a user can see is
+  the proof, and the run log only says what was done. CONTRADICTION means the two
+  disagree - reported with both sides rather than settled one way, and ### Artifacts
+  then names the html, aria and screenshot on disk so you can judge it yourself. Not
+  finding something in the picture is not enough on its own; that is "not verified".
+  ok: follows those outcomes - false when one FAILED or CONTRADICTED, or when the run
+  could not complete, which is reported as such rather than as an app failure.
   Page problems seen on the way appear under ### Answer, not as step failures.
 `;
 
 const doHelp = dedent`
-  Each instruction is numbered and accounted for: ### Steps reports each as ok or FAIL
-  with what proved it. One that could not be carried out fails the command and says why.
+  Each instruction is numbered and accounted for: ### Steps reports each as ok, FAIL or ??.
+  ?? means the action ran but the run ended without confirming that instruction - read the
+  steps above it. Only FAIL and an instruction the page could not carry out fail the command.
   Nothing runs past the last instruction given. A whole remaining sequence in one call is
   what makes this tier cheap.
 `;
@@ -94,6 +104,8 @@ function addCommonOptions(cmd: Command): Command {
     .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('--model <model>', 'Main model, as provider/model-id')
+    .option('--vision-model <model>', 'Model for screenshot analysis, as provider/model-id')
     .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')
@@ -103,7 +115,10 @@ function addCommonOptions(cmd: Command): Command {
 }
 
 function primaFor(options: any): Prima {
+  Prima.applyEnv();
   if (options.ephemeral) process.env.EXPLORBOT_EPHEMERAL = '1';
+  if (options.model) process.env.EXPLORBOT_AI_MODEL = options.model;
+  if (options.visionModel) process.env.EXPLORBOT_VISION_MODEL = options.visionModel;
   return new Prima(buildOptions(options));
 }
 
@@ -186,13 +201,15 @@ export function createPrimaCommands(name = 'prima'): Command {
     await runPrima(options, `go ${target}`, (prima) => prima.go(target));
   });
 
-  addCommonOptions(cmd.command('config').description('Show the AI models prima runs on and the config file they come from')).action(async (options) => {
-    setQuietMode(!isVerboseMode());
-    const prima = primaFor(options);
-    console.log(await prima.config().catch((error: unknown) => browserErrorMessage(error)));
-    await prima.stop().catch(() => {});
-    process.exit(0);
-  });
+  addCommonOptions(cmd.command('config').description('Show models, config file and paths used by this run'))
+    .option('--json', 'Print the resolved config as JSON')
+    .action(async (options) => {
+      setQuietMode(!isVerboseMode());
+      const prima = primaFor(options);
+      console.log(await prima.config(options.json).catch((error: unknown) => browserErrorMessage(error)));
+      await prima.stop().catch(() => {});
+      process.exit(0);
+    });
 
   addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command')).action(async (hash, options) => {
     await runPrima(options, `status ${hash}`, (prima) => prima.status(hash), false);

package/boat/prima/src/envelope.ts

@@ -2,9 +2,10 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 const EXPECTATION_LABELS = {
-  passed: 'PASSED      ',
-  failed: 'FAILED      ',
-  unverified: 'not verified',
+  passed: 'PASSED       ',
+  failed: 'FAILED       ',
+  unverified: 'not verified ',
+  contradiction: 'CONTRADICTION',
 };
 
 export interface InstanceInfo {
@@ -21,8 +22,9 @@ export interface EnvelopeData {
   used?: string[];
   page: { url: string; previousUrl?: string; title: string; state: string; visits: number };
   changes?: string | null;
-  steps?: Array<{ label: string; ok: boolean; proof: string }>;
-  expectations?: Array<{ text: string; status: 'passed' | 'failed' | 'unverified' }>;
+  steps?: Array<{ label: string; ok: boolean; unconfirmed?: boolean; proof: string }>;
+  expectations?: Array<{ text: string; status: 'passed' | 'failed' | 'unverified' | 'contradiction'; evidence?: string }>;
+  warning?: string;
   stepFiles?: string;
   value?: string;
   answer?: string;
@@ -31,23 +33,28 @@ export interface EnvelopeData {
   failure?: { error: string; compactAria?: string };
   instance: InstanceInfo;
   status?: string;
-  artifacts?: { aria: string; html: string; network?: string };
+  artifacts?: { aria: string; html: string; screenshot?: string; network?: string };
 }
 
 export function renderEnvelope(data: EnvelopeData): string {
-  const sections = [renderResult(data), renderPage(data), renderValue(data), renderChanges(data), renderSteps(data), renderExpectations(data), renderOutcome(data), ...renderFailure(data), renderInstance(data), renderArtifacts(data)];
+  const sections = [renderResult(data), renderPage(data), renderValue(data), renderChanges(data), renderSteps(data), renderExpectations(data), renderWarning(data), renderOutcome(data), ...renderFailure(data), renderInstance(data), renderArtifacts(data)];
   return sections.filter((section) => section).join('\n\n');
 }
 
-export function writeArtifacts(dir: string, snapshot: { aria: string | null; html: string | null; requests: unknown[] }): { aria: string; html: string; network?: string } {
+export function writeArtifacts(dir: string, snapshot: { aria: string | null; html: string | null; screenshot?: Buffer; requests: unknown[] }): { aria: string; html: string; screenshot?: string; network?: string } {
   mkdirSync(dir, { recursive: true });
-  const paths: { aria: string; html: string; network?: string } = {
+  const paths: { aria: string; html: string; screenshot?: string; network?: string } = {
     aria: path.resolve(dir, 'aria.yml'),
     html: path.resolve(dir, 'page.html'),
   };
   writeFileSync(paths.aria, snapshot.aria ?? '', 'utf-8');
   writeFileSync(paths.html, snapshot.html ?? '', 'utf-8');
 
+  if (snapshot.screenshot) {
+    paths.screenshot = path.resolve(dir, 'page.png');
+    writeFileSync(paths.screenshot, snapshot.screenshot);
+  }
+
   if (!snapshot.requests.length) return paths;
 
   paths.network = path.resolve(dir, 'network.jsonl');
@@ -87,7 +94,10 @@ function renderSteps(data: EnvelopeData): string | null {
 
   const lines: string[] = [];
   data.steps.forEach((step, index) => {
-    lines.push(`${index + 1}. ${step.ok ? 'ok  ' : 'FAIL'} ${step.label}`);
+    let mark = 'FAIL';
+    if (step.ok) mark = 'ok  ';
+    if (step.unconfirmed) mark = '??  ';
+    lines.push(`${index + 1}. ${mark} ${step.label}`);
     for (const line of (step.proof || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
   });
   if (data.stepFiles) lines.push('', `page after each step: ${data.stepFiles}`);
@@ -96,10 +106,21 @@ function renderSteps(data: EnvelopeData): string | null {
 
 function renderExpectations(data: EnvelopeData): string | null {
   if (!data.expectations?.length) return null;
-  const lines = data.expectations.map((expectation, index) => `${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
+
+  const lines: string[] = [];
+  data.expectations.forEach((expectation, index) => {
+    lines.push(`${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
+    if (expectation.status !== 'contradiction' && expectation.status !== 'failed') return;
+    for (const line of (expectation.evidence || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
+  });
   return section('Expected outcomes', lines.join('\n'));
 }
 
+function renderWarning(data: EnvelopeData): string | null {
+  if (!data.warning) return null;
+  return section('Warning', data.warning);
+}
+
 function renderOutcome(data: EnvelopeData): string | null {
   if (data.answer) return section('Answer', data.answer);
   if (data.research) return section('Research', data.research);
@@ -154,8 +175,9 @@ function tabsLabel(tabs: number): string {
 
 export function renderArtifacts(data: EnvelopeData): string | null {
   if (!data.artifacts) return null;
-  const lines = [`aria: ${data.artifacts.aria}`, `html: ${data.artifacts.html}`];
-  if (data.artifacts.network) lines.push(`network: ${data.artifacts.network}`);
+  const lines = [`aria:       ${data.artifacts.aria}`, `html:       ${data.artifacts.html}`];
+  if (data.artifacts.screenshot) lines.push(`screenshot: ${data.artifacts.screenshot}`);
+  if (data.artifacts.network) lines.push(`network:    ${data.artifacts.network}`);
   return section('Artifacts', lines.join('\n'));
 }