explorbot 0.1.20 → 0.1.21

package/boat/doc-collector/src/docs-renderer.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import type { WebPageState } from '../../../src/state-manager.ts';
-import type { PageDocumentation } from './ai/documentarian.ts';
+import type { PageDocumentation, StateTransition } from './ai/documentarian.ts';
 
 function renderPageDocumentation(state: WebPageState, documentation: PageDocumentation): string {
   const lines: string[] = [];
@@ -16,6 +16,28 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
   lines.push('');
   lines.push(ensureSentence(documentation.summary));
   lines.push('');
+
+  const interactions = documentation.interactions;
+  if (interactions && interactions.length > 0) {
+    lines.push('## State Transitions');
+    lines.push('');
+    for (const transition of interactions) {
+      lines.push(`### ${transition.action}`);
+      lines.push('');
+      lines.push(`**Before:** ${transition.before}`);
+      lines.push('');
+      lines.push(`**After:** ${transition.after}`);
+      lines.push('');
+      if (transition.newCapabilities && transition.newCapabilities.length > 0) {
+        lines.push('**Observed changes:**');
+        for (const cap of transition.newCapabilities) {
+          lines.push(`- ${cap}`);
+        }
+        lines.push('');
+      }
+    }
+  }
+
   lines.push('## User Can');
   lines.push('');
 
@@ -50,6 +72,16 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
     lines.push('');
   }
 
+  const qualityNotes = documentation.qualityNotes;
+  if (qualityNotes && qualityNotes.length > 0) {
+    lines.push('## Coverage Notes');
+    lines.push('');
+    for (const note of qualityNotes) {
+      lines.push(`- ${ensureSentence(note)}`);
+    }
+    lines.push('');
+  }
+
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
@@ -79,6 +111,9 @@ function renderSpecIndex(outputDir: string, startPath: string, pages: Documented
     lines.push(`Purpose: ${ensureSentence(page.summary)}`);
     lines.push(`Proven actions: ${page.canCount}`);
     lines.push(`Possible actions: ${page.mightCount}`);
+    if (page.interactionCount > 0) {
+      lines.push(`Interactive transitions: ${page.interactionCount}`);
+    }
     if (page.title) {
       lines.push(`Title: ${normalizeInlineText(page.title)}`);
     }
@@ -99,6 +134,22 @@ function renderSpecIndex(outputDir: string, startPath: string, pages: Documented
       }
       lines.push('');
     }
+
+    if (page.interactionActions.length > 0) {
+      lines.push('Interactive Findings:');
+      for (const action of page.interactionActions.slice(0, 3)) {
+        lines.push(`- ${normalizeInlineText(action)}`);
+      }
+      lines.push('');
+    }
+
+    if (page.qualityNotes.length > 0) {
+      lines.push('Coverage Notes:');
+      for (const note of page.qualityNotes) {
+        lines.push(`- ${ensureSentence(note)}`);
+      }
+      lines.push('');
+    }
   }
 
   if (skipped.length > 0) {
@@ -173,8 +224,11 @@ interface DocumentedPage {
   summary: string;
   canCount: number;
   mightCount: number;
+  interactionCount: number;
   canActions: string[];
   mightActions: string[];
+  interactionActions: string[];
+  qualityNotes: string[];
   filePath: string;
 }
 
@@ -184,4 +238,4 @@ interface SkippedPage {
 }
 
 export { renderPageDocumentation, renderSpecIndex, ensureSentence, normalizeAction };
-export type { DocumentedPage, SkippedPage };
+export type { DocumentedPage, SkippedPage, StateTransition };

package/dist/bin/explorbot-cli.js

@@ -266,11 +266,17 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
         process.exit(1);
     }
 });
-addCommonOptions(program.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1,3, 1-5, *, all').option('--grep <pattern>', 'Run tests matching pattern')).action(async (planfile, index, options) => {
+addCommonOptions(program.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1,3, 1-5, *, all').option('--grep <pattern>', 'Run tests matching pattern').option('--from-plan <file>', 'Load plan file when the first argument is a test index')).action(async (planfile, index, options) => {
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));
         await explorBot.start();
-        const plan = explorBot.loadPlan(planfile);
+        let planfileArg = planfile;
+        let indexArg = index;
+        if (options.fromPlan) {
+            planfileArg = options.fromPlan;
+            indexArg = planfile;
+        }
+        const plan = explorBot.loadPlan(planfileArg);
         const pending = plan.getPendingTests();
         log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests, ${pending.length} pending)`);
         const startUrl = plan.url || pending[0]?.startUrl;
@@ -280,8 +286,8 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
         log(`Navigating to ${startUrl}`);
         await explorBot.visit(startUrl);
         let args = '';
-        if (index)
-            args = index;
+        if (indexArg)
+            args = indexArg;
         else if (options.grep)
             args = options.grep;
         const { TestCommand } = await import('../src/commands/test-command.js');
@@ -315,6 +321,26 @@ program
         process.exit(1);
     }
 });
+program
+    .command('plans [plan]')
+    .description('List saved plans, or show tests for a specific plan')
+    .option('-p, --path <path>', 'Working directory path')
+    .option('-c, --config <path>', 'Path to configuration file')
+    .action(async (plan, options) => {
+    try {
+        await ConfigParser.getInstance().loadConfig({
+            config: options.config,
+            path: options.path || process.cwd(),
+        });
+        const explorBot = new ExplorBot({ path: options.path });
+        const { PlansCommand } = await import('../src/commands/plans-command.js');
+        await new PlansCommand(explorBot).execute(plan || '');
+    }
+    catch (error) {
+        console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
+});
 addCommonOptions(program.command('rerun <filename> [index]').description('Re-run generated tests with AI auto-healing')).action(async (filename, index, options) => {
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));

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

@@ -1,13 +1,26 @@
 import dedent from 'dedent';
 import { z } from 'zod';
+import { tag } from "../../../../src/utils/logger.js";
+import { collectDocInteractions } from "./tools.js";
 class Documentarian {
     provider;
     config;
-    constructor(provider, config = {}) {
+    explorer;
+    constructor(provider, config = {}, explorer) {
         this.provider = provider;
         this.config = config;
+        this.explorer = explorer;
     }
     async document(state, research) {
+        const interactiveEnabled = this.config.docs?.interactive === true && this.explorer;
+        if (!interactiveEnabled) {
+            tag('info').log('Documentarian: Using static mode (interactive disabled or no explorer)');
+            return this.documentStatic(state, research);
+        }
+        tag('info').log('Documentarian: Using interactive mode with tools');
+        return this.documentWithInteraction(state, research);
+    }
+    async documentStatic(state, research) {
         try {
             return await this.generateDocumentation(state, research);
         }
@@ -18,39 +31,110 @@ class Documentarian {
             return this.generateDocumentation(state, this.sanitizeResearch(research), true);
         }
     }
+    async documentWithInteraction(state, research) {
+        try {
+            tag('info').log('Starting interactive exploration...');
+            const deterministicInteractions = await collectDocInteractions(this.explorer, state, research);
+            const meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
+            if (meaningfulInteractions.length > 0) {
+                tag('success').log(`Collected ${meaningfulInteractions.length} deterministic interactions`);
+                return await this.generateDocumentationWithInteractions(state, research, meaningfulInteractions);
+            }
+            if (deterministicInteractions.length > 0) {
+                tag('info').log('Interactive exploration found only low-value navigation changes. Using static documentation.');
+            }
+            else {
+                tag('info').log('Interactive exploration found no reliable deterministic interactions. Using static documentation.');
+            }
+            return this.documentStatic(state, research);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            tag('warning').log(`Interactive documentation failed: ${message}. Falling back to static.`);
+            return this.documentStatic(state, research);
+        }
+    }
+    getMeaningfulInteractions(interactions) {
+        return interactions.filter((interaction) => {
+            if (interaction.targetUrl) {
+                return true;
+            }
+            if (interaction.changes?.urlChanged) {
+                return true;
+            }
+            if ((interaction.changes?.newElements || 0) > 0) {
+                return true;
+            }
+            return (interaction.discoveredUrls || []).length > 0;
+        });
+    }
+    async generateDocumentationWithInteractions(state, research, interactions) {
+        const messages = [
+            {
+                role: 'system',
+                content: this.getSystemPrompt(),
+            },
+            {
+                role: 'user',
+                content: this.buildPrompt(state, `${research}${this.buildInteractionContext(interactions)}`),
+            },
+        ];
+        const response = await this.provider.generateObject(messages, pageDocumentationSchema, undefined, {
+            agentName: 'documentarian',
+        });
+        return this.normalizeDocumentation({
+            ...response.object,
+            interactions,
+        }, state, research);
+    }
+    async generateDocumentation(state, research, simplified = false) {
+        const messages = [
+            {
+                role: 'system',
+                content: this.getSystemPrompt(),
+            },
+            {
+                role: 'user',
+                content: this.buildPrompt(state, research, simplified),
+            },
+        ];
+        const response = await this.provider.generateObject(messages, pageDocumentationSchema, undefined, {
+            agentName: 'documentarian',
+        });
+        return this.normalizeDocumentation(response.object, state, research);
+    }
     getSystemPrompt() {
-        const customPrompt = this.config.docs?.prompt;
         let promptSuffix = '';
-        if (customPrompt) {
-            promptSuffix = customPrompt;
+        if (this.config.docs?.prompt) {
+            promptSuffix = this.config.docs.prompt;
         }
         return dedent `
-    <role>
-    You are a product analyst preparing functional website documentation from UI research.
-    </role>
+      <role>
+      You are a product analyst preparing functional website documentation from UI research.
+      </role>
 
-    <task>
-    Convert exploratory UI research into a precise spec of what users can do on the current page.
-    Distinguish proven capabilities from assumptions.
-    Prefer accuracy over coverage.
-    </task>
+      <task>
+      Convert exploratory UI research into a precise spec of what users can do on the current page.
+      Distinguish proven capabilities from assumptions.
+      Prefer accuracy over coverage.
+      </task>
 
-    <rules>
-    Only list capabilities that are grounded in the provided page research.
-    Put actions into "can" only when there is direct evidence in the page context.
-    Put actions into "might" only when the UI strongly suggests a capability but proof is incomplete.
-    Describe each action from the end-user perspective.
-    Be explicit about scope:
-    - one item
-    - list of items
-    - bulk operations
-    - all items
-    - page-level
-    Avoid implementation details, selectors, and QA wording.
-    Avoid duplicate actions with different phrasing.
-    </rules>
+      <rules>
+      Only list capabilities that are grounded in the provided page research.
+      Put actions into "can" only when there is direct evidence in the page context.
+      Put actions into "might" only when the UI strongly suggests a capability but proof is incomplete.
+      Describe each action from the end-user perspective.
+      Be explicit about scope:
+      - one item
+      - list of items
+      - bulk operations
+      - all items
+      - page-level
+      Avoid implementation details, selectors, and QA wording.
+      Avoid duplicate actions with different phrasing.
+      </rules>
 
-    ${promptSuffix}
+      ${promptSuffix}
     `;
     }
     buildPrompt(state, research, simplified = false) {
@@ -59,68 +143,89 @@ class Documentarian {
             .slice(0, 50)
             .map((link) => `- ${link.title}: ${link.url}`)
             .join('\n');
-        const simplificationNote = simplified
-            ? dedent `
+        let simplificationNote = '';
+        if (simplified) {
+            simplificationNote = dedent `
         <fallback_mode>
         The research text was simplified because the original formatting was noisy.
         Ignore malformed table syntax and rely only on clear, repeated signals.
         Prefer fewer actions over speculative coverage.
         </fallback_mode>
-        `
-            : '';
+      `;
+        }
         return dedent `
-    <page>
-    URL: ${state.url}
-    Title: ${state.title || ''}
-    Headings: ${headings}
-    </page>
+      <page>
+      URL: ${state.url}
+      Title: ${state.title || ''}
+      Headings: ${headings}
+      </page>
 
-    <navigation_links>
-    ${links}
-    </navigation_links>
+      <navigation_links>
+      ${links}
+      </navigation_links>
 
-    <research>
-    ${research}
-    </research>
+      <research>
+      ${research}
+      </research>
 
-    ${simplificationNote}
+      ${simplificationNote}
 
-    <output_requirements>
-    Return structured data.
-    summary: short page purpose statement.
-    can: actions you are 100% sure are available on page.
-    might: actions that look possible but are not fully proven.
-    For each action provide:
-    - action: concise user-facing capability phrased as "user can ..."
-    - scope: one of one item, list of items, bulk operations, all items, page-level
-    - evidence: short reason based on visible UI or research
-    </output_requirements>
+      <output_requirements>
+      Return structured data.
+      summary: short page purpose statement.
+      can: actions you are 100% sure are available on page.
+      might: actions that look possible but are not fully proven.
+      For each action provide:
+      - action: concise user-facing capability phrased as "user can ..."
+      - scope: one of one item, list of items, bulk operations, all items, page-level
+      - evidence: short reason based on visible UI or research
+      </output_requirements>
     `;
     }
-    async generateDocumentation(state, research, simplified = false) {
-        const messages = [
-            {
-                role: 'system',
-                content: this.getSystemPrompt(),
-            },
-            {
-                role: 'user',
-                content: this.buildPrompt(state, research, simplified),
-            },
-        ];
-        const response = await this.provider.generateObject(messages, pageDocumentationSchema, undefined, {
-            agentName: 'documentarian',
-        });
-        return response.object;
+    buildInteractionContext(interactions) {
+        const lines = interactions
+            .map((interaction) => {
+            const parts = [`Action: ${interaction.action}`, `Element: ${this.formatInteractionElement(interaction)}`, `Before: ${interaction.before}`, `After: ${interaction.after}`, `Changes: ${this.formatInteractionChanges(interaction)}`];
+            if (interaction.targetUrl) {
+                parts.push(`Target URL: ${interaction.targetUrl}`);
+            }
+            if (interaction.discoveredUrls && interaction.discoveredUrls.length > 0) {
+                parts.push(`Discovered URLs: ${interaction.discoveredUrls.join(', ')}`);
+            }
+            return `- ${parts.join('\n  ')}`;
+        })
+            .join('\n');
+        return dedent `
+
+      <interaction_observations>
+      These are raw observations collected after interacting with visible controls. They are not semantic conclusions.
+      Classify them yourself as proven user capabilities, possible capabilities, navigation, page-state changes, or noise.
+      Do not trust the action label as a capability category; use the before/after state, element metadata, and URL changes as evidence.
+      ${lines}
+      </interaction_observations>
+    `;
     }
     shouldRetryWithSanitizedResearch(error) {
         const message = error instanceof Error ? error.message : String(error);
-        return message.includes('Failed to generate JSON') || message.includes('failed_generation');
+        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');
+    }
+    normalizeDocumentation(documentation, _state, _research) {
+        const qualityNotes = this.evaluateDocumentationQuality(documentation);
+        return {
+            ...documentation,
+            qualityNotes,
+        };
+    }
+    evaluateDocumentationQuality(documentation) {
+        const notes = [];
+        if ((documentation.interactions || []).length === 0 && this.config.docs?.interactive) {
+            notes.push('Interactive exploration did not produce any reliable page-specific transitions for this page.');
+        }
+        return notes;
     }
     sanitizeResearch(research) {
-        const lines = research.split('\n');
         const sanitized = [];
-        for (const line of lines) {
+        for (const line of research.split('\n')) {
             if (!line.trim()) {
                 sanitized.push(line);
                 continue;
@@ -143,15 +248,59 @@ class Documentarian {
         }
         return sanitized.join('\n');
     }
+    formatInteractionElement(interaction) {
+        if (!interaction.element) {
+            return 'unknown element';
+        }
+        const parts = [`role=${interaction.element.role}`, `name=${interaction.element.name}`, `section=${interaction.element.section}`];
+        if (interaction.element.container) {
+            parts.push(`container=${interaction.element.container}`);
+        }
+        if (interaction.element.locator) {
+            parts.push(`locator=${interaction.element.locator}`);
+        }
+        return parts.join(', ');
+    }
+    formatInteractionChanges(interaction) {
+        if (!interaction.changes) {
+            return 'unknown changes';
+        }
+        return `urlChanged=${interaction.changes.urlChanged}, newElements=${interaction.changes.newElements}, removedElements=${interaction.changes.removedElements}`;
+    }
 }
 const capabilitySchema = z.object({
     action: z.string(),
     scope: z.enum(['one item', 'list of items', 'bulk operations', 'all items', 'page-level']),
     evidence: z.string(),
 });
+const stateTransitionSchema = z.object({
+    action: z.string(),
+    before: z.string(),
+    after: z.string(),
+    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().optional(),
+        locator: z.string().optional(),
+    })
+        .optional(),
+    changes: z
+        .object({
+        urlChanged: z.boolean(),
+        newElements: z.number(),
+        removedElements: z.number(),
+    })
+        .optional(),
+});
 const pageDocumentationSchema = z.object({
     summary: z.string(),
     can: z.array(capabilitySchema),
     might: z.array(capabilitySchema),
+    interactions: z.array(stateTransitionSchema).optional(),
 });
 export { Documentarian };