Refactor gems

.agents/codebase-insights.txt

@@ -1 +1,26 @@
-No insights yet. Please add content here and remove this line.
+# 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
+explosive amount of output and may appear as an infinite recursion when running
+`examples/selective_tracing_pure.rb`. To avoid this, `load_variables` now skips
+values that refer to the recorder or its `TraceRecord`.

.agents/tasks/2025/05/30-1219-refactor-gems

@@ -0,0 +1,19 @@
+A previous developer got the following task:
+
+> Make sure the functionality of both gems is usable as a library. The gem binaries
+> should just call into methods exported by the gem libraries. Make command-line
+> handling consistent between the two gems. Use class names that are derived from
+> the gem names.
+
+He made really good progress in commit d007872908d4fb5dbe862549f825eec98e7721f0, but
+he hasn't tested his code.
+
+Please test his changes and fix any issues that you find.
+
+He tried to implement one new feature:
+
+Both gem binaries now allow the standard "--" separator that specifies where
+the arguments of the executed program begin.
+
+Please add a test case that uses this notation to make sure its works correctly.
+Of course, keep the existing tests that don't use this notation.

.gitignore

@@ -4,7 +4,8 @@
 !test/benchmarks/fixtures/*.json
 test/tmp/
 .direnv/
-pkg/ 
+.idea/
+pkg/
 
 # Built ruby gems
 
@@ -14,4 +15,5 @@ pkg/
 .codex/deps_src/
 .codex/internet_resources/
 
-agents-workflow/
+# 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

MAINTAINERS.md

@@ -23,7 +23,7 @@ just build-extension
 
 This compiles the extension in release mode using Cargo. The resulting
 shared library is placed under
-`ext/native_tracer/target/release/` and is loaded by `gems/codetracer-ruby-recorder/lib/native_trace.rb`.
+`ext/native_tracer/target/release/` and is loaded by `gems/codetracer-ruby-recorder/lib/codetracer_ruby_recorder.rb`.
 
 ## Running tests
 

README.md

@@ -36,7 +36,7 @@ recorder.flush_trace(Dir.pwd)
 you can currently use it directly with
 
 ```bash
-ruby gems/codetracer-pure-ruby-recorder/lib/trace.rb [--out-dir DIR] <path to ruby file>
+ruby gems/codetracer-pure-ruby-recorder/bin/codetracer-pure-ruby-recorder [--out-dir DIR] <path to ruby file>
 # produces several trace json files in DIR,
 # or in `$CODETRACER_RUBY_RECORDER_OUT_DIR` if DIR is not provided.
 # Defaults to the current directory.
@@ -47,7 +47,7 @@ You can also invoke a lightweight CLI that loads the native tracer extension
 directly:
 
 ```bash
-ruby gems/codetracer-ruby-recorder/lib/native_trace.rb [--out-dir DIR] <path to ruby file>
+ruby gems/codetracer-ruby-recorder/bin/codetracer-ruby-recorder [--out-dir DIR] <path to ruby file>
 # Uses DIR or `$CODETRACER_RUBY_RECORDER_OUT_DIR` to choose where traces are saved.
 ```
 
@@ -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:
 

examples/selective_tracing.rb

@@ -1,13 +1,9 @@
 #!/usr/bin/env ruby
 
-# Load the native extension only if RubyRecorder is not already available
-# (e.g., when running directly without the codetracer wrapper)
-unless defined?(RubyRecorder)
-  ext_base = File.expand_path('../gems/codetracer-ruby-recorder/ext/native_tracer/target/release/libcodetracer_ruby_recorder', __dir__)
-  require ext_base
-end
+ext_base = File.expand_path('../gems/codetracer-ruby-recorder/ext/native_tracer/target/release/libcodetracer_ruby_recorder', __dir__)
+require ext_base
 
-recorder = RubyRecorder.new
+recorder = CodeTracer::RubyRecorder.new
 
 puts 'start trace'
 recorder.disable_tracing

examples/selective_tracing_pure.rb

@@ -1,18 +1,15 @@
 #!/usr/bin/env ruby
 
-# Load the pure Ruby tracer library if RubyRecorder is not already defined
-unless defined?(RubyRecorder)
-  lib_base = File.expand_path('../gems/codetracer-pure-ruby-recorder/lib/codetracer_pure_ruby_recorder', __dir__)
-  require lib_base
-end
+lib_base = File.expand_path('../gems/codetracer-pure-ruby-recorder/lib/codetracer_pure_ruby_recorder', __dir__)
+require lib_base
 
-recorder = RubyRecorder.new
+recorder = CodeTracer::PureRubyRecorder.new
 
 puts 'start trace'
-recorder.disable_tracing
+recorder.stop
 puts 'this will not be traced'
-recorder.enable_tracing
+recorder.start
 puts 'this will be traced'
-recorder.disable_tracing
+recorder.stop
 puts 'tracing disabled'
 recorder.flush_trace(Dir.pwd)

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/bin/codetracer-pure-ruby-recorder

@@ -1,4 +1,9 @@
 #!/usr/bin/env ruby
-require 'rbconfig'
-script = File.expand_path('../lib/trace.rb', __dir__)
-exec RbConfig.ruby, script, *ARGV
+# SPDX-License-Identifier: MIT
+# CLI for the pure Ruby tracer
+
+lib_dir = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+require 'codetracer_pure_ruby_recorder'
+
+exit CodeTracer::PureRubyRecorder.parse_argv_and_trace_ruby_file(ARGV)

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

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: MIT
 
-module Codetracer
+module CodeTracer
   module KernelPatches
     @@tracers = []
 
@@ -54,10 +54,6 @@ def self.uninstall(tracer)
           alias_method :p, :codetracer_original_p
           alias_method :puts, :codetracer_original_puts
           alias_method :print, :codetracer_original_print
-
-          remove_method :codetracer_original_p
-          remove_method :codetracer_original_puts
-          remove_method :codetracer_original_print
         end
       end
     end