tui-td 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b759a458f409fc1596611c306a59a14e04be1842b6f44fff4e45eebd61f6b673
-  data.tar.gz: deb8ebbd1e4804f7874f3af677969e333cda8321fb935a287789fd166ab20a29
+  metadata.gz: b8ebaa8989019a8cd573f682a538ca76a21a17daee810f29a1f178f8f35f0008
+  data.tar.gz: 52fecfc7d59143648f450e71612ac7b7b6839e1b697d03056cb80e0a0dd067ac
 SHA512:
-  metadata.gz: ecb87f37f0af8ec853a37465aa822b4c547b389ef064579243522429c48e885b56d7fdf9d701cc7e5e08bed1adeb5d0a7a035301351531fe68806b24d15f9923
-  data.tar.gz: 53fe8549f0a04d5bf403dda60ab3016e7be26f817453693f6fda68288a926bf89bdd6a86dc858e624a5f4e7ed618d1c8adc1b1e545dedf9fdf2d0926bcfa2543
+  metadata.gz: 9563af163f07bbaae4ea0427120785cc814c444289f7a6bc75b527d9a2e2a5a29785b99f40fa7c31c807c10708693f7f1a5cb5d9c39fea40b82a31e8d8c56964
+  data.tar.gz: 6912a0399394405e8678e33b13b1c95a7575ce5ef7f7731c23a514d2f55c720724c1f4d17bcb73be654a58461bade34d03adfcfd7e615509d1244c53ac8a8673

data/CHANGELOG.md

@@ -1,9 +1,45 @@
 # CHANGELOG
 
-## 0.1.0 (initial)
+## 0.2.0
 
-- PTY-basierter TUI-Driver
-- ANSI-Parser (SGR Farben, Cursor, Erase, 256/Truecolor)
-- Strukturierter State als JSON
-- CLI: run, drive, capture
-- Screenshot-Funktion (ANSI → PNG via terminal-screenshot)
+- Live debug modes for `tui-td test`: `-v` (verbose), `-l` (live screen-refresh), `-s` (step-by-step pause)
+- Fix: skip DEC private mode sequences (`\e[?1049h` alternate screen, `\e[?25h` cursor visibility, etc.)
+- TestRunner `on_step` callback API for programmatic step-by-step observation
+- Vim interaction test example: type, yank, paste, substitute
+- Removed aruba dev dependency from Gemfile
+
+## 0.1.3
+
+- UTF-8 multi-byte character support in ANSI parser (`_utf8_char_at`)
+- `--help` is now a complete CLI reference: Examples section, interactive drive commands
+- `tui-td help test` — JSON test step reference with CLI and Ruby code workflow
+- `tui-td help rspec` — RSpec matchers reference with Driver/State setup workflow
+- `--version` flag
+
+## 0.1.2
+
+- Background reader thread — continuous PTY reads prevent buffer overflow
+- Thread-safe output buffer with Mutex protection
+- DSR (Device Status Report) support — respond to `\e[6n` cursor position requests
+- Replace `IO.select`/`readpartial` with `read_nonblock`
+
+## 0.1.1
+
+- Add `--chdir` / `-C` CLI flag for running commands in a specific directory
+- Default `capture` output to text instead of full JSON grid
+- Use `permute!` for CLI option parsing so global flags work after the command
+- Fix: skip ISO 2022 charset sequences (`ESC(B`) instead of leaking `(B` into output
+- Add `raw` field to state JSON (original ANSI with all escape sequences preserved)
+- Publish to rubygems.org
+
+## 0.1.0
+
+- PTY-based TUI driver with `start`, `send`, `send_keys`, `wait_for_text`, `wait_for_stable`
+- ANSI parser: SGR colors (16, 256, TrueColor), cursor movement, erase, scroll
+- Structured state output: `{size, cursor, rows, raw}`
+- CLI: `capture`, `run`, `drive`, `test`, `serve`
+- Pure Ruby PNG screenshots via `chunky_png` with embedded Spleen 8×16 font
+- HTML renderer with run-length encoding
+- JSON test runner with 12 step types
+- RSpec matchers: `have_text`, `have_fg`, `have_bg`, `have_style`
+- MCP server (JSON-RPC over stdio) for AI-driven TUI testing

data/README.md

@@ -98,24 +98,50 @@ Usage: tui-td <command> [options]
 
 Commands:
   serve              Start MCP server (JSON-RPC over stdio)
-  test <file>        Run JSON test file
-  run <command>      Run a TUI app and show live output
-  drive <command>    Drive a TUI with structured state output
   capture <command>  Run once, capture and display state
+  drive <command>    Drive a TUI interactively
+  run <command>      Run a TUI app and show live output
+  test <file.json>   Run JSON test file
+  help [topic]       Show this help, or help test / help rspec
+
+Examples:
+  tui-td capture "ls -la"
+  tui-td --screenshot out.png capture "htop" --timeout 5
+  tui-td --html out.html capture "glow README.md"
+  tui-td -C /my/project capture "make test"
+  tui-td drive "vim file.txt" --rows 24 --cols 80
+  tui-td test examples/echo_test.json
+  tui-td -vl test examples/vim_hello_world.json
+  tui-td serve
+
+Interactive commands (drive mode):
+  state              Show terminal state as pretty JSON
+  raw                Show raw ANSI output
+  key <name>         Send keystroke (enter, tab, escape, up, down, left, right,
+                     backspace, ctrl_c, ctrl_d)
+  <text>             Send text to the TUI
+  exit               Quit drive mode
 
 Global options:
   -r, --rows N          Terminal rows (default: 40)
   -c, --cols N          Terminal cols (default: 120)
-  -C, --chdir PATH      Working directory for the command
   -t, --timeout N       Timeout in seconds (default: 30)
+  -C, --chdir PATH      Working directory for the command
   --screenshot PATH     Save PNG screenshot
   --html PATH           Save HTML render for browser viewing
   --json                Output state as compact JSON (includes raw ANSI)
   --pretty              Output state as pretty JSON
-  --text                Output state as plain text table (default)
-  -h, --help            Show help
+  --text                Output state as plain text table
+  -v, --verbose         Show each test step as it runs
+  -l, --live            Show terminal state after each test step (screen-refresh)
+  -s, --step            Pause after each test step for confirmation
+  --version             Show version
+  -h, --help            Show complete reference
 ```
 
+`tui-td --help` serves as the full CLI reference. `tui-td help test` shows all JSON test
+step types and `tui-td help rspec` shows all RSpec matchers — no need to consult the docs.
+
 ## Ruby API
 
 ### Driver — Start, send, capture

data/lib/tui_td/ansi_parser.rb

@@ -103,7 +103,7 @@ module TUITD
         if processed[i] == "\e" && processed[i + 1] == "["
           # Find end of CSI sequence
           j = i + 2
-          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@`fmnR]/)
+          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@`fhlmnR]/)
           seq = processed[i..j]
 
           dsr = _apply_csi(seq, cursor, attrs, grid, rows, cols)
@@ -137,16 +137,16 @@ module TUITD
           else
             i += 1
           end
-        elsif processed[i] =~ /[[:print:]]/
-          # Printable character
+        elsif (char, char_len = _utf8_char_at(processed, i))
+          # Printable character (including multi-byte UTF-8)
           if cursor[:row] < rows && cursor[:col] < cols
             cell = grid[cursor[:row]][cursor[:col]]
-            cell[:char] = processed[i]
+            cell[:char] = char
             cell.merge!(attrs)
             cursor[:col] += 1
             cursor[:col] = cols - 1 if cursor[:col] >= cols
           end
-          i += 1
+          i += char_len
         else
           i += 1
         end
@@ -214,7 +214,7 @@ module TUITD
     def self._apply_csi(seq, cursor, attrs, grid, rows, cols)
       # Strip leading escape char if present
       cleaned = seq.sub(/^\e/, "")
-      match = cleaned.match(/^\[([\d;]*)([A-HJ-KP-SX@`fhmnR])$/)
+      match = cleaned.match(/^\[([\d;]*)([A-HJ-KP-SX@`fhlmnR])$/)
       return unless match
 
       params = match[1].split(";").map(&:to_i)
@@ -270,6 +270,8 @@ module TUITD
           next unless cursor[:row] < rows && cursor[:col] + i < cols
           grid[cursor[:row]][cursor[:col] + i][:char] = " "
         end
+      when "h", "l" # DEC private mode set/reset — skip (alternate screen, cursor show/hide, etc.)
+        nil
       when "n" # DSR — Device Status Report request
         # \e[6n = request cursor position → caller must respond with \e[row;colR
         return params[0] == 6
@@ -409,5 +411,38 @@ module TUITD
         nil
       end
     end
+
+    # Extract a single UTF-8 character at position i in a binary string.
+    # Returns [char_string, byte_length] or nil if the byte is not printable/valid.
+    def self._utf8_char_at(str, i)
+      byte = str.getbyte(i)
+      return nil unless byte
+
+      if byte < 0x80
+        # Single-byte ASCII
+        return nil unless byte >= 0x20  # only printable, skip control chars
+        return [byte.chr, 1]
+      end
+
+      # Multi-byte UTF-8
+      len = if byte & 0xE0 == 0xC0
+              2
+      elsif byte & 0xF0 == 0xE0
+              3
+      elsif byte & 0xF8 == 0xF0
+              4
+      else
+              return nil  # continuation byte or invalid — let main loop advance
+      end
+      return nil if i + len > str.bytesize
+
+      bytes = str.byteslice(i, len)
+      char = bytes.dup.force_encoding("UTF-8")
+      return nil unless char.valid_encoding?
+
+      [char, len]
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/tui_td/cli.rb

@@ -18,12 +18,30 @@ module TUITD
         opts.banner = "Usage: tui-td <command> [options]"
         opts.separator ""
         opts.separator "Commands:"
-        opts.separator "  serve             Start MCP server (JSON-RPC over stdio)"
-        opts.separator "  run <command>      Run a TUI app and show live output"
-        opts.separator "  drive <command>    Drive a TUI with structured state output"
+        opts.separator "  serve              Start MCP server (JSON-RPC over stdio)"
         opts.separator "  capture <command>  Run once, capture and display state"
-        opts.separator "  test <file>        Run JSON test file"
-        opts.separator "  help               Show this help"
+        opts.separator "  drive <command>    Drive a TUI interactively"
+        opts.separator "  run <command>      Run a TUI app and show live output"
+        opts.separator "  test <file.json>   Run JSON test file"
+        opts.separator "  help [topic]       Show this help, or help test / help rspec"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  tui-td capture \"ls -la\""
+        opts.separator "  tui-td --screenshot out.png capture \"htop\" --timeout 5"
+        opts.separator "  tui-td --html out.html capture \"glow README.md\""
+        opts.separator "  tui-td -C /my/project capture \"make test\""
+        opts.separator "  tui-td drive \"vim file.txt\" --rows 24 --cols 80"
+        opts.separator "  tui-td test examples/echo_test.json"
+        opts.separator "  tui-td -vl test examples/vim_hello_world.json"
+        opts.separator "  tui-td serve"
+        opts.separator ""
+        opts.separator "Interactive commands (drive mode):"
+        opts.separator "  state              Show terminal state as pretty JSON"
+        opts.separator "  raw                Show raw ANSI output"
+        opts.separator "  key <name>         Send keystroke (enter, tab, escape, up, down, left, right,"
+        opts.separator "                     backspace, ctrl_c, ctrl_d)"
+        opts.separator "  <text>             Send text to the TUI"
+        opts.separator "  exit               Quit drive mode"
         opts.separator ""
         opts.separator "Global options:"
 
@@ -54,6 +72,19 @@ module TUITD
         opts.on("--text", "Output state as plain text table") do |_|
           global_opts[:format] = :text
         end
+        opts.on("-v", "--verbose", "Show each test step as it runs") do |_|
+          global_opts[:verbose] = true
+        end
+        opts.on("-l", "--live", "Show terminal state after each step (screen-refresh)") do |_|
+          global_opts[:live] = true
+        end
+        opts.on("-s", "--step", "Pause after each test step for confirmation") do |_|
+          global_opts[:step_mode] = true
+        end
+        opts.on("--version", "Show version") do
+          puts "tui-td #{TUITD::VERSION}"
+          exit 0
+        end
         opts.on("-h", "--help", "Show help") do
           puts opts
           exit 0
@@ -74,9 +105,20 @@ module TUITD
         cmd_capture(command_opts, global_opts)
       when "test"
         cmd_test(command_opts, global_opts)
-      when nil, "help"
-        puts OptionParser.new { |o| o.banner = "Usage: tui-td <command> [options]" }
-        exit 0
+      when "help"
+        topic = argv.shift
+        case topic
+        when "test"
+          _help_test
+        when "rspec"
+          _help_rspec
+        when nil
+          _help_main
+        else
+          abort "Unknown help topic: #{topic.inspect}\nTry: tui-td help test, tui-td help rspec"
+        end
+      when nil
+        _help_main
       else
         abort "Unknown command: #{command.inspect}\nUse tui-td --help for usage"
       end
@@ -196,9 +238,35 @@ module TUITD
       path = args.first
       abort "File not found: #{path}" unless File.exist?(path)
 
+      verbose = globals[:verbose]
+      live = globals[:live]
+      step_mode = globals[:step_mode]
+
+      on_step = if verbose || live || step_mode
+                  lambda do |info|
+                    if live && info[:driver]
+                      info[:driver].wait_for_stable(stable_ms: 200)
+                    end
+                    if verbose
+                      status = info[:result].passed ? "PASS" : "FAIL"
+                      puts "[#{info[:index] + 1}/#{info[:total]}] #{info[:action]}: #{info[:result].message}"
+                      puts "      → #{status}"
+                    end
+                    if live && info[:driver]
+                      print "\e[2J\e[H"  # clear screen, home cursor
+                      _render_text(info[:driver].state_data)
+                    end
+                    if step_mode
+                      print "\n[Enter=weiter, q=abbruch] "
+                      input = $stdin.gets
+                      exit 1 if input&.chomp == "q"
+                    end
+                  end
+                end
+
       require "json"
       plan = JSON.parse(File.read(path), symbolize_names: true)
-      runner = TestRunner.new(plan)
+      runner = TestRunner.new(plan, on_step: on_step)
       result = runner.run
 
       puts
@@ -228,5 +296,134 @@ module TUITD
         puts line.empty? ? "~" : line
       end
     end
+
+    def _help_main
+      puts OptionParser.new { |o| o.banner = "Usage: tui-td <command> [options]" }
+      puts
+      puts "For more: tui-td help test   (JSON test step types)"
+      puts "          tui-td help rspec  (RSpec matchers)"
+      exit 0
+    end
+
+    def _help_test
+      puts <<~HELP
+        JSON Test Format
+        ================
+
+        Run from CLI:
+
+          tui-td test examples/echo_test.json
+          tui-td -v test examples/echo_test.json   (verbose: show each step)
+          tui-td -vl test examples/echo_test.json  (verbose + live terminal view)
+          tui-td -vs test examples/echo_test.json  (verbose + pause after each step)
+          tui-td -vls test examples/vim_hello_world.json  (all three: watch vim edit live)
+
+        Or from Ruby code:
+
+          require "tui_td/test_runner"
+          runner = TUITD::TestRunner.new(name: "my test", steps: [...])
+          result = runner.run  # => { passed: true, results: [...] }
+
+        A test is a Hash or JSON string: {"name": "...", "steps": [...]}
+
+        Top-level keys: name, steps, rows (default 40), cols (default 120),
+                        timeout (default 30), chdir
+
+        Each step is an object with a single action key:
+
+          {"start": "<command>"}
+              Start a TUI process in a PTY.
+
+          {"send": "<text>"}
+              Send text to the TUI. Use "\\n" for Enter.
+
+          {"send_key": "<name>"}
+              Send a keystroke. Names: enter, tab, escape, up, down,
+              left, right, backspace, ctrl_c, ctrl_d.
+
+          {"wait_for_text": "<substring>"}
+              Wait until the given text appears in the output.
+
+          {"wait_for_stable": true}
+              Wait until the output stops changing (default 300ms quiet).
+
+          {"assert_text": "<substring>"}
+              Fail if the text is not found in the current state.
+
+          {"assert_fg": [row, col], "is": "<color>"}
+              Assert foreground color at cell. Colors: "default",
+              named ANSI (red, green, blue, cyan, ...), "bright_*",
+              "color<N>" (256-color), "#rrggbb" (TrueColor).
+
+          {"assert_bg": [row, col], "is": "<color>"}
+              Assert background color at cell. Same color format.
+
+          {"assert_style": [row, col], "bold": true, "italic": false, ...}
+              Assert style attributes at cell. Checks only the keys provided.
+
+          {"screenshot": "<path>"}
+              Save a PNG screenshot. Path defaults to /tmp/tui_td_<ts>.png.
+
+          {"html": "<path>"}
+              Save an HTML render. Path defaults to /tmp/tui_td_<ts>.html.
+
+          {"close": true}
+              Close the driver session.
+
+        Example test file: examples/echo_test.json
+      HELP
+      exit 0
+    end
+
+    def _help_rspec
+      puts <<~HELP
+        RSpec Matchers
+        ==============
+
+        Matchers work on TUITD::State objects, not raw output.
+        Get a State from the Driver:
+
+          require "tui_td"
+          require "tui_td/matchers"
+
+          driver = TUITD::Driver.new("my_tui", rows: 24, cols: 80)
+          driver.start
+          state = TUITD::State.new(driver.state_data)
+
+          expect(state).to have_text("Hello")
+          expect(state).to have_fg("red").at(0, 5)
+
+          driver.close
+
+        Or build a State manually for unit tests:
+
+          state = TUITD::State.new(
+            size: { rows: 5, cols: 20 },
+            cursor: { row: 0, col: 0 },
+            rows: [[{ char: "H", fg: "default", bg: "default",
+                      bold: false, italic: false, underline: false }]]
+          )
+
+        Matchers
+        --------
+
+        have_text(expected)
+            Passes if expected text appears anywhere in the terminal state.
+            Usage: expect(state).to have_text("Hello")
+
+        have_fg(expected).at(row, col)
+            Assert foreground color at [row, col] matches expected.
+            Usage: expect(state).to have_fg("red").at(0, 5)
+
+        have_bg(expected).at(row, col)
+            Assert background color at [row, col] matches expected.
+            Usage: expect(state).to have_bg("default").at(0, 0)
+
+        have_style.at(row, col).with(bold: true, italic: false, ...)
+            Assert style attributes at [row, col] match the given hash.
+            Usage: expect(state).to have_style.at(0, 0).with(bold: true)
+      HELP
+      exit 0
+    end
   end
 end

data/lib/tui_td/test_runner.rb

@@ -26,10 +26,11 @@ module TUITD
   class TestRunner
     Result = Struct.new(:step, :passed, :message, keyword_init: true)
 
-    def initialize(source)
+    def initialize(source, on_step: nil)
       raw = source.is_a?(String) ? JSON.parse(source) : source
       @plan = raw.transform_keys(&:to_sym)
       @plan[:steps] = @plan[:steps].map { |s| s.transform_keys(&:to_sym) }
+      @on_step = on_step
     end
 
     def run
@@ -150,6 +151,24 @@ module TUITD
 
         results << r
         all_passed &&= r.passed
+
+        if @on_step
+          state_data = nil
+          begin
+            state_data = driver.state_data if driver
+          rescue StandardError
+            # ignore — state retrieval is best-effort
+          end
+          @on_step.call(
+            index: results.size - 1,
+            total: @plan[:steps].size,
+            action: action,
+            value: value,
+            result: r,
+            driver: driver,
+            state_data: state_data
+          )
+        end
       end
 
       driver&.close

data/lib/tui_td/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Haluk Durmus