debug-run 0.5.6 → 0.5.8

package/.claude/skills/debug-run/SKILL.md

@@ -34,6 +34,25 @@ Check available adapters:
 npx debug-run list-adapters
 ```
 
+## Installing the Skill
+
+To install this skill for AI coding assistants:
+
+```bash
+# Install to Claude Code (~/.claude/skills/)
+npx debug-run install-skill --claude
+
+# Install to GitHub Copilot (~/.copilot/skills/)
+npx debug-run install-skill --copilot
+
+# Install to project directory (for project-specific skills)
+npx debug-run install-skill --claude --project
+npx debug-run install-skill --copilot --project
+
+# Install to custom directory
+npx debug-run install-skill --dir /path/to/skills
+```
+
 ## Language-Specific Guides
 
 For detailed setup, examples, and troubleshooting for each language:

package/.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

package/README.md

@@ -178,6 +178,35 @@ debug-run outputs newline-delimited JSON (NDJSON) events:
 {"type":"session_end","summary":{"breakpointsHit":1,"duration":1234}}
 ```
 
+### Breakpoint Set Event (with Diagnostics)
+
+When a breakpoint cannot be verified (e.g., source mapping issues, missing debug symbols), the event includes actionable diagnostics:
+
+```json
+{
+  "type": "breakpoint_set",
+  "id": 1,
+  "file": "src/handler.ts",
+  "line": 45,
+  "verified": false,
+  "message": "Could not resolve source location",
+  "diagnostics": {
+    "requestedFile": "src/handler.ts",
+    "requestedLine": 45,
+    "adapterMessage": "Could not resolve source location",
+    "suggestions": [
+      "Ensure \"sourceMap\": true in tsconfig.json",
+      "Rebuild with source maps: tsc --sourceMap (or your build command)",
+      "Verify .map files exist in your output directory (e.g., dist/**/*.map)"
+    ],
+    "adapterType": "node",
+    "fileExtension": ".ts"
+  }
+}
+```
+
+Suggestions are context-aware based on the adapter and file type.
+
 ### Breakpoint Hit Event
 
 ```json

package/dist/index.cjs

@@ -3356,6 +3356,13 @@ function findVsdbg() {
   return null;
 }
 function findDebugpy() {
+  const debugpyExt = findExtension("ms-python.debugpy");
+  if (debugpyExt) {
+    const debugpyPath = path3.join(debugpyExt, "bundled", "libs", "debugpy");
+    if ((0, import_node_fs2.existsSync)(debugpyPath)) {
+      return debugpyPath;
+    }
+  }
   const pythonExt = findExtension("ms-python.python");
   if (pythonExt) {
     const possiblePaths = [
@@ -3517,6 +3524,16 @@ var debugpyAdapter = {
   get args() {
     return ["-m", "debugpy.adapter"];
   },
+  get env() {
+    if (cachedSource === "vscode" && cachedDebugpyPath) {
+      const debugpyParentDir = path5.dirname(cachedDebugpyPath);
+      const existingPythonPath = process.env.PYTHONPATH || "";
+      return {
+        PYTHONPATH: existingPythonPath ? `${debugpyParentDir}:${existingPythonPath}` : debugpyParentDir
+      };
+    }
+    return void 0;
+  },
   detect: async () => {
     const pythonCmd = await findPythonCommand();
     if (!pythonCmd) {
@@ -5189,7 +5206,7 @@ var OutputFormatter = class {
   /**
    * Emit a breakpoint_set event
    */
-  breakpointSet(id, file, line, verified, condition, message) {
+  breakpointSet(id, file, line, verified, condition, message, diagnostics) {
     this.emit(
       this.createEvent("breakpoint_set", {
         id,
@@ -5197,7 +5214,8 @@ var OutputFormatter = class {
         line,
         verified,
         condition,
-        message
+        message,
+        diagnostics
       })
     );
   }
@@ -5217,7 +5235,169 @@ var OutputFormatter = class {
 
 // src/session/breakpoints.ts
 var path10 = __toESM(require("node:path"), 1);
-function parseBreakpointSpec(spec) {
+function resolveBreakpointPath(file, options = {}) {
+  if (path10.isAbsolute(file)) {
+    return file;
+  }
+  if (options.cwd) {
+    return path10.resolve(options.cwd, file);
+  }
+  return path10.resolve(file);
+}
+function validateBreakpointSpec(spec) {
+  const trimmed = spec.trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: "Breakpoint specification cannot be empty",
+      spec
+    };
+  }
+  if (!trimmed.includes(":")) {
+    return {
+      valid: false,
+      error: `Invalid breakpoint format "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+      spec
+    };
+  }
+  const match = trimmed.match(/^(.+):(\d+)(?:\?(.+)|#(\d+))?$/);
+  if (!match) {
+    const colonIdx = trimmed.lastIndexOf(":");
+    if (colonIdx !== -1) {
+      const linePartRaw = trimmed.slice(colonIdx + 1);
+      const linePart = linePartRaw.split("?")[0].split("#")[0];
+      if (linePart === "") {
+        return {
+          valid: false,
+          error: `Missing line number in breakpoint "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+          spec
+        };
+      }
+      if (!/^\d+$/.test(linePart)) {
+        return {
+          valid: false,
+          error: `Invalid line number "${linePart}" in breakpoint "${spec}". Line must be a positive integer`,
+          spec
+        };
+      }
+    }
+    return {
+      valid: false,
+      error: `Invalid breakpoint format "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+      spec
+    };
+  }
+  const [, file, lineStr] = match;
+  const line = parseInt(lineStr, 10);
+  if (!file || !file.trim()) {
+    return {
+      valid: false,
+      error: `Missing file path in breakpoint "${spec}". Expected "file:line" (e.g., "Program.cs:42")`,
+      spec
+    };
+  }
+  if (isNaN(line) || line < 1) {
+    return {
+      valid: false,
+      error: `Invalid line number "${lineStr}" in breakpoint "${spec}". Line must be a positive integer`,
+      spec
+    };
+  }
+  return { valid: true };
+}
+function validateLogpointSpec(spec) {
+  const trimmed = spec.trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: "Logpoint specification cannot be empty",
+      spec
+    };
+  }
+  if (!trimmed.includes("|")) {
+    return {
+      valid: false,
+      error: `Invalid logpoint format "${spec}". Expected "file:line|message" (e.g., "Program.cs:42|value is {x}")`,
+      spec
+    };
+  }
+  const pipeIdx = trimmed.indexOf("|");
+  const beforePipe = trimmed.slice(0, pipeIdx);
+  if (!beforePipe.includes(":")) {
+    return {
+      valid: false,
+      error: `Invalid logpoint format "${spec}". Expected "file:line|message" (e.g., "Program.cs:42|value is {x}")`,
+      spec
+    };
+  }
+  const match = trimmed.match(/^(.+):(\d+)\|(.+)$/);
+  if (!match) {
+    const colonIdx = beforePipe.lastIndexOf(":");
+    if (colonIdx !== -1) {
+      const linePart = beforePipe.slice(colonIdx + 1);
+      if (linePart === "") {
+        return {
+          valid: false,
+          error: `Missing line number in logpoint "${spec}". Expected "file:line|message"`,
+          spec
+        };
+      }
+      if (!/^\d+$/.test(linePart)) {
+        return {
+          valid: false,
+          error: `Invalid line number "${linePart}" in logpoint "${spec}". Line must be a positive integer`,
+          spec
+        };
+      }
+    }
+    return {
+      valid: false,
+      error: `Invalid logpoint format "${spec}". Expected "file:line|message" (e.g., "Program.cs:42|value is {x}")`,
+      spec
+    };
+  }
+  const [, file, lineStr, message] = match;
+  const line = parseInt(lineStr, 10);
+  if (!file || !file.trim()) {
+    return {
+      valid: false,
+      error: `Missing file path in logpoint "${spec}". Expected "file:line|message"`,
+      spec
+    };
+  }
+  if (isNaN(line) || line < 1) {
+    return {
+      valid: false,
+      error: `Invalid line number "${lineStr}" in logpoint "${spec}". Line must be a positive integer`,
+      spec
+    };
+  }
+  if (!message || !message.trim()) {
+    return {
+      valid: false,
+      error: `Missing log message in logpoint "${spec}". Expected "file:line|message"`,
+      spec
+    };
+  }
+  return { valid: true };
+}
+function validateAllBreakpoints(breakpoints, logpoints = []) {
+  const errors = [];
+  for (const bp of breakpoints) {
+    const result = validateBreakpointSpec(bp);
+    if (!result.valid && result.error) {
+      errors.push(result.error);
+    }
+  }
+  for (const lp of logpoints) {
+    const result = validateLogpointSpec(lp);
+    if (!result.valid && result.error) {
+      errors.push(result.error);
+    }
+  }
+  return errors;
+}
+function parseBreakpointSpec(spec, pathOptions = {}) {
   const match = spec.match(/^(.+):(\d+)(?:\?(.+)|#(\d+))?$/);
   if (!match) {
     throw new Error(
@@ -5230,13 +5410,13 @@ function parseBreakpointSpec(spec) {
     throw new Error(`Invalid line number: ${lineStr}`);
   }
   return {
-    file: path10.resolve(file),
+    file: resolveBreakpointPath(file, pathOptions),
     line,
     condition: condition || void 0,
     hitCondition: hitCount || void 0
   };
 }
-function parseLogpointSpec(spec) {
+function parseLogpointSpec(spec, pathOptions = {}) {
   const match = spec.match(/^(.+):(\d+)\|(.+)$/);
   if (!match) {
     throw new Error(`Invalid logpoint format: "${spec}". Expected "file:line|log message"`);
@@ -5247,7 +5427,7 @@ function parseLogpointSpec(spec) {
     throw new Error(`Invalid line number: ${lineStr}`);
   }
   return {
-    file: path10.resolve(file),
+    file: resolveBreakpointPath(file, pathOptions),
     line,
     logMessage: logMessage.trim()
   };
@@ -5257,15 +5437,19 @@ var BreakpointManager = class {
   formatter;
   breakpoints = /* @__PURE__ */ new Map();
   nextId = 1;
-  constructor(client, formatter) {
+  pathOptions;
+  adapterType;
+  constructor(client, formatter, options = {}) {
     this.client = client;
     this.formatter = formatter;
+    this.pathOptions = options;
+    this.adapterType = options.adapterType;
   }
   /**
    * Add a breakpoint from a spec string
    */
   addBreakpoint(spec) {
-    const bp = parseBreakpointSpec(spec);
+    const bp = parseBreakpointSpec(spec, this.pathOptions);
     this.addBreakpointSpec(bp);
     return bp;
   }
@@ -5273,7 +5457,7 @@ var BreakpointManager = class {
    * Add a logpoint from a spec string
    */
   addLogpoint(spec) {
-    const lp = parseLogpointSpec(spec);
+    const lp = parseLogpointSpec(spec, this.pathOptions);
     this.addBreakpointSpec(lp);
     return lp;
   }
@@ -5306,6 +5490,7 @@ var BreakpointManager = class {
       hitCondition: spec.hitCondition,
       logMessage: spec.logMessage
     }));
+    const requestedLines = specs.map((spec) => spec.line);
     try {
       const response = await this.client.setBreakpoints({
         source: { path: file },
@@ -5318,22 +5503,34 @@ var BreakpointManager = class {
           specs[i].verified = bp.verified;
           specs[i].message = bp.message;
           specs[i].line = bp.line ?? specs[i].line;
+          const diagnostics = !bp.verified ? this.generateDiagnostics(file, requestedLines[i], bp.message) : void 0;
           this.formatter.breakpointSet(
             specs[i].id,
             file,
             specs[i].line,
             specs[i].verified,
             specs[i].condition,
-            specs[i].message
+            specs[i].message,
+            diagnostics
           );
         }
       }
     } catch (error) {
-      for (const spec of specs) {
+      for (let i = 0; i < specs.length; i++) {
+        const spec = specs[i];
         spec.id = this.nextId++;
         spec.verified = false;
         spec.message = error instanceof Error ? error.message : "Failed to set breakpoint";
-        this.formatter.breakpointSet(spec.id, file, spec.line, false, spec.condition, spec.message);
+        const diagnostics = this.generateDiagnostics(file, requestedLines[i], spec.message);
+        this.formatter.breakpointSet(
+          spec.id,
+          file,
+          spec.line,
+          false,
+          spec.condition,
+          spec.message,
+          diagnostics
+        );
       }
     }
   }
@@ -5363,7 +5560,103 @@ var BreakpointManager = class {
   getHitCount() {
     return 0;
   }
+  /**
+   * Generate diagnostics for an unverified breakpoint
+   */
+  generateDiagnostics(requestedFile, requestedLine, adapterMessage) {
+    const ext = path10.extname(requestedFile).toLowerCase();
+    const suggestions = getBreakpointSuggestions(this.adapterType, ext, adapterMessage);
+    return {
+      requestedFile,
+      requestedLine,
+      adapterMessage,
+      suggestions,
+      adapterType: this.adapterType,
+      fileExtension: ext || void 0
+    };
+  }
 };
+function normalizeAdapterType(adapterType) {
+  if (!adapterType) return void 0;
+  const lower = adapterType.toLowerCase();
+  if (["dotnet", "coreclr", "vsdbg", "netcoredbg"].includes(lower)) {
+    return "coreclr";
+  }
+  if (["node", "nodejs", "javascript", "js", "typescript", "ts"].includes(lower)) {
+    return "node";
+  }
+  if (["debugpy", "python", "py"].includes(lower)) {
+    return "python";
+  }
+  if (["lldb", "codelldb", "cpp", "c", "rust"].includes(lower)) {
+    return "lldb";
+  }
+  return lower;
+}
+function getBreakpointSuggestions(adapterType, fileExtension, adapterMessage) {
+  const suggestions = [];
+  const normalizedAdapter = normalizeAdapterType(adapterType);
+  const ext = fileExtension.toLowerCase();
+  const msgLower = (adapterMessage || "").toLowerCase();
+  const isSourceMapIssue = msgLower.includes("source map") || msgLower.includes("sourcemap") || msgLower.includes("cannot find");
+  const isPathIssue = msgLower.includes("not found") || msgLower.includes("cannot find file") || msgLower.includes("does not exist");
+  if (normalizedAdapter === "node") {
+    if (ext === ".ts" || ext === ".tsx") {
+      suggestions.push('Ensure "sourceMap": true in tsconfig.json');
+      suggestions.push("Rebuild with source maps: tsc --sourceMap (or your build command)");
+      suggestions.push("Verify .map files exist in your output directory (e.g., dist/**/*.map)");
+      suggestions.push(
+        'Check that "sourceMaps": true is set in your debug config and "outFiles" points to your built JS files'
+      );
+    } else if (ext === ".js" || ext === ".mjs" || ext === ".cjs") {
+      suggestions.push(
+        "Confirm you are setting the breakpoint in the executed file (built output vs source)"
+      );
+      if (isSourceMapIssue) {
+        suggestions.push(
+          "If using bundlers (webpack/esbuild/vite), ensure source maps are generated and accessible"
+        );
+        suggestions.push("Verify source map files (.map) are not excluded from your output");
+      }
+    }
+  } else if (normalizedAdapter === "coreclr") {
+    if (ext === ".cs") {
+      suggestions.push("Build in Debug configuration to ensure PDB files are produced");
+      suggestions.push("Clean and rebuild to refresh symbols: dotnet clean && dotnet build");
+      suggestions.push(
+        "Confirm the running binary matches the source version (stale builds can break mapping)"
+      );
+      suggestions.push("Ensure PDB files are deployed alongside the DLL");
+    }
+  } else if (normalizedAdapter === "python") {
+    if (ext === ".py") {
+      suggestions.push("Confirm the Python interpreter and working directory match your project");
+      suggestions.push(
+        "If debugging remotely or in containers, configure path mappings (localRoot/remoteRoot)"
+      );
+      suggestions.push(
+        "Verify you are setting the breakpoint in code that actually executes (imported module vs different copy)"
+      );
+    }
+  } else if (normalizedAdapter === "lldb") {
+    if ([".c", ".cpp", ".cc", ".cxx", ".h", ".hpp", ".rs", ".m", ".mm"].includes(ext)) {
+      suggestions.push("Compile with debug symbols (-g) and avoid stripping binaries");
+      suggestions.push("Ensure the running binary matches the source used to compile");
+      suggestions.push("For Rust, build with: cargo build (debug mode, not --release)");
+    }
+  }
+  if (isPathIssue) {
+    suggestions.push("Check the file path is correct and exists relative to the provided cwd");
+  }
+  if (suggestions.length === 0) {
+    suggestions.push("Check the file path is correct and exists relative to the provided cwd");
+    suggestions.push(
+      "Ensure the running program corresponds to this source (no stale build artifacts)"
+    );
+    suggestions.push("Verify the file has been compiled/built with debug information");
+  }
+  return suggestions;
+}
 
 // src/session/variables.ts
 var BLOCKED_PROPERTIES = /* @__PURE__ */ new Set([
@@ -5437,7 +5730,8 @@ var VariableInspector = class {
       timeout: options.timeout ?? 5e3,
       deduplicateByContent: options.deduplicateByContent ?? true,
       compactServices: options.compactServices ?? true,
-      omitNullProperties: options.omitNullProperties ?? true
+      omitNullProperties: options.omitNullProperties ?? true,
+      captureClosures: options.captureClosures ?? false
     };
   }
   /**
@@ -5449,14 +5743,38 @@ var VariableInspector = class {
     const contentHashes = /* @__PURE__ */ new Map();
     try {
       const scopesResponse = await this.client.scopes({ frameId });
+      let foundPrimaryLocals = false;
       for (const scope of scopesResponse.scopes) {
-        if (scope.name === "Locals" || scope.name === "Arguments" || scope.name === "Local") {
-          const vars = await this.client.variables({
-            variablesReference: scope.variablesReference,
-            count: this.options.maxCollectionItems
-          });
-          for (const v of vars.variables) {
-            result[v.name] = await this.expandVariable(
+        const scopeLower = scope.name.toLowerCase();
+        const isPrimaryLocals = scopeLower === "locals" || scopeLower === "local" || scopeLower.startsWith("local:") || scopeLower.startsWith("local ");
+        const isArguments = scopeLower === "arguments" || scopeLower.startsWith("arg");
+        const isBlockOrClosure = scopeLower === "block" || scopeLower === "closure";
+        const shouldInclude = isPrimaryLocals || isArguments || isBlockOrClosure && (this.options.captureClosures || !foundPrimaryLocals);
+        if (!shouldInclude) continue;
+        if (isPrimaryLocals) {
+          foundPrimaryLocals = true;
+        }
+        const vars = await this.client.variables({
+          variablesReference: scope.variablesReference,
+          count: this.options.maxCollectionItems
+        });
+        for (const v of vars.variables) {
+          let varName = v.name;
+          if (varName in result) {
+            const existingValue = result[varName];
+            const newValue = await this.expandVariable(
+              v,
+              this.options.maxDepth,
+              visited,
+              contentHashes,
+              v.name
+            );
+            if (!this.valuesEqual(existingValue, newValue)) {
+              varName = `${v.name} (${scope.name})`;
+              result[varName] = newValue;
+            }
+          } else {
+            result[varName] = await this.expandVariable(
               v,
               this.options.maxDepth,
               visited,
@@ -6131,7 +6449,7 @@ var DebugSession = class {
         command: this.config.adapter.command,
         args: this.config.adapter.args,
         cwd: this.config.cwd,
-        env: this.config.env,
+        env: { ...this.config.adapter.env, ...this.config.env },
         port: this.config.adapter.socketPort,
         timeout: this.config.timeout
       });
@@ -6140,7 +6458,7 @@ var DebugSession = class {
         command: this.config.adapter.command,
         args: this.config.adapter.args,
         cwd: this.config.cwd,
-        env: this.config.env,
+        env: { ...this.config.adapter.env, ...this.config.env },
         timeout: this.config.timeout
       });
     }
@@ -6150,7 +6468,11 @@ var DebugSession = class {
     await this.client.initialize({
       adapterID: this.config.adapter.id
     });
-    this.breakpointManager = new BreakpointManager(this.client, this.formatter);
+    this.breakpointManager = new BreakpointManager(this.client, this.formatter, {
+      cwd: this.config.cwd,
+      programPath: this.config.program,
+      adapterType: this.config.adapter.name
+    });
     this.variableInspector = new VariableInspector(this.client, {
       compactServices: !this.config.expandServices,
       omitNullProperties: !this.config.showNullProps,
@@ -6950,6 +7272,16 @@ function createCli() {
         console.error(`Available adapters: ${getAdapterNames().join(", ")}`);
         process.exit(1);
       }
+      const breakpointErrors = validateAllBreakpoints(
+        options.breakpoint || [],
+        options.logpoint || []
+      );
+      if (breakpointErrors.length > 0) {
+        for (const error of breakpointErrors) {
+          console.error(`Error: ${error}`);
+        }
+        process.exit(1);
+      }
       await runDebugSession({ ...options, program: programPath, adapter: options.adapter });
     }
   );
@@ -6984,6 +7316,13 @@ async function runTestDebugSession(options) {
     console.error('Example: -b "path/to/TestFile.cs:42"');
     process.exit(1);
   }
+  const breakpointErrors = validateAllBreakpoints(options.breakpoint || [], options.logpoint || []);
+  if (breakpointErrors.length > 0) {
+    for (const error of breakpointErrors) {
+      console.error(`Error: ${error}`);
+    }
+    process.exit(1);
+  }
   console.error(`Starting test runner for: ${options.testProject}`);
   if (options.testFilter) {
     console.error(`Test filter: ${options.testFilter}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "debug-run",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "CLI tool enabling AI agents to programmatically debug code via DAP",
   "type": "module",
   "main": "dist/index.cjs",
@@ -37,7 +37,7 @@
     "prettier": "^3.8.0",
     "tsx": "^4.21.0",
     "typescript": "^5.3.0",
-    "vitest": "^1.0.0"
+    "vitest": "^4.0.17"
   },
   "engines": {
     "node": ">=18.0.0"