explorbot 0.1.31 → 0.2.0

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

@@ -0,0 +1,200 @@
+import path from 'node:path';
+import { normalizeUrl } from "../../../src/state-manager.js";
+import { normalizeInlineText } from "../../../src/utils/strings.js";
+function buildStateGraph(outputDir, pages) {
+    const pageIds = new Map();
+    const pageNodes = [];
+    const adjacency = new Map();
+    const classAssignment = new Map([
+        ['page', []],
+        ['dialog', []],
+        ['section', []],
+    ]);
+    for (const [index, page] of pages.entries()) {
+        const id = `page${index}`;
+        pageIds.set(normalizeUrl(page.url), id);
+        adjacency.set(id, new Set());
+        classAssignment.get('page')?.push(id);
+        pageNodes.push({ id, kind: 'page', label: page.title || page.url, subLabel: page.url, filePath: page.filePath });
+    }
+    const stateKeys = new Map();
+    const transientByPage = new Map();
+    const clicks = [];
+    const edges = [];
+    const drawnBack = new Set();
+    let stateIndex = 0;
+    for (const [pageIndex, page] of pages.entries()) {
+        const sourceId = `page${pageIndex}`;
+        for (const transition of page.interactions || []) {
+            const targetState = transition.targetState;
+            if (!targetState) {
+                continue;
+            }
+            const normalizedTarget = normalizeUrl(targetState.url);
+            const isPageTarget = targetState.kind === 'page';
+            let pageTargetId;
+            if (isPageTarget) {
+                pageTargetId = pageIds.get(normalizedTarget);
+            }
+            let targetId;
+            if (pageTargetId && pageTargetId !== sourceId) {
+                targetId = pageTargetId;
+            }
+            if (!targetId) {
+                const stateKey = `${sourceId}:${targetState.kind}:${normalizeInlineText(targetState.label)}:${normalizedTarget}`;
+                targetId = stateKeys.get(stateKey);
+                if (!targetId) {
+                    targetId = `state${stateIndex++}`;
+                    stateKeys.set(stateKey, targetId);
+                    adjacency.set(targetId, new Set());
+                    classAssignment.get(classForKind(targetState.kind))?.push(targetId);
+                    const list = transientByPage.get(sourceId) ?? [];
+                    list.push({ id: targetId, kind: targetState.kind, label: targetState.label, subLabel: targetState.kind, parentPageId: sourceId });
+                    transientByPage.set(sourceId, list);
+                    if (transition.screenshot) {
+                        const screenshotPath = path.resolve(path.dirname(page.filePath), transition.screenshot.relativePath);
+                        clicks.push({ node: targetId, target: path.relative(outputDir, screenshotPath).replaceAll('\\', '/'), tooltip: 'Open state screenshot' });
+                    }
+                }
+            }
+            if (!targetId) {
+                continue;
+            }
+            const pairKey = `${sourceId}>${targetId}`;
+            if (adjacency.get(targetId)?.has(sourceId)) {
+                if (drawnBack.has(pairKey)) {
+                    continue;
+                }
+                drawnBack.add(pairKey);
+                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 });
+        }
+    }
+    const pageClicks = [];
+    for (const pageNode of pageNodes) {
+        const filePath = pageNode.filePath;
+        if (!filePath) {
+            continue;
+        }
+        const relativeFile = path.relative(outputDir, filePath).replaceAll('\\', '/');
+        pageClicks.push({ node: pageNode.id, target: relativeFile, tooltip: `Open ${pageNode.label}` });
+    }
+    return { pages: pageNodes, transientByPage, edges, clicks: [...pageClicks, ...clicks], classAssignment };
+}
+function renderMermaidBody(outputDir, pages) {
+    return renderMermaidFromGraph(buildStateGraph(outputDir, pages));
+}
+function renderMermaidFromGraph(graph) {
+    const lines = ['flowchart TD'];
+    if (graph.pages.length === 0) {
+        lines.push('  empty["No documented states"]');
+        return lines.join('\n');
+    }
+    for (const page of graph.pages) {
+        lines.push(`  ${renderNodeLine(page)}`);
+        const children = graph.transientByPage.get(page.id);
+        if (!children || children.length === 0) {
+            continue;
+        }
+        lines.push(`  subgraph sg_${page.id} ["${escapeMermaidLabel(page.label)} — transient states"]`);
+        for (const child of children) {
+            lines.push(`    ${renderNodeLine(child)}`);
+        }
+        lines.push('  end');
+    }
+    for (const edge of graph.edges) {
+        let arrow = '-->';
+        if (edge.isBack) {
+            arrow = '-.->';
+        }
+        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;');
+    lines.push('  classDef section fill:#f3e8ff,stroke:#9333ea,color:#0f172a;');
+    for (const [className, ids] of graph.classAssignment) {
+        if (ids.length === 0) {
+            continue;
+        }
+        lines.push(`  class ${ids.join(',')} ${className};`);
+    }
+    for (const click of graph.clicks) {
+        lines.push(`  click ${click.node} "${click.target}" "${escapeMermaidLabel(click.tooltip)}"`);
+    }
+    return lines.join('\n');
+}
+function renderStateMapFromGraph(graph) {
+    if (graph.pages.length === 0) {
+        return '';
+    }
+    const clickByNode = new Map(graph.clicks.map((click) => [click.node, click]));
+    const rows = ['| State | Type | Open |', '| --- | --- | --- |'];
+    for (const pageNode of graph.pages) {
+        const pageClick = clickByNode.get(pageNode.id);
+        let openCell = '—';
+        if (pageClick) {
+            openCell = `[open page](${pageClick.target})`;
+        }
+        rows.push(`| ${escapeTable(pageNode.label)} | page | ${openCell} |`);
+        for (const child of graph.transientByPage.get(pageNode.id) ?? []) {
+            const childClick = clickByNode.get(child.id);
+            let childCell = '—';
+            if (childClick) {
+                childCell = `[view screenshot](${childClick.target})`;
+            }
+            rows.push(`| ${escapeTable(child.label)} | ${child.kind} | ${childCell} |`);
+        }
+    }
+    return rows.join('\n');
+}
+function renderNodeLine(node) {
+    const label = `${escapeMermaidLabel(node.label)}<br/>${escapeMermaidLabel(node.subLabel)}`;
+    if (node.kind === 'dialog' || node.kind === 'modal') {
+        return `${node.id}{{"${label}"}}`;
+    }
+    if (node.kind === 'section') {
+        return `${node.id}("${label}")`;
+    }
+    return `${node.id}["${label}"]`;
+}
+function createsCycle(sourceId, targetId, adjacency) {
+    if (sourceId === targetId) {
+        return true;
+    }
+    const pending = [targetId];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const nodeId = pending.pop();
+        if (!nodeId || visited.has(nodeId)) {
+            continue;
+        }
+        if (nodeId === sourceId) {
+            return true;
+        }
+        visited.add(nodeId);
+        pending.push(...(adjacency.get(nodeId) || []));
+    }
+    return false;
+}
+function escapeMermaidLabel(value) {
+    return normalizeInlineText(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('|', '&#124;');
+}
+function escapeTable(value) {
+    return normalizeInlineText(value).replaceAll('|', '\\|');
+}
+function classForKind(kind) {
+    if (kind === 'section') {
+        return 'section';
+    }
+    if (kind === 'page') {
+        return 'page';
+    }
+    return 'dialog';
+}
+export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderStateMapFromGraph };

package/dist/package.json

@@ -1,13 +1,15 @@
 {
   "name": "explorbot",
-  "version": "0.1.31",
+  "version": "0.2.0",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
   "exports": {
     ".": {
-      "bun": "./src/index.tsx",
+      "types": "./dist/src/index.d.ts",
+      "bun": "./src/index.ts",
       "import": "./dist/src/index.js"
     }
   },
@@ -27,13 +29,13 @@
     "assets/sample-files/"
   ],
   "scripts": {
-    "build": "bun run src/index.tsx build && bun run build:bin",
+    "build": "bun run build:bin",
     "build:bin": "bun build bin/explorbot-cli.ts --outdir bin --target node --external commander --format esm",
     "build:npm": "bash scripts/build-npm.sh",
     "prepublishOnly": "npm run build:npm",
-    "dev": "bun run src/index.tsx",
-    "start": "node dist/index.js",
-    "init": "bun run src/index.tsx init",
+    "dev": "bun run bin/explorbot-cli.ts start",
+    "start": "node dist/bin/explorbot-cli.js",
+    "init": "bun run bin/explorbot-cli.ts init",
     "test": "codeceptjs run",
     "test:headless": "codeceptjs run --headless",
     "test:ui": "bun test tests/ui",

package/dist/src/action-result.d.ts

@@ -0,0 +1,131 @@
+import { type HtmlConfig } from './config.js';
+import type { Link, WebPageState } from './state-manager.js';
+import { TTLCache } from './utils/cache.js';
+import { type HtmlDiffPart, type HtmlDiffResult } from './utils/html-diff.js';
+interface ActionResultData extends WebPageState {
+    html?: string;
+    fullUrl?: string | undefined;
+    screenshot?: Buffer;
+    screenshotFile?: string;
+    logFile?: string;
+    htmlFile?: string;
+    title?: string;
+    timestamp?: Date;
+    error?: string | null;
+    h1?: string | undefined;
+    h2?: string | undefined;
+    h3?: string | undefined;
+    h4?: string | undefined;
+    browserLogs?: any[];
+    iframeSnapshots?: Array<{
+        src: string;
+        html: string;
+        id?: string;
+    }>;
+    ariaSnapshot?: string | null;
+    ariaSnapshotFile?: string;
+    iframeURL?: string;
+    links?: Link[];
+}
+export interface PageDiff {
+    urlChanged: boolean;
+    previousUrl?: string;
+    currentUrl: string;
+    ariaChanges?: string | null;
+    ariaChangeCount?: number;
+    htmlParts?: HtmlDiffPart[];
+    iframes?: string;
+}
+export interface ToolResultMetadata {
+    url: string;
+    locator: string;
+    targetedHtml: string;
+    pageDiff: PageDiff | null;
+    iframeURL?: string;
+}
+export declare class ActionResult implements ActionResultData {
+    id?: number;
+    title: string;
+    httpStatus: number | undefined;
+    error: string | null;
+    timestamp: Date;
+    h1: string | undefined;
+    h2: string | undefined;
+    h3: string | undefined;
+    h4: string | undefined;
+    url: string;
+    fullUrl: string | undefined;
+    browserLogs: any[];
+    iframeSnapshots: Array<{
+        src: string;
+        html: string;
+        id?: string;
+    }>;
+    iframeURL: string | undefined;
+    readonly screenshotFile: string | undefined;
+    _screenshot: Buffer | undefined;
+    readonly htmlFile: string | undefined;
+    _html: string | undefined;
+    snapshotCache: TTLCache<string>;
+    readonly logFile: string | undefined;
+    readonly ariaSnapshotFile: string | undefined;
+    _ariaSnapshot: string | null | undefined;
+    _lastExtractedHtml: string | undefined;
+    notes: string[];
+    links: Link[];
+    verifications?: Record<string, boolean>;
+    constructor(data: ActionResultData);
+    get hash(): string;
+    get html(): string;
+    set html(value: string);
+    get screenshot(): Buffer | undefined;
+    get ariaSnapshot(): string | null;
+    set ariaSnapshot(value: string | null);
+    extractHeadings(html: string): void;
+    addVerification(assertion: string, passed: boolean): void;
+    getVerification(message: string | RegExp): boolean | null;
+    isSameUrl(state: WebPageState): boolean;
+    isMatchedBy(state: WebPageState): boolean;
+    isRelevantExperienceRecord(record: WebPageState, options?: {
+        includeDescendantExperience?: boolean;
+    }): boolean;
+    simplifiedHtml(htmlConfig?: HtmlConfig): Promise<string>;
+    combinedHtml(htmlConfig?: HtmlConfig & {
+        keepPositions?: boolean;
+    }): Promise<string>;
+    textHtml(htmlConfig?: HtmlConfig): Promise<string>;
+    getInteractiveARIA(): string;
+    getCompactARIA(): string;
+    normalizeHtmlConfig(htmlConfig?: HtmlConfig): HtmlConfig | undefined;
+    static fromState(state: WebPageState): ActionResult;
+    static loadStateFile(file: string): string | null;
+    static loadHtmlFromFile(htmlFile: string): string | null;
+    static loadScreenshotFromFile(screenshotFile: string): Buffer | undefined;
+    static loadBrowserLogsFromFile(logFile: string): any[];
+    static loadAriaSnapshotFromFile(ariaSnapshotFile: string): string | null;
+    toAiContext(): string;
+    get relativeUrl(): string | null;
+    get isInsideIframe(): boolean;
+    getStateHash(): string;
+    diff(previousState: ActionResult | null): Promise<Diff>;
+    toToolResult(previousState: ActionResult | null, locator: string): Promise<ToolResultMetadata>;
+}
+export declare class Diff {
+    current: ActionResult;
+    previous: ActionResult | null;
+    _htmlDiffResult: HtmlDiffResult | null;
+    _ariaDiffResult: string | null;
+    _ariaChangeCount: number;
+    _isSameUrl: boolean;
+    constructor(current: ActionResult, previous: ActionResult | null);
+    static create(current: ActionResult, previous: ActionResult | null): Promise<Diff>;
+    hasChanges(): boolean;
+    isSameUrl(): boolean;
+    urlHasChanged(): boolean;
+    get htmlParts(): HtmlDiffPart[];
+    get ariaChanged(): string | null;
+    get ariaChangeCount(): number;
+    get htmlDiff(): HtmlDiffResult | null;
+    calculate(): Promise<void>;
+}
+export {};