explorbot 0.0.1 → 0.1.0

package/src/index.tsx

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { addKnowledgeCommand } from './commands/add-knowledge.js';
+import { cleanCommand } from './commands/clean.js';
+import { exploreCommand } from './commands/explore.js';
+import { initCommand } from './commands/init.js';
+
+const program = new Command();
+
+program
+  .name('explorbot')
+  .description('AI-powered web exploration tool')
+  .option('-f, --from <url>', 'Start exploration from a specific URL')
+  .option('-v, --verbose', 'Enable verbose logging')
+  .option('--debug', 'Enable debug logging (same as --verbose)')
+  .option('-c, --config <path>', 'Path to configuration file')
+  .option('-p, --path <path>', 'Working directory path')
+  .helpOption('-h, --help', 'Show this help message');
+
+program
+  .command('clean')
+  .description('Clean up artifacts or experience folders')
+  .option('-t, --type <type>', 'Type of cleanup (artifacts|experience|all)', 'artifacts')
+  .option('-p, --path <path>', 'Custom path to clean')
+  .action(async (options, command) => {
+    const globalOptions = command.parent.opts();
+    const allOptions = { ...globalOptions, ...options };
+    await cleanCommand(allOptions);
+  });
+
+program
+  .command('init')
+  .description('Initialize a new project with configuration')
+  .option('-c, --config-path <path>', 'Path for the config file', './explorbot.config.js')
+  .option('-f, --force', 'Overwrite existing config file', false)
+  .option('-p, --path <path>', 'Working directory for initialization')
+  .action(async (options, command) => {
+    const globalOptions = command.parent.opts();
+    const allOptions = { ...globalOptions, ...options };
+    await initCommand(allOptions);
+  });
+
+program
+  .command('add-knowledge')
+  .alias('learn')
+  .description('Add knowledge for specific URLs')
+  .option('-p, --path <path>', 'Knowledge directory path')
+  .action(async (options) => {
+    await addKnowledgeCommand(options);
+  });
+
+program.parse();
+
+const options = program.opts();
+const command = program.args[0];
+
+if (command === 'clean' || command === 'init' || command === 'add-knowledge' || command === 'learn') {
+  // These commands are handled by their respective actions
+} else {
+  // Default to explore command
+  exploreCommand(options);
+}

package/src/knowledge-tracker.ts

@@ -0,0 +1,230 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import matter from 'gray-matter';
+import { ActionResult } from './action-result.js';
+import { ConfigParser } from './config.js';
+import { getCliName } from './utils/cli-name.ts';
+import { createDebug } from './utils/logger.js';
+
+const debugLog = createDebug('explorbot:knowledge-tracker');
+
+interface Knowledge {
+  filePath: string;
+  url: string;
+  content: string;
+  [key: string]: any;
+}
+
+export class KnowledgeTracker {
+  private knowledgeDir: string;
+  private knowledgeFiles: Knowledge[] = [];
+  private isLoaded = false;
+
+  constructor() {
+    const configParser = ConfigParser.getInstance();
+    const config = configParser.getConfig();
+    const configPath = configParser.getConfigPath();
+
+    if (configPath) {
+      const projectRoot = dirname(configPath);
+      this.knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
+    } else {
+      this.knowledgeDir = config.dirs?.knowledge || 'knowledge';
+    }
+
+    if (!existsSync(this.knowledgeDir)) {
+      mkdirSync(this.knowledgeDir, { recursive: true });
+    }
+  }
+
+  private loadKnowledgeFiles(): void {
+    if (this.isLoaded) return;
+
+    this.knowledgeFiles = [];
+
+    if (!existsSync(this.knowledgeDir)) {
+      return;
+    }
+
+    const files = readdirSync(this.knowledgeDir)
+      .filter((file) => file.endsWith('.md'))
+      .map((file) => join(this.knowledgeDir, file));
+
+    for (const filePath of files) {
+      try {
+        const fileContent = readFileSync(filePath, 'utf8');
+        const parsed = matter(fileContent);
+        const urlPattern = parsed.data.url || parsed.data.path || '*';
+
+        this.knowledgeFiles.push({
+          filePath,
+          url: urlPattern,
+          content: this.interpolateVars(parsed.content),
+          ...parsed.data,
+        });
+      } catch (error) {
+        // Skip invalid files
+      }
+    }
+
+    this.isLoaded = true;
+  }
+
+  getRelevantKnowledge(state: ActionResult): Knowledge[] {
+    this.loadKnowledgeFiles();
+
+    return this.knowledgeFiles.filter((knowledge) => {
+      return state.isMatchedBy(knowledge);
+    });
+  }
+
+  addKnowledge(urlPattern: string, description: string): { filename: string; filePath: string; isNewFile: boolean } {
+    const configParser = ConfigParser.getInstance();
+    const config = configParser.getConfig();
+    const configPath = configParser.getConfigPath();
+
+    if (!configPath) {
+      throw new Error(`No explorbot configuration found. Please run "${getCliName()} init" first.`);
+    }
+
+    const projectRoot = dirname(configPath);
+    const knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
+
+    if (!existsSync(knowledgeDir)) {
+      mkdirSync(knowledgeDir, { recursive: true });
+    }
+
+    const normalizedUrl = this.normalizeUrl(urlPattern);
+    const filename = this.generateFilename(normalizedUrl);
+    const filePath = join(knowledgeDir, filename);
+
+    const isNewFile = !existsSync(filePath);
+
+    if (isNewFile) {
+      const frontmatter = {
+        url: normalizedUrl,
+        title: '', // Can be populated later
+      };
+      const fileContent = matter.stringify(description, frontmatter);
+      writeFileSync(filePath, fileContent, 'utf8');
+    } else {
+      const existingContent = readFileSync(filePath, 'utf8');
+      const parsed = matter(existingContent);
+
+      // Update URL in frontmatter if different
+      const frontmatter = { ...parsed.data, url: normalizedUrl };
+      const existingDescription = parsed.content.trim();
+
+      // Append new knowledge with separator
+      let newContent;
+      if (existingDescription) {
+        newContent = `${existingDescription}\n\n---\n\n${description}`;
+      } else {
+        newContent = description;
+      }
+
+      const fileContent = matter.stringify(newContent, frontmatter);
+      writeFileSync(filePath, fileContent, 'utf8');
+    }
+
+    return { filename, filePath, isNewFile };
+  }
+
+  private interpolateVars(content: string): string {
+    return content.replace(/\$\{([^}]+)\}/g, (match, expr: string) => {
+      const dotIndex = expr.indexOf('.');
+      if (dotIndex === -1) return match;
+
+      const namespace = expr.slice(0, dotIndex);
+      const key = expr.slice(dotIndex + 1);
+
+      if (namespace === 'env') return process.env[key] ?? '';
+
+      if (namespace === 'config') {
+        const config = ConfigParser.getInstance().getConfig();
+        const value = key.split('.').reduce((obj: any, k) => obj?.[k], config);
+        if (value !== undefined && typeof value !== 'object') return String(value);
+        return '';
+      }
+
+      return match;
+    });
+  }
+
+  private generateFilename(url: string): string {
+    let filename = url
+      .replace(/https?:\/\//g, '')
+      .replace(/[^a-zA-Z0-9_]/g, '_')
+      .replace(/_+/g, '_')
+      .replace(/^_|_$/g, '')
+      .toLowerCase();
+
+    if (!filename || filename === '*') {
+      filename = 'general';
+    }
+
+    if (!filename.endsWith('.md')) {
+      filename += '.md';
+    }
+
+    return filename;
+  }
+
+  getExistingUrls(): string[] {
+    this.loadKnowledgeFiles();
+
+    return this.knowledgeFiles.map((knowledge) => knowledge.url).filter((url) => url && url !== '*');
+  }
+
+  getKnowledgeForUrl(urlPattern: string): string[] {
+    this.loadKnowledgeFiles();
+    const normalizedUrl = this.normalizeUrl(urlPattern);
+
+    return this.knowledgeFiles.filter((knowledge) => knowledge.url === normalizedUrl).map((knowledge) => knowledge.content.trim());
+  }
+
+  listAllKnowledge(): Array<{ url: string; firstLine: string; filePath: string }> {
+    this.loadKnowledgeFiles();
+
+    return this.knowledgeFiles.map((knowledge) => {
+      const content = knowledge.content.trim();
+      const firstLine = content.split('\n')[0]?.trim() || '';
+      return {
+        url: knowledge.url,
+        firstLine,
+        filePath: knowledge.filePath,
+      };
+    });
+  }
+
+  getMatchingKnowledge(url: string): Knowledge[] {
+    this.loadKnowledgeFiles();
+    const state = new ActionResult({ url });
+    return this.getRelevantKnowledge(state);
+  }
+
+  normalizeUrl(url: string): string {
+    const trimmed = url.trim();
+
+    if (!trimmed) {
+      throw new Error('URL pattern cannot be empty');
+    }
+
+    return trimmed;
+  }
+
+  getStateParameters(state: ActionResult, keys: string[]) {
+    const relevantKnowledge = this.getRelevantKnowledge(state);
+    const result: Record<string, any> = {};
+
+    for (const key of keys) {
+      for (const knowledge of relevantKnowledge) {
+        if (knowledge[key] !== undefined && result[key] === undefined) {
+          result[key] = knowledge[key];
+        }
+      }
+    }
+
+    return result;
+  }
+}

package/src/observability.ts

@@ -0,0 +1,150 @@
+import { randomBytes } from 'node:crypto';
+import { type Span, context, trace } from '@opentelemetry/api';
+
+type TelemetryMetadata = Record<string, unknown>;
+
+type TelemetryState = {
+  metadata: TelemetryMetadata;
+  traceId: string;
+  updateParent: boolean;
+  name: string;
+  span?: Span;
+};
+
+let current: TelemetryState | null = null;
+let depth = 0;
+
+export const Observability = {
+  async run<T>(name: string, metadata: TelemetryMetadata, fn: () => Promise<T>): Promise<T> {
+    const started = Observability.startTrace(name, metadata);
+
+    try {
+      if (!started) {
+        const parentSpan = current?.span;
+        if (!parentSpan || !current) return await fn();
+
+        const tracer = trace.getTracer('ai');
+        const childSpan = tracer.startSpan(name, undefined, trace.setSpan(context.active(), parentSpan));
+        const savedSpan = current.span;
+        const savedName = current.name;
+        current.span = childSpan;
+        current.name = name;
+        return await context.with(trace.setSpan(context.active(), childSpan), async () => {
+          try {
+            return await fn();
+          } finally {
+            childSpan.end();
+            current!.span = savedSpan;
+            current!.name = savedName;
+          }
+        });
+      }
+
+      const tracer = trace.getTracer('ai');
+      const spanContext = {
+        traceId: current?.traceId || randomBytes(16).toString('hex'),
+        spanId: randomBytes(8).toString('hex'),
+        traceFlags: 1,
+      };
+      const rootContext = trace.setSpanContext(context.active(), spanContext);
+
+      const initSpan = tracer.startSpan(name, undefined, rootContext);
+      initSpan.setAttribute('langfuse.trace.name', name);
+      initSpan.setAttribute('langfuse.trace.id', current?.traceId || '');
+      if (current?.metadata?.sessionId) {
+        initSpan.setAttribute('langfuse.trace.session_id', String(current.metadata.sessionId));
+      }
+      if (current?.metadata?.userId) {
+        initSpan.setAttribute('langfuse.trace.user_id', String(current.metadata.userId));
+      }
+      if (current?.metadata?.tags && Array.isArray(current.metadata.tags)) {
+        initSpan.setAttribute('langfuse.trace.tags', current.metadata.tags);
+      }
+      if (current?.metadata?.input) {
+        initSpan.setAttribute('langfuse.trace.input', JSON.stringify(current.metadata.input));
+      }
+      initSpan.end();
+
+      const span = tracer.startSpan(name, undefined, rootContext);
+      current.span = span;
+
+      return await context.with(trace.setSpan(rootContext, span), async () => {
+        try {
+          return await fn();
+        } finally {
+          span.end();
+          current.span = undefined;
+        }
+      });
+    } finally {
+      Observability.endTrace(started);
+    }
+  },
+
+  startTrace(name: string, metadata: TelemetryMetadata) {
+    if (current) {
+      depth += 1;
+      return false;
+    }
+
+    const langfuseTraceId = metadata.langfuseTraceId || randomBytes(16).toString('hex');
+    current = {
+      metadata: {
+        ...metadata,
+        langfuseTraceId,
+      },
+      traceId: langfuseTraceId,
+      updateParent: true,
+      name,
+    };
+    depth = 1;
+    return true;
+  },
+
+  endTrace(started: boolean) {
+    if (!current) {
+      return;
+    }
+
+    if (!started) {
+      depth -= 1;
+      return;
+    }
+
+    depth -= 1;
+    if (depth <= 0) {
+      current = null;
+      depth = 0;
+    }
+  },
+
+  getTelemetry() {
+    if (!current) {
+      return undefined;
+    }
+
+    const telemetry = {
+      isEnabled: true,
+      functionId: current.name,
+      metadata: {
+        ...current.metadata,
+        langfuseTraceId: current.traceId,
+        langfuseUpdateParent: current.updateParent,
+      },
+    };
+
+    if (current.updateParent) {
+      current.updateParent = false;
+    }
+
+    return telemetry;
+  },
+
+  isTracing() {
+    return Boolean(current);
+  },
+
+  getSpan() {
+    return current?.span;
+  },
+};

package/src/reporter.ts

@@ -0,0 +1,224 @@
+import { join } from 'node:path';
+import { Client } from '@testomatio/reporter';
+import type { Step } from '@testomatio/reporter/types/types.js';
+import { ConfigParser, outputPath } from './config.js';
+import type { ReporterConfig } from './config.js';
+import { Test } from './test-plan.js';
+import { createDebug } from './utils/logger.js';
+
+export type ReporterMeta = Record<string, string | undefined>;
+
+const debugLog = createDebug('explorbot:reporter');
+
+export interface ReporterStep {
+  title: string;
+  status: 'passed' | 'failed';
+  code: string[];
+  discovery?: string;
+}
+
+export class Reporter {
+  private client: Client;
+  private isRunStarted = false;
+  private reporterEnabled: boolean;
+
+  constructor(config?: ReporterConfig) {
+    this.reporterEnabled = Reporter.resolveEnabled(config);
+
+    if (this.reporterEnabled && (!process.env.TESTOMATIO || config?.html)) {
+      this.configureHtmlPipe();
+    }
+
+    this.client = new Client({ apiKey: process.env.TESTOMATIO || '' });
+    const pipe = process.env.TESTOMATIO && config?.html ? 'both' : process.env.TESTOMATIO ? 'testomatio' : 'html';
+    debugLog('Reporter initialized', { enabled: this.reporterEnabled, pipe });
+  }
+
+  static resolveEnabled(config?: ReporterConfig): boolean {
+    if (config?.enabled === true) return true;
+    if (config?.enabled === false) return false;
+    return Boolean(process.env.TESTOMATIO);
+  }
+
+  private configureHtmlPipe(): void {
+    process.env.TESTOMATIO_HTML_REPORT_SAVE = '1';
+    process.env.TESTOMATIO_HTML_REPORT_FOLDER = outputPath('reports');
+    debugLog('HTML report pipe configured', { folder: process.env.TESTOMATIO_HTML_REPORT_FOLDER });
+  }
+
+  async startRun(): Promise<void> {
+    if (this.isRunStarted) {
+      return;
+    }
+
+    if (!this.reporterEnabled) {
+      return;
+    }
+
+    try {
+      const timeoutMs = Number(process.env.TESTOMATIO_TIMEOUT_MS || '15000');
+      const timeoutPromise = new Promise<'timeout'>((resolve) => setTimeout(() => resolve('timeout'), timeoutMs));
+
+      const result = await Promise.race([this.client.createRun().then(() => 'success' as const), timeoutPromise]);
+
+      if (result === 'timeout') {
+        debugLog('Reporter run creation timed out');
+        return;
+      }
+
+      if (process.env.TESTOMATIO && !this.client.runId) {
+        debugLog('Testomat.io run creation failed - no runId received');
+        return;
+      }
+
+      this.isRunStarted = true;
+      debugLog('Reporter run started', { runId: this.client.runId || 'html-only' });
+    } catch (error) {
+      debugLog('Failed to start reporter:', error);
+      return;
+    }
+
+    process.env.TESTOMATIO_STACK_PASSED = 'true';
+    process.env.TESTOMATIO_STEPS_PASSED = 'true';
+  }
+
+  async reportTestStart(test: Test): Promise<void> {
+    await this.startRun();
+  }
+
+  protected combineStepsAndNotes(test: Test, lastScreenshotFile?: string): Step[] {
+    const noteEntries = Object.entries(test.notes)
+      .map(([timestampKey, note]) => ({
+        startTime: note.startTime,
+        message: note.message,
+        status: note.status,
+        screenshot: note.screenshot,
+      }))
+      .sort((a, b) => a.startTime - b.startTime);
+
+    const stepEntries = Object.entries(test.steps)
+      .map(([timestampKey, stepData]) => ({
+        noteStartTime: stepData.noteStartTime,
+        text: stepData.text,
+        duration: stepData.duration,
+        error: stepData.error,
+        log: stepData.log,
+      }))
+      .filter((step) => step.noteStartTime !== undefined);
+
+    const steps: Step[] = [];
+
+    for (const noteEntry of noteEntries) {
+      const noteSteps = stepEntries
+        .filter((step) => step.noteStartTime === noteEntry.startTime)
+        .map((entry) => ({
+          category: 'framework',
+          title: entry.text,
+          duration: entry.duration ?? 0,
+          ...Object.fromEntries(Object.entries(entry).filter(([k]) => k !== 'noteStartTime' && k !== 'text' && k !== 'duration')),
+        }));
+
+      const step: Step = {
+        category: 'user',
+        title: noteEntry.message,
+        duration: 0,
+        status: noteEntry.status || 'none',
+        steps: noteSteps.length > 0 ? noteSteps : undefined,
+      };
+      if (noteEntry.screenshot) {
+        step.artifacts = [outputPath('states', noteEntry.screenshot)];
+      }
+      steps.push(step);
+    }
+
+    if (lastScreenshotFile && steps.length > 0) {
+      const lastStep = steps[steps.length - 1];
+      const screenshotPath = outputPath('states', lastScreenshotFile);
+      if (lastStep.artifacts) {
+        lastStep.artifacts.push(screenshotPath);
+      } else {
+        lastStep.artifacts = [screenshotPath];
+      }
+    }
+
+    return steps;
+  }
+
+  async reportTest(test: Test, meta?: ReporterMeta): Promise<void> {
+    await this.startRun();
+
+    if (!this.isRunStarted) {
+      return;
+    }
+
+    try {
+      let status = null;
+      if (test.isSuccessful) {
+        status = 'passed';
+      } else if (test.isSkipped) {
+        status = 'skipped';
+      } else if (test.hasFailed) {
+        status = 'failed';
+      }
+
+      const screenshotFile = meta?.screenshotFile;
+      if (meta) {
+        meta.screenshotFile = undefined;
+        meta = Object.fromEntries(Object.entries(meta).filter(([, v]) => v));
+      }
+
+      const steps = this.combineStepsAndNotes(test, screenshotFile);
+
+      const testData = {
+        rid: test.id,
+        title: test.scenario,
+        suite_title: test.plan?.title || 'Auto-Exploratory Testing',
+        file: '<note>',
+        description: test.description,
+        code: test.generatedCode || '',
+        steps,
+        logs: Object.values(test.steps)
+          .map((stepData) => stepData.text)
+          .join('\n'),
+        files: Object.values(test.artifacts) || [],
+        message: test.summary || this.extractLastNoteMessage(test) || '',
+        meta,
+      };
+
+      debugLog(testData);
+
+      await this.client.addTestRun(status, testData);
+      debugLog(`Test reported: ${test.scenario} - ${status}`);
+    } catch (error) {
+      debugLog('Failed to report test:', error);
+    }
+  }
+
+  async finishRun(): Promise<void> {
+    if (!this.isRunStarted) {
+      return;
+    }
+
+    try {
+      await this.client.updateRunStatus('finished');
+      this.isRunStarted = false;
+      debugLog('Testomat.io run finished');
+    } catch (error) {
+      debugLog('Failed to finish Testomat.io run:', error);
+    }
+  }
+
+  isEnabled(): boolean {
+    return this.isRunStarted;
+  }
+
+  private extractLastNoteMessage(test: Test): string {
+    const notes = Object.values(test.notes);
+    if (notes.length === 0) return '';
+    return notes[notes.length - 1].message;
+  }
+
+  async reportSteps(test: Test, steps: ReporterStep[]): Promise<void> {
+    return;
+  }
+}