explorbot 0.1.31 → 0.2.0

package/dist/src/utils/markdown-query.d.ts

@@ -0,0 +1,46 @@
+import { type Token } from 'marked';
+export type SelectorType = 'section' | 'section1' | 'section2' | 'section3' | 'section4' | 'section5' | 'section6' | 'table' | 'heading' | 'paragraph' | 'list' | 'item' | 'code' | 'blockquote' | 'hr' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+export interface TextMatcher {
+    mode: 'exact' | 'contains' | 'regex';
+    value: string;
+    negated: boolean;
+}
+export interface QuerySegment {
+    selector: SelectorType;
+    textMatch?: TextMatcher;
+    index: number | null;
+    slice: {
+        from?: number;
+        to?: number;
+    } | null;
+}
+export interface MatchedRange {
+    token: Token;
+    start: number;
+    length: number;
+    innerTokens?: MatchedRange[];
+}
+export declare function parseQuery(input: string): QuerySegment[];
+export declare class MarkdownQuery {
+    source: string;
+    matches: MatchedRange[];
+    constructor(source: string, matches?: MatchedRange[]);
+    query(selector: string): MarkdownQuery;
+    text(): string;
+    get(): string;
+    toJson(): Record<string, string>[];
+    replace(content: string): string;
+    replaceEach(replacer: (match: MarkdownQuery, index: number) => string): string;
+    count(): number;
+    first(): MarkdownQuery;
+    last(): MarkdownQuery;
+    before(): MarkdownQuery;
+    after(): MarkdownQuery;
+    each(): MarkdownQuery[];
+    meta(): Array<{
+        type: string;
+        depth: number | null;
+        text: string;
+    }>;
+}
+export declare function mdq(source: string): MarkdownQuery;

package/dist/src/utils/markdown-query.js

@@ -341,6 +341,9 @@ export class MarkdownQuery {
         return results;
     }
     replace(content) {
+        return this.replaceEach(() => content);
+    }
+    replaceEach(replacer) {
         const sorted = [...this.matches].sort((a, b) => a.start - b.start);
         const kept = [];
         let lastEnd = -1;
@@ -350,10 +353,11 @@ export class MarkdownQuery {
             kept.push(range);
             lastEnd = range.start + range.length;
         }
+        const replacements = kept.map((range, index) => replacer(new MarkdownQuery(this.source, [range]), index));
         let result = this.source;
         for (let i = kept.length - 1; i >= 0; i--) {
             const range = kept[i];
-            result = result.slice(0, range.start) + content + result.slice(range.start + range.length);
+            result = result.slice(0, range.start) + replacements[i] + result.slice(range.start + range.length);
         }
         return result;
     }
@@ -386,6 +390,15 @@ export class MarkdownQuery {
     each() {
         return this.matches.map((m) => new MarkdownQuery(this.source, [m]));
     }
+    meta() {
+        return this.matches.map((range) => {
+            const token = range.token;
+            let depth = null;
+            if (token.type === 'heading')
+                depth = token.depth;
+            return { type: token.type, depth, text: getTokenText(range.token) };
+        });
+    }
 }
 export function mdq(source) {
     return new MarkdownQuery(source);

package/dist/src/utils/markdown-terminal.d.ts

@@ -0,0 +1 @@
+export declare function parseMarkdownToTerminal(markdown: string): string;

package/dist/src/utils/next-steps.d.ts

@@ -0,0 +1,11 @@
+export interface NextStepCommand {
+    label: string;
+    command: string;
+}
+export interface NextStepSection {
+    label: string;
+    path?: string;
+    commands?: NextStepCommand[];
+}
+export declare function relativeToCwd(absPath: string): string;
+export declare function printNextSteps(sections: NextStepSection[]): void;

package/dist/src/utils/page-readiness.d.ts

@@ -0,0 +1,7 @@
+export declare function waitForPageReadiness(page: any, options?: PageReadinessOptions): Promise<void>;
+export declare function sleep(ms: number): Promise<void>;
+interface PageReadinessOptions {
+    timeout?: number;
+    spinnerSelectors?: string[];
+}
+export {};

package/dist/src/utils/page-readiness.js

@@ -43,6 +43,6 @@ function waitForPageBodyContent(page, timeout) {
     }, undefined, { timeout })
         .catch(() => { });
 }
-function sleep(ms) {
+export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/src/utils/research-parser.d.ts

@@ -0,0 +1 @@
+export { RESEARCH_COLUMN_ORDER, type ResearchElement, type ResearchSection, extractContainerFromBlockquote, extractValidContainers, formatResearchSummary, mapRowToElement, parseResearchSections, rebuildSectionMarkdown, } from '../ai/researcher/parser.js';

package/dist/src/utils/retry.d.ts

@@ -0,0 +1,8 @@
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+    retryCondition?: (error: Error) => boolean;
+}
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/src/utils/rules-loader.d.ts

@@ -0,0 +1,12 @@
+export declare class RulesLoader {
+    static loadRules(agentName: string, rulesConfig: RuleEntry[], currentUrl: string): string;
+    static loadStyles(agentName: string, styleNames: string[]): Record<string, string>;
+    static listStyleNames(agentName: string): string[];
+    static getActiveStyle(styles: Record<string, string>, iteration: number, override?: string): {
+        name: string;
+        approach: string;
+    };
+    static extractRules(agentName: string, targetDir: string): string[];
+}
+type RuleEntry = string | Record<string, string>;
+export type { RuleEntry };

package/dist/src/utils/secrets.d.ts

@@ -0,0 +1,4 @@
+export declare function registerSecret(value: string): void;
+export declare function redactSecrets(text: string): string;
+export declare function clearRegisteredSecrets(): void;
+export declare function isSecretName(name: string): boolean;

package/dist/src/utils/secrets.js

@@ -0,0 +1,28 @@
+const MIN_SECRET_LENGTH = 4;
+const SECRET_NAME_TOKENS = ['password', 'passwd', 'secret', 'token', 'apikey', 'api_key', 'credential', 'private_key', 'privatekey', 'access_key', 'jwt', 'auth', 'bearer', 'authorization', 'cert', 'certificate'];
+const secretValues = new Set();
+export function registerSecret(value) {
+    if (!value)
+        return;
+    if (value.length < MIN_SECRET_LENGTH)
+        return;
+    secretValues.add(value);
+}
+export function redactSecrets(text) {
+    if (!text)
+        return text;
+    let result = text;
+    for (const value of [...secretValues].sort((a, b) => b.length - a.length)) {
+        if (!result.includes(value))
+            continue;
+        result = result.split(value).join('***REDACTED***');
+    }
+    return result;
+}
+export function clearRegisteredSecrets() {
+    secretValues.clear();
+}
+export function isSecretName(name) {
+    const lower = name.toLowerCase();
+    return SECRET_NAME_TOKENS.some((token) => lower.includes(token));
+}

package/dist/src/utils/step-analyzer.d.ts

@@ -0,0 +1,11 @@
+import type { SessionStep } from '../experience-tracker.js';
+import type { StepData } from '../test-plan.js';
+export declare const CODECEPT_TOOLS: readonly ["click", "hover", "pressKey", "form"];
+export type CodeceptToolName = (typeof CODECEPT_TOOLS)[number];
+export declare function isCodeceptToolName(toolName: string): toolName is CodeceptToolName;
+export declare function getCodeceptToolName(commandName: string): CodeceptToolName | null;
+export declare function getCodeceptToolNameFromCode(code: string): CodeceptToolName | null;
+export declare function stripComments(code: string): string;
+export declare function isNonReusableCode(code: string): boolean;
+export declare function toReusableSessionStep(step: StepData): SessionStep | null;
+export declare function mergeUniqueStepsByCode(primary: SessionStep[], secondary: SessionStep[]): SessionStep[];

package/dist/src/utils/strings.d.ts

@@ -0,0 +1,5 @@
+export declare function truncateJson(input: any): string;
+export declare function slugify(text: string): string;
+export declare function normalizeInlineText(text: string): string;
+export declare function sanitizeFilename(name: string): string;
+export declare function safeFilename(name: string, ext?: string, maxBytes?: number): string;

package/dist/src/utils/strings.js

@@ -5,6 +5,16 @@ export function truncateJson(input) {
     const str = JSON.stringify(input);
     return str.length <= 80 ? str : `${str.slice(0, 77)}...`;
 }
+export function slugify(text) {
+    return text
+        .replace(/[^a-zA-Z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '')
+        .toLowerCase();
+}
+export function normalizeInlineText(text) {
+    return text.normalize('NFKC').replace(/\s+/g, ' ').trim();
+}
 export function sanitizeFilename(name) {
     return name
         .toLowerCase()

package/dist/src/utils/test-files.d.ts

@@ -0,0 +1,3 @@
+export declare function loadTestSuites(testsDir: string): any[];
+export declare function printTestList(suites: any[]): void;
+export declare function dryRunTestFile(filePath: string): Promise<void>;

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

@@ -0,0 +1,9 @@
+import { Plan } from '../test-plan.js';
+export declare function planToCompactAiContext(plan: Plan): string;
+export declare function parsePlanFromMarkdown(filePath: string): Plan;
+export declare function parsePlansFromMarkdown(filePath: string): Plan[];
+export declare function savePlanToMarkdown(plan: Plan, filePath: string): void;
+export declare function savePlansToMarkdown(plans: Plan[], filePath: string): void;
+export declare function planToAiContext(plan: Plan, options?: {
+    skipSteps?: boolean;
+}): string;

package/dist/src/utils/throttle.d.ts

@@ -0,0 +1,2 @@
+export declare function throttle<T>(fn: () => Promise<T> | T, intervalSeconds?: number): Promise<T | undefined>;
+export declare function __clearThrottleCacheForTests(): void;

package/dist/src/utils/unique-names.d.ts

@@ -0,0 +1,2 @@
+export declare function uniqSessionName(): string;
+export declare function uniqExplorationName(): string;

package/dist/src/utils/url-matcher.d.ts

@@ -0,0 +1,6 @@
+export declare function isDynamicSegment(segment: string): boolean;
+export declare function hasDynamicUrlSegment(url: string): boolean;
+export declare function generalizeSegment(segment: string): string;
+export declare function generalizeUrl(url: string): string;
+export declare function matchesUrl(pattern: string, path: string): boolean;
+export declare function extractStatePath(url: string): string;

package/dist/src/utils/web-element.d.ts

@@ -0,0 +1,45 @@
+import { EXPLORBOT_ATTRS, type RawElementData } from './html.js';
+import { type XPathMatch } from './xpath.js';
+export { extractElementData } from './html.js';
+export declare class WebElement {
+    tag: string;
+    role: string;
+    xpath: string;
+    clickXPath: string;
+    attrs: Record<string, string>;
+    text: string;
+    outerHTML: string;
+    x: number;
+    y: number;
+    constructor(data: {
+        tag: string;
+        role?: string;
+        xpath: string;
+        clickXPath: string;
+        attrs: Record<string, string>;
+        text: string;
+        outerHTML?: string;
+        x: number;
+        y: number;
+    });
+    get description(): string;
+    get keyAttrs(): string;
+    get coordinates(): string;
+    get eidx(): string | null;
+    ourAttr(name: keyof typeof EXPLORBOT_ATTRS): string | undefined;
+    get isNavigationLink(): boolean;
+    get filteredClasses(): string[];
+    get areaHints(): string[];
+    get contextLabel(): string;
+    get variantHints(): string[];
+    static fromRawData(d: RawElementData, role?: string): WebElement;
+    static fromXPathMatch(m: XPathMatch): WebElement;
+    static fromPlaywrightLocator(locator: any): Promise<WebElement | null>;
+    static fromEidx(page: any, eidx: string): Promise<WebElement | null>;
+    static fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]>;
+    static findByXPath(html: string, xpath: string): Promise<{
+        totalFound: number;
+        elements: WebElement[];
+        error?: string;
+    }>;
+}

package/dist/src/utils/web-element.js

@@ -39,6 +39,9 @@ export class WebElement {
     get eidx() {
         return this.attrs[EXPLORBOT_ATTRS.eidx] || this.attrs.eidx || null;
     }
+    ourAttr(name) {
+        return this.attrs[EXPLORBOT_ATTRS[name]];
+    }
     get isNavigationLink() {
         if (this.tag !== 'a')
             return false;

package/dist/src/utils/web-sandbox.d.ts

@@ -0,0 +1,4 @@
+export declare function sanitizeCodeBlock(code: string): string;
+export declare function hasPlaywrightCommands(code: string): boolean;
+export declare function playwrightSandbox(page: any, code: string): Promise<any>;
+export declare function codeceptJSSandbox(actor: any, codeOrFn: string | ((...args: any[]) => void)): void;

package/dist/src/utils/web-sandbox.js

@@ -0,0 +1,37 @@
+import { faker } from '@faker-js/faker';
+import { hopeThat, retryTo, tryTo, within } from 'codeceptjs/lib/effects';
+import step from 'codeceptjs/steps';
+const SHADOWED_GLOBALS = ['process', 'global', 'globalThis', 'fetch', 'Bun', 'require', 'module', 'exports'];
+const ALLOWED_COMMAND_HEADS = ['I.', 'page.', 'await page.', 'await I.'];
+const PLAYWRIGHT_COMMAND_HEADS = ['page.', 'await page.'];
+const PLAYWRIGHT_ARG_NAMES = ['page'];
+const CODECEPT_ARG_NAMES = ['I', 'tryTo', 'retryTo', 'within', 'hopeThat', 'step', 'faker'];
+export function sanitizeCodeBlock(code) {
+    return code
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => ALLOWED_COMMAND_HEADS.some((head) => line.startsWith(head)))
+        .join('\n');
+}
+export function hasPlaywrightCommands(code) {
+    return code.split('\n').some((line) => {
+        const trimmed = line.trim();
+        return PLAYWRIGHT_COMMAND_HEADS.some((head) => trimmed.startsWith(head));
+    });
+}
+export function playwrightSandbox(page, code) {
+    const run = createSandbox(PLAYWRIGHT_ARG_NAMES, `return (async () => { ${code} })()`);
+    return run(page);
+}
+export function codeceptJSSandbox(actor, codeOrFn) {
+    if (typeof codeOrFn === 'function') {
+        codeOrFn(actor, tryTo, retryTo, within, hopeThat, step, faker);
+        return;
+    }
+    const run = createSandbox(CODECEPT_ARG_NAMES, codeOrFn);
+    run(actor, tryTo, retryTo, within, hopeThat, step, faker);
+}
+function createSandbox(argNames, body) {
+    const fn = new Function(...argNames, ...SHADOWED_GLOBALS, `'use strict';\n${body}`);
+    return (...args) => fn(...args);
+}

package/dist/src/utils/xpath.d.ts

@@ -0,0 +1,17 @@
+export interface XPathMatch {
+    tag: string;
+    outerHTML: string;
+    text: string;
+    absoluteXPath: string;
+    allAttrs: Record<string, string>;
+}
+export interface XPathResult {
+    totalFound: number;
+    matches: XPathMatch[];
+    error?: string;
+}
+export declare const isDynamicId: (id: string) => boolean;
+export declare const isGenericClass: (cls: string) => boolean;
+export declare function buildClickableXPath(el: XPathMatch): string;
+export declare function cssToAncestorXPath(css: string): string | null;
+export declare function evaluateXPath(html: string, xpath: string): Promise<XPathResult>;

package/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",