e11y-devtools 0.1.0

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module E11y
+  module Devtools
+    module Overlay
+      # Rack middleware that injects the e11y overlay badge into HTML responses.
+      #
+      # Skips injection for:
+      # - XHR requests (X-Requested-With: XMLHttpRequest)
+      # - Asset paths (/assets/, /packs/, /_e11y/)
+      # - Non-HTML responses
+      class Middleware
+        OVERLAY_SNIPPET = <<~HTML
+
+          <!-- e11y-overlay -->
+          <script id="e11y-overlay-loader">
+            (function() {
+              var s = document.createElement('script');
+              s.src = '/_e11y/overlay.js';
+              s.defer = true;
+              document.head.appendChild(s);
+            })();
+          </script>
+        HTML
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          status, headers, body = @app.call(env)
+          return [status, headers, body] unless injectable?(env, headers)
+
+          new_body = inject_overlay(body, env["e11y.trace_id"])
+          [status, update_content_length(headers, new_body), [new_body]]
+        end
+
+        private
+
+        def injectable?(env, headers)
+          !xhr?(env) && !asset_path?(env) && html_response?(headers)
+        end
+
+        def xhr?(env)
+          env["HTTP_X_REQUESTED_WITH"]&.downcase == "xmlhttprequest"
+        end
+
+        def asset_path?(env)
+          path = env["PATH_INFO"] || ""
+          path.start_with?("/assets/", "/packs/", "/_e11y/")
+        end
+
+        def html_response?(headers)
+          ct = headers["Content-Type"] || headers["content-type"] || ""
+          ct.include?("text/html")
+        end
+
+        def inject_overlay(body, trace_id)
+          full = body.respond_to?(:join) ? body.join : body.to_s
+          snippet = trace_id_script(trace_id) + OVERLAY_SNIPPET
+          full.sub("</body>", "#{snippet}</body>")
+        end
+
+        def trace_id_script(trace_id)
+          return "" unless trace_id
+
+          "<script>window.__E11Y_TRACE_ID__ = '#{trace_id}';</script>\n"
+        end
+
+        def update_content_length(headers, new_body)
+          h = headers.dup
+          h.delete("Content-Length")
+          h.delete("content-length")
+          h["Content-Length"] = new_body.bytesize.to_s
+          h
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "controller"
+
+module E11y
+  module Devtools
+    module Overlay
+      # Thin Rails controller — delegates to plain Controller for testability.
+      # Only available in development/test.
+      class RailsController < ActionController::Base
+        before_action :development_only!
+
+        def events
+          render json: overlay_ctrl.events_for(trace_id: params[:trace_id])
+        end
+
+        def recent
+          render json: overlay_ctrl.recent_events(limit: params[:limit])
+        end
+
+        def clear
+          overlay_ctrl.clear_log!
+          head :no_content
+        end
+
+        def stats
+          render json: overlay_ctrl.stats
+        end
+
+        private
+
+        def overlay_ctrl
+          @overlay_ctrl ||= Controller.new
+        end
+
+        def development_only!
+          head :not_found unless Rails.env.development? || Rails.env.test?
+        end
+      end
+    end
+  end
+end

data/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/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/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/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/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/lib/e11y/devtools/version.rb

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

data/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