explorbot 0.2.2 → 0.2.3

package/dist/boat/prima/src/cli.js

@@ -0,0 +1,200 @@
+import { Command } from 'commander';
+import dedent from 'dedent';
+import { keepServerRunning } from "../../../src/browser-server.js";
+import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
+import { setPreserveConsoleLogs } from "../../../src/utils/logger.js";
+import { renderEnvelope } from "./envelope.js";
+import { Prima } from "./prima.js";
+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) {
+    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) {
+    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) {
+    setPreserveConsoleLogs(true);
+    if (options.ephemeral)
+        process.env.EXPLORBOT_EPHEMERAL = '1';
+    return new Prima(buildOptions(options));
+}
+async function runPrima(options, command, run) {
+    const prima = primaFor(options);
+    let envelope;
+    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, run) {
+    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') {
+    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;
+}

package/dist/boat/prima/src/envelope.js

@@ -0,0 +1,116 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export function renderEnvelope(data) {
+    const sections = [renderResult(data), renderPage(data), renderOutcome(data), ...renderFailure(data), renderInstance(data.instance), renderArtifacts(data)];
+    return sections.filter((section) => section).join('\n\n');
+}
+export function writeArtifacts(dir, snapshot) {
+    mkdirSync(dir, { recursive: true });
+    const paths = {
+        aria: path.resolve(dir, 'aria.yml'),
+        html: path.resolve(dir, 'page.html'),
+        network: path.resolve(dir, 'network.jsonl'),
+    };
+    writeFileSync(paths.aria, snapshot.aria ?? '', 'utf-8');
+    writeFileSync(paths.html, snapshot.html ?? '', 'utf-8');
+    writeFileSync(paths.network, snapshot.requests.map((request) => `${JSON.stringify(request)}\n`).join(''), 'utf-8');
+    return paths;
+}
+function renderResult(data) {
+    const lines = [`ok: ${data.ok}`, `command: ${data.command}`];
+    const healed = renderHealed(data);
+    if (healed)
+        lines.push(healed);
+    if (data.used?.length)
+        lines.push(`used: ${data.used.join('; ')}`);
+    return section('Result', lines.join('\n'));
+}
+function renderHealed(data) {
+    if (data.healed === undefined)
+        return null;
+    if (data.healNote)
+        return `healed: ${data.healed} (${data.healNote})`;
+    return `healed: ${data.healed}`;
+}
+function renderPage(data) {
+    const { url, previousUrl, title, state, visits } = data.page;
+    const urlLabel = `url: ${url}`;
+    const stateLabel = `state: ${state}`;
+    const width = Math.max(urlLabel.length, stateLabel.length) + 3;
+    let changedMarker = '';
+    if (previousUrl && previousUrl !== url)
+        changedMarker = `(changed: ${previousUrl} → ${url})`;
+    const lines = [align(urlLabel, changedMarker, width), `title: ${title}`, align(stateLabel, `(visit #${visits})`, width)];
+    return section('Page', lines.join('\n'));
+}
+function renderOutcome(data) {
+    if (data.changes)
+        return section('Changes', data.changes);
+    if (data.answer)
+        return section('Answer', data.answer);
+    if (data.research)
+        return section('Research', data.research);
+    if (!data.verdict)
+        return null;
+    const lines = [`passed: ${data.verdict.passed}`, `evidence: ${data.verdict.evidence}`, `code: ${data.verdict.code}`];
+    return section('Verdict', lines.join('\n'));
+}
+function renderFailure(data) {
+    if (!data.failure)
+        return [];
+    const lines = [`error: ${data.failure.error}`];
+    if (data.failure.reasoning)
+        lines.push(`reasoning: ${data.failure.reasoning}`);
+    return [section('Failure', lines.join('\n')), renderAttempts(data.failure.attempts), renderCompactAria(data.failure.compactAria)];
+}
+function renderAttempts(attempts) {
+    if (!attempts?.length)
+        return null;
+    const labels = attempts.map((attempt, index) => `${index + 1}. ${attempt.code}`);
+    const width = Math.max(...labels.map((label) => label.length)) + 3;
+    const lines = labels.map((label, index) => align(label, `→ ${attempts[index].outcome}`, width));
+    return section(`Healing attempts (${attempts.length})`, lines.join('\n'));
+}
+function renderCompactAria(compactAria) {
+    if (!compactAria)
+        return null;
+    return section('Current page (compact ARIA)', compactAria);
+}
+function renderInstance(instance) {
+    const others = instance.others.map((other) => `${other.name} (${tabsLabel(other.tabs)})`);
+    const lines = [`instance: ${instance.name} (${tabsLabel(instance.tabs)}) | other instances: ${otherInstances(others)}`, browserLine(instance)];
+    return section('Instance', lines.join('\n'));
+}
+function otherInstances(others) {
+    if (!others.length)
+        return 'none';
+    return others.join(', ');
+}
+function browserLine(instance) {
+    if (instance.attached)
+        return `browser: attached (${instance.attached})`;
+    if (instance.startedAgo)
+        return `browser: running, started ${instance.startedAgo} ago`;
+    if (instance.tabs > 0)
+        return 'browser: running';
+    return 'browser: not running';
+}
+function tabsLabel(tabs) {
+    if (tabs === 1)
+        return '1 tab';
+    return `${tabs} tabs`;
+}
+function renderArtifacts(data) {
+    if (!data.artifacts)
+        return null;
+    const lines = [`aria: ${data.artifacts.aria}`, `html: ${data.artifacts.html}`, `network: ${data.artifacts.network}`];
+    return section('Artifacts', lines.join('\n'));
+}
+function align(label, marker, width) {
+    if (!marker)
+        return label;
+    return `${label.padEnd(width)}${marker}`;
+}
+function section(title, body) {
+    return `### ${title}\n${body}`;
+}