explorbot 0.2.2 → 0.2.3

package/dist/src/commands/clean-command.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { ConfigParser, outputPath } from '../config.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
@@ -13,12 +13,7 @@ export const CLEAN_TARGETS = {
 };
 function getExperienceDir() {
     const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
-    const configPath = configParser.getConfigPath();
-    if (configPath) {
-        return join(dirname(configPath), config.dirs?.experience || 'experience');
-    }
-    return config.dirs?.experience || 'experience';
+    return configParser.resolveProjectDir(configParser.getConfig().dirs?.experience || 'experience');
 }
 function cleanDirectoryContents(dirPath) {
     if (!existsSync(dirPath))

package/dist/src/commands/init-command.d.ts

@@ -1,7 +1,12 @@
+export declare function runInit(options: InitCommandOptions): Promise<void>;
+export declare function writeGlobalConfig(provider: string, apiKey?: string): void;
 export declare function runInitCommand(options: InitCommandOptions): void;
 type InitCommandOptions = {
     configPath?: string;
     force?: boolean;
     path?: string;
+    global?: boolean;
+    provider?: string;
+    apiKey?: string;
 };
 export {};

package/dist/src/commands/init-command.js

@@ -1,7 +1,9 @@
-import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
 import dedent from 'dedent';
+import { ConfigParser, PROVIDERS } from "../config.js";
+import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from "../global-config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { log, tag } from '../utils/logger.js';
 import { relativeToCwd } from "../utils/next-steps.js";
@@ -58,6 +60,41 @@ LANGFUSE_BASE_URL=
 # Testomat.io API key to publish run results
 TESTOMATIO=
 `;
+export async function runInit(options) {
+    if (options.global || options.provider) {
+        await runGlobalInit(options);
+        return;
+    }
+    if (options.configPath || options.path || !process.stdin.isTTY) {
+        runInitCommand(options);
+        return;
+    }
+    const choice = await renderInitWizard('choose');
+    if (choice === 'local')
+        runInitCommand(options);
+}
+export function writeGlobalConfig(provider, apiKey) {
+    if (!PROVIDERS[provider]) {
+        throw new Error(`Unknown AI provider "${provider}". Supported providers: ${Object.keys(PROVIDERS).join(', ')}`);
+    }
+    mkdirSync(globalDir(), { recursive: true });
+    writeFileSync(globalConfigPath(), globalConfigTemplate(provider), 'utf8');
+    log(`Created global config: ${globalConfigPath()}`);
+    const envKey = PROVIDERS[provider].envKey;
+    writeEnvKey(envKey, apiKey || '');
+    log(`Stored ${envKey} in ${globalEnvPath()}`);
+    const missing = missingRoles(provider);
+    if (missing.length) {
+        tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${globalConfigPath()}`);
+    }
+    if (!apiKey && !process.env[envKey]) {
+        tag('warning').log(`Add your API key to ${globalEnvPath()}`);
+    }
+    log('');
+    log('Explorbot now runs from any directory:');
+    tag('substep').log(chalk.yellow(`${getCliName()} explore https://your-app.example.com`));
+    tag('substep').log(chalk.yellow(`${getCliName()} sites`));
+}
 export function runInitCommand(options) {
     const configPath = options.configPath ?? './explorbot.config.js';
     const force = options.force ?? false;
@@ -125,3 +162,84 @@ export function runInitCommand(options) {
         }
     }
 }
+async function runGlobalInit(options) {
+    const existing = findGlobalConfig();
+    if (existing && !options.force) {
+        log(`Global config already exists: ${existing}`);
+        log('Use --force to overwrite existing file');
+        process.exit(1);
+    }
+    if (options.provider) {
+        writeGlobalConfig(options.provider, options.apiKey);
+        return;
+    }
+    if (!process.stdin.isTTY) {
+        log('Cannot run the setup wizard outside an interactive terminal');
+        log(`Pass a provider instead: ${getCliName()} init --global --provider ${Object.keys(PROVIDERS)[0]}`);
+        process.exit(1);
+    }
+    await renderInitWizard('global');
+}
+async function renderInitWizard(mode) {
+    const [{ render }, React, InitWizard] = await Promise.all([import('ink'), import('react'), import('../components/InitWizard.js').then((m) => m.default)]);
+    return new Promise((resolve) => {
+        const finish = (choice) => {
+            unmount();
+            resolve(choice);
+        };
+        const { unmount } = render(React.createElement(InitWizard, {
+            mode,
+            globalConfigExists: !!findGlobalConfig(),
+            onLocal: () => finish('local'),
+            onComplete: () => finish('global'),
+            onCancel: () => finish(null),
+        }), { exitOnCtrlC: false, patchConsole: false });
+    });
+}
+function globalConfigTemplate(provider) {
+    const { envKey } = PROVIDERS[provider];
+    const recommended = ConfigParser.recommendedModels()[provider] || {};
+    const roles = [
+        ['model', 'fast model with tool calling capabilities'],
+        ['visionModel', 'vision model for screenshot analysis'],
+        ['agenticModel', 'agentic model for decision making'],
+    ];
+    const models = roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+    return `// Global Explorbot configuration — used by every directory without its own explorbot.config.js.
+// Models are written as 'provider/model-id' so they resolve without a local node_modules.
+// The key is read from ${envKey} in ~/.explorbot/.env
+// Model ids are snapshotted from the recommendations of this Explorbot version.
+// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
+const config = {
+  ai: {
+${models}
+  },
+
+  reporter: {
+    // Save a local HTML report after each run.
+    html: true,
+    // Save a local markdown report after each run.
+    markdown: true,
+  },
+};
+
+export default config;
+`;
+}
+function missingRoles(provider) {
+    const recommended = ConfigParser.recommendedModels()[provider] || {};
+    return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);
+}
+function writeEnvKey(key, value) {
+    const envPath = globalEnvPath();
+    let content = '# AI provider API keys';
+    if (existsSync(envPath))
+        content = readFileSync(envPath, 'utf8').trimEnd();
+    const lines = content.split('\n');
+    const index = lines.findIndex((line) => line.startsWith(`${key}=`));
+    if (index < 0)
+        lines.push(`${key}=${value}`);
+    if (index >= 0 && value)
+        lines[index] = `${key}=${value}`;
+    writeFileSync(envPath, `${lines.join('\n').trimEnd()}\n`, 'utf8');
+}

package/dist/src/commands/navigate-command.js

@@ -12,7 +12,7 @@ export class NavigateCommand extends BaseCommand {
         if (!destination) {
             throw new Error('Navigate command requires a target URI or state');
         }
-        await this.explorBot.agentNavigator().visit(destination);
+        await this.explorBot.visit(destination);
         tag('success').log(`Navigation requested: ${destination}`);
     }
 }

package/dist/src/commands/research-command.js

@@ -21,7 +21,7 @@ export class ResearchCommand extends BaseCommand {
         const noFix = !!opts.noFix;
         const target = remaining.join(' ');
         if (target) {
-            await this.explorBot.agentNavigator().visit(target);
+            await this.explorBot.visit(target);
         }
         const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {

package/dist/src/commands/sites-command.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from './base-command.js';
+export declare class SitesCommand extends BaseCommand {
+    name: string;
+    description: string;
+    execute(): Promise<void>;
+}

package/dist/src/commands/sites-command.js

@@ -0,0 +1,23 @@
+import { listSites, sitesDir } from '../global-config.js';
+import { getCliName } from '../utils/cli-name.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+export class SitesCommand extends BaseCommand {
+    name = 'sites';
+    description = 'List sites registered in the global installation';
+    async execute() {
+        const sites = listSites();
+        if (sites.length === 0) {
+            tag('info').log(`No sites registered in ${sitesDir()}`);
+            tag('info').log(`Explore one to register it: ${getCliName()} explore https://app.example.com`);
+            return;
+        }
+        const width = sites.reduce((max, site) => Math.max(max, site.folder.length), 0);
+        tag('info').log(`Registered sites (${sites.length}):`);
+        for (const site of sites) {
+            tag('info').log(`  ${site.folder.padEnd(width)}  ${site.url}  last run ${site.lastRunAt.slice(0, 16).replace('T', ' ')}`);
+        }
+        tag('info').log('');
+        tag('info').log(`Stored in ${sitesDir()}`);
+    }
+}

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

@@ -0,0 +1,10 @@
+import React from 'react';
+interface InitWizardProps {
+    mode: 'choose' | 'global';
+    globalConfigExists: boolean;
+    onLocal: () => void;
+    onComplete: () => void;
+    onCancel: () => void;
+}
+declare const InitWizard: React.FC<InitWizardProps>;
+export default InitWizard;

package/dist/src/components/InitWizard.js

@@ -0,0 +1,133 @@
+import figureSet from 'figures';
+import { Box, Text, useInput } from 'ink';
+import React, { useState } from 'react';
+import { AIProvider } from '../ai/provider.js';
+import { writeGlobalConfig } from '../commands/init-command.js';
+import { ConfigParser, PROVIDERS, createModel } from '../config.js';
+import { globalDir } from '../global-config.js';
+import InputReadline from './InputReadline.js';
+const PROVIDER_NAMES = Object.keys(PROVIDERS);
+const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel }) => {
+    const [step, setStep] = useState(mode === 'choose' ? 'target' : 'provider');
+    const [targetIndex, setTargetIndex] = useState(0);
+    const [providerIndex, setProviderIndex] = useState(0);
+    const [apiKey, setApiKey] = useState('');
+    const [status, setStatus] = useState('');
+    const [error, setError] = useState('');
+    const provider = PROVIDER_NAMES[providerIndex];
+    const envKey = PROVIDERS[provider].envKey;
+    const save = () => {
+        writeGlobalConfig(provider, apiKey.trim());
+        onComplete();
+    };
+    const validate = async () => {
+        const modelId = defaultModelId(provider);
+        if (!modelId) {
+            save();
+            return;
+        }
+        setStatus(`Sending a test request to ${provider}...`);
+        setError('');
+        if (apiKey.trim())
+            process.env[envKey] = apiKey.trim();
+        try {
+            const model = await createModel(provider, modelId);
+            await new AIProvider({ model }).validateConnection();
+            save();
+        }
+        catch (err) {
+            setStatus('');
+            setError(err instanceof Error ? err.message : String(err));
+        }
+    };
+    useInput((input, key) => {
+        if (key.ctrl && input === 'c') {
+            onCancel();
+            return;
+        }
+        if (step === 'key')
+            return;
+        if (key.escape) {
+            onCancel();
+            return;
+        }
+        if (step === 'target') {
+            if (key.upArrow)
+                setTargetIndex(0);
+            if (key.downArrow && !globalConfigExists)
+                setTargetIndex(1);
+            if (key.return && targetIndex === 0)
+                onLocal();
+            if (key.return && targetIndex === 1)
+                setStep('provider');
+            return;
+        }
+        if (step === 'provider') {
+            if (key.upArrow)
+                setProviderIndex((index) => Math.max(0, index - 1));
+            if (key.downArrow)
+                setProviderIndex((index) => Math.min(PROVIDER_NAMES.length - 1, index + 1));
+            if (key.return)
+                setStep('key');
+            return;
+        }
+        if (status)
+            return;
+        if (input.toLowerCase() === 'y')
+            void validate();
+        if (input.toLowerCase() === 'n')
+            save();
+        if (input.toLowerCase() === 'r') {
+            setError('');
+            setStep('key');
+        }
+    });
+    return (React.createElement(Box, { flexDirection: "column", padding: 1 },
+        React.createElement(Box, { marginBottom: 1 },
+            React.createElement(Text, { color: "cyan", bold: true }, "Explorbot setup")),
+        step === 'target' && (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(Text, null, "Where should explorbot be initialized?"),
+            React.createElement(Text, { color: targetIndex === 0 ? 'blue' : undefined },
+                targetIndex === 0 ? `${figureSet.pointer} ` : '  ',
+                "Local ",
+                React.createElement(Text, { dimColor: true }, "\u2014 creates the config file in the current directory")),
+            React.createElement(Text, { color: targetIndex === 1 ? 'blue' : undefined, dimColor: globalConfigExists },
+                targetIndex === 1 ? `${figureSet.pointer} ` : '  ',
+                "Global ",
+                React.createElement(Text, { dimColor: true }, "\u2014 initializes explorbot to run from anywhere on this machine"),
+                globalConfigExists && React.createElement(Text, { dimColor: true }, " (already installed)")))),
+        step === 'provider' && (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(Text, null, "Pick an AI provider:"),
+            PROVIDER_NAMES.map((name, index) => (React.createElement(Text, { key: name, color: index === providerIndex ? 'blue' : undefined },
+                index === providerIndex ? `${figureSet.pointer} ` : '  ',
+                name))))),
+        step === 'key' && (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(Text, null,
+                "Enter the API key for ",
+                provider,
+                " ",
+                React.createElement(Text, { dimColor: true },
+                    "(stored as ",
+                    envKey,
+                    ")")),
+            React.createElement(Box, { borderStyle: "single", borderColor: "blue", paddingX: 1 },
+                React.createElement(InputReadline, { value: apiKey, onChange: setApiKey, onSubmit: () => setStep('validate'), placeholder: process.env[envKey] ? 'leave empty to keep the key from your environment' : 'paste the key', isActive: true, showPrompt: false, mask: true })))),
+        step === 'validate' && (React.createElement(Box, { flexDirection: "column" },
+            !status && !error && React.createElement(Text, null, "Check the key with a test AI call? (y/n)"),
+            status && React.createElement(Text, { color: "yellow" }, status),
+            error && (React.createElement(Box, { flexDirection: "column" },
+                React.createElement(Text, { color: "red" }, error),
+                React.createElement(Text, { dimColor: true }, "r: re-enter the key | n: save anyway"))))),
+        React.createElement(Box, { marginTop: 1 },
+            React.createElement(Text, { dimColor: true },
+                "Config goes to ",
+                globalDir(),
+                " | ",
+                step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm',
+                " | Ctrl+C: exit"))));
+};
+function defaultModelId(provider) {
+    const recommended = ConfigParser.recommendedModels()[provider] || {};
+    return recommended.model || recommended.agenticModel || recommended.visionModel || '';
+}
+export default InitWizard;

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

@@ -12,6 +12,7 @@ interface InputReadlineProps {
     value?: string;
     placeholder?: string;
     showPrompt?: boolean;
+    mask?: boolean;
 }
 declare const InputReadline: React.FC<InputReadlineProps>;
 export default InputReadline;

package/dist/src/components/InputReadline.js

@@ -3,7 +3,7 @@ import React from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { setAutocompleteState } from './autocomplete-store.js';
 import parseKeypress, { nonAlphanumericKeys } from './parse-keypress.js';
-const InputReadline = React.memo(({ commandHandler, exitOnEmptyInput = false, onSubmit, onChange, onCommandStart, onCommandComplete, isActive = true, visible = true, value: controlledValue, placeholder = '', showPrompt = true }) => {
+const InputReadline = React.memo(({ commandHandler, exitOnEmptyInput = false, onSubmit, onChange, onCommandStart, onCommandComplete, isActive = true, visible = true, value: controlledValue, placeholder = '', showPrompt = true, mask = false }) => {
     const isControlled = controlledValue !== undefined;
     const [inputState, setInputState] = useState({
         value: controlledValue || '',
@@ -537,11 +537,14 @@ const InputReadline = React.memo(({ commandHandler, exitOnEmptyInput = false, on
             commandHandler.setExitOnEmptyInput(exitOnEmptyInput);
         }
     }, [commandHandler, exitOnEmptyInput]);
-    const beforeCursor = displayValue.slice(0, cursorPosition);
-    const afterCursor = displayValue.slice(cursorPosition);
+    let renderedValue = displayValue;
+    if (mask)
+        renderedValue = '•'.repeat(displayValue.length);
+    const beforeCursor = renderedValue.slice(0, cursorPosition);
+    const afterCursor = renderedValue.slice(cursorPosition);
     const beforeLines = beforeCursor.split('\n');
     const afterLines = afterCursor.split('\n');
-    const lines = displayValue.split('\n');
+    const lines = renderedValue.split('\n');
     const cursorLineIndex = beforeLines.length - 1;
     const cursorLineBefore = beforeLines[cursorLineIndex] || '';
     const cursorLineAfter = afterLines[0] || '';

package/dist/src/config.d.ts

@@ -1,4 +1,5 @@
-export declare const PROVIDERS: Record<string, () => Promise<(modelId: string) => any>>;
+import { type SiteRecord } from './global-config.js';
+export declare const PROVIDERS: Record<string, ProviderInfo>;
 interface PlaywrightConfig {
     browser: 'chromium' | 'firefox' | 'webkit';
     url: string;
@@ -202,6 +203,7 @@ interface ExplorbotConfig {
         knowledge: string;
         experience: string;
         output: string;
+        spec?: string;
     };
     experience?: {
         maxReadLines?: number;
@@ -222,21 +224,27 @@ export declare class ConfigParser {
     static recommended: Record<string, Record<string, string>> | null;
     config: ExplorbotConfig | null;
     configPath: string | null;
-    runtimeBaseUrlOverride: string | null;
+    runtimeTarget: string | null;
+    site: SiteRecord | null;
+    siteStartPath: string;
     constructor();
-    static loadEnv(filePath: string): void;
+    static loadEnv(filePath: string, keepExisting?: boolean): void;
     static recommendedModels(): Record<string, Record<string, string>>;
     static getInstance(): ConfigParser;
     loadConfig(options?: {
         config?: string;
         path?: string;
         baseUrl?: string;
+        from?: string;
     }): Promise<ExplorbotConfig>;
     getConfig(): ExplorbotConfig;
     getConfigPath(): string | null;
     getOutputDir(): string;
     getProjectRoot(): string;
     resolveProjectDir(relativeDir: string): string;
+    isGlobalMode(): boolean;
+    getSite(): SiteRecord | null;
+    resolveTargetPath(target?: string): string;
     getStatesDir(): string;
     getPlansDir(): string;
     getTestsDir(): string;
@@ -244,6 +252,7 @@ export declare class ConfigParser {
     static setupTestConfig(): void;
     static getTestDirectories(): string[];
     static cleanupAllTestDirectories(): void;
+    enterGlobalMode(config: ExplorbotConfig, target: string | null): void;
     buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
     loadConfigModule(configPath: string): Promise<any>;
@@ -258,13 +267,23 @@ export declare class ConfigParser {
 }
 export declare function outputPath(...segments: string[]): string;
 export declare function resolveModel(spec: string, role?: ModelRole): Promise<any>;
-export declare function resolveOutputRoot(): string;
+export declare class ConfigMissingError extends Error {
+}
+export declare function envConfigRequested(): boolean;
+export declare function missingConfigMessage(configFile?: string): string;
+export declare function resolveConfigModels(ai?: AIConfig): Promise<void>;
+export declare function resolveOutputRoot(baseUrl?: string): string;
+export declare function resolveStateRoot(baseUrl: string, ephemeral?: boolean): string;
 export declare function materializeKnowledge(outputRoot: string): void;
 export declare function createModel(provider: string, modelId: string): Promise<any>;
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
+interface ProviderInfo {
+    envKey: string;
+    load: () => Promise<(modelId: string) => any>;
+}
 interface EnvVar {
     name: string;
     description: string;
     required?: boolean;
 }
-export type { ModelRole, EnvVar };
+export type { ModelRole, EnvVar, ProviderInfo };