clack 0.6.1 → 0.7.0

data/lib/clack/core/settings.rb

@@ -2,7 +2,8 @@
 
 module Clack
   module Core
-    # Global configuration for key bindings, guide bar display, and input classification.
+    # Global configuration for key bindings, guide bar display, keyboard hint
+    # display, input classification, and the user-facing cancel/error strings.
     module Settings
       # Navigation and control actions
       ACTIONS = %i[up down left right space enter cancel].freeze
@@ -16,6 +17,8 @@ module Clack
       KEY_ENTER = "\r"            # ASCII 13: Carriage return
       KEY_NEWLINE = "\n"          # ASCII 10: Line feed
       KEY_SPACE = " "             # ASCII 32: Space
+      KEY_HOME = "\e[H"           # Canonical Home (CSI H)
+      KEY_END = "\e[F"            # Canonical End (CSI F)
 
       # First printable ASCII character (space)
       PRINTABLE_CHAR_MIN = 32
@@ -37,11 +40,35 @@ module Clack
         KEY_CTRL_C => :cancel
       }.freeze
 
+      # Terminals encode the same key in several ways: SS3 (+ESC O x+) in
+      # application cursor mode, and Home/End as +ESC [ H+, +ESC [ 1 ~+ or
+      # +ESC [ 7 ~+ depending on the terminal. {KeyReader} folds every variant
+      # into the canonical code on the right, so prompts and aliases only ever
+      # deal with one code per key.
+      KEY_NORMALIZE = {
+        "\eOA" => "\e[A",
+        "\eOB" => "\e[B",
+        "\eOC" => "\e[C",
+        "\eOD" => "\e[D",
+        "\eOH" => KEY_HOME,
+        "\e[1~" => KEY_HOME,
+        "\e[7~" => KEY_HOME,
+        "\eOF" => KEY_END,
+        "\e[4~" => KEY_END,
+        "\e[8~" => KEY_END
+      }.freeze
+
+      # Default user-facing strings, overridable via update(messages:) for localization.
+      DEFAULT_MESSAGES = {cancel: "Cancelled", error: "Something went wrong"}.freeze
+      MESSAGE_KEYS = DEFAULT_MESSAGES.keys.freeze
+
       # Global configuration (mutable)
       @config = {
         aliases: ALIASES.dup,
         with_guide: true,
-        ci_mode: false
+        show_instructions: true,
+        ci_mode: false,
+        messages: DEFAULT_MESSAGES
       }
       @config_mutex = Mutex.new
 
@@ -55,34 +82,67 @@ module Clack
         # Update global settings
         # @param aliases [Hash, nil] Custom key to action mappings (merged with defaults)
         # @param with_guide [Boolean, nil] Whether to show guide bars
+        # @param show_instructions [Boolean, nil] Whether prompts show their keyboard hint footer
         # @param ci_mode [Boolean, Symbol, nil] CI mode: true (always), :auto (detect), false (never)
+        # @param messages [Hash{Symbol=>String}, nil] Cancel/error strings, merged with the
+        #   current values: +{cancel: "Cancelled", error: "Something went wrong"}+
         # @return [Hash] Updated configuration
-        def update(aliases: nil, with_guide: nil, ci_mode: nil)
+        # @raise [ArgumentError] if messages is not a Hash, has an unknown key, or a non-String value
+        def update(aliases: nil, with_guide: nil, show_instructions: nil, ci_mode: nil, messages: nil)
+          validate_messages(messages) if messages
           @config_mutex.synchronize do
             @config[:aliases] = ALIASES.merge(aliases) if aliases
             @config[:with_guide] = with_guide unless with_guide.nil?
+            @config[:show_instructions] = show_instructions unless show_instructions.nil?
             @config[:ci_mode] = ci_mode unless ci_mode.nil?
+            # Values are frozen too (-value dedups without to_s), so a caller's
+            # mutable String cannot change global state after the fact.
+            @config[:messages] = @config[:messages].merge(messages.transform_values { |value| -value }).freeze if messages
             @config.dup
           end
         end
 
+        # Current cancel/error strings.
+        # @return [Hash{Symbol=>String}] frozen
+        def messages = @config_mutex.synchronize { @config[:messages] }
+
+        # Look up one user-facing string.
+        # @param key [Symbol] :cancel or :error
+        # @return [String]
+        # @raise [KeyError] for an unknown key
+        def message(key) = messages.fetch(key)
+
         # Reset settings to defaults
         def reset!
           @config_mutex.synchronize do
             @config = {
               aliases: ALIASES.dup,
               with_guide: true,
-              ci_mode: false
+              show_instructions: true,
+              ci_mode: false,
+              messages: DEFAULT_MESSAGES
             }
           end
         end
 
-        # Check if guide bars should be shown
+        # Resolve whether guide bars are shown.
+        # @param override [Boolean, nil] per-call value; nil means "use the global setting"
         # @return [Boolean]
-        def with_guide?
+        def with_guide?(override = nil)
+          return override unless override.nil?
+
           @config_mutex.synchronize { @config[:with_guide] }
         end
 
+        # Resolve whether keyboard hint footers are shown.
+        # @param override [Boolean, nil] per-call value; nil means "use the global setting"
+        # @return [Boolean]
+        def show_instructions?(override = nil)
+          return override unless override.nil?
+
+          @config_mutex.synchronize { @config[:show_instructions] }
+        end
+
         # Look up the action mapped to a key code.
         # @param key [String] key code from {KeyReader}
         # @return [Symbol, nil] the action (:up, :down, :enter, etc.) or nil
@@ -91,6 +151,13 @@ module Clack
           aliases[key] if ACTIONS.include?(aliases[key])
         end
 
+        # Fold terminal-specific escape sequence variants into one canonical code.
+        # @param key [String] key code as assembled by {KeyReader}
+        # @return [String] the canonical code (unchanged when no variant matches)
+        def normalize_key(key)
+          KEY_NORMALIZE.fetch(key, key)
+        end
+
         # Check if a key is a printable character (handles combining marks and multi-codepoint grapheme clusters)
         def printable?(key)
           key && key.grapheme_clusters.length == 1 && key.ord >= PRINTABLE_CHAR_MIN
@@ -100,6 +167,20 @@ module Clack
         def backspace?(key)
           [KEY_BACKSPACE, KEY_DELETE].include?(key)
         end
+
+        private
+
+        # Raises before any state changes so a bad call leaves the config untouched.
+        def validate_messages(messages)
+          raise ArgumentError, "messages must be a Hash" unless messages.is_a?(Hash)
+
+          messages.each do |key, value|
+            unless MESSAGE_KEYS.include?(key)
+              raise ArgumentError, "unknown messages key: #{key.inspect} (expected #{MESSAGE_KEYS.map(&:inspect).join(", ")})"
+            end
+            raise ArgumentError, "messages[#{key.inspect}] must be a String" unless value.is_a?(String)
+          end
+        end
       end
     end
   end

data/lib/clack/environment.rb

@@ -57,12 +57,36 @@ module Clack
         ENV["TERM"] == "dumb"
       end
 
-      # Check if ANSI colors are supported
-      # @param output [IO] Output stream to check
+      # Check if ANSI colors are supported on +output+.
+      #
+      # Resolution order, first match wins:
+      # 1. +FORCE_COLOR=0+ or +FORCE_COLOR=false+ (any case): +false+
+      # 2. +NO_COLOR+ set to a non-empty value: +false+ (see https://no-color.org)
+      # 3. +FORCE_COLOR+ set to any other non-empty value: +true+, even when
+      #    +output+ is not a TTY or +TERM=dumb+
+      # 4. +output+ is not a TTY: +false+
+      # 5. +TERM=dumb+: +false+
+      # 6. Otherwise +true+
+      #
+      # An empty +NO_COLOR+ or +FORCE_COLOR+ is treated as unset. The result is
+      # not cached; every call re-reads the environment.
+      #
+      # {Colors.enabled?}, {Core::Cursor.enabled?} and {Symbols.unicode?} all
+      # delegate here, so these variables also control cursor escape sequences
+      # and the Unicode/ASCII symbol set (unless +CLACK_UNICODE+ overrides the
+      # latter).
+      #
+      # @param output [IO] Output stream to check (default: $stdout)
       # @return [Boolean]
       def colors_supported?(output = $stdout)
-        return false if ENV["NO_COLOR"]
-        return true if ENV["FORCE_COLOR"]
+        force = ENV["FORCE_COLOR"].to_s
+        # The binary copy matters: ENV values carry the locale encoding, and
+        # String#casecmp? raises ArgumentError on invalid bytes in that
+        # encoding. Symbols calls this at require time, so a stray
+        # FORCE_COLOR=$'\xff' would otherwise make `require "clack"` raise.
+        return false if force == "0" || force.b.casecmp?("false")
+        return false unless ENV["NO_COLOR"].to_s.empty?
+        return true unless force.empty?
         return false unless tty?(output)
         return false if dumb_terminal?
 

data/lib/clack/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Clack
+  # Raised when a prompt needs keystrokes but its input stream is not an
+  # interactive terminal (for example, stdin is a pipe, a file, or /dev/null).
+  #
+  # Inherits from IOError so existing +rescue IOError+ guards keep working.
+  # The message names the fix: run from a terminal, or enable CI mode so
+  # prompts auto-submit their defaults.
+  #
+  # @example
+  #   begin
+  #     Clack.text(message: "Name?")
+  #   rescue Clack::NotATerminalError => e
+  #     warn e.message
+  #     exit 1
+  #   end
+  class NotATerminalError < IOError; end
+end

data/lib/clack/log.rb

@@ -6,6 +6,11 @@ module Clack
   # Each method prints a message prefixed with a colored symbol. Multi-line
   # messages are automatically aligned with a continuation bar on subsequent lines.
   #
+  # With guides off (+with_guide: false+ or +Clack.update_settings(with_guide: false)+)
+  # the level symbol stays on the first line and only the continuation rail goes
+  # away, so +log.error+ still looks different from +log.info+ (upstream drops the
+  # symbol as well).
+  #
   # Accessed via +Clack.log+:
   #
   # @example
@@ -23,22 +28,26 @@ module Clack
       # log levels).
       #
       # @param msg [String] the message to display
-      # @param symbol [String, nil] custom prefix symbol (default: gray bar)
+      # @param symbol [String, nil] custom prefix symbol (default: gray bar, or nothing with guides off)
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
       # @return [void]
       #
       # @example Custom symbol
-      #   Clack.log.message("Deploying...", symbol: "\u2708")
-      def message(msg = "", symbol: nil, output: $stdout)
-        symbol ||= Colors.gray(Symbols::S_BAR)
+      #   Clack.log.message("Deploying...", symbol: "✈")
+      def message(msg = "", symbol: nil, with_guide: nil, output: $stdout)
+        guide = Core::Settings.with_guide?(with_guide)
+        rail = Colors.gray(Symbols::S_BAR)
+        first = symbol || (guide ? rail : nil)
+        first_prefix = first ? "#{first}  " : ""
+        next_prefix = guide ? "#{rail}  " : ""
         lines = msg.to_s.lines
 
         if lines.empty?
-          output.puts symbol
+          output.puts first.to_s
         else
           lines.each_with_index do |line, idx|
-            prefix = idx.zero? ? symbol : Colors.gray(Symbols::S_BAR)
-            output.puts "#{prefix}  #{line.chomp}"
+            output.puts "#{idx.zero? ? first_prefix : next_prefix}#{line.chomp}"
           end
         end
       end
@@ -46,47 +55,52 @@ module Clack
       # Print an informational message (blue symbol).
       #
       # @param msg [String] the message to display
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
       # @return [void]
-      def info(msg, output: $stdout)
-        message(msg, symbol: Colors.blue(Symbols::S_INFO), output:)
+      def info(msg, with_guide: nil, output: $stdout)
+        message(msg, symbol: Colors.blue(Symbols::S_INFO), with_guide:, output:)
       end
 
       # Print a success message (green symbol).
       #
       # @param msg [String] the message to display
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
       # @return [void]
-      def success(msg, output: $stdout)
-        message(msg, symbol: Colors.green(Symbols::S_SUCCESS), output:)
+      def success(msg, with_guide: nil, output: $stdout)
+        message(msg, symbol: Colors.green(Symbols::S_SUCCESS), with_guide:, output:)
       end
 
       # Print a step completion message (green submit symbol).
       #
       # @param msg [String] the message to display
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
       # @return [void]
-      def step(msg, output: $stdout)
-        message(msg, symbol: Colors.green(Symbols::S_STEP_SUBMIT), output:)
+      def step(msg, with_guide: nil, output: $stdout)
+        message(msg, symbol: Colors.green(Symbols::S_STEP_SUBMIT), with_guide:, output:)
       end
 
       # Print a warning message (yellow symbol).
       #
       # @param msg [String] the message to display
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
       # @return [void]
-      def warn(msg, output: $stdout)
-        message(msg, symbol: Colors.yellow(Symbols::S_WARN), output:)
+      def warn(msg, with_guide: nil, output: $stdout)
+        message(msg, symbol: Colors.yellow(Symbols::S_WARN), with_guide:, output:)
       end
       alias_method :warning, :warn
 
       # Print an error message (red symbol).
       #
       # @param msg [String] the message to display
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
       # @return [void]
-      def error(msg, output: $stdout)
-        message(msg, symbol: Colors.red(Symbols::S_ERROR), output:)
+      def error(msg, with_guide: nil, output: $stdout)
+        message(msg, symbol: Colors.red(Symbols::S_ERROR), with_guide:, output:)
       end
     end
   end

data/lib/clack/note.rb

@@ -6,27 +6,33 @@ module Clack
     class << self
       # Render a note box to the output stream.
       #
+      # With guides on, a rail line precedes the box and the bottom-left corner is
+      # a T-connector so the rail continues below. With guides off there is no
+      # leading rail and the corner is rounded (upstream behavior).
+      #
       # @param message [String] the note content
       # @param title [String, nil] optional title displayed above the box
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
       # @return [void]
-      def render(message = "", title: nil, output: $stdout)
+      def render(message = "", title: nil, with_guide: nil, output: $stdout)
+        guide = Core::Settings.with_guide?(with_guide)
         lines = message.to_s.lines.map(&:chomp)
         # Add empty lines at start and end like original
         lines = ["", *lines, ""]
         title_len = Clack::Utils.visible_length(title)
         width = calculate_width(lines, title_len)
 
-        output.puts Colors.gray(Symbols::S_BAR)
+        output.puts Colors.gray(Symbols::S_BAR) if guide
         output.puts build_top_border(title, title_len, width)
 
         lines.each do |line|
           pad = width - Clack::Utils.visible_length(line)
           padded = pad.positive? ? line + (" " * pad) : line
-          output.puts "#{Colors.gray(Symbols::S_BAR)}  #{Colors.dim(padded)}#{Colors.gray(Symbols::S_BAR)}"
+          output.puts "#{Colors.gray(Symbols::S_BAR)}  #{padded}#{Colors.gray(Symbols::S_BAR)}"
         end
 
-        output.puts build_bottom_border(width)
+        output.puts build_bottom_border(width, guide)
       end
 
       private
@@ -48,9 +54,10 @@ module Clack
         end
       end
 
-      def build_bottom_border(width)
+      def build_bottom_border(width, guide)
         border = Symbols::S_BAR_H * (width + 2)
-        "#{Colors.gray(Symbols::S_CONNECT_LEFT)}#{Colors.gray(border)}#{Colors.gray(Symbols::S_CORNER_BOTTOM_RIGHT)}"
+        corner = guide ? Symbols::S_CONNECT_LEFT : Symbols::S_CORNER_BOTTOM_LEFT
+        "#{Colors.gray(corner)}#{Colors.gray(border)}#{Colors.gray(Symbols::S_CORNER_BOTTOM_RIGHT)}"
       end
     end
   end

data/lib/clack/prompts/autocomplete.rb

@@ -107,23 +107,15 @@ module Clack
       end
 
       def build_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-        lines << help_line
-        lines << "#{active_bar}  #{input_display}\n"
+        lines = [frame_header]
+        lines << "#{gutter(active_bar)}#{input_display}\n"
 
         visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx
-          lines << "#{bar}  #{option_display(opt, actual_idx == @option_index)}\n"
-        end
-
-        if @state in :error | :warning
-          lines.concat(validation_message_lines)
-        else
-          lines << "#{bar_end}\n"
+          lines << "#{gutter(active_bar)}#{option_display(opt, actual_idx == @option_index)}\n"
         end
 
+        lines << frame_footer
         lines.join
       end
 
@@ -141,6 +133,15 @@ module Clack
 
       def navigable_items = @filtered
 
+      # Upstream autocomplete footer
+      def keyboard_hints
+        [
+          key_hint(Symbols::S_ARROWS_UP_DOWN, "to select"),
+          key_hint("Enter:", "confirm"),
+          key_hint("Type:", "to search")
+        ]
+      end
+
       def option_display(opt, active)
         hint = (opt.hint && active) ? Colors.dim(" (#{opt.hint})") : ""
         if active

data/lib/clack/prompts/autocomplete_multiselect.rb

@@ -101,27 +101,16 @@ module Clack
       end
 
       def build_frame
-        lines = []
-        lines << "#{bar}\n"
-        lines << "#{symbol_for_state}  #{@message}\n"
-        lines << help_line
-        lines << "#{active_bar}  #{Colors.dim("Search:")} #{input_display}#{match_count}\n"
+        lines = [frame_header]
+        lines << "#{gutter(active_bar)}#{Colors.dim("Search:")} #{input_display}#{match_count}\n"
 
         visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx
-          lines << "#{active_bar}  #{option_display(opt, actual_idx == @option_index)}\n"
-        end
-
-        lines << "#{active_bar}  #{Colors.yellow("No matches found")}\n" if @filtered.empty? && !@search_text.empty?
-
-        lines << "#{active_bar}  #{keyboard_hints}\n"
-
-        if @state in :error | :warning
-          lines.concat(validation_message_lines)
-        else
-          lines << "#{bar_end}\n"
+          lines << "#{gutter(active_bar)}#{option_display(opt, actual_idx == @option_index)}\n"
         end
 
+        lines << "#{gutter(active_bar)}#{Colors.yellow("No matches found")}\n" if @filtered.empty? && !@search_text.empty?
+        lines << frame_footer
         lines.join
       end
 
@@ -150,12 +139,14 @@ module Clack
         Colors.dim(" (#{@filtered.size} match#{"es" unless @filtered.size == 1})")
       end
 
+      # Upstream autocomplete multiselect footer, minus Tab (Ruby has no Tab-select).
       def keyboard_hints
-        Colors.dim([
-          "up/down: navigate",
-          "space: select",
-          "enter: confirm"
-        ].join(" | "))
+        [
+          key_hint(Symbols::S_ARROWS_UP_DOWN, "to navigate"),
+          key_hint("Space:", "select"),
+          key_hint("Enter:", "confirm"),
+          key_hint("Type:", "to search")
+        ]
       end
 
       def update_filtered

data/lib/clack/prompts/confirm.rb

@@ -18,17 +18,31 @@ module Clack
     #     initial_value: false
     #   )
     #
+    # @example Stacked layout for long labels
+    #   Clack.confirm(
+    #     message: "Overwrite ~/.zshrc?",
+    #     active: "Yes, back it up and replace it",
+    #     inactive: "No, keep my existing file",
+    #     vertical: true
+    #   )
+    #
     class Confirm < Core::Prompt
       # @param message [String] the prompt message
       # @param active [String] label for the "yes" option (default: "Yes")
       # @param inactive [String] label for the "no" option (default: "No")
-      # @param initial_value [Boolean] initial selection (default: true)
+      # @param initial_value [Object] initial selection (default: true); coerced to a
+      #   Boolean, so nil and false select "no" and anything else selects "yes"
+      # @param vertical [Boolean] render the two options on separate lines (default: false)
       # @param opts [Hash] additional options passed to {Core::Prompt}
-      def initialize(message:, active: "Yes", inactive: "No", initial_value: true, **opts)
+      def initialize(message:, active: "Yes", inactive: "No", initial_value: true, vertical: false, **opts)
         super(message:, **opts)
         @active_label = active
         @inactive_label = inactive
-        @value = initial_value
+        @vertical = vertical
+        # Coerce like upstream (`!!opts.initialValue`) so the prompt always
+        # returns a real Boolean, even when the caller passes nil from ENV or
+        # an options hash.
+        @value = initial_value ? true : false
       end
 
       protected
@@ -46,23 +60,27 @@ module Clack
       end
 
       def build_frame
-        "#{frame_header}#{bar}  #{options_display}\n#{frame_footer}"
+        "#{frame_header}#{row_prefix}#{options_display}\n#{frame_footer}"
       end
 
       def final_display = @value ? @active_label : @inactive_label
 
       private
 
+      # Gutter prefix for an option row. Both the first row and the vertical
+      # joiner use it, so the rail colour follows the prompt state in one place.
+      # Empty when guides are off, so the vertical joiner collapses to a bare newline.
+      def row_prefix = gutter(active_bar)
+
       def options_display
-        if @value
-          active = "#{Colors.green(Symbols::S_RADIO_ACTIVE)} #{@active_label}"
-          inactive = "#{Colors.dim(Symbols::S_RADIO_INACTIVE)} #{Colors.dim(@inactive_label)}"
-        else
-          active = "#{Colors.dim(Symbols::S_RADIO_INACTIVE)} #{Colors.dim(@active_label)}"
-          inactive = "#{Colors.green(Symbols::S_RADIO_ACTIVE)} #{@inactive_label}"
-        end
+        joiner = @vertical ? "\n#{row_prefix}" : " #{Colors.dim("/")} "
+        "#{radio(@active_label, @value)}#{joiner}#{radio(@inactive_label, !@value)}"
+      end
+
+      def radio(label, selected)
+        return "#{Colors.green(Symbols::S_RADIO_ACTIVE)} #{label}" if selected
 
-        "#{active} #{Colors.dim("/")} #{inactive}"
+        "#{Colors.dim(Symbols::S_RADIO_INACTIVE)} #{Colors.dim(label)}"
       end
     end
   end

data/lib/clack/prompts/date.rb

@@ -83,7 +83,7 @@ module Clack
       end
 
       def build_frame
-        "#{frame_header}#{active_bar}  #{date_display}\n#{frame_footer}"
+        "#{frame_header}#{gutter(active_bar)}#{date_display}\n#{frame_footer}"
       end
 
       def final_display = formatted_date