e11y 0.2.0 → 1.1.0

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

@@ -0,0 +1,94 @@
+# 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
+
+        # @return [Array<Hash>] JSON-ready rows, newest interaction first (matches TUI ordering).
+        def v1_interactions(source: nil, limit: 50, window_ms: 500)
+          src = normalize_v1_source(source)
+          lim = limit.to_i.clamp(1, 500)
+          wm = window_ms.to_i.clamp(50, 10_000)
+          list = @query.interactions(window_ms: wm, limit: lim, source: src)
+          list.reverse.map { |row| v1_interaction_hash(row) }
+        end
+
+        # @return [Array<Hash>] events for trace, chronological (same as DevLog::Query).
+        def v1_trace_events(trace_id)
+          return [] if trace_id.nil? || trace_id.to_s.empty?
+
+          @query.events_by_trace(trace_id.to_s)
+        end
+
+        # @return [Array<Hash>] newest-first flat list for badge / pulse.
+        def v1_recent_events(limit: 100)
+          lim = limit.to_i.clamp(1, 500)
+          @query.stored_events(limit: lim)
+        end
+
+        private
+
+        def normalize_v1_source(source)
+          s = source.to_s
+          return "web" if s == "web"
+          return "job" if s == "job"
+
+          nil
+        end
+
+        def v1_interaction_hash(row)
+          {
+            "started_at" => row.started_at.iso8601(3),
+            "trace_ids" => row.trace_ids,
+            "has_error" => row.has_error?,
+            "source" => row.source,
+            "traces_count" => row.traces_count
+          }
+        end
+
+        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/gems/e11y-devtools/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

data/gems/e11y-devtools/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/gems/e11y-devtools/lib/e11y/devtools/overlay/rails_controller.rb

@@ -0,0 +1,67 @@
+# 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
+
+        def overlay_js
+          path = E11y::Devtools::Overlay::Engine.root.join(
+            "lib/e11y/devtools/overlay/assets/overlay.js"
+          )
+          return head :not_found unless path.file?
+
+          send_file path, type: "application/javascript", disposition: "inline"
+        end
+
+        def v1_interactions
+          render json: overlay_ctrl.v1_interactions(
+            source: params[:source],
+            limit: params[:limit],
+            window_ms: params[:window_ms]
+          )
+        end
+
+        def v1_trace_events
+          render json: overlay_ctrl.v1_trace_events(params[:trace_id])
+        end
+
+        def v1_events_recent
+          render json: overlay_ctrl.v1_recent_events(limit: params[:limit])
+        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/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