ratatui_ruby 0.3.1 → 0.4.0

data/tasks/resources/build.yml.erb

@@ -1,19 +1,19 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-image: alpine/edge
+image: archlinux
 packages:
   - bash
-  - build-base
+  - base-devel
   - curl
-  - openssl-dev
-  - yaml-dev
-  - zlib-dev
-  - readline-dev
-  - gdbm-dev
-  - ncurses-dev
-  - libffi-dev
-  - clang-dev
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
   - git
 artifacts:
   - ratatui_ruby/pkg/<%= gem_filename %>
@@ -24,8 +24,10 @@ tasks:
       curl https://mise.jdx.dev/install.sh | sh
       echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
       echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
-      export RUSTFLAGS="-C target-feature=-crt-static"
       export CI="true"
       cd ratatui_ruby
       sed -i 's/ruby = .*/ruby = "<%= ruby_version %>"/' mise.toml

data/tasks/terminal_preview/app_screenshot.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "tmpdir"
+require_relative "launcher_script"
+require_relative "terminal_window"
+require_relative "crash_report"
+
+class AppScreenshot < Data.define(:app, :output_path)
+  def capture
+    print "  📸 #{app}..."
+
+    LauncherScript.new(app.app_path, Dir.pwd).run do |launcher|
+      TerminalWindow.new(launcher.path, launcher.pid_file).open do |window|
+        take_snapshot(window.window_id)
+        puts " done."
+        true
+      end
+    end
+  rescue => e
+    puts " FAILED"
+    puts
+    puts CrashReport.new(app, e, "Program crashed before screenshot could be taken:")
+    puts
+    false
+  end
+
+  private
+
+  def take_snapshot(window_id)
+    system("screencapture -l #{window_id} -o -x '#{output_path}'")
+  end
+end

data/tasks/terminal_preview/crash_report.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class CrashReport < Data.define(:app, :error, :preamble)
+  def self.new(app, error, preamble = nil)
+    # Allow preamble to be optional while Data.define requires all fields
+    super(app:, error:, preamble:)
+  end
+
+  def to_s
+    output = error.message.strip
+    formatted_error = output.split("\n").map { |line| format_line(line) }.join("\n")
+    preamble_section = preamble ? <<~PREAMBLE.chomp : ""
+      #{box_top}
+      #{format_line(preamble)}
+      #{box_bottom}
+    PREAMBLE
+
+    <<~TEXT
+      #{preamble_section}
+      #{border_top(app.to_s)}
+      #{formatted_error}
+      #{box_bottom}
+    TEXT
+  end
+
+  private
+
+  def box_top
+    "┌" + "─" * (width - 2) + "┐"
+  end
+
+  def box_bottom
+    "└" + "─" * (width - 2) + "┘"
+  end
+
+  def border_top(title)
+    left = "┌─ #{title} "
+    right = "┐"
+    dashes = "─" * (width - left.length - right.length)
+    left + dashes + right
+  end
+
+  def format_line(line)
+    truncated = line[0...(width - 4)]
+    "│ #{truncated.ljust(width - 4)} │"
+  end
+
+  def width
+    80
+  end
+end

data/tasks/terminal_preview/example_app.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class ExampleApp < Data.define(:directory)
+  def self.all
+    examples_dir = File.expand_path("../../examples", __dir__)
+    Dir.glob("#{examples_dir}/*/app.rb").map do |path|
+      new(File.basename(File.dirname(path)))
+    end.sort_by(&:directory)
+  end
+
+  def app_path
+    "examples/#{directory}/app.rb"
+  end
+
+  def screenshot_filename
+    "#{directory}.png"
+  end
+
+  def to_s
+    directory
+  end
+end

data/tasks/terminal_preview/launcher_script.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "fileutils"
+require "tmpdir"
+
+class LauncherScript < Data.define(:app_path, :repo_root)
+  def initialize(app_path:, repo_root:)
+    super
+    write
+  end
+
+  def run
+    yield self
+  ensure
+    cleanup
+  end
+
+  def path
+    File.join(Dir.tmpdir, "preview_launcher.sh")
+  end
+
+  def pid_file
+    File.join(Dir.tmpdir, "preview_launcher.pid")
+  end
+
+  private
+
+  def cleanup
+    File.delete(path) if File.exist?(path)
+    File.delete(pid_file) if File.exist?(pid_file)
+  rescue Errno::ENOENT
+    # Already deleted
+  end
+
+  def write
+    File.open(path, "w") do |f|
+      f.puts "#!/bin/zsh"
+      f.puts "cd '#{repo_root}'"
+      f.puts "clear"
+      f.puts "echo $$ > '#{pid_file}'"
+      f.puts "exec bundle exec ruby '#{app_path}'"
+    end
+    FileUtils.chmod(0o755, path)
+  end
+end

data/tasks/terminal_preview/preview_collection.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "fileutils"
+require_relative "example_app"
+require_relative "app_screenshot"
+require_relative "crash_report"
+require_relative "preview_timing"
+require_relative "safety_confirmation"
+require_relative "saved_screenshot"
+
+class PreviewCollection
+  def initialize(output_dir)
+    @output_dir = output_dir
+  end
+
+  def generate
+    abort "Error: This task requires macOS." unless RUBY_PLATFORM.match?(/darwin/)
+
+    apps = ExampleApp.all
+    stale_count = count_stale_apps(apps)
+
+    if stale_count.zero?
+      puts "\n✨ All #{apps.count} screenshots are up to date."
+      return
+    end
+
+    SafetyConfirmation.new(stale_count, apps.count).request
+
+    puts "\nHere we go!"
+    failures = apps.count { |app| !capture_app(app) }
+    
+    if failures.zero?
+      puts "\n✨ All captures complete. Check doc/images/."
+    else
+      abort "\n❌ #{failures} capture(s) failed."
+    end
+  end
+
+  private
+
+  def count_stale_apps(apps)
+    apps.count { |app| SavedScreenshot.for(app, @output_dir).stale? }
+  end
+
+  def capture_app(app)
+    saved = SavedScreenshot.for(app, @output_dir)
+
+    if saved.stale?
+      success = AppScreenshot.new(app, saved.path).capture
+      sleep PreviewTiming.between_captures
+      success
+    else
+      puts "  ⏭️  #{app} (unchanged)"
+      true
+    end
+  end
+  end

data/tasks/terminal_preview/preview_timing.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class PreviewTiming
+  def self.window_startup
+    1.5
+  end
+
+  def self.between_captures
+    0.2
+  end
+
+  def self.close_delay
+    1.0
+  end
+
+  def self.total
+    window_startup + close_delay + between_captures
+  end
+end

data/tasks/terminal_preview/safety_confirmation.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "preview_timing"
+require_relative "system_appearance"
+
+class SafetyConfirmation
+  def initialize(stale_count, total_count)
+    @stale_count = stale_count
+    @total_count = total_count
+  end
+
+  def request
+    print_warning
+    wait_for_user
+  end
+
+  private
+
+  def print_warning
+    unchanged_count = @total_count - @stale_count
+    puts "\n" + "=" * 60
+    puts "  📸  NATIVE TERMINAL CAPTURE  📸"
+    puts "=" * 60
+    puts "This task will:"
+    puts "  1. Take control of your mouse/keyboard focus"
+    puts "  2. Rapidly open and close Terminal windows"
+    puts "  3. Capture #{@stale_count} screenshots (#{unchanged_count} unchanged)"
+    puts
+    puts "Before starting, be sure Terminal.app has the following permissions"
+    puts "in System Settings.app -> Privacy & Security:"
+    puts "  - Screen & System Audio Recording"
+    puts "  - Automation -> System Events"
+    puts
+    puts "⚠️  PLEASE DO NOT TOUCH YOUR COMPUTER WHILE THIS RUNS."
+    min_time = (@stale_count * PreviewTiming.total).to_i
+    max_time = (@stale_count * (PreviewTiming.total + PreviewTiming.close_delay)).to_i
+    puts "   (Estimated time: #{min_time}-#{max_time} seconds)"
+    puts
+  end
+
+  def wait_for_user
+    loop do
+      print "Continue? [Y/n]: "
+      response = $stdin.gets.strip.downcase
+
+      if response.empty? || response == "y"
+        return if SystemAppearance.dark?
+        puts "⚠️  Dark Mode is not enabled. Please enable it in System Settings or Control Center before proceeding."
+        puts
+      elsif response == "n"
+        abort "Cancelled."
+      end
+    end
+  end
+end

data/tasks/terminal_preview/saved_screenshot.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "time"
+
+class SavedScreenshot < Data.define(:app, :path)
+  def self.for(app, output_dir)
+    new(app, File.join(output_dir, app.screenshot_filename))
+  end
+
+  def stale?
+    return true unless exists?
+
+    app_last_modified > screenshot_last_commit_time
+  end
+
+  private
+
+  def exists?
+    File.exist?(path)
+  end
+
+  def app_last_modified
+    # If the file has staged or unstaged changes, it's definitely stale
+    return Time.now.to_i if changed?
+
+    # Otherwise, compare against the last git commit time
+    app_last_commit_time
+  end
+
+  def changed?
+    system("git diff HEAD --quiet #{app.app_path} 2>/dev/null")
+    !$?.success?
+  end
+
+  def app_last_commit_time
+    output = `git log -1 --format=%cI "#{app.app_path}" 2>/dev/null`.strip
+    return 0 if output.empty?
+
+    Time.iso8601(output).to_i
+  rescue StandardError
+    0
+  end
+
+  def screenshot_last_commit_time
+    output = `git log -1 --format=%cI "#{path}" 2>/dev/null`.strip
+    return Time.now.to_i if output.empty?
+
+    Time.iso8601(output).to_i
+  rescue StandardError
+    Time.now.to_i
+  end
+end

data/tasks/terminal_preview/system_appearance.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class SystemAppearance
+  def self.dark?
+    result = `osascript -e 'tell application "System Events" to tell appearance preferences to get dark mode'`.strip
+    result == "true"
+  end
+end

data/tasks/terminal_preview/terminal_window.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "window_id"
+require_relative "preview_timing"
+
+class TerminalWindow
+  CTRL_C = "ASCII character 3"
+
+  def initialize(launcher_script_path, pid_file)
+    @launcher_script_path = launcher_script_path
+    @pid_file = pid_file
+    @window_id = nil
+  end
+
+  def open
+    setup_script = <<~APPLESCRIPT
+      tell application "Terminal"
+        set newTab to do script "#{@launcher_script_path}"
+        set currentWindow to window 1
+        
+        set number of rows of currentWindow to 24
+        set number of columns of currentWindow to 80
+        set position of currentWindow to {100, 100}
+        set frontmost of currentWindow to true
+        
+        return id of currentWindow
+      end tell
+    APPLESCRIPT
+
+    @window_id = WindowID.new(`osascript -e '#{setup_script}'`.strip)
+    wait_for_startup
+    yield self
+  ensure
+    close if @window_id
+  end
+
+  def window_id
+    @window_id
+  end
+
+  private
+
+  def close
+    try_graceful_shutdown
+    kill_process if process_still_alive?
+
+    delay_script = <<~APPLESCRIPT
+      tell application "Terminal"
+        delay #{PreviewTiming.close_delay}
+        
+        try
+          close window id #{@window_id}
+        end try
+      end tell
+    APPLESCRIPT
+
+    system("osascript", "-e", delay_script, out: File::NULL, err: File::NULL)
+  end
+
+  def wait_for_startup
+    sleep PreviewTiming.window_startup
+
+    unless @window_id.valid?
+      raise "Failed to open terminal window"
+    end
+
+    unless process_running?
+      error_output = contents
+      raise error_output
+    end
+  end
+
+  def try_graceful_shutdown
+    shutdown_script = <<~APPLESCRIPT
+      tell application "Terminal"
+        try
+          do script (#{CTRL_C}) in window id #{@window_id}
+        end try
+      end tell
+    APPLESCRIPT
+
+    system("osascript", "-e", shutdown_script, out: File::NULL, err: File::NULL)
+    sleep 0.2
+  end
+
+  def process_still_alive?
+    return false unless @pid_file && File.exist?(@pid_file)
+
+    pid = File.read(@pid_file).strip.to_i
+    Process.kill(0, pid)
+    true
+  rescue Errno::ESRCH, Errno::ENOENT
+    false
+  end
+
+  def kill_process
+    return unless @pid_file && File.exist?(@pid_file)
+
+    pid = File.read(@pid_file).strip.to_i
+    Process.kill("TERM", pid)
+  rescue Errno::ESRCH, Errno::ENOENT
+    # Process already gone or PID file doesn't exist
+  end
+
+  def process_running?
+    check_script = <<~APPLESCRIPT
+      tell application "Terminal"
+        try
+          set theWindow to window id #{@window_id}
+          return busy of theWindow
+        on error
+          return false
+        end try
+      end tell
+    APPLESCRIPT
+
+    result = `osascript -e '#{check_script}'`.strip
+    result == "true"
+  end
+
+  def contents
+    read_script = <<~APPLESCRIPT
+      tell application "Terminal"
+        try
+          set theWindow to window id #{@window_id}
+          return contents of selected tab of theWindow
+        on error
+          return ""
+        end try
+      end tell
+    APPLESCRIPT
+
+    `osascript -e '#{read_script}'`
+  end
+end

data/tasks/terminal_preview/window_id.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class WindowID < Data.define(:value)
+  def valid?
+    !value.empty? && value.match?(/^\d+$/)
+  end
+
+  def to_s
+    value
+  end
+end

data/tasks/terminal_preview.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "fileutils"
+require_relative "terminal_preview/preview_collection"
+require_relative "terminal_preview/example_app"
+
+namespace :terminal_preview do
+  desc "Generate native PNG screenshots using Terminal.app"
+  task :generate do
+    img_dir = File.expand_path("../doc/images", __dir__)
+    FileUtils.mkdir_p(img_dir)
+
+    # Create empty placeholder files for any missing images that compile depends on.
+    # This prevents Rake from trying to build them as dependencies.
+    ExampleApp.all.each do |app|
+      image_path = File.join(img_dir, "#{app}.png")
+      FileUtils.touch(image_path) unless File.exist?(image_path)
+    end
+
+    Rake::Task["compile"].invoke
+
+    collection = PreviewCollection.new(img_dir)
+    collection.generate
+  end
+end

data/tasks/test.rake

@@ -16,7 +16,7 @@ end
 Rake::Task["test"].clear if Rake::Task.task_defined?("test")
 
 desc "Run all tests (Ruby and Rust)"
-task test: %w[test:ruby test:rust]
+task test: %w[compile test:ruby test:rust]
 
 namespace :test do
   desc "Run Rust tests"