clack 0.6.2 → 0.7.0

data/lib/clack/prompts/spinner.rb

@@ -11,6 +11,13 @@ module Clack
     # - `:dots` - animating dots after message (default)
     # - `:timer` - elapsed time display [Xs] or [Xm Ys]
     #
+    # Exit safety: a spinner still running when the process exits, whether by
+    # `exit` (including `exit 0`), Ctrl+C, or an uncaught exception, prints its
+    # cancel or error line first and stops the animation thread, instead of
+    # leaving a half-drawn frame. `Clack.spin` does the same when its block
+    # exits early. Exit and signals count as cancelled; any other exception
+    # counts as an error.
+    #
     # @example Basic usage
     #   s = Clack.spinner
     #   s.start("Installing...")
@@ -31,19 +38,132 @@ module Clack
     #   do_step_2
     #   s.stop("All done!")
     #
+    # @example Cancel and error messages
+    #   s = Clack.spinner(cancel_message: "Deploy aborted", error_message: "Deploy failed",
+    #                     on_cancel: -> { release_lock })
+    #   s.start("Deploying")
+    #   s.cancel   # => "■  Deploy aborted", then on_cancel runs
+    #
     class Spinner
+      # Running spinners, so the process-exit hook can finish them. A module
+      # rather than class-level state so reek counts its ivars separately.
+      #
+      # Lock order: a spinner calls {register}/{unregister} while holding its own
+      # mutex (membership changes with the state flip), so the registry mutex
+      # nests inside a spinner mutex and never the reverse. {abandon_active}
+      # snapshots the list and releases the registry mutex before calling any
+      # spinner.
+      # @api private
+      module Registry
+        @active = []
+        @mutex = Mutex.new
+        @exit_hook_installed = false
+        @owner_pid = nil
+
+        class << self
+          # @api private
+          # @return [Array<Spinner>] snapshot of running spinners
+          def active = @mutex.synchronize { @active.dup }
+
+          # @api private
+          # Track a spinner that just started; installs the exit hook on first use.
+          # @param spinner [Spinner]
+          # @return [nil]
+          def register(spinner)
+            @mutex.synchronize do
+              install_exit_hook
+              @active << spinner unless @active.include?(spinner)
+            end
+            nil
+          end
+
+          # @api private
+          # Forget a spinner that finished or was cleared.
+          # @param spinner [Spinner]
+          # @return [nil]
+          def unregister(spinner)
+            @mutex.synchronize { @active.delete(spinner) }
+            nil
+          end
+
+          # @api private
+          # Finish every running spinner as abandoned (see Spinner#abandon).
+          # A spinner whose output stream fails (closed, EPIPE at exit) is
+          # reported with Kernel#warn and the rest are still finished.
+          # @param exception [Exception, nil] the exception ending the process, typically $!
+          # @return [nil]
+          def abandon_active(exception = nil)
+            active.each do |spinner|
+              spinner.abandon(exception)
+            rescue => error
+              warn_failure(error)
+            end
+            nil
+          end
+
+          private
+
+          # Registered on the first start (not at require time) so it runs before
+          # at_exit blocks the application registered earlier: the final line lands
+          # before their output instead of after it.
+          #
+          # A forked child inherits this hook and the registry contents, both of
+          # which belong to the parent. The hook checks the pid it was installed
+          # under so the child never finishes the parent's spinners (that would
+          # print the cancel line into the shared stdout and run on_cancel in the
+          # wrong process). When the child starts a spinner of its own, the
+          # inherited entries are dropped and a hook for the child is installed.
+          def install_exit_hook
+            pid = Process.pid
+            return if @exit_hook_installed && @owner_pid == pid
+
+            @active.clear if @exit_hook_installed
+            @exit_hook_installed = true
+            @owner_pid = pid
+            at_exit do
+              abandon_active($!) if Process.pid == pid
+            rescue => exception
+              warn_failure(exception)
+            end
+          end
+
+          def warn_failure(exception)
+            warn "clack: failed to finish spinner: #{exception.class}: #{exception.message}"
+          end
+        end
+      end
+
       # @param indicator [:dots, :timer] animation style (default: :dots)
       # @param frames [Array<String>, nil] custom spinner frames
       # @param delay [Float, nil] delay between frames in seconds
       # @param style_frame [Proc, nil] proc to style each frame character
+      # @param cancel_message [String, nil] text for {#cancel} with no argument and for
+      #   Ctrl+C / exit while running (default: the global messages[:cancel], "Cancelled")
+      # @param error_message [String, nil] text for {#error} with no argument and for an
+      #   uncaught exception while running (default: the global messages[:error],
+      #   "Something went wrong")
+      # @param on_cancel [#call, nil] called with no arguments after the spinner is
+      #   cancelled; a StandardError raised by it is reported with Kernel#warn and swallowed
+      # @param with_guide [Boolean, nil] print the guide rail line above the spinner
+      #   (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
+      # @raise [ArgumentError] if cancel_message/error_message are not Strings or
+      #   on_cancel does not respond to #call
       def initialize(
         indicator: :dots,
         frames: nil,
         delay: nil,
         style_frame: nil,
+        cancel_message: nil,
+        error_message: nil,
+        on_cancel: nil,
+        with_guide: nil,
         output: $stdout
       )
+        validate_options(cancel_message, error_message, on_cancel)
+        @messages = {cancel: cancel_message, error: error_message}.freeze
+        @on_cancel = on_cancel
+        @with_guide = with_guide
         @output = output
         @indicator = indicator
         @frames = frames || Symbols::SPINNER_FRAMES
@@ -54,7 +174,9 @@ module Clack
         @thread = nil
         @frame_idx = 0
         @prev_frame = nil
-        @start_time = nil
+        # The pid that started the spinner and the monotonic start time; nil
+        # while idle. One hash so the class stays within reek's ivar limit.
+        @run = nil
         @mutex = Mutex.new
       end
 
@@ -70,11 +192,14 @@ module Clack
           @state = :running
           @prev_frame = nil
           @frame_idx = 0
-          @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @run = {pid: Process.pid, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC)}.freeze
+          # Under the mutex so a concurrent finish cannot slip between the
+          # state flip and registration and leave a finished spinner tracked.
+          Registry.register(self)
         end
 
         @output.print Core::Cursor.hide
-        @output.print "#{Colors.gray(Symbols::S_BAR)}\n"
+        @output.print "#{Colors.gray(Symbols::S_BAR)}\n" if Core::Settings.with_guide?(@with_guide)
 
         @thread = Thread.new { spin_loop }
         self
@@ -89,14 +214,16 @@ module Clack
 
       # Stop with error state.
       #
-      # @param message [String, nil] error message (uses current if nil)
+      # @param message [String, nil] error message (default: +error_message:+,
+      #   then the global messages[:error])
       def error(message = nil)
         finish(:error, message)
       end
 
-      # Stop with cancelled state.
+      # Stop with cancelled state and run +on_cancel+.
       #
-      # @param message [String, nil] cancellation message
+      # @param message [String, nil] cancellation message (default: +cancel_message:+,
+      #   then the global messages[:cancel])
       def cancel(message = nil)
         finish(:cancelled, message)
       end
@@ -113,6 +240,7 @@ module Clack
       def clear
         @mutex.synchronize do
           @state = :idle
+          Registry.unregister(self)
         end
         @thread&.join
         restore_cursor
@@ -120,14 +248,64 @@ module Clack
         @output.print Core::Cursor.show
       end
 
+      # @return [Boolean] true once {#cancel} has finished the spinner
       def cancelled? = @mutex.synchronize { @state == :cancelled }
 
+      # @return [Boolean] true between start and the first of stop/error/cancel/clear
+      def running? = @mutex.synchronize { @state == :running }
+
+      # @api private
+      # Finish a spinner whose caller is not coming back. Exit and signals end
+      # cancelled, any other exception ends in the error state, nil (break, throw,
+      # or a forgotten stop at process exit) ends cancelled. No-op unless running.
+      # @param exception [Exception, nil]
+      # @return [void]
+      def abandon(exception = nil)
+        return unless running?
+
+        crash?(exception) ? error : cancel
+      end
+
       private
 
+      def validate_options(cancel_message, error_message, on_cancel)
+        raise ArgumentError, "cancel_message must be a String" unless cancel_message.nil? || cancel_message.is_a?(String)
+        raise ArgumentError, "error_message must be a String" unless error_message.nil? || error_message.is_a?(String)
+        raise ArgumentError, "on_cancel must respond to #call" unless on_cancel.nil? || on_cancel.respond_to?(:call)
+      end
+
+      def crash?(exception) = !(exception.nil? || exception.is_a?(SystemExit) || exception.is_a?(SignalException))
+
+      # Resolved at finish time, not construction, so update_settings after
+      # Clack.spinner still applies.
+      def default_final_message(end_state)
+        case end_state
+        when :cancelled then @messages[:cancel] || Core::Settings.message(:cancel)
+        when :error then @messages[:error] || Core::Settings.message(:error)
+        else @message
+        end
+      end
+
+      def final_symbol(end_state)
+        case end_state
+        when :success then Colors.green(Symbols::S_STEP_SUBMIT)
+        when :error then Colors.red(Symbols::S_STEP_ERROR)
+        when :cancelled then Colors.red(Symbols::S_STEP_CANCEL)
+        end
+      end
+
+      # The hook runs during exit, signal unwinding, and at_exit, where a raise
+      # would replace the in-flight SystemExit or change the exit status.
+      def run_on_cancel
+        @on_cancel&.call
+      rescue => exception
+        warn "clack: on_cancel raised: #{exception.class}: #{exception.message}"
+      end
+
       def remove_trailing_dots(msg) = msg.to_s.sub(/\.+$/, "")
 
       def format_timer
-        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @run[:started_at]
         min = (elapsed / 60).to_i
         secs = (elapsed % 60).to_i
         min.positive? ? "[#{min}m #{secs}s]" : "[#{secs}s]"
@@ -174,24 +352,27 @@ module Clack
           return unless @state == :running
 
           @state = end_state
+          # Unregistered with the state flip, before any print can raise, so
+          # the registry never retains a finished spinner.
+          Registry.unregister(self)
+          # A child of a block-less fork inherits this running spinner and, on
+          # exit, unwinds through the parent's Clack.spin rescue with it. The
+          # parent owns the final line and on_cancel, so the child only marks
+          # its copy finished instead of printing into the shared stdout.
+          return unless @run[:pid] == Process.pid
+
           thread_to_join = @thread
-          suffix = (@indicator == :timer && @start_time) ? " #{format_timer}" : ""
-          [message || @message, suffix]
+          suffix = (@indicator == :timer) ? " #{format_timer}" : ""
+          [message || default_final_message(end_state), suffix]
         end
 
         thread_to_join&.join(5)
         thread_to_join&.kill if thread_to_join&.alive?
 
         @output.print "\r#{Core::Cursor.clear_to_end}"
-
-        symbol = case end_state
-        when :success then Colors.green(Symbols::S_STEP_SUBMIT)
-        when :error then Colors.red(Symbols::S_STEP_ERROR)
-        when :cancelled then Colors.red(Symbols::S_STEP_CANCEL)
-        end
-
-        @output.print "#{symbol}  #{msg}#{timer_suffix}\n"
+        @output.print "#{final_symbol(end_state)}  #{msg}#{timer_suffix}\n"
         @output.print Core::Cursor.show
+        run_on_cancel if end_state == :cancelled
       end
 
       def restore_cursor

data/lib/clack/prompts/tasks.rb

@@ -9,9 +9,10 @@ module Clack
     #
     # Each task is a hash with:
     # - +:title+ - display title
-    # - +:task+ - Proc to execute (exceptions are caught).
-    #     Optionally accepts a message-update callable to change
-    #     the spinner message mid-execution.
+    # - +:task+ - Proc to execute. A StandardError is caught and recorded
+    #     as a result; exit, signals, and other exceptions finish the
+    #     spinner and propagate. Optionally accepts a message-update
+    #     callable to change the spinner message mid-execution.
     # - +:enabled+ - optional boolean (default true). When false,
     #     the task is skipped entirely.
     #
@@ -64,8 +65,10 @@ module Clack
       TaskResult = Data.define(:title, :status, :error)
 
       # @param tasks [Array<Hash>] tasks with :title, :task, and optional :enabled keys
+      # @param with_guide [Boolean, nil] show the guide rail on each spinner and error
+      #   detail line (default: Clack.settings[:with_guide])
       # @param output [IO] output stream (default: $stdout)
-      def initialize(tasks:, output: $stdout)
+      def initialize(tasks:, with_guide: nil, output: $stdout)
         @tasks = tasks.map do |task_data|
           Task.new(
             title: task_data[:title],
@@ -73,6 +76,7 @@ module Clack
             enabled: task_data.fetch(:enabled, true)
           )
         end
+        @with_guide = with_guide
         @output = output
         @results = []
       end
@@ -98,9 +102,20 @@ module Clack
 
       private
 
+      # Gutter in front of the red error detail line under a failed task.
+      def error_prefix
+        Core::Settings.with_guide?(@with_guide) ? "#{Colors.gray(Symbols::S_BAR)}  " : ""
+      end
+
+      # Exit, signals, break, and throw end the spinner with the cancel line and
+      # propagate; a non-StandardError prints the error line and propagates.
+      # Only StandardError is recorded as a result. +title.to_s+ on the error
+      # calls keeps a title-less task printing a blank line rather than the
+      # configured error message.
       def run_task(task)
-        spinner = Spinner.new(output: @output)
-        spinner.start(task.title)
+        title = task.title
+        spinner = Spinner.new(output: @output, with_guide: @with_guide)
+        spinner.start(title)
 
         begin
           if task.task.arity.zero?
@@ -108,12 +123,20 @@ module Clack
           else
             task.task.call(spinner.method(:message))
           end
-          spinner.stop(task.title)
-          @results << TaskResult.new(title: task.title, status: :success, error: nil)
+          spinner.stop(title)
+          @results << TaskResult.new(title: title, status: :success, error: nil)
         rescue => exception
-          spinner.error(task.title)
-          @output.puts "#{Colors.gray(Symbols::S_BAR)}  #{Colors.red(exception.message)}"
-          @results << TaskResult.new(title: task.title, status: :error, error: exception.message)
+          spinner.error(title.to_s)
+          @output.puts "#{error_prefix}#{Colors.red(exception.message)}"
+          @results << TaskResult.new(title: title, status: :error, error: exception.message)
+        rescue SystemExit, SignalException
+          spinner.cancel
+          raise
+        rescue Exception # standard:disable Lint/RescueException
+          spinner.error(title.to_s)
+          raise
+        ensure
+          spinner.abandon
         end
       end
     end

data/lib/clack/prompts/text.rb

@@ -47,7 +47,7 @@ module Clack
       # @param initial_value [String, nil] pre-filled editable text
       # @param completions [Array<String>, Proc, nil] tab completion candidates. Array of
       #   strings or a proc that receives current input and returns candidates.
-      # @option opts [Proc, nil] :validate validation proc returning error string or nil
+      # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve})
       # @option opts [Hash] additional options passed to {Core::Prompt}
       def initialize(message:, placeholder: nil, default_value: nil, initial_value: nil, completions: nil, **opts)
         super(message:, **opts)
@@ -88,7 +88,7 @@ module Clack
       end
 
       def build_frame
-        "#{frame_header}#{active_bar}  #{input_display}\n#{frame_footer}"
+        "#{frame_header}#{gutter(active_bar)}#{input_display}\n#{frame_footer}"
       end
 
       private

data/lib/clack/stream.rb

@@ -6,70 +6,85 @@ require "stringio"
 module Clack
   # Stream logging utility for iterables, enumerables, and IO streams.
   # Similar to Log but works with streaming data in real-time.
+  #
+  # Every method accepts +with_guide:+ (default: the global setting). With
+  # guides off the level symbol stays on the first line and continuation
+  # lines lose their rail prefix.
   module Stream
     class << self
       # Stream lines with an info symbol (cyan).
       # @param source [IO, String, Enumerable] data source to stream
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream
       # @yield [line] optional block called for each line
       # @return [void]
-      def info(source, output: $stdout, &block)
-        stream_with_symbol(source, Symbols::S_INFO, :cyan, output, &block)
+      def info(source, with_guide: nil, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_INFO, :cyan, with_guide, output, &block)
       end
 
       # Stream lines with a success symbol (green).
       # @param source [IO, String, Enumerable] data source to stream
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream
       # @yield [line] optional block called for each line
       # @return [void]
-      def success(source, output: $stdout, &block)
-        stream_with_symbol(source, Symbols::S_SUCCESS, :green, output, &block)
+      def success(source, with_guide: nil, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_SUCCESS, :green, with_guide, output, &block)
       end
 
       # Stream lines with a step symbol (green).
       # @param source [IO, String, Enumerable] data source to stream
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream
       # @yield [line] optional block called for each line
       # @return [void]
-      def step(source, output: $stdout, &block)
-        stream_with_symbol(source, Symbols::S_STEP_SUBMIT, :green, output, &block)
+      def step(source, with_guide: nil, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_STEP_SUBMIT, :green, with_guide, output, &block)
       end
 
       # Stream lines with a warning symbol (yellow).
       # @param source [IO, String, Enumerable] data source to stream
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream
       # @yield [line] optional block called for each line
       # @return [void]
-      def warn(source, output: $stdout, &block)
-        stream_with_symbol(source, Symbols::S_WARN, :yellow, output, &block)
+      def warn(source, with_guide: nil, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_WARN, :yellow, with_guide, output, &block)
       end
 
       # Stream lines with an error symbol (red).
       # @param source [IO, String, Enumerable] data source to stream
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream
       # @yield [line] optional block called for each line
       # @return [void]
-      def error(source, output: $stdout, &block)
-        stream_with_symbol(source, Symbols::S_ERROR, :red, output, &block)
+      def error(source, with_guide: nil, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_ERROR, :red, with_guide, output, &block)
       end
 
-      # Stream lines with a plain bar prefix (no symbol).
+      # Stream lines with a plain bar prefix (no symbol), or bare lines with guides off.
       # @param source [IO, String, Enumerable] data source to stream
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
       # @param output [IO] output stream
       # @return [void]
-      def message(source, output: $stdout)
+      def message(source, with_guide: nil, output: $stdout)
+        prefix = rail_prefix(with_guide)
         each_line(source) do |line|
-          output.puts "#{Colors.gray(Symbols::S_BAR)}  #{line.chomp}"
+          output.puts "#{prefix}#{line.chomp}"
           output.flush
         end
       end
 
       # Stream from a subprocess command.
       # Usage: Clack.stream.command("npm install", type: :info)
-      # Returns true on success, false on failure or if command cannot be executed
-      def command(cmd, type: :info, output: $stdout)
+      # @param cmd [String] the shell command to run
+      # @param type [Symbol] which stream method renders the output (:info, :success, :step, :warn, :error)
+      # @param with_guide [Boolean, nil] show the guide rail (default: Clack.settings[:with_guide])
+      # @param output [IO] output stream
+      # @return [Boolean] true on success, false on failure or if the command cannot be executed
+      def command(cmd, type: :info, with_guide: nil, output: $stdout)
         IO.popen(cmd, err: %i[child out]) do |io|
-          send(type, io, output: output)
+          send(type, io, with_guide:, output:)
         end
         $CHILD_STATUS.success?
       rescue Errno::ENOENT
@@ -78,15 +93,20 @@ module Clack
 
       private
 
-      def stream_with_symbol(source, symbol, color, output)
+      def rail_prefix(with_guide)
+        Core::Settings.with_guide?(with_guide) ? "#{Colors.gray(Symbols::S_BAR)}  " : ""
+      end
+
+      def stream_with_symbol(source, symbol, color, with_guide, output)
         first = true
+        prefix = rail_prefix(with_guide)
         each_line(source) do |line|
           line = line.chomp
           if first
             output.puts "#{Colors.send(color, symbol)}  #{line}"
             first = false
           else
-            output.puts "#{Colors.gray(Symbols::S_BAR)}  #{line}"
+            output.puts "#{prefix}#{line}"
           end
           output.flush
           yield line if block_given?

data/lib/clack/symbols.rb

@@ -7,7 +7,7 @@ module Clack
     class << self
       # Check if unicode output is enabled.
       # CLACK_UNICODE=1 forces unicode, CLACK_UNICODE=0 forces ASCII.
-      # Otherwise auto-detects from TTY and TERM.
+      # Otherwise follows {Environment.colors_supported?} (TTY, TERM, NO_COLOR, FORCE_COLOR).
       def unicode?
         return @unicode if defined?(@unicode)
 
@@ -87,6 +87,11 @@ module Clack
     # Unicode error log symbol, or ASCII fallback.
     S_ERROR = unicode? ? "■" : "x"
 
+    # Keyboard hint pieces used by the instruction footer
+    S_ARROWS_UP_DOWN = unicode? ? "↑/↓" : "up/down"
+    # Unicode bullet separator between hints, or ASCII fallback.
+    S_HINT_SEPARATOR = unicode? ? " • " : " | "
+
     # File system
     S_FOLDER = unicode? ? "📁" : "[D]"
     # Unicode file icon, or ASCII fallback.

data/lib/clack/task_log.rb

@@ -15,11 +15,16 @@ module Clack
     # @param title [String] Title displayed at the top
     # @param limit [Integer, nil] Max lines to show (older lines scroll out)
     # @param retain_log [Boolean] Keep full log history for display on error
+    # @param with_guide [Boolean, nil] Show the guide rail around the title and log lines
+    #   (default: Clack.settings[:with_guide])
     # @param output [IO] Output stream
-    def initialize(title:, limit: nil, retain_log: false, output: $stdout)
+    def initialize(title:, limit: nil, retain_log: false, with_guide: nil, output: $stdout)
       @title = title
       @limit = limit
       @retain_log = retain_log
+      # Resolved once: the title is printed right here, and every later redraw
+      # must clear the same number of lines, so the setting cannot change mid-log.
+      @guide = Core::Settings.with_guide?(with_guide)
       @output = output
       @buffer = []
       @full_buffer = []
@@ -80,8 +85,15 @@ module Clack
     private
 
     def render_title
+      title_line = "#{Colors.green(Symbols::S_STEP_SUBMIT)}  #{@title}"
+      unless @guide
+        @output.puts title_line
+        @lines_written = 1
+        return
+      end
+
       @output.puts Colors.gray(Symbols::S_BAR)
-      @output.puts "#{Colors.green(Symbols::S_STEP_SUBMIT)}  #{@title}"
+      @output.puts title_line
       @output.puts Colors.gray(Symbols::S_BAR)
       @lines_written = 3
     end
@@ -106,23 +118,27 @@ module Clack
     end
 
     def render_buffer
-      bar = Colors.gray(Symbols::S_BAR)
+      prefix = line_prefix
       @buffer.each do |message|
-        print_message_lines(bar, message)
+        print_message_lines(prefix, message)
       end
     end
 
     def render_full_buffer
-      bar = Colors.gray(Symbols::S_BAR)
+      prefix = line_prefix
       lines = @retain_log ? (@full_buffer + @buffer) : @buffer
       lines.each do |message|
-        print_message_lines(bar, message)
+        print_message_lines(prefix, message)
       end
     end
 
-    def print_message_lines(bar, message)
+    def line_prefix
+      @guide ? "#{Colors.gray(Symbols::S_BAR)}  " : ""
+    end
+
+    def print_message_lines(prefix, message)
       message.each_line do |line|
-        @output.puts "#{bar}  #{Colors.dim(line.chomp)}"
+        @output.puts "#{prefix}#{Colors.dim(line.chomp)}"
       end
     end
 

data/lib/clack/utils.rb

@@ -19,6 +19,23 @@ module Clack
         display_width(strip_ansi(text))
       end
 
+      # Count the terminal rows +text+ occupies once printed: one per line, plus
+      # one more for every +width+ columns a line overflows, since the terminal
+      # soft-wraps lines wider than the pane. A line exactly +width+ wide stays
+      # on one row (the terminal defers the wrap until the next character).
+      # Trailing text without a newline only counts the rows it wrapped onto;
+      # the cursor is still on its last row.
+      # @param text [String] rendered text, ANSI codes allowed
+      # @param width [Integer] terminal width in columns
+      # @return [Integer] rows
+      def rendered_rows(text, width)
+        text.to_s.each_line.sum do |line|
+          columns = visible_length(line.chomp)
+          rows = columns.zero? ? 1 : (columns + width - 1) / width
+          line.end_with?("\n") ? rows : rows - 1
+        end
+      end
+
       # Calculate the terminal display width (columns) of a string.
       # ASCII and most chars: width 1. CJK ideographs, fullwidth forms, common emoji: width 2.
       # Zero-width joiners, combining marks, variation selectors: width 0.
@@ -170,12 +187,7 @@ module Clack
       # Width of a grapheme cluster: the max char_width among its codepoints.
       # Handles ZWJ emoji sequences, combining marks, and flag sequences correctly.
       def grapheme_width(cluster)
-        max_w = 0
-        cluster.each_char do |char|
-          w = char_width(char)
-          max_w = w if w > max_w
-        end
-        max_w
+        cluster.each_char.map { |char| char_width(char) }.max || 0
       end
 
       def char_width(char)