explorbot 0.5.7 → 0.5.9

package/src/components/InitWizard.tsx

@@ -15,14 +15,16 @@ interface InitWizardProps {
   onLocal: () => void;
   onComplete: () => void;
   onCancel: () => void;
-  onLocalProvider?: (provider: string) => void;
+  onLocalSetup?: (setup: { provider: string; apiKey: string; url: string }) => void;
 }
 
-const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, onLocalProvider }) => {
-  const [step, setStep] = useState<'target' | 'provider' | 'key' | 'validate'>(mode === 'choose' ? 'target' : 'provider');
+const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, onLocalSetup }) => {
+  const [step, setStep] = useState<'target' | 'provider' | 'key' | 'validate' | 'url'>(mode === 'choose' ? 'target' : 'provider');
   const [targetIndex, setTargetIndex] = useState(0);
   const [providerIndex, setProviderIndex] = useState(0);
   const [apiKey, setApiKey] = useState('');
+  const [url, setUrl] = useState('');
+  const [urlError, setUrlError] = useState('');
   const [status, setStatus] = useState('');
   const [error, setError] = useState('');
 
@@ -30,6 +32,11 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
   const envKey = PROVIDERS[provider].envKey;
 
   const save = () => {
+    if (mode === 'local') {
+      setStatus('');
+      setStep('url');
+      return;
+    }
     writeGlobalConfig(provider, apiKey.trim());
     onComplete();
   };
@@ -61,7 +68,7 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
       return;
     }
 
-    if (step === 'key') return;
+    if (step === 'key' || step === 'url') return;
 
     if (key.escape) {
       onCancel();
@@ -79,10 +86,7 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
     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) {
-        if (mode === 'local') onLocalProvider?.(provider);
-        else setStep('key');
-      }
+      if (key.return) setStep('key');
       return;
     }
 
@@ -132,7 +136,10 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
       {step === 'key' && (
         <Box flexDirection="column">
           <Text>
-            Enter the API key for {provider} <Text dimColor>(stored as {envKey})</Text>
+            Enter the API key for {provider}{' '}
+            <Text dimColor>
+              (stored as {envKey}, create one at {PROVIDERS[provider].keyUrl})
+            </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 />
@@ -147,15 +154,40 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
           {error && (
             <Box flexDirection="column">
               <Text color="red">{error}</Text>
-              <Text dimColor>r: re-enter the key | n: save anyway</Text>
+              <Text dimColor>r: re-enter the key | n: continue anyway</Text>
             </Box>
           )}
         </Box>
       )}
 
+      {step === 'url' && (
+        <Box flexDirection="column">
+          <Text>
+            What is the URL of the web application to test? <Text dimColor>(written to web.url in the config)</Text>
+          </Text>
+          <Box borderStyle="single" borderColor="blue" paddingX={1}>
+            <InputReadline
+              value={url}
+              onChange={setUrl}
+              onSubmit={() => {
+                if (!URL.canParse(url.trim())) {
+                  setUrlError('Enter a full URL, e.g. http://localhost:3000');
+                  return;
+                }
+                onLocalSetup?.({ provider, apiKey: apiKey.trim(), url: url.trim() });
+              }}
+              placeholder="http://localhost:3000"
+              isActive
+              showPrompt={false}
+            />
+          </Box>
+          {urlError && <Text color="red">{urlError}</Text>}
+        </Box>
+      )}
+
       <Box marginTop={1}>
         <Text dimColor>
-          Config goes to {mode === 'local' ? 'the current directory' : globalDir()} | {step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm'} | Ctrl+C: exit
+          Config goes to {mode === 'local' ? 'the current directory' : globalDir()} | {step === 'key' || step === 'url' ? 'Enter: continue' : '↑↓: select | Enter: confirm'} | Ctrl+C: exit
         </Text>
       </Box>
     </Box>

package/src/config.ts

@@ -11,13 +11,13 @@ import { deepMerge } from './utils/merge.js';
 import { log, tag } from './utils/logger.js';
 
 export const PROVIDERS: Record<string, ProviderInfo> = {
-  openai: { envKey: 'OPENAI_API_KEY', load: async () => (await import('@ai-sdk/openai')).createOpenAI() },
-  anthropic: { envKey: 'ANTHROPIC_API_KEY', load: async () => (await import('@ai-sdk/anthropic')).createAnthropic() },
-  google: { envKey: 'GOOGLE_GENERATIVE_AI_API_KEY', load: async () => (await import('@ai-sdk/google')).createGoogleGenerativeAI() },
-  groq: { envKey: 'GROQ_API_KEY', load: async () => (await import('@ai-sdk/groq')).createGroq() },
-  mistral: { envKey: 'MISTRAL_API_KEY', load: async () => (await import('@ai-sdk/mistral')).createMistral() },
-  openrouter: { envKey: 'OPENROUTER_API_KEY', load: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter() },
-  sambanova: { envKey: 'SAMBANOVA_API_KEY', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
+  openai: { envKey: 'OPENAI_API_KEY', keyUrl: 'https://platform.openai.com/api-keys', load: async () => (await import('@ai-sdk/openai')).createOpenAI() },
+  anthropic: { envKey: 'ANTHROPIC_API_KEY', keyUrl: 'https://console.anthropic.com/settings/keys', load: async () => (await import('@ai-sdk/anthropic')).createAnthropic() },
+  google: { envKey: 'GOOGLE_GENERATIVE_AI_API_KEY', keyUrl: 'https://aistudio.google.com/apikey', load: async () => (await import('@ai-sdk/google')).createGoogleGenerativeAI() },
+  groq: { envKey: 'GROQ_API_KEY', keyUrl: 'https://console.groq.com/keys', load: async () => (await import('@ai-sdk/groq')).createGroq() },
+  mistral: { envKey: 'MISTRAL_API_KEY', keyUrl: 'https://console.mistral.ai/api-keys', load: async () => (await import('@ai-sdk/mistral')).createMistral() },
+  openrouter: { envKey: 'OPENROUTER_API_KEY', keyUrl: 'https://openrouter.ai/keys', load: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter() },
+  sambanova: { envKey: 'SAMBANOVA_API_KEY', keyUrl: 'https://cloud.sambanova.ai/apis', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
 };
 
 export const MODEL_ROLES: ModelRole[] = ['model', 'visionModel', 'agenticModel'];
@@ -169,6 +169,7 @@ interface AgentsConfig {
 
 interface AIConfig {
   model: any;
+  recommendedModels?: string;
   apiKey?: string;
   config?: Record<string, any>;
   langfuse?: {
@@ -890,11 +891,34 @@ export async function resolveConfigModels(ai?: AIConfig): Promise<void> {
     if (typeof ai[role] === 'string') ai[role] = await resolveModel(ai[role], role);
   }
 
+  await fillRecommendedModels(ai);
+
   for (const agent of Object.values(ai.agents || {})) {
     if (typeof agent?.model === 'string') agent.model = await resolveModel(agent.model);
   }
 }
 
+async function fillRecommendedModels(ai: AIConfig): Promise<void> {
+  const provider = ai.recommendedModels;
+  if (!provider) return;
+
+  const recommended = ConfigParser.recommendedModels()[provider];
+  if (!recommended) {
+    throw new Error(`No recommended models for "${provider}". Use a provider with recommendations: ${Object.keys(ConfigParser.recommendedModels()).join(', ')}`);
+  }
+
+  for (const role of MODEL_ROLES) {
+    if (ai[role]) continue;
+    if (!recommended[role]) continue;
+    ai[role] = await resolveModel(provider, role);
+  }
+
+  if (!ai.decisionModel && recommended.decisionModel) ai.decisionModel = { provider, model: recommended.decisionModel };
+
+  const missing = missingModelRoles(provider);
+  if (missing.length) tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set them explicitly as "provider/model-id"`);
+}
+
 export function resolveLangfuse(ai?: AIConfig): void {
   if (!ai) return;
 
@@ -994,6 +1018,7 @@ interface ConfiguredModel {
 
 interface ProviderInfo {
   envKey: string;
+  keyUrl: string;
   load: () => Promise<(modelId: string) => any>;
 }
 

package/src/explorbot.ts

@@ -137,6 +137,7 @@ export class ExplorBot {
     if (typeof this.options.session === 'string') this.options.session = path.resolve(this.options.path || '.', this.options.session);
     if (this.options.optionalAi) return this.bootstrapOptionalProvider();
     this.provider = new AIProvider(this.config.ai);
+    this.provider.setJudge(this.judge());
     await this.provider.validateConnection();
   }
 
@@ -266,8 +267,11 @@ export class ExplorBot {
         return new Tester(deps, researcher, navigator, tools);
       });
 
-      const qm = this.agentQuartermaster();
-      if (qm) this.agents.tester.setQuartermaster(qm);
+      if (this.config.ai?.agents?.quartermaster?.enabled === true) {
+        const quartermaster = this.agentQuartermaster();
+        quartermaster.start(this.stateManager());
+        this.agents.tester.setQuartermaster(quartermaster);
+      }
       if (this.isHistorianEnabled()) this.agents.tester.setHistorian(this.agentHistorian());
       this.agents.tester.setPilot(this.agentPilot());
       this.agents.tester.setCaptain(this.agentCaptain());
@@ -289,17 +293,8 @@ export class ExplorBot {
     return (this.agents.experienceCompactor ||= new ExperienceCompactor(this.provider, this.experienceTracker()));
   }
 
-  agentQuartermaster(): Quartermaster | null {
-    const config = this.config.ai?.agents?.quartermaster;
-    if (config?.enabled !== true) return null;
-
-    if (!this.agents.quartermaster) {
-      this.agents.quartermaster = new Quartermaster(this.provider, {
-        model: config?.model,
-      });
-      this.agents.quartermaster.start(this.explorer, this.stateManager());
-    }
-    return this.agents.quartermaster;
+  agentQuartermaster(): Quartermaster {
+    return (this.agents.quartermaster ||= new Quartermaster(this.provider, this.explorer, { model: this.config.ai?.agents?.quartermaster?.model }));
   }
 
   agentHistorian(): Historian {
@@ -571,6 +566,7 @@ export class ExplorBot {
   private async bootstrapOptionalProvider(): Promise<void> {
     try {
       const provider = new AIProvider(this.config.ai);
+      provider.setJudge(this.judge());
       await provider.validateConnection();
       this.provider = provider;
     } catch (error) {

package/src/explorer.ts

@@ -104,6 +104,7 @@ class Explorer {
       throw new Error('Playwright helper not available');
     }
     this.applyBasePathToHelper();
+    codeceptjs.store.visibleLocator = this.playwrightHelper.options?.visibleLocator;
     await this.connectOrLaunchBrowser();
     const hasSession = !this.options?.attachedBrowser && this.options?.session && existsSync(this.options.session);
     await this.openContextPage();

package/src/global-config.ts

@@ -6,6 +6,7 @@ import dedent from 'dedent';
 
 const GLOBAL_CONFIG_NAMES = ['config.js', 'config.mjs', 'config.ts'];
 const SITE_DIRS = ['knowledge', 'experience', 'output'];
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
 
 export const EXPLORBOT_CONFIG_PATHS = ['explorbot.config.js', 'explorbot.config.mjs', 'explorbot.config.ts'];
 
@@ -34,7 +35,9 @@ export function sitesDir(): string {
 }
 
 export function siteFolderName(url: string): string {
-  return new URL(url).host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+  const parsed = new URL(url);
+  if (LOOPBACK_HOSTS.includes(parsed.hostname)) parsed.hostname = 'localhost';
+  return parsed.host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
 }
 
 export function listSites(): SiteRecord[] {
@@ -81,7 +84,7 @@ function validateSiteConfig(config: any, configPath: string, baseUrl: string): v
   }
 
   const declared = URL.parse(url)?.origin;
-  if (declared === baseUrl) return;
+  if (declared && siteFolderName(declared) === siteFolderName(baseUrl)) return;
 
   throw new Error(dedent`
     Site config declares a different site.

package/src/utils/ux-probe.ts

@@ -0,0 +1,163 @@
+import { HTML_SELECTORS, HTML_VISIBILITY_LIMITS } from './html.ts';
+
+export const UX_FOCUS_ATTR = 'data-explorbot-ux';
+
+const UX_LIMITS = {
+  touchTarget: 44,
+  pointerTarget: 24,
+  touchWidth: 1024,
+  targetGap: 8,
+  minFontSize: 12,
+  minLineHeight: 1.3,
+  maxEntries: 8,
+  minOpacity: HTML_VISIBILITY_LIMITS.minOpacity,
+};
+
+export function uxProbeArgs(scope: string): UxProbeArgs {
+  return { scope, controlsSelector: HTML_SELECTORS.interactiveControl, limits: UX_LIMITS };
+}
+
+export function renderUxMeasurements(measurements: UxMeasurements): string {
+  const lines = [`viewport: ${measurements.width}px wide`];
+  for (const [check, entries] of Object.entries(measurements.checks)) {
+    if (!entries.length) continue;
+    lines.push(`${check}:`, ...entries.map((entry) => `  - ${entry}`));
+  }
+  if (lines.length === 1) lines.push('no measurable problems');
+  return lines.join('\n');
+}
+
+// Passed to page.evaluate as a function — must stay self-contained with no outer-scope references.
+export function measureUx({ scope, controlsSelector, limits }: UxProbeArgs): UxMeasurements {
+  const root = document.querySelector(scope) || document.body;
+  const width = window.innerWidth;
+  const touch = width <= limits.touchWidth;
+  const visibleWidth = document.documentElement.clientWidth;
+  const checks: Record<string, string[]> = {
+    'horizontal overflow': [],
+    'zoom and viewport meta': [],
+    'small targets': [],
+    'crowded targets': [],
+    'placeholder-only labels': [],
+    'small text': [],
+    'cramped line-height': [],
+    'truncated text without full text': [],
+    'layout-property transitions': [],
+  };
+
+  const add = (check: string, entry: string) => {
+    if (checks[check].length >= limits.maxEntries) return;
+    if (checks[check].includes(entry)) return;
+    checks[check].push(entry);
+  };
+
+  const describe = (el: Element) => {
+    const role = el.getAttribute('role') || el.tagName.toLowerCase();
+    const name = (el.getAttribute('aria-label') || (el as HTMLElement).innerText || el.getAttribute('placeholder') || el.getAttribute('title') || '').trim().replace(/\s+/g, ' ');
+    if (!name) return `${role} (unnamed)`;
+    return `${role} "${name.slice(0, 40)}"`;
+  };
+
+  const visible = (el: Element) => {
+    const rect = el.getBoundingClientRect();
+    if (!rect.width || !rect.height) return false;
+    const style = window.getComputedStyle(el);
+    return style.visibility !== 'hidden' && style.display !== 'none' && Number(style.opacity) > limits.minOpacity;
+  };
+
+  if (root === document.body || root.matches('main, [role="main"]')) {
+    const docWidth = document.documentElement.scrollWidth;
+    if (docWidth > visibleWidth + 1) add('horizontal overflow', `page is ${docWidth}px wide in a ${visibleWidth}px visible area`);
+
+    const meta = document.querySelector('meta[name="viewport"]')?.getAttribute('content');
+    if (!meta) add('zoom and viewport meta', 'no viewport meta tag');
+    const metaRules = (meta || '').toLowerCase().replace(/\s/g, '');
+    if (metaRules.includes('user-scalable=no') || metaRules.includes('user-scalable=0')) add('zoom and viewport meta', 'zoom disabled by user-scalable');
+    const maxScale = metaRules.split(',').find((part) => part.startsWith('maximum-scale='));
+    if (maxScale && Number(maxScale.split('=')[1]) <= 1) add('zoom and viewport meta', `zoom capped by ${maxScale}`);
+  }
+
+  const minTarget = touch ? limits.touchTarget : limits.pointerTarget;
+  const controls = Array.from(root.querySelectorAll(controlsSelector)).filter(visible);
+  const boxes = controls.map((el) => ({ el, rect: el.getBoundingClientRect() }));
+  for (const { el, rect } of boxes) {
+    if (el.tagName === 'A' && window.getComputedStyle(el).display === 'inline') continue;
+    if (rect.width >= minTarget && rect.height >= minTarget) continue;
+    add('small targets', `${describe(el)} is ${Math.round(rect.width)}×${Math.round(rect.height)}px, below ${minTarget}px`);
+  }
+
+  if (touch) {
+    for (let i = 0; i < boxes.length; i++) {
+      for (let j = i + 1; j < boxes.length; j++) {
+        const a = boxes[i];
+        const b = boxes[j];
+        if (a.el.contains(b.el) || b.el.contains(a.el)) continue;
+        const gapX = Math.max(b.rect.left - a.rect.right, a.rect.left - b.rect.right);
+        const gapY = Math.max(b.rect.top - a.rect.bottom, a.rect.top - b.rect.bottom);
+        const gap = Math.max(gapX, gapY);
+        if (gap >= limits.targetGap) continue;
+        if (a.rect.height >= limits.touchTarget && b.rect.height >= limits.touchTarget && a.rect.width >= limits.touchTarget && b.rect.width >= limits.touchTarget) continue;
+        add('crowded targets', `${describe(a.el)} and ${describe(b.el)} are ${Math.max(0, Math.round(gap))}px apart`);
+      }
+    }
+  }
+
+  for (const el of Array.from(root.querySelectorAll('input[placeholder], textarea[placeholder]'))) {
+    if (!visible(el)) continue;
+    if (el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title')) continue;
+    if ((el as HTMLInputElement).labels?.length) continue;
+    add('placeholder-only labels', describe(el));
+  }
+
+  for (const el of Array.from(root.querySelectorAll('*'))) {
+    if (!visible(el)) continue;
+    const rect = el.getBoundingClientRect();
+    const style = window.getComputedStyle(el);
+
+    const overflows = rect.right > visibleWidth + 1 && rect.left < visibleWidth;
+    if (overflows && !(el.parentElement && el.parentElement.getBoundingClientRect().right > visibleWidth + 1)) add('horizontal overflow', `${describe(el)} ends at ${Math.round(rect.right)}px`);
+
+    const animated = style.transitionProperty.split(',').map((property) => property.trim());
+    const layout = animated.filter((property) => ['width', 'height', 'top', 'left', 'right', 'bottom', 'margin', 'padding'].includes(property));
+    const transitions = style.transitionDuration.split(',').some((duration) => Number.parseFloat(duration) > 0);
+    if (transitions && layout.length) add('layout-property transitions', `${describe(el)} transitions ${layout.join(', ')}`);
+
+    const ownText = Array.from(el.childNodes)
+      .filter((node) => node.nodeType === Node.TEXT_NODE)
+      .map((node) => node.textContent || '')
+      .join('')
+      .trim();
+    if (!ownText) continue;
+
+    const fontSize = Number.parseFloat(style.fontSize);
+    if (fontSize < limits.minFontSize) add('small text', `"${ownText.slice(0, 40)}" at ${fontSize}px`);
+
+    const lineHeight = Number.parseFloat(style.lineHeight);
+    const multiline = rect.height > fontSize * 2.5;
+    if (multiline && lineHeight && lineHeight / fontSize < limits.minLineHeight) add('cramped line-height', `"${ownText.slice(0, 40)}" at ${(lineHeight / fontSize).toFixed(2)}`);
+
+    const htmlEl = el as HTMLElement;
+    if (style.textOverflow === 'ellipsis' && htmlEl.scrollWidth > htmlEl.clientWidth && !el.getAttribute('title')) add('truncated text without full text', `"${ownText.slice(0, 40)}"`);
+  }
+
+  return { width, checks };
+}
+
+export function countRunningAnimations(scope: string): number {
+  const root = document.querySelector(scope) || document.body;
+  return document.getAnimations().filter((animation) => {
+    const target = (animation.effect as KeyframeEffect | null)?.target;
+    return animation.playState === 'running' && target && root.contains(target);
+  }).length;
+}
+
+interface UxProbeArgs {
+  scope: string;
+  controlsSelector: string;
+  limits: typeof UX_LIMITS;
+}
+
+export interface UxMeasurements {
+  width: number;
+  checks: Record<string, string[]>;
+}