explorbot 0.2.3 → 0.2.4

package/boat/prima/src/pw-parser.ts

@@ -13,5 +13,15 @@ export function isFunctionExpression(expr: string): { valid: boolean; error?: st
 }
 
 export function toCodeceptWrapper(expr: string): string {
-  return `I.usePlaywrightTo('pw', async (playwright) => (${expr.trim()})(playwright))`;
+  return `return I.usePlaywrightTo('pw', async (playwright) => (${expr.trim()})(playwright))`;
+}
+
+export function takePwValue(held: unknown): string | undefined {
+  if (held === undefined || held === null) return undefined;
+  if (typeof held === 'string') return held;
+  try {
+    return JSON.stringify(held, null, 2);
+  } catch {
+    return String(held);
+  }
 }

package/boat/prima/src/pw-registry.ts

@@ -20,9 +20,8 @@ export function readDescriptors(dir = registryDir()): PwServerDescriptor[] {
   return descriptors;
 }
 
-export function selectDescriptor(descriptors: PwServerDescriptor[], opts: { workspaceDir: string; title?: string }): { match?: PwServerDescriptor; candidates: PwServerDescriptor[] } {
-  const workspaceDir = path.resolve(opts.workspaceDir);
-  const candidates = descriptors.filter((descriptor) => path.resolve(descriptor.workspaceDir) === workspaceDir);
+export function selectDescriptor(descriptors: PwServerDescriptor[], opts: { title?: string } = {}): { match?: PwServerDescriptor; candidates: PwServerDescriptor[] } {
+  const candidates = descriptors;
   if (!candidates.length) return { candidates };
 
   if (opts.title) {
@@ -53,13 +52,13 @@ function parseDescriptor(file: string): PwServerDescriptor | null {
     return null;
   }
 
-  if (!data?.endpoint || !data?.title || !data?.workspaceDir) return null;
+  if (!data?.endpoint || !data?.title) return null;
 
   return {
     file,
     title: data.title,
     endpoint: data.endpoint,
-    workspaceDir: data.workspaceDir,
+    workspaceDir: data.workspaceDir || '',
     browserName: data.browser?.browserName || DEFAULT_BROWSER,
     playwrightLib: data.playwrightLib || '',
   };

package/boat/prima/src/session-log.ts

@@ -0,0 +1,126 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { outputPath } from '../../../src/config.ts';
+import { safeFilename } from '../../../src/utils/strings.ts';
+import { type EnvelopeData, renderEnvelope } from './envelope.ts';
+
+const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped' };
+
+export function sessionsDir(): string {
+  return outputPath('prima', 'sessions');
+}
+
+export function sessionFile(key: string): string {
+  return path.join(sessionsDir(), `${safeFilename(key)}.jsonl`);
+}
+
+export function latestSessionFile(): string | null {
+  const dir = sessionsDir();
+  if (!existsSync(dir)) return null;
+
+  const files = readdirSync(dir)
+    .filter((name) => name.endsWith('.jsonl'))
+    .map((name) => path.join(dir, name))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+
+  return files[0] || null;
+}
+
+export function recordCommand(file: string, session: SessionRun, envelope: EnvelopeData, durationMs: number): void {
+  mkdirSync(path.dirname(file), { recursive: true });
+  if (recordedEndpoint(file) !== session.endpoint) writeFileSync(file, jsonLine({ action: 'createRun', endpoint: session.endpoint, params: { title: session.title } }), 'utf-8');
+  appendFileSync(file, jsonLine({ action: 'addTest', testId: commandTest(envelope, durationMs) }), 'utf-8');
+}
+
+export function readSession(file: string): { title: string; tests: any[] } {
+  const entries = readEntries(file);
+  const run = entries.find((entry) => entry.action === 'createRun');
+  const tests = entries.filter((entry) => entry.action === 'addTest').map((entry) => entry.testId);
+  return { title: run?.params?.title || 'prima session', tests };
+}
+
+function commandTest(envelope: EnvelopeData, durationMs: number): any {
+  let status = 'failed';
+  if (envelope.ok) status = 'passed';
+
+  const test: any = {
+    rid: envelope.status,
+    title: envelope.command,
+    suite_title: 'Prima session',
+    status,
+    file: '<prima>',
+    description: [`page: ${envelope.page.url}`, envelope.stepFiles && `artifacts: ${envelope.stepFiles}`].filter(Boolean).join('\n'),
+    code: (envelope.used || []).join('\n'),
+    steps: commandSteps(envelope),
+    logs: renderEnvelope(envelope),
+    time: Math.round(durationMs),
+  };
+
+  if (envelope.failure) test.error = { message: envelope.failure.error };
+  return test;
+}
+
+function commandSteps(envelope: EnvelopeData): any[] {
+  const steps: any[] = [];
+
+  for (const step of envelope.steps || []) {
+    const entry: any = { category: 'user', title: step.label, status: 'passed', duration: 0, log: step.proof };
+    if (!step.ok) {
+      entry.status = 'failed';
+      entry.error = step.proof;
+    }
+    steps.push(entry);
+  }
+
+  for (const expectation of envelope.expectations || []) {
+    const entry: any = { category: 'user', title: `expected: ${expectation.text}`, status: EXPECTATION_STATUS[expectation.status], duration: 0 };
+    if (expectation.status === 'failed') entry.error = 'the run did not reach this outcome';
+    steps.push(entry);
+  }
+
+  for (const assertion of envelope.assertions || []) {
+    const entry: any = { category: 'user', title: assertion.code, status: 'passed', duration: 0, log: assertion.proof.join('\n') };
+    if (!assertion.passed) {
+      entry.status = 'failed';
+      entry.error = 'the assertion did not hold on the page';
+    }
+    steps.push(entry);
+  }
+
+  return steps;
+}
+
+function recordedEndpoint(file: string): string | null {
+  const [first] = readEntries(file);
+  return first?.endpoint || null;
+}
+
+function readEntries(file: string): any[] {
+  if (!existsSync(file)) return [];
+
+  const entries: any[] = [];
+  for (const line of readFileSync(file, 'utf-8').split('\n')) {
+    if (!line.trim()) continue;
+    const entry = parseLine(line);
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
+function parseLine(line: string): any {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function jsonLine(entry: unknown): string {
+  return `${JSON.stringify(entry)}\n`;
+}
+
+export interface SessionRun {
+  key: string;
+  endpoint: string;
+  title: string;
+}

package/dist/bin/explorbot-cli.js

@@ -11,6 +11,7 @@ import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot } from '../src/explorbot.js';
+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.js";
@@ -23,7 +24,8 @@ const cli = getCliName();
 const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../package.json');
 const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
-if (!process.env.EXPLORBOT_NO_BANNER) {
+remote.registerOption(program);
+if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
     console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 function buildExplorBotOptions(from, options) {
@@ -74,6 +76,10 @@ async function startTUI(explorBot) {
     });
 }
 async function showStatsAndExit(code) {
+    if (remote.isAttached()) {
+        await remote.close(code);
+        process.exit(code);
+    }
     if (Stats.hasActivity()) {
         await new Promise((resolve) => {
             const { unmount } = render(React.createElement(StatusPane, {

package/dist/boat/api-tester/bin/apibot-cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env bun
+import { remote } from "../../../src/remote.js";
 import { createApiCommands } from "../src/cli.js";
 const program = createApiCommands('apibot');
+remote.registerOption(program);
 program.parse();

package/dist/boat/api-tester/src/config.js

@@ -8,6 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
 import { ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot } from "../../../src/config.js";
 import { findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from "../../../src/global-config.js";
@@ -181,9 +182,10 @@ export class ApibotConfigParser {
     }
     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);
@@ -191,7 +193,7 @@ export class ApibotConfigParser {
             }
         }
         if (ext === 'js' || ext === 'mjs') {
-            return await import(__rewriteRelativeImportExtension(configPath));
+            return await import(__rewriteRelativeImportExtension(moduleUrl));
         }
         const content = readFileSync(configPath, 'utf8');
         return JSON.parse(content);

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

@@ -1,4 +1,6 @@
 #!/usr/bin/env bun
+import { remote } from "../../../src/remote.js";
 import { createDocsCommands } from "../src/cli.js";
 const program = createDocsCommands('doc-collector');
+remote.registerOption(program);
 program.parse();

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/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/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)}`);
+}