e11y-devtools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 102fbf2c428a06eba9c77929f68c2e4843cb67cb7b46d1f83540997cee1a16be
+  data.tar.gz: 7c990a1c47e5e4a631efcb6ecb658cc1898e9530243c88d017cc0d13454b6c00
+SHA512:
+  metadata.gz: c1fcdccf770d5f98fcac0e04b57f1b708b910eff26bfeeb70dbe1da87465ca5e88afa384692a706f16ea711b3ef5be02abf45ea465218698ca192fb3adfbf639
+  data.tar.gz: b48620b09a3327808f33ee3e7d3609652501a9450cf32b23c57238aa65b82ee5e552ed41544560821beb75c010ca07b7096d9cb79ec3c1ee4b2183f0ed70268e

data/README.md

@@ -0,0 +1,137 @@
+# e11y-devtools
+
+Developer tools for [e11y](https://github.com/aseletskiy/e11y) — the Rails observability gem.
+
+Three complementary viewers for the same JSONL log:
+
+| Viewer | How to use |
+|--------|-----------|
+| **TUI** (terminal) | `bundle exec e11y` |
+| **Browser Overlay** | Automatic in development — floating badge in bottom-right |
+| **MCP Server** | `bundle exec e11y mcp` — AI integration for Cursor / Claude Code |
+
+## Installation
+
+Add to your Gemfile (development group only):
+
+```ruby
+# Gemfile
+gem "e11y", "~> 1.0"
+gem "e11y-devtools", "~> 0.1.0", group: :development
+```
+
+Then run `bundle install`.
+
+## TUI — Interactive Log Viewer
+
+```bash
+bundle exec e11y           # Open TUI (default)
+bundle exec e11y tui       # Same as above
+bundle exec e11y tail      # Stream events to stdout
+bundle exec e11y help      # Show help
+```
+
+### TUI Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `↑` / `k` | Move up |
+| `↓` / `j` | Move down |
+| `Enter` | Drill in (interactions → events → detail) |
+| `Esc` / `b` | Go back |
+| `w` | Filter: web requests only |
+| `j` | Filter: background jobs only |
+| `a` | Filter: all sources |
+| `r` | Reload manually |
+| `c` | Copy event JSON to clipboard (in detail view) |
+| `q` | Quit |
+
+## Browser Overlay
+
+When `gem "e11y-devtools"` is in your Gemfile, the overlay badge appears automatically in development. No configuration needed — the Railtie mounts it.
+
+The badge shows:
+- Total event count for the current request
+- Error count (red badge when errors present)
+- Click to expand the slide-in panel with full event list
+
+## MCP Server — AI Integration
+
+Start the server:
+
+```bash
+# stdio (for Cursor / Claude Code)
+bundle exec e11y mcp
+
+# HTTP (for direct integration)
+bundle exec e11y mcp --port 3099
+```
+
+Add to `.cursor/mcp.json` or `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "e11y": {
+      "command": "bundle",
+      "args": ["exec", "e11y", "mcp"],
+      "cwd": "/path/to/your/rails/app"
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `recent_events` | Get latest N events (filterable by severity) |
+| `events_by_trace` | Get all events for a trace ID |
+| `search` | Full-text search across event names and payloads |
+| `stats` | Aggregate statistics (total, by severity, oldest/newest) |
+| `interactions` | Time-grouped interactions (parallel requests) |
+| `event_detail` | Full payload for a single event by ID |
+| `errors` | Recent error/fatal events only — fastest way to see what went wrong |
+| `clear` | Clear the dev log |
+
+## Configuration
+
+```ruby
+# config/initializers/e11y.rb
+E11y.configure do |config|
+  config.register_adapter :dev_log, E11y::Adapters::DevLog.new(
+    path:         Rails.root.join("log", "e11y_dev.jsonl"),
+    max_size:     ENV.fetch("E11Y_MAX_SIZE", 50).to_i * 1024 * 1024,  # 50 MB
+    max_lines:    ENV.fetch("E11Y_MAX_EVENTS", 10_000).to_i,
+    keep_rotated: ENV.fetch("E11Y_KEEP_ROTATED", 5).to_i
+  )
+end
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `E11Y_MAX_EVENTS` | `10000` | Max lines before rotation |
+| `E11Y_MAX_SIZE` | `50` | Max log size in MB before rotation |
+| `E11Y_KEEP_ROTATED` | `5` | Number of compressed `.gz` files to keep |
+
+## Log Format
+
+Events are stored as JSONL (one JSON object per line) at `log/e11y_dev.jsonl`.
+Rotated files are numbered and gzip-compressed: `e11y_dev.jsonl.1.gz`, `.2.gz`, etc.
+
+## Architecture
+
+```
+log/e11y_dev.jsonl  ←  E11y::Adapters::DevLog (write)
+         ↓
+E11y::Adapters::DevLog::Query (read, cache, search, grouping)
+         ↓
+   ┌─────┴──────┬──────────────┬──────────────┐
+   TUI          Browser        MCP Server
+(ratatui_ruby)  Overlay       (gem 'mcp')
+                (Rack)
+```
+
+The JSONL file is the single source of truth. All viewers are stateless readers — they never write.

data/exe/e11y

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "e11y/devtools"
+
+command = ARGV.shift || "tui"
+
+case command
+when "tui"
+  require "e11y/devtools/tui/app"
+  E11y::Devtools::Tui::App.new.run
+when "mcp"
+  require "e11y/devtools/mcp/server"
+  E11y::Devtools::Mcp::Server.new.run(
+    transport: ARGV.include?("--port") ? :http : :stdio,
+    port: (ARGV[ARGV.index("--port") + 1] if ARGV.include?("--port"))&.to_i
+  )
+when "tail"
+  require "e11y/devtools/tui/tail"
+  E11y::Devtools::Tui::Tail.new.run
+when "help", "--help", "-h"
+  puts <<~HELP
+    bundle exec e11y [command]
+
+    Commands:
+      tui   (default)  Interactive TUI — browse events and traces
+      mcp              MCP server for Cursor / Claude Code AI integration
+      tail             Stream new events to stdout (pipe-friendly)
+      help             Show this help
+  HELP
+else
+  warn "Unknown command: #{command}. Run `bundle exec e11y help`."
+  exit 1
+end

data/lib/e11y/devtools/mcp/server.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "e11y/adapters/dev_log/query"
+require_relative "tools/recent_events"
+require_relative "tools/events_by_trace"
+require_relative "tools/search"
+require_relative "tools/stats"
+require_relative "tools/interactions"
+require_relative "tools/event_detail"
+require_relative "tools/errors"
+require_relative "tools/clear"
+
+module E11y
+  module Devtools
+    module Mcp
+      # MCP Server wrapping the E11y DevLog adapter.
+      #
+      # Exposes 8 tools to AI tools like Cursor and Claude Code.
+      # Supports stdio (default) and StreamableHTTP transports.
+      #
+      # @example Start stdio server
+      #   E11y::Devtools::Mcp::Server.new.run
+      #
+      # @example Start HTTP server on port 3099
+      #   E11y::Devtools::Mcp::Server.new.run(transport: :http, port: 3099)
+      class Server
+        TOOLS = [
+          Tools::RecentEvents, Tools::EventsByTrace, Tools::Search,
+          Tools::Stats, Tools::Interactions, Tools::EventDetail,
+          Tools::Errors, Tools::Clear
+        ].freeze
+
+        def initialize(log_path: nil)
+          @log_path = log_path || auto_detect_log_path
+          @store    = E11y::Adapters::DevLog::Query.new(@log_path)
+        end
+
+        # Start the MCP server.
+        #
+        # @param transport [:stdio, :http] Transport to use
+        # @param port      [Integer, nil]  HTTP port (default 3099)
+        def run(transport: :stdio, port: nil)
+          require "mcp"
+          server = build_mcp_server
+          case transport
+          when :stdio then run_stdio(server)
+          when :http  then run_http(server, port || 3099)
+          else raise ArgumentError, "Unknown transport: #{transport}"
+          end
+        end
+
+        private
+
+        def build_mcp_server
+          MCP::Server.new(
+            name: "e11y",
+            version: E11y::Devtools::VERSION,
+            tools: TOOLS,
+            server_context: { store: @store }
+          )
+        end
+
+        def run_stdio(server)
+          t = MCP::Server::Transports::StdioTransport.new(server)
+          server.transport = t
+          t.open
+        end
+
+        def run_http(server, port)
+          require "webrick"
+          t = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+          server.transport = t
+          s = WEBrick::HTTPServer.new(Port: port, Logger: WEBrick::Log.new(nil))
+          s.mount("/mcp", t)
+          trap("INT") { s.shutdown }
+          s.start
+        end
+
+        def auto_detect_log_path
+          dir = Pathname.new(Dir.pwd)
+          loop do
+            candidate = dir.join("log", "e11y_dev.jsonl")
+            return candidate.to_s if candidate.exist?
+
+            parent = dir.parent
+            break if parent == dir
+
+            dir = parent
+          end
+          "log/e11y_dev.jsonl"
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tool_base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module E11y
+  module Devtools
+    module Mcp
+      # Conditional base: use MCP::Tool if available, otherwise plain class.
+      # This allows tests to run without the mcp gem installed.
+      ToolBase = if defined?(MCP::Tool)
+                   MCP::Tool
+                 else
+                   Class.new do
+                     def self.description(desc = nil)
+                       @description = desc if desc
+                       @description
+                     end
+
+                     def self.input_schema(schema = nil)
+                       @input_schema = schema if schema
+                       @input_schema
+                     end
+                   end
+                 end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/clear.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Clears the E11y development log file.
+        class Clear < ToolBase
+          description "Clear the E11y development log file"
+
+          input_schema(
+            type: :object,
+            properties: {}
+          )
+
+          def self.call(server_context:, **_opts)
+            server_context[:store].clear!
+            "E11y log cleared successfully"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Returns recent error and fatal events only.
+        class Errors < ToolBase
+          ERROR_SEVERITIES = %w[error fatal].freeze
+
+          description "Get recent error and fatal events only"
+
+          input_schema(
+            type: :object,
+            properties: {
+              limit: { type: :integer, description: "Max events", default: 20 }
+            }
+          )
+
+          def self.call(server_context:, limit: 20)
+            events = server_context[:store].stored_events(limit: limit * 5)
+            events.select { |e| ERROR_SEVERITIES.include?(e["severity"]) }.first(limit)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/event_detail.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Returns the full payload of a single event by ID.
+        class EventDetail < ToolBase
+          description "Get full payload of a single event by ID"
+
+          input_schema(
+            type: :object,
+            required: ["event_id"],
+            properties: {
+              event_id: { type: :string, description: "Event UUID" }
+            }
+          )
+
+          def self.call(event_id:, server_context:)
+            server_context[:store].find_event(event_id) || { error: "Event #{event_id} not found" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/events_by_trace.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Returns all events for a specific trace ID in chronological order.
+        class EventsByTrace < ToolBase
+          description "Get all events for a specific trace ID in chronological order"
+
+          input_schema(
+            type: :object,
+            required: ["trace_id"],
+            properties: {
+              trace_id: { type: :string, description: "Trace ID" }
+            }
+          )
+
+          def self.call(trace_id:, server_context:)
+            server_context[:store].events_by_trace(trace_id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/interactions.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Returns time-grouped interactions (parallel requests from one user action).
+        class Interactions < ToolBase
+          description "Get time-grouped interactions (parallel requests from one user action)"
+
+          input_schema(
+            type: :object,
+            properties: {
+              limit: { type: :integer, description: "Max interactions", default: 20 },
+              window_ms: { type: :integer, description: "Grouping window in ms", default: 500 }
+            }
+          )
+
+          def self.call(server_context:, limit: 20, window_ms: 500)
+            server_context[:store].interactions(limit: limit, window_ms: window_ms).map do |ix|
+              {
+                started_at: ix.started_at.iso8601(3),
+                trace_ids: ix.trace_ids,
+                has_error: ix.has_error?,
+                traces_count: ix.traces_count
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/recent_events.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Returns the most recent events from the dev log.
+        class RecentEvents < ToolBase
+          description "Get recent E11y events from the development log"
+
+          input_schema(
+            type: :object,
+            properties: {
+              limit: { type: :integer, description: "Max events to return (default 50)", default: 50 },
+              severity: { type: :string, description: "Filter by severity",
+                          enum: %w[debug info warn error fatal] }
+            }
+          )
+
+          def self.call(server_context:, limit: 50, severity: nil)
+            server_context[:store].stored_events(limit: limit, severity: severity)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/search.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Full-text search across event names and payload content.
+        class Search < ToolBase
+          description "Full-text search across event names and payload content"
+
+          input_schema(
+            type: :object,
+            required: ["query"],
+            properties: {
+              query: { type: :string, description: "Search term" },
+              limit: { type: :integer, description: "Max results", default: 50 }
+            }
+          )
+
+          def self.call(query:, server_context:, limit: 50)
+            server_context[:store].search(query, limit: limit)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/mcp/tools/stats.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  # mcp gem not available — ToolBase will use plain class
+end
+require_relative "../tool_base"
+
+module E11y
+  module Devtools
+    module Mcp
+      module Tools
+        # Returns aggregate statistics about the E11y development log.
+        class Stats < ToolBase
+          description "Get aggregate statistics about the E11y development log"
+
+          input_schema(
+            type: :object,
+            properties: {}
+          )
+
+          def self.call(server_context:, **_opts)
+            server_context[:store].stats
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/overlay/controller.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "e11y/adapters/dev_log/query"
+require "e11y/adapters/dev_log"
+
+module E11y
+  module Devtools
+    module Overlay
+      # Plain Ruby controller logic — testable without Rails.
+      # Used by the Rails route handlers (see config/routes.rb).
+      class Controller
+        def initialize(query = nil)
+          @query = query || resolve_query
+        end
+
+        def events_for(trace_id: nil, limit: 50)
+          if trace_id && !trace_id.empty?
+            @query.events_by_trace(trace_id)
+          else
+            @query.stored_events(limit: limit)
+          end
+        end
+
+        def recent_events(limit: 50)
+          clamped = limit.to_i.clamp(1, 500)
+          @query.stored_events(limit: clamped)
+        end
+
+        def clear_log!
+          @query.clear!
+        end
+
+        def stats
+          @query.stats
+        end
+
+        private
+
+        def resolve_query
+          if defined?(E11y) && E11y.respond_to?(:configuration)
+            adapter = E11y.configuration.adapters[:dev_log]
+            return adapter if adapter.respond_to?(:stored_events)
+          end
+          default_path = if defined?(Rails) && Rails.respond_to?(:root)
+                           Rails.root.join("log", "e11y_dev.jsonl").to_s
+                         else
+                           "log/e11y_dev.jsonl"
+                         end
+          E11y::Adapters::DevLog::Query.new(default_path)
+        end
+      end
+    end
+  end
+end

data/lib/e11y/devtools/overlay/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module E11y
+  module Devtools
+    module Overlay
+      # Rails Engine that mounts JSON endpoints at /_e11y/
+      # and injects the overlay badge via Rack middleware.
+      class Engine < Rails::Engine
+        isolate_namespace E11y::Devtools::Overlay
+
+        initializer "e11y_devtools.overlay.middleware" do |app|
+          next unless Rails.env.development? || Rails.env.test?
+
+          require "e11y/devtools/overlay/middleware"
+          app.middleware.use E11y::Devtools::Overlay::Middleware
+        end
+
+        config.generators do |g|
+          g.test_framework :rspec
+        end
+      end
+    end
+  end
+end