explorbot 0.1.31 → 0.2.0

package/dist/src/components/AddKnowledge.js

@@ -1,8 +1,7 @@
 import { Box, Text, useInput } from 'ink';
 import React, { useEffect, useState } from 'react';
-import { KnowledgeTracker } from '../knowledge-tracker.js';
 import InputReadline from './InputReadline.js';
-const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
+const AddKnowledge = ({ initialUrl = '', knowledgeTracker, onComplete, onCancel }) => {
     const [urlPattern, setUrlPattern] = useState(initialUrl);
     const [description, setDescription] = useState('');
     const [activeField, setActiveField] = useState(initialUrl ? 'description' : 'url');
@@ -11,18 +10,16 @@ const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
     const isStandalone = !onComplete;
     useEffect(() => {
         try {
-            const knowledgeTracker = new KnowledgeTracker();
             const urls = knowledgeTracker.getExistingUrls();
             setSuggestedUrls(urls);
         }
         catch (error) {
             console.error('Failed to load suggestions:', error);
         }
-    }, []);
+    }, [knowledgeTracker]);
     useEffect(() => {
         if (urlPattern.trim()) {
             try {
-                const knowledgeTracker = new KnowledgeTracker();
                 const knowledge = knowledgeTracker.getKnowledgeForUrl(urlPattern);
                 setExistingKnowledge(knowledge);
             }
@@ -34,13 +31,12 @@ const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
         else {
             setExistingKnowledge([]);
         }
-    }, [urlPattern]);
+    }, [urlPattern, knowledgeTracker]);
     const handleSave = () => {
         if (!urlPattern.trim() || !description.trim()) {
             return;
         }
         try {
-            const knowledgeTracker = new KnowledgeTracker();
             const result = knowledgeTracker.addKnowledge(urlPattern.trim(), description.trim());
             const action = result.isNewFile ? 'Created' : 'Updated';
             console.log(`\nKnowledge ${action} in: ${result.filename}`);

package/dist/src/components/AddRule.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+interface AddRuleProps {
+    initialAgent?: string;
+    initialName?: string;
+    onComplete?: () => void;
+    onCancel?: () => void;
+}
+declare const AddRule: React.FC<AddRuleProps>;
+export default AddRule;

package/dist/src/components/App.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { ExplorBot } from '../explorbot.js';
+interface AppProps {
+    explorBot: ExplorBot;
+    initialShowInput?: boolean;
+    exitOnEmptyInput?: boolean;
+}
+export declare function App({ explorBot, initialShowInput, exitOnEmptyInput }: AppProps): React.JSX.Element;
+export {};

package/dist/src/components/App.js

@@ -111,7 +111,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
                 return;
             setChecklistData({
                 config: explorBot.getConfig(),
-                knowledgeTracker: explorBot.getKnowledgeTracker(),
+                knowledgeTracker: explorBot.knowledgeTracker(),
             });
             setShowWelcome(true);
             setShowInput(true);
@@ -283,7 +283,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
         React.createElement(Box, { height: 3, flexDirection: "row", justifyContent: "space-between", alignItems: "center", paddingX: 1 },
             React.createElement(ActivityPane, { isInputVisible: showInput }),
             showSessionTimer && React.createElement(SessionTimer, { startedAt: sessionStartedAtRef.current })),
-        showWelcome && React.createElement(WelcomeCommands, { hasKnowledge: explorBot.getKnowledgeTracker().listAllKnowledge().length > 0 }),
+        showWelcome && React.createElement(WelcomeCommands, { hasKnowledge: explorBot.knowledgeTracker().listAllKnowledge().length > 0 }),
         showInput && React.createElement(Box, { height: 1 }),
         interruptPrompt && showInput && (React.createElement(Box, { paddingX: 1 },
             React.createElement(Text, { color: "yellow" }, interruptPrompt))),

package/dist/src/components/Autocomplete.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const Autocomplete: React.FC;
+export default Autocomplete;

package/dist/src/components/InputPane.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { CommandHandler } from '../command-handler.js';
+interface InputPaneProps {
+    commandHandler: CommandHandler;
+    exitOnEmptyInput?: boolean;
+    onSubmit?: (value: string) => Promise<void>;
+    onCommandStart?: () => void;
+    onCommandComplete?: () => void;
+    isActive?: boolean;
+    visible?: boolean;
+}
+declare const InputPane: React.FC<InputPaneProps>;
+export default InputPane;

package/dist/src/components/InputReadline.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { CommandHandler } from '../command-handler.js';
+interface InputReadlineProps {
+    commandHandler?: CommandHandler;
+    exitOnEmptyInput?: boolean;
+    onSubmit?: (value: string) => void | Promise<void>;
+    onChange?: (value: string) => void;
+    onCommandStart?: () => void;
+    onCommandComplete?: () => void;
+    isActive?: boolean;
+    visible?: boolean;
+    value?: string;
+    placeholder?: string;
+    showPrompt?: boolean;
+}
+declare const InputReadline: React.FC<InputReadlineProps>;
+export default InputReadline;

package/dist/src/components/LogPane.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+interface LogPaneProps {
+    verboseMode: boolean;
+}
+declare const LogPane: React.FC<LogPaneProps>;
+export default LogPane;

package/dist/src/components/PlanEditor.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { Test } from '../test-plan.js';
+interface PlanEditorProps {
+    tasks: Test[];
+    onClose: () => void;
+    isActive: boolean;
+}
+declare const PlanEditor: React.FC<PlanEditorProps>;
+export default PlanEditor;

package/dist/src/components/PlanPane.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+interface PlanPaneProps {
+    completedPlans: PlanSummary[];
+    activePlan: PlanSummary | null;
+}
+declare const PlanPane: React.FC<PlanPaneProps>;
+export default PlanPane;
+export interface PlanSummary {
+    title: string;
+    testCount: number;
+    passed: number;
+    failed: number;
+}

package/dist/src/components/SessionTimer.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+type SessionTimerProps = {
+    startedAt: number;
+};
+declare const SessionTimer: React.FC<SessionTimerProps>;
+export default SessionTimer;

package/dist/src/components/StateTransitionPane.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { StateTransition, WebPageState } from '../state-manager.js';
+interface StateTransitionPaneProps {
+    transition?: StateTransition;
+    currentState?: WebPageState;
+}
+declare const StateTransitionPane: React.FC<StateTransitionPaneProps>;
+export default StateTransitionPane;

package/dist/src/components/StatusPane.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+export declare const StatusPane: React.FC<{
+    onComplete?: () => void;
+}>;

package/dist/src/components/TaskPane.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { Test } from '../test-plan.js';
+export declare const WINDOW_SIZE = 7;
+interface TaskPaneProps {
+    tasks: Test[];
+    scrollOffset?: number;
+}
+declare const TaskPane: React.FC<TaskPaneProps>;
+export default TaskPane;

package/dist/src/components/Welcome.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const Welcome: React.FC;
+export default Welcome;

package/dist/src/components/WelcomeChecklist.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { ExplorbotConfig } from '../config.js';
+import type { KnowledgeTracker } from '../knowledge-tracker.js';
+interface WelcomeChecklistProps {
+    config: ExplorbotConfig;
+    knowledgeTracker: KnowledgeTracker;
+}
+declare const WelcomeChecklist: React.FC<WelcomeChecklistProps>;
+export default WelcomeChecklist;

package/dist/src/components/WelcomeCommands.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+interface WelcomeCommandsProps {
+    hasKnowledge: boolean;
+}
+declare const WelcomeCommands: React.FC<WelcomeCommandsProps>;
+export default WelcomeCommands;

package/dist/src/components/autocomplete-store.d.ts

@@ -0,0 +1,10 @@
+import type { CommandAutocompleteSuggestion } from '../command-handler.js';
+interface AutocompleteState {
+    suggestions: CommandAutocompleteSuggestion[];
+    argumentHint?: string;
+    selectedIndex: number;
+    visible: boolean;
+}
+export declare const setAutocompleteState: (next: AutocompleteState) => void;
+export declare const useAutocompleteState: () => AutocompleteState;
+export {};

package/dist/src/components/parse-keypress.d.ts

@@ -0,0 +1,12 @@
+import { Buffer } from 'node:buffer';
+export declare const nonAlphanumericKeys: string[];
+export default function parseKeypress(value?: string | Buffer): {
+    name: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    option: boolean;
+    sequence: string;
+    raw: string | undefined;
+    code: string | undefined;
+};

package/dist/src/config.d.ts

@@ -0,0 +1,253 @@
+interface PlaywrightConfig {
+    browser: 'chromium' | 'firefox' | 'webkit';
+    url: string;
+    show?: boolean;
+    windowSize?: string;
+    slowMo?: number;
+    chromium?: {
+        args?: string[];
+    };
+    firefox?: {
+        args?: string[];
+    };
+    webkit?: {
+        args?: string[];
+    };
+    timeout?: number;
+    waitForAction?: number;
+    waitForNavigation?: 'load' | 'domcontentloaded' | 'networkidle';
+    waitForTimeout?: number;
+    spinnerSelectors?: string[];
+    ignoreHTTPSErrors?: boolean;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    args?: string[];
+}
+type PlaywrightHookFn = (ctx: {
+    page: any;
+    url: string;
+}) => Promise<void> | void;
+type CodeceptJSHookFn = (ctx: {
+    I: any;
+    url: string;
+}) => Promise<void> | void;
+interface PlaywrightHook {
+    type: 'playwright';
+    hook: PlaywrightHookFn;
+}
+interface CodeceptJSHook {
+    type: 'codeceptjs';
+    hook: CodeceptJSHookFn;
+}
+type Hook = PlaywrightHook | CodeceptJSHook;
+type HookPatternMap = Record<string, Hook>;
+type HookConfig = Hook | HookPatternMap;
+interface HooksConfig {
+    beforeHook?: HookConfig;
+    afterHook?: HookConfig;
+}
+interface AgentConfig extends HooksConfig {
+    model?: any;
+    enabled?: boolean;
+    systemPrompt?: string;
+    rules?: RuleEntry[];
+    providerOptions?: Record<string, any>;
+    reasoning?: 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+}
+interface ResearcherAgentConfig extends AgentConfig {
+    excludeSelectors?: string[];
+    includeSelectors?: string[];
+    stopWords?: string[];
+    maxElementsToExplore?: number;
+    maxExpandableClicks?: number;
+    retries?: number;
+    sections?: string[];
+    focusSections?: string[];
+    errorPageTimeout?: number;
+}
+interface TesterAgentConfig extends AgentConfig {
+    progressCheckInterval?: number;
+}
+interface PilotAgentConfig extends AgentConfig {
+    stepsToReview?: number;
+}
+interface NavigatorAgentConfig extends AgentConfig {
+    addHtmlOnTry?: number;
+    maxAttempts?: number;
+    verifyAttempts?: number;
+    verifyTimeout?: number;
+}
+type HealFn = (ctx: {
+    I: any;
+}) => Promise<void> | void;
+interface HealRecipe {
+    priority?: number;
+    steps?: string[];
+    fn: (context: {
+        step: any;
+        error: Error;
+        prevSteps?: any[];
+    }) => HealFn | Promise<HealFn | null> | null;
+}
+interface RerunnerAgentConfig extends AgentConfig {
+    healLimit?: number;
+    ariaSnapshotLimit?: number;
+    retryFailedStep?: Record<string, any>;
+    screenshotOnFail?: Record<string, any>;
+    recipes?: Record<string, HealRecipe>;
+}
+interface PlannerAgentConfig extends AgentConfig {
+    styles?: string[];
+    stylesDir?: string;
+}
+interface ScreencastConfig {
+    size?: {
+        width: number;
+        height: number;
+    };
+    quality?: number;
+}
+interface HistorianAgentConfig extends AgentConfig {
+    framework?: 'codeceptjs' | 'playwright';
+    screencast?: boolean | ScreencastConfig;
+}
+interface AgentsConfig {
+    tester?: TesterAgentConfig;
+    navigator?: NavigatorAgentConfig;
+    researcher?: ResearcherAgentConfig;
+    planner?: PlannerAgentConfig;
+    pilot?: PilotAgentConfig;
+    driller?: AgentConfig;
+    'experience-compactor'?: AgentConfig;
+    captain?: AgentConfig;
+    quartermaster?: AgentConfig;
+    historian?: HistorianAgentConfig;
+    fisherman?: AgentConfig;
+    chief?: AgentConfig;
+    curler?: AgentConfig;
+    rerunner?: RerunnerAgentConfig;
+    analyst?: AgentConfig;
+}
+interface AIConfig {
+    model: any;
+    apiKey?: string;
+    config?: Record<string, any>;
+    langfuse?: {
+        enabled?: boolean;
+        publicKey?: string;
+        secretKey?: string;
+        baseUrl?: string;
+    };
+    tools?: {
+        enabled: boolean;
+        maxConcurrency: number;
+        timeout: number;
+    };
+    vision?: boolean;
+    visionModel?: any;
+    agenticModel?: any;
+    maxAttempts?: number;
+    retryDelay?: number;
+    agents?: AgentsConfig;
+}
+interface HtmlConfig {
+    minimal?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    combined?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    text?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
+interface ActionConfig {
+    delay?: number;
+    retries?: number;
+}
+interface ReporterConfig {
+    enabled?: boolean;
+    html?: boolean;
+    markdown?: boolean;
+    runGroup?: string | null;
+}
+type ApiHookFn = (ctx: {
+    headers: Record<string, string>;
+    baseEndpoint: string;
+}) => Promise<Record<string, string> | undefined> | Record<string, string> | undefined;
+interface ApiConfig {
+    baseEndpoint?: string;
+    spec?: string[];
+    headers?: Record<string, string>;
+    bootstrap?: ApiHookFn;
+    teardown?: ApiHookFn;
+}
+interface WebConfig {
+    url: string;
+}
+interface ExplorbotConfig {
+    web?: WebConfig;
+    playwright: PlaywrightConfig;
+    ai: AIConfig;
+    html?: HtmlConfig;
+    action?: ActionConfig;
+    dirs?: {
+        knowledge: string;
+        experience: string;
+        output: string;
+    };
+    experience?: {
+        maxReadLines?: number;
+    };
+    reporter?: ReporterConfig;
+    api?: ApiConfig;
+    stepsFile?: string;
+    files?: Record<string, string>;
+    dynamicPageRegex?: string;
+}
+type RuleEntry = string | Record<string, string>;
+export declare const EXPLORBOT_CONFIG_PATHS: string[];
+export type { ExplorbotConfig, PlaywrightConfig, AIConfig, HtmlConfig, ActionConfig, AgentConfig, AgentsConfig, HistorianAgentConfig, ResearcherAgentConfig, NavigatorAgentConfig, PlannerAgentConfig, RerunnerAgentConfig, HealRecipe, Hook, HookConfig, HooksConfig, PlaywrightHook, CodeceptJSHook, HookPatternMap, RuleEntry, ReporterConfig, ApiConfig, WebConfig, ApiHookFn, };
+export declare class ConfigParser {
+    static instance: ConfigParser;
+    config: ExplorbotConfig | null;
+    configPath: string | null;
+    runtimeBaseUrlOverride: string | null;
+    constructor();
+    static loadEnv(filePath: string): void;
+    static getInstance(): ConfigParser;
+    loadConfig(options?: {
+        config?: string;
+        path?: string;
+        baseUrl?: string;
+    }): Promise<ExplorbotConfig>;
+    getConfig(): ExplorbotConfig;
+    getConfigPath(): string | null;
+    getOutputDir(): string;
+    getProjectRoot(): string;
+    resolveProjectDir(relativeDir: string): string;
+    getStatesDir(): string;
+    getPlansDir(): string;
+    getTestsDir(): string;
+    static resetForTesting(): void;
+    static setupTestConfig(): void;
+    static getTestDirectories(): string[];
+    static cleanupAllTestDirectories(): void;
+    findConfigFile(): string | null;
+    loadConfigModule(configPath: string): Promise<any>;
+    resolveConfig(config: ExplorbotConfig, options?: {
+        baseUrl?: string;
+    }): ExplorbotConfig;
+    validateConfig(config: ExplorbotConfig): void;
+    getNestedValue(obj: any, path: string): any;
+    mergeWithDefaults(config: Partial<ExplorbotConfig>): ExplorbotConfig;
+    deepMerge(target: any, source: any): any;
+    ensureDirectory(path: string): void;
+}
+export declare function outputPath(...segments: string[]): string;

package/dist/src/config.js

@@ -96,6 +96,18 @@ export class ConfigParser {
             throw new Error('Config path not found');
         return path.join(path.dirname(configPath), config.dirs?.output || 'output');
     }
+    getProjectRoot() {
+        const configPath = this.getConfigPath();
+        if (configPath)
+            return path.dirname(configPath);
+        return process.cwd();
+    }
+    resolveProjectDir(relativeDir) {
+        const configPath = this.getConfigPath();
+        if (!configPath)
+            return relativeDir;
+        return path.join(path.dirname(configPath), relativeDir);
+    }
     getStatesDir() {
         return outputPath('states');
     }

package/dist/src/execution-controller.d.ts

@@ -0,0 +1,25 @@
+import { EventEmitter } from 'node:events';
+export type InputCallback = (prompt: string) => Promise<string | null>;
+export declare class ExecutionController extends EventEmitter {
+    static instance: ExecutionController;
+    interrupted: boolean;
+    inputCallback: InputCallback | null;
+    interruptResolvers: Array<() => void>;
+    abortController: AbortController | null;
+    awaitingInput: boolean;
+    constructor();
+    static getInstance(): ExecutionController;
+    setInputCallback(callback: InputCallback): void;
+    startExecution(): void;
+    getAbortSignal(): AbortSignal | undefined;
+    interrupt(): void;
+    isAwaitingInput(): boolean;
+    isInterrupted(): boolean;
+    waitForInterrupt(): Promise<void>;
+    checkInterrupt(): Promise<string | null>;
+    handleInterrupt(prompt?: string): Promise<string | null>;
+    requestInput(prompt: string): Promise<string | null>;
+    readlineInput(prompt: string): Promise<string | null>;
+    reset(): void;
+}
+export declare const executionController: ExecutionController;

package/dist/src/experience-tracker.d.ts

@@ -0,0 +1,112 @@
+import type { ActionResult } from './action-result.js';
+import { KnowledgeTracker } from './knowledge-tracker.js';
+export declare const RECENT_WINDOW_DAYS = 30;
+/**
+ * Stores and reads per-page experience files (`./experience/<stateHash>.md`).
+ *
+ * Two writers, two contracts:
+ *
+ *   writeFlow(state, body, relatedUrls?)  — caller hands in a fully-formatted
+ *                                            `## FLOW: <imperative title>` block (multi-step,
+ *                                            `*` bullets + optional ```js``` + `>` discovery,
+ *                                            ends with `---`). Tracker dedups + prepends.
+ *   writeAction(state, ActionInput)        — `## ACTION: <imperative title>`, single-step,
+ *                                            optional `Solution:` line + one ```js``` code block.
+ *                                            Title normalized via normalizeTitle().
+ *
+ * - Always h2. Never h3 for FLOW/ACTION.
+ * - On read (getSuccessfulExperience), headings are rendered as
+ *   `## HOW to <title> (multi-step|single-step)` so prompts get natural phrasing.
+ */
+export declare class ExperienceTracker {
+    experienceDir: string;
+    disabled: boolean;
+    knowledgeTracker: KnowledgeTracker;
+    constructor(knowledgeTracker: KnowledgeTracker, options?: {
+        disabled?: boolean;
+    });
+    getExperienceDirectories(): string[];
+    ensureDirectory(dir: string): void;
+    readExperienceFile(stateHash: string): {
+        content: string;
+        data: any;
+    };
+    readExperienceFileAt(filePath: string): {
+        content: string;
+        data: any;
+    };
+    writeExperienceFile(stateHash: string, content: string, frontmatter?: any): void;
+    getExperienceFilePath(stateHash: string): string;
+    ensureExperienceFile(state: ActionResult): string;
+    updateSummary(state: ActionResult, summary: string): void;
+    isWritingDisabled(state: ActionResult): boolean;
+    writeAction(state: ActionResult, action: ActionInput): void;
+    writeFlow(state: ActionResult, body: string, relatedUrls?: string[]): void;
+    getAllExperience(): ExperienceFile[];
+    getRelevantExperience(state: ActionResult, options?: {
+        includeDescendantExperience?: boolean;
+    }): ExperienceFile[];
+    getSuccessfulExperience(state: ActionResult, options?: {
+        includeDescendants?: boolean;
+        stripCode?: boolean;
+    }): string[];
+    getExperienceTableOfContents(state: ActionResult, options?: {
+        includeDescendantExperience?: boolean;
+    }): ExperienceTocEntry[];
+    renderExperienceTocFor(state: ActionResult): string;
+    getExperienceSection(fileTag: string, sectionIndex: number, state: ActionResult, options?: {
+        includeDescendantExperience?: boolean;
+    }): {
+        title: string;
+        url: string;
+        content: string;
+    } | null;
+    buildToc(records: ExperienceFile[]): ExperienceTocEntry[];
+    readSectionByHash(fileHash: string, sectionIndex: number): {
+        title: string;
+        body: string;
+    } | null;
+    findExperienceFileByHash(fileHash: string): string | null;
+    listAllExperienceToc(filter?: string, options?: {
+        recency?: 'recent' | 'old';
+    }): ExperienceTocEntry[];
+    getExperienceSectionByTag(fileTag: string, sectionIndex: number, filter?: string): {
+        title: string;
+        url: string;
+        content: string;
+        fileHash: string;
+    } | null;
+}
+export declare function renderExperienceToc(toc: ExperienceTocEntry[]): string;
+export interface ExperienceFile {
+    filePath: string;
+    data: {
+        url?: string;
+        title?: string;
+        [key: string]: any;
+    };
+    content: string;
+    mtime: Date;
+}
+export interface ActionInput {
+    title: string;
+    code: string;
+    explanation?: string;
+}
+export interface SessionStep {
+    message: string;
+    status: 'passed' | 'failed' | 'neutral';
+    tool?: string;
+    code?: string;
+    discovery?: string;
+}
+export interface ExperienceTocEntry {
+    fileTag: string;
+    fileHash: string;
+    url: string;
+    sections: {
+        index: number;
+        level: 2 | 3;
+        title: string;
+    }[];
+}