clack 0.6.2 → 0.7.0

data/lib/clack/core/chrome.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Clack
+  module Core
+    # The chrome around every prompt frame: the guide rail (gray connector, cyan
+    # active bar, yellow error bar), the gutters in front of content lines, the
+    # header/footer templates, and the keyboard hint footer.
+    #
+    # Mixed into {Prompt}. All helpers are private; subclasses call them without
+    # a receiver from +build_frame+. {#bar}, {#active_bar}, and {#bar_end} always
+    # return the colored symbol; only {#gutter} and {#guide_line} know about
+    # +with_guide+, so a frame that builds its own lines from +bar+ still renders
+    # exactly as before when guides are on.
+    module Chrome
+      private
+
+      # Store the per-prompt chrome options. Called from Prompt#initialize.
+      def setup_chrome(with_guide:, show_instructions:, instructions:)
+        unless valid_instructions?(instructions)
+          raise ArgumentError, "instructions must be a String or an Array of Strings"
+        end
+
+        @with_guide = with_guide
+        @show_instructions = show_instructions
+        @instructions = instructions
+      end
+
+      # nil, a String, or an Array of Strings.
+      def valid_instructions?(value)
+        value.nil? || value.is_a?(String) || (value.is_a?(Array) && value.all?(String))
+      end
+
+      # Resolved on every frame so a global change mid-prompt applies to the next redraw.
+      def guide? = Settings.with_guide?(@with_guide)
+
+      def show_instructions? = Settings.show_instructions?(@show_instructions)
+
+      # Content-line prefix: the symbol plus two spaces, or nothing without guides.
+      def gutter(symbol = bar) = guide? ? "#{symbol}  " : ""
+
+      # A rail-only line (connector or closing corner), or nothing without guides.
+      def guide_line(symbol = bar) = guide? ? "#{symbol}\n" : ""
+
+      # The gray rail: the connector above the message and every final-frame line.
+      def bar = Colors.gray(Symbols::S_BAR)
+
+      # The rail next to the step being answered: cyan while it is open, yellow
+      # while it shows a validation error or warning, gray once it is done.
+      def active_bar
+        case @state
+        when :initial, :active then Colors.cyan(Symbols::S_BAR)
+        when :error, :warning then Colors.yellow(Symbols::S_BAR)
+        else bar
+        end
+      end
+
+      # The closing corner, colored like {#active_bar}.
+      def bar_end
+        case @state
+        when :initial, :active then Colors.cyan(Symbols::S_BAR_END)
+        when :error, :warning then Colors.yellow(Symbols::S_BAR_END)
+        else Colors.gray(Symbols::S_BAR_END)
+        end
+      end
+
+      def symbol_for_state
+        case @state
+        when :initial, :active then Colors.cyan(Symbols::S_STEP_ACTIVE)
+        when :submit then Colors.green(Symbols::S_STEP_SUBMIT)
+        when :cancel then Colors.red(Symbols::S_STEP_CANCEL)
+        when :error, :warning then Colors.yellow(Symbols::S_STEP_ERROR)
+        end
+      end
+
+      # The help: line sits inside the active rail, like a message continuation.
+      def help_line
+        return "" unless @help
+
+        "#{gutter(active_bar)}#{Colors.dim(@help)}\n"
+      end
+
+      # One keyboard hint: dim key token, normal description ("↑/↓ to navigate").
+      def key_hint(key, text) = "#{Colors.dim(key)} #{text}"
+
+      # Built-in hints for the footer. Subclasses return an Array<String> of
+      # key_hint fragments; nil means the prompt has no footer. {#frame_footer}
+      # renders the result, so a subclass that defines this hook must not also
+      # print its own hint row: the 0.6.2 built-ins wrote one from a private
+      # method of this name and closed with bar_end, and a copy of that pattern
+      # that calls frame_footer would show the hints twice.
+      def keyboard_hints = nil
+
+      # The hint line under the body rows: the prompt's own hints, or the
+      # caller's instructions: text, joined with the hint separator. Empty when
+      # hidden or when there is nothing to show. Not guarded on state on purpose:
+      # the transient frame rendered right before finalize keeps the line, with
+      # a gray gutter, so the redraw erases the same number of rows.
+      def instruction_footer
+        return "" unless show_instructions?
+
+        hints = Array(@instructions.nil? ? keyboard_hints : @instructions)
+        return "" if hints.empty?
+
+        "#{gutter(active_bar)}#{hints.join(Symbols::S_HINT_SEPARATOR)}\n"
+      end
+
+      # Common frame header: connector + symbol/message + help line.
+      # @return [String] header lines
+      def frame_header
+        "#{guide_line}#{symbol_for_state}  #{@message}\n#{help_line}"
+      end
+
+      # Common frame footer: validation messages, or hint footer + closing corner.
+      # @return [String] footer lines
+      def frame_footer
+        vlns = validation_message_lines
+        return vlns.join if vlns.any?
+
+        "#{instruction_footer}#{guide_line(bar_end)}"
+      end
+
+      # Build validation message lines for error or warning states.
+      # Returns array of lines to append, or empty array if no validation message.
+      def validation_message_lines
+        case @state
+        when :error
+          ["#{gutter(Colors.yellow(Symbols::S_BAR_END))}#{Colors.yellow(@error_message)}\n"]
+        when :warning
+          [
+            "#{gutter(Colors.yellow(Symbols::S_BAR_END))}#{Colors.yellow(@warning_message)}\n",
+            "#{gutter}#{Colors.dim("Press Enter to confirm, or edit your input")}\n"
+          ]
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/clack/core/ci_mode.rb

@@ -11,20 +11,23 @@ module Clack
     # Enable explicitly:
     #   Clack.update_settings(ci_mode: true)
     #
-    # Or auto-detect (non-TTY stdin or CI environment variable):
+    # Or auto-detect (non-TTY input or CI environment variable):
     #   Clack.update_settings(ci_mode: :auto)
     module CiMode
       class << self
         # Check if CI mode is currently active.
         #
+        # @param input [IO, nil] the prompt's input stream, consulted by +:auto+
+        #   (default: $stdin; nil also means $stdin, matching KeyReader's
+        #   console fallback)
         # @return [Boolean]
-        def active?
+        def active?(input = $stdin)
           setting = Settings.config[:ci_mode]
           case setting
           when true
             true
           when :auto
-            !Environment.tty?($stdin) || Environment.ci?
+            !Environment.tty?(input || $stdin) || Environment.ci?
           else
             false
           end

data/lib/clack/core/key_reader.rb

@@ -7,53 +7,113 @@ module Clack
     # Reads single keystrokes from the terminal in raw mode.
     # Handles escape sequences for arrow keys and other special keys.
     #
+    # Escape sequences come in two shapes: CSI (+ESC [+ ... final byte) and
+    # SS3 (+ESC O+ + one byte), the latter used by terminals in application
+    # cursor mode (tmux, and after vim or less leave keypad-transmit mode on).
+    # Both are assembled here and folded into one canonical code per key via
+    # {Settings.normalize_key}, so prompts only ever see +"\e[A"+ for Up.
+    #
     # The Escape detection window is tunable via the +CLACK_ESCAPE_TIMEOUT+
     # env var (see {Environment.escape_timeout}) for high-latency links.
     module KeyReader
+      # Escape-sequence introducers: CSI ("[") and SS3 ("O").
+      SEQUENCE_INTRODUCERS = ["[", "O"].freeze
+
+      # Upper bound on bytes assembled after the introducer, so a stream of
+      # garbage can never keep the reader inside one sequence forever.
+      MAX_SEQUENCE_LENGTH = 32
+
+      # Range of CSI final bytes (+@+ through +~+), per ECMA-48.
+      CSI_FINAL_BYTES = (0x40..0x7E)
+
       class << self
         # Read a single keystroke in raw mode.
         # When input is an IO backed by a console, uses raw mode.
         # When input is a StringIO or test double, reads directly.
         #
+        # End of input (EOF) and a disconnected terminal both return Ctrl+C so
+        # the prompt cancels instead of spinning on an exhausted stream.
+        #
         # @param input [IO, nil] input stream (defaults to IO.console)
-        # @return [String, nil] the key code, or nil on EOF
+        # @return [String] the (normalized) key code
+        # @raise [NotATerminalError] if the input cannot be put into raw mode
         def read(input = nil)
           io = input || IO.console
-          raise IOError, "No console available (not a TTY?)" unless io
-
-          # StringIO / test doubles don't support raw mode
-          return read_from(io) unless io.respond_to?(:raw)
+          raise NotATerminalError, not_a_terminal_message(io) unless io
 
-          io.raw { |raw_io| read_from(raw_io) }
+          key = io.respond_to?(:raw) ? read_raw(io) : read_from(io)
+          Settings.normalize_key(key || Settings::KEY_CTRL_C)
+        rescue NotATerminalError
+          raise
         rescue Errno::EIO, Errno::EBADF, IOError
           # Terminal disconnected or closed - treat as cancel
-          "\u0003" # Ctrl+C
+          Settings::KEY_CTRL_C
         end
 
         private
 
+        # EINVAL is what the Windows console layer (and some BSD device nodes)
+        # report for a handle that is not a console, where POSIX says ENOTTY.
+        def read_raw(io)
+          io.raw { |raw_io| read_from(raw_io) }
+        rescue Errno::ENOTTY, Errno::ENODEV, Errno::ENXIO, Errno::EINVAL
+          raise NotATerminalError, not_a_terminal_message(io)
+        end
+
+        def not_a_terminal_message(io)
+          label = (io.nil? || io.equal?($stdin)) ? "stdin" : "input"
+          "#{label} is not an interactive terminal. Run from a terminal, or enable CI mode " \
+            "with Clack.update_settings(ci_mode: :auto) to auto-submit defaults when input is piped."
+        end
+
         def read_from(io)
           char = io.getc
-          return char if char.nil? # EOF
           return char unless char == "\e"
 
           escape_timeout = Environment.escape_timeout
+
+          # Check for escape sequence - wait briefly for follow-up
+          return char unless readable?(io, escape_timeout)
+
+          introducer = io.getc.to_s
+          return "\e#{introducer}" unless SEQUENCE_INTRODUCERS.include?(introducer)
+
           # Subsequent bytes in a sequence normally arrive almost instantly, so
           # the inter-byte wait stays much shorter, but it scales with the
           # escape timeout so high-latency links still assemble full sequences.
-          sequence_timeout = escape_timeout / 5.0
-
-          # Check for escape sequence - wait briefly for follow-up
-          return char unless io.respond_to?(:wait_readable) && io.wait_readable(escape_timeout)
+          "\e#{introducer}#{read_sequence(io, introducer, escape_timeout / 5.0)}"
+        end
 
-          seq = io.getc.to_s
-          return "\e#{seq}" unless seq == "["
+        # Assemble the bytes after a CSI or SS3 introducer. SS3 carries exactly
+        # one byte; CSI runs until its final byte so a keystroke typed right
+        # after an arrow key is not swallowed into the sequence.
+        def read_sequence(io, introducer, timeout)
+          bytes = []
+          while bytes.length < MAX_SEQUENCE_LENGTH && readable?(io, timeout)
+            byte = io.getc.to_s
+            break if byte.empty?
 
-          # Read CSI sequence until no more characters arrive
-          while io.respond_to?(:wait_readable) && io.wait_readable(sequence_timeout)
-            seq += io.getc.to_s
+            bytes << byte
+            break if introducer == "O" || csi_final?(bytes)
           end
-          "\e[#{seq[1..]}"
+          bytes.join
+        end
+
+        # The Linux virtual console sends F1..F5 as +ESC [ [ A+ .. +ESC [ [ E+,
+        # so a "[" right after the CSI introducer is a second introducer, not
+        # a final byte, even though 0x5B sits inside CSI_FINAL_BYTES.
+        #
+        # Compares the raw byte rather than the codepoint: +ord+ raises on a
+        # byte that is invalid in the input's encoding (line noise, a
+        # mis-encoded terminal), and such a byte simply is not a final byte.
+        def csi_final?(bytes)
+          return false if bytes.length == 1 && bytes.first == "["
+
+          CSI_FINAL_BYTES.cover?(bytes.last.getbyte(0))
+        end
+
+        def readable?(io, timeout)
+          io.respond_to?(:wait_readable) && io.wait_readable(timeout)
         end
       end
     end

data/lib/clack/core/options_helper.rb

@@ -38,17 +38,54 @@ module Clack
     # Including classes must implement:
     # - +navigable_items+ [Array] returns the current list to navigate
     module OptionsHelper
-      # Normalize options to a consistent hash format.
-      # Accepts strings, symbols, or hashes with value/label/hint/disabled keys.
+      # Normalize options to a consistent list of {Option} value objects.
       #
-      # @param options [Array] Raw options in various formats
-      # @return [Array<Hash>] Normalized option hashes
-      # @raise [ArgumentError] if options is empty
+      # Accepts an Array of strings, symbols, or hashes with value/label/hint/disabled
+      # keys, or a Hash of value => label (or value => {label:, hint:, disabled:}).
+      #
+      # @param options [Array, Hash] Raw options in any accepted shape
+      # @return [Array<Option>] Normalized options
+      # @raise [ArgumentError] if options is nil or empty, or a Hash spec sets :value
       def normalize_options(options)
         raise ArgumentError, "options cannot be empty" if options.nil? || options.empty?
 
-        options.map { |opt| OptionsHelper.normalize_option(opt) }
+        OptionsHelper.normalize_list(options)
+      end
+
+      # Normalize a list of raw options without the empty check.
+      # Used by prompts that build their own list (e.g. GroupMultiselect groups).
+      #
+      # @param options [Array, Hash] Raw options in any accepted shape
+      # @return [Array<Option>] Normalized options
+      def self.normalize_list(options)
+        option_entries(options).map { |opt| normalize_option(opt) }
+      end
+
+      # Expand the Hash shorthand (value => label, or value => spec Hash) into
+      # the Array-of-entries shape that {.normalize_option} understands.
+      # Anything that is not a Hash is returned unchanged.
+      #
+      # @param options [Array, Hash] Raw options
+      # @return [Array] Option entries (hashes, strings, symbols, or other bare values)
+      # @raise [ArgumentError] if a spec Hash sets :value
+      def self.option_entries(options)
+        return options unless options.is_a?(Hash)
+
+        options.map { |value, spec| hash_entry(value, spec) }
+      end
+
+      # Build one option entry from a Hash-shorthand pair.
+      # A Hash spec is merged with the value; anything else is the label
+      # (nil means "no label", so normalize_option falls back to value.to_s).
+      def self.hash_entry(value, spec)
+        return {value: value, label: spec&.to_s} unless spec.is_a?(Hash)
+        if spec.key?(:value)
+          raise ArgumentError, "options entry #{value.inspect} must not set :value (the Hash key is the value)"
+        end
+
+        spec.merge(value: value)
       end
+      private_class_method :hash_entry
 
       # Normalize a single option to an Option value object.
       # @param opt [Hash, String, Symbol] Raw option

data/lib/clack/core/prompt.rb

@@ -22,11 +22,13 @@ module Clack
     # @example Creating a custom prompt
     #   class MyPrompt < Clack::Core::Prompt
     #     def build_frame
-    #       "#{bar}\n#{symbol_for_state}  #{@message}\n"
+    #       "#{frame_header}#{gutter(active_bar)}#{something}\n#{frame_footer}"
     #     end
     #   end
     #
     class Prompt
+      include Chrome
+
       # Minimum terminal width for clean rendering.
       # Prompts warn (non-blocking) if the terminal is narrower.
       MIN_TERMINAL_WIDTH = 40
@@ -82,14 +84,25 @@ module Clack
 
       # @param message [String] the prompt message to display
       # @param help [String, nil] optional help text shown below the message
-      # @param validate [Proc, nil] optional validation proc; returns error string, Warning, or nil
+      # @param validate [Proc, Regexp, Symbol, Array, Hash, nil, false] validator, resolved by
+      #   {Validators.resolve}; a proc returns an error string, {Clack::Warning}, or nil.
+      #   nil or false disables validation
       # @param transform [Symbol, Proc, nil] transformer (symbol shortcut or proc); applied after validation
+      # @param with_guide [Boolean, nil] show the guide rail; nil uses Clack.settings[:with_guide]
+      # @param show_instructions [Boolean, nil] show the keyboard hint footer; nil uses
+      #   Clack.settings[:show_instructions]
+      # @param instructions [String, Array<String>, nil] replacement hint text, rendered verbatim on one
+      #   line (newlines are not re-prefixed); nil uses the prompt's built-in hints
       # @param input [IO] input stream (default: $stdin)
       # @param output [IO] output stream (default: $stdout)
-      def initialize(message:, help: nil, validate: nil, transform: nil, input: $stdin, output: $stdout)
+      # @raise [ArgumentError] if instructions is not nil, a String, or an Array of Strings
+      def initialize(message:, help: nil, validate: nil, transform: nil,
+        with_guide: nil, show_instructions: nil, instructions: nil,
+        input: $stdin, output: $stdout)
         @message = message
         @help = help
-        @validate = validate
+        setup_chrome(with_guide:, show_instructions:, instructions:)
+        @validate = Validators.resolve(validate)
         @transform = Transformers.resolve(transform)
         @input = input
         @output = output
@@ -114,8 +127,9 @@ module Clack
       # submits or cancels. Returns the final value or {Clack::CANCEL}.
       #
       # @return [Object, Clack::CANCEL] the submitted value or CANCEL sentinel
+      # @raise [NotATerminalError] if input is an IO that is not a TTY and CI mode is off
       def run
-        return run_ci_mode if CiMode.active?
+        return run_ci_mode if CiMode.active?(@input)
 
         Prompt.register(self)
         warn_narrow_terminal
@@ -138,6 +152,11 @@ module Clack
 
           finalize
           (terminal_state? && @state == :cancel) ? CANCEL : @value
+        rescue NotATerminalError
+          # The first read failed, so the frame drawn above is orphaned: erase
+          # it so the caller's error output is the only thing left on screen.
+          finalize("")
+          raise
         ensure
           Prompt.unregister(self)
           cleanup_terminal if terminal_setup
@@ -325,10 +344,12 @@ module Clack
       end
 
       # Render the final frame after submit/cancel.
-      def finalize
+      # @param frame [String] what replaces the live frame (default: the final
+      #   frame); pass +""+ to erase the live frame and print nothing
+      def finalize(frame = build_final_frame)
         restore_cursor
         @output.print Cursor.clear_down
-        @output.print build_final_frame
+        @output.print frame
       end
 
       # Build the final frame shown after interaction ends.
@@ -338,9 +359,7 @@ module Clack
       #
       # @return [String] the final frame content
       def build_final_frame
-        "#{bar}\n" \
-          "#{symbol_for_state}  #{@message}\n" \
-          "#{bar}  #{styled_final_display}\n"
+        "#{guide_line}#{symbol_for_state}  #{@message}\n#{gutter}#{styled_final_display}\n"
       end
 
       # The text to display in the final frame after submit/cancel.
@@ -358,10 +377,16 @@ module Clack
 
       # Auto-submit with current defaults in CI/non-interactive mode.
       # Subclass submit overrides (e.g., Text applying default_value) run normally.
-      # Validation and transforms are applied. Returns the value regardless of
-      # validation outcome since there's no interactive way to fix input.
+      # Validation and transforms are applied. A warning is confirmed the way a
+      # second Enter would (so the transform still runs); if validation fails, a
+      # warning goes to stderr and CANCEL is returned, since there is no
+      # interactive way to fix the input.
       def run_ci_mode
         submit
+        if @state == :warning
+          confirm_warning
+          submit
+        end
         if @state == :error
           $stderr.print "#{Colors.yellow("!")}  #{Colors.yellow("CI mode: validation failed for")} \"#{@message}\": #{@error_message}\n"
           return CANCEL
@@ -396,76 +421,26 @@ module Clack
         # Output unavailable - terminal may need manual reset
       end
 
+      # Move the cursor back to the first row of the previous frame. On a TTY
+      # the distance includes the rows the terminal used to soft-wrap lines
+      # wider than the pane (a long message, or the keyboard hint footer in a
+      # narrow split); counting newlines alone lands one row low per wrapped
+      # line and leaves the wrapped remainder on screen after every redraw.
       def restore_cursor
         return unless @prev_frame
 
-        lines = @prev_frame.count("\n")
+        lines = if Environment.tty?(@output)
+          Utils.rendered_rows(@prev_frame, Environment.columns(@output))
+        else
+          @prev_frame.count("\n")
+        end
         @output.print Cursor.up(lines) if lines.positive?
         @output.print Cursor.column(1)
       end
 
-      def bar
-        Colors.gray(Symbols::S_BAR)
-      end
-
-      def active_bar
-        %i[error warning].include?(@state) ? Colors.yellow(Symbols::S_BAR) : bar
-      end
-
-      def bar_end
-        %i[error warning].include?(@state) ? Colors.yellow(Symbols::S_BAR_END) : Colors.gray(Symbols::S_BAR_END)
-      end
-
-      def help_line
-        return "" unless @help
-
-        "#{bar}  #{Colors.dim(@help)}\n"
-      end
-
       def cursor_block
         Colors.inverse(" ")
       end
-
-      def symbol_for_state
-        case @state
-        when :initial, :active then Colors.cyan(Symbols::S_STEP_ACTIVE)
-        when :submit then Colors.green(Symbols::S_STEP_SUBMIT)
-        when :cancel then Colors.red(Symbols::S_STEP_CANCEL)
-        when :error, :warning then Colors.yellow(Symbols::S_STEP_ERROR)
-        end
-      end
-
-      # Common frame header: bar + symbol/message + help line.
-      # @return [String] header lines
-      def frame_header
-        "#{bar}\n#{symbol_for_state}  #{@message}\n#{help_line}"
-      end
-
-      # Common frame footer: validation messages or bar_end.
-      # Replaces the repeated pattern of splicing validation lines.
-      # @return [String] footer lines
-      def frame_footer
-        vlns = validation_message_lines
-        return vlns.join if vlns.any?
-
-        "#{bar_end}\n"
-      end
-
-      # Build validation message lines for error or warning states.
-      # Returns array of lines to append, or empty array if no validation message.
-      def validation_message_lines
-        case @state
-        when :error
-          ["#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n"]
-        when :warning
-          [
-            "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@warning_message)}\n",
-            "#{bar}  #{Colors.dim("Press Enter to confirm, or edit your input")}\n"
-          ]
-        else
-          []
-        end
-      end
     end
   end
 end