explorbot 0.0.1 → 0.1.0

package/src/utils/retry.ts

@@ -0,0 +1,73 @@
+import { createDebug, tag } from './logger.js';
+
+const debugLog = createDebug('explorbot:retry');
+
+const RATE_LIMIT_DELAYS = [10_000, 20_000, 30_000, 60_000, 90_000];
+const RATE_LIMIT_MAX_ATTEMPTS = RATE_LIMIT_DELAYS.length + 1;
+
+export interface RetryOptions {
+  maxAttempts?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  backoffMultiplier?: number;
+  retryCondition?: (error: Error) => boolean;
+}
+
+const defaultOptions: Required<RetryOptions> = {
+  maxAttempts: 3,
+  baseDelay: 1000,
+  maxDelay: 10000,
+  backoffMultiplier: 2,
+  retryCondition: (error: Error) => {
+    return error.constructor.name === 'AI_APICallError' || error.message.includes('schema') || error.message.includes('timeout') || error.message.includes('network') || error.message.includes('rate limit') || error.message.includes('Failed to generate JSON');
+  },
+};
+
+function isRateLimitError(error: Error): boolean {
+  return error.message.toLowerCase().includes('rate limit');
+}
+
+export async function withRetry<T>(operation: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
+  const config = { ...defaultOptions, ...options };
+  let lastError: Error;
+  let rateLimitAttempt = 0;
+
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+    try {
+      if (attempt > 1) debugLog(`Attempt ${attempt}/${config.maxAttempts}`);
+      return await operation();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (lastError.name === 'AbortError') {
+        throw lastError;
+      }
+
+      if (isRateLimitError(lastError) && rateLimitAttempt < RATE_LIMIT_DELAYS.length) {
+        const delay = RATE_LIMIT_DELAYS[rateLimitAttempt];
+        tag('warning').log(`Rate limit hit, waiting ${delay / 1000}s before retry (${rateLimitAttempt + 1}/${RATE_LIMIT_MAX_ATTEMPTS})...`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        rateLimitAttempt++;
+        attempt--;
+        continue;
+      }
+
+      if (attempt === config.maxAttempts) {
+        debugLog(`All ${config.maxAttempts} attempts failed`);
+        throw lastError;
+      }
+
+      if (!config.retryCondition(lastError)) {
+        debugLog('Error does not meet retry condition, not retrying');
+        throw lastError;
+      }
+
+      const delay = Math.min(config.baseDelay * config.backoffMultiplier ** (attempt - 1), config.maxDelay);
+
+      debugLog(`Retrying in ${delay}ms. Error: ${lastError.message}`);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError!;
+}

package/src/utils/rules-loader.ts

@@ -0,0 +1,118 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tag } from './logger.ts';
+import { matchesUrl } from './url-matcher.ts';
+
+const BUILT_IN_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../../rules');
+
+export class RulesLoader {
+  static loadRules(agentName: string, rulesConfig: RuleEntry[], currentUrl: string): string {
+    const parts: string[] = [];
+
+    for (const entry of rulesConfig) {
+      if (typeof entry === 'string') {
+        const content = loadFile(agentName, entry);
+        if (content) parts.push(content);
+        continue;
+      }
+
+      for (const [pattern, filename] of Object.entries(entry)) {
+        if (!matchesUrl(pattern, currentUrl)) continue;
+        const content = loadFile(agentName, filename);
+        if (content) parts.push(content);
+      }
+    }
+
+    return parts.join('\n\n');
+  }
+
+  static loadStyles(agentName: string, styleNames: string[]): Record<string, string> {
+    const styles: Record<string, string> = {};
+    for (const name of styleNames) {
+      styles[name] = loadStyleFile(agentName, name);
+    }
+    return styles;
+  }
+
+  static listStyleNames(agentName: string): string[] {
+    const names = new Set<string>();
+    const userDir = join(process.cwd(), 'rules', agentName, 'styles');
+    const builtInDir = join(BUILT_IN_DIR, agentName, 'styles');
+    for (const dir of [userDir, builtInDir]) {
+      if (!existsSync(dir)) continue;
+      for (const f of readdirSync(dir)) {
+        if (f.endsWith('.md')) names.add(basename(f, '.md'));
+      }
+    }
+    if (!names.size) {
+      throw new Error(`No planning styles found for agent "${agentName}". Expected .md files under rules/${agentName}/styles/ or bundled rules.`);
+    }
+    return [...names].sort();
+  }
+
+  static getActiveStyle(styles: Record<string, string>, iteration: number, override?: string): { name: string; approach: string } {
+    const names = Object.keys(styles);
+
+    if (override) {
+      const approach = styles[override];
+      if (!approach) throw new Error(`Unknown planning style: "${override}". Available: ${names.join(', ')}`);
+      return { name: override, approach };
+    }
+
+    const idx = iteration % names.length;
+    const name = names[idx];
+    return { name, approach: styles[name] };
+  }
+
+  static extractStyles(agentName: string, targetDir: string): string[] {
+    const sourceDir = join(BUILT_IN_DIR, agentName, 'styles');
+    if (!existsSync(sourceDir)) throw new Error(`No built-in styles found for agent: ${agentName}`);
+
+    mkdirSync(targetDir, { recursive: true });
+
+    const files = readdirSync(sourceDir)
+      .filter((f) => f.endsWith('.md'))
+      .sort();
+    const extracted: string[] = [];
+
+    for (const file of files) {
+      const target = join(targetDir, file);
+      if (existsSync(target)) {
+        tag('info').log(`Skipping ${file} (already exists)`);
+        continue;
+      }
+      writeFileSync(target, readFileSync(join(sourceDir, file), 'utf8'));
+      extracted.push(file);
+      tag('success').log(`Extracted ${file}`);
+    }
+
+    return extracted;
+  }
+}
+
+function loadFile(agentName: string, name: string, subdir?: string): string | undefined {
+  const file = `${name}.md`;
+  const segments = subdir ? [agentName, subdir, file] : [agentName, file];
+
+  const userPath = join(process.cwd(), 'rules', ...segments);
+  if (existsSync(userPath)) return readFileSync(userPath, 'utf8').trim();
+
+  const builtInPath = join(BUILT_IN_DIR, ...segments);
+  if (existsSync(builtInPath)) return readFileSync(builtInPath, 'utf8').trim();
+
+  return undefined;
+}
+
+function loadStyleFile(agentName: string, name: string): string {
+  const content = loadFile(agentName, name, 'styles');
+  if (content) return content;
+
+  const userPath = join(process.cwd(), 'rules', agentName, 'styles', `${name}.md`);
+  const builtInPath = join(BUILT_IN_DIR, agentName, 'styles', `${name}.md`);
+  throw new Error(`Style "${name}" not found for agent "${agentName}". Searched: ${userPath}, ${builtInPath}`);
+}
+
+type RuleEntry = string | Record<string, string>;
+
+export type { RuleEntry };

package/src/utils/strings.ts

@@ -0,0 +1,13 @@
+export function truncateJson(input: any): string {
+  if (!input) return '';
+  const str = JSON.stringify(input);
+  return str.length <= 80 ? str : `${str.slice(0, 77)}...`;
+}
+
+export function sanitizeFilename(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 50);
+}

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

@@ -0,0 +1,332 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { type Note, Plan, Test } from '../test-plan.ts';
+import { mdq } from './markdown-query.ts';
+
+const NOISE_PREFIXES = ['Test started', 'Finish requested:', 'Session name:'];
+
+function isNoiseNote(message: string): boolean {
+  return NOISE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+function getPilotVerdict(notes: Record<string, Note>): string | null {
+  for (const note of Object.values(notes)) {
+    if (note.status === 'passed' && note.message.startsWith('Pilot:')) {
+      return note.message.replace(/^Pilot:\s*/, '');
+    }
+  }
+  return null;
+}
+
+function formatBulletItem(text: string): string {
+  const lines = text.split('\n');
+  let result = `* ${lines[0]}\n`;
+  for (let i = 1; i < lines.length; i++) {
+    result += `${lines[i]}\n`;
+  }
+  return result;
+}
+
+function parseMultiLineBullet(lines: string[], i: number): { text: string; nextIndex: number } {
+  let text = lines[i].replace(/^\*\s+/, '');
+  let j = i + 1;
+  while (j < lines.length) {
+    const nextLine = lines[j];
+    const trimmedNext = nextLine.trim();
+    if (nextLine.match(/^\*\s+/)) break;
+    if (trimmedNext.startsWith('##') || trimmedNext.startsWith('<!--')) break;
+    if (nextLine.startsWith('  ')) {
+      text += `\n${nextLine}`;
+      j++;
+    } else {
+      break;
+    }
+  }
+  return { text, nextIndex: j - 1 };
+}
+
+function formatFailedNotes(notes: Record<string, Note>): string[] {
+  const lines: string[] = [];
+  for (const note of Object.values(notes)) {
+    if (!note.status) continue;
+    if (isNoiseNote(note.message)) continue;
+    if (note.message.startsWith('Pilot:')) continue;
+    if (note.status === 'passed') {
+      lines.push(`  ${note.message}`);
+    } else if (note.status === 'failed') {
+      lines.push(`  FAILED ${note.message}`);
+    }
+  }
+  return lines;
+}
+
+export function planToCompactAiContext(plan: Plan): string {
+  const allTests = plan.getAllTests();
+  const passed = allTests.filter((t) => t.result === 'passed');
+  const failed = allTests.filter((t) => t.result === 'failed');
+  const pending = allTests.filter((t) => !t.result);
+
+  const summaryParts: string[] = [];
+  if (passed.length > 0) summaryParts.push(`${passed.length} passed`);
+  if (failed.length > 0) summaryParts.push(`${failed.length} failed`);
+  if (pending.length > 0) summaryParts.push(`${pending.length} pending`);
+
+  let content = `${allTests.length} tests (${summaryParts.join(', ')})\n`;
+
+  if (passed.length > 0) {
+    content += '\n## Passed\n';
+    for (const test of passed) {
+      content += `- [${test.priority}]${test.style ? ` [${test.style}]` : ''} "${test.scenario}"\n`;
+      if (test.startUrl) content += `  url: ${test.startUrl}\n`;
+      const verdict = getPilotVerdict(test.notes);
+      if (verdict) content += `  Verdict: ${verdict}\n`;
+    }
+  }
+
+  if (failed.length > 0) {
+    content += '\n## Failed\n';
+    for (const test of failed) {
+      content += `- [${test.priority}]${test.style ? ` [${test.style}]` : ''} "${test.scenario}"\n`;
+      if (test.startUrl) content += `  url: ${test.startUrl}\n`;
+      const noteLines = formatFailedNotes(test.notes);
+      content += noteLines.join('\n');
+      if (noteLines.length > 0) content += '\n';
+    }
+  }
+
+  if (pending.length > 0) {
+    content += '\n## Pending\n';
+    for (const test of pending) {
+      content += `- [${test.priority}] "${test.scenario}"\n`;
+    }
+  }
+
+  return content;
+}
+
+export function parsePlanFromMarkdown(filePath: string): Plan {
+  const plans = parsePlansFromMarkdown(filePath);
+  if (plans.length === 0) return new Plan('');
+  if (plans.length === 1) return plans[0];
+
+  const main = plans[0];
+  for (let i = 1; i < plans.length; i++) {
+    for (const test of plans[i].tests) {
+      main.addTest(test);
+    }
+  }
+  return main;
+}
+
+export function parsePlansFromMarkdown(filePath: string): Plan[] {
+  const content = readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  const plans: Plan[] = [];
+  let currentPlan: Plan | null = null;
+  let currentTest: Test | null = null;
+  let inRequirements = false;
+  let inSteps = false;
+  let inExpected = false;
+  let priority: 'critical' | 'important' | 'high' | 'normal' | 'low' = 'normal';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    if (line.startsWith('<!-- suite -->')) {
+      currentTest = null;
+      inRequirements = false;
+      inSteps = false;
+      inExpected = false;
+      priority = 'normal';
+      const title = lines[i + 1]?.replace(/^#\s+/, '') || '';
+      currentPlan = new Plan(title);
+      plans.push(currentPlan);
+      i++;
+      continue;
+    }
+
+    if (!currentPlan) continue;
+
+    if (line.startsWith('<!-- test')) {
+      currentTest = null;
+      const priorityMatch = line.match(/priority:\s*(\w+)/);
+      priority = (priorityMatch?.[1] as 'critical' | 'important' | 'high' | 'normal' | 'low') || 'normal';
+      continue;
+    }
+
+    if (line.startsWith('# ') && currentTest === null) {
+      const scenario = line.replace(/^#\s+/, '');
+      currentTest = new Test(scenario, priority, [], '');
+      currentPlan.addTest(currentTest);
+      inRequirements = false;
+      inSteps = false;
+      inExpected = false;
+      continue;
+    }
+
+    if (currentTest && line === '## Requirements') {
+      inRequirements = true;
+      inSteps = false;
+      inExpected = false;
+      continue;
+    }
+
+    if (currentTest && line === '## Steps') {
+      inRequirements = false;
+      inSteps = true;
+      inExpected = false;
+      continue;
+    }
+
+    if (currentTest && line === '## Expected') {
+      inRequirements = false;
+      inSteps = false;
+      inExpected = true;
+      continue;
+    }
+
+    if (currentTest && inRequirements && line && !line.startsWith('##')) {
+      currentTest.startUrl = line;
+      continue;
+    }
+
+    if (currentTest && inSteps && line.startsWith('* ')) {
+      const { text, nextIndex } = parseMultiLineBullet(lines, i);
+      currentTest.plannedSteps.push(text);
+      i = nextIndex;
+      continue;
+    }
+
+    if (currentTest && inExpected && line.startsWith('* ')) {
+      const { text, nextIndex } = parseMultiLineBullet(lines, i);
+      currentTest.expected.push(text);
+      i = nextIndex;
+    }
+  }
+
+  for (const plan of plans) {
+    if (plan.url) continue;
+    const suiteStart = content.indexOf(`# ${plan.title}`);
+    if (suiteStart === -1) continue;
+    const nextSuite = content.indexOf('<!-- suite -->', suiteStart + 1);
+    const suiteContent = nextSuite === -1 ? content.slice(suiteStart) : content.slice(suiteStart, nextSuite);
+    const firstItem = mdq(suiteContent).query('section[0] item[0]').text().trim();
+    const urlMatch = firstItem.match(/^URL:\s*(.+)/);
+    if (urlMatch) {
+      plan.url = urlMatch[1].replace(/\*\*|`|\*|_|~~?/g, '').trim();
+      for (const test of plan.tests) {
+        if (!test.startUrl) test.startUrl = plan.url;
+      }
+    }
+  }
+
+  return plans;
+}
+
+function formatPlanSuite(plan: Plan): string {
+  let content = `<!-- suite -->\n# ${plan.title}\n\n`;
+
+  if (plan.url) {
+    content += `### Prerequisite\n\n* URL: ${plan.url}\n\n`;
+  }
+
+  if (plan.iteration > 0) {
+    content += `<!-- plan updated on ${new Date().toISOString()} -->\n\n`;
+  }
+
+  for (const test of plan.tests) {
+    content += `<!-- test\npriority: ${test.priority}\n-->\n`;
+    content += `# ${test.scenario}\n\n`;
+    content += '## Requirements\n';
+    content += `${test.startUrl || 'Current page'}\n\n`;
+
+    if (test.plannedSteps.length > 0) {
+      content += '## Steps\n';
+      for (const step of test.plannedSteps) {
+        content += formatBulletItem(step);
+      }
+      content += '\n';
+    }
+
+    content += '## Expected\n';
+
+    for (const expectation of test.expected) {
+      content += formatBulletItem(expectation);
+    }
+
+    content += '\n';
+  }
+
+  return content;
+}
+
+export function savePlanToMarkdown(plan: Plan, filePath: string): void {
+  writeFileSync(filePath, formatPlanSuite(plan), 'utf-8');
+}
+
+export function savePlansToMarkdown(plans: Plan[], filePath: string): void {
+  const content = plans.map((plan) => formatPlanSuite(plan)).join('\n');
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+export function planToAiContext(plan: Plan, options?: { skipSteps?: boolean }): string {
+  let content = `# Test Plan: ${plan.title}\n\n`;
+
+  if (plan.url) {
+    content += `**URL:** ${plan.url}\n\n`;
+  }
+
+  content += `**Total Tests:** ${plan.tests.length}\n`;
+  content += `**Status:** ${plan.isComplete ? 'Complete' : 'In Progress'}\n\n`;
+
+  for (let i = 0; i < plan.tests.length; i++) {
+    const test = plan.tests[i];
+    content += `## Test ${i + 1}: ${test.scenario}\n\n`;
+    content += `**Priority:** ${test.priority}\n`;
+    content += `**Status:** ${test.status}\n`;
+    if (test.result) {
+      content += `**Result:** ${test.result}\n`;
+    }
+    content += '\n';
+
+    if (test.startUrl) {
+      content += `**Start URL:** ${test.startUrl}\n\n`;
+    }
+
+    if (test.plannedSteps.length > 0) {
+      content += '**Planned Steps:**\n';
+      for (const step of test.plannedSteps) {
+        content += `- ${step}\n`;
+      }
+      content += '\n';
+    }
+
+    if (test.expected.length > 0) {
+      content += '**Expected Outcomes:**\n';
+      for (const expectation of test.expected) {
+        content += `- ${expectation}\n`;
+      }
+      content += '\n';
+    }
+
+    if (!options?.skipSteps && Object.keys(test.steps).length > 0) {
+      content += '**Steps:**\n';
+      for (const step of Object.values(test.steps)) {
+        content += `- ${step.text}\n`;
+      }
+      content += '\n';
+    }
+
+    if (Object.keys(test.notes).length > 0) {
+      content += '**Notes:**\n';
+      for (const note of test.getPrintableNotes()) {
+        content += `${note}\n`;
+      }
+      content += '\n';
+    }
+
+    content += '---\n\n';
+  }
+
+  return content;
+}

package/src/utils/throttle.ts

@@ -0,0 +1,18 @@
+const DEFAULT_INTERVAL_SECONDS = 30;
+
+const lastExecutionByKey = new Map<string, number>();
+
+export async function throttle<T>(fn: () => Promise<T> | T, intervalSeconds = DEFAULT_INTERVAL_SECONDS): Promise<T | undefined> {
+  const key = fn.toString();
+  const now = Date.now();
+  const lastExecution = lastExecutionByKey.get(key);
+  if (lastExecution !== undefined && now - lastExecution < intervalSeconds * 1000) {
+    return undefined;
+  }
+  lastExecutionByKey.set(key, now);
+  return await fn();
+}
+
+export function __clearThrottleCacheForTests(): void {
+  lastExecutionByKey.clear();
+}

package/src/utils/unique-names.ts

@@ -0,0 +1,14 @@
+import { adjectives, animals, colors, uniqueNamesGenerator } from 'unique-names-generator';
+
+const nameConfig = {
+  dictionaries: [adjectives, adjectives, colors],
+  separator: '',
+  length: 3,
+  style: 'capital',
+};
+
+export function uniqSessionName(): string {
+  const name = uniqueNamesGenerator(nameConfig);
+  const randomNum = Math.floor(Math.random() * 999);
+  return `${name}${randomNum}`;
+}

package/src/utils/url-matcher.ts

@@ -0,0 +1,45 @@
+import micromatch from 'micromatch';
+
+export function matchesUrl(pattern: string, path: string): boolean {
+  if (pattern === '*') return true;
+  const norm = (s: string) => s?.replace(/\/+$/, '').toLowerCase();
+  if (norm(pattern) === norm(path)) return true;
+
+  if (pattern.endsWith('/*')) {
+    const base = pattern.slice(0, -2).replace(/\/+$/, '');
+    const normPath = path.replace(/\/+$/, '');
+    if (normPath === base || path.startsWith(`${base}/`)) return true;
+  }
+
+  if (pattern.startsWith('^')) {
+    try {
+      return new RegExp(pattern.slice(1)).test(path);
+    } catch {
+      return false;
+    }
+  }
+
+  if (pattern.startsWith('~') && pattern.endsWith('~') && pattern.length > 2) {
+    try {
+      return new RegExp(pattern.slice(1, -1)).test(path);
+    } catch {
+      return false;
+    }
+  }
+
+  try {
+    return micromatch.isMatch(path, pattern);
+  } catch {
+    return false;
+  }
+}
+
+export function extractStatePath(url: string): string {
+  if (url.startsWith('/')) return url;
+  try {
+    const urlObj = new URL(url);
+    return urlObj.pathname + urlObj.hash;
+  } catch {
+    return url;
+  }
+}