debug-agent 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f71863664d8e95b34f553c692cfc6de2328151f3496dc5bb92ba309232dc3b52
-  data.tar.gz: ab521965229d38b7e8a2ae4fd56a466170219865863573bad59fbe8676f14ce6
+  metadata.gz: 7b9c945dc45966ff8c9d06b0679357d54ba9dc443d5ee68c532ae1058878c6e4
+  data.tar.gz: a986e568c59ca3f8d04f71d647ba0649bbbff7659f021eca349bc3cce3b3b044
 SHA512:
-  metadata.gz: 01edd9b04e2c7054f6f247536eb85af48db98eb6c6367b4d863ea477b49388b347ad1a78d1758548caf965f483f10b432d979f397af8947e482ab3283104e0b6
-  data.tar.gz: cf20b7101a695433ddc35d6e4654d99555e50c7220fa8e4132e1495e6e9cadc88c1b217db487a5f9973c5a4a358ce2d6368bff3d65fbb9968ed420d2ee46d7a5
+  metadata.gz: 90d75283c6f362c3be78a419923c26d622aa6d55ed3d29ebfca1c40341d7d264a9a6074fd30e93140fb13db44991a8a52261d0695a2df22bcf1e17e865f793bb
+  data.tar.gz: 319d197cd23d9c9fd15845dc4a8a896b2560d3da83b85ac69e9687ba4ce3495ed1b720089ce82cc6adef8497e570177078f9430191bbca260a32a230f68171aa

data/README.md

@@ -1,10 +1,26 @@
 # Ruby Debug Agent
 
 [![Gem Version](https://img.shields.io/badge/gem-debug--agent-red)](https://github.com/topcheer/ruby-debug-agent)
-![Tools](https://img.shields.io/badge/tools-54-blue)
-![Inspectors](https://img.shields.io/badge/inspectors-20-green)
+![Tools](https://img.shields.io/badge/tools-84-blue)
+![Inspectors](https://img.shields.io/badge/inspectors-31-green)
+![Ruby](https://img.shields.io/badge/Ruby-2.7%2B-CC342D)
+![Gem](https://img.shields.io/badge/gem-debug--agent-red)
 
-An AI-powered runtime debugging agent that embeds directly into your Ruby application. Add one gem, configure an LLM key, and chat with your live app at `/agent` to inspect GC, ObjectSpace, threads, routes, Redis, Rails models/routes, Sidekiq queues, Puma stats, fibers/signals, process info, HTTP requests, and more — **54 diagnostic tools across 20 inspectors**.
+An AI-powered runtime debugging agent that embeds directly into your Ruby application. Add one gem, configure an LLM key, and chat with your live app at `/agent` to inspect GC, ObjectSpace, threads, routes, Redis, Rails models/routes, Sidekiq queues, Puma stats, fibers/signals, process info, HTTP requests, and more — **84 diagnostic tools across 31 inspectors**.
+
+## Version Support
+
+| Ruby Version | Status |
+|--------------|--------|
+| 2.6          | Not supported |
+| 2.7          | Minimum supported |
+| 3.0          | Supported (Fiber.list available) |
+| 3.1          | Supported |
+| 3.2          | Supported |
+| 3.3          | Supported |
+| 3.4          | Tested |
+
+> Requires Ruby 2.7+ for pattern matching guards. Framework inspectors (Rails, Sidekiq, Puma) are optional and auto-detected via `defined?`.
 
 ## Quick Start
 
@@ -55,10 +71,10 @@ http://localhost:4567/agent
 - **Context compression** — automatically summarizes old conversation when token limit is approached
 - **Dark-themed chat UI** with full markdown rendering (tables, code blocks, lists)
 - **Max tool rounds** (25) with forced final summary when limit is reached
-- **54 diagnostic tools** across **20 inspectors**
+- **84 diagnostic tools** across **31 inspectors**
 - Zero external dependencies (no Datadog, no Grafana, no APM)
 
-## Inspectors & Tools (54)
+## Inspectors & Tools (84)
 
 ### GC Inspector
 | Tool | Description |
@@ -193,6 +209,47 @@ http://localhost:4567/agent
 |------|-------------|
 | `get_concurrent_state` | Ruby concurrency primitives state (Mutex, ConditionVariable, Queue) |
 
+### Deadlock & Lock Contention Inspector (v0.6.0)
+| Tool | Description |
+|------|-------------|
+| `get_lock_contention` | Mutex contention stats (wait time, hold time, acquisition count) |
+| `detect_deadlock` | Analyze all threads for deadlock patterns (circular wait detection) |
+| `get_mutex_stats` | Per-lock statistics: total acquisitions, contentions, average wait time |
+
+### Database Migration Inspector (v0.6.0)
+| Tool | Description |
+|------|-------------|
+| `get_migration_status` | Current schema version, applied count, last migration applied |
+| `get_pending_migrations` | Migrations not yet applied (version, description, dependencies) |
+| `get_migration_history` | Applied migration history (version, applied_at, duration_ms) |
+
+### Configuration Inspector (v0.6.0)
+| Tool | Description |
+|------|-------------|
+| `get_config_snapshot` | All registered config values (sensitive keys masked) |
+| `get_env_vars_masked` | Process environment variables with secret values redacted |
+| `get_config_sources` | Config source hierarchy (env, file, defaults) with effective values |
+
+### Feature Flags Inspector (v0.6.0)
+| Tool | Description |
+|------|-------------|
+| `get_feature_flags` | List all registered feature flags with current state |
+| `evaluate_feature_flag` | Evaluate a specific flag for a given context/user |
+
+### Endpoint Testing Inspector (v0.6.0)
+| Tool | Description |
+|------|-------------|
+| `test_endpoint` | Make an HTTP request to own app, return full response (status, headers, body) |
+| `batch_test_endpoints` | Test multiple endpoints in one call with aggregated results |
+| `get_endpoint_coverage` | Compare registered routes vs tested endpoints (coverage report) |
+
+### Connection Pool Inspector (v0.6.0)
+| Tool | Description |
+|------|-------------|
+| `get_pool_details` | Detailed DB pool stats (pool size, active, idle, waiting, max) |
+| `detect_pool_leaks` | Heuristic leak detection (growing pool, high wait ratio, saturation) |
+| `get_pool_wait_stats` | Connection acquire wait stats (avg, P95, max wait, timeout count) |
+
 ## Custom Tools
 
 ```ruby

data/lib/debug_agent/inspectors/config_inspector.rb

@@ -0,0 +1,137 @@
+require 'time'
+
+module DebugAgent
+  # Register configuration hashes for inspection.
+  #
+  #   DebugAgent.register_config(:app, {
+  #     app_name: 'MyApp',
+  #     port: 4567,
+  #     api_key: 'secret123'
+  #   })
+  @registered_configs = {}
+
+  SENSITIVE_KEY_PATTERN = /password|secret|token|api.?key|private.?key|credential/i
+
+  class << self
+    attr_reader :registered_configs
+
+    def register_config(name, config_hash, source: 'registered')
+      @registered_configs[name.to_s] = {
+        values: config_hash,
+        source: source,
+        registered_at: Time.now.iso8601
+      }
+    end
+  end
+
+  class << self
+    private
+
+    def mask_sensitive(key, value)
+      return value unless value.is_a?(String) || value.is_a?(Symbol)
+      return '***' if key.to_s =~ SENSITIVE_KEY_PATTERN
+      value
+    end
+
+    def mask_config_hash(hash)
+      hash.map do |k, v|
+        if v.is_a?(Hash)
+          [k, mask_config_hash(v)]
+        else
+          [k, mask_sensitive(k, v)]
+        end
+      end.to_h
+    end
+  end
+
+  register_tool('get_config_snapshot',
+                'Get all registered configuration values. Sensitive keys (password, secret, ' \
+                'token, api_key, etc.) are automatically masked') do
+    if registered_configs.empty?
+      next { error: 'No configs registered. Call DebugAgent.register_config(:name, hash).' }
+    end
+
+    configs = registered_configs.map do |name, entry|
+      {
+        name: name,
+        source: entry[:source],
+        registered_at: entry[:registered_at],
+        values: mask_config_hash(entry[:values] || {}),
+        key_count: (entry[:values] || {}).size,
+        masked_keys: (entry[:values] || {}).keys.select { |k| k.to_s =~ SENSITIVE_KEY_PATTERN }
+      }
+    end
+
+    {
+      total_configs: configs.size,
+      configs: configs
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_env_vars',
+                'Dump environment variables (ENV) with optional prefix filter. ' \
+                'Sensitive values are automatically masked',
+                prefix: { type: 'string', description: 'Only return vars starting with this prefix (e.g. APP_, RAILS_)', required: false }) do |prefix: nil|
+    vars = ENV.to_h
+
+    if prefix && !prefix.to_s.empty?
+      vars = vars.select { |k, _| k.start_with?(prefix.to_s) }
+    end
+
+    masked = {}
+    sensitive_count = 0
+    vars.each do |k, v|
+      if k =~ SENSITIVE_KEY_PATTERN
+        masked[k] = '***'
+        sensitive_count += 1
+      else
+        masked[k] = v
+      end
+    end
+
+    {
+      total_vars: masked.size,
+      sensitive_masked: sensitive_count,
+      prefix_filter: prefix,
+      env_vars: masked
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_config_sources',
+                'Configuration provenance: shows where each registered config comes from ' \
+                '(environment, file, default, or registered)') do
+    if registered_configs.empty?
+      next { error: 'No configs registered. Call DebugAgent.register_config(:name, hash).' }
+    end
+
+    sources = registered_configs.map do |name, entry|
+      {
+        name: name,
+        source: entry[:source],
+        registered_at: entry[:registered_at],
+        keys: (entry[:values] || {}).keys
+      }
+    end
+
+    # Also show ENV as a config source
+    env_config_count = ENV.size
+
+    {
+      registered_config_sources: sources,
+      total_sources: sources.size,
+      env_var_count: env_config_count,
+      summary: {
+        registered: sources.count { |s| s[:source] == 'registered' },
+        file: sources.count { |s| s[:source] == 'file' },
+        env: sources.count { |s| s[:source] == 'env' },
+        default: sources.count { |s| s[:source] == 'default' }
+      }
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/endpoint_test.rb

@@ -0,0 +1,284 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'time'
+
+module DebugAgent
+  @tested_routes = []
+  @tested_routes_lock = Mutex.new
+
+  class << self
+    attr_reader :tested_routes
+
+    def record_tested_route(method, path, status, duration_ms)
+      @tested_routes_lock.synchronize do
+        @tested_routes << {
+          method: method,
+          path: path,
+          status: status,
+          duration_ms: duration_ms,
+          tested_at: Time.now.iso8601
+        }
+        @tested_routes.shift if @tested_routes.size > 500
+      end
+    end
+
+    def reset_tested_routes
+      @tested_routes_lock.synchronize { @tested_routes.clear }
+    end
+  end
+
+  class << self
+    private
+
+    def app_port
+      app = DebugAgent.app
+      if app
+        app_class = app.is_a?(Class) ? app : app.class
+        if app_class.respond_to?(:port)
+          return app_class.port
+        end
+        if app_class.respond_to?(:settings) && app_class.settings.respond_to?(:port)
+          return app_class.settings.port
+        end
+      end
+      # Common defaults
+      ENV['PORT']&.to_i || 4567
+    end
+
+    def app_host
+      'localhost'
+    end
+
+    def perform_http_request(method, path, headers, body)
+      port = app_port
+      host = app_host
+
+      uri = URI("http://#{host}:#{port}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.read_timeout = 30
+      http.open_timeout = 10
+
+      request_method = Net::HTTP.const_get(method.capitalize)
+      req = request_method.new(uri.request_uri)
+
+      # Set headers
+      headers&.each do |k, v|
+        req[k.to_s] = v.to_s
+      end
+
+      # Set body if provided
+      if body && !body.to_s.empty?
+        req['Content-Type'] ||= 'application/json'
+        req.body = body.to_s
+      end
+
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = http.request(req)
+      duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+
+      resp_body = response.body
+      parsed_body = nil
+      begin
+        parsed_body = JSON.parse(resp_body) if resp_body && !resp_body.empty?
+      rescue JSON::ParserError
+        parsed_body = resp_body
+      end
+
+      {
+        status: response.code.to_i,
+        status_message: response.message,
+        headers: response.each_header.to_h,
+        body: parsed_body,
+        duration_ms: duration,
+        method: method,
+        path: path,
+        url: uri.to_s
+      }
+    rescue Errno::ECONNREFUSED
+      { error: "Connection refused — app not running on #{host}:#{app_port}" }
+    rescue => e
+      { error: "Request failed: #{e.message}", method: method, path: path }
+    end
+  end
+
+  register_tool('test_endpoint',
+                'Send an HTTP request to your own running app. Returns status, headers, body, ' \
+                'and duration. Useful for testing API endpoints from the debug agent',
+                method: { type: 'string', description: 'HTTP method: GET, POST, PUT, DELETE, PATCH', required: true },
+                path: { type: 'string', description: 'Request path (e.g. /api/orders)', required: true },
+                headers: { type: 'object', description: 'Optional HTTP headers as key-value pairs (e.g. {"X-API-Key": "demo-key-12345"})', required: false },
+                body: { type: 'string', description: 'Optional request body (JSON string for POST/PUT)', required: false }) do |method:, path:, headers: nil, body: nil|
+    method_up = method.to_s.upcase
+    unless %w[GET POST PUT DELETE PATCH HEAD OPTIONS].include?(method_up)
+      next { error: "Unsupported HTTP method: #{method}. Use GET, POST, PUT, DELETE, PATCH, HEAD, or OPTIONS." }
+    end
+
+    result = perform_http_request(method_up, path, headers, body)
+
+    if result[:error]
+      next result
+    end
+
+    record_tested_route(method_up, path, result[:status], result[:duration_ms])
+
+    result
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('batch_test_endpoints',
+                'Run multiple endpoint tests with assertions. Each test specifies method, path, ' \
+                'optional headers/body, and optional assertions (expected_status, expected_body_contains)',
+                tests: { type: 'array', description: 'Array of test objects: {method, path, headers?, body?, expected_status?, expected_body_contains?}', required: true }) do |tests:|
+    unless tests.is_a?(Array)
+      next { error: 'tests must be an array of test objects' }
+    end
+
+    results = tests.map do |test|
+      test = test.is_a?(Hash) ? test : {}
+      method = (test['method'] || test[:method] || 'GET').to_s.upcase
+      path = test['path'] || test[:path]
+      headers = test['headers'] || test[:headers]
+      body = test['body'] || test[:body]
+
+      unless path
+        next { method: method, path: '(missing)', error: 'Missing required field: path' }
+      end
+
+      http_result = perform_http_request(method, path, headers, body)
+
+      if http_result[:error]
+        next { method: method, path: path, error: http_result[:error], passed: false }
+      end
+
+      record_tested_route(method, path, http_result[:status], http_result[:duration_ms])
+
+      # Run assertions
+      passed = true
+      failures = []
+
+      expected_status = test['expected_status'] || test[:expected_status]
+      if expected_status && http_result[:status] != expected_status.to_i
+        passed = false
+        failures << "Expected status #{expected_status}, got #{http_result[:status]}"
+      end
+
+      expected_contains = test['expected_body_contains'] || test[:expected_body_contains]
+      if expected_contains
+        body_str = http_result[:body].is_a?(String) ? http_result[:body] : JSON.generate(http_result[:body])
+        unless body_str.include?(expected_contains.to_s)
+          passed = false
+          failures << "Body does not contain: '#{expected_contains}'"
+        end
+      end
+
+      {
+        method: method,
+        path: path,
+        status: http_result[:status],
+        duration_ms: http_result[:duration_ms],
+        passed: passed,
+        failures: failures,
+        body_preview: (http_result[:body].is_a?(String) ? http_result[:body][0..200] : http_result[:body])
+      }
+    end
+
+    total = results.size
+    passed_count = results.count { |r| r[:passed] }
+    failed_count = total - passed_count
+
+    {
+      total: total,
+      passed: passed_count,
+      failed: failed_count,
+      pass_rate: total.zero? ? '0%' : format('%.0f%%', passed_count.to_f / total * 100),
+      results: results
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_endpoint_coverage',
+                'Compare registered Sinatra/Rails routes against tested routes. Shows ' \
+                'which endpoints have been tested via the agent and which are untested') do
+    # Get all routes from the app
+    all_routes = []
+    app = DebugAgent.app
+
+    if app
+      app_class = app.is_a?(Class) ? app : app.class
+
+      if app_class.respond_to?(:routes)
+        app_class.routes.each do |method, route_list|
+          route_list.each do |route|
+            pattern = route[0]
+            pattern_str = case pattern
+                          when Regexp then pattern.source
+                          else pattern.to_s
+                          end
+            all_routes << { method: method.to_s.upcase, pattern: pattern_str }
+          end
+        end
+      end
+    end
+
+    if all_routes.empty? && defined?(Sinatra) && defined?(Sinatra::Base)
+      Sinatra::Base.routes.each do |method, route_list|
+        route_list.each do |route|
+          pattern = route[0]
+          pattern_str = case pattern
+                        when Regexp then pattern.source
+                        else pattern.to_s
+                        end
+          all_routes << { method: method.to_s.upcase, pattern: pattern_str }
+        end
+      end
+    end
+
+    tested = tested_routes_lock.synchronize { @tested_routes.dup }
+    tested_routes_set = tested.map { |t| "#{t[:method]} #{t[:path]}" }.to_set rescue tested.map { |t| "#{t[:method]} #{t[:path]}" }
+
+    # Match tested routes against app routes
+    covered = []
+    uncovered = []
+
+    all_routes.each do |route|
+      pattern = route[:pattern]
+      # Simplify regex patterns for matching (e.g. \A\/api\/orders\/(?<id>[^\/?]+) -> /api/orders)
+      base_pattern = pattern
+        .gsub(/\A\^?\\A?/, '')
+        .gsub(/\$?\\z?\z/, '')
+        .gsub(/\(\?<\w+>[^\)]+\)/, ':param')
+        .gsub(/\(\?:[^\)]+\)/, ':param')
+        .gsub(/\+|\*/, '')
+        .gsub(/\\\//, '/')
+
+      was_tested = tested.any? do |t|
+        t[:method] == route[:method] && (
+          t[:path] == pattern ||
+          t[:path].start_with?(base_pattern.gsub(/:param.*/, ''))
+        )
+      end
+
+      if was_tested
+        covered << route
+      else
+        uncovered << route
+      end
+    end
+
+    {
+      total_routes: all_routes.size,
+      tested_routes: tested_routes_set.size,
+      covered: covered.size,
+      uncovered: uncovered.size,
+      coverage_rate: all_routes.empty? ? '0%' : format('%.0f%%', covered.size.to_f / all_routes.size * 100),
+      covered_routes: covered,
+      uncovered_routes: uncovered,
+      recent_tests: tested.last(50)
+    }
+  rescue => e
+    { error: e.message }
+  end
+end