explorbot 0.1.31 → 0.2.0

package/dist/src/observability.js

@@ -1,4 +1,5 @@
 import { trace } from '@opentelemetry/api';
+import { redactSecrets } from './utils/secrets.js';
 let current = null;
 export const Observability = {
     async run(name, metadata, fn) {
@@ -70,7 +71,7 @@ function buildRootSpanAttributes(name, metadata) {
         attributes['langfuse.trace.tags'] = metadata.tags;
     }
     if (metadata.input !== undefined) {
-        attributes['langfuse.trace.input'] = JSON.stringify(metadata.input);
+        attributes['langfuse.trace.input'] = redactSecrets(JSON.stringify(metadata.input));
     }
     return attributes;
 }

package/dist/src/playwright-recorder.d.ts

@@ -0,0 +1,31 @@
+export interface TraceCall {
+    class: string;
+    method: string;
+    params: Record<string, any>;
+}
+export interface VerificationStep {
+    name: string;
+    args: any[];
+}
+export declare class PlaywrightRecorder {
+    context: any;
+    tracing: any;
+    active: boolean;
+    nextGroupId: number;
+    verifications: VerificationStep[];
+    recordVerification(steps: VerificationStep[]): void;
+    drainVerifications(): VerificationStep[];
+    start(browserContext: any): Promise<void>;
+    beginAction(title: string): Promise<string | null>;
+    endAction(): Promise<void>;
+    exportChunk(): Promise<Map<string, TraceCall[]>>;
+    stop(): Promise<void>;
+    isActive(): boolean;
+}
+declare function parseTrace(ndjson: string): Map<string, TraceCall[]>;
+export declare function renderCall(call: TraceCall): string;
+export declare function renderAssertion(assertion: {
+    name: string;
+    args: any[];
+}): string;
+export { parseTrace };

package/dist/src/reporter.d.ts

@@ -0,0 +1,34 @@
+import { Client } from '@testomatio/reporter';
+import type { Step } from '@testomatio/reporter/types/types.js';
+import type { ReporterConfig } from './config.js';
+import type { StateManager } from './state-manager.js';
+import { Test } from './test-plan.js';
+export type ReporterMeta = Record<string, string | undefined>;
+export interface ReporterStep {
+    title: string;
+    status: 'passed' | 'failed';
+    code: string[];
+    discovery?: string;
+}
+export declare class Reporter {
+    client: Client;
+    isRunStarted: boolean;
+    reporterEnabled: boolean;
+    stateManager?: StateManager;
+    constructor(config?: ReporterConfig, stateManager?: StateManager);
+    buildTitle(): string;
+    static resolveEnabled(config?: ReporterConfig): boolean;
+    configureHtmlPipe(): void;
+    configureMarkdownPipe(): void;
+    configureRunGroup(runGroup: string | null | undefined): void;
+    startRun(): Promise<void>;
+    reportTestStart(test: Test): Promise<void>;
+    combineStepsAndNotes(test: Test, lastScreenshotFile?: string): Step[];
+    buildVerificationStep(test: Test, lastScreenshotFile?: string): Step | undefined;
+    reportTest(test: Test, meta?: ReporterMeta): Promise<void>;
+    finishRun(): Promise<void>;
+    isEnabled(): boolean;
+    setRunDescription(text: string): Promise<void>;
+    extractLastNoteMessage(test: Test): string;
+    reportSteps(test: Test, steps: ReporterStep[]): Promise<void>;
+}

package/dist/src/state-manager.d.ts

@@ -0,0 +1,160 @@
+import { ActionResult } from './action-result.js';
+import type { ExperienceTracker } from './experience-tracker.js';
+import type { KnowledgeTracker, Knowledge } from './knowledge-tracker.js';
+export interface Link {
+    title: string;
+    url: string;
+    visible?: boolean;
+}
+export interface WebPageState {
+    /** Unique incremental state identifier */
+    id?: number;
+    /** URL path without domain, including hash: /path/to/page#section */
+    url: string;
+    /** Page title */
+    title?: string;
+    /** HTTP status of the main document navigation */
+    httpStatus?: number;
+    /** Full URL for reference */
+    fullUrl?: string;
+    /** Timestamp when state was captured */
+    timestamp?: Date;
+    /** Hash of the state for unique identification */
+    hash?: string;
+    /** HTML file path */
+    htmlFile?: string;
+    /** Screenshot file path */
+    screenshotFile?: string;
+    /** Log file path */
+    logFile?: string;
+    /** HTML content */
+    html?: string;
+    notes?: string[];
+    /** Page headings */
+    h1?: string;
+    h2?: string;
+    h3?: string;
+    h4?: string;
+    ariaSnapshot?: string | null;
+    ariaSnapshotFile?: string;
+    links?: Link[];
+    verifications?: Record<string, boolean>;
+}
+export interface StateTransition {
+    /** Previous state (null if this is the first state) */
+    fromState: WebPageState | null;
+    /** Current state */
+    toState: WebPageState;
+    /** Code block that caused the transition */
+    codeBlock: string;
+    /** Timestamp of the transition */
+    timestamp: Date;
+    /** Any error that occurred during transition */
+    error?: string;
+    /** What triggered the state change */
+    trigger: 'manual' | 'navigation' | 'automatic';
+}
+export type StateChangeListener = (event: StateTransition) => void;
+export type { Knowledge };
+export declare class StateManager {
+    currentState: WebPageState | null;
+    stateHistory: StateTransition[];
+    allVisitedUrls: Set<string>;
+    stateChangeListeners: StateChangeListener[];
+    experienceTracker: ExperienceTracker;
+    knowledgeTracker: KnowledgeTracker;
+    nextStateId: number;
+    constructor(experienceTracker: ExperienceTracker, knowledgeTracker: KnowledgeTracker);
+    getExperienceTracker(): ExperienceTracker;
+    getKnowledgeTracker(): KnowledgeTracker;
+    /**
+     * Subscribe to state change events
+     */
+    onStateChange(listener: StateChangeListener): () => void;
+    /**
+     * Emit state change event to all listeners
+     */
+    emitStateChange(event: StateTransition): void;
+    /**
+     * Update current state from ActionResult and record transition if state changed
+     */
+    updateState(actionResult: ActionResult, codeBlock?: string, trigger?: 'manual' | 'navigation' | 'automatic'): WebPageState;
+    /**
+     * Update state from basic data (for navigation events)
+     */
+    updateStateFromBasic(url: string, title?: string, trigger?: 'manual' | 'navigation' | 'automatic'): WebPageState;
+    hasDialogAppeared(previousState: WebPageState | null, newState: WebPageState): boolean;
+    /**
+     * Generate a basic hash for state comparison
+     */
+    generateBasicHash(url: string, title?: string): string;
+    /**
+     * Get current state
+     */
+    getCurrentState(): WebPageState | null;
+    /**
+     * Check if state has changed since a given state
+     */
+    hasStateChanged(previousState: WebPageState | null): boolean;
+    /**
+     * Compare two states by their hash
+     */
+    statesEqual(state1: WebPageState | null, state2: WebPageState | null): boolean;
+    /**
+     * Get state history
+     */
+    getStateHistory(): StateTransition[];
+    isInDeadLoop(): boolean;
+    /**
+     * Get the last N transitions
+     */
+    getRecentTransitions(count?: number): StateTransition[];
+    /**
+     * Get relevant knowledge files for current state
+     */
+    getRelevantKnowledge(): Knowledge[];
+    /**
+     * Get relevant experience files for current state
+     */
+    getRelevantExperience(): string[];
+    /**
+     * Get all context for current state (knowledge + experience)
+     */
+    /**
+     * Check if we've been in this state before
+     */
+    hasVisitedState(path: string): boolean;
+    getAllVisitedUrls(): Set<string>;
+    /**
+     * Get how many times we've visited a specific path
+     */
+    getVisitCount(path: string): number;
+    /**
+     * Find the most recent transition to a specific path
+     */
+    getLastVisitToPath(path: string): StateTransition | null;
+    /**
+     * Get previous state from history for comparison.
+     * If the last transition changed URL, returns the fromState (for URL change detection).
+     * Otherwise returns the most recent toState with content (for diffing).
+     */
+    /**
+     * Clear state history (useful for testing or reset)
+     * Note: This preserves the current state, only clears navigation history
+     */
+    clearHistory(): void;
+    /**
+     * Get the number of active state change listeners
+     */
+    getListenerCount(): number;
+    /**
+     * Clear all state change listeners
+     */
+    clearListeners(): void;
+    /**
+     * Complete cleanup of the StateManager instance
+     * Clears all state, history, listeners, and caches
+     */
+    cleanup(): void;
+}
+export declare function normalizeUrl(url: string): string;

package/dist/src/state-manager.js

@@ -1,41 +1,27 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
-import { ConfigParser, outputPath } from './config.js';
-import { ExperienceTracker } from './experience-tracker.js';
 import { detectFocusArea } from './utils/aria.js';
-import { htmlTextSnapshot } from './utils/html.js';
 import { createDebug } from './utils/logger.js';
+import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 const debugLog = createDebug('explorbot:state');
 export class StateManager {
     currentState = null;
     stateHistory = [];
     allVisitedUrls = new Set();
-    knowledgeCache = [];
-    lastKnowledgeScan = null;
     stateChangeListeners = [];
     experienceTracker;
-    knowledgeDir;
+    knowledgeTracker;
     nextStateId = 1;
-    constructor() {
-        this.experienceTracker = new ExperienceTracker();
-        const configParser = ConfigParser.getInstance();
-        const config = configParser.getConfig();
-        const configPath = configParser.getConfigPath();
-        // Resolve knowledge directory relative to the config file location (project root)
-        if (configPath) {
-            const projectRoot = dirname(configPath);
-            this.knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
-        }
-        else {
-            this.knowledgeDir = config.dirs?.knowledge || 'knowledge';
-        }
+    constructor(experienceTracker, knowledgeTracker) {
+        this.experienceTracker = experienceTracker;
+        this.knowledgeTracker = knowledgeTracker;
     }
     getExperienceTracker() {
         return this.experienceTracker;
     }
+    getKnowledgeTracker() {
+        return this.knowledgeTracker;
+    }
     /**
      * Subscribe to state change events
      */
@@ -53,12 +39,6 @@ export class StateManager {
      * Emit state change event to all listeners
      */
     emitStateChange(event) {
-        // Log HTML content when state changes
-        if (event.toState.html && event.toState.html !== event.fromState?.html) {
-            let htmlContent = event?.toState?.html ?? '';
-            htmlContent = htmlTextSnapshot(htmlContent);
-            // tag('html').log(`Page HTML for ${event.toState.url}:\n${htmlContent}`);
-        }
         this.stateChangeListeners.forEach((listener) => {
             try {
                 listener(event);
@@ -68,11 +48,6 @@ export class StateManager {
             }
         });
     }
-    /**
-     * Extract state path from full URL
-     * Removes domain, port, protocol
-     * Keeps path, query, and hash: /path/to/page?tab=users#section
-     */
     /**
      * Update current state from ActionResult and record transition if state changed
      */
@@ -148,13 +123,7 @@ export class StateManager {
         if (title) {
             parts.push(`title_${title}`);
         }
-        return parts
-            .join('_')
-            .replace(/[^a-zA-Z0-9_]/g, '_')
-            .replace(/_+/g, '_')
-            .replace(/^_|_$/g, '')
-            .toLowerCase()
-            .substring(0, 200);
+        return slugify(parts.join('_')).substring(0, 200);
     }
     /**
      * Get current state
@@ -233,57 +202,14 @@ export class StateManager {
     getRecentTransitions(count = 5) {
         return this.stateHistory.slice(-count);
     }
-    /**
-     * Scan knowledge directory for .md files and cache them
-     */
-    scanKnowledgeFiles() {
-        const now = new Date();
-        // Only rescan every 30 seconds to avoid excessive file I/O
-        if (this.lastKnowledgeScan && now.getTime() - this.lastKnowledgeScan.getTime() < 30000) {
-            return;
-        }
-        this.knowledgeCache = [];
-        if (!existsSync(this.knowledgeDir)) {
-            debugLog(`Knowledge directory not found: ${this.knowledgeDir}`);
-            return;
-        }
-        try {
-            const files = readdirSync(this.knowledgeDir, { recursive: true })
-                .filter((file) => typeof file === 'string' && file.endsWith('.md'))
-                .map((file) => join(this.knowledgeDir, file));
-            for (const filePath of files) {
-                try {
-                    const fileContent = readFileSync(filePath, 'utf8');
-                    const parsed = matter(fileContent);
-                    const urlPattern = parsed.data.url || parsed.data.path || '*';
-                    this.knowledgeCache.push({
-                        filePath,
-                        url: urlPattern,
-                        ...parsed.data,
-                        content: parsed.content,
-                    });
-                    debugLog(`Loaded knowledge file: ${filePath} (pattern: ${urlPattern})`);
-                }
-                catch (error) {
-                    debugLog(`Failed to load knowledge file ${filePath}:`, error);
-                }
-            }
-            this.lastKnowledgeScan = now;
-            debugLog(`Scanned ${this.knowledgeCache.length} knowledge files`);
-        }
-        catch (error) {
-            debugLog('Failed to scan knowledge directory:', error);
-        }
-    }
     /**
      * Get relevant knowledge files for current state
      */
     getRelevantKnowledge() {
         if (!this.currentState)
             return [];
-        this.scanKnowledgeFiles();
         const actionResult = ActionResult.fromState(this.currentState);
-        return this.knowledgeCache.filter((knowledge) => actionResult.isMatchedBy(knowledge));
+        return this.knowledgeTracker.getRelevantKnowledge(actionResult);
     }
     /**
      * Get relevant experience files for current state
@@ -298,17 +224,6 @@ export class StateManager {
     /**
      * Get all context for current state (knowledge + experience)
      */
-    getCurrentContext() {
-        if (!this.currentState) {
-            throw new Error('No current state available');
-        }
-        return {
-            state: this.currentState,
-            knowledge: this.getRelevantKnowledge(),
-            experience: this.getRelevantExperience(),
-            recentTransitions: this.getRecentTransitions(),
-        };
-    }
     /**
      * Check if we've been in this state before
      */
@@ -340,41 +255,6 @@ export class StateManager {
      * If the last transition changed URL, returns the fromState (for URL change detection).
      * Otherwise returns the most recent toState with content (for diffing).
      */
-    getPreviousState() {
-        if (this.stateHistory.length === 0)
-            return null;
-        const lastTransition = this.stateHistory[this.stateHistory.length - 1];
-        if (lastTransition.fromState?.url !== lastTransition.toState?.url) {
-            return lastTransition.fromState;
-        }
-        for (let i = this.stateHistory.length - 1; i >= 0; i--) {
-            const toState = this.stateHistory[i].toState;
-            if (!toState)
-                continue;
-            if (toState.id === this.currentState?.id)
-                continue;
-            if (toState.html || toState.ariaSnapshot) {
-                return toState;
-            }
-        }
-        return null;
-    }
-    /**
-     * Load HTML content from file
-     */
-    loadHtmlFromFile(htmlFile) {
-        try {
-            const filePath = outputPath('states', htmlFile);
-            if (existsSync(filePath)) {
-                return readFileSync(filePath, 'utf8');
-            }
-            return null;
-        }
-        catch (error) {
-            debugLog('Failed to load HTML from file:', error);
-            return null;
-        }
-    }
     /**
      * Clear state history (useful for testing or reset)
      * Note: This preserves the current state, only clears navigation history
@@ -405,13 +285,7 @@ export class StateManager {
         this.stateHistory = [];
         this.allVisitedUrls.clear();
         this.stateChangeListeners = [];
-        this.knowledgeCache = [];
-        this.lastKnowledgeScan = null;
         this.nextStateId = 1;
-        // Clean up experience tracker if it has cleanup method
-        if (this.experienceTracker && typeof this.experienceTracker.cleanup === 'function') {
-            this.experienceTracker.cleanup();
-        }
         debugLog('StateManager cleanup completed');
     }
 }

package/dist/src/stats.d.ts

@@ -0,0 +1,24 @@
+interface TokenUsage {
+    input: number;
+    output: number;
+    total: number;
+    cached?: number;
+}
+export type ExplorbotMode = 'explore' | 'test' | 'freesail' | 'tui';
+export declare class Stats {
+    static startTime: number;
+    static sessionName: string;
+    static researches: number;
+    static tests: number;
+    static plans: number;
+    static mode?: ExplorbotMode;
+    static focus?: string;
+    static models: Record<string, TokenUsage>;
+    static recordTokens(_agent: string, model: string, usage: TokenUsage): void;
+    static getElapsedTime(): string;
+    static humanizeTokens(num: number): string;
+    static modelsTable(roleModels: Record<string, string>): string;
+    static hasActivity(): boolean;
+    static sessionLabel(): string;
+}
+export {};

package/dist/src/suite.d.ts

@@ -0,0 +1,24 @@
+export declare class Suite {
+    readonly url: string;
+    _automatedTests: AutomatedTest[] | null;
+    _plannedScenarios: string[] | null;
+    constructor(url: string);
+    getAutomatedTests(): AutomatedTest[];
+    getPlannedScenarios(): string[];
+    getActiveScenarioTitles(): Set<string>;
+    get automatedTestCount(): number;
+    getAutomatedTestNames(): string[];
+    getAutomatedTestFiles(): string[];
+    loadAutomatedTests(): AutomatedTest[];
+    parseTestFile(filePath: string): {
+        url: string;
+        tests: AutomatedTest[];
+    } | null;
+    loadPlannedScenarios(): string[];
+}
+interface AutomatedTest {
+    title: string;
+    pending: boolean;
+    file: string;
+}
+export {};

package/dist/src/test-plan.d.ts

@@ -0,0 +1,166 @@
+import { WebPageState } from './state-manager.js';
+export declare const TestResult: {
+    readonly PASSED: "passed";
+    readonly FAILED: "failed";
+    readonly SKIPPED: "skipped";
+};
+export type TestResultType = (typeof TestResult)[keyof typeof TestResult] | null;
+export declare const TestStatus: {
+    readonly PENDING: "pending";
+    readonly IN_PROGRESS: "in_progress";
+    readonly DONE: "done";
+};
+export type TestStatusType = (typeof TestStatus)[keyof typeof TestStatus];
+export interface Note {
+    message: string;
+    status?: TestResultType;
+    startTime: number;
+    endTime: number;
+    screenshot?: string;
+    log?: string;
+}
+export declare class ActiveNote {
+    task: Task;
+    startTime: number;
+    message: string;
+    status?: TestResultType;
+    screenshot?: string;
+    log?: string;
+    constructor(task: Task, message: string, status?: TestResultType);
+    commit(finalStatus?: TestResultType): void;
+    getMessage(): string;
+    getStartTime(): number;
+}
+export interface StepData {
+    text: string;
+    duration?: number;
+    status?: string;
+    error?: string;
+    log?: string;
+    artifacts?: string[];
+    noteStartTime?: number;
+}
+export declare class Task {
+    id: string;
+    description: string;
+    notes: Record<string, Note>;
+    steps: Record<string, StepData>;
+    states: WebPageState[];
+    startUrl: string;
+    verification?: Verification;
+    timestampCounter: number;
+    activeNote?: ActiveNote;
+    constructor(description: string, startUrl?: string);
+    startNote(message: string, status?: TestResultType): ActiveNote;
+    finishNote(activeNote: ActiveNote, endTime: number, finalStatus?: TestResultType): void;
+    getPrintableNotes(): string[];
+    notesToString(): string;
+    addNote(message: string, status?: TestResultType, screenshot?: string, log?: string): void;
+    addUrlNote(state: UrlNoteState, prevState?: {
+        title?: string;
+        h1?: string;
+        h2?: string;
+    }): void;
+    addState(state: WebPageState): void;
+    addStep(text: string, duration?: number, status?: string, error?: string, log?: string, artifacts?: string[]): void;
+    setActiveNoteScreenshot(screenshotFile?: string): void;
+    setVerification(message: string, status: TestResultType, state?: UrlNoteState): void;
+    addVerificationDetail(detail: string): void;
+    getLog(): Array<{
+        type: 'step' | 'note' | 'artifact';
+        content: string;
+        timestamp: number;
+    }>;
+    getLogString(): string;
+    getRunResult(): 'success' | 'partial' | 'failed';
+}
+export declare class Test extends Task {
+    scenario: string;
+    sessionName?: string;
+    status: TestStatusType;
+    result: TestResultType;
+    priority: 'critical' | 'important' | 'high' | 'normal' | 'low';
+    expected: string[];
+    plannedSteps: string[];
+    plan?: Plan;
+    summary: string;
+    artifacts: Record<string, string>;
+    generatedCode?: string;
+    style?: string;
+    planIteration: number;
+    enabled: boolean;
+    startTime?: number;
+    endTime?: number;
+    resetCount: number;
+    constructor(scenario: string, priority: 'critical' | 'important' | 'high' | 'normal' | 'low', expectedOutcome: string | string[], startUrl: string, plannedSteps?: string[]);
+    getVisitedUrls({ localOnly }?: {
+        localOnly?: boolean;
+    }): string[];
+    addArtifact(artifact?: string): void;
+    get hasFinished(): boolean;
+    get isSuccessful(): boolean;
+    get hasFailed(): boolean;
+    get isSkipped(): boolean;
+    getCheckedNotes(): Note[];
+    getCheckedExpectations(): string[];
+    hasAchievedAny(): boolean;
+    getRunResult(): 'success' | 'partial' | 'failed';
+    hasAchievedAll(): boolean;
+    isComplete(): boolean;
+    start(): void;
+    finish(result?: TestResultType): void;
+    getDurationMs(): number | null;
+    getRemainingExpectations(): string[];
+    getLog(): Array<{
+        type: 'step' | 'note' | 'artifact';
+        content: string;
+        timestamp: number;
+    }>;
+}
+type PlanChangeListener = (tests: Test[]) => void;
+export declare class Plan {
+    title: string;
+    tests: Test[];
+    url?: string;
+    iteration: number;
+    parentPlan?: Plan;
+    changeListeners: PlanChangeListener[];
+    constructor(title: string);
+    nextIteration(): void;
+    addTest(test: Test): void;
+    removeTest(test: Test): void;
+    onTestsChange(listener: PlanChangeListener): () => void;
+    notifyChange(): void;
+    getAllTests(): Test[];
+    listTests(): Test[];
+    getPendingTests(): Test[];
+    get isComplete(): boolean;
+    get allSuccessful(): boolean;
+    get allFailed(): boolean;
+    updateStatus(): void;
+    static fromMarkdown(filePath: string): Plan;
+    saveToMarkdown(filePath: string): void;
+    static saveMultipleToMarkdown(plans: Plan[], filePath: string): void;
+    getVisitedPages(): WebPageState[];
+    merge(otherPlan: Plan): Plan;
+    toAiContext(options?: {
+        skipSteps?: boolean;
+    }): string;
+}
+interface Verification {
+    message: string;
+    status: TestResultType;
+    screenshot?: string;
+    url?: string;
+    pageLabel?: string;
+    details: string[];
+}
+interface UrlNoteState {
+    url?: string;
+    fullUrl?: string;
+    title?: string;
+    h1?: string;
+    h2?: string;
+    screenshotFile?: string;
+}
+export {};