@bugmole/cli 0.4.0

package/scripts/billing/paypal-setup.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Creates Bugmole's PayPal product and its four billing plans (Team and
+// Business, monthly and yearly) from the plan catalog, and prints the plan ids
+// to set as registry vars (plan ids aren't secret).
+//
+// Sandbox first, then live; each environment needs its own plans. Credentials
+// come from Arcana so they never reach the shell history:
+//
+//   arcana run --secret arcana://paypal/bugmole/sandbox-client-id --env PAYPAL_CLIENT_ID -- \
+//   arcana run --secret arcana://paypal/bugmole/sandbox-client-secret --env PAYPAL_CLIENT_SECRET -- \
+//   env PAYPAL_ENV=sandbox node scripts/billing/paypal-setup.mjs
+//
+// Set PAYPAL_PLANS=0 to skip creating plans (e.g. to add only the webhook).
+// PAYPAL_PRODUCT_ID=PROD-… reuses an existing product. Running it twice
+// creates duplicate plans (PayPal has no "ensure"); deactivate extras in the
+// PayPal dashboard.
+//
+// Plan choices (from realistiz-dd's plan script):
+// - total_cycles 0: renews until cancelled.
+// - auto_bill_outstanding: a failed renewal is retried with the next charge.
+// - payment_failure_threshold 1: one failed renewal suspends the subscription,
+//   which Bugmole turns into a 7-day grace period.
+import { PLANS } from "../../src/billing/plan-catalog.ts";
+
+const sandbox = process.env.PAYPAL_ENV === "sandbox";
+const apiBase = sandbox ? "https://api-m.sandbox.paypal.com" : "https://api-m.paypal.com";
+const { PAYPAL_CLIENT_ID: clientId, PAYPAL_CLIENT_SECRET: clientSecret } = process.env;
+if (!clientId || !clientSecret) {
+  console.error("Set PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET (and PAYPAL_ENV=sandbox for the sandbox).");
+  process.exit(1);
+}
+
+async function paypal(path, init = {}) {
+  const res = await fetch(`${apiBase}${path}`, init);
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${init.method ?? "GET"} ${path} failed: ${res.status} ${text}`);
+  return text ? JSON.parse(text) : {};
+}
+
+const { access_token: token } = await paypal("/v1/oauth2/token", {
+  method: "POST",
+  headers: {
+    Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`,
+    "content-type": "application/x-www-form-urlencoded",
+  },
+  body: "grant_type=client_credentials",
+});
+
+const post = (body) => ({
+  method: "POST",
+  headers: {
+    Authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    Prefer: "return=representation",
+    "PayPal-Request-Id": crypto.randomUUID(),
+  },
+  body: JSON.stringify(body),
+});
+
+const product = process.env.PAYPAL_PRODUCT_ID
+  ? { id: process.env.PAYPAL_PRODUCT_ID }
+  : await paypal("/v1/catalogs/products", post({
+    name: "Bugmole",
+    description: "AI-powered end-to-end testing: cloud runs, AI credits and team features.",
+    type: "SERVICE",
+    category: "SOFTWARE",
+    home_url: "https://bugmole.com",
+  }));
+
+const dollars = (cents) => (cents / 100).toFixed(2);
+const lines = [];
+for (const planId of process.env.PAYPAL_PLANS === "0" ? [] : ["team", "business"]) {
+  const plan = PLANS[planId];
+  for (const interval of ["month", "year"]) {
+    const cents = interval === "year" ? plan.priceYearlyMonthlyCents * 12 : plan.priceMonthlyCents;
+    const created = await paypal("/v1/billing/plans", post({
+      product_id: product.id,
+      name: `Bugmole ${plan.name} - ${interval === "year" ? "yearly" : "monthly"}`,
+      description: `USD ${dollars(cents)} per ${interval}, renews until cancelled. Usage beyond the allowance is invoiced monthly.`,
+      status: "ACTIVE",
+      billing_cycles: [{
+        frequency: { interval_unit: interval === "year" ? "YEAR" : "MONTH", interval_count: 1 },
+        tenure_type: "REGULAR",
+        sequence: 1,
+        total_cycles: 0,
+        pricing_scheme: { fixed_price: { value: dollars(cents), currency_code: "USD" } },
+      }],
+      payment_preferences: {
+        auto_bill_outstanding: true,
+        setup_fee_failure_action: "CANCEL",
+        payment_failure_threshold: 1,
+      },
+    }));
+    lines.push(`PAYPAL_PLAN_${planId.toUpperCase()}_${interval.toUpperCase()}=${created.id}`);
+  }
+}
+
+// PAYPAL_WEBHOOK_URL (e.g. https://api.bugmole.com/api/billing/webhooks/paypal)
+// also registers the webhook; its id goes in PAYPAL_WEBHOOK_ID.
+if (process.env.PAYPAL_WEBHOOK_URL) {
+  const hook = await paypal("/v1/notifications/webhooks", post({
+    url: process.env.PAYPAL_WEBHOOK_URL,
+    event_types: [
+      "BILLING.SUBSCRIPTION.ACTIVATED",
+      "BILLING.SUBSCRIPTION.UPDATED",
+      "BILLING.SUBSCRIPTION.RE-ACTIVATED",
+      "BILLING.SUBSCRIPTION.SUSPENDED",
+      "BILLING.SUBSCRIPTION.CANCELLED",
+      "BILLING.SUBSCRIPTION.EXPIRED",
+      "BILLING.SUBSCRIPTION.PAYMENT.FAILED",
+      "PAYMENT.SALE.COMPLETED",
+      "PAYMENT.SALE.REFUNDED",
+      "INVOICING.INVOICE.PAID",
+      "INVOICING.INVOICE.CANCELLED",
+    ].map((name) => ({ name })),
+  }));
+  lines.push(`PAYPAL_WEBHOOK_ID=${hook.id}`);
+}
+
+console.log(`PayPal ${sandbox ? "sandbox" : "LIVE"} product: ${product.id}`);
+for (const line of lines) console.log(line);

package/scripts/bugmole-continue.ts

@@ -0,0 +1,318 @@
+/**
+ * Bugmole MCP Continuation Script
+ *
+ * After initialization, this script uses Cursor LLM to:
+ * 1. Investigate the project structure
+ * 2. Detect how to start the application
+ * 3. Determine URLs and ports
+ * 4. Continue with exploration and test creation
+ *
+ * Usage:
+ *   npm run bugmole:continue
+ *   npm run bugmole:continue -- --project-directory /path/to/project
+ *   npm run bugmole:continue -- --max-iterations 100
+ *   npm run bugmole:continue -- --project-directory /path/to/project --max-iterations 100 --timeout 900000
+ */
+
+import { executeContinuously } from "../src/runtime/continuous-execution.js";
+
+function readArg(name: string): string | undefined {
+  const args = process.argv;
+  const i = args.indexOf(name);
+  if (i >= 0 && i + 1 < args.length) return args[i + 1];
+  return undefined;
+}
+
+function hasFlag(name: string): boolean {
+  return process.argv.includes(name);
+}
+
+/**
+ * Generates the continuation task that asks Cursor to investigate and continue
+ */
+function generateContinuationTask(projectDirectory?: string): string {
+  return `# Bugmole MCP Continuation Task
+
+You are continuing the Bugmole MCP setup for this project. The initial spec files have been created, and now you need to:
+
+1. **Investigate the project structure** to understand:
+   - What type of application(s) this is (monorepo, single app, etc.)
+   - How to start the application(s)
+   - What URLs/ports the applications run on
+   - What dependencies need to be installed or started first
+
+2. **Determine the base URL** for testing:
+   - Check package.json scripts (start, dev, etc.)
+   - Check configuration files (.env, config files)
+   - Check documentation (README.md, docs/)
+   - Look for port numbers in code or config
+   - Identify the main frontend application URL
+
+3. **Start the application** (if not already running):
+   - Determine the correct start command
+   - Check if services are already running on expected ports
+   - Use appropriate commands to start the application
+
+4. **Continue with exploration**:
+   - Once the application is running, use \`bugmole_explore\` to discover user journeys
+   - Update the journey graph with discovered screens and actions
+   - Create test plans for key user journeys
+
+5. **Create initial test plans**:
+   - Use \`bugmole_plan\` to generate test plans for discovered journeys
+   - Focus on critical user flows first
+
+## Available MCP Tools
+
+You have access to these Bugmole MCP tools:
+- \`bugmole_explore\` - Explore the application and discover user journeys (requires baseUrl)
+- \`bugmole_read_spec\` - Read existing spec files
+- \`bugmole_write_spec\` - Write or update spec files
+- \`bugmole_plan\` - Generate journey plans from discovered journeys
+- \`bugmole_report_progress\` - Report your progress periodically (use every 2-3 minutes for long tasks)
+
+## CRITICAL: About next_steps
+
+When you commit your response, if you mention ANY of the following in your answer, you MUST include them in the "next_steps" array:
+- "Next Steps" section
+- "TODO" items
+- "should do", "need to", "use bugmole_", "run bugmole_"
+- Any future actions or commands
+
+Example: If you write "Next: Run bugmole_explore with baseUrl=http://localhost:8000", then your commit MUST include:
+\`\`\`json
+{
+  "next_steps": ["Run bugmole_explore with baseUrl=http://localhost:8000"]
+}
+\`\`\`
+
+ONLY omit next_steps when EVERYTHING is 100% complete and there is NO remaining work.
+
+## Your Investigation Steps
+
+### Step 1: Understand Project Structure
+
+Analyze the codebase to determine:
+- Is this a monorepo? (check for apps/, packages/, libs/ directories)
+- What applications exist? (check apps/ directory or root package.json)
+- What frameworks are used? (React, Next.js, Vue, Express, etc.)
+- Are there multiple services? (APIs, frontends, etc.)
+
+### Step 2: Find How to Start the Application
+
+Look for:
+- \`package.json\` scripts (start, dev, serve, etc.)
+- \`README.md\` or documentation with setup instructions
+- \`.env\` files or config files with port/URL information
+- Docker compose files or startup scripts
+- Any existing dev scripts (scripts/dev.sh, etc.)
+
+### Step 3: Determine Base URL
+
+Figure out:
+- What port does the main frontend run on? (common: 3000, 3001, 5173, 8000, etc.)
+- What is the full URL? (usually http://localhost:PORT)
+- Are there multiple services? Which one should be tested first?
+- Check for environment variables like PORT, BASE_URL, etc.
+
+### Step 4: Check if Application is Running
+
+Before starting, check if services are already running:
+- Try to detect running processes on expected ports
+- Check if the application responds to HTTP requests
+- If running, proceed to exploration
+- If not running, determine how to start it
+
+### Step 5: Start the Application (if needed)
+
+If the application is not running:
+- Determine the correct command to start it
+- Consider dependencies (databases, other services)
+- Start the application in a way that allows testing
+
+### Step 6: Explore the Application (Optional)
+
+**NOTE:** The \`bugmole_explore\` tool may not be fully implemented yet. If it returns an error, **do NOT keep retrying**. Instead:
+- Work with existing journey graph if it exists (check spec/journeys.graph.json)
+- Create test plans based on codebase analysis
+- Proceed with other tasks like creating plans, reading/writing specs
+
+If you want to try exploration:
+- Use \`bugmole_explore\` with the discovered baseUrl
+- Set appropriate maxDepth (start with 3-5)
+- If it fails, move on immediately - don't get stuck
+
+### Step 7: Create Test Plans
+
+After exploration:
+- Identify key user journeys from the journey graph
+- Use \`bugmole_plan\` to create test plans for important journeys
+- Start with critical user flows (login, main features, etc.)
+
+## Important Notes
+
+- **You have full access to the codebase** - use it to understand the project
+- **Use MCP tools** - don't just read files, use the tools to interact with the framework
+- **Be thorough** - investigate multiple sources (package.json, README, code, config files)
+- **Start simple** - focus on the main application first, then expand
+- **Document findings** - update spec files with discovered information
+- **CRITICAL: Do not get stuck on exploration** - If \`bugmole_explore\` fails or returns errors, immediately move on to other productive tasks like creating test plans, reading/writing specs, or executing existing plans. Do NOT retry exploration repeatedly.
+
+## Project Context
+
+${projectDirectory ? `- Project directory: ${projectDirectory}` : "- Current working directory"}
+- Spec files have been initialized in spec/ directory
+- You need to figure out how to proceed from here
+
+## Expected Outcome
+
+After completing this task:
+- ✅ Application is running (or instructions provided on how to start it)
+- ✅ Base URL is determined and documented
+- ✅ Journey graph is populated with discovered screens/actions
+- ✅ Initial test plans are created for key user journeys
+- ✅ All findings are documented in spec files
+
+## 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": "Investigated project structure, need to start application",
+  "next_steps": [
+    "Start the application using npm run dev",
+    "Wait for application to be ready on port 3000",
+    "Use bugmole_explore with http://localhost:3000 to discover journeys"
+  ]
+}
+\`\`\`
+
+The framework will automatically continue with these next steps. Only omit \`next_steps\` when the task is fully complete.
+
+Begin by investigating the project structure and determining how to start the application.`;
+}
+
+async function main() {
+  const projectDirectory =
+    readArg("--project-directory") ||
+    readArg("--projectDirectory") ||
+    process.env.CURSOR_PROJECT_DIRECTORY;
+
+  const timeout = Number(readArg("--timeout") || "900000"); // 15 minutes default
+  const configPath = readArg("--config");
+  const maxIterations = Number(readArg("--max-iterations") || readArg("--maxIterations") || "100");
+
+  console.log("[Bugmole MCP Continue] Starting framework continuation...");
+  console.log(
+    `[Bugmole MCP Continue] Project Directory: ${projectDirectory || "(current directory)"}`,
+  );
+  console.log(`[Bugmole MCP Continue] Timeout: ${timeout}ms`);
+  console.log(`[Bugmole MCP Continue] Max Iterations: ${maxIterations}\n`);
+
+  // Generate continuation task
+  const continuationTask = generateContinuationTask(projectDirectory);
+
+  console.log("[Bugmole MCP Continue] Generated continuation task");
+  console.log("[Bugmole MCP Continue] Starting continuous execution loop...");
+  console.log(
+    "[Bugmole MCP Continue] Cursor will investigate and continue until complete...\n",
+  );
+
+  // Use continuous execution to automatically follow next_steps
+  const result = await executeContinuously(continuationTask, {
+    configPath,
+    timeout,
+    projectDirectory,
+    useCursor: true,
+    maxIterations: Number(maxIterations), // Configurable via --max-iterations flag
+    iterationDelay: 3000, // 3 second delay between iterations
+    customInstructions:
+      "Please thoroughly investigate the project structure, determine how to start the application, find the base URL, and continue with exploration and test creation using the MCP tools. Include next_steps in your response if there are more steps to complete.",
+  });
+
+  console.log("\n[Bugmole MCP Continue] Continuous execution completed\n");
+
+  if (result.success) {
+    console.log(`✅ Task completed successfully in ${result.iterations} iteration(s)!`);
+
+    // Show summary of all iterations
+    console.log(`\n--- Execution Summary (${result.iterations} iteration(s)) ---`);
+    result.responses.forEach((response, index) => {
+      if ("payload" in response && response.payload) {
+        const cursorResponse = response as any;
+        console.log(`\nIteration ${index + 1}:`);
+        console.log(`  Summary: ${cursorResponse.payload?.summary || "N/A"}`);
+        if (cursorResponse.payload?.next_steps) {
+          console.log(
+            `  Next Steps: ${cursorResponse.payload.next_steps.length} step(s) remaining`,
+          );
+        } else {
+          console.log(`  Status: Complete (no next steps)`);
+        }
+      }
+    });
+
+    // Show final response details
+    const finalResponse = result.finalResponse;
+    if ("payload" in finalResponse && finalResponse.payload) {
+      const cursorResponse = finalResponse as any;
+
+      console.log(`\n--- Final Response ---`);
+      console.log(`Summary: ${cursorResponse.payload?.summary || "No summary provided"}`);
+
+      if (cursorResponse.payload?.answer_markdown) {
+        console.log("\n--- Full Answer ---");
+        console.log(cursorResponse.payload.answer_markdown);
+      }
+
+      if (cursorResponse.payload?.actions && cursorResponse.payload.actions.length > 0) {
+        console.log("\n--- Actions Performed ---");
+        cursorResponse.payload.actions.forEach((action: any, i: number) => {
+          console.log(`${i + 1}. ${action.type}: ${action.target}`);
+          if (action.details) {
+            console.log(`   ${action.details}`);
+          }
+        });
+      }
+
+      if (cursorResponse.payload?.artifacts && cursorResponse.payload.artifacts.length > 0) {
+        console.log("\n--- Artifacts Generated ---");
+        cursorResponse.payload.artifacts.forEach((artifact: any, i: number) => {
+          console.log(`${i + 1}. ${artifact.type}`);
+          if (artifact.content) {
+            const preview = artifact.content.substring(0, 200);
+            console.log(`   ${preview}${artifact.content.length > 200 ? "..." : ""}`);
+          }
+        });
+      }
+    }
+
+    console.log("\n📁 Check the spec/ directory for updated files:");
+    console.log("   - spec/journeys.graph.json (should have discovered journeys)");
+    console.log("   - spec/plans/*.flow.yaml (should have test plans)");
+
+    process.exit(0);
+  } else {
+    console.error("❌ Continuation failed!");
+    console.error(`Error: ${result.error}`);
+    console.error(`Iterations completed: ${result.iterations}`);
+
+    if (result.iterations >= Number(maxIterations)) {
+      console.error(
+        `\n💡 Reached maximum iterations (${maxIterations}). The task may be too complex.`,
+      );
+      console.error(
+        "   Consider breaking it into smaller tasks or increasing maxIterations with --max-iterations flag.",
+      );
+    }
+
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`[Bugmole MCP Continue] Fatal error: ${err?.message ?? err}`);
+  process.exit(1);
+});

package/scripts/bugmole-init.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Bugmole MCP Initialization Script
+ *
+ * Uses CURSOR_DRIVER to automatically explore a project and initialize
+ * all required spec files using MCP tools.
+ *
+ * Usage:
+ *   npm run bugmole:init
+ *   npm run bugmole:init -- --base-url http://localhost:3000
+ *   npm run bugmole:init -- --project-directory /path/to/project
+ */
+
+import { executeContinuously } from "../src/runtime/continuous-execution.js";
+import { generateInitTask, inferApplicationDetails } from "../src/runtime/cursor-driver-init.js";
+
+function readArg(name: string): string | undefined {
+  const args = process.argv;
+  const i = args.indexOf(name);
+  if (i >= 0 && i + 1 < args.length) return args[i + 1];
+  return undefined;
+}
+
+function hasFlag(name: string): boolean {
+  return process.argv.includes(name);
+}
+
+async function main() {
+  // Parse arguments
+  const baseUrl = readArg("--base-url") || readArg("--baseUrl") || process.env.PLAYWRIGHT_BASE_URL;
+
+  const projectDirectory =
+    readArg("--project-directory") ||
+    readArg("--projectDirectory") ||
+    process.env.CURSOR_PROJECT_DIRECTORY;
+
+  const maxDepth = Number(readArg("--max-depth") || readArg("--maxDepth") || "5");
+  const force = hasFlag("--force");
+  const timeout = Number(readArg("--timeout") || "600000"); // 10 minutes default for init
+  const configPath = readArg("--config");
+  const maxIterations = Number(readArg("--max-iterations") || readArg("--maxIterations") || "100");
+
+  console.log("[Bugmole MCP Init] Starting framework initialization...");
+  console.log(
+    `[Bugmole MCP Init] Base URL: ${baseUrl || "(not specified, will infer from codebase)"}`,
+  );
+  console.log(
+    `[Bugmole MCP Init] Project Directory: ${projectDirectory || "(current directory)"}`,
+  );
+  console.log(`[Bugmole MCP Init] Max Depth: ${maxDepth}`);
+  console.log(`[Bugmole MCP Init] Force: ${force}`);
+  console.log(`[Bugmole MCP Init] Timeout: ${timeout}ms`);
+  console.log(`[Bugmole MCP Init] Max Iterations: ${maxIterations}`);
+
+  // Infer application details if baseUrl not provided
+  let inferredBaseUrl = baseUrl;
+  if (!inferredBaseUrl && projectDirectory) {
+    const details = inferApplicationDetails(projectDirectory);
+    if (details.baseUrl) {
+      inferredBaseUrl = details.baseUrl;
+      console.log(`[Bugmole MCP Init] Inferred base URL: ${inferredBaseUrl}`);
+    }
+  }
+
+  // Generate initialization task
+  const initTask = generateInitTask({
+    baseUrl: inferredBaseUrl,
+    maxDepth,
+    projectDirectory,
+    force,
+  });
+
+  console.log("[Bugmole MCP Init] Generated initialization task");
+  console.log("[Bugmole MCP Init] Starting continuous execution loop...");
+  console.log(
+    "[Bugmole MCP Init] Cursor will initialize the framework and continue until complete...\n",
+  );
+
+  // Use continuous execution to automatically follow next_steps
+  const result = await executeContinuously(initTask, {
+    configPath,
+    timeout,
+    projectDirectory,
+    useCursor: true,
+    maxIterations: Number(maxIterations), // Configurable via --max-iterations flag
+    iterationDelay: 3000, // 3 second delay between iterations
+    customInstructions:
+      "Please continue with the Bugmole MCP initialization. Use the MCP tools to explore and create spec files. Include next_steps in your response if there are more steps to complete.",
+  });
+
+  console.log("\n[Bugmole MCP Init] Continuous execution completed\n");
+
+  if (result.success) {
+    console.log(`✅ Initialization completed successfully in ${result.iterations} iteration(s)!`);
+
+    // Show summary of all iterations
+    console.log(`\n--- Execution Summary (${result.iterations} iteration(s)) ---`);
+    result.responses.forEach((response, index) => {
+      if ("payload" in response && response.payload) {
+        const cursorResponse = response as any;
+        console.log(`\nIteration ${index + 1}:`);
+        console.log(`  Summary: ${cursorResponse.payload?.summary || "N/A"}`);
+        if (cursorResponse.payload?.next_steps) {
+          console.log(
+            `  Next Steps: ${cursorResponse.payload.next_steps.length} step(s) remaining`,
+          );
+        } else {
+          console.log(`  Status: Complete (no next steps)`);
+        }
+      }
+    });
+
+    // Show final response details
+    const finalResponse = result.finalResponse;
+    if ("payload" in finalResponse && finalResponse.payload) {
+      const cursorResponse = finalResponse as any;
+
+      console.log(`\n--- Final Response ---`);
+      console.log(`Summary: ${cursorResponse.payload?.summary || "No summary provided"}`);
+
+      if (cursorResponse.payload?.answer_markdown) {
+        console.log("\n--- Full Answer ---");
+        console.log(cursorResponse.payload.answer_markdown);
+      }
+
+      if (cursorResponse.payload?.actions && cursorResponse.payload.actions.length > 0) {
+        console.log("\n--- Actions Performed ---");
+        cursorResponse.payload.actions.forEach((action: any, i: number) => {
+          console.log(`${i + 1}. ${action.type}: ${action.target}`);
+          if (action.details) {
+            console.log(`   ${action.details}`);
+          }
+        });
+      }
+
+      if (cursorResponse.payload?.artifacts && cursorResponse.payload.artifacts.length > 0) {
+        console.log("\n--- Artifacts Generated ---");
+        cursorResponse.payload.artifacts.forEach((artifact: any, i: number) => {
+          console.log(`${i + 1}. ${artifact.type}`);
+          if (artifact.content) {
+            const preview = artifact.content.substring(0, 200);
+            console.log(`   ${preview}${artifact.content.length > 200 ? "..." : ""}`);
+          }
+        });
+      }
+    }
+
+    console.log("\n📁 Check the spec/ directory for initialized files:");
+    console.log("   - spec/roles.yaml");
+    console.log("   - spec/domain_rules.yaml");
+    console.log("   - spec/blockers.yaml");
+    console.log("   - spec/journeys.graph.json");
+    console.log("   - spec/bugs.index.json");
+
+    process.exit(0);
+  } else {
+    console.error("❌ Initialization failed!");
+    console.error(`Error: ${result.error}`);
+    console.error(`Iterations completed: ${result.iterations}`);
+
+    if (result.iterations >= Number(maxIterations)) {
+      console.error(
+        `\n💡 Reached maximum iterations (${maxIterations}). The task may be too complex.`,
+      );
+      console.error(
+        "   Consider breaking it into smaller tasks or increasing maxIterations with --max-iterations flag.",
+      );
+    } else if (result.responses.length > 0) {
+      const lastResponse = result.responses[result.responses.length - 1];
+      if ("errorCode" in lastResponse) {
+        const cursorResponse = lastResponse as any;
+        if (cursorResponse.errorCode === "MCP_UNAVAILABLE") {
+          console.error("\n💡 Make sure:");
+          console.error("   1. MCP server is running (npm run bugmole:mcp)");
+          console.error("   2. Cursor is configured to use the Bugmole MCP server");
+          console.error("   3. MCP tools are available in Cursor");
+        }
+      }
+    }
+
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`[Bugmole MCP Init] Fatal error: ${err?.message ?? err}`);
+  process.exit(1);
+});

package/scripts/bugmole.cjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const tsxCli = require.resolve("tsx/cli");
+const script = path.join(__dirname, "bugmole.ts");
+const result = spawnSync(process.execPath, [tsxCli, script, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(`[Bugmole CLI] failed to start: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);