tui-td 0.2.11 → 0.2.13

data/lib/tui_td/mcp/server.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Layout/LineLength
+# rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/LineLength
 
 require "json"
 
@@ -60,6 +60,8 @@ module TUITD
         @driver&.close
       end
 
+      ALLOWED_OUTPUT_DIRS = ["/tmp"].freeze
+
       private
 
       def handle_request(request)
@@ -282,6 +284,23 @@ module TUITD
                   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.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    role: {
+                      type: "string",
+                      description: "Filter by role: button, checkbox, dialog, statusbar, progress. Omit to return all.",
+                    },
+                    text: {
+                      type: "string",
+                      description: "Filter by visible text (partial match). Optional.",
+                    },
+                  },
+                },
+              },
               {
                 name: "tui_close",
                 description: "Close the TUI application and clean up the PTY session. Call this when finished.",
@@ -313,7 +332,8 @@ module TUITD
                  when "tui_wait_for_exit" then call_tui_wait_for_exit
                  when "tui_exit_status" then call_tui_exit_status
                  when "tui_find_text" then call_tui_find_text(args)
-                 when "tui_close"     then call_tui_close
+                 when "tui_find_elements" then call_tui_find_elements(args)
+                 when "tui_close" then call_tui_close
                  else
                    return error_response(id, -32_602, "Unknown tool: #{tool_name}")
                  end
@@ -433,7 +453,7 @@ module TUITD
 
       def call_tui_screenshot(args)
         ensure_driver!
-        path = args["path"] || "/tmp/tui_td_#{Time.now.to_i}.png"
+        path = safe_path(args["path"], ext: "png")
         result = @driver.screenshot(path)
         "OK: Screenshot saved to #{result}"
       end
@@ -444,8 +464,9 @@ module TUITD
         renderer = HtmlRenderer.new(@driver.state_data)
 
         if path
-          renderer.render(path)
-          "OK: HTML saved to #{path}"
+          safe = safe_path(path, ext: "html")
+          renderer.render(safe)
+          "OK: HTML saved to #{safe}"
         else
           renderer.to_html
         end
@@ -485,6 +506,39 @@ module TUITD
         end
       end
 
+      def call_tui_find_elements(args)
+        ensure_driver!
+        state = TUITD::State.new(@driver.state_data)
+        selector = TUITD::Selector.new(state)
+
+        role = args["role"]&.to_sym
+        text = args["text"]
+
+        elements = if role
+                     selector.get_by_role(role)
+                   else
+                     selector.elements
+                   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
+          "No elements found for #{desc}"
+        else
+          lines = ["Found #{elements.size} element(s):"]
+          elements.each do |el|
+            parts = ["  :#{el.role}"]
+            parts << el.text.inspect if el.text
+            parts << "at [#{el.row},#{el.col}]"
+            parts << "#{el.width}x#{el.height}"
+            parts << "(checked)" if el.checked
+            lines << parts.join(" ")
+          end
+          lines.join("\n")
+        end
+      end
+
       def call_tui_close
         @driver&.close
         @driver = nil
@@ -493,6 +547,17 @@ module TUITD
 
       # --- Helpers ---
 
+      def safe_path(user_path, ext:)
+        default = File.join("/tmp", "tui_td_#{Time.now.to_i}.#{ext}")
+        resolved = File.expand_path(user_path || default)
+
+        unless ALLOWED_OUTPUT_DIRS.any? { |dir| resolved.start_with?(File.expand_path(dir)) }
+          raise TUITD::Error, "Output path must be under one of: #{ALLOWED_OUTPUT_DIRS.join(", ")}"
+        end
+
+        resolved
+      end
+
       def ensure_driver!
         raise Error, "No TUI session active. Call tui_start first." if @driver.nil?
       end
@@ -530,4 +595,4 @@ module TUITD
     end
   end
 end
-# rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Layout/LineLength
+# rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/LineLength

data/lib/tui_td/selector.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+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/state.rb

@@ -1,128 +1,7 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+require "tans-parser"
 
 module TUITD
-  # Represents the parsed state of a terminal screen.
-  # Provides high-level query methods for AI consumption.
-  class State
-    attr_reader :rows, :cols, :grid, :cursor, :cursor_visible, :cursor_style, :mouse_mode, :mouse_format
-
-    def initialize(data)
-      raise ArgumentError, "State data must include :size key" unless data[:size]
-      raise ArgumentError, "State data must include :rows key" unless data[:rows]
-
-      @rows = data[:size][:rows]
-      @cols = data[:size][:cols]
-      @grid = data[:rows]
-      @cursor = data[:cursor]
-
-      cursor_info = data[:cursor].is_a?(Hash) ? data[:cursor] : {}
-      @cursor_visible = data.key?(:cursor_visible) ? data[:cursor_visible] : (cursor_info[:visible] != false)
-      @cursor_style = data.key?(:cursor_style) ? data[:cursor_style] : (cursor_info[:style] || 1)
-
-      @mouse_mode = data[:mouse_mode] || :none
-      @mouse_format = data[:mouse_format] || :normal
-    end
-
-    # Get plain text of the entire terminal (no ANSI)
-    def plain_text
-      @grid.map { |row| row.map { |c| c[:char] }.join.rstrip }.join("\n")
-    end
-
-    # Get text at a specific position
-    def text_at(row, col, length = @cols - col)
-      return "" if row >= @rows || col >= @cols
-
-      @grid[row][col, length].map { |c| c[:char] }.join
-    end
-
-    # Search for text across the entire terminal
-    def find_text(pattern)
-      results = []
-      @grid.each_with_index do |row, ri|
-        text = row.map { |c| c[:char] }.join
-        pos = 0
-        while (match = text.index(pattern, pos))
-          results << { row: ri, col: match, text: pattern, full_line: text }
-          pos = match + 1
-        end
-      end
-      results
-    end
-
-    # Get the color at a specific cell
-    def foreground_at(row, col)
-      return nil if row >= @rows || col >= @cols
-
-      @grid[row][col][:fg]
-    end
-
-    def background_at(row, col)
-      return nil if row >= @rows || col >= @cols
-
-      @grid[row][col][:bg]
-    end
-
-    def style_at(row, col)
-      return nil if row >= @rows || col >= @cols
-
-      cell = @grid[row][col]
-      { bold: cell[:bold], italic: cell[:italic], underline: cell[:underline] }
-    end
-
-    def to_ai_json
-      h = extract_highlights
-      cursor_info = @cursor.is_a?(Hash) ? @cursor : {}
-      r = cursor_info[:row] || cursor_info["row"] || 0
-      c = cursor_info[:col] || cursor_info["col"] || 0
-      styled_count = h.count { |hl| hl[:bold] || hl[:italic] || hl[:underline] || hl[:fg] || hl[:bg] }
-
-      summary = "Cursor at [#{r},#{c}]. "
-      summary << "#{styled_count} styled row#{"s" unless styled_count == 1}"
-      fgs = h.flat_map { |hl| hl[:fg] }.compact.uniq
-      bgs = h.flat_map { |hl| hl[:bg] }.compact.uniq
-      summary << ", colors: fg=#{fgs.sort.join(",")}" unless fgs.empty?
-      summary << ", bg=#{bgs.sort.join(",")}" unless bgs.empty?
-      summary << "."
-
-      {
-        size: { rows: @rows, cols: @cols },
-        cursor: cursor_info,
-        text: plain_text,
-        highlights: h,
-        summary: summary,
-      }
-    end
-
-    private
-
-    def extract_highlights
-      highlights = []
-      @grid.each_with_index do |row, ri|
-        row_text = row.map { |c| c[:char] }.join
-        next if row_text.strip.empty?
-
-        fgs = row.map { |c| c[:fg] || c["fg"] || "default" }
-                 .uniq.reject { |c| c == "default" }
-        bgs = row.map { |c| c[:bg] || c["bg"] || "default" }
-                 .uniq.reject { |c| c == "default" }
-        bold = row.any? { |c| c[:bold] || c["bold"] }
-        italic = row.any? { |c| c[:italic] || c["italic"] }
-        underline = row.any? { |c| c[:underline] || c["underline"] }
-
-        next if fgs.empty? && bgs.empty? && !bold && !italic && !underline
-
-        h = { row: ri, text: row_text }
-        h[:bold] = true if bold
-        h[:italic] = true if italic
-        h[:underline] = true if underline
-        h[:fg] = fgs.size == 1 ? fgs.first : fgs unless fgs.empty?
-        h[:bg] = bgs.size == 1 ? bgs.first : bgs unless bgs.empty?
-        highlights << h
-      end
-      highlights
-    end
-  end
+  State = TansParser::State
 end
-# rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

data/lib/tui_td/test_runner.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
+# rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength, Metrics/ClassLength
 
 require "json"
+require "shellwords"
 
 module TUITD
   # Executes TUI tests defined in JSON format.
@@ -108,29 +109,41 @@ module TUITD
                 when "assert_style"
                   ensure_driver!(driver)
                   row, col = coords(step)
-                  state = State.new(driver.state_data)
-                  actual = state.style_at(row, col)
-                  expected = {}
-                  expected[:bold] = step[:bold] unless step[:bold].nil?
-                  expected[:italic] = step[:italic] unless step[:italic].nil?
-                  expected[:underline] = step[:underline] unless step[:underline].nil?
-                  match = expected.all? { |k, v| actual[k] == v }
+                  expected_style = {}
+                  expected_style[:bold] = step[:bold] unless step[:bold].nil?
+                  expected_style[:italic] = step[:italic] unless step[:italic].nil?
+                  expected_style[:underline] = step[:underline] unless step[:underline].nil?
+                  actual = nil
+                  match = begin
+                    driver.wait_for(timeout: 2) do |s|
+                      actual = s.style_at(row, col)
+                      expected_style.all? { |k, v| actual[k] == v }
+                    end
+                    true
+                  rescue TimeoutError
+                    false
+                  end
+                  actual ||= begin
+                    state = State.new(driver.state_data)
+                    state.style_at(row, col)
+                  end
                   if match
-                    Result.new(step: action, passed: true, message: "Style at [#{row},#{col}] matches #{expected}")
+                    Result.new(step: action, passed: true,
+                               message: "Style at [#{row},#{col}] matches #{expected_style}",)
                   else
                     Result.new(step: action, passed: false,
-                               message: "Style at [#{row},#{col}] is #{actual}, expected #{expected}",)
+                               message: "Style at [#{row},#{col}] is #{actual}, expected #{expected_style}",)
                   end
 
                 when "screenshot"
                   ensure_driver!(driver)
-                  path = value.is_a?(String) ? value : "/tmp/tui_td_#{Time.now.to_i}.png"
+                  path = safe_output_path(value, "png")
                   driver.screenshot(path)
                   Result.new(step: action, passed: true, message: "Saved: #{path}")
 
                 when "html"
                   ensure_driver!(driver)
-                  path = value.is_a?(String) ? value : "/tmp/tui_td_#{Time.now.to_i}.html"
+                  path = safe_output_path(value, "html")
                   HtmlRenderer.new(driver.state_data).render(path)
                   Result.new(step: action, passed: true, message: "Saved: #{path}")
 
@@ -150,6 +163,19 @@ module TUITD
                     Result.new(step: action, passed: false, message: "Exit status #{actual}, expected #{expected}")
                   end
 
+                when "assert_button"
+                  check_role(driver, :button, value.to_s)
+
+                when "assert_dialog"
+                  check_role(driver, :dialog, nil)
+
+                when "assert_checkbox"
+                  check_role(driver, :checkbox, value.to_s, checked: step[:checked])
+
+                when "assert_role"
+                  role = step[:role]&.to_sym
+                  check_role(driver, role, value.to_s)
+
                 when "close"
                   driver&.close
                   driver = nil
@@ -194,8 +220,40 @@ module TUITD
       }
     end
 
+    ALLOWED_OUTPUT_DIRS = ["/tmp"].freeze
+
     private
 
+    def check_role(driver, role, text, checked: nil)
+      ensure_driver!(driver)
+      state = State.new(driver.state_data)
+      selector = Selector.new(state)
+      elements = selector.get_by_role(role)
+      elements = elements.select { |e| e.text&.include?(text.to_s) } if text
+      elements = elements.select { |e| e.checked == checked } unless checked.nil?
+
+      action = "assert_#{role}"
+      if elements.any?
+        count = elements.size
+        desc = text ? "#{role} #{text.inspect}" : role.to_s
+        Result.new(step: action, passed: true, message: "Found #{count} #{desc} element(s)")
+      else
+        desc = text ? "#{role} with text #{text.inspect}" : role.to_s
+        Result.new(step: action, passed: false, message: "No #{desc} found")
+      end
+    end
+
+    def safe_output_path(value, ext)
+      default = File.join("/tmp", "tui_td_#{Time.now.to_i}.#{ext}")
+      resolved = File.expand_path(value.is_a?(String) ? value : default)
+
+      unless ALLOWED_OUTPUT_DIRS.any? { |dir| resolved.start_with?(File.expand_path(dir)) }
+        raise TUITD::Error, "Output path must be under one of: #{ALLOWED_OUTPUT_DIRS.join(", ")}"
+      end
+
+      resolved
+    end
+
     def ensure_driver!(driver)
       raise Error, "No session. Add a 'start' step first." if driver.nil?
     end
@@ -209,7 +267,6 @@ module TUITD
 
     def check_text(driver, value, action)
       ensure_driver!(driver)
-      state = State.new(driver.state_data)
       text = value.to_s
 
       if action == "assert_regex"
@@ -222,7 +279,17 @@ module TUITD
         pattern = text
       end
 
-      found = state.find_text(pattern).any?
+      found = if action == "assert_not_text"
+                state = State.new(driver.state_data)
+                state.find_text(pattern).any?
+              else
+                begin
+                  driver.wait_for(timeout: 2) { |s| s.find_text(pattern).any? }
+                  true
+                rescue TimeoutError
+                  false
+                end
+              end
 
       case action
       when "assert_text"
@@ -252,17 +319,32 @@ module TUITD
       ensure_driver!(driver)
       row, col = coords(step)
       expected = step[:is] || step["is"]
-      state = State.new(driver.state_data)
       label = property == :fg ? "FG" : "BG"
-      actual = property == :fg ? state.foreground_at(row, col) : state.background_at(row, col)
 
-      if actual == expected
+      actual_val = nil
+      found = begin
+        driver.wait_for(timeout: 2) do |s|
+          actual_val = property == :fg ? s.foreground_at(row, col) : s.background_at(row, col)
+          actual_val == expected
+        end
+        true
+      rescue TimeoutError
+        # actual_val holds the last observed value
+        false
+      end
+
+      actual_val ||= begin
+        state = State.new(driver.state_data)
+        property == :fg ? state.foreground_at(row, col) : state.background_at(row, col)
+      end
+
+      if found
         Result.new(step: step.keys.first.to_s, passed: true, message: "#{label} at [#{row},#{col}] is #{expected}")
       else
         Result.new(step: step.keys.first.to_s, passed: false,
-                   message: "#{label} at [#{row},#{col}] is #{actual}, expected #{expected}",)
+                   message: "#{label} at [#{row},#{col}] is #{actual_val}, expected #{expected}",)
       end
     end
   end
 end
-# rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
+# rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength, Metrics/ClassLength

data/lib/tui_td/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TUITD
-  VERSION = "0.2.11"
+  VERSION = "0.2.13"
 end

data/lib/tui_td.rb

@@ -16,6 +16,7 @@ require_relative "tui_td/state"
 require_relative "tui_td/screenshot"
 require_relative "tui_td/html_renderer"
 require_relative "tui_td/test_runner"
+require_relative "tui_td/selector"
 require_relative "tui_td/mcp/server"
 require_relative "tui_td/cli"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.2.11
+  version: 0.2.13
 platform: ruby
 authors:
 - Haluk Durmus
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: tans-parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -159,6 +173,7 @@ files:
 - lib/tui_td/matchers.rb
 - lib/tui_td/mcp/server.rb
 - lib/tui_td/screenshot.rb
+- lib/tui_td/selector.rb
 - lib/tui_td/state.rb
 - lib/tui_td/test_runner.rb
 - lib/tui_td/unifont_glyphs.rb