@bugmole/cli 0.4.0

package/src/runtime/cursor-cli-driver.ts

@@ -0,0 +1,156 @@
+import { execFile, type ExecFileException } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import {
+  generateCursorDriverPrompt,
+  validateCommitPayload,
+  type CursorDriverOptions,
+  type CursorDriverResponse,
+} from "./cursor-driver.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Long-running stages (a full source exploration with screenshot capture)
+ * routinely outlive a short timeout: the agent gets SIGTERM'd mid-flight and
+ * the pipeline stalls with "cursor-agent run timed out" even though it was
+ * making progress. Investigation work therefore gets a much longer budget
+ * than a small code edit.
+ */
+export const DEFAULT_CURSOR_TIMEOUT_MS = 300_000;
+export const INVESTIGATION_CURSOR_TIMEOUT_MS = 1_800_000;
+
+export function resolveCursorTimeoutMs(
+  taskType?: string,
+  override?: number,
+  env: NodeJS.ProcessEnv = process.env,
+): number {
+  if (Number.isFinite(override) && (override as number) > 0) return override as number;
+  const configured = Number(env.BUGMOLE_CURSOR_TIMEOUT_MS);
+  if (Number.isFinite(configured) && configured > 0) return configured;
+  return taskType === "investigation" ? INVESTIGATION_CURSOR_TIMEOUT_MS : DEFAULT_CURSOR_TIMEOUT_MS;
+}
+
+export type CursorCliDriverOptions = CursorDriverOptions & {
+  /** @default "cursor-agent" */
+  command?: string;
+  /** @default 300000, or 1800000 for investigation tasks */
+  timeoutMs?: number;
+  /** Drives the default timeout when timeoutMs is not given. */
+  taskType?: string;
+  model?: string;
+  /** Workspace directory the agent should operate in (defaults to cwd). */
+  workspaceDirectory?: string;
+};
+
+/**
+ * cursor-agent resolves `--workspace` against its own working directory, and
+ * this driver already spawns it with that same directory as `cwd`. A relative
+ * value was therefore applied twice: `apps/qa` from a repo-root run became
+ * `<repo>/apps/qa/apps/qa`, and cursor-agent exited immediately with
+ * "Workspace directory does not exist".
+ *
+ * That surfaced as `cursor-agent run timed out.`, so it read like a slow agent
+ * rather than a bad path — and every task routed through this driver failed
+ * the same way, which is why no test case ever reached a verdict.
+ *
+ * Resolving once keeps the two uses in agreement, and is a no-op for a path
+ * that is already absolute.
+ */
+export function resolveWorkspaceDirectory(workspaceDirectory?: string): string | undefined {
+  return workspaceDirectory ? path.resolve(workspaceDirectory) : undefined;
+}
+
+export function buildCursorCliArgs(prompt: string, options: CursorCliDriverOptions = {}): string[] {
+  const args = ["-p", prompt, "--output-format", "json", "--force"];
+  if (options.model) args.push("--model", options.model);
+  const workspace = resolveWorkspaceDirectory(options.workspaceDirectory);
+  if (workspace) args.push("--workspace", workspace);
+  return args;
+}
+
+/**
+ * Parses `cursor-agent -p --output-format json` stdout into a commit-style
+ * payload, reusing the same {status, summary, ...} shape the AppleScript
+ * path's `bugmole_commit_response` expects, so downstream consumers do not
+ * need to know which delivery mechanism produced a response.
+ *
+ * The exact `--output-format json` envelope was not exercised against a live
+ * `cursor-agent` run while writing this (doing so would mean actually
+ * spawning an autonomous coding-agent session as a side effect of writing
+ * this file, which needs its own explicit go-ahead). This tries the
+ * reasonable shapes generously and always falls back to treating raw stdout
+ * as the summary rather than throwing, so an unexpected envelope degrades to
+ * "unstructured but present" instead of a hard failure — confirm the real
+ * shape against one real run before relying on this in production.
+ */
+export function parseCursorCliOutput(stdout: string): CursorDriverResponse["payload"] | undefined {
+  const trimmed = stdout.trim();
+  if (!trimmed) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object") {
+      const { valid } = validateCommitPayload(parsed);
+      if (valid) return parsed;
+      const text =
+        typeof parsed.result === "string" ? parsed.result
+        : typeof parsed.text === "string" ? parsed.text
+        : typeof parsed.message === "string" ? parsed.message
+        : typeof parsed.response === "string" ? parsed.response
+        : undefined;
+      if (text) return { status: "ok", summary: text.slice(0, 400), answer_markdown: text };
+    }
+  } catch {
+    // Not JSON; fall through to the raw-text fallback below.
+  }
+  return { status: "ok", summary: trimmed.slice(0, 400), answer_markdown: trimmed };
+}
+
+/**
+ * Runs a prompt through the real, headless `cursor-agent` CLI instead of
+ * AppleScript-injecting it into the Cursor GUI. `-p` mode blocks until the
+ * agent finishes and prints its final response, so there is no polling or
+ * "nudge" loop here the way the AppleScript path needs — the agent still has
+ * MCP access (via `cursor-agent mcp`) and can call the same `bugmole_*`
+ * tools; this driver only replaces *delivery* of the prompt and *receipt* of
+ * the final answer.
+ */
+export async function runCursorCliDriver(
+  task: string,
+  options: CursorCliDriverOptions,
+): Promise<CursorDriverResponse> {
+  const command = options.command?.trim() || "cursor-agent";
+  const prompt = generateCursorDriverPrompt(task, options);
+  const args = buildCursorCliArgs(prompt, options);
+  try {
+    const { stdout } = await execFileAsync(command, args, {
+      // Same resolved path the --workspace arg carries; see
+      // resolveWorkspaceDirectory for why these must not disagree.
+      cwd: resolveWorkspaceDirectory(options.workspaceDirectory),
+      timeout: resolveCursorTimeoutMs(options.taskType, options.timeoutMs),
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    const payload = parseCursorCliOutput(stdout);
+    if (!payload) {
+      return { success: false, error: "cursor-agent produced no output.", errorCode: "TIMEOUT" };
+    }
+    const validation = validateCommitPayload(payload);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: `Payload validation failed: ${validation.errors.join(", ")}`,
+        errorCode: "VALIDATION_FAILED",
+      };
+    }
+    return { success: true, payload };
+  } catch (error) {
+    const failure = error as ExecFileException;
+    if (failure.code === "ENOENT") {
+      return { success: false, error: `cursor-agent executable was not found: ${command}`, errorCode: "MCP_UNAVAILABLE" };
+    }
+    if (failure.killed || failure.signal === "SIGTERM") {
+      return { success: false, error: "cursor-agent run timed out.", errorCode: "TIMEOUT" };
+    }
+    return { success: false, error: failure.message || "cursor-agent run failed." };
+  }
+}

package/src/runtime/cursor-driver-example.ts

@@ -0,0 +1,117 @@
+/**
+ * Example usage of CURSOR_DRIVER as an LLM API adapter
+ *
+ * This demonstrates how to use CURSOR_DRIVER in place of traditional LLM calls.
+ */
+
+import { runCursorDriver, cursorComplete, cursorCompleteStructured } from "./cursor-driver-run.js";
+
+/**
+ * Example 1: Simple text completion (like OpenAI API)
+ */
+export async function exampleSimpleCompletion(cfg: any) {
+  const task = "Analyze the codebase and suggest improvements to the error handling patterns.";
+
+  const result = await cursorComplete(task, {
+    artifactsDir: cfg.runtime.artifacts_dir || "./artifacts",
+    mcpHost: cfg.mcp?.host || "127.0.0.1",
+    mcpPort: cfg.mcp?.port || 3187,
+  });
+
+  console.log("Completion result:", result);
+  return result;
+}
+
+/**
+ * Example 2: Structured completion with full payload
+ */
+export async function exampleStructuredCompletion(cfg: any) {
+  const task = `
+    Review the test failures in the execution results and propose fixes.
+    Focus on selector mismatches and timing issues.
+  `;
+
+  const result = await cursorCompleteStructured(task, {
+    artifactsDir: cfg.runtime.artifacts_dir || "./artifacts",
+    mcpHost: cfg.mcp?.host || "127.0.0.1",
+    mcpPort: cfg.mcp?.port || 3187,
+    requestId: `review_${Date.now()}`,
+    customInstructions: "Pay special attention to Playwright selectors and wait conditions.",
+  });
+
+  if (result.success && result.payload) {
+    console.log("Status:", result.payload.status);
+    console.log("Summary:", result.payload.summary);
+    console.log("Actions:", result.payload.actions);
+    console.log("Artifacts:", result.payload.artifacts);
+  } else {
+    console.error("Error:", result.error);
+  }
+
+  return result;
+}
+
+/**
+ * Example 3: Using in a diff proposal workflow
+ */
+export async function exampleDiffProposal(cfg: any, evidence: any, failures: any[]) {
+  const task = `
+    Based on the execution evidence and failures, propose minimal changes to the spec file.
+    
+    Evidence: ${JSON.stringify(evidence, null, 2)}
+    Failures: ${JSON.stringify(failures, null, 2)}
+    
+    Generate a diff that addresses these issues while maintaining backward compatibility.
+  `;
+
+  const result = await runCursorDriver(task, {
+    artifactsDir: cfg.runtime.artifacts_dir || "./artifacts",
+    mcpHost: cfg.mcp?.host || "127.0.0.1",
+    mcpPort: cfg.mcp?.port || 3187,
+    timeout: 600000, // 10 minutes for complex tasks
+    requestId: `diff_proposal_${Date.now()}`,
+  });
+
+  return result;
+}
+
+/**
+ * Example 4: Error handling
+ */
+export async function exampleWithErrorHandling(cfg: any, task: string) {
+  try {
+    const result = await runCursorDriver(task, {
+      artifactsDir: cfg.runtime.artifacts_dir || "./artifacts",
+      mcpHost: cfg.mcp?.host || "127.0.0.1",
+      mcpPort: cfg.mcp?.port || 3187,
+      timeout: 300000,
+    });
+
+    if (!result.success) {
+      switch (result.errorCode) {
+        case "TIMEOUT":
+          console.error("Task timed out. Consider increasing timeout or simplifying the task.");
+          break;
+        case "MCP_UNAVAILABLE":
+          console.error("MCP server is not available. Check if the server is running.");
+          break;
+        case "INJECTION_FAILED":
+          console.error(
+            "Failed to inject prompt into Cursor. Check if Cursor is running and accessible.",
+          );
+          break;
+        case "VALIDATION_FAILED":
+          console.error("Response validation failed:", result.error);
+          break;
+        default:
+          console.error("Unknown error:", result.error);
+      }
+      return null;
+    }
+
+    return result.payload;
+  } catch (error: any) {
+    console.error("Unexpected error:", error);
+    return null;
+  }
+}

package/src/runtime/cursor-driver-index.ts

@@ -0,0 +1,65 @@
+/**
+ * CURSOR_DRIVER - Main exports
+ *
+ * This module provides a complete LLM API adapter using Cursor as the reasoning engine.
+ * Use this instead of traditional LLM API calls for tasks that benefit from Cursor's
+ * codebase context and tool access.
+ */
+
+// Continuous execution (automatically follows next_steps)
+export {
+  executeContinuously,
+  type ContinuousExecutionOptions,
+  type ContinuousExecutionResult,
+} from "./continuous-execution.js";
+
+// Unified LLM interface (works with OpenAI, Anthropic, Cursor, Ollama)
+export {
+  llm,
+  llmStructured,
+  resetLLMConfigCache,
+  type LLMProvider,
+  type LLMOptions,
+  type LLMResponse,
+} from "./llm.js";
+
+// Simple LLM-like interface (recommended for Cursor use cases)
+export {
+  cursorLLM,
+  cursorLLMStructured,
+  resetConfigCache,
+  type CursorLLMOptions,
+} from "./cursor-llm.js";
+
+// Main driver function (advanced use)
+export { runCursorDriver, cursorComplete, cursorCompleteStructured } from "./cursor-driver-run.js";
+
+// Prompt generation utilities
+export {
+  generateFinalizationProtocol,
+  appendFinalizationProtocol,
+  generateCursorDriverPrompt,
+  validateCommitPayload,
+  type CursorDriverOptions,
+} from "./cursor-driver.js";
+
+// AppleScript utilities (for advanced use cases)
+export {
+  injectPrompt,
+  activateCursor,
+  ensureChatPanelOpen,
+  createNewChat,
+  isCursorRunning,
+  type CursorInjectionOptions,
+} from "./cursor-applescript.js";
+
+// MCP monitoring utilities (for advanced use cases)
+export {
+  waitForCommitResponse,
+  getLatestCommit,
+  type CommitResponse,
+  type MonitorOptions,
+} from "./cursor-mcp-monitor.js";
+
+// Response types
+export type { CursorDriverResponse, CursorDriverRunOptions } from "./cursor-driver.js";

package/src/runtime/cursor-driver-init.ts

@@ -0,0 +1,277 @@
+/**
+ * CURSOR_DRIVER initialization task generator
+ *
+ * Generates a comprehensive task prompt that instructs Cursor to:
+ * 1. Explore the application using bugmole_explore MCP tool
+ * 2. Read existing spec files using bugmole_read_spec
+ * 3. Create/update all necessary spec files using bugmole_write_spec
+ * 4. Follow templates and schemas from the docs
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export interface InitOptions {
+  /**
+   * Base URL of the application to explore
+   */
+  baseUrl?: string;
+
+  /**
+   * Maximum exploration depth
+   * @default 5
+   */
+  maxDepth?: number;
+
+  /**
+   * Project directory path (for context)
+   */
+  projectDirectory?: string;
+
+  /**
+   * Whether to force re-initialization even if files exist
+   * @default false
+   */
+  force?: boolean;
+}
+
+/**
+ * Generates the initialization task prompt for Cursor
+ */
+export function generateInitTask(options: InitOptions = {}): string {
+  const { baseUrl, maxDepth = 5, projectDirectory, force = false } = options;
+
+  let task = `# Bugmole MCP Initialization Task
+
+You are tasked with initializing the Bugmole MCP framework for this project. This involves exploring the application, understanding its structure, and creating all necessary spec files.
+
+## Your Mission
+
+Use the available Bugmole MCP tools to:
+1. Explore the application to discover user journeys
+2. Read existing spec files (if any) to understand current state
+3. Create or update all required spec files following the framework's schemas and templates
+
+## Available MCP Tools
+
+You have access to these Bugmole MCP tools:
+- \`bugmole_explore\` - Explore the application and discover user journeys
+- \`bugmole_journey_create\`, \`bugmole_journey_add_step\`, \`bugmole_journey_add_transition\` - Build flows incrementally
+- \`bugmole_journey_update\`, \`bugmole_journey_remove\` - Edit flows and their steps
+- \`bugmole_journey_next\` - Check the flow chart for the next exploration task
+- \`bugmole_read_spec\` - Read existing spec files
+- \`bugmole_write_spec\` - Write or update spec files
+- \`bugmole_plan\` - Generate journey plans (optional, for later)
+
+## Step-by-Step Instructions
+
+### Step 1: Explore the Application
+
+First, explore the application to discover screens and user journeys:
+
+1. Call \`bugmole_explore\` with:
+   - \`baseUrl\`: ${
+     baseUrl ||
+     "The application base URL (check environment variables, .env file, or bugmole.config.yaml for PLAYWRIGHT_BASE_URL)"
+   }
+   - \`maxDepth\`: ${maxDepth}
+
+${
+  baseUrl
+    ? ""
+    : "**Note**: If the base URL is not available, you can skip exploration and focus on creating spec files based on codebase analysis. However, exploration is recommended for accurate journey discovery."
+}
+
+This will discover screens and actions, building the journey graph. It is only the first exploration pass.
+
+After every exploration or discovery pass, call \`bugmole_journey_next\` for the selected flow. Perform its returned task, record the result, and repeat until it returns \`exhausted\` or \`blocked\`. Do not call \`bugmole_plan\` while it still returns an actionable task.
+
+### Step 2: Check Existing Spec Files
+
+Read existing spec files to understand what's already in place:
+
+1. Check if these files exist using \`bugmole_read_spec\`:
+   - \`roles.yaml\` - Role and capability definitions
+   - \`domain_rules.yaml\` - Business rules and invariants
+   - \`blockers.yaml\` - UI blocker handling rules
+   - \`journeys.graph.json\` - Journey graph (created by explorer)
+   - \`bugs.index.json\` - Bug backlog structure
+
+### Step 3: Initialize Required Spec Files
+
+Create or update each spec file following the schemas. Reference these files for guidance:
+- \`spec/schema.md\` - Complete schema reference
+- \`docs/file-authoring-template.md\` - Template for creating spec files
+- \`spec/roles.yaml\` - Example roles file (if exists, use as reference)
+- \`spec/domain_rules.yaml\` - Example domain rules (if exists, use as reference)
+- \`spec/blockers.yaml\` - Example blockers (if exists, use as reference)
+
+#### 3.1: roles.yaml
+
+Create \`roles.yaml\` defining:
+- All user roles/actors in the application
+- Capabilities for each role
+- Capability groups for organization
+
+**Requirements:**
+- Follow \`spec/schema.md\` section "2) spec/roles.yaml"
+- Include at least 2-3 roles (e.g., user, admin, viewer)
+- Define capabilities that match the application's features
+- Use the existing template structure if available
+
+#### 3.2: domain_rules.yaml
+
+Create \`domain_rules.yaml\` defining:
+- Business prerequisites
+- Policies (what's allowed/blocked)
+- Invariants (what must always be true)
+
+**Requirements:**
+- Follow \`spec/schema.md\` section "3) spec/domain_rules.yaml"
+- Include at least one entity with prerequisites
+- Include at least one policy
+- Include at least one invariant
+
+#### 3.3: blockers.yaml
+
+Create \`blockers.yaml\` defining:
+- UI interruptions (modals, dialogs, overlays)
+- How to handle each blocker type
+- Hard-stop conditions
+
+**Requirements:**
+- Follow \`spec/schema.md\` section "4) spec/blockers.yaml"
+- Include common UI blockers (modals, toasts, loading states)
+- Define resolution strategies
+- Include at least one hard-stop condition
+
+#### 3.4: bugs.index.json
+
+Create \`bugs.index.json\` for bug backlog structure:
+
+**Requirements:**
+- Follow \`spec/schema.md\` section "6) spec/bugs.index.json"
+- Initialize with empty structure if no bugs exist yet
+
+### Step 4: Verify Journey Graph
+
+After exploration, verify that \`journeys.graph.json\` was created/updated:
+- Check if it contains discovered screens (nodes)
+- Check if it contains discovered actions (edges)
+- If empty or minimal, you may need to manually enhance it based on application understanding
+- Check the selected flow with \`bugmole_journey_get\` and continue its \`bugmole_journey_next\` loop
+
+## Important Guidelines
+
+1. **Follow Schemas Strictly**: Always reference \`spec/schema.md\` for exact field names and structure
+2. **Use Templates**: Reference \`docs/file-authoring-template.md\` for file authoring guidance
+3. **Be Domain-Agnostic**: The framework works for any application - adapt the examples to this project
+4. **Quality Over Speed**: Create complete, well-structured files rather than minimal placeholders
+5. **Preserve Existing Content**: If files exist and are well-formed, enhance them rather than replacing
+${
+  force
+    ? "6. **Force Mode**: You are instructed to re-initialize even if files exist"
+    : "6. **Preserve Mode**: Only create missing files, enhance existing ones"
+}
+
+## Project Context
+
+${projectDirectory ? `- Project directory: ${projectDirectory}` : "- Current working directory"}
+- Application type: Analyze the codebase to determine (web app, API, etc.)
+- Framework: Analyze to determine (React, Next.js, Vue, etc.)
+
+## Expected Outcome
+
+After completing this task, the \`spec/\` directory should contain:
+- ✅ \`roles.yaml\` - Complete role definitions
+- ✅ \`domain_rules.yaml\` - Business rules and invariants
+- ✅ \`blockers.yaml\` - UI blocker handling
+- ✅ \`journeys.graph.json\` - Discovered journey graph
+- ✅ \`bugs.index.json\` - Bug backlog structure (initialized)
+
+All files should:
+- Follow the schema exactly
+- Be ready for use by the framework
+- Contain realistic, application-specific content (not just examples)
+
+## Important: Next Steps
+
+If you cannot complete all steps in a single response, you MUST include a \`next_steps\` field in your commit payload with the remaining steps. For example:
+
+\`\`\`json
+{
+  "status": "ok",
+  "summary": "Completed initial investigation, need to continue with exploration",
+  "next_steps": [
+    "Start the application using the discovered command",
+    "Use bugmole_explore with the base URL to discover journeys",
+    "Create test plans for discovered journeys"
+  ]
+}
+\`\`\`
+
+The framework will automatically continue with these next steps. Only omit \`next_steps\` when the task is fully complete.
+
+## Notes
+
+- If the application URL is not available, focus on creating the spec files based on codebase analysis
+- If exploration fails, you can still create spec files based on understanding the codebase structure
+- Use \`bugmole_read_spec\` to verify files after writing them
+- All file paths are relative to \`spec/\` directory
+
+Begin by exploring the application, then proceed with file creation.`;
+
+  return task;
+}
+
+/**
+ * Reads the project structure to infer application details
+ */
+export function inferApplicationDetails(projectDirectory?: string): {
+  baseUrl?: string;
+  appType?: string;
+  framework?: string;
+} {
+  const dir = projectDirectory || process.cwd();
+  const packageJsonPath = path.join(dir, "package.json");
+
+  const details: {
+    baseUrl?: string;
+    appType?: string;
+    framework?: string;
+  } = {};
+
+  // Try to read package.json
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+
+      // Infer framework from dependencies
+      if (pkg.dependencies || pkg.devDependencies) {
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps.next) details.framework = "Next.js";
+        else if (deps.react) details.framework = "React";
+        else if (deps.vue) details.framework = "Vue";
+        else if (deps["@angular/core"]) details.framework = "Angular";
+      }
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  // Try to infer base URL from environment or config
+  const envPath = path.join(dir, ".env");
+  if (fs.existsSync(envPath)) {
+    try {
+      const envContent = fs.readFileSync(envPath, "utf-8");
+      const urlMatch = envContent.match(/PLAYWRIGHT_BASE_URL=(.+)/);
+      if (urlMatch) {
+        details.baseUrl = urlMatch[1].trim();
+      }
+    } catch (e) {
+      // Ignore errors
+    }
+  }
+
+  return details;
+}

package/src/runtime/cursor-driver-run.test.ts

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { shouldFallBackToCursorGui } from "./cursor-driver-run.js";
+
+const missingCli = { success: false, error: "cursor-agent executable was not found: cursor-agent", errorCode: "MCP_UNAVAILABLE" as const };
+
+test("falls back to the Cursor GUI only on macOS when cursor-agent is missing", () => {
+  assert.equal(shouldFallBackToCursorGui(missingCli, "darwin"), true);
+  assert.equal(shouldFallBackToCursorGui(missingCli, "linux"), false);
+});
+
+test("never falls back after the CLI ran, whether it succeeded or failed for another reason", () => {
+  assert.equal(shouldFallBackToCursorGui({ success: true }, "darwin"), false);
+  assert.equal(shouldFallBackToCursorGui({ success: false, error: "cursor-agent run timed out.", errorCode: "TIMEOUT" }, "darwin"), false);
+});