explorbot 0.2.3 → 0.2.5

package/README.md

@@ -138,7 +138,7 @@ EXPLORBOT_KNOWLEDGE="Log in as admin@example.com / secret123" \
   npx explorbot explore /admin/users --max-tests 3
 ```
 
-Output lands in a per-host state directory, `~/.explorbot/state/<host>/`, so runs against the same app collect in one place and nothing is written to your project. Set `EXPLORBOT_EPHEMERAL=1` to keep nothing between runs. See [Agentic Usage](docs/workflow/agentic-usage.md).
+Output lands in a per-host site directory, `~/.explorbot/sites/<host>/`, so runs against the same app collect in one place and nothing is written to your project. Set `EXPLORBOT_EPHEMERAL=1` to keep nothing between runs. See [Agentic Usage](docs/workflow/agentic-usage.md).
 
 ## Teaching Explorbot
 

package/bin/explorbot-cli.ts

@@ -11,10 +11,11 @@ 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, type ExplorBotOptions } 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.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';
@@ -26,8 +27,9 @@ const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../p
 const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version as string;
 
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
+remote.registerOption(program);
 
-if (!process.env.EXPLORBOT_NO_BANNER) {
+if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
   console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 
@@ -99,6 +101,10 @@ async function startTUI(explorBot: ExplorBot): Promise<void> {
 }
 
 async function showStatsAndExit(code: number): Promise<never> {
+  if (remote.isAttached()) {
+    await remote.close(code);
+    process.exit(code);
+  }
   if (Stats.hasActivity()) {
     await new Promise<void>((resolve) => {
       const { unmount } = render(
@@ -430,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')
@@ -906,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/api-tester/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
 import { type AIConfig, type ApiHookFn, type ApiConfig as BaseApiConfig, ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot } from '../../../src/config.ts';
 import { type SiteRecord, findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from '../../../src/global-config.ts';
@@ -213,10 +214,11 @@ export class ApibotConfigParser {
 
   private async loadConfigModule(configPath: string): Promise<any> {
     const ext = configPath.split('.').pop();
+    const moduleUrl = pathToFileURL(resolve(configPath)).href;
 
     if (ext === 'ts') {
       try {
-        return await import(configPath);
+        return await import(moduleUrl);
       } catch {
         const require = (await import('node:module')).createRequire(import.meta.url);
         return require(configPath);
@@ -224,7 +226,7 @@ export class ApibotConfigParser {
     }
 
     if (ext === 'js' || ext === 'mjs') {
-      return await import(configPath);
+      return await import(moduleUrl);
     }
 
     const content = readFileSync(configPath, 'utf8');

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

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

package/boat/doc-collector/src/ai/documentarian.ts

@@ -67,17 +67,32 @@ 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: [],
-            interactions: meaningfulInteractions,
-          },
-          state,
-          research
-        );
+        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
+            )
+          )
+          .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);
     }
@@ -113,13 +128,13 @@ class Documentarian {
       },
     ];
 
-    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 as PageDocumentation),
+        ...(response.object as GeneratedPageDocumentation),
         interactions,
       },
       state,
@@ -139,11 +154,11 @@ class Documentarian {
       },
     ];
 
-    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 as PageDocumentation, state, research);
+    return this.normalizeDocumentation(response.object as GeneratedPageDocumentation, state, research);
   }
 
   private getSystemPrompt(): string {
@@ -259,7 +274,7 @@ class Documentarian {
     return message.includes('Failed to generate JSON') || message.includes('Failed to validate JSON') || message.includes('failed_generation') || message.includes('No object generated') || message.includes('response did not match schema');
   }
 
-  private normalizeDocumentation(documentation: PageDocumentation, _state: WebPageState, _research: string): PageDocumentation {
+  private normalizeDocumentation(documentation: GeneratedPageDocumentation & Partial<Pick<PageDocumentation, 'interactions'>>, _state: WebPageState, _research: string): PageDocumentation {
     const normalized = { ...documentation };
     if (!normalized.interactions) {
       normalized.interactions = undefined;
@@ -267,10 +282,10 @@ class Documentarian {
 
     const qualityNotes = this.evaluateDocumentationQuality(normalized);
 
-    return {
+    return pageDocumentationSchema.parse({
       ...normalized,
       qualityNotes,
-    };
+    });
   }
 
   private evaluateDocumentationQuality(documentation: PageDocumentation): string[] {
@@ -346,39 +361,54 @@ 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(),
 });
 
 type StateTransition = DocStateTransition;
-type PageDocumentation = Omit<z.infer<typeof pageDocumentationSchema>, 'interactions'> & {
-  interactions?: StateTransition[];
-  qualityNotes?: string[];
-};
+type GeneratedPageDocumentation = z.infer<typeof generatedPageDocumentationSchema>;
+type PageDocumentation = z.infer<typeof pageDocumentationSchema>;
 
 export { Documentarian };
 export type { PageDocumentation, StateTransition };

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/doc-collector/src/config.ts

@@ -1,5 +1,6 @@
 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.ts';
 
@@ -90,10 +91,11 @@ class DocbotConfigParser {
 
   private async loadConfigModule(configPath: string): Promise<any> {
     const ext = configPath.split('.').pop();
+    const moduleUrl = pathToFileURL(resolve(configPath)).href;
 
     if (ext === 'ts') {
       try {
-        return await import(configPath);
+        return await import(moduleUrl);
       } catch {
         const require = (await import('node:module')).createRequire(import.meta.url);
         return require(configPath);
@@ -101,7 +103,7 @@ class DocbotConfigParser {
     }
 
     if (ext === 'js' || ext === 'mjs') {
-      return await import(configPath);
+      return await import(moduleUrl);
     }
 
     return JSON.parse(readFileSync(configPath, 'utf8'));

package/boat/prima/src/activity-line.ts

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { type ActivityEntry, addActivityListener, removeActivityListener } from '../../../src/activity.ts';
+import { isVerboseMode } from '../../../src/utils/logger.ts';
+
+const RESET_LINE = '\r\u001b[2K';
+
+const stream = process.stderr;
+let tracking = false;
+
+export function trackActivityLine(): void {
+  if (tracking) return;
+  if (!stream.isTTY) return;
+  if (isVerboseMode()) return;
+
+  tracking = true;
+  addActivityListener(writeActivityLine);
+}
+
+export function clearActivityLine(): void {
+  if (!tracking) return;
+
+  tracking = false;
+  removeActivityListener(writeActivityLine);
+  stream.write(RESET_LINE);
+}
+
+function writeActivityLine(activity: ActivityEntry | null): void {
+  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)}`);
+}