explorbot 0.2.1 → 0.2.3

package/src/browser-server.ts

@@ -1,27 +1,33 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { chromium, firefox, webkit } from 'playwright-core';
+import { chromium, firefox, webkit } from 'playwright';
 import { ConfigParser } from './config.js';
 import { getCliName } from './utils/cli-name.ts';
 import { log } from './utils/logger.js';
 import { type NextStepSection, printNextSteps } from './utils/next-steps.ts';
 
 const ENDPOINT_FILENAME = '.browser-endpoint';
+const INSTANCE_NAME_PATTERN = /^[a-z0-9-]+$/;
+const KEEP_ALIVE_INTERVAL = 1 << 30;
 
-function getEndpointFilePath(): string {
+function getEndpointFilePath(instance = 'default'): string {
+  if (!INSTANCE_NAME_PATTERN.test(instance)) {
+    throw new Error(`Invalid browser instance name: "${instance}". Use lowercase letters, digits and dashes.`);
+  }
   const configParser = ConfigParser.getInstance();
   const outputDir = configParser.getOutputDir();
-  return path.join(outputDir, ENDPOINT_FILENAME);
+  if (instance === 'default') return path.join(outputDir, ENDPOINT_FILENAME);
+  return path.join(outputDir, `${ENDPOINT_FILENAME}-${instance}`);
 }
 
-function readEndpoint(): string | null {
-  const filePath = getEndpointFilePath();
+function readEndpoint(instance = 'default'): string | null {
+  const filePath = getEndpointFilePath(instance);
   if (!existsSync(filePath)) return null;
   return readFileSync(filePath, 'utf8').trim();
 }
 
-function writeEndpoint(wsEndpoint: string): void {
-  const filePath = getEndpointFilePath();
+function writeEndpoint(wsEndpoint: string, instance = 'default'): void {
+  const filePath = getEndpointFilePath(instance);
   const dir = path.dirname(filePath);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
@@ -29,11 +35,28 @@ function writeEndpoint(wsEndpoint: string): void {
   writeFileSync(filePath, wsEndpoint, 'utf8');
 }
 
-function removeEndpointFile(): void {
-  const filePath = getEndpointFilePath();
+function removeEndpointFile(instance = 'default'): void {
+  const filePath = getEndpointFilePath(instance);
   if (existsSync(filePath)) unlinkSync(filePath);
 }
 
+function listInstances(): Array<{ name: string; endpoint: string }> {
+  const dir = path.dirname(getEndpointFilePath());
+  if (!existsSync(dir)) return [];
+
+  const instances: Array<{ name: string; endpoint: string }> = [];
+  for (const fileName of readdirSync(dir)) {
+    if (!fileName.startsWith(ENDPOINT_FILENAME)) continue;
+    const suffix = fileName.slice(ENDPOINT_FILENAME.length);
+    if (suffix && !suffix.startsWith('-')) continue;
+    if (suffix === '-') continue;
+    const name = suffix.slice(1) || 'default';
+    if (!INSTANCE_NAME_PATTERN.test(name)) continue;
+    instances.push({ name, endpoint: readFileSync(path.join(dir, fileName), 'utf8').trim() });
+  }
+  return instances;
+}
+
 async function isServerRunning(wsEndpoint: string): Promise<boolean> {
   try {
     const browser = await chromium.connect(wsEndpoint, { timeout: 3000 });
@@ -46,7 +69,7 @@ async function isServerRunning(wsEndpoint: string): Promise<boolean> {
 
 const BROWSER_LAUNCHERS = { chromium, firefox, webkit } as const;
 
-async function launchServer(opts: { browser?: string; show?: boolean }): Promise<any> {
+async function launchServer(opts: { browser?: string; show?: boolean }, instance = 'default'): Promise<any> {
   const browserName = (opts.browser || 'chromium') as keyof typeof BROWSER_LAUNCHERS;
   const launcher = BROWSER_LAUNCHERS[browserName];
   if (!launcher) throw new Error(`Unsupported browser: ${browserName}`);
@@ -56,19 +79,21 @@ async function launchServer(opts: { browser?: string; show?: boolean }): Promise
   });
 
   const wsEndpoint = server.wsEndpoint();
-  writeEndpoint(wsEndpoint);
+  writeEndpoint(wsEndpoint, instance);
 
   log(`Browser server started: ${browserName} (${opts.show ? 'headed' : 'headless'})`);
 
   const cli = getCliName();
+  let instanceFlag = '';
+  if (instance !== 'default') instanceFlag = ` --instance ${instance}`;
   const sections: NextStepSection[] = [
     {
       label: 'Browser server',
-      path: getEndpointFilePath(),
+      path: getEndpointFilePath(instance),
       commands: [
         { label: 'Endpoint', command: wsEndpoint },
-        { label: 'Status', command: `${cli} browser status` },
-        { label: 'Stop', command: `${cli} browser stop` },
+        { label: 'Status', command: `${cli} browser status${instanceFlag}` },
+        { label: 'Stop', command: `${cli} browser stop${instanceFlag}` },
       ],
     },
   ];
@@ -77,12 +102,42 @@ async function launchServer(opts: { browser?: string; show?: boolean }): Promise
   return server;
 }
 
-async function getAliveEndpoint(): Promise<string | null> {
-  const endpoint = readEndpoint();
+async function stopServer(instance = 'default'): Promise<boolean> {
+  const endpoint = await getAliveEndpoint(instance);
+  if (!endpoint) return false;
+
+  try {
+    const browser = await chromium.connect(endpoint, { timeout: 3000 });
+    await browser.close();
+  } catch {}
+
+  removeEndpointFile(instance);
+  return true;
+}
+
+function keepServerRunning(stop: () => unknown): Promise<never> {
+  console.log('Browser server is running. Press Ctrl+C to stop.');
+  const heartbeat = setInterval(() => {}, KEEP_ALIVE_INTERVAL);
+
+  const cleanup = async () => {
+    console.log('\nStopping browser server...');
+    clearInterval(heartbeat);
+    await stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  return new Promise<never>(() => {});
+}
+
+async function getAliveEndpoint(instance = 'default'): Promise<string | null> {
+  const endpoint = readEndpoint(instance);
   if (!endpoint) return null;
   if (await isServerRunning(endpoint)) return endpoint;
-  removeEndpointFile();
+  removeEndpointFile(instance);
   return null;
 }
 
-export { readEndpoint, removeEndpointFile, isServerRunning, launchServer, getEndpointFilePath, getAliveEndpoint };
+export { readEndpoint, removeEndpointFile, isServerRunning, launchServer, stopServer, getEndpointFilePath, getAliveEndpoint, listInstances, keepServerRunning };

package/src/commands/clean-command.ts

@@ -15,12 +15,7 @@ export const CLEAN_TARGETS: Record<string, { description: string; getDir: () =>
 
 function getExperienceDir(): string {
   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: string): number {

package/src/commands/init-command.ts

@@ -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.ts';
+import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from '../global-config.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { log, tag } from '../utils/logger.js';
 import { relativeToCwd } from '../utils/next-steps.ts';
@@ -61,6 +63,48 @@ LANGFUSE_BASE_URL=
 TESTOMATIO=
 `;
 
+export async function runInit(options: InitCommandOptions): Promise<void> {
+  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: string, apiKey?: string): void {
+  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: InitCommandOptions): void {
   const configPath = options.configPath ?? './explorbot.config.js';
   const force = options.force ?? false;
@@ -134,8 +178,109 @@ export function runInitCommand(options: InitCommandOptions): void {
   }
 }
 
+async function runGlobalInit(options: InitCommandOptions): Promise<void> {
+  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: 'choose' | 'global'): Promise<'local' | 'global' | null> {
+  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: 'local' | 'global' | null) => {
+      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: string): string {
+  const { envKey } = PROVIDERS[provider];
+  const recommended = ConfigParser.recommendedModels()[provider] || {};
+  const roles: Array<[ModelRoleName, string]> = [
+    ['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: string): string[] {
+  const recommended = ConfigParser.recommendedModels()[provider] || {};
+  return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);
+}
+
+function writeEnvKey(key: string, value: string): void {
+  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');
+}
+
+type ModelRoleName = 'model' | 'visionModel' | 'agenticModel';
+
 type InitCommandOptions = {
   configPath?: string;
   force?: boolean;
   path?: string;
+  global?: boolean;
+  provider?: string;
+  apiKey?: string;
 };

package/src/commands/navigate-command.ts

@@ -15,7 +15,7 @@ export class NavigateCommand extends BaseCommand {
       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/src/commands/research-command.ts

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

package/src/commands/sites-command.ts

@@ -0,0 +1,27 @@
+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(): Promise<void> {
+    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/src/components/InitWizard.tsx

@@ -0,0 +1,166 @@
+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);
+
+interface InitWizardProps {
+  mode: 'choose' | 'global';
+  globalConfigExists: boolean;
+  onLocal: () => void;
+  onComplete: () => void;
+  onCancel: () => void;
+}
+
+const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLocal, onComplete, onCancel }) => {
+  const [step, setStep] = useState<'target' | 'provider' | 'key' | 'validate'>(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 (
+    <Box flexDirection="column" padding={1}>
+      <Box marginBottom={1}>
+        <Text color="cyan" bold>
+          Explorbot setup
+        </Text>
+      </Box>
+
+      {step === 'target' && (
+        <Box flexDirection="column">
+          <Text>Where should explorbot be initialized?</Text>
+          <Text color={targetIndex === 0 ? 'blue' : undefined}>
+            {targetIndex === 0 ? `${figureSet.pointer} ` : '  '}Local <Text dimColor>— creates the config file in the current directory</Text>
+          </Text>
+          <Text color={targetIndex === 1 ? 'blue' : undefined} dimColor={globalConfigExists}>
+            {targetIndex === 1 ? `${figureSet.pointer} ` : '  '}Global <Text dimColor>— initializes explorbot to run from anywhere on this machine</Text>
+            {globalConfigExists && <Text dimColor> (already installed)</Text>}
+          </Text>
+        </Box>
+      )}
+
+      {step === 'provider' && (
+        <Box flexDirection="column">
+          <Text>Pick an AI provider:</Text>
+          {PROVIDER_NAMES.map((name, index) => (
+            <Text key={name} color={index === providerIndex ? 'blue' : undefined}>
+              {index === providerIndex ? `${figureSet.pointer} ` : '  '}
+              {name}
+            </Text>
+          ))}
+        </Box>
+      )}
+
+      {step === 'key' && (
+        <Box flexDirection="column">
+          <Text>
+            Enter the API key for {provider} <Text dimColor>(stored as {envKey})</Text>
+          </Text>
+          <Box borderStyle="single" borderColor="blue" paddingX={1}>
+            <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 showPrompt={false} mask />
+          </Box>
+        </Box>
+      )}
+
+      {step === 'validate' && (
+        <Box flexDirection="column">
+          {!status && !error && <Text>Check the key with a test AI call? (y/n)</Text>}
+          {status && <Text color="yellow">{status}</Text>}
+          {error && (
+            <Box flexDirection="column">
+              <Text color="red">{error}</Text>
+              <Text dimColor>r: re-enter the key | n: save anyway</Text>
+            </Box>
+          )}
+        </Box>
+      )}
+
+      <Box marginTop={1}>
+        <Text dimColor>
+          Config goes to {globalDir()} | {step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm'} | Ctrl+C: exit
+        </Text>
+      </Box>
+    </Box>
+  );
+};
+
+function defaultModelId(provider: string): string {
+  const recommended = ConfigParser.recommendedModels()[provider] || {};
+  return recommended.model || recommended.agenticModel || recommended.visionModel || '';
+}
+
+export default InitWizard;

package/src/components/InputReadline.tsx

@@ -17,6 +17,7 @@ interface InputReadlineProps {
   value?: string;
   placeholder?: string;
   showPrompt?: boolean;
+  mask?: boolean;
 }
 
 interface InputState {
@@ -26,7 +27,7 @@ interface InputState {
   selectedIndex: number;
 }
 
-const InputReadline: React.FC<InputReadlineProps> = React.memo(({ commandHandler, exitOnEmptyInput = false, onSubmit, onChange, onCommandStart, onCommandComplete, isActive = true, visible = true, value: controlledValue, placeholder = '', showPrompt = true }) => {
+const InputReadline: React.FC<InputReadlineProps> = 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<InputState>({
     value: controlledValue || '',
@@ -616,11 +617,14 @@ const InputReadline: React.FC<InputReadlineProps> = React.memo(({ commandHandler
     }
   }, [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] || '';