explorbot 0.2.2 → 0.2.4

package/dist/boat/doc-collector/src/ai/documentarian.js

@@ -55,13 +55,22 @@ class Documentarian {
             const message = error instanceof Error ? error.message : String(error);
             tag('warning').log(`Interactive documentation failed: ${message}.`);
             if (meaningfulInteractions.length > 0) {
-                tag('info').log(`Preserving ${meaningfulInteractions.length} observed interaction(s) without AI summary.`);
-                return this.normalizeDocumentation({
-                    summary: `Observed ${meaningfulInteractions.length} interaction(s); AI-generated summary was unavailable.`,
-                    can: [],
-                    might: [],
+                tag('info').log(`Retrying static documentation while preserving ${meaningfulInteractions.length} observed interaction(s).`);
+                return this.documentStatic(state, research)
+                    .then((documentation) => this.normalizeDocumentation({
+                    ...documentation,
                     interactions: meaningfulInteractions,
-                }, state, research);
+                }, state, research))
+                    .catch((fallbackError) => {
+                    const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+                    tag('warning').log(`Static documentation fallback failed: ${fallbackMessage}. Preserving observed interactions without AI summary.`);
+                    return this.normalizeDocumentation({
+                        summary: `Observed ${meaningfulInteractions.length} interaction(s); AI-generated summary was unavailable.`,
+                        can: [],
+                        might: [],
+                        interactions: meaningfulInteractions,
+                    }, state, research);
+                });
             }
             return this.documentStatic(state, research);
         }
@@ -94,7 +103,7 @@ class Documentarian {
                 content: this.buildPrompt(state, `${research}${this.buildInteractionContext(interactions)}`),
             },
         ];
-        const response = await this.provider.generateObject(messages, pageDocumentationSchema, undefined, {
+        const response = await this.provider.generateObject(messages, generatedPageDocumentationSchema, undefined, {
             agentName: 'documentarian',
         });
         return this.normalizeDocumentation({
@@ -113,7 +122,7 @@ class Documentarian {
                 content: this.buildPrompt(state, research, simplified),
             },
         ];
-        const response = await this.provider.generateObject(messages, pageDocumentationSchema, undefined, {
+        const response = await this.provider.generateObject(messages, generatedPageDocumentationSchema, undefined, {
             agentName: 'documentarian',
         });
         return this.normalizeDocumentation(response.object, state, research);
@@ -230,10 +239,10 @@ class Documentarian {
             normalized.interactions = undefined;
         }
         const qualityNotes = this.evaluateDocumentationQuality(normalized);
-        return {
+        return pageDocumentationSchema.parse({
             ...normalized,
             qualityNotes,
-        };
+        });
     }
     evaluateDocumentationQuality(documentation) {
         const notes = [];
@@ -296,30 +305,46 @@ const stateTransitionSchema = z.object({
     action: z.string(),
     before: z.string(),
     after: z.string(),
-    targetUrl: z.string().nullable(),
-    discoveredUrls: z.array(z.string()).nullable(),
-    newCapabilities: z.array(z.string()).nullable(),
+    targetUrl: z.string().optional(),
+    discoveredUrls: z.array(z.string()).optional(),
+    newCapabilities: z.array(z.string()).optional(),
     element: z
         .object({
         role: z.string(),
         name: z.string(),
         section: z.string(),
-        container: z.string().nullable(),
-        locator: z.string().nullable(),
+        container: z.string().optional(),
+        locator: z.string().optional(),
     })
-        .nullable(),
+        .optional(),
     changes: z
         .object({
         urlChanged: z.boolean(),
         newElements: z.number(),
         removedElements: z.number(),
     })
-        .nullable(),
+        .optional(),
+    targetState: z
+        .object({
+        kind: z.enum(['page', 'dialog', 'modal', 'section']),
+        label: z.string(),
+        url: z.string(),
+    })
+        .optional(),
+    screenshot: z
+        .object({
+        title: z.string(),
+        relativePath: z.string(),
+    })
+        .optional(),
 });
-const pageDocumentationSchema = z.object({
+const generatedPageDocumentationSchema = z.object({
     summary: z.string(),
     can: z.array(capabilitySchema),
     might: z.array(capabilitySchema),
-    interactions: z.array(stateTransitionSchema).nullable(),
+});
+const pageDocumentationSchema = generatedPageDocumentationSchema.extend({
+    interactions: z.array(stateTransitionSchema).optional(),
+    qualityNotes: z.array(z.string()).optional(),
 });
 export { Documentarian };

package/dist/boat/doc-collector/src/cli.js

@@ -47,6 +47,7 @@ export function createDocsCommands(name = 'docs') {
             console.log(`Skipped ${result.skipped.length} page(s)`);
             console.log(`Spec index: ${result.indexPath}`);
             console.log(`Pages dir: ${path.join(result.outputDir, 'pages')}`);
+            console.log(`Use in Explorbot: npx explorbot start ${startPath} --spec "${result.outputDir}"`);
             await bot.stop();
             process.exit(0);
         }

package/dist/boat/doc-collector/src/config.js

@@ -8,6 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
 import { ConfigParser } from "../../../src/config.js";
 class DocbotConfigParser {
@@ -84,9 +85,10 @@ class DocbotConfigParser {
     }
     async loadConfigModule(configPath) {
         const ext = configPath.split('.').pop();
+        const moduleUrl = pathToFileURL(resolve(configPath)).href;
         if (ext === 'ts') {
             try {
-                return await import(__rewriteRelativeImportExtension(configPath));
+                return await import(__rewriteRelativeImportExtension(moduleUrl));
             }
             catch {
                 const require = (await import('node:module')).createRequire(import.meta.url);
@@ -94,7 +96,7 @@ class DocbotConfigParser {
             }
         }
         if (ext === 'js' || ext === 'mjs') {
-            return await import(__rewriteRelativeImportExtension(configPath));
+            return await import(__rewriteRelativeImportExtension(moduleUrl));
         }
         return JSON.parse(readFileSync(configPath, 'utf8'));
     }

package/dist/boat/doc-collector/src/docs-renderer.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
-import { buildStateGraph, renderMermaidFromGraph, renderStateMapFromGraph } from "./state-diagram.js";
+import matter from 'gray-matter';
+import { APPLICATION_SPEC_FORMAT, APPLICATION_SPEC_VERSION } from "../../../src/application-spec-contract.js";
 import { normalizeInlineText } from "../../../src/utils/strings.js";
+import { buildStateGraph, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph } from "./state-diagram.js";
 function renderPageDocumentation(state, documentation, screenshots = []) {
     const lines = [];
     lines.push(`# ${state.url}`);
@@ -25,6 +27,13 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
         }
     }
     const interactions = documentation.interactions;
+    const pageStateDiagram = renderPageStateDiagram(state.title || state.url || 'page', state.url || '', interactions || []);
+    if (pageStateDiagram) {
+        lines.push('## State Map');
+        lines.push('');
+        lines.push(`\`\`\`mermaid\n${pageStateDiagram}\n\`\`\``);
+        lines.push('');
+    }
     if (interactions && interactions.length > 0) {
         lines.push('## State Transitions');
         lines.push('');
@@ -83,7 +92,11 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
         }
         lines.push('');
     }
-    return `${lines.join('\n').trimEnd()}\n`;
+    return matter.stringify(`${lines.join('\n').trimEnd()}\n`, {
+        url: state.url,
+        format: APPLICATION_SPEC_FORMAT,
+        version: APPLICATION_SPEC_VERSION,
+    });
 }
 function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
     const lines = [];
@@ -97,9 +110,10 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
     lines.push(`Max pages: ${maxPages}`);
     lines.push('');
     const graph = buildStateGraph(outputDir, pages);
+    const mermaid = renderMermaidFromGraph(graph, true);
     lines.push('## State Transitions');
     lines.push('');
-    lines.push(`\`\`\`mermaid\n${renderMermaidFromGraph(graph)}\n\`\`\``);
+    lines.push(`\`\`\`mermaid\n${mermaid}\n\`\`\``);
     lines.push('');
     const stateMap = renderStateMapFromGraph(graph);
     if (stateMap) {

package/dist/boat/doc-collector/src/state-diagram.js

@@ -60,8 +60,11 @@ function buildStateGraph(outputDir, pages) {
             if (!targetId) {
                 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;
                 }
@@ -69,9 +72,6 @@ function buildStateGraph(outputDir, pages) {
                 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 });
         }
@@ -90,8 +90,8 @@ function buildStateGraph(outputDir, pages) {
 function renderMermaidBody(outputDir, pages) {
     return renderMermaidFromGraph(buildStateGraph(outputDir, pages));
 }
-function renderMermaidFromGraph(graph) {
-    const lines = ['flowchart TD'];
+function renderMermaidFromGraph(graph, compact = false) {
+    const lines = [compact ? 'flowchart LR' : 'flowchart TD'];
     if (graph.pages.length === 0) {
         lines.push('  empty["No documented states"]');
         return lines.join('\n');
@@ -102,6 +102,12 @@ function renderMermaidFromGraph(graph) {
         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)}`);
@@ -109,11 +115,13 @@ function renderMermaidFromGraph(graph) {
         lines.push('  end');
     }
     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;');
     lines.push('  classDef dialog fill:#ffedd5,stroke:#ea580c,color:#0f172a;');
@@ -153,6 +161,42 @@ function renderStateMapFromGraph(graph) {
     }
     return rows.join('\n');
 }
+function renderPageStateDiagram(label, url, interactions) {
+    const targets = new Map();
+    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 = ['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) {
     const label = `${escapeMermaidLabel(node.label)}<br/>${escapeMermaidLabel(node.subLabel)}`;
     if (node.kind === 'dialog' || node.kind === 'modal') {
@@ -183,7 +227,7 @@ function createsCycle(sourceId, targetId, adjacency) {
     return false;
 }
 function escapeMermaidLabel(value) {
-    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) {
     return normalizeInlineText(value).replaceAll('|', '\\|');
@@ -197,4 +241,4 @@ function classForKind(kind) {
     }
     return 'dialog';
 }
-export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderStateMapFromGraph };
+export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph };

package/dist/boat/prima/bin/prima-cli.js

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

package/dist/boat/prima/src/activity-line.js

@@ -0,0 +1,30 @@
+import chalk from 'chalk';
+import { addActivityListener, removeActivityListener } from "../../../src/activity.js";
+import { isVerboseMode } from "../../../src/utils/logger.js";
+const RESET_LINE = '\r\u001b[2K';
+const stream = process.stderr;
+let tracking = false;
+export function trackActivityLine() {
+    if (tracking)
+        return;
+    if (!stream.isTTY)
+        return;
+    if (isVerboseMode())
+        return;
+    tracking = true;
+    addActivityListener(writeActivityLine);
+}
+export function clearActivityLine() {
+    if (!tracking)
+        return;
+    tracking = false;
+    removeActivityListener(writeActivityLine);
+    stream.write(RESET_LINE);
+}
+function writeActivityLine(activity) {
+    if (!activity)
+        return;
+    const width = (stream.columns || 80) - 2;
+    const message = Array.from(activity.message.replace(/\s+/g, ' ').trim()).slice(0, width).join('');
+    stream.write(`${RESET_LINE}${chalk.gray(message)}`);
+}

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

@@ -0,0 +1,220 @@
+import { Command } from 'commander';
+import dedent from 'dedent';
+import { keepServerRunning } from "../../../src/browser-server.js";
+import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
+import { isVerboseMode, setQuietMode } from "../../../src/utils/logger.js";
+import { clearActivityLine, trackActivityLine } from "./activity-line.js";
+import { renderEnvelope } from "./envelope.js";
+import { Prima } from "./prima.js";
+const helpContract = dedent `
+  Prima is a high-level AI extension to playwright-cli, driving the browser it has open.
+
+    playwright-cli open <url>    starts the session
+    prima <command> ...          drives it
+    playwright-cli close         ends it
+
+  One call takes a whole job:
+
+    prima check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
+    prima do "open the account menu" "choose the settings entry" "switch the theme to dark" "check it took effect"
+    prima pw "({ page }) => page.click('[data-test=submit]')"
+`;
+const checkHelp = dedent `
+  check takes an outcome rather than a click path, and works out how to reach it.
+  --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.
+  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.
+  Nothing runs past the last instruction given. A whole remaining sequence in one call is
+  what makes this tier cheap.
+`;
+const verifyHelp = dedent `
+  Reports each assertion it could express as PASSED or FAILED with its playwright form,
+  and gives no overall verdict - read the lines and decide. "none ran" means the claim
+  could not be expressed, which is not the same as false.
+`;
+const reportHelp = dedent `
+  Commands are logged as they run, so the report needs no browser and outlives the session.
+  The most recent session is reported unless --pw-session names another.
+`;
+const sessionHelp = dedent `
+  --endpoint <ep>    attach to a browser server endpoint directly, skipping discovery
+  --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, since the attached session keeps its own
+  --framework        parsed but not active yet; reported code is CodeceptJS either way
+  DEBUG='explorbot:*' in front of a command prints the log of everything it does.
+  When no AI model is usable pw still works; for everything else drive playwright-cli.
+`;
+let rootOptions = () => ({});
+function buildOptions(subcommand) {
+    const options = { ...rootOptions(), ...stripEmpty(subcommand) };
+    return {
+        config: options.config,
+        path: options.path,
+        instance: options.instance,
+        session: options.session,
+        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 stripEmpty(options) {
+    const present = {};
+    for (const [key, value] of Object.entries(options || {})) {
+        if (value === undefined)
+            continue;
+        present[key] = value;
+    }
+    return present;
+}
+function addCommonOptions(cmd) {
+    return cmd
+        .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('--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')
+        .addHelpText('after', `\n${sessionHelp}`);
+}
+function primaFor(options) {
+    if (options.ephemeral)
+        process.env.EXPLORBOT_EPHEMERAL = '1';
+    return new Prima(buildOptions(options));
+}
+async function runPrima(options, command, run, record = true) {
+    setQuietMode(!isVerboseMode());
+    trackActivityLine();
+    const prima = primaFor(options);
+    const startedAt = Date.now();
+    let envelope;
+    try {
+        await prima.start();
+        envelope = await run(prima);
+    }
+    catch (error) {
+        envelope = await prima.toolFailureEnvelope(command, error);
+    }
+    if (record)
+        prima.record(envelope, Date.now() - startedAt);
+    clearActivityLine();
+    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('Tests and drives a web app through described behaviour instead of locators: one command carries a whole scenario, verifies it, and reports the proof');
+    cmd.option('--pw-session <title>', 'Title of the playwright-cli session to attach to');
+    cmd.option('--url <url>', 'Page to open when the session has no page yet');
+    cmd.addHelpText('after', `\n${helpContract}`);
+    rootOptions = () => cmd.opts();
+    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'))
+        .addHelpText('after', `\n${doHelp}`)
+        .action(async (instructions, options) => {
+        await runPrima(options, `do ${instructions.join(' ')}`, (prima) => prima.do(instructions));
+    });
+    addCommonOptions(cmd.command('check <scenario>').description('Run a scenario end to end as a test, with its own verification, and report the steps it took'))
+        .option('--expected <outcome>', 'An outcome the run must reach; repeat the flag for several', (value, all) => [...all, value], [])
+        .addHelpText('after', `\n${checkHelp}`)
+        .action(async (scenario, options) => {
+        await runPrima(options, `check ${scenario}`, (prima) => prima.check(scenario, options.expected));
+    });
+    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'))
+        .addHelpText('after', `\n${verifyHelp}`)
+        .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));
+    });
+    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) => 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);
+    });
+    addCommonOptions(cmd.command('report').description('Turn every command of a session into one html and markdown report'))
+        .addHelpText('after', `\n${reportHelp}`)
+        .action(async (options) => {
+        setQuietMode(!isVerboseMode());
+        console.log(await primaFor(options)
+            .report()
+            .catch((error) => browserErrorMessage(error)));
+        process.exit(0);
+    });
+    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;
+}