@bugmole/cli 0.4.0

package/src/runtime/llm-example.ts

@@ -0,0 +1,105 @@
+/**
+ * Example: Using the unified LLM interface
+ *
+ * This demonstrates how to use the unified LLM interface that works
+ * with OpenAI, Anthropic, Cursor LLM, or Ollama - all with the same API.
+ */
+
+import { llm, llmStructured } from "./llm.js";
+
+/**
+ * Example 1: Simple text completion (works with any provider)
+ *
+ * The provider is automatically selected from config (bugmole.config.yaml)
+ */
+export async function exampleSimple() {
+  // Works with OpenAI, Anthropic, Cursor, or Ollama
+  // Just change LLM_PROVIDER in your config!
+  const answer = await llm("Analyze the error handling patterns in this codebase");
+  console.log(answer);
+  return answer;
+}
+
+/**
+ * Example 2: Override provider
+ */
+export async function exampleOverrideProvider() {
+  // Force a specific provider
+  const answer = await llm(
+    "Your prompt here",
+    { provider: "openai" }, // or 'anthropic', 'cursor', 'ollama'
+  );
+  return answer;
+}
+
+/**
+ * Example 3: Structured response
+ */
+export async function exampleStructured() {
+  const response = await llmStructured("Review test failures and propose fixes");
+
+  console.log("Provider:", response.provider);
+  console.log("Model:", response.model);
+  console.log("Text:", response.text);
+  console.log("Metadata:", response.metadata);
+
+  return response;
+}
+
+/**
+ * Example 4: Using in a workflow
+ */
+export async function exampleWorkflow() {
+  // Step 1: Analyze (uses provider from config)
+  const analysis = await llm("Analyze the current test coverage");
+
+  // Step 2: Generate plan (same provider, or override)
+  const plan = await llm(
+    `Based on this analysis, create a test plan:\n\n${analysis}`,
+    { provider: "cursor" }, // Use Cursor for code-aware planning
+  );
+
+  return { analysis, plan };
+}
+
+/**
+ * Example 5: Error handling
+ */
+export async function exampleWithErrorHandling() {
+  try {
+    const answer = await llm("Your task here");
+    return answer;
+  } catch (error: any) {
+    if (error.message?.includes("API key")) {
+      console.error("Missing API key. Set LLM_API_KEY in .env");
+    } else if (error.message?.includes("timeout")) {
+      console.error("Request timed out. Try increasing timeout.");
+    } else {
+      console.error("Error:", error.message);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Example 6: Switching providers dynamically
+ */
+export async function exampleSwitchProviders() {
+  const providers: Array<"openai" | "anthropic" | "cursor" | "ollama"> = [
+    "openai",
+    "anthropic",
+    "cursor",
+  ];
+
+  const results = await Promise.all(
+    providers.map((provider) =>
+      llm("What is 2+2?", { provider }).then((text) => ({
+        provider,
+        text,
+      })),
+    ),
+  );
+
+  console.log("Results from different providers:", results);
+  return results;
+}

package/src/runtime/llm.ts

@@ -0,0 +1,527 @@
+/**
+ * Unified LLM Interface
+ *
+ * Provides a single, consistent interface for calling any LLM provider:
+ * - OpenAI
+ * - Anthropic
+ * - Cursor LLM (via CURSOR_DRIVER)
+ * - Ollama
+ *
+ * Usage:
+ *   import { llm } from './llm.js';
+ *   const response = await llm('Your prompt here');
+ */
+
+import fs from "node:fs";
+import { preferExisting } from "./legacy-names.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import dotenv from "dotenv";
+import YAML from "yaml";
+import { cursorLLM, cursorLLMStructured } from "./cursor-llm.js";
+import type { CursorDriverResponse } from "./cursor-driver.js";
+
+/**
+ * Type definitions for API responses
+ */
+interface OpenAIResponse {
+  choices: Array<{
+    message: {
+      content: string;
+    };
+  }>;
+  model?: string;
+  usage?: { prompt_tokens?: number; completion_tokens?: number };
+}
+
+interface AnthropicResponse {
+  content: Array<{
+    text: string;
+  }>;
+  model?: string;
+  usage?: { input_tokens?: number; output_tokens?: number; cache_read_input_tokens?: number };
+}
+
+interface OllamaResponse {
+  response: string;
+  prompt_eval_count?: number;
+  eval_count?: number;
+}
+
+/** Token counts a provider reported for one call, when it reports them. */
+export type ModelUsage = { provider: string; model: string; inputTokens?: number; outputTokens?: number };
+export type ModelReply = { text: string; usage: ModelUsage };
+
+// Cache config to avoid reloading
+let cachedConfig: any = null;
+
+/**
+ * Loads and caches the Bugmole MCP configuration
+ */
+function loadConfig(configPath: string = preferExisting("bugmole.config.yaml", "valkyrie.config.yaml")): any {
+  if (cachedConfig) {
+    return cachedConfig;
+  }
+
+  const scriptPath = fileURLToPath(import.meta.url);
+  const scriptDir = path.dirname(scriptPath);
+  const projectRoot = path.resolve(scriptDir, "../..");
+
+  const originalCwd = process.cwd();
+  process.chdir(projectRoot);
+
+  try {
+    dotenv.config({ quiet: true });
+
+    const fullConfigPath = path.join(projectRoot, configPath);
+    if (!fs.existsSync(fullConfigPath)) {
+      throw new Error(`Config file not found: ${fullConfigPath}`);
+    }
+
+    const raw = fs.readFileSync(fullConfigPath, "utf-8");
+    const parsed = YAML.parse(raw);
+
+    cachedConfig = interpolateEnv(parsed);
+    return cachedConfig;
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+// tiny ${ENV} interpolator for yaml configs
+function interpolateEnv(obj: any): any {
+  if (typeof obj === "string") {
+    return obj.replace(/\$\{([A-Z0-9_]+)(?::-([^}]+))?\}/g, (_, k, defaultValue) => {
+      const envValue = process.env[k];
+      if (envValue !== undefined && envValue !== "") {
+        return envValue;
+      }
+      return defaultValue !== undefined ? defaultValue : "";
+    });
+  }
+  if (Array.isArray(obj)) return obj.map(interpolateEnv);
+  if (obj && typeof obj === "object") {
+    const out: any = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = interpolateEnv(v);
+    return out;
+  }
+  return obj;
+}
+
+/**
+ * LLM Provider types
+ */
+export type LLMProvider = "openai" | "anthropic" | "cursor" | "ollama";
+
+/**
+ * Unified LLM options
+ */
+export interface LLMOptions {
+  /**
+   * Override provider (default: from config)
+   */
+  provider?: LLMProvider;
+
+  /**
+   * Override model (default: from config)
+   */
+  model?: string;
+
+  /**
+   * Custom config file path (default: bugmole.config.yaml)
+   */
+  configPath?: string;
+
+  /**
+   * Timeout in milliseconds (default: 300000 = 5 minutes)
+   */
+  timeout?: number;
+
+  /**
+   * Request ID for tracking
+   */
+  requestId?: string;
+
+  /**
+   * Custom instructions (provider-specific)
+   */
+  customInstructions?: string;
+
+  /**
+   * Project directory (for Cursor provider)
+   */
+  projectDirectory?: string;
+}
+
+/**
+ * Unified LLM response
+ */
+export interface LLMResponse {
+  /**
+   * The text response from the LLM
+   */
+  text: string;
+
+  /**
+   * Provider used
+   */
+  provider: LLMProvider;
+
+  /**
+   * Model used
+   */
+  model: string;
+
+  /**
+   * Additional metadata (provider-specific)
+   */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Unified LLM interface - works with any provider
+ *
+ * Automatically selects the provider based on config:
+ * - If provider is 'cursor', uses CURSOR_DRIVER
+ * - Otherwise, uses standard HTTP API calls
+ *
+ * @param prompt - The prompt to send
+ * @param options - Optional overrides
+ * @returns The text response
+ *
+ * @example
+ * ```typescript
+ * import { llm } from './llm.js';
+ *
+ * // Works with any provider configured in bugmole.config.yaml
+ * const answer = await llm('Analyze the error handling in this codebase');
+ * console.log(answer);
+ * ```
+ */
+export async function llm(prompt: string, options: LLMOptions = {}): Promise<string> {
+  const cfg = loadConfig(options.configPath);
+  const provider = (options.provider || cfg.llm?.provider || "cursor").toLowerCase() as LLMProvider;
+  const model = options.model || cfg.llm?.model || "gpt-4o-mini";
+
+  // Cursor provider uses CURSOR_DRIVER
+  if (provider === "cursor") {
+    return cursorLLM(prompt, {
+      configPath: options.configPath,
+      timeout: options.timeout,
+      requestId: options.requestId,
+      customInstructions: options.customInstructions,
+      projectDirectory: options.projectDirectory,
+    });
+  }
+
+  // Other providers use HTTP APIs
+  return callLLMAPI(prompt, {
+    provider,
+    model,
+    apiKey: cfg.llm?.api_key,
+    baseUrl: cfg.llm?.base_url,
+    timeout: options.timeout,
+  });
+}
+
+/**
+ * Unified LLM interface with structured response
+ *
+ * @param prompt - The prompt to send
+ * @param options - Optional overrides
+ * @returns Structured response
+ */
+export async function llmStructured(
+  prompt: string,
+  options: LLMOptions = {},
+): Promise<LLMResponse> {
+  const cfg = loadConfig(options.configPath);
+  const provider = (options.provider || cfg.llm?.provider || "cursor").toLowerCase() as LLMProvider;
+  const model = options.model || cfg.llm?.model || "gpt-4o-mini";
+
+  // Cursor provider uses CURSOR_DRIVER
+  if (provider === "cursor") {
+    const response = await cursorLLMStructured(prompt, {
+      configPath: options.configPath,
+      timeout: options.timeout,
+      requestId: options.requestId,
+      customInstructions: options.customInstructions,
+      projectDirectory: options.projectDirectory,
+    });
+
+    if (!response.success || !response.payload) {
+      throw new Error(response.error || "LLM call failed");
+    }
+
+    return {
+      text: response.payload.answer_markdown || response.payload.summary,
+      provider: "cursor",
+      model: "cursor",
+      metadata: {
+        commitId: response.commitId,
+        actions: response.payload.actions,
+        artifacts: response.payload.artifacts,
+      },
+    };
+  }
+
+  // Other providers use HTTP APIs
+  const text = await callLLMAPI(prompt, {
+    provider,
+    model,
+    apiKey: cfg.llm?.api_key,
+    baseUrl: cfg.llm?.base_url,
+    timeout: options.timeout,
+  });
+
+  return {
+    text,
+    provider,
+    model,
+  };
+}
+
+/**
+ * Calls a model with explicit settings (e.g. a project's own `llm` config)
+ * instead of the package-level config the helpers above read.
+ */
+export async function callModel(
+  prompt: string,
+  options: { provider: string; model: string; apiKey?: string; baseUrl?: string; timeout?: number },
+): Promise<string> {
+  return (await callModelWithUsage(prompt, options)).text;
+}
+
+/** callModel, plus the token counts the provider reported. */
+export function callModelWithUsage(
+  prompt: string,
+  options: { provider: string; model: string; apiKey?: string; baseUrl?: string; timeout?: number; maxTokens?: number },
+): Promise<ModelReply> {
+  return callLLMAPIWithUsage(prompt, { ...options, provider: options.provider.toLowerCase() as LLMProvider });
+}
+
+/**
+ * Calls standard LLM APIs (OpenAI, Anthropic, Ollama)
+ */
+async function callLLMAPI(
+  prompt: string,
+  options: {
+    provider: LLMProvider;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+  },
+): Promise<string> {
+  return (await callLLMAPIWithUsage(prompt, options)).text;
+}
+
+async function callLLMAPIWithUsage(
+  prompt: string,
+  options: {
+    provider: LLMProvider;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxTokens?: number;
+  },
+): Promise<ModelReply> {
+  const { provider, model, apiKey, baseUrl, timeout = 300000, maxTokens } = options;
+
+  if (!apiKey && provider !== "ollama") {
+    throw new Error(`API key required for provider: ${provider}`);
+  }
+
+  // OpenAI
+  if (provider === "openai") {
+    return callOpenAI(prompt, { model, apiKey: apiKey!, baseUrl, timeout, maxTokens });
+  }
+
+  // Anthropic
+  if (provider === "anthropic") {
+    return callAnthropic(prompt, { model, apiKey: apiKey!, baseUrl, timeout, maxTokens });
+  }
+
+  // Ollama
+  if (provider === "ollama") {
+    return callOllama(prompt, {
+      model,
+      baseUrl: baseUrl || "http://localhost:11434",
+      timeout,
+    });
+  }
+
+  throw new Error(`Unsupported provider: ${provider}`);
+}
+
+/**
+ * Calls OpenAI API
+ */
+async function callOpenAI(
+  prompt: string,
+  options: { model: string; apiKey: string; baseUrl?: string; timeout: number; maxTokens?: number },
+): Promise<ModelReply> {
+  const { model, apiKey, baseUrl, timeout, maxTokens } = options;
+  const url = baseUrl || "https://api.openai.com/v1/chat/completions";
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: prompt }],
+        temperature: 0.7,
+        ...(maxTokens ? { max_tokens: maxTokens } : {}),
+      }),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OpenAI API error: ${response.status} ${error}`);
+    }
+
+    const data = (await response.json()) as OpenAIResponse;
+    return {
+      text: data.choices[0]?.message?.content || "",
+      usage: {
+        provider: "openai",
+        model: data.model ?? model,
+        inputTokens: data.usage?.prompt_tokens,
+        outputTokens: data.usage?.completion_tokens,
+      },
+    };
+  } catch (error: any) {
+    clearTimeout(timeoutId);
+    if (error.name === "AbortError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Calls Anthropic API
+ */
+/** Accepts a gateway root ("https://gw.example.com") or a full messages URL. */
+export function anthropicMessagesUrl(baseUrl?: string): string {
+  if (!baseUrl) return "https://api.anthropic.com/v1/messages";
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  if (trimmed.endsWith("/messages")) return trimmed;
+  return trimmed.endsWith("/v1") ? `${trimmed}/messages` : `${trimmed}/v1/messages`;
+}
+
+async function callAnthropic(
+  prompt: string,
+  options: { model: string; apiKey: string; baseUrl?: string; timeout: number; maxTokens?: number },
+): Promise<ModelReply> {
+  const { model, apiKey, baseUrl, timeout, maxTokens } = options;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(anthropicMessagesUrl(baseUrl), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: maxTokens ?? 4096,
+        messages: [{ role: "user", content: prompt }],
+      }),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Anthropic API error: ${response.status} ${error}`);
+    }
+
+    const data = (await response.json()) as AnthropicResponse;
+    return {
+      text: data.content[0]?.text || "",
+      usage: {
+        provider: "anthropic",
+        model: data.model ?? model,
+        inputTokens: (data.usage?.input_tokens ?? 0) + (data.usage?.cache_read_input_tokens ?? 0) || undefined,
+        outputTokens: data.usage?.output_tokens,
+      },
+    };
+  } catch (error: any) {
+    clearTimeout(timeoutId);
+    if (error.name === "AbortError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Calls Ollama API
+ */
+async function callOllama(
+  prompt: string,
+  options: { model: string; baseUrl: string; timeout: number },
+): Promise<ModelReply> {
+  const { model, baseUrl, timeout } = options;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(`${baseUrl}/api/generate`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        prompt,
+        stream: false,
+      }),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Ollama API error: ${response.status} ${error}`);
+    }
+
+    const data = (await response.json()) as OllamaResponse;
+    return {
+      text: data.response || "",
+      usage: { provider: "ollama", model, inputTokens: data.prompt_eval_count, outputTokens: data.eval_count },
+    };
+  } catch (error: any) {
+    clearTimeout(timeoutId);
+    if (error.name === "AbortError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Reset the config cache (useful for testing or when config changes)
+ */
+export function resetLLMConfigCache(): void {
+  cachedConfig = null;
+}

package/src/runtime/local-browser.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { MAC_CHROME_PATH, headlessBrowserArgs, resolveHeadlessBrowserPath } from "./local-browser.js";
+
+const bundled = "/ms-playwright/chromium/chrome";
+
+test("an explicit BUGMOLE_BROWSER_PATH wins over every installed browser", async () => {
+  const browser = await resolveHeadlessBrowserPath({
+    env: { BUGMOLE_BROWSER_PATH: " /opt/chrome " },
+    exists: () => true,
+    playwrightChromiumPath: async () => bundled,
+  });
+  assert.equal(browser, "/opt/chrome");
+});
+
+test("keeps using macOS Google Chrome when it is installed", async () => {
+  const browser = await resolveHeadlessBrowserPath({
+    env: {},
+    exists: (candidate) => candidate === MAC_CHROME_PATH || candidate === bundled,
+    playwrightChromiumPath: async () => bundled,
+  });
+  assert.equal(browser, MAC_CHROME_PATH);
+});
+
+test("falls back to Playwright's bundled Chromium, as on a Linux worker", async () => {
+  const browser = await resolveHeadlessBrowserPath({
+    env: {},
+    exists: (candidate) => candidate === bundled,
+    playwrightChromiumPath: async () => bundled,
+  });
+  assert.equal(browser, bundled);
+});
+
+test("explains how to fix it when no browser is available", async () => {
+  await assert.rejects(
+    resolveHeadlessBrowserPath({ env: {}, exists: () => false, playwrightChromiumPath: async () => undefined }),
+    /BUGMOLE_BROWSER_PATH.*playwright install chromium/,
+  );
+});
+
+test("adds --no-sandbox only for root on Linux", () => {
+  assert.deepEqual(headlessBrowserArgs("linux", 0), ["--no-sandbox"]);
+  assert.deepEqual(headlessBrowserArgs("linux", 1000), []);
+  assert.deepEqual(headlessBrowserArgs("darwin", 0), []);
+});