tracebug 1.5.0

package/README.md

@@ -0,0 +1,37 @@
+# tracebug
+
+The TraceBug CLI — a **local MCP server** that lets AI coding agents debug [TraceBug](https://github.com/prashantsinghmangat/tracebug-ai) bug-report exports, plus one-command framework setup.
+
+Zero dependencies. ~24 KB. Node ≥ 18.
+
+## MCP server
+
+Connect Claude Code, Cursor, Windsurf, or VS Code to the `.html` bug reports the [TraceBug Chrome extension](https://chromewebstore.google.com/detail/fdemmibikigigkfjngclmdheeajhdgaj) exports:
+
+```bash
+claude mcp add tracebug -- npx -y tracebug mcp --dir ./bug-reports
+```
+
+The agent gets six read tools — `list_bug_reports`, `get_bug_report` (with a prioritized investigation guide), `get_console_errors`, `get_network_activity`, `get_repro_steps`, `get_screenshot` — and a `/tracebug:debug_bug_report` prompt.
+
+**Everything stays on your machine.** The server binds to stdio only, opens zero network connections, and reads the report files from your disk. No account, no cloud, no upload.
+
+Full guide: [tracebug.netlify.app/docs/mcp](https://tracebug.netlify.app/docs/mcp)
+
+## Project setup
+
+```bash
+npx tracebug init
+```
+
+Detects your framework (React, Next.js, Vue, Angular, Svelte, Nuxt, vanilla) and prints the setup snippet for the [`tracebug-sdk`](https://www.npmjs.com/package/tracebug-sdk) — the embeddable capture SDK.
+
+## Related packages
+
+| Package | What it is |
+|---|---|
+| [`tracebug`](https://www.npmjs.com/package/tracebug) (this one) | CLI: MCP server + `init`. For developers *receiving* bug reports. |
+| [`tracebug-sdk`](https://www.npmjs.com/package/tracebug-sdk) | The full SDK for embedding capture in your app. Includes this CLI too. |
+| [Chrome extension](https://chromewebstore.google.com/detail/fdemmibikigigkfjngclmdheeajhdgaj) | Zero-code capture for QA/testers on any website. |
+
+MIT © Prashant Singh Mangat

package/bin.mjs

@@ -0,0 +1,591 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// cli/mcp-server.ts
+var mcp_server_exports = {};
+__export(mcp_server_exports, {
+  PROMPT_DEFINITIONS: () => PROMPT_DEFINITIONS,
+  TOOL_DEFINITIONS: () => TOOL_DEFINITIONS,
+  buildDebugPrompt: () => buildDebugPrompt,
+  buildInvestigationGuide: () => buildInvestigationGuide,
+  callTool: () => callTool,
+  handleMessage: () => handleMessage,
+  parseReportFile: () => parseReportFile,
+  runMcpServer: () => runMcpServer,
+  scanReportFiles: () => scanReportFiles,
+  toolGetBugReport: () => toolGetBugReport,
+  toolGetConsoleErrors: () => toolGetConsoleErrors,
+  toolGetNetworkActivity: () => toolGetNetworkActivity,
+  toolGetReproSteps: () => toolGetReproSteps,
+  toolGetScreenshot: () => toolGetScreenshot,
+  toolListBugReports: () => toolListBugReports
+});
+import * as fs from "fs";
+import * as path from "path";
+function parseReportFile(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    if (filePath.endsWith(".html")) {
+      const m = TB_DATA_RE.exec(raw);
+      if (!m) return null;
+      const payload = JSON.parse(m[1].replace(/<\\\/script>/gi, "</script>"));
+      return isReportPayload(payload) ? payload : null;
+    }
+    if (filePath.endsWith(".json")) {
+      const payload = JSON.parse(raw);
+      return isReportPayload(payload) ? payload : null;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function isReportPayload(p) {
+  return typeof p === "object" && p !== null && typeof p.meta === "object" && p.meta !== null && typeof p.meta.title === "string" && typeof p.meta.sessionId === "string";
+}
+function scanReportFiles(dir, depth = 0) {
+  if (depth > MAX_SCAN_DEPTH) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+        found.push(...scanReportFiles(full, depth + 1));
+      }
+    } else if (entry.name.endsWith(".html") || entry.name.endsWith(".json")) {
+      if (parseReportFile(full) !== null) found.push(full);
+    }
+  }
+  return found;
+}
+function requireReport(baseDir, file) {
+  const direct = path.isAbsolute(file) ? file : path.join(baseDir, file);
+  const directPayload = parseReportFile(direct);
+  if (directPayload) return { payload: directPayload, resolved: direct };
+  const candidates = scanReportFiles(baseDir);
+  const query = file.toLowerCase();
+  let match = candidates.find((c) => path.basename(c).toLowerCase() === query);
+  if (!match) {
+    match = candidates.find((c) => {
+      if (path.basename(c).toLowerCase().includes(query)) return true;
+      const p = parseReportFile(c);
+      return p !== null && p.meta.title.toLowerCase().includes(query);
+    });
+  }
+  if (match) return { payload: parseReportFile(match), resolved: match };
+  const available = candidates.map((c) => path.relative(baseDir, c) || c);
+  throw new Error(
+    `Not a TraceBug export: ${file}. ` + (available.length ? `Available reports: ${available.join(", ")}` : `No reports found under ${baseDir} \u2014 check the server's --dir.`)
+  );
+}
+function buildInvestigationGuide(p) {
+  const steps = [];
+  const consoleErrors = p.consoleLogs?.filter((l) => l.level === "error").length ?? p.consoleErrors?.length ?? 0;
+  const netFailures = p.networkErrors?.length ?? 0;
+  const frustration = (p.actionChips ?? []).filter((c) => c.frustration).length;
+  const screenshots = p.screenshots?.length ?? 0;
+  const hintMentionsNetwork = /\b(request|response|http|4\d\d|5\d\d|status|api|fetch|xhr)\b/i.test(
+    p.rootCauseHint?.hint ?? ""
+  );
+  const networkStep = netFailures > 0 && `[HIGH] get_network_activity \u2014 ${netFailures} failed request${netFailures === 1 ? "" : "s"} captured, with response-body snippets that often name the server-side error.`;
+  const consoleStep = consoleErrors > 0 && `[HIGH] get_console_errors \u2014 ${consoleErrors} console error${consoleErrors === 1 ? "" : "s"} captured; stack traces point at the failing file and function.`;
+  for (const step of hintMentionsNetwork ? [networkStep, consoleStep] : [consoleStep, networkStep]) {
+    if (step) steps.push(step);
+  }
+  steps.push(
+    frustration > 0 ? `[HIGH] get_repro_steps \u2014 includes ${frustration} frustration signal${frustration === 1 ? "" : "s"} (rage/dead clicks) marking where the user got stuck, plus the action-to-error timeline.` : `[MEDIUM] get_repro_steps \u2014 the plain-English steps and session timeline show what the user did leading up to the bug.`
+  );
+  if (screenshots > 0) {
+    steps.push(
+      `[${consoleErrors || netFailures ? "MEDIUM" : "HIGH"}] get_screenshot \u2014 ${screenshots} screenshot${screenshots === 1 ? "" : "s"} showing the visual state when the bug was captured${consoleErrors || netFailures ? "" : " (no errors were captured, so visuals are a primary source)"}.`
+    );
+  }
+  if (p.video?.comments?.length) {
+    steps.push(
+      `[MEDIUM] The video has ${p.video.comments.length} timestamped tester comment${p.video.comments.length === 1 ? "" : "s"} (included in get_bug_report) \u2014 read them, they mark the exact moments the tester flagged.`
+    );
+  }
+  steps.push(
+    "Finally: cross-reference the findings with the codebase \u2014 search for the failing endpoint path, the symbols in the stack trace, or the UI text near the error \u2014 to locate the root cause and propose a fix."
+  );
+  return steps;
+}
+function toolListBugReports(baseDir, args2) {
+  const scanDir = args2.dir ? path.isAbsolute(args2.dir) ? args2.dir : path.join(baseDir, args2.dir) : baseDir;
+  const files = scanReportFiles(scanDir);
+  const reports = files.map((file) => {
+    const p = parseReportFile(file);
+    return {
+      file: path.relative(baseDir, file) || file,
+      title: p.meta.title,
+      summary: p.meta.summary,
+      severity: p.meta.severity,
+      priority: p.meta.priority ?? null,
+      page: p.meta.page,
+      generatedAt: new Date(p.meta.generatedAt).toISOString(),
+      rootCause: p.rootCauseHint ?? p.meta.rootCause ?? null,
+      counts: {
+        consoleErrors: p.consoleErrors?.length ?? 0,
+        networkFailures: p.networkErrors?.length ?? 0,
+        userActions: p.actionChips?.length ?? p.actions?.length ?? 0,
+        screenshots: p.screenshots?.length ?? 0,
+        hasVideo: Boolean(p.video)
+      }
+    };
+  });
+  return {
+    count: reports.length,
+    scannedDir: scanDir,
+    reports,
+    ...reports.length ? { nextStep: "Call get_bug_report on a file for the full overview plus a prioritized investigation guide." } : {}
+  };
+}
+function toolGetBugReport(baseDir, args2) {
+  const { payload: p } = requireReport(baseDir, args2.file);
+  return {
+    title: p.meta.title,
+    summary: p.meta.summary,
+    severity: p.meta.severity,
+    priority: p.meta.priority ?? null,
+    page: p.meta.page,
+    generatedAt: new Date(p.meta.generatedAt).toISOString(),
+    sessionDurationMs: p.meta.durationMs,
+    environment: p.meta.environment,
+    environmentDetails: p.info ?? [],
+    description: p.description || null,
+    rootCause: p.rootCauseHint ?? p.meta.rootCause ?? null,
+    annotations: p.annotations ?? [],
+    consoleErrorCount: p.consoleErrors?.length ?? 0,
+    networkFailureCount: p.networkErrors?.length ?? 0,
+    screenshotCount: p.screenshots?.length ?? 0,
+    video: p.video ? { durationMs: p.video.durationMs, comments: p.video.comments } : null,
+    investigationGuide: buildInvestigationGuide(p)
+  };
+}
+function toolGetConsoleErrors(baseDir, args2) {
+  const { payload: p } = requireReport(baseDir, args2.file);
+  const logs = p.consoleLogs?.length ? p.consoleLogs : (p.consoleErrors ?? []).map((e) => ({ level: "error", ...e }));
+  return {
+    count: logs.length,
+    entries: logs.map((l) => ({
+      level: l.level,
+      message: l.message,
+      stack: l.stack ?? null,
+      at: new Date(l.timestamp).toISOString()
+    }))
+  };
+}
+function toolGetNetworkActivity(baseDir, args2) {
+  const { payload: p } = requireReport(baseDir, args2.file);
+  const failures = p.networkErrors ?? [];
+  const all = p.networkRequests ?? [];
+  const rows = args2.failuresOnly !== false ? failures : all.length ? all : failures;
+  return {
+    failureCount: failures.length,
+    totalCaptured: all.length || failures.length,
+    showing: args2.failuresOnly !== false ? "failures only (pass failuresOnly:false for all requests)" : "all requests",
+    requests: rows.map((r) => ({
+      method: r.method,
+      url: r.url,
+      status: r.status,
+      durationMs: r.duration,
+      at: new Date(r.timestamp).toISOString(),
+      responseSnippet: r.response ?? null
+    }))
+  };
+}
+function toolGetReproSteps(baseDir, args2) {
+  const { payload: p } = requireReport(baseDir, args2.file);
+  return {
+    title: p.meta.title,
+    rootCause: p.rootCauseHint ?? p.meta.rootCause ?? null,
+    steps: p.actions ?? [],
+    actions: (p.actionChips ?? []).map((c) => ({
+      action: [c.verb, c.nounLabel ?? c.target].filter(Boolean).join(" "),
+      kind: c.kind,
+      detail: c.detail ?? null,
+      frustrationSignal: c.frustration ?? null,
+      causedError: c.isError ?? false,
+      at: new Date(c.timestamp).toISOString()
+    })),
+    timeline: (p.events ?? []).map((e) => ({
+      elapsed: e.elapsed,
+      type: e.type,
+      description: e.description,
+      isError: e.isError
+    }))
+  };
+}
+function toolGetScreenshot(baseDir, args2) {
+  const { payload: p } = requireReport(baseDir, args2.file);
+  const shots = p.screenshots ?? [];
+  const index = args2.index ?? 0;
+  if (!shots.length) throw new Error("This report contains no screenshots.");
+  if (index < 0 || index >= shots.length) {
+    throw new Error(`Screenshot index ${index} out of range (0\u2013${shots.length - 1}).`);
+  }
+  const shot = shots[index];
+  const m = /^data:(image\/[a-z+]+);base64,(.+)$/s.exec(shot.dataUrl);
+  if (!m) throw new Error(`Screenshot ${index} has an unsupported data URL format.`);
+  return {
+    image: { mimeType: m[1], base64: m[2] },
+    filename: shot.filename,
+    takenAt: new Date(shot.timestamp).toISOString(),
+    totalScreenshots: shots.length
+  };
+}
+function buildDebugPrompt(file) {
+  const target = file?.trim();
+  return [
+    target ? `This is a TraceBug bug report: ${target}` : "Debug the most recent TraceBug bug report.",
+    "",
+    target ? `1. Call get_bug_report("${target}") to load the report overview and its investigation guide.` : "1. Call list_bug_reports to find the reports, then get_bug_report on the most recent one to load its overview and investigation guide.",
+    "2. Follow the investigation guide to gather the relevant data (console errors, network failures, repro steps, screenshots).",
+    "3. Cross-reference the findings with this codebase \u2014 search for the failing endpoint path, stack-trace symbols, or the UI text near the error \u2014 to identify the root cause.",
+    "4. Propose a concrete fix, citing the files and lines involved, and note edge cases worth testing once it lands."
+  ].join("\n");
+}
+function callTool(baseDir, name, args2) {
+  try {
+    switch (name) {
+      case "list_bug_reports":
+        return textResult(toolListBugReports(baseDir, args2));
+      case "get_bug_report":
+        return textResult(toolGetBugReport(baseDir, args2));
+      case "get_console_errors":
+        return textResult(toolGetConsoleErrors(baseDir, args2));
+      case "get_network_activity":
+        return textResult(toolGetNetworkActivity(baseDir, args2));
+      case "get_repro_steps":
+        return textResult(toolGetReproSteps(baseDir, args2));
+      case "get_screenshot": {
+        const r = toolGetScreenshot(baseDir, args2);
+        return {
+          content: [
+            { type: "image", data: r.image.base64, mimeType: r.image.mimeType },
+            { type: "text", text: JSON.stringify({ filename: r.filename, takenAt: r.takenAt, totalScreenshots: r.totalScreenshots }) }
+          ]
+        };
+      }
+      default:
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+  } catch (err) {
+    return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true };
+  }
+}
+function textResult(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function handleMessage(baseDir, msg) {
+  const isNotification = msg.id === void 0 || msg.id === null;
+  switch (msg.method) {
+    case "initialize":
+      return reply(msg.id, {
+        protocolVersion: msg.params?.protocolVersion || "2025-06-18",
+        capabilities: { tools: {}, prompts: {} },
+        serverInfo: { name: "tracebug", version: SERVER_VERSION },
+        instructions: "TraceBug exposes locally-exported bug reports (self-contained .html files) to AI agents. Call list_bug_reports to discover reports, then get_bug_report \u2014 it returns an investigation guide telling you which get_* tools to call next. All data is read from local disk \u2014 nothing is uploaded."
+      });
+    case "ping":
+      return reply(msg.id, {});
+    case "tools/list":
+      return reply(msg.id, { tools: TOOL_DEFINITIONS });
+    case "tools/call": {
+      const name = msg.params?.name;
+      const args2 = msg.params?.arguments ?? {};
+      return reply(msg.id, callTool(baseDir, name, args2));
+    }
+    case "prompts/list":
+      return reply(msg.id, { prompts: PROMPT_DEFINITIONS });
+    case "prompts/get": {
+      const promptName = msg.params?.name;
+      if (promptName !== "debug_bug_report") {
+        return { jsonrpc: "2.0", id: msg.id ?? null, error: { code: -32602, message: `Unknown prompt: ${promptName}` } };
+      }
+      const promptArgs = msg.params?.arguments ?? {};
+      return reply(msg.id, {
+        description: PROMPT_DEFINITIONS[0].description,
+        messages: [
+          { role: "user", content: { type: "text", text: buildDebugPrompt(promptArgs.file) } }
+        ]
+      });
+    }
+    default:
+      if (isNotification) return null;
+      return { jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `Method not found: ${msg.method}` } };
+  }
+}
+function reply(id, result) {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function runMcpServer(baseDir, version) {
+  SERVER_VERSION = version;
+  process.stderr.write(`TraceBug MCP server \u2014 reading bug reports from ${baseDir}
+`);
+  return new Promise((resolve) => {
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+      let nl;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, nl).trim();
+        buffer = buffer.slice(nl + 1);
+        if (!line) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          process.stdout.write(
+            JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }) + "\n"
+          );
+          continue;
+        }
+        const response = handleMessage(baseDir, msg);
+        if (response) process.stdout.write(JSON.stringify(response) + "\n");
+      }
+    });
+    process.stdin.on("end", () => resolve());
+  });
+}
+var TB_DATA_RE, MAX_SCAN_DEPTH, SKIP_DIRS, FILE_PROP, TOOL_DEFINITIONS, PROMPT_DEFINITIONS, SERVER_VERSION;
+var init_mcp_server = __esm({
+  "cli/mcp-server.ts"() {
+    "use strict";
+    TB_DATA_RE = /<script id="tb-data" type="application\/json">([\s\S]*?)<\/script>/;
+    MAX_SCAN_DEPTH = 3;
+    SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".next", "dist", "build", "coverage", "out"]);
+    FILE_PROP = {
+      file: {
+        type: "string",
+        description: "The report to read: a path to a TraceBug export file (.html), absolute or relative to the server's base directory \u2014 or just the filename, or a fragment of the filename or report title. Get exact paths from list_bug_reports."
+      }
+    };
+    TOOL_DEFINITIONS = [
+      {
+        name: "list_bug_reports",
+        description: "Scan a directory for TraceBug bug-report export files (.html/.json) and summarize each: title, summary, severity, root-cause hint, and captured-data counts. Start here.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            dir: { type: "string", description: "Directory to scan (default: the server's base directory). Scans up to 3 levels deep, skipping node_modules etc." }
+          }
+        }
+      },
+      {
+        name: "get_bug_report",
+        description: "Get the overview of one TraceBug bug report: title, summary, severity, root-cause hint, environment, tester annotations, and a prioritized investigation guide telling you which tools to call next for this specific bug. Call this before the other get_* tools.",
+        inputSchema: { type: "object", properties: { ...FILE_PROP }, required: ["file"] }
+      },
+      {
+        name: "get_console_errors",
+        description: "Get the captured console output (errors, warnings, logs) with stack traces from a TraceBug bug report.",
+        inputSchema: { type: "object", properties: { ...FILE_PROP }, required: ["file"] }
+      },
+      {
+        name: "get_network_activity",
+        description: "Get captured network requests from a TraceBug bug report. Defaults to failed requests (status >= 400 or 0) with response snippets; pass failuresOnly:false for every captured request.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            ...FILE_PROP,
+            failuresOnly: { type: "boolean", description: "true (default) = failures only; false = all captured requests" }
+          },
+          required: ["file"]
+        }
+      },
+      {
+        name: "get_repro_steps",
+        description: "Get the reproduction context from a TraceBug bug report: plain-English steps, structured user actions (with rage/dead-click frustration signals), and the full session timeline.",
+        inputSchema: { type: "object", properties: { ...FILE_PROP }, required: ["file"] }
+      },
+      {
+        name: "get_screenshot",
+        description: "Get one screenshot from a TraceBug bug report as an image. Screenshots are auto-named from the action that triggered them (e.g. 01_click_submit.png).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            ...FILE_PROP,
+            index: { type: "number", description: "Zero-based screenshot index (default 0). list_bug_reports shows the count." }
+          },
+          required: ["file"]
+        }
+      }
+    ];
+    PROMPT_DEFINITIONS = [
+      {
+        name: "debug_bug_report",
+        description: "Debug a TraceBug bug report: load it, follow its investigation guide, and cross-reference with the codebase to find the root cause and propose a fix.",
+        arguments: [
+          {
+            name: "file",
+            description: "Which report to debug \u2014 a path, filename, or title fragment. Omit to pick the most recent report.",
+            required: false
+          }
+        ]
+      }
+    ];
+    SERVER_VERSION = "0.0.0";
+  }
+});
+
+// cli/bin.ts
+var args = process.argv.slice(2);
+var command = args[0];
+var BOLD = "\x1B[1m";
+var CYAN = "\x1B[36m";
+var GREEN = "\x1B[32m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+async function main() {
+  if (!command || command === "help") {
+    printHelp();
+    return;
+  }
+  if (command === "init") {
+    await initProject();
+    return;
+  }
+  if (command === "mcp") {
+    await startMcpServer();
+    return;
+  }
+  console.log(`Unknown command: ${command}. Run ${CYAN}npx tracebug help${RESET}`);
+}
+async function startMcpServer() {
+  const { runMcpServer: runMcpServer2 } = await Promise.resolve().then(() => (init_mcp_server(), mcp_server_exports));
+  const fs2 = await import("fs");
+  const path2 = await import("path");
+  const dirFlag = args.indexOf("--dir");
+  const baseDir = dirFlag !== -1 && args[dirFlag + 1] ? path2.resolve(args[dirFlag + 1]) : process.cwd();
+  let version = "0.0.0";
+  for (const rel of ["./package.json", "../package.json"]) {
+    try {
+      const pkg = JSON.parse(fs2.readFileSync(new URL(rel, import.meta.url), "utf8"));
+      if (pkg.version) {
+        version = pkg.version;
+        break;
+      }
+    } catch {
+    }
+  }
+  await runMcpServer2(baseDir, version);
+}
+function printHelp() {
+  console.log(`
+${BOLD}TraceBug CLI${RESET} \u2014 Debug bugs in seconds, not hours
+
+${BOLD}Commands:${RESET}
+  ${CYAN}init${RESET}    Set up TraceBug in your project
+  ${CYAN}mcp${RESET}     Start the MCP server so AI agents (Claude Code, Cursor) can read
+          exported bug reports. Options: ${DIM}--dir <path>${RESET} (default: current dir)
+  ${CYAN}help${RESET}    Show this help message
+
+${BOLD}Quick Start:${RESET}
+  ${DIM}$${RESET} npx tracebug init
+  ${DIM}$${RESET} npm run dev
+
+${BOLD}Docs:${RESET} https://tracebug.dev/docs
+`);
+}
+async function initProject() {
+  console.log(`
+${BOLD}${CYAN}TraceBug${RESET} \u2014 Setting up bug reporting
+`);
+  const fs2 = await import("fs");
+  const path2 = await import("path");
+  const cwd = process.cwd();
+  let framework = "vanilla";
+  const pkgPath = path2.join(cwd, "package.json");
+  if (fs2.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps["next"]) framework = "nextjs";
+      else if (deps["nuxt"]) framework = "nuxt";
+      else if (deps["vue"]) framework = "vue";
+      else if (deps["@angular/core"]) framework = "angular";
+      else if (deps["svelte"]) framework = "svelte";
+      else if (deps["react"]) framework = "react";
+    } catch {
+    }
+  }
+  console.log(`  Detected framework: ${GREEN}${framework}${RESET}`);
+  const snippets = {
+    nextjs: `// app/tracebug.tsx (create this file)
+"use client";
+import { useEffect } from "react";
+
+export default function TraceBugInit() {
+  useEffect(() => {
+    import("tracebug-sdk").then(({ default: TraceBug }) => {
+      TraceBug.init({ projectId: "${path2.basename(cwd)}" });
+    });
+  }, []);
+  return null;
+}
+
+// Then add <TraceBugInit /> to your root layout.tsx`,
+    react: `// src/main.tsx (add to your entry file)
+import TraceBug from "tracebug-sdk";
+TraceBug.init({ projectId: "${path2.basename(cwd)}" });`,
+    vue: `// main.ts (add to your entry file)
+import TraceBug from "tracebug-sdk";
+TraceBug.init({ projectId: "${path2.basename(cwd)}" });`,
+    svelte: `<!-- +layout.svelte (add to your root layout) -->
+<script>
+  import { onMount } from 'svelte';
+  import TraceBug from 'tracebug-sdk';
+  onMount(() => TraceBug.init({ projectId: "${path2.basename(cwd)}" }));
+</script>`,
+    angular: `// app.component.ts (add to constructor or ngOnInit)
+import TraceBug from "tracebug-sdk";
+TraceBug.init({ projectId: "${path2.basename(cwd)}" });`,
+    vanilla: `<!-- Add before </body> -->
+<script type="module">
+  import TraceBug from "tracebug-sdk";
+  TraceBug.init({ projectId: "${path2.basename(cwd)}" });
+</script>`,
+    nuxt: `// plugins/tracebug.client.ts (create this file)
+import TraceBug from "tracebug-sdk";
+export default defineNuxtPlugin(() => {
+  TraceBug.init({ projectId: "${path2.basename(cwd)}" });
+});`
+  };
+  console.log(`
+${BOLD}Add this to your project:${RESET}
+`);
+  console.log(`${DIM}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${RESET}`);
+  console.log(snippets[framework]);
+  console.log(`${DIM}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${RESET}`);
+  console.log(`
+${BOLD}Next steps:${RESET}
+  1. Install the SDK:  ${CYAN}npm install tracebug-sdk${RESET}
+  2. Add the snippet above to your app
+  3. Run your dev server and interact with your app
+  4. Click the TraceBug toolbar to see captured sessions
+
+${GREEN}Done!${RESET} TraceBug is ready. Happy debugging.
+`);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "tracebug",
+  "version": "1.5.0",
+  "description": "TraceBug CLI — local MCP server that lets AI coding agents (Claude Code, Cursor, VS Code) debug TraceBug bug-report exports, plus framework setup via `tracebug init`. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "tracebug": "./bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepublishOnly": "node -e \"if(!require('fs').existsSync('bin.mjs')){console.error('bin.mjs missing - run: npm run build:cli (from the repo root)');process.exit(1)}\""
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bug-reporting",
+    "debugging",
+    "claude-code",
+    "cursor",
+    "ai-agents",
+    "tracebug"
+  ],
+  "author": {
+    "name": "Prashant Singh Mangat",
+    "url": "https://github.com/prashantsinghmangat"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prashantsinghmangat/tracebug-ai.git",
+    "directory": "packages/tracebug"
+  },
+  "homepage": "https://tracebug.netlify.app/docs/mcp",
+  "bugs": {
+    "url": "https://github.com/prashantsinghmangat/tracebug-ai/issues"
+  }
+}