e11y 0.2.0 → 1.0.0

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

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "e11y/adapters/dev_log/query"
+require_relative "grouping"
+
+module E11y
+  module Devtools
+    module Tui
+      # Top-level TUI application.
+      #
+      # Manages navigation state (:interactions | :events | :detail),
+      # handles keyboard events, and reloads data when the log file changes.
+      # rubocop:disable Metrics/ClassLength
+      class App
+        attr_reader :current_view, :source_filter
+
+        POLL_INTERVAL_MS = 250
+
+        def initialize(log_path: nil)
+          @log_path         = log_path || auto_detect_log_path
+          @query            = E11y::Adapters::DevLog::Query.new(@log_path)
+          @current_view     = :interactions
+          @source_filter    = :web
+          @selected_ix      = 0
+          @interactions     = []
+          @events           = []
+          @current_trace_id = nil
+          @current_event    = nil
+          @last_mtime       = nil
+        end
+
+        # Start the TUI event loop (blocks until user quits).
+        def run
+          require "ratatui_ruby"
+          require_relative "widgets/interaction_list"
+          require_relative "widgets/event_list"
+          require_relative "widgets/event_detail"
+          RatatuiRuby.run do |tui|
+            loop do
+              reload_if_changed!
+              tui.draw { |frame| render(tui, frame) }
+              event = tui.poll_event(timeout_ms: POLL_INTERVAL_MS)
+              break if quit_event?(event)
+
+              handle_key(key_from(event)) if key_event?(event)
+            end
+          end
+        end
+
+        # Handle a single key press (public for testability).
+        def handle_key(key)
+          case @current_view
+          when :interactions then handle_interactions_key(key)
+          when :events       then handle_events_key(key)
+          when :detail       then handle_detail_key(key)
+          end
+        end
+
+        # Return the currently highlighted interaction (or nil).
+        def selected_interaction
+          @interactions[@selected_ix]
+        end
+
+        private
+
+        # --- Rendering ---
+
+        def render(tui, frame)
+          case @current_view
+          when :interactions then render_interactions(tui, frame)
+          when :events       then render_events(tui, frame)
+          when :detail
+            render_events(tui, frame)
+            Widgets::EventDetail.new(event: @current_event).render(tui, frame, frame.area)
+          end
+        end
+
+        def render_interactions(tui, frame)
+          Widgets::InteractionList.new(
+            interactions: @interactions,
+            selected_index: @selected_ix
+          ).render(tui, frame, frame.area)
+        end
+
+        def render_events(tui, frame)
+          Widgets::EventList.new(
+            events: @events,
+            trace_id: @current_trace_id || "",
+            selected_index: @selected_ix
+          ).render(tui, frame, frame.area)
+        end
+
+        # --- Key handlers per view ---
+
+        def handle_interactions_key(key)
+          case key
+          when "enter"  then drill_into_events
+          when "j"      then @source_filter = :job
+                             reload!
+          when "w"      then @source_filter = :web
+                             reload!
+          when "a"      then @source_filter = :all
+                             reload!
+          when "down"   then move_down(@interactions.size)
+          when "up"     then move_up
+          when "r"      then reload!
+          end
+        end
+
+        def handle_events_key(key)
+          case key
+          when "esc", "b" then back_to_interactions
+          when "enter"    then drill_into_detail
+          when "down"     then move_down(@events.size)
+          when "up"       then move_up
+          end
+        end
+
+        def handle_detail_key(key)
+          case key
+          when "esc", "b" then @current_view = :events
+          when "c"        then copy_to_clipboard(::JSON.generate(@current_event))
+          end
+        end
+
+        # --- Navigation helpers ---
+
+        def drill_into_events
+          ix = selected_interaction
+          return unless ix
+
+          @current_trace_id = ix.trace_ids.first
+          @events           = @query.events_by_trace(@current_trace_id)
+          @selected_ix      = 0
+          @current_view     = :events
+        end
+
+        def drill_into_detail
+          event = @events[@selected_ix]
+          return unless event
+
+          @current_event = event
+          @current_view  = :detail
+        end
+
+        def back_to_interactions
+          @current_view = :interactions
+          @selected_ix  = 0
+        end
+
+        def move_down(size)
+          @selected_ix = [@selected_ix + 1, size - 1].min
+        end
+
+        def move_up
+          @selected_ix = [@selected_ix - 1, 0].max
+        end
+
+        # --- Data loading ---
+
+        def reload_if_changed!
+          mtime = file_mtime
+          return if mtime == @last_mtime
+
+          @last_mtime = mtime
+          reload!
+        end
+
+        def reload!
+          source = @source_filter == :all ? nil : @source_filter.to_s
+          traces = build_traces(source)
+          @interactions = Grouping.group(traces, window_ms: 500)
+        end
+
+        def build_traces(source)
+          events    = @query.stored_events(limit: 5000, source: source)
+          trace_map = {}
+          events.each { |e| accumulate_trace(trace_map, e) }
+          trace_map.values
+        end
+
+        def accumulate_trace(trace_map, event)
+          tid = event["trace_id"]
+          return unless tid
+
+          entry = trace_map[tid] ||= {
+            trace_id: tid,
+            started_at: parse_time(event.dig("metadata", "started_at") || event["timestamp"]),
+            severity: event["severity"],
+            source: event.dig("metadata", "source") || "web"
+          }
+          entry[:severity] = "error" if %w[error fatal].include?(event["severity"])
+        end
+
+        def file_mtime
+          ::File.mtime(@log_path)
+        rescue Errno::ENOENT
+          nil
+        end
+
+        # --- Utilities ---
+
+        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
+
+        def parse_time(str)
+          ::Time.parse(str.to_s)
+        rescue ArgumentError, TypeError
+          ::Time.now
+        end
+
+        def quit_event?(event)
+          return false unless event
+          return false unless event[:type] == :key
+
+          event[:code] == "q" ||
+            (event[:code] == "c" && event[:modifiers]&.include?("ctrl"))
+        end
+
+        def key_event?(event)
+          event && event[:type] == :key
+        end
+
+        def key_from(event)
+          event&.dig(:code)
+        end
+
+        def copy_to_clipboard(text)
+          copy_macos(text) || copy_linux(text)
+        end
+
+        def copy_macos(text)
+          ::IO.popen("pbcopy", "w") { |f| f.write(text) }
+          true
+        rescue StandardError
+          false
+        end
+
+        def copy_linux(text)
+          ::IO.popen("xclip -selection clipboard", "w") { |f| f.write(text) }
+          true
+        rescue StandardError
+          false
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module E11y
+  module Devtools
+    module Tui
+      # Pure-function time-window grouping for traces → interactions.
+      # Shared by TUI widgets, Overlay, and MCP interactions tool.
+      module Grouping
+        # Severities that count as errors for interaction flagging.
+        ERROR_SEVERITIES = %w[error fatal].freeze
+
+        # Value object representing one interaction group.
+        Interaction = Struct.new(:started_at, :trace_ids, :has_error?,
+                                 :source)
+
+        # Group an array of trace hashes into Interaction bands.
+        #
+        # @param traces     [Array<Hash>]  Each hash must have :trace_id,
+        #                                  :started_at (Time), :severity
+        # @param window_ms  [Integer]      Grouping window in milliseconds
+        # @return [Array<Interaction>]     Newest-first
+        def self.group(traces, window_ms: 500)
+          return [] if traces.empty?
+
+          build_interactions(accumulate_groups(traces, window_ms))
+        end
+
+        def self.accumulate_groups(traces, window_ms)
+          sorted = traces.sort_by { |t| t[:started_at] }
+          groups = []
+          current = nil
+          sorted.each { |trace| current = append_trace(groups, current, trace, window_ms) }
+          groups
+        end
+
+        def self.append_trace(groups, current, trace, window_ms)
+          if current.nil? || outside_window?(trace, current, window_ms)
+            current = new_group(trace)
+            groups << current
+          end
+          current[:trace_ids] << trace[:trace_id]
+          current[:has_error] ||= ERROR_SEVERITIES.include?(trace[:severity])
+          current
+        end
+
+        def self.outside_window?(trace, current, window_ms)
+          (trace[:started_at] - current[:anchor]) * 1000 > window_ms
+        end
+
+        def self.new_group(trace)
+          { anchor: trace[:started_at], started_at: trace[:started_at],
+            trace_ids: [], has_error: false, source: trace[:source] }
+        end
+
+        def self.build_interactions(groups)
+          groups.reverse.map do |g|
+            Interaction.new(g[:started_at], g[:trace_ids], g[:has_error], g[:source])
+          end
+        end
+
+        private_class_method :accumulate_groups, :append_trace,
+                             :outside_window?, :new_group, :build_interactions
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+require "json"
+
+module E11y
+  module Devtools
+    module Tui
+      module Widgets
+        # Full-screen popup overlay showing event payload + metadata.
+        class EventDetail
+          def initialize(event:)
+            @event = event
+          end
+
+          def render(tui, frame, area)
+            popup_area = centered_rect(area, percent_x: 80, percent_y: 70)
+
+            frame.render_widget(tui.clear, popup_area)
+
+            sev   = @event["severity"] || "info"
+            title = " #{@event['event_name']} · #{sev.upcase} "
+
+            frame.render_widget(
+              tui.paragraph(
+                text: build_lines,
+                block: tui.block(title: title, borders: :all),
+                scroll: [0, 0]
+              ),
+              popup_area
+            )
+          end
+
+          private
+
+          def build_lines
+            lines = []
+            lines << "  timestamp:  #{@event['timestamp']}"
+            lines << "  trace_id:   #{@event['trace_id']}"
+            lines << "  span_id:    #{@event['span_id']}"
+            lines << ""
+            lines << "  payload:"
+            JSON.pretty_generate(@event["payload"] || {}).each_line do |l|
+              lines << "    #{l.chomp}"
+            end
+            lines << ""
+            lines << "  [c] copy JSON    [b] back"
+            lines
+          end
+
+          def centered_rect(area, percent_x:, percent_y:)
+            w = (area.width  * percent_x / 100).to_i
+            h = (area.height * percent_y / 100).to_i
+            x = area.x + ((area.width  - w) / 2)
+            y = area.y + ((area.height - h) / 2)
+            RatatuiRuby::Rect.new(x: x, y: y, width: w, height: h)
+          end
+        end
+      end
+    end
+  end
+end

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.0"
+    CORE_VERSION = "0.2" # 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,58 @@
+# 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
+end