e11y 0.2.0 → 1.1.0

data/gems/e11y-devtools/lib/e11y/devtools/tui/widgets/event_list.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+
+module E11y
+  module Devtools
+    module Tui
+      module Widgets
+        # Renders a table of events for the selected trace.
+        class EventList
+          SEVERITY_COLORS = {
+            "debug" => :dark_gray,
+            "info" => :white,
+            "warn" => :yellow,
+            "error" => :red,
+            "fatal" => :red
+          }.freeze
+
+          def initialize(events:, trace_id:, selected_index: 0)
+            @events         = events
+            @trace_id       = trace_id
+            @selected_index = selected_index
+          end
+
+          def render(tui, frame, area)
+            frame.render_widget(
+              tui.table(
+                header: ["#", "Severity", "Event Name", "Duration", "At"],
+                rows: build_rows(tui),
+                row_highlight_style: { bg: :dark_gray },
+                selected_row: @selected_index,
+                block: tui.block(title: " #{@trace_id} ", borders: :all)
+              ),
+              area
+            )
+          end
+
+          private
+
+          def build_rows(tui)
+            @events.each_with_index.map do |e, i|
+              sev   = e["severity"] || "info"
+              color = SEVERITY_COLORS.fetch(sev, :white)
+              [
+                (i + 1).to_s,
+                tui.span(content: sev.upcase, style: { fg: color }),
+                e["event_name"].to_s,
+                duration_str(e),
+                timestamp_short(e["timestamp"])
+              ]
+            end
+          end
+
+          def duration_str(event)
+            ms = event.dig("metadata", "duration_ms")
+            ms ? "#{ms}ms" : "—"
+          end
+
+          def timestamp_short(timestamp)
+            return "—" unless timestamp
+
+            Time.parse(timestamp).strftime(".%L")
+          rescue ArgumentError
+            "—"
+          end
+        end
+      end
+    end
+  end
+end

data/gems/e11y-devtools/lib/e11y/devtools/tui/widgets/interaction_list.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+require_relative "../grouping"
+
+module E11y
+  module Devtools
+    module Tui
+      module Widgets
+        # Renders a scrollable list of interaction groups.
+        # Each row shows: bullet (● error / ○ ok), time, trace count.
+        class InteractionList
+          def initialize(interactions:, selected_index: 0, source_filter: :all)
+            @interactions   = interactions
+            @selected_index = selected_index
+            @source_filter  = source_filter
+          end
+
+          def render(tui, frame, area)
+            rows = @interactions.map do |ix|
+              bullet    = ix.has_error? ? "●" : "○"
+              bullet_fg = ix.has_error? ? :red : :gray
+              time_str  = ix.started_at.strftime("%H:%M:%S")
+              count_str = "#{ix.trace_ids.size} req"
+              error_str = ix.has_error? ? "  ● err" : ""
+
+              tui.line(spans: [
+                         tui.span(content: bullet, style: { fg: bullet_fg }),
+                         tui.span(content: " #{time_str}  #{count_str}#{error_str}")
+                       ])
+            end
+
+            frame.render_widget(
+              tui.list(
+                items: rows,
+                highlight_style: { bg: :dark_gray },
+                selected_index: @selected_index,
+                block: tui.block(title: " INTERACTIONS ", borders: :all)
+              ),
+              area
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/gems/e11y-devtools/lib/e11y/devtools/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module E11y
+  module Devtools
+    VERSION      = "0.1.1"
+    CORE_VERSION = "1.0" # compatible e11y gem version
+  end
+end

data/gems/e11y-devtools/lib/e11y/devtools.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "e11y"
+require_relative "devtools/version"
+
+module E11y
+  # Developer tooling for E11y: TUI, Browser Overlay, and MCP Server.
+  module Devtools
+    autoload :Tui,     "e11y/devtools/tui"
+    autoload :Overlay, "e11y/devtools/overlay"
+    autoload :Mcp,     "e11y/devtools/mcp"
+  end
+end

data/gems/e11y-devtools/spec/e11y/devtools/mcp/tools_spec.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tmpdir"
+require "json"
+require "securerandom"
+require "time"
+require "fileutils"
+require "e11y/adapters/dev_log/query"
+
+# Load tool files (guarded in case mcp gem is absent)
+%w[
+  recent_events events_by_trace search stats errors clear
+].each do |name|
+  require "e11y/devtools/mcp/tools/#{name}"
+end
+
+RSpec.describe E11y::Devtools::Mcp::Tools do
+  let(:error_severities) { %w[error fatal] }
+  let(:dir)   { Dir.mktmpdir("e11y_mcp") }
+  let(:path)  { File.join(dir, "e11y_dev.jsonl") }
+  let(:store) { E11y::Adapters::DevLog::Query.new(path) }
+  let(:ctx)   { { store: store } }
+
+  after { FileUtils.remove_entry(dir) }
+
+  def write_event(overrides = {})
+    data = {
+      "id" => SecureRandom.uuid,
+      "timestamp" => Time.now.iso8601(3),
+      "event_name" => "test.event",
+      "severity" => "info",
+      "trace_id" => "t1",
+      "payload" => {},
+      "metadata" => {}
+    }.merge(overrides)
+    File.open(path, "a") { |f| f.puts(JSON.generate(data)) }
+  end
+
+  describe E11y::Devtools::Mcp::Tools::RecentEvents do
+    it "returns recent events as array" do
+      write_event
+      result = described_class.call(limit: 10, server_context: ctx)
+      expect(result).to be_an(Array)
+      expect(result.first["event_name"]).to eq("test.event")
+    end
+
+    it "respects limit" do
+      5.times { write_event }
+      result = described_class.call(limit: 2, server_context: ctx)
+      expect(result.size).to eq(2)
+    end
+
+    it "filters by severity" do
+      write_event("severity" => "info")
+      write_event("severity" => "error")
+      result = described_class.call(limit: 10, severity: "error", server_context: ctx)
+      expect(result.all? { |e| e["severity"] == "error" }).to be true
+    end
+  end
+
+  describe E11y::Devtools::Mcp::Tools::EventsByTrace do
+    it "returns events for given trace_id" do
+      write_event("trace_id" => "abc", "event_name" => "a")
+      write_event("trace_id" => "xyz", "event_name" => "b")
+      result = described_class.call(trace_id: "abc", server_context: ctx)
+      expect(result.size).to eq(1)
+      expect(result.first["event_name"]).to eq("a")
+    end
+  end
+
+  describe E11y::Devtools::Mcp::Tools::Search do
+    it "finds events matching query" do
+      write_event("event_name" => "payment.failed")
+      write_event("event_name" => "order.created")
+      result = described_class.call(query: "payment", limit: 10, server_context: ctx)
+      expect(result.size).to eq(1)
+    end
+  end
+
+  describe E11y::Devtools::Mcp::Tools::Stats do
+    it "returns stats hash" do
+      write_event
+      result = described_class.call(server_context: ctx)
+      expect(result).to be_a(Hash)
+      expect(result).to have_key(:total_events)
+    end
+  end
+
+  describe E11y::Devtools::Mcp::Tools::Errors do
+    it "returns only error/fatal events" do
+      write_event("severity" => "info")
+      write_event("severity" => "error")
+      result = described_class.call(limit: 10, server_context: ctx)
+      expect(result.all? { |e| error_severities.include?(e["severity"]) }).to be true
+    end
+  end
+
+  describe E11y::Devtools::Mcp::Tools::Clear do
+    it "clears the log and returns confirmation string" do
+      write_event
+      result = described_class.call(server_context: ctx)
+      expect(result).to include("cleared")
+      expect(store.stored_events).to be_empty
+    end
+  end
+end

data/gems/e11y-devtools/spec/e11y/devtools/overlay/controller_spec.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tmpdir"
+require "json"
+require "securerandom"
+require "e11y/adapters/dev_log/query"
+require "e11y/devtools/overlay/controller"
+
+RSpec.describe E11y::Devtools::Overlay::Controller do
+  let(:dir) { Dir.mktmpdir("e11y_ctrl") }
+  let(:controller) { described_class.new(query) }
+  let(:path)    { File.join(dir, "e11y_dev.jsonl") }
+  let(:query)   { E11y::Adapters::DevLog::Query.new(path) }
+
+  after { FileUtils.remove_entry(dir) }
+
+  def write_event(name: "test.event", severity: "info", trace_id: "t1")
+    data = {
+      "id" => SecureRandom.uuid, "timestamp" => Time.now.iso8601(3),
+      "event_name" => name, "severity" => severity,
+      "trace_id" => trace_id, "payload" => {}, "metadata" => {}
+    }
+    File.open(path, "a") { |f| f.puts(JSON.generate(data)) }
+  end
+
+  describe "#events_for" do
+    it "returns events_by_trace when trace_id given" do
+      write_event(trace_id: "abc")
+      result = controller.events_for(trace_id: "abc")
+      expect(result).to be_an(Array)
+      expect(result.first["trace_id"]).to eq("abc")
+    end
+
+    it "returns recent events when no trace_id" do
+      write_event
+      result = controller.events_for(trace_id: nil)
+      expect(result).to be_an(Array)
+      expect(result.size).to eq(1)
+    end
+  end
+
+  describe "#recent_events" do
+    it "returns limited recent events" do
+      3.times { write_event }
+      result = controller.recent_events(limit: 2)
+      expect(result.size).to eq(2)
+    end
+  end
+
+  describe "#clear_log!" do
+    it "removes the log file" do
+      write_event
+      controller.clear_log!
+      expect(File.exist?(path)).to be false
+    end
+  end
+
+  describe "#v1_interactions" do
+    it "returns hashes with trace_ids and traces_count" do
+      write_event(name: "a", trace_id: "t1", severity: "info")
+      write_event(name: "b", trace_id: "t2", severity: "error")
+      rows = controller.v1_interactions(source: nil, limit: 10, window_ms: 500)
+      expect(rows).to be_an(Array)
+      expect(rows.first).to include("started_at", "trace_ids", "has_error", "source", "traces_count")
+      expect(rows.first["trace_ids"]).to be_an(Array)
+      expect(rows.first["traces_count"]).to eq(rows.first["trace_ids"].size)
+    end
+  end
+
+  describe "#v1_trace_events" do
+    it "returns events for trace in order" do
+      write_event(name: "first", trace_id: "tx")
+      write_event(name: "second", trace_id: "tx")
+      rows = controller.v1_trace_events("tx")
+      expect(rows.map { |e| e["event_name"] }).to eq(%w[first second])
+    end
+
+    it "returns empty array for blank trace id" do
+      expect(controller.v1_trace_events("")).to eq([])
+    end
+  end
+
+  describe "#v1_recent_events" do
+    it "respects limit clamp" do
+      5.times { write_event }
+      rows = controller.v1_recent_events(limit: 2)
+      expect(rows.size).to eq(2)
+    end
+  end
+end

data/gems/e11y-devtools/spec/e11y/devtools/overlay/middleware_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "rack/test"
+require "rack/mock"
+require "e11y/devtools/overlay/middleware"
+
+RSpec.describe E11y::Devtools::Overlay::Middleware do
+  include Rack::Test::Methods
+
+  let(:html_body) { "<html><body><h1>Hello</h1></body></html>" }
+  let(:base_app) do
+    ->(_env) { [200, { "Content-Type" => "text/html" }, [html_body]] }
+  end
+
+  def app = described_class.new(base_app)
+
+  it "injects overlay script before </body>" do
+    get "/"
+    expect(last_response.body).to include("e11y-overlay")
+    expect(last_response.body).to include("</body>")
+  end
+
+  it "does not inject into non-HTML responses" do
+    json_app = ->(_env) { [200, { "Content-Type" => "application/json" }, ['{"ok":true}']] }
+    response = described_class.new(json_app).call(Rack::MockRequest.env_for("/"))
+    body = response[2].join
+    expect(body).not_to include("e11y-overlay")
+  end
+
+  it "does not inject into XHR requests" do
+    get "/", {}, { "HTTP_X_REQUESTED_WITH" => "XMLHttpRequest" }
+    expect(last_response.body).not_to include("e11y-overlay")
+  end
+
+  it "does not inject into asset paths" do
+    get "/assets/application.js"
+    expect(last_response.body).not_to include("e11y-overlay")
+  end
+
+  it "preserves Content-Length consistency after injection" do
+    get "/"
+    content_length = last_response.headers["Content-Length"]
+    expect(content_length.to_i).to eq(last_response.body.bytesize) if content_length
+  end
+end

data/gems/e11y-devtools/spec/e11y/devtools/tui/app_spec.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tmpdir"
+require "e11y/adapters/dev_log/query"
+require "e11y/devtools/tui/grouping"
+require "e11y/devtools/tui/app"
+
+RSpec.describe E11y::Devtools::Tui::App do
+  subject(:app) { described_class.new(log_path: "/dev/null") }
+
+  describe "#initialize" do
+    it "starts in :interactions view" do
+      expect(app.current_view).to eq(:interactions)
+    end
+
+    it "starts with source_filter :web" do
+      expect(app.source_filter).to eq(:web)
+    end
+  end
+
+  describe "#handle_key" do
+    context "when in :interactions view" do
+      it "drills into :events on Enter" do
+        query = instance_double(E11y::Adapters::DevLog::Query, events_by_trace: [])
+        interaction = E11y::Devtools::Tui::Grouping::Interaction.new(
+          Time.now, ["t1"], false, "web"
+        )
+        app.instance_variable_set(:@query, query)
+        app.instance_variable_set(:@interactions, [interaction])
+        app.instance_variable_set(:@selected_ix, 0)
+        app.handle_key("enter")
+        expect(app.current_view).to eq(:events)
+      end
+
+      it "toggles source to :job on 'j'" do
+        app.handle_key("j")
+        expect(app.source_filter).to eq(:job)
+      end
+
+      it "toggles source to :all on 'a'" do
+        app.handle_key("a")
+        expect(app.source_filter).to eq(:all)
+      end
+
+      it "toggles source back to :web on 'w'" do
+        app.handle_key("a")
+        app.handle_key("w")
+        expect(app.source_filter).to eq(:web)
+      end
+    end
+
+    context "when in :events view" do
+      before do
+        app.instance_variable_set(:@current_view, :events)
+        app.instance_variable_set(:@current_trace_id, "t1")
+        app.instance_variable_set(:@events, [{ "id" => "e1", "event_name" => "x" }])
+      end
+
+      it "goes back to :interactions on Esc" do
+        app.handle_key("esc")
+        expect(app.current_view).to eq(:interactions)
+      end
+
+      it "drills into :detail on Enter" do
+        app.handle_key("enter")
+        expect(app.current_view).to eq(:detail)
+      end
+    end
+
+    context "when in :detail view" do
+      before { app.instance_variable_set(:@current_view, :detail) }
+
+      it "goes back to :events on Esc" do
+        app.handle_key("esc")
+        expect(app.current_view).to eq(:events)
+      end
+
+      it "goes back to :events on 'b'" do
+        app.handle_key("b")
+        expect(app.current_view).to eq(:events)
+      end
+    end
+  end
+end

data/gems/e11y-devtools/spec/e11y/devtools/tui/grouping_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "time"
+require "e11y/devtools/tui/grouping"
+
+RSpec.describe E11y::Devtools::Tui::Grouping do
+  def make_trace(id, offset_ms, severity: "info", source: "web")
+    {
+      trace_id: id,
+      started_at: Time.now + (offset_ms / 1000.0),
+      severity: severity,
+      source: source
+    }
+  end
+
+  describe ".group" do
+    it "returns empty array for empty input" do
+      expect(described_class.group([])).to eq([])
+    end
+
+    it "places single trace in one interaction" do
+      groups = described_class.group([make_trace("t1", 0)])
+      expect(groups.size).to eq(1)
+      expect(groups.first.trace_ids).to eq(["t1"])
+    end
+
+    it "groups traces within window into one interaction" do
+      traces = [
+        make_trace("t1", 0),
+        make_trace("t2", 300),  # 300ms after t1 — within 500ms window
+        make_trace("t3", 1200)  # 1200ms after t1 — outside window
+      ]
+      groups = described_class.group(traces, window_ms: 500)
+      expect(groups.size).to eq(2)
+      # newest-first: groups[0] = t3 group, groups[1] = t1+t2 group
+      expect(groups.last.trace_ids.sort).to eq(%w[t1 t2].sort)
+      expect(groups.first.trace_ids).to eq(["t3"])
+    end
+
+    it "marks interaction has_error? when any trace has error severity" do
+      traces = [
+        make_trace("t1", 0, severity: "error"),
+        make_trace("t2", 100, severity: "info")
+      ]
+      groups = described_class.group(traces, window_ms: 500)
+      expect(groups.first.has_error?).to be true
+    end
+
+    it "marks interaction clean when no errors" do
+      groups = described_class.group([make_trace("t1", 0, severity: "info")])
+      expect(groups.first.has_error?).to be false
+    end
+
+    it "returns groups newest-first" do
+      traces = [
+        make_trace("old", 0),
+        make_trace("new", 2000)
+      ]
+      groups = described_class.group(traces, window_ms: 500)
+      expect(groups.first.trace_ids).to eq(["new"])
+    end
+  end
+end

data/gems/e11y-devtools/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "e11y/devtools/version"

data/gems/e11y-devtools/spec/tui/widgets/event_list_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "time"
+
+unless defined?(RATATUI_AVAILABLE)
+  begin
+    require "minitest"
+    require "ratatui_ruby"
+    require "ratatui_ruby/test_helper"
+    RATATUI_AVAILABLE = true
+  rescue LoadError
+    RATATUI_AVAILABLE = false
+  end
+end
+
+RSpec.describe "E11y::Devtools::Tui::Widgets::EventList" do
+  include RatatuiRuby::TestHelper if RATATUI_AVAILABLE
+
+  before do
+    skip "ratatui_ruby not available" unless RATATUI_AVAILABLE
+    require "e11y/devtools/tui/widgets/event_list"
+  end
+
+  let(:events) do
+    [
+      { "severity" => "error", "event_name" => "order.failed",
+        "timestamp" => Time.now.iso8601, "metadata" => {} },
+      { "severity" => "info", "event_name" => "order.created",
+        "timestamp" => Time.now.iso8601, "metadata" => { "duration_ms" => 42 } }
+    ]
+  end
+
+  it "renders without raising" do
+    widget = E11y::Devtools::Tui::Widgets::EventList.new(
+      events: events, trace_id: "trace-1", selected_index: 0
+    )
+    tui = RatatuiRuby::TUI.new
+    with_test_terminal(80, 10) do
+      expect { RatatuiRuby.draw { |frame| widget.render(tui, frame, frame.area) } }
+        .not_to raise_error
+    end
+  end
+end

data/gems/e11y-devtools/spec/tui/widgets/interaction_list_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "time"
+require "e11y/devtools/tui/grouping"
+
+unless defined?(RATATUI_AVAILABLE)
+  begin
+    require "minitest"
+    require "ratatui_ruby"
+    require "ratatui_ruby/test_helper"
+    RATATUI_AVAILABLE = true
+  rescue LoadError
+    RATATUI_AVAILABLE = false
+  end
+end
+
+RSpec.describe "E11y::Devtools::Tui::Widgets::InteractionList" do
+  include RatatuiRuby::TestHelper if RATATUI_AVAILABLE
+
+  before do
+    skip "ratatui_ruby not available" unless RATATUI_AVAILABLE
+    require "e11y/devtools/tui/widgets/interaction_list"
+  end
+
+  let(:t0) { Time.now }
+
+  def make_interaction(trace_ids:, has_error: false)
+    E11y::Devtools::Tui::Grouping::Interaction.new(
+      started_at: t0,
+      trace_ids: trace_ids,
+      has_error?: has_error,
+      source: "web"
+    )
+  end
+
+  it "renders bullet as ● red when interaction has error" do
+    widget = E11y::Devtools::Tui::Widgets::InteractionList.new(
+      interactions: [make_interaction(trace_ids: ["t1"], has_error: true)],
+      selected_index: 0
+    )
+    tui = RatatuiRuby::TUI.new
+    with_test_terminal(40, 5) do
+      expect { RatatuiRuby.draw { |frame| widget.render(tui, frame, frame.area) } }
+        .not_to raise_error
+      expect(buffer_content.join).to include("●")
+    end
+  end
+
+  it "renders bullet as ○ when interaction is clean" do
+    widget = E11y::Devtools::Tui::Widgets::InteractionList.new(
+      interactions: [make_interaction(trace_ids: ["t1"], has_error: false)],
+      selected_index: 0
+    )
+    tui = RatatuiRuby::TUI.new
+    with_test_terminal(40, 5) do
+      expect { RatatuiRuby.draw { |frame| widget.render(tui, frame, frame.area) } }
+        .not_to raise_error
+      expect(buffer_content.join).to include("○")
+    end
+  end
+end