tui-td 0.2.13 → 0.2.17

data/lib/tui_td/mcp/server.rb

@@ -272,7 +272,7 @@ module TUITD
               },
               {
                 name: "tui_find_text",
-                description: "Search for text or regex pattern in the current terminal state. Returns positions of all matches with surrounding context.",
+                description: "Search for text or regex pattern in the current terminal state. Returns positions of all matches with surrounding context. Supports match modes: partial (default, substring), exact (whole row), regex (Ruby regex).",
                 inputSchema: {
                   type: "object",
                   properties: {
@@ -280,25 +280,148 @@ module TUITD
                       type: "string",
                       description: "Text or regex pattern to search for (e.g., 'error', 'ERROR|FAIL')",
                     },
+                    match: {
+                      type: "string",
+                      enum: %w[partial exact regex],
+                      description: "Match mode: partial (substring), exact (whole row match), regex (Ruby regex). Default: partial.",
+                    },
                   },
                   required: ["pattern"],
                 },
               },
               {
                 name: "tui_find_elements",
-                description: "Search for UI elements in the terminal state. Returns buttons, checkboxes, dialogs, statusbars, and progress bars detected by heuristic analysis. Optionally filter by role and/or text.",
+                description: "Search for UI elements in the terminal state. Returns buttons, checkboxes, dialogs, statusbars, progress bars, inputs, labels, menus, and tabs detected by heuristic analysis. Optionally filter by role, text, checked, and/or disabled state.",
                 inputSchema: {
                   type: "object",
                   properties: {
                     role: {
                       type: "string",
-                      description: "Filter by role: button, checkbox, dialog, statusbar, progress. Omit to return all.",
+                      description: "Filter by role: button, checkbox, dialog, statusbar, progress, input, label, menu, tab. Omit to return all.",
                     },
                     text: {
                       type: "string",
                       description: "Filter by visible text (partial match). Optional.",
                     },
+                    checked: {
+                      type: "boolean",
+                      description: "Filter by checked state (checkboxes). Optional.",
+                    },
+                    disabled: {
+                      type: "boolean",
+                      description: "Filter by disabled state. Optional.",
+                    },
+                  },
+                },
+              },
+              {
+                name: "tui_element_actions",
+                description: "Get action hashes for a detected UI element. Returns click/type/press_key actions that can be used to interact with the element via tui_send/tui_send_key.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    role: {
+                      type: "string",
+                      description: "Element role: button, checkbox, dialog, statusbar, progress, input, label, menu, tab",
+                    },
+                    text: {
+                      type: "string",
+                      description: "Filter by visible text (partial match). Optional.",
+                    },
+                  },
+                  required: ["role"],
+                },
+              },
+              {
+                name: "tui_diff",
+                description: "Compare the current terminal state against a previous state. Returns cell-level differences. Use chars_only: true to ignore color/style changes.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    snapshot: {
+                      type: "object",
+                      description: "A previously saved state snapshot (from tui_state or a prior capture). Must include size, cursor, and rows keys.",
+                    },
+                    chars_only: {
+                      type: "boolean",
+                      description: "If true, only compare character differences (ignore color/style). Default: false.",
+                    },
+                  },
+                  required: ["snapshot"],
+                },
+              },
+              {
+                name: "tui_annotate_element",
+                description: "Manually register a UI element at a specific region. The annotation is picked up by tui_find_elements for subsequent queries.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    role: {
+                      type: "string",
+                      description: "Element role (e.g., button, dialog, statusbar, progress, input, label, menu, tab).",
+                    },
+                    row: {
+                      type: "integer",
+                      description: "Top row of the element.",
+                    },
+                    col: {
+                      type: "integer",
+                      description: "Left column of the element.",
+                    },
+                    width: {
+                      type: "integer",
+                      description: "Width in columns (default: 1).",
+                      default: 1,
+                    },
+                    height: {
+                      type: "integer",
+                      description: "Height in rows (default: 1).",
+                      default: 1,
+                    },
+                    text: {
+                      type: "string",
+                      description: "Visible text label for the element.",
+                    },
+                  },
+                  required: %w[role row col],
+                },
+              },
+              {
+                name: "tui_save_snapshot",
+                description: "Save the current terminal state as a named snapshot to disk. Used to create golden masters for snapshot testing.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Snapshot name (e.g., 'login_screen'). Saved as <name>.json in the snapshot directory.",
+                    },
+                    type: {
+                      type: "string",
+                      enum: %w[text full png html all],
+                      description: "Snapshot type. text=chars_only (default), full=chars+colors, png=screenshot, html=render, all=all formats.",
+                    },
                   },
+                  required: ["name"],
+                },
+              },
+              {
+                name: "tui_assert_snapshot",
+                description: "Assert the current terminal state matches a named snapshot on disk. On first run, creates the snapshot automatically. Set UPDATE_SNAPSHOTS=1 to force update all snapshots.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Snapshot name to compare against.",
+                    },
+                    type: {
+                      type: "string",
+                      enum: %w[text full png html all],
+                      description: "Snapshot type. Default: text.",
+                    },
+                  },
+                  required: ["name"],
                 },
               },
               {
@@ -333,6 +456,11 @@ module TUITD
                  when "tui_exit_status" then call_tui_exit_status
                  when "tui_find_text" then call_tui_find_text(args)
                  when "tui_find_elements" then call_tui_find_elements(args)
+                 when "tui_element_actions" then call_tui_element_actions(args)
+                 when "tui_diff" then call_tui_diff(args)
+                 when "tui_annotate_element" then call_tui_annotate_element(args)
+                 when "tui_save_snapshot" then call_tui_save_snapshot(args)
+                 when "tui_assert_snapshot" then call_tui_assert_snapshot(args)
                  when "tui_close" then call_tui_close
                  else
                    return error_response(id, -32_602, "Unknown tool: #{tool_name}")
@@ -492,8 +620,9 @@ module TUITD
       def call_tui_find_text(args)
         ensure_driver!
         pattern = args["pattern"] or return "ERROR: 'pattern' argument is required"
+        match_mode = (args["match"] || "partial").to_sym
         state = TUITD::State.new(@driver.state_data)
-        matches = state.find_text(pattern)
+        matches = state.find_text(pattern, match: match_mode)
 
         if matches.empty?
           "No matches found for: #{pattern}"
@@ -513,17 +642,29 @@ module TUITD
 
         role = args["role"]&.to_sym
         text = args["text"]
+        checked = args.key?("checked") ? args["checked"] : nil
+        disabled = args.key?("disabled") ? args["disabled"] : nil
+
+        filters = {}
+        filters[:text] = text if text
+        filters[:checked] = checked unless checked.nil?
+        filters[:disabled] = disabled unless disabled.nil?
 
         elements = if role
-                     selector.get_by_role(role)
+                     selector.get_by_role(role, **filters)
                    else
-                     selector.elements
+                     result = selector.elements
+                     result = result.select { |e| e.text&.include?(text) } if text
+                     result = result.select { |e| e.checked == checked } unless checked.nil?
+                     result = result.select { |e| e.disabled == disabled } unless disabled.nil?
+                     result
                    end
-        elements = elements.select { |e| e.text&.include?(text) } if text
 
         if elements.empty?
           desc = role ? "role :#{role}" : "any role"
           desc += " with text #{text.inspect}" if text
+          desc += " checked=#{checked}" unless checked.nil?
+          desc += " disabled=#{disabled}" unless disabled.nil?
           "No elements found for #{desc}"
         else
           lines = ["Found #{elements.size} element(s):"]
@@ -533,12 +674,115 @@ module TUITD
             parts << "at [#{el.row},#{el.col}]"
             parts << "#{el.width}x#{el.height}"
             parts << "(checked)" if el.checked
+            parts << "(disabled)" if el.disabled
+            parts << "(focused)" if el.focused
             lines << parts.join(" ")
           end
           lines.join("\n")
         end
       end
 
+      def call_tui_element_actions(args)
+        ensure_driver!
+        role = args["role"]&.to_sym || (return "ERROR: 'role' argument is required")
+        text = args["text"]
+
+        state = TUITD::State.new(@driver.state_data)
+        selector = TUITD::Selector.new(state)
+
+        filters = {}
+        filters[:text] = text if text
+        element = selector.get_by_role(role, **filters).first
+
+        unless element
+          desc = "No #{role} element"
+          desc << " with text #{text.inspect}" if text
+          desc << " found"
+          return desc
+        end
+
+        lines = ["Element: :#{element.role} #{element.text.inspect} at [#{element.row},#{element.col}]"]
+        lines << "Bounds: #{element.bounds.inspect}"
+        lines << "Actions:"
+        lines << "  click:       #{element.click.inspect}"
+        lines << "  type(text):  #{element.type("text").inspect}"
+        lines << "  press_key:   #{element.press_key(:enter).inspect}"
+        lines.join("\n")
+      end
+
+      def call_tui_diff(args)
+        ensure_driver!
+        snapshot = args["snapshot"] or return "ERROR: 'snapshot' argument is required"
+        chars_only = args["chars_only"] || false
+
+        current = TUITD::State.new(@driver.state_data)
+        snapshot = deep_symbolize(snapshot) if snapshot.is_a?(Hash)
+        diffs = current.diff(snapshot, chars_only: chars_only)
+
+        if diffs.empty?
+          "No differences found (chars_only: #{chars_only})"
+        else
+          lines = ["Found #{diffs.size} difference(s):"]
+          diffs.first(20).each do |d|
+            before_char = d[:before][:char].inspect
+            after_char = d[:after][:char].inspect
+            lines << "  [#{d[:row]},#{d[:col]}] #{before_char} -> #{after_char}"
+          end
+          lines << "  ... (truncated)" if diffs.size > 20
+          lines.join("\n")
+        end
+      end
+
+      def call_tui_annotate_element(args)
+        ensure_driver!
+        role = args["role"] or return "ERROR: 'role' argument is required"
+        row = args["row"] or return "ERROR: 'row' argument is required"
+        col = args["col"] or return "ERROR: 'col' argument is required"
+        width = args["width"] || 1
+        height = args["height"] || 1
+        text = args["text"]
+
+        state = TUITD::State.new(@driver.state_data)
+        state.annotate_role(role, row: row, col: col, width: width, height: height, text: text)
+
+        desc = "OK: Annotated :#{role} at [#{row},#{col}] #{width}x#{height}"
+        desc << " with text #{text.inspect}" if text
+        desc
+      end
+
+      def call_tui_save_snapshot(args)
+        ensure_driver!
+        name = args["name"] or return "ERROR: 'name' argument is required"
+        type = (args["type"] || "text").to_sym
+        snap = Snapshot.new(name, type: type)
+        snap.save(@driver.state_data)
+        "OK: Snapshot '#{name}' (type: #{type}) saved to #{snap.path}"
+      end
+
+      def call_tui_assert_snapshot(args)
+        ensure_driver!
+        name = args["name"] or return "ERROR: 'name' argument is required"
+        type = (args["type"] || "text").to_sym
+        snap = Snapshot.new(name, type: type)
+
+        if TUITD.configuration.update_snapshots?
+          snap.save(@driver.state_data)
+          return "OK: Snapshot '#{name}' (type: #{type}) updated (UPDATE_SNAPSHOTS mode)"
+        end
+
+        unless snap.exists?
+          snap.save(@driver.state_data)
+          return "OK: Snapshot '#{name}' (type: #{type}) created (first run)"
+        end
+
+        result = snap.compare(@driver.state_data)
+        if result.passed?
+          "OK: Snapshot '#{name}' (type: #{type}) matches"
+        else
+          "MISMATCH: #{result.message}"
+        end
+      end
+
       def call_tui_close
         @driver&.close
         @driver = nil
@@ -547,6 +791,17 @@ module TUITD
 
       # --- Helpers ---
 
+      def deep_symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+        when Array
+          obj.map { |v| deep_symbolize(v) }
+        else
+          obj
+        end
+      end
+
       def safe_path(user_path, ext:)
         default = File.join("/tmp", "tui_td_#{Time.now.to_i}.#{ext}")
         resolved = File.expand_path(user_path || default)

data/lib/tui_td/selector.rb

@@ -5,27 +5,4 @@ require "tans-parser"
 module TUITD
   Selector = TansParser::Selector
   Element = TansParser::Element
-
-  # Extend the aliased Selector with within scoping.
-  # within is a testing-specific pattern (scope queries to a dialog region)
-  # and therefore lives in tui-td rather than tans-parser.
-  Selector.class_eval do
-    # Return a new Selector whose elements are filtered to the given bounding box.
-    # Coordinates of returned elements are relative to the box origin.
-    def within(top_row, left_col, width, height)
-      scoped = @elements.select do |e|
-        e.row >= top_row && e.row < top_row + height &&
-          e.col >= left_col && e.col < left_col + width
-      end
-      scoped.each do |e|
-        e = e.dup
-        e.row -= top_row
-        e.col -= left_col
-      end
-      self.class.allocate.tap do |s|
-        s.instance_variable_set(:@state, @state)
-        s.instance_variable_set(:@elements, scoped)
-      end
-    end
-  end
 end

data/lib/tui_td/snapshot.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+require "json"
+require "fileutils"
+
+module TUITD
+  # Named, persisted snapshot for terminal state comparison.
+  #
+  # First run: saves the snapshot to disk (golden master).
+  # Subsequent runs: compares current state against the saved snapshot.
+  #
+  # Types:
+  #   :text  - chars_only comparison (ignores colors/styles), saved as JSON
+  #   :full  - full cell comparison (includes colors/styles), saved as JSON
+  #   :png   - screenshot PNG, compared byte-by-byte
+  #   :html  - HTML render, compared byte-by-byte
+  #   :all   - saves/compares all three formats
+  #
+  # Environment:
+  #   UPDATE_SNAPSHOTS=1 — auto-update all snapshots instead of comparing
+  #
+  class Snapshot
+    EXTENSIONS = {
+      text: ".json",
+      full: ".json",
+      png: ".png",
+      html: ".html",
+    }.freeze
+
+    # Result of a snapshot comparison.
+    ComparisonResult = Struct.new(
+      :passed, :diff_count, :message, :details, :type,
+      keyword_init: true,
+    ) do
+      def passed?
+        passed
+      end
+    end
+
+    attr_reader :name, :type, :snapshot_dir
+
+    def initialize(name, type: :text, snapshot_dir: nil)
+      @name = name.to_s
+      @type = type.to_sym
+      @snapshot_dir = snapshot_dir || TUITD.configuration.snapshot_dir || "spec/snapshots"
+      FileUtils.mkdir_p(@snapshot_dir)
+    end
+
+    # Return the full filesystem path for the given extension.
+    def path(ext = EXTENSIONS.fetch(@type, ".json"))
+      File.join(@snapshot_dir, "#{@name}#{ext}")
+    end
+
+    # Check if the primary snapshot file exists on disk.
+    def exists?
+      if @type == :all
+        %i[text png html].all? { |t| File.exist?(path(EXTENSIONS[t])) }
+      else
+        File.exist?(path)
+      end
+    end
+
+    # Save terminal state as a named snapshot.
+    def save(state_data)
+      data = normalize(state_data)
+
+      File.write(path(".json"), JSON.pretty_generate(data)) if save_json?
+
+      Screenshot.new(data).render(path(".png")) if save_png?
+
+      return unless save_html?
+
+      HtmlRenderer.new(data).render(path(".html"))
+    end
+
+    # Compare current terminal state against the saved snapshot.
+    # Returns ComparisonResult.
+    def compare(state_data, ignore_rows: nil, region: nil)
+      if @type == :all
+        compare_all(state_data, ignore_rows: ignore_rows, region: region)
+      elsif png?
+        compare_png(state_data)
+      elsif html?
+        compare_html(state_data)
+      else
+        compare_json(state_data, chars_only: @type == :text, ignore_rows: ignore_rows, region: region)
+      end
+    end
+
+    private
+
+    def normalize(state_data)
+      return state_data if state_data.is_a?(Hash)
+
+      # Extract hash from State objects
+      if state_data.respond_to?(:grid) && state_data.respond_to?(:rows)
+        return {
+          size: { rows: state_data.rows, cols: state_data.cols },
+          cursor: state_data.cursor,
+          rows: state_data.grid,
+        }
+      end
+
+      state_data
+    end
+
+    def save_json?
+      %i[text full all].include?(@type)
+    end
+
+    def save_png?
+      %i[png all].include?(@type)
+    end
+
+    def save_html?
+      %i[html all].include?(@type)
+    end
+
+    def png?
+      @type == :png
+    end
+
+    def html?
+      @type == :html
+    end
+
+    def compare_json(state_data, chars_only:, ignore_rows: nil, region: nil)
+      file = path(".json")
+      return missing_file_result(file) unless File.exist?(file)
+
+      begin
+        saved = JSON.parse(File.read(file), symbolize_names: true)
+      rescue JSON::ParserError => e
+        return ComparisonResult.new(
+          passed: false, diff_count: 1, type: @type,
+          message: "Failed to parse snapshot JSON: #{e.message}",
+        )
+      end
+
+      current = TUITD::State.new(normalize(state_data))
+      saved_state = TUITD::State.new(saved)
+      diffs = current.diff(saved_state, chars_only: chars_only)
+
+      # Restrict to specified region first, then remove ignored rows
+      if region
+        region = Array(region)
+        diffs.select! { |d| region.include?(d[:row]) }
+      end
+      if ignore_rows
+        ignored = Array(ignore_rows)
+        diffs.reject! { |d| ignored.include?(d[:row]) }
+      end
+
+      if diffs.empty?
+        ComparisonResult.new(
+          passed: true, diff_count: 0, type: @type,
+          message: "Snapshot '#{@name}' matches (#{@type})",
+        )
+      else
+        details = diffs.first(20).map do |d|
+          {
+            row: d[:row], col: d[:col],
+            before: d[:before], after: d[:after],
+          }
+        end
+        msg = ["Snapshot '#{@name}' has #{diffs.size} difference(s) (#{@type}):"]
+        diffs.first(20).each do |d|
+          msg << "  [#{d[:row]},#{d[:col]}] #{d[:before][:char].inspect} -> #{d[:after][:char].inspect}"
+        end
+        msg << "  ... (truncated)" if diffs.size > 20
+        ComparisonResult.new(
+          passed: false, diff_count: diffs.size, type: @type,
+          message: msg.join("\n"), details: details,
+        )
+      end
+    end
+
+    def compare_png(state_data)
+      file = path(".png")
+      return missing_file_result(file) unless File.exist?(file)
+
+      expected = File.binread(file)
+      tmp = File.join(@snapshot_dir, ".#{@name}_tmp.png")
+      Screenshot.new(state_data).render(tmp)
+      actual = File.binread(tmp)
+      FileUtils.rm_f(tmp)
+
+      if expected == actual
+        ComparisonResult.new(
+          passed: true, diff_count: 0, type: :png,
+          message: "Snapshot '#{@name}' matches (png)",
+        )
+      else
+        ComparisonResult.new(
+          passed: false, diff_count: 1, type: :png,
+          message: "Snapshot '#{@name}' does not match (png — pixel difference)",
+        )
+      end
+    end
+
+    def compare_html(state_data)
+      file = path(".html")
+      return missing_file_result(file) unless File.exist?(file)
+
+      expected = File.read(file)
+      actual = HtmlRenderer.new(state_data).to_html
+
+      if expected == actual
+        ComparisonResult.new(
+          passed: true, diff_count: 0, type: :html,
+          message: "Snapshot '#{@name}' matches (html)",
+        )
+      else
+        ComparisonResult.new(
+          passed: false, diff_count: 1, type: :html,
+          message: "Snapshot '#{@name}' does not match (html — content difference)",
+        )
+      end
+    end
+
+    def compare_all(state_data, ignore_rows: nil, region: nil)
+      results = []
+      results << compare_json(state_data, chars_only: true, ignore_rows: ignore_rows, region: region)
+      results << compare_png(state_data)
+      results << compare_html(state_data)
+
+      all_passed = results.all?(&:passed?)
+      messages = results.map(&:message).join("\n")
+      total_diffs = results.sum(&:diff_count)
+
+      ComparisonResult.new(
+        passed: all_passed, diff_count: total_diffs, type: :all,
+        message: messages,
+      )
+    end
+
+    def missing_file_result(file)
+      ComparisonResult.new(
+        passed: false, diff_count: 0, type: @type,
+        message: "Snapshot '#{@name}' not found at #{file}",
+      )
+    end
+  end
+end
+# rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity