clack 0.1.4 → 0.4.1

data/lib/clack/prompts/tasks.rb

@@ -8,8 +8,12 @@ module Clack
     # Displays success/error status after each task completes.
     #
     # Each task is a hash with:
-    # - `:title` - display title
-    # - `:task` - Proc to execute (exceptions are caught)
+    # - +:title+ - display title
+    # - +:task+ - Proc to execute (exceptions are caught).
+    #     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.
     #
     # @example Basic usage
     #   results = Clack.tasks(tasks: [
@@ -18,6 +22,19 @@ module Clack
     #     { title: "Running tests", task: -> { run_tests } }
     #   ])
     #
+    # @example Updating spinner message mid-task
+    #   Clack.tasks(tasks: [
+    #     { title: "Installing", task: ->(message) {
+    #       message.call("Step 1..."); step1
+    #       message.call("Step 2..."); step2
+    #     }}
+    #   ])
+    #
+    # @example Conditionally skipping tasks
+    #   Clack.tasks(tasks: [
+    #     { title: "Deploy", task: -> { deploy }, enabled: ENV["DEPLOY"] == "true" }
+    #   ])
+    #
     # @example Checking results
     #   results.each do |r|
     #     if r.status == :error
@@ -26,12 +43,18 @@ module Clack
     #   end
     #
     class Tasks
+      # A single task definition with title, callable, and enabled flag.
+      #
       # @!attribute [r] title
       #   @return [String] the task title
       # @!attribute [r] task
       #   @return [Proc] the task to execute
-      Task = Struct.new(:title, :task, keyword_init: true)
+      # @!attribute [r] enabled
+      #   @return [Boolean] whether the task should run (default: true)
+      Task = Struct.new(:title, :task, :enabled, keyword_init: true)
 
+      # Result of a completed task, including status and any error.
+      #
       # @!attribute [r] title
       #   @return [String] the task title
       # @!attribute [r] status
@@ -40,16 +63,18 @@ module Clack
       #   @return [String, nil] error message if failed
       TaskResult = Struct.new(:title, :status, :error, keyword_init: true)
 
-      # @param tasks [Array<Hash>] tasks with :title and :task keys
+      # @param tasks [Array<Hash>] tasks with :title, :task, and optional :enabled keys
       # @param output [IO] output stream (default: $stdout)
       def initialize(tasks:, output: $stdout)
-        @tasks = tasks.map { |task_data| Task.new(title: task_data[:title], task: task_data[:task]) }
+        @tasks = tasks.map do |task_data|
+          Task.new(
+            title: task_data[:title],
+            task: task_data[:task],
+            enabled: task_data.fetch(:enabled, true)
+          )
+        end
         @output = output
         @results = []
-        @current_index = 0
-        @frame_index = 0
-        @spinning = false
-        @mutex = Mutex.new
       end
 
       # Run all tasks sequentially.
@@ -57,8 +82,9 @@ module Clack
       # @return [Array<TaskResult>] results for each task
       def run
         @output.print Core::Cursor.hide
-        @tasks.each_with_index do |task, idx|
-          @current_index = idx
+        @tasks.each do |task|
+          next unless task.enabled
+
           run_task(task)
         end
         @output.print Core::Cursor.show
@@ -68,63 +94,22 @@ module Clack
       private
 
       def run_task(task)
-        render_pending(task.title)
+        spinner = Spinner.new(output: @output)
+        spinner.start(task.title)
 
         begin
-          task.task.call
+          if task.task.arity.zero?
+            task.task.call
+          else
+            task.task.call(spinner.method(:message))
+          end
+          spinner.stop(task.title)
           @results << TaskResult.new(title: task.title, status: :success, error: nil)
-          render_success(task.title)
         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)
-          render_error(task.title, exception.message)
-        end
-      end
-
-      def render_pending(title)
-        @output.print "\r#{Core::Cursor.clear_to_end}"
-        @output.print "#{Colors.magenta(spinner_frame)}  #{title}"
-        @spinner_thread = start_spinner(title)
-      end
-
-      def render_success(title)
-        stop_spinner
-        @output.print "\r#{Core::Cursor.clear_to_end}"
-        @output.puts "#{Colors.green(Symbols::S_STEP_SUBMIT)}  #{title}"
-      end
-
-      def render_error(title, message)
-        stop_spinner
-        @output.print "\r#{Core::Cursor.clear_to_end}"
-        @output.puts "#{Colors.red(Symbols::S_STEP_CANCEL)}  #{title}"
-        @output.puts "#{Colors.gray(Symbols::S_BAR)}  #{Colors.red(message)}"
-      end
-
-      def start_spinner(title)
-        @mutex.synchronize do
-          @spinning = true
-          @frame_index = 0
         end
-        Thread.new do
-          while @mutex.synchronize { @spinning }
-            frame = @mutex.synchronize do
-              current_frame = Symbols::SPINNER_FRAMES[@frame_index]
-              @frame_index = (@frame_index + 1) % Symbols::SPINNER_FRAMES.length
-              current_frame
-            end
-            @output.print "\r#{Core::Cursor.clear_to_end}"
-            @output.print "#{Colors.magenta(frame)}  #{title}"
-            sleep Symbols::SPINNER_DELAY
-          end
-        end
-      end
-
-      def stop_spinner
-        @mutex.synchronize { @spinning = false }
-        @spinner_thread&.join
-      end
-
-      def spinner_frame
-        @mutex.synchronize { Symbols::SPINNER_FRAMES[@frame_index] }
       end
     end
   end

data/lib/clack/prompts/text.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Clack
+  # Interactive prompt implementations (text, select, confirm, etc.).
   module Prompts
     # Single-line text input prompt with cursor navigation.
     #
@@ -11,6 +12,7 @@ module Clack
     # - Default value (used if submitted empty)
     # - Initial value (pre-filled, editable)
     # - Validation support
+    # - Tab completion (optional)
     #
     # @example Basic usage
     #   name = Clack.text(message: "What is your name?")
@@ -24,6 +26,18 @@ module Clack
     #     validate: ->(v) { "Required!" if v.empty? }
     #   )
     #
+    # @example With tab completion
+    #   cmd = Clack.text(
+    #     message: "Command?",
+    #     completions: %w[build test deploy lint format]
+    #   )
+    #
+    # @example With dynamic completions
+    #   cmd = Clack.text(
+    #     message: "Command?",
+    #     completions: ->(input) { Dir.glob("#{input}*") }
+    #   )
+    #
     class Text < Core::Prompt
       include Core::TextInputHelper
 
@@ -31,12 +45,15 @@ module Clack
       # @param placeholder [String, nil] dim text shown when input is empty
       # @param default_value [String, nil] value used if submitted empty
       # @param initial_value [String, nil] pre-filled editable text
-      # @param validate [Proc, nil] validation proc returning error string or nil
-      # @param opts [Hash] additional options passed to {Core::Prompt}
-      def initialize(message:, placeholder: nil, default_value: nil, initial_value: nil, **opts)
+      # @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 [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, placeholder: nil, default_value: nil, initial_value: nil, completions: nil, **opts)
         super(message:, **opts)
         @placeholder = placeholder
         @default_value = default_value
+        @completions = completions
         @value = initial_value || ""
         @cursor = @value.grapheme_clusters.length
       end
@@ -58,7 +75,11 @@ module Clack
           end
         end
 
-        handle_text_input(key)
+        if key == "\t" && @completions
+          tab_complete
+        else
+          handle_text_input(key)
+        end
       end
 
       def submit
@@ -72,7 +93,7 @@ module Clack
         lines << "#{symbol_for_state}  #{@message}\n"
         lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
-        lines << "#{bar_end}\n" if @state == :active || @state == :initial
+        lines << "#{bar_end}\n" if @state in :active | :initial
 
         validation_lines = validation_message_lines
         if validation_lines.any?
@@ -93,6 +114,41 @@ module Clack
 
         lines.join
       end
+
+      private
+
+      # Complete the current input using the longest common prefix of matching candidates.
+      # Single match: fills the full candidate. Multiple matches: fills the shared prefix.
+      def tab_complete
+        candidates = if @completions.respond_to?(:call)
+          @completions.call(@value)
+        else
+          @completions.select { |candidate| candidate.downcase.start_with?(@value.downcase) }
+        end
+
+        return if candidates.empty?
+
+        completion = if candidates.length == 1
+          candidates.first
+        else
+          common_prefix(candidates)
+        end
+
+        return if completion.length <= @value.length
+
+        @value = completion
+        @cursor = @value.grapheme_clusters.length
+      end
+
+      def common_prefix(strings)
+        return "" if strings.empty?
+
+        ref = strings.first
+        ref.each_char.with_index do |char, idx|
+          return ref[0, idx] unless strings.all? { |s| s[idx]&.downcase == char.downcase }
+        end
+        ref
+      end
     end
   end
 end

data/lib/clack/stream.rb

@@ -4,30 +4,59 @@ require "English"
 require "stringio"
 
 module Clack
-  # Stream logging utility for iterables, enumerables, and IO streams
-  # Similar to Log but works with streaming data in real-time
+  # Stream logging utility for iterables, enumerables, and IO streams.
+  # Similar to Log but works with streaming data in real-time.
   module Stream
     class << self
+      # Stream lines with an info symbol (cyan).
+      # @param source [IO, String, Enumerable] data source to stream
+      # @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)
       end
 
+      # Stream lines with a success symbol (green).
+      # @param source [IO, String, Enumerable] data source to stream
+      # @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)
       end
 
+      # Stream lines with a step symbol (green).
+      # @param source [IO, String, Enumerable] data source to stream
+      # @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)
       end
 
+      # Stream lines with a warning symbol (yellow).
+      # @param source [IO, String, Enumerable] data source to stream
+      # @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)
       end
 
+      # Stream lines with an error symbol (red).
+      # @param source [IO, String, Enumerable] data source to stream
+      # @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)
       end
 
+      # Stream lines with a plain bar prefix (no symbol).
+      # @param source [IO, String, Enumerable] data source to stream
+      # @param output [IO] output stream
+      # @return [void]
       def message(source, output: $stdout)
         each_line(source) do |line|
           output.puts "#{Colors.gray(Symbols::S_BAR)}  #{line.chomp}"
@@ -35,7 +64,7 @@ module Clack
         end
       end
 
-      # Stream from a subprocess command
+      # 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)

data/lib/clack/symbols.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Clack
+  # Unicode and ASCII symbols used for prompt rendering.
+  # Automatically selects Unicode or ASCII fallback based on terminal capabilities.
   module Symbols
     class << self
       # Check if unicode output is enabled.
@@ -12,6 +14,8 @@ module Clack
         @unicode = compute_unicode_support
       end
 
+      # Reset cached unicode detection (useful for testing).
+      # @return [void]
       def reset!
         remove_instance_variable(:@unicode) if defined?(@unicode)
       end
@@ -29,17 +33,23 @@ module Clack
 
     # Step indicators
     S_STEP_ACTIVE = unicode? ? "◆" : "*"
+    # Unicode cancel step indicator, or ASCII fallback.
     S_STEP_CANCEL = unicode? ? "■" : "x"
+    # Unicode error step indicator, or ASCII fallback.
     S_STEP_ERROR = unicode? ? "▲" : "x"
+    # Unicode submit step indicator, or ASCII fallback.
     S_STEP_SUBMIT = unicode? ? "◇" : "o"
 
     # Radio buttons
     S_RADIO_ACTIVE = unicode? ? "●" : ">"
+    # Unicode inactive radio button, or ASCII fallback.
     S_RADIO_INACTIVE = unicode? ? "○" : " "
 
     # Checkboxes
     S_CHECKBOX_ACTIVE = unicode? ? "◻" : "[•]"
+    # Unicode selected checkbox, or ASCII fallback.
     S_CHECKBOX_SELECTED = unicode? ? "◼" : "[+]"
+    # Unicode inactive checkbox, or ASCII fallback.
     S_CHECKBOX_INACTIVE = unicode? ? "◻" : "[ ]"
 
     # Password mask
@@ -47,35 +57,50 @@ module Clack
 
     # Bars and connectors
     S_BAR = unicode? ? "│" : "|"
+    # Unicode bar start connector, or ASCII fallback.
     S_BAR_START = unicode? ? "┌" : "+"
+    # Unicode bar end connector, or ASCII fallback.
     S_BAR_END = unicode? ? "└" : "+"
+    # Unicode horizontal bar, or ASCII fallback.
     S_BAR_H = unicode? ? "─" : "-"
+    # Unicode top-right corner, or ASCII fallback.
     S_CORNER_TOP_RIGHT = unicode? ? "╮" : "+"
+    # Unicode top-left corner, or ASCII fallback.
     S_CORNER_TOP_LEFT = unicode? ? "╭" : "+"
+    # Unicode bottom-right corner, or ASCII fallback.
     S_CORNER_BOTTOM_RIGHT = unicode? ? "╯" : "+"
+    # Unicode bottom-left corner, or ASCII fallback.
     S_CORNER_BOTTOM_LEFT = unicode? ? "╰" : "+"
+    # Unicode left T-connector, or ASCII fallback.
     S_CONNECT_LEFT = unicode? ? "├" : "+"
 
     # Square corners (for box with rounded: false)
     S_BAR_START_RIGHT = unicode? ? "┐" : "+"
+    # Unicode square bottom-right corner, or ASCII fallback.
     S_BAR_END_RIGHT = unicode? ? "┘" : "+"
 
     # Log symbols
     S_INFO = unicode? ? "●" : "*"
+    # Unicode success log symbol, or ASCII fallback.
     S_SUCCESS = unicode? ? "◆" : "*"
+    # Unicode warning log symbol, or ASCII fallback.
     S_WARN = unicode? ? "▲" : "!"
+    # Unicode error log symbol, or ASCII fallback.
     S_ERROR = unicode? ? "■" : "x"
 
     # File system
     S_FOLDER = unicode? ? "📁" : "[D]"
+    # Unicode file icon, or ASCII fallback.
     S_FILE = unicode? ? "📄" : "[F]"
 
     # Spinner frames - quarter circle rotation pattern
     SPINNER_FRAMES = unicode? ? %w[◒ ◐ ◓ ◑] : %w[• o O 0]
+    # Delay between spinner frame updates (seconds).
     SPINNER_DELAY = unicode? ? 0.08 : 0.12
 
     # Progress bar characters
     S_PROGRESS_FILLED = unicode? ? "█" : "#"
+    # Unicode empty progress segment, or ASCII fallback.
     S_PROGRESS_EMPTY = unicode? ? "░" : "-"
 
     # Alternative progress bar (smoother gradient)

data/lib/clack/task_log.rb

@@ -69,7 +69,8 @@ module Clack
       reset_buffers
     end
 
-    # @api private
+    # Add a message from a group to the log buffer.
+    # @private
     def add_group_message(_group, msg)
       clear_buffer
       @buffer << msg.to_s
@@ -149,15 +150,12 @@ module Clack
 
   # A group within a TaskLog
   class TaskLogGroup
-    def initialize(name, parent)
-      @name = name
+    def initialize(_name, parent)
       @parent = parent
-      @buffer = []
     end
 
     # Add a message to this group
     def message(msg, raw: false)
-      @buffer << msg.to_s
       @parent.add_group_message(self, msg)
     end
 

data/lib/clack/testing.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Clack
+  # First-class test helpers for simulating prompt interactions.
+  #
+  # Works with RSpec, Minitest, or any test framework. Provides a DSL
+  # for feeding keystrokes to prompts without a real terminal.
+  #
+  # @example Basic text prompt
+  #   result = Clack::Testing.simulate(Clack.method(:text), message: "Name?") do |p|
+  #     p.type("Alice")
+  #     p.submit
+  #   end
+  #   assert_equal "Alice", result
+  #
+  # @example Select prompt
+  #   result = Clack::Testing.simulate(Clack.method(:select), message: "Pick", options: %w[a b c]) do |p|
+  #     p.down
+  #     p.submit
+  #   end
+  #   assert_equal "b", result
+  #
+  # @example Multiselect
+  #   result = Clack::Testing.simulate(Clack.method(:multiselect), message: "Pick", options: %w[a b c]) do |p|
+  #     p.toggle      # select "a"
+  #     p.down
+  #     p.toggle      # select "b"
+  #     p.submit
+  #   end
+  #   assert_equal %w[a b], result
+  #
+  # @example Cancellation
+  #   result = Clack::Testing.simulate(Clack.method(:text), message: "Name?") do |p|
+  #     p.cancel
+  #   end
+  #   assert Clack.cancel?(result)
+  module Testing
+    # Key constants matching what KeyReader returns
+    KEYS = {
+      enter: "\r",
+      escape: "\e",
+      ctrl_c: "\u0003",
+      ctrl_d: "\u0004",
+      up: "\e[A",
+      down: "\e[B",
+      right: "\e[C",
+      left: "\e[D",
+      backspace: "\u007F",
+      space: " ",
+      tab: "\t",
+      shift_tab: "\e[Z"
+    }.freeze
+
+    # DSL for building a key sequence to feed to a prompt.
+    class PromptDriver
+      # @return [Array<String>] accumulated key sequence
+      attr_reader :keys
+
+      def initialize
+        @keys = []
+      end
+
+      # Type a string of text character by character.
+      # @param text [String] text to type
+      def type(text)
+        text.each_char { |char| @keys << char }
+      end
+
+      # Press Enter to submit.
+      def submit = @keys << KEYS[:enter]
+
+      # Press Escape to cancel.
+      def cancel = @keys << KEYS[:escape]
+
+      # Press arrow down.
+      def down = @keys << KEYS[:down]
+
+      # Press arrow up.
+      def up = @keys << KEYS[:up]
+
+      # Press arrow left.
+      def left = @keys << KEYS[:left]
+
+      # Press arrow right.
+      def right = @keys << KEYS[:right]
+
+      # Press Space (toggle selection in multiselect).
+      def toggle = @keys << KEYS[:space]
+
+      # Press Tab.
+      def tab = @keys << KEYS[:tab]
+
+      # Press Backspace.
+      def backspace = @keys << KEYS[:backspace]
+
+      # Press Ctrl+D (submit multiline text).
+      def ctrl_d = @keys << KEYS[:ctrl_d]
+
+      # Press an arbitrary key by name or character.
+      # @param key [Symbol, String] key name (e.g. :escape) or raw character
+      def key(key)
+        @keys << (key.is_a?(Symbol) ? KEYS.fetch(key) : key)
+      end
+    end
+
+    @mutex = Mutex.new
+
+    class << self
+      # Simulate a prompt interaction by feeding a predefined key sequence.
+      #
+      # @param prompt_method [Method, Proc] the Clack method to call (e.g. +Clack.method(:text)+)
+      # @param kwargs [Hash] keyword arguments for the prompt
+      # @yield [PromptDriver] block to define the interaction
+      # @return [Object] the prompt result
+      def simulate(prompt_method, **kwargs, &block)
+        with_stubbed_input(block) do |output|
+          prompt_method.call(**kwargs, output: output)
+        end
+      end
+
+      # Capture the rendered output of a prompt simulation.
+      # Returns both the result and the raw output string.
+      #
+      # @param prompt_method [Method, Proc] the Clack method to call
+      # @param kwargs [Hash] keyword arguments for the prompt
+      # @yield [PromptDriver] block to define the interaction
+      # @return [Array(Object, String)] [result, output_string]
+      def simulate_with_output(prompt_method, **kwargs, &block)
+        output_io = nil
+        result = with_stubbed_input(block) do |output|
+          output_io = output
+          prompt_method.call(**kwargs, output: output)
+        end
+        [result, output_io.string]
+      end
+
+      private
+
+      def with_stubbed_input(driver_block)
+        driver = PromptDriver.new
+        driver_block.call(driver)
+
+        queue = driver.keys.dup
+        output = StringIO.new
+        read_count = 0
+
+        verbose, $VERBOSE = $VERBOSE, nil
+        Core::KeyReader.singleton_class.alias_method(:_original_read, :read)
+
+        Core::KeyReader.define_singleton_method(:read) do
+          read_count += 1
+          raise "Too many reads (#{read_count}) - possible infinite loop in test" if read_count > 100
+
+          queue.shift || KEYS[:enter]
+        end
+        $VERBOSE = verbose
+
+        yield output
+      ensure
+        if Core::KeyReader.singleton_class.method_defined?(:_original_read)
+          verbose, $VERBOSE = $VERBOSE, nil
+          Core::KeyReader.singleton_class.alias_method(:read, :_original_read)
+          Core::KeyReader.singleton_class.remove_method(:_original_read)
+          $VERBOSE = verbose
+        end
+      end
+    end
+  end
+end

data/lib/clack/transformers.rb

@@ -31,19 +31,20 @@ module Clack
     REGISTRY = {}
 
     class << self
-      # Resolve a transformer from a symbol, proc, or return as-is.
-      # @param transformer [Symbol, Proc, nil] the transformer to resolve
-      # @return [Proc, nil] the resolved transformer proc
+      # Resolve a transformer from a symbol, callable, or return as-is.
+      # @param transformer [Symbol, #call, nil] the transformer to resolve
+      # @return [#call, nil] the resolved transformer
       def resolve(transformer)
         case transformer
         when Symbol
-          REGISTRY[transformer] || raise(ArgumentError, "Unknown transformer: #{transformer}")
-        when Proc
-          transformer
+          REGISTRY[transformer] || raise(ArgumentError,
+            "Unknown transformer: #{transformer.inspect}. Available: #{REGISTRY.keys.map(&:inspect).join(", ")}")
         when nil
           nil
         else
-          raise ArgumentError, "Transform must be a Symbol or Proc, got #{transformer.class}"
+          return transformer if transformer.respond_to?(:call)
+
+          raise ArgumentError, "Transform must be a Symbol or respond to #call, got #{transformer.class}"
         end
       end