feat: Add debugging support

Author: zah

.agents/codebase-insights.txt

@@ -1,3 +1,23 @@
+# Critical Architecture Notes
+
+## Ruby Debugging Setup
+- VS Code debugging is configured with rdbg (Ruby Debug) support
+- Use the rdbg-wrapper script in scripts/ to avoid hardcoded paths
+- Debug configurations available:
+  - "Debug Current Ruby File" - Debug the currently open Ruby file
+  - "Debug Current Test File" - Debug test files with proper load paths
+  - "Debug All Tests" - Debug the main test runner
+- For interactive debugging with Pry, use the "Debug Current Test with Pry" task
+- The Ruby LSP is configured for full language support features
+
+## Debugging Gem Installation
+- To use debugging features, install: `gem install debug pry`
+- The debug gem is required for VS Code rdbg debugging
+- Pry is used for interactive debugging tasks
+- Native compilation may fail in nix environment due to missing headers
+- Alternative: Use system Ruby for gem installation if nix environment has issues
+
+## Codetracer Architecture
 When the pure Ruby recorder traces a script that holds a reference to the
 `PureRubyRecorder` instance in a local variable, the variable inspection code
 would recursively serialise the tracer's internal state. This results in an

.gitignore

@@ -14,3 +14,6 @@ pkg/
 # Offline dependency sources
 .codex/deps_src/
 .codex/internet_resources/
+
+# JetBrains IDES 
+.idea/

.vscode/README.md

@@ -0,0 +1,86 @@
+# Ruby Debugging Setup for VS Code
+
+This repository includes a comprehensive Ruby debugging setup for Visual Studio Code, similar to the one in the agents-workflow repository.
+
+## Files Created
+
+### VS Code Configuration (`.vscode/`)
+
+- **`tasks.json`** - VS Code tasks for running and debugging Ruby code
+- **`launch.json`** - Debug configurations for rdbg debugger
+- **`settings.json`** - Ruby LSP settings and debugging preferences
+
+### Scripts
+
+- **`scripts/rdbg-wrapper`** - Wrapper script to locate and run rdbg without hardcoded paths
+
+## Available Tasks
+
+Use `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux) and search for "Tasks: Run Task":
+
+1. **Run Current Test File** - Execute the currently open test file
+2. **Run All Tests** - Execute all tests using the main test runner
+3. **Debug Current Test with Pry** - Run current test with Pry for interactive debugging
+4. **Simple Test Run (No Debug)** - Basic test execution without debug features
+
+## Debug Configurations
+
+Use the Debug panel (F5 or Run → Start Debugging):
+
+1. **Debug Current Ruby File** - Debug any Ruby file with rdbg
+2. **Debug Current Test File** - Debug test files with proper load paths
+3. **Debug All Tests** - Debug the complete test suite
+
+## Required Gems
+
+To use the debugging features, install these gems:
+
+```bash
+gem install debug pry
+```
+
+### For Nix Users
+
+If you're using the nix development environment and encounter compilation issues:
+
+1. Use system Ruby for gem installation:
+
+   ```bash
+   # Exit nix shell first
+   gem install debug pry
+   ```
+
+2. Or install globally and ensure they're available in PATH
+
+## Usage
+
+1. **Setting Breakpoints**: Click in the gutter next to line numbers or use `F9`
+2. **Interactive Debugging**: Use the "Debug Current Test with Pry" task for REPL-style debugging
+3. **Variable Inspection**: Hover over variables or use the Variables panel during debugging
+4. **Step Through Code**: Use F10 (step over), F11 (step into), Shift+F11 (step out)
+
+## Ruby LSP Features
+
+The setup includes full Ruby Language Server Protocol support:
+
+- Code completion and IntelliSense
+- Go to definition/implementation
+- Syntax highlighting and error detection
+- Code formatting and refactoring
+- Document symbols and workspace search
+
+## Troubleshooting
+
+- **"debug gem not found"**: Install the debug gem with `gem install debug`
+- **Compilation errors in nix**: Try using system Ruby for gem installation
+- **rdbg not found**: The rdbg-wrapper script should handle this automatically
+- **Breakpoints not working**: Ensure the debug gem is installed and accessible
+
+## Integration with Editor
+
+The configuration integrates seamlessly with VS Code's built-in features:
+
+- Debug console for evaluating expressions
+- Call stack navigation
+- Automatic variable inspection
+- Terminal integration for task execution

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

GEMINI.md

@@ -0,0 +1 @@
+AGENTS.md

Gemfile

@@ -4,3 +4,7 @@ source "https://rubygems.org"
 
 gem "codetracer-ruby-recorder", path: "gems/codetracer-ruby-recorder"
 gem "codetracer-pure-ruby-recorder", path: "gems/codetracer-pure-ruby-recorder"
+
+# Development and debugging gems (optional - install separately if needed)
+# gem "debug", "~> 1.7"      # Ruby debugging with rdbg
+# gem "pry", "~> 0.14"       # Interactive debugging and REPL

README.md

@@ -58,13 +58,40 @@ however you probably want to use it in combination with CodeTracer, which would
 * if you pass `CODETRACER_RUBY_RECORDER_DEBUG=1`, you enable some additional debug-related logging
 * `CODETRACER_RUBY_RECORDER_OUT_DIR` can be used to specify the directory for trace files
 
+## Development Setup
+
+This repository includes a comprehensive Ruby debugging setup for Visual Studio Code. See [`.vscode/README.md`](.vscode/README.md) for detailed information about:
+
+* VS Code tasks for running and debugging Ruby code
+* Debug configurations for rdbg debugger  
+* Ruby LSP integration for full language support
+* Interactive debugging with Pry
+
+### Quick Start for Contributors
+
+1. **Install debugging gems** (if not using nix):
+
+   ```bash
+   gem install debug pry
+   ```
+
+2. **Use VS Code tasks**: Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and search for "Tasks: Run Task"
+
+3. **Debug with F5**: Use the debug panel to set breakpoints and step through code
+
+4. **Run tests**: Use the provided tasks or run manually:
+
+   ```bash
+   ruby -I lib -I test test/test_tracer.rb
+   ```
+
 ## Future directions
 
 The current Ruby support is a prototype. In the future, it may be expanded to function in a way similar to the more complete implementations, e.g. [Noir](https://github.com/blocksense-network/noir/tree/blocksense/tooling/tracer).
 
 ### Current approach: TracePoint API
 
-Currently we're using the TracePoint API: https://rubyapi.org/3.4/o/tracepoint .
+Currently we're using the [TracePoint API](https://rubyapi.org/3.4/o/tracepoint).
 This is very flexible and can function with probably multiple Ruby versions out of the box.
 However, this is limited:
 

flake.nix

@@ -37,6 +37,10 @@
           # C standard library headers required for Ruby C extension compilation on Linux
           # Without this, build fails with "stdarg.h file not found" error
           glibc.dev
+        ] ++ pkgs.lib.optionals isDarwin [
+          # Required for Ruby C extension compilation on macOS
+          darwin.apple_sdk.frameworks.CoreFoundation
+          darwin.apple_sdk.frameworks.Security
         ];
 
         # Environment variables required to fix build issues with rb-sys/bindgen

gems/codetracer-pure-ruby-recorder/lib/recorder.rb

@@ -394,7 +394,7 @@ def to_value(v, depth=10)
         end)
       end
     when Hash
-      if true or v.count > MAX_COUNT
+      if v.count > MAX_COUNT
         not_supported_value
       else
         pairs = v.map do |k, val|

scripts/rdbg-wrapper

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Wrapper script to launch rdbg without hardcoded paths
+# On Windows, rdbg doesn't place any executable binaries in the system
+# PATH for some reason, so this script discovers the debug gem path and
+# executes the main rdbg script directly
+
+begin
+  require 'debug'
+
+  # Find the rdbg executable in the debug gem
+  debug_gem_spec = Gem.loaded_specs['debug']
+  if debug_gem_spec.nil?
+    puts 'Error: debug gem not found. Install with: gem install debug'
+    exit 1
+  end
+
+  rdbg_path = File.join(debug_gem_spec.full_gem_path, 'exe', 'rdbg')
+
+  unless File.exist?(rdbg_path)
+    puts "Error: rdbg executable not found at #{rdbg_path}"
+    exit 1
+  end
+
+  # Set up ARGV to match what rdbg expects
+  # The rdbg script reads from ARGV directly
+  original_argv = ARGV.dup
+  ARGV.replace(original_argv)
+
+  # Load and execute the rdbg script
+  load rdbg_path
+rescue LoadError => e
+  puts "Error loading debug gem: #{e.message}"
+  puts 'Install with: gem install debug'
+  exit 1
+rescue StandardError => e
+  puts "Error: #{e.message}"
+  exit 1
+end