debug-run 0.5.7 → 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/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
       })
     );
   }
@@ -5224,12 +5242,161 @@ function resolveBreakpointPath(file, options = {}) {
   if (options.cwd) {
     return path10.resolve(options.cwd, file);
   }
-  if (options.programPath) {
-    const programDir = path10.dirname(options.programPath);
-    return path10.resolve(programDir, 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) {
@@ -5271,10 +5438,12 @@ var BreakpointManager = class {
   breakpoints = /* @__PURE__ */ new Map();
   nextId = 1;
   pathOptions;
-  constructor(client, formatter, pathOptions = {}) {
+  adapterType;
+  constructor(client, formatter, options = {}) {
     this.client = client;
     this.formatter = formatter;
-    this.pathOptions = pathOptions;
+    this.pathOptions = options;
+    this.adapterType = options.adapterType;
   }
   /**
    * Add a breakpoint from a spec string
@@ -5321,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 },
@@ -5333,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
+        );
       }
     }
   }
@@ -5378,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([
@@ -6171,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
       });
@@ -6180,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
       });
     }
@@ -6192,7 +6470,8 @@ var DebugSession = class {
     });
     this.breakpointManager = new BreakpointManager(this.client, this.formatter, {
       cwd: this.config.cwd,
-      programPath: this.config.program
+      programPath: this.config.program,
+      adapterType: this.config.adapter.name
     });
     this.variableInspector = new VariableInspector(this.client, {
       compactServices: !this.config.expandServices,
@@ -6993,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 });
     }
   );
@@ -7027,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.7",
+  "version": "0.5.8",
   "description": "CLI tool enabling AI agents to programmatically debug code via DAP",
   "type": "module",
   "main": "dist/index.cjs",