cli-ui 2.3.1 → 2.6.0

data/lib/cli/ui/progress_reporter.rb

@@ -0,0 +1,209 @@
+# typed: true
+# frozen_string_literal: true
+
+module CLI
+  module UI
+    # Handles terminal progress bar reporting using ConEmu OSC 9;4 sequences
+    # Supports:
+    # - Numerical progress (0-100%)
+    # - Indeterminate/pulsing progress
+    # - Success/error states
+    # - Paused state
+    module ProgressReporter
+      # Progress reporter instance that manages the lifecycle of progress reporting
+      class Reporter
+        # OSC (Operating System Command) escape sequences
+        OSC = "\e]"
+        ST = "\a" # String Terminator (BEL)
+
+        # Progress states
+        REMOVE = 0
+        SET_PROGRESS = 1
+        ERROR = 2
+        INDETERMINATE = 3
+        PAUSED = 4
+
+        #: (Symbol mode, ?io_like to, ?parent: Reporter?, ?delay_start: bool) -> void
+        def initialize(mode, to = $stdout, parent: nil, delay_start: false)
+          @mode = mode
+          @to = to
+          @parent = parent
+          @children = []
+          @active = ProgressReporter.supports_progress? && @parent.nil?
+
+          # Register with parent if nested
+          @parent&.add_child(self)
+
+          return unless @active
+          return if delay_start # Don't emit initial OSC if delayed
+
+          case mode
+          when :indeterminate
+            set_indeterminate
+          when :progress
+            set_progress(0)
+          else
+            raise ArgumentError, "Unknown progress mode: #{mode}"
+          end
+        end
+
+        #: (Reporter child) -> void
+        def add_child(child)
+          @children << child
+        end
+
+        #: (Reporter child) -> void
+        def remove_child(child)
+          @children.delete(child)
+        end
+
+        #: -> bool
+        def has_active_children?
+          @children.any?
+        end
+
+        #: (Integer percentage) -> void
+        def set_progress(percentage) # rubocop:disable Naming/AccessorMethodName
+          # Don't emit progress if we have active children (they own the progress)
+          return if has_active_children?
+          return unless @active
+
+          @mode = :progress # Update mode when switching to progress
+          percentage = percentage.clamp(0, 100)
+          @to.print("#{OSC}9;4;#{SET_PROGRESS};#{percentage}#{ST}")
+        end
+
+        #: -> void
+        def set_indeterminate
+          # Don't emit progress if we have active children
+          return if has_active_children?
+          return unless @active
+
+          @mode = :indeterminate # Update mode when switching to indeterminate
+          @to.print("#{OSC}9;4;#{INDETERMINATE};#{ST}")
+        end
+
+        # Force progress mode even if there are children - used by SpinGroup
+        # when a task needs to show deterministic progress
+        #: (Integer percentage) -> void
+        def force_set_progress(percentage)
+          return unless @active
+
+          @mode = :progress
+          percentage = percentage.clamp(0, 100)
+          @to.print("#{OSC}9;4;#{SET_PROGRESS};#{percentage}#{ST}")
+        end
+
+        # Force indeterminate mode even if there are children
+        #: -> void
+        def force_set_indeterminate
+          return unless @active
+
+          @mode = :indeterminate
+          @to.print("#{OSC}9;4;#{INDETERMINATE};#{ST}")
+        end
+
+        #: -> void
+        def set_error
+          # Error state can be set even with children
+          return unless @active
+
+          @to.print("#{OSC}9;4;#{ERROR};#{ST}")
+        end
+
+        #: (?Integer? percentage) -> void
+        def set_paused(percentage = nil)
+          return if has_active_children?
+          return unless @active
+
+          if percentage
+            percentage = percentage.clamp(0, 100)
+            @to.print("#{OSC}9;4;#{PAUSED};#{percentage}#{ST}")
+          else
+            @to.print("#{OSC}9;4;#{PAUSED};#{ST}")
+          end
+        end
+
+        #: -> void
+        def clear
+          # Only clear if we're the root reporter and have no active children
+          return unless @active
+          return if has_active_children?
+
+          @to.print("#{OSC}9;4;#{REMOVE};#{ST}")
+        end
+
+        #: -> void
+        def cleanup
+          # Remove self from parent's children list
+          @parent&.remove_child(self)
+
+          # If parent exists and has no more children, restore its progress state
+          if @parent && !@parent.has_active_children?
+            case @parent.instance_variable_get(:@mode)
+            when :indeterminate
+              @parent.set_indeterminate
+            when :progress
+              # Parent progress bar should maintain its last state
+              # The parent will handle re-emitting its progress on next tick
+            end
+          elsif !@parent
+            # We're the root, clear progress
+            clear
+          end
+        end
+      end
+
+      class << self
+        # Thread-local storage for the current reporter stack
+        #: -> Array[Reporter]
+        def reporter_stack
+          Thread.current[:progress_reporter_stack] ||= []
+        end
+
+        #: -> Reporter?
+        def current_reporter
+          reporter_stack.last
+        end
+
+        # Block-based API that ensures progress is cleared
+        #: [T] (?mode: Symbol, ?to: io_like, ?delay_start: bool) { (Reporter reporter) -> T } -> T
+        def with_progress(mode: :indeterminate, to: $stdout, delay_start: false, &block)
+          parent = current_reporter
+          reporter = Reporter.new(mode, to, parent: parent, delay_start: delay_start)
+
+          reporter_stack.push(reporter)
+          yield(reporter)
+        ensure
+          reporter_stack.pop
+          reporter&.cleanup
+        end
+
+        #: -> bool
+        def supports_progress?
+          # Check if terminal supports ConEmu OSC sequences
+          # This is supported by:
+          # - ConEmu on Windows
+          # - Windows Terminal
+          # - Ghostty
+          # - Various terminals on Linux (with OSC 9;4 support)
+
+          # Check common environment variables that indicate support
+          return true if ENV['ConEmuPID']
+          return true if ENV['WT_SESSION'] # Windows Terminal
+          return true if ENV['GHOSTTY_RESOURCES_DIR'] # Ghostty
+
+          # Check TERM_PROGRAM for known supporting terminals
+          term_program = ENV['TERM_PROGRAM']
+          return true if term_program == 'ghostty'
+
+          # For now, we'll be conservative and only enable for known terminals
+          # Users can force-enable with an environment variable
+          return true if ENV['CLI_UI_ENABLE_PROGRESS'] == '1'
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/cli/ui/prompt/interactive_options.rb

@@ -8,14 +8,10 @@ module CLI
   module UI
     module Prompt
       class InteractiveOptions
-        extend T::Sig
-
         DONE = 'Done'
         CHECKBOX_ICON = { false => '☐', true => '☑' }
 
         class << self
-          extend T::Sig
-
           # Prompts the user with options
           # Uses an interactive session to allow the user to pick an answer
           # Can use arrows, y/n, numbers (1/2), and vim bindings to control
@@ -30,18 +26,17 @@ module CLI
           # Ask an interactive question
           #   CLI::UI::Prompt::InteractiveOptions.call(%w(rails go python))
           #
-          sig do
-            params(options: T::Array[String], multiple: T::Boolean, default: T.nilable(T.any(String, T::Array[String])))
-              .returns(T.any(String, T::Array[String]))
-          end
+          #: (Array[String] options, ?multiple: bool, ?default: (String | Array[String])?) -> (String | Array[String])
           def call(options, multiple: false, default: nil)
             list = new(options, multiple: multiple, default: default)
             selected = list.call
             case selected
             when Array
-              selected.map { |s| T.must(options[s - 1]) }
+              selected.map do |s|
+                options[s - 1] #: as !nil
+              end
             else
-              T.must(options[selected - 1])
+              options[selected - 1] #: as !nil
             end
           end
         end
@@ -53,10 +48,7 @@ module CLI
         #
         #   CLI::UI::Prompt::InteractiveOptions.new(%w(rails go python))
         #
-        sig do
-          params(options: T::Array[String], multiple: T::Boolean, default: T.nilable(T.any(String, T::Array[String])))
-            .void
-        end
+        #: (Array[String] options, ?multiple: bool, ?default: (String | Array[String])?) -> void
         def initialize(options, multiple: false, default: nil)
           @options = options
           @active = if default && (i = options.index(default))
@@ -82,13 +74,13 @@ module CLI
             end
           end
           @redraw = true
-          @presented_options = T.let([], T::Array[[String, T.nilable(Integer)]])
+          @presented_options = [] #: Array[[String, Integer?]]
         end
 
         # Calls the +InteractiveOptions+ and asks the question
         # Usually used from +self.call+
         #
-        sig { returns(T.any(Integer, T::Array[Integer])) }
+        #: -> (Integer | Array[Integer])
         def call
           calculate_option_line_lengths
           CLI::UI.raw { print(ANSI.hide_cursor) }
@@ -108,7 +100,7 @@ module CLI
 
         private
 
-        sig { void }
+        #: -> void
         def calculate_option_line_lengths
           @terminal_width_at_calculation_time = CLI::UI::Terminal.width
           # options will be an array of questions but each option can be multi-line
@@ -138,7 +130,7 @@ module CLI
           end
         end
 
-        sig { params(number_of_lines: Integer).void }
+        #: (?Integer number_of_lines) -> void
         def reset_position(number_of_lines = num_lines)
           # This will put us back at the beginning of the options
           # When we redraw the options, they will be overwritten
@@ -147,7 +139,7 @@ module CLI
           end
         end
 
-        sig { params(number_of_lines: Integer).void }
+        #: (?Integer number_of_lines) -> void
         def clear_output(number_of_lines = num_lines)
           CLI::UI.raw do
             # Write over all lines with whitespace
@@ -163,12 +155,12 @@ module CLI
 
         # Don't use this in place of +@displaying_metadata+, this updates too
         # quickly to be useful when drawing to the screen.
-        sig { returns(T::Boolean) }
+        #: -> bool
         def display_metadata?
           filtering? || selecting? || has_filter?
         end
 
-        sig { returns(Integer) }
+        #: -> Integer
         def num_lines
           calculate_option_line_lengths if terminal_width_changed?
 
@@ -182,7 +174,7 @@ module CLI
           option_length + (@displaying_metadata ? 1 : 0)
         end
 
-        sig { returns(T::Boolean) }
+        #: -> bool
         def terminal_width_changed?
           @terminal_width_at_calculation_time != CLI::UI::Terminal.width
         end
@@ -192,7 +184,7 @@ module CLI
         CTRL_C = "\u0003"
         CTRL_D = "\u0004"
 
-        sig { void }
+        #: -> void
         def up
           active_index = @filtered_options.index { |_, num| num == @active } || 0
 
@@ -203,7 +195,7 @@ module CLI
           @redraw = true
         end
 
-        sig { void }
+        #: -> void
         def down
           active_index = @filtered_options.index { |_, num| num == @active } || 0
 
@@ -214,10 +206,45 @@ module CLI
           @redraw = true
         end
 
+        #: -> void
+        def first_option
+          @active = @filtered_options.first&.last || -1
+          @redraw = true
+        end
+
+        #: -> void
+        def last_option
+          @active = @filtered_options.last&.last || -1
+          @redraw = true
+        end
+
+        #: -> void
+        def next_page
+          active_index = @filtered_options.index { |_, num| num == @active } || 0
+
+          previous_visible = @filtered_options[active_index + max_lines]
+          previous_visible ||= @filtered_options.last
+
+          @active = previous_visible ? previous_visible.last : -1
+          @redraw = true
+        end
+
+        #: -> void
+        def previous_page
+          active_index = @filtered_options.index { |_, num| num == @active } || 0
+
+          # do not jump into the end of the options if the subtraction result is non-positive
+          previous_visible = @filtered_options[active_index - max_lines] if active_index - max_lines >= 0
+          previous_visible ||= @filtered_options.first
+
+          @active = previous_visible ? previous_visible.last : -1
+          @redraw = true
+        end
+
         # n is 1-indexed selection
         # n == 0 if "Done" was selected in @multiple mode
-        sig { params(n: Integer).void }
-        def select_n(n)
+        #: (Integer n, ?final: bool) -> void
+        def select_n(n, final: false)
           if @multiple
             if n == 0
               @answer = []
@@ -230,7 +257,7 @@ module CLI
             end
           elsif n == 0
             # Ignore pressing "0" when not in multiple mode
-          elsif should_enter_select_mode?(n)
+          elsif !final && should_enter_select_mode?(n)
             # When we have more than 9 options, we need to enter select mode
             # to avoid pre-selecting (e.g) 1 when the user wanted 10.
             # This also applies to 2 and 20+ options, 3/30+, etc.
@@ -243,7 +270,7 @@ module CLI
           @redraw = true
         end
 
-        sig { params(n: Integer).returns(T::Boolean) }
+        #: (Integer n) -> bool
         def should_enter_select_mode?(n)
           # If we have less than 10 options, we don't need to enter select mode
           # and we can just select the option directly. This just keeps the code easier
@@ -257,29 +284,29 @@ module CLI
           @options.length >= (n * 10)
         end
 
-        sig { params(char: String).void }
+        #: (String char) -> void
         def select_bool(char)
           return unless (@options - ['yes', 'no']).empty?
 
-          index = T.must(@options.index { |o| o.start_with?(char) })
+          index = @options.index { |o| o.start_with?(char) } #: as !nil
           @active = index + 1
           @answer = index + 1
           @redraw = true
         end
 
-        sig { params(char: String).void }
+        #: (String char) -> void
         def build_selection(char)
           @active = (@active.to_s + char).to_i
           @redraw = true
         end
 
-        sig { void }
+        #: -> void
         def chop_selection
           @active = @active.to_s.chop.to_i
           @redraw = true
         end
 
-        sig { params(char: String).void }
+        #: (String char) -> void
         def update_search(char)
           @redraw = true
 
@@ -297,22 +324,22 @@ module CLI
           end
         end
 
-        sig { void }
+        #: -> void
         def select_current
           # Prevent selection of invisible options
           return unless presented_options.any? { |_, num| num == @active }
 
-          select_n(@active)
+          select_n(@active, final: true)
         end
 
-        sig { void }
+        #: -> void
         def process_input_until_redraw_required
           @redraw = false
           wait_for_user_input until @redraw
         end
 
         # rubocop:disable Style/WhenThen,Layout/SpaceBeforeSemicolon,Style/Semicolon
-        sig { void }
+        #: -> void
         def wait_for_user_input
           char = Prompt.read_char
           @last_char = char
@@ -363,48 +390,53 @@ module CLI
             when 'B'      ; down
             when 'C'      ; # Ignore right key
             when 'D'      ; # Ignore left key
+            when '3'      ; print("\a")
+            when '5'      ; previous_page
+            when '6'      ; next_page
+            when 'H'      ; first_option
+            when 'F'      ; last_option
             else          ; raise Interrupt # unhandled escape sequence.
             end
           end
         end
         # rubocop:enable Style/WhenThen,Layout/SpaceBeforeSemicolon,Style/Semicolon
 
-        sig { returns(T::Boolean) }
+        #: -> bool
         def selecting?
           @state == :line_select
         end
 
-        sig { returns(T::Boolean) }
+        #: -> bool
         def filtering?
           @state == :filter
         end
 
-        sig { returns(T::Boolean) }
+        #: -> bool
         def has_filter?
           !@filter.empty?
         end
 
-        sig { void }
+        #: -> void
         def start_filter
           @state = :filter
           @redraw = true
         end
 
-        sig { void }
+        #: -> void
         def start_line_select
           @state  = :line_select
           @active = 0
           @redraw = true
         end
 
-        sig { void }
+        #: -> void
         def stop_line_select
           @state = :root
           @active = 1 if @active.zero?
           @redraw = true
         end
 
-        sig { params(recalculate: T::Boolean).returns(T::Array[[String, T.nilable(Integer)]]) }
+        #: (?recalculate: bool) -> Array[[String, Integer?]]
         def presented_options(recalculate: false)
           return @presented_options unless recalculate
 
@@ -447,44 +479,44 @@ module CLI
           @presented_options
         end
 
-        sig { void }
+        #: -> void
         def ensure_visible_is_active
           unless presented_options.any? { |_, num| num == @active }
             @active = presented_options.first&.last.to_i
           end
         end
 
-        sig { returns(Integer) }
+        #: -> Integer
         def distance_from_selection_to_end
           @presented_options.count - index_of_active_option
         end
 
-        sig { returns(Integer) }
+        #: -> Integer
         def distance_from_start_to_selection
           index_of_active_option
         end
 
-        sig { returns(Integer) }
+        #: -> Integer
         def index_of_active_option
           @presented_options.index { |_, num| num == @active }.to_i
         end
 
-        sig { void }
+        #: -> void
         def ensure_last_item_is_continuation_marker
           @presented_options.push(['...', nil]) if @presented_options.last&.last
         end
 
-        sig { void }
+        #: -> void
         def ensure_first_item_is_continuation_marker
           @presented_options.unshift(['...', nil]) if @presented_options.first&.last
         end
 
-        sig { returns(Integer) }
+        #: -> Integer
         def max_lines
           CLI::UI::Terminal.height - (@displaying_metadata ? 3 : 2) # Keeps a one line question visible
         end
 
-        sig { void }
+        #: -> void
         def render_options
           previously_displayed_lines = num_lines
 
@@ -535,7 +567,7 @@ module CLI
           end
         end
 
-        sig { params(format: String, choice: String).returns(String) }
+        #: (String format, String choice) -> String
         def format_choice(format, choice)
           eol = CLI::UI::ANSI.clear_to_end_of_line
           lines = choice.split("\n")

data/lib/cli/ui/prompt/options_handler.rb

@@ -6,24 +6,22 @@ module CLI
     module Prompt
       # A class that handles the various options of an InteractivePrompt and their callbacks
       class OptionsHandler
-        extend T::Sig
-
-        sig { void }
+        #: -> void
         def initialize
           @options = {}
         end
 
-        sig { returns(T::Array[String]) }
+        #: -> Array[String]
         def options
           @options.keys
         end
 
-        sig { params(option: String, handler: T.proc.params(option: String).returns(String)).void }
+        #: (String option) { (String option) -> String } -> void
         def option(option, &handler)
           @options[option] = handler
         end
 
-        sig { params(options: T.any(T::Array[String], String)).returns(String) }
+        #: ((Array[String] | String) options) -> String
         def call(options)
           case options
           when Array