ruby-progress 1.3.6 → 1.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '028f7d94178db61fa5e6fc4353b977b1279504486e83dd540ea63fa9bc7bd6ee'
-  data.tar.gz: 135e0f649c449fccb49de440e1b4ff33782bb4d1e44e340d818a2c989628d098
+  metadata.gz: ed28989b5200a0ba018f976c1b7b90b8077916959633a5e2ea576de25bb6ddb5
+  data.tar.gz: f5c0ddea618bad931125e8f3195162e3cae7405c583fe27da5759d0febf30fa1
 SHA512:
-  metadata.gz: 721f3ca96efffadf06b20079ad931f9f47c1580506c7fb4e174323353fafed08f855594561fa77b4af2cbc99ba1d23347662a4363363b5364f41908a936b8cf1
-  data.tar.gz: 262fc8c721794e2f9a13474d00619577c918b70c6af55b30cad2e92d7382af36d3b2d743e3cc3ff0b2159c6498b40ae40f8a057e224f75a12bc385045f23df4e
+  metadata.gz: 6722478a39177ac8c8618035abbd0b155afc275eb53120c7c89ff9f7a0c2194a02313efb5cf19ec59205d5f8002435edbef41c7cf5590f7e5f30ad00fa10f02d
+  data.tar.gz: 861feef40116e9c4a5f1c18e2455032a286c9c38fd7bccca19d24c1438b2554be90db4b5c820421b87301b4f21a3527a9bb17095c35140cf4ddddd0d8551539a

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.7] - 2025-10-22
+
+### Fixed
+
+- PTY command spawning now executes via the user's login shell to support shell aliases/functions and ensure PATH customizations are honored.
+  - Uses `ENV['SHELL']` when available (fallback `/bin/sh`).
+  - `bash`/`zsh`/`sh`: `-lc` is used; `fish`: `-l -c` is used.
+  - Resolves `Errno::ENOENT` when running commands like `-c 'r fast'` under `--stdout-live`.
+
+### Changed
+
+- Refactored output capture internals:
+  - Introduced `RubyProgress::ShellExec.build_shell_argv` for shell argv construction.
+  - Extracted terminal reservation to `RubyProgress::OutputUI.reserve_space`.
+  - Reduced method complexity and addressed linter warnings without behavior changes.
+
 ## [1.3.6] - 2025-10-15
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-progress (1.3.6)
+    ruby-progress (1.3.7)
       tty-cursor (~> 0.7)
       tty-screen (~> 0.8)
 

data/README.md

@@ -6,7 +6,7 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.5.0-ruby.svg)](https://www.ruby-lang.org/)
 <!-- [![Coverage Status](https://img.shields.io/badge/coverage-31%25-yellow.svg)](#) -->
 
-This repository contains three different Ruby progress indicator projects: **Ripple**, **Worm**, and **Twirl**. All provide animated terminal progress indicators with different visual styles and features.
+This repository contains a collection of Ruby progress indicator projects: **Ripple**, **Worm**, **Twirl**, and **Fill**. All provide animated terminal progress indicators with different visual styles and features.
 
 ## Table of Contents
 

data/lib/ruby-progress/cli/fill_options.rb

@@ -8,6 +8,9 @@ module RubyProgress
     # rubocop:disable Metrics/AbcSize
     module Options
       # rubocop :disable Metrics/MethodLength
+      # Parse CLI options for the fill subcommand.
+      #
+      # @return [Hash] parsed options keyed by symbols
       def self.parse_cli_options
         options = {
           style: :blocks,

data/lib/ruby-progress/cli/ripple_options.rb

@@ -6,6 +6,9 @@ require 'json'
 module RippleCLI
   # Option parsing extracted to its own file to reduce module size of RippleCLI.
   module Options
+    # Parse CLI options for the ripple subcommand.
+    #
+    # @return [Hash] parsed options keyed by symbols
     def self.parse_cli_options
       options = {
         speed: :medium,

data/lib/ruby-progress/cli/twirl_cli.rb

@@ -7,6 +7,16 @@ require_relative 'twirl_runner'
 
 # Twirl CLI (extracted from bin/prg)
 module TwirlCLI
+  # CLI dispatcher for the Twirl spinner indicator. Parses options and
+  # dispatches to runtime helpers in TwirlRunner or controls daemons via
+  # RubyProgress::Daemon.
+  #
+  # Public methods:
+  # - .run
+  # - .resolve_pid_file
+  # - .parse_cli_options
+  #
+  # @return [void]
   def self.run
     trap('INT') do
       RubyProgress::Utils.show_cursor
@@ -43,6 +53,11 @@ module TwirlCLI
   end
 
   # runtime methods moved to TwirlRunner
+  # Resolve the pid file path used for named/unnamed daemons.
+  #
+  # @param options [Hash]
+  # @param name_key [Symbol]
+  # @return [String]
   def self.resolve_pid_file(options, name_key)
     return options[:pid_file] if options[:pid_file]
 

data/lib/ruby-progress/cli/twirl_options.rb

@@ -9,6 +9,9 @@ module TwirlCLI
   # Keeps the CLI option definitions extracted from the main dispatcher
   # so the `TwirlCLI` module stays small and focused on dispatching.
   module Options
+    # Parse CLI options for the twirl subcommand.
+    #
+    # @return [Hash] parsed options keyed by symbols
     def self.parse_cli_options
       options = {
         output_position: :above,

data/lib/ruby-progress/cli/twirl_runner.rb

@@ -12,6 +12,12 @@ require_relative '../output_capture'
 # indefinitely, or launching in daemon mode) and were extracted to
 # reduce module size and improve testability.
 module TwirlRunner
+  # Runtime helper: run the provided command while showing a twirl spinner.
+  # Captures output via RubyProgress::OutputCapture when appropriate and
+  # prints final completion messages according to options.
+  #
+  # @param options [Hash] CLI options parsed from TwirlCLI::Options
+  # @return [void] exits with appropriate status code (0 success, 1 failure)
   def self.run_with_command(options)
     message = options[:message]
     captured_output = nil
@@ -72,6 +78,10 @@ module TwirlRunner
     exit success ? 0 : 1
   end
 
+  # Run the spinner indefinitely until interrupted (SIGINT).
+  #
+  # @param options [Hash] CLI options used to configure the spinner
+  # @return [void] exits 130 on interrupt
   def self.run_indefinitely(options)
     message = options[:message]
     spinner = TwirlSpinner.new(message, options)
@@ -96,6 +106,11 @@ module TwirlRunner
     end
   end
 
+  # Run the spinner in daemon mode. Writes a pid file and listens for
+  # control messages via the daemon control message file.
+  #
+  # @param options [Hash]
+  # @return [void]
   def self.run_daemon_mode(options)
     pid_file = resolve_pid_file(options, :daemon_name)
     FileUtils.mkdir_p(File.dirname(pid_file))
@@ -150,6 +165,11 @@ module TwirlRunner
     end
   end
 
+  # Resolve pid file helper used by run_daemon_mode and CLI.
+  #
+  # @param options [Hash]
+  # @param name_key [Symbol]
+  # @return [String]
   def self.resolve_pid_file(options, name_key)
     return options[:pid_file] if options[:pid_file]
 

data/lib/ruby-progress/cli/worm_cli.rb

@@ -6,6 +6,25 @@ require_relative 'worm_options'
 
 # Enhanced Worm CLI (extracted from bin/prg)
 module WormCLI
+  # CLI dispatcher for the Worm indicator.
+  #
+  # Responsibilities:
+  # - parse CLI options (delegates to WormCLI::Options)
+  # - handle daemonization, status, and stop commands via RubyProgress::Daemon
+  # - launch the appropriate runtime mode (command-run, indefinite, daemon)
+  #
+  # Public methods:
+  # - .run
+  # - .resolve_pid_file
+  # - .run_daemon_mode
+
+  # Determine the pid file path from options. If options specify a custom
+  # :pid_file, return it. If a named daemon key is present, use
+  # /tmp/ruby-progress/<name>.pid. Otherwise fall back to the default.
+  #
+  # @param options [Hash] parsed CLI options
+  # @param name_key [Symbol] key used for named daemons (default :daemon_name)
+  # @return [String] path to the pid file
   def self.resolve_pid_file(options, name_key = :daemon_name)
     return options[:pid_file] if options[:pid_file]
 
@@ -14,6 +33,10 @@ module WormCLI
     RubyProgress::Daemon.default_pid_file
   end
 
+  # Entrypoint for the Worm CLI. Parses options and dispatches to status,
+  # stop, daemon, or runtime modes. Ensures the cursor is restored on Ctrl+C.
+  #
+  # @return [void] exits with appropriate exit codes for status/stop modes.
   def self.run
     trap('INT') do
       RubyProgress::Utils.show_cursor
@@ -53,6 +76,11 @@ module WormCLI
     end
   end
 
+  # Launch the worm indicator in daemon mode writing a pid file and
+  # monitoring for control messages. Ensures pid file is removed on exit.
+  #
+  # @param options [Hash] parsed CLI options used to configure the Worm instance
+  # @return [void]
   def self.run_daemon_mode(options)
     pid_file = resolve_pid_file(options, :daemon_name)
     FileUtils.mkdir_p(File.dirname(pid_file))

data/lib/ruby-progress/cli/worm_options.rb

@@ -8,6 +8,9 @@ module WormCLI
   # Keeps the CLI option definitions for `prg worm` extracted from
   # the main dispatcher to keep the CLI module small and focused.
   module Options
+    # Parse CLI options for the worm subcommand.
+    #
+    # @return [Hash] parsed options keyed by symbols
     def self.parse_cli_options
       options = {
         output_position: :above,

data/lib/ruby-progress/daemon.rb

@@ -9,14 +9,39 @@ module RubyProgress
   module Daemon
     module_function
 
+    # Return the default PID file path used by ruby-progress daemons.
+    #
+    # @return [String] The filesystem path to the default PID file.
+    # @example
+    #   RubyProgress::Daemon.default_pid_file
+    #   #=> "/tmp/ruby-progress/progress.pid"
     def default_pid_file
       '/tmp/ruby-progress/progress.pid'
     end
 
+    # Return the path for the control message file corresponding to a PID file.
+    # The control message file is used to pass JSON-encoded messages to a running
+    # daemon (for example, success/failure metadata or a final message).
+    #
+    # @param pid_file [String] the path to the pid file
+    # @return [String] the control-message file path (pid_file + ".msg")
+    # @example
+    #   RubyProgress::Daemon.control_message_file('/tmp/foo.pid')
+    #   #=> '/tmp/foo.pid.msg'
     def control_message_file(pid_file)
       "#{pid_file}.msg"
     end
 
+    # Print the daemon status for the given PID file and exit with an appropriate
+    # exit code. If the PID file exists and the process is running this prints
+    # a message and exits 0. If the PID file exists but the process is not
+    # running this prints a warning and exits 1. If the PID file does not
+    # exist this prints that the daemon is not running and exits 1.
+    #
+    # @param pid_file [String] path to the pid file
+    # @return [void]
+    # @example
+    #   RubyProgress::Daemon.show_status('/tmp/ruby-progress/progress.pid')
     def show_status(pid_file)
       if File.exist?(pid_file)
         pid = File.read(pid_file).strip
@@ -29,6 +54,23 @@ module RubyProgress
       end
     end
 
+    # Stop a running daemon by reading its PID from the given pid file. Optionally
+    # write a small JSON control message (containing :checkmark and :message keys)
+    # to the corresponding control message file before signalling the process.
+    # The method attempts to send SIGUSR1 to the running process, sleeps briefly
+    # to allow the process to handle the signal, and then removes the pid file.
+    #
+    # This helper prints user-friendly errors and exits with non-zero status when
+    # the pid file is missing, the process cannot be found, or permission is
+    # denied when sending the signal.
+    #
+    # @param pid_file [String] path to the pid file
+    # @param message [String, nil] optional message to send to the daemon via the control file
+    # @param checkmark [Boolean] whether to include a checkmark flag in the control payload
+    # @param error [Boolean] whether this stop represents an error (affects success flag in payload)
+    # @return [void]
+    # @example
+    #   RubyProgress::Daemon.stop_daemon_by_pid_file('/tmp/ruby-progress/progress.pid', message: 'Stopping', checkmark: true)
     def stop_daemon_by_pid_file(pid_file, message: nil, checkmark: false, error: false)
       unless File.exist?(pid_file)
         puts "PID file #{pid_file} not found"

data/lib/ruby-progress/fill.rb

@@ -3,6 +3,16 @@
 module RubyProgress
   # Determinate progress bar with customizable fill styles
   class Fill
+    # A simple determinate progress bar that can be advanced programmatically
+    # or used with the block-based convenience method {Fill.progress}.
+    #
+    # Public API (instance): #advance, #percent=, #completed?, #render, #complete, #cancel
+    # Public API (class): .progress, .parse_custom_style
+    #
+    # @example
+    #   Fill.progress(length: 10) do |bar|
+    #     10.times { bar.advance; sleep 0.1 }
+    #   end
     # Built-in fill styles with empty and full characters
     FILL_STYLES = {
       blocks: { empty: '▱', full: '▰' },
@@ -19,6 +29,14 @@ module RubyProgress
     attr_reader :length, :style, :current_progress, :start_chars, :end_chars
     attr_accessor :success_message, :error_message
 
+    # Initialize a progress bar instance.
+    #
+    # @param options [Hash] configuration values
+    # @option options [Integer] :length number of cells in the bar (default 20)
+    # @option options [Symbol,String,Hash] :style style name, symbol, or custom hash
+    # @option options [String] :success success message shown on completion
+    # @option options [String] :error error message shown on cancel/exception
+    # @return [void]
     def initialize(options = {})
       @length = options[:length] || 20
       @style = parse_style(options[:style] || :blocks)
@@ -36,7 +54,11 @@ module RubyProgress
       end
     end
 
-    # Advance the progress bar by one step or specified increment
+    # Advance the progress bar by one step or specified increment.
+    #
+    # @param increment [Integer] amount to increase progress by (default 1)
+    # @param percent [Numeric,nil] optional percent to set the bar to (0-100)
+    # @return [Boolean] true if the bar is complete after advancing
     def advance(increment: 1, percent: nil)
       @current_progress = if percent
                             [@length * percent / 100.0, @length].min.round
@@ -48,7 +70,10 @@ module RubyProgress
       completed?
     end
 
-    # Set progress to specific percentage (0-100)
+    # Set progress to specific percentage (0-100).
+    #
+    # @param percent [Numeric] percentage 0..100 to set the bar to
+    # @return [Boolean] true if the bar is complete after setting percent
     def percent=(percent)
       percent = percent.clamp(0, 100) # Clamp between 0-100
       @current_progress = (@length * percent / 100.0).round
@@ -56,22 +81,30 @@ module RubyProgress
       completed?
     end
 
-    # Check if progress bar is complete
+    # Check if progress bar is complete.
+    #
+    # @return [Boolean]
     def completed?
       @current_progress >= @length
     end
 
-    # Get current progress as percentage
+    # Get current progress as percentage.
+    #
+    # @return [Float] percentage (0.0-100.0) rounded to 1 decimal place
     def percent
       (@current_progress.to_f / @length * 100).round(1)
     end
 
-    # Get current progress as float (0.0-100.0) - for scripting
+    # Get current progress as float (0.0-100.0) - for scripting.
+    #
+    # @return [Float]
     def current
       (@current_progress.to_f / @length * 100).round(1)
     end
 
-    # Get detailed progress status information
+    # Get detailed progress status information.
+    #
+    # @return [Hash] structured status information about the bar
     def report
       {
         progress: [@current_progress, @length],
@@ -81,7 +114,9 @@ module RubyProgress
       }
     end
 
-    # Render the current progress bar to stderr
+    # Render the current progress bar to stderr.
+    #
+    # @return [void]
     def render
       # First redraw captured output (if any) so it appears above/below the bar
       @output_capture&.redraw($stderr)
@@ -94,7 +129,11 @@ module RubyProgress
       $stderr.flush
     end
 
-    # Complete the progress bar and show success message
+    # Complete the progress bar and show success message.
+    #
+    # @param message [String,nil] optional override message
+    # @param icons [Hash] optional icons map passed to Utils.display_completion
+    # @return [void]
     def complete(message = nil, icons: {})
       @current_progress = @length
       render
@@ -113,7 +152,10 @@ module RubyProgress
       end
     end
 
-    # Cancel the progress bar and show error message
+    # Cancel the progress bar and show error message.
+    #
+    # @param message [String,nil] optional override message
+    # @return [void]
     def cancel(message = nil)
       $stderr.print "\r\e[2K" # Clear the progress bar
       $stderr.flush

data/lib/ruby-progress/fill_cli.rb

@@ -12,6 +12,10 @@ module RubyProgress
   # rubocop:disable Metrics/ClassLength
   module FillCLI
     class << self
+      # Entrypoint for the `prg fill` CLI. Parses options and dispatches to
+      # the matching behavior (auto-advance, command-run, daemon, report).
+      #
+      # @return [void]
       def run
         trap('INT') do
           Utils.show_cursor

data/lib/ruby-progress/output_capture.rb

@@ -13,11 +13,64 @@ rescue LoadError
 end
 
 module RubyProgress
+  # Shell execution helpers for spawning commands within a PTY
+  module ShellExec
+    module_function
+
+    # Build argv for invoking the user's shell with a command string.
+    # Uses login shells so aliases/functions and environment are available.
+    #
+    # @param shell [String] path to shell executable
+    # @param command [String] command to execute
+    # @return [Array<String>] argv (excluding the shell path for convenience)
+    def build_shell_argv(shell, command)
+      shell_name = File.basename(shell)
+      case shell_name
+      when 'fish'
+        ['-l', '-c', command]
+      else
+        ['-lc', command]
+      end
+    end
+  end
+
+  # Output helpers for reserving terminal space
+  module OutputUI
+    module_function
+
+    def reserve_space(io, position, lines)
+      return unless io.tty?
+
+      if position == :above
+        io.print "\e[#{lines}L"
+      else
+        io.print("\n" * lines)
+        io.print "\e[#{lines}A"
+      end
+
+      io.flush
+    end
+  end
+
   # PTY-based live output capture that reserves a small terminal area
   # for printing captured output while the animation draws elsewhere.
   class OutputCapture
     attr_reader :exit_status
 
+    # Create a new OutputCapture instance.
+    #
+    # @param command [String] the shell command to spawn and capture via PTY
+    # @param lines [Integer] number of reserved lines to keep for captured output (minimum 1)
+    # @param position [Symbol,String] :above/:below (or :top/:bottom) to place the reserved area
+    # @param log_path [String,nil] optional path to append raw captured output
+    # @param stream [Boolean] when true, redraw captured output live into the terminal area
+    # @param debug [Boolean,nil] enable debug logging when true; nil will consult ENV['RUBY_PROGRESS_DEBUG']
+    # @return [OutputCapture]
+    # @example
+    #   oc = RubyProgress::OutputCapture.new(command: 'bundle exec rspec', lines: 4, position: :below)
+    #   oc.start
+    #   oc.wait
+    #   oc.flush_to($stdout)
     def initialize(command:, lines: 3, position: :above, log_path: nil, stream: false, debug: nil)
       @command = command
       # Coerce lines into a positive Integer
@@ -63,30 +116,49 @@ module RubyProgress
     end
 
     # Start capturing the child process. Returns self.
+    #
+    # This spawns the configured command in a PTY and begins a background
+    # reader thread which buffers the most recent lines. When +stream+ is true
+    # the captured lines are redrawn into the terminal area reserved by
+    # {#reserve_space}.
     def start
-      reserve_space($stderr) if @stream
+      OutputUI.reserve_space($stderr, @position, @lines) if @stream
       @reader_thread = Thread.new { spawn_and_read }
       self
     end
 
+    # Signal the reader thread to stop and wait for it to finish.
+    # @return [void]
     def stop
       @stop = true
       @reader_thread&.join
     end
 
+    # Wait for the background reader thread to finish and return control to
+    # the caller. This is a simple join wrapper used by callers that need to
+    # block until the captured command completes.
+    #
+    # @return [Thread, nil] the joined thread or nil if not started
     def wait
       @reader_thread&.join
     end
 
+    # Return a snapshot of the currently buffered lines.
+    # @return [Array<String>]
     def lines
       @buf_mutex.synchronize { @buffer.dup }
     end
 
+    # Return true when the background reader thread is alive.
+    # @return [Boolean]
     def alive?
       @reader_thread&.alive? || false
     end
 
     # Redraw the reserved area using the current buffered lines.
+    #
+    # @param io [IO] the IO stream to draw into (defaults to $stderr)
+    # @return [void]
     def redraw(io = $stderr)
       buf = lines
       debug_log("redraw called; buffer=#{buf.size}; lines=#{@lines}; position=#{@position}")
@@ -154,6 +226,9 @@ module RubyProgress
     # Flush the buffered lines to the given IO (defaults to STDOUT).
     # This is used when capturing non-live output: capture silently during
     # the run and emit all captured output at the end.
+    #
+    # @param io [IO] the IO to write captured lines to (defaults to STDOUT)
+    # @return [void]
     def flush_to(io = $stdout)
       buf = lines
       return if buf.empty?
@@ -171,16 +246,35 @@ module RubyProgress
     private
 
     def spawn_and_read
-      PTY.spawn(@command) do |reader, _writer, pid|
+      # Run the command through the user's login shell so that shell aliases,
+      # functions, and PATH modifications are available.
+      shell = ENV['SHELL'] || '/bin/sh'
+      argv = ShellExec.build_shell_argv(shell, @command)
+
+      debug_log("spawning via shell=#{shell} argv=#{argv.inspect} raw_cmd=#{@command.inspect}")
+
+      PTY.spawn(shell, *argv) do |reader, _writer, pid|
         @child_pid = pid
         debug_log("spawned pid=#{pid} cmd=#{@command}")
 
         until reader.eof? || @stop
-          ready = if reader.respond_to?(:wait_readable)
-                    reader.wait_readable(0.1)
-                  else
-                    IO.select([reader], nil, nil, 0.1)
-                  end
+          # Prefer IO#wait_readable when available (avoids Fiber scheduler issues).
+          # If not available, attempt to use an underlying IO via #to_io, otherwise
+          # fall back to a short sleep to avoid calling deprecated/select APIs.
+          io = if reader.respond_to?(:wait_readable)
+                 reader
+               elsif reader.respond_to?(:to_io)
+                 reader.to_io
+               end
+
+          # Prefer IO#wait_readable when available (use safe navigation).
+          if io.respond_to?(:wait_readable)
+            ready = io.wait_readable(0.1)
+          else
+            # Best-effort fallback: sleep briefly and continue reading loop.
+            sleep 0.1
+            ready = true
+          end
           next unless ready
 
           chunk = reader.read_nonblock(4096, exception: false)
@@ -249,25 +343,6 @@ module RubyProgress
       end
     end
 
-    def reserve_space(io = $stderr)
-      return unless io.tty?
-
-      debug_log("reserve_space called; position=#{@position.inspect}; lines=#{@lines}")
-
-      if @position == :above
-        # Insert lines above current cursor using CSI n L
-        io.print "\e[#{@lines}L"
-        debug_log("reserve_space: inserted #{@lines} lines for :above")
-      else
-        # Print newlines then move cursor back up so animation stays above
-        io.print("\n" * @lines)
-        io.print "\e[#{@lines}A"
-        debug_log("reserve_space: printed #{@lines} newlines and moved up #{@lines} for :below")
-      end
-
-      io.flush
-    rescue StandardError => e
-      debug_log("reserve_space error: #{e.class}: #{e.message}")
-    end
+    # reserve_space moved to RubyProgress::OutputUI
   end
 end

data/lib/ruby-progress/ripple.rb

@@ -56,6 +56,11 @@ module RubyProgress
 
   # String extensions for color support
   module StringExtensions
+    # Extensions that add colorization helpers to String instances.
+    # Methods are dynamically defined from the COLORS map (e.g. #red, #green).
+    #
+    # Example:
+    #   "hello".red #=> "\e[31mhello\e[0m"
     COLORS.each do |color_name, color_code|
       define_method(color_name) do
         "#{color_code}#{self}#{COLORS['reset']}"
@@ -63,6 +68,11 @@ module RubyProgress
     end
 
     def rainbow(index = 0)
+      # Apply a per-character rainbow by cycling through the COLORS map.
+      #
+      # @param index [Integer] an optional offset to shift the colors
+      # @return [String] colorized string where each character is wrapped
+      #   in a terminal color escape sequence
       chars = self.chars
       colored_chars = chars.map.with_index do |char, idx|
         color = COLORS.values[(idx + index) % COLORS.size]
@@ -72,6 +82,11 @@ module RubyProgress
     end
 
     def normalize_type
+      # Attempt to guess a spinner indicator type from this string's
+      # characters. Returns a symbol matching one of INDICATORS keys or
+      # :classic as fallback.
+      #
+      # @return [Symbol]
       spinner_type = :classic
       INDICATORS.each do |spinner, _v|
         spinner_type = spinner if spinner =~ /^#{chars.join('.*?')}/i
@@ -82,9 +97,21 @@ module RubyProgress
 
   # Text ripple animation class
   class Ripple
+    # Public API:
+    # - instance: #advance, #printout
+    # - class: .progress (block-based helper), .complete
     attr_accessor :index, :string, :speed, :format, :inverse, :rainbow, :spinner, :spinner_position, :caps
 
     def initialize(string, options = {})
+      # Create a new Ripple animation for the given string.
+      #
+      # @param string [String] the text to animate
+      # @param options [Hash] configuration options (speed, format, rainbow, etc.)
+      # @option options [Symbol] :speed (:medium) animation speed :fast/:medium/:slow
+      # @option options [Symbol] :format (:bidirectional) :bidirectional/:forward_only
+      # @option options [Boolean] :rainbow (false) colorize characters individually
+      # @option options [Boolean] :spinner (false) use a spinner glyph instead of ripple
+      # @return [void]
       defaults = {
         speed: :medium,
         format: :bidirectional,
@@ -109,6 +136,10 @@ module RubyProgress
     end
 
     def printout
+      # Render a single frame of the ripple to stderr, preserving any
+      # reserved output area managed by OutputCapture.
+      #
+      # @return [void]
       letters = @string.dup.chars
       i = @index
       if @spinner
@@ -154,7 +185,19 @@ module RubyProgress
       RubyProgress::Utils.show_cursor
     end
 
+    # Show the cursor in the terminal. Delegates to Utils.
+    #
+    # @return [void]
+
     def self.complete(string, message, checkmark, success, icons: {})
+      # Display a final completion message for the ripple indicator.
+      #
+      # @param string [String] fallback message
+      # @param message [String,nil] explicit message to show
+      # @param checkmark [Boolean] whether to show a checkmark
+      # @param success [Boolean] whether the result is success
+      # @param icons [Hash] optional icons mapping
+      # @return [void]
       display_message = message || (checkmark ? string : nil)
       return unless display_message
 
@@ -197,6 +240,15 @@ module RubyProgress
     end
 
     def self.progress(string, options = {})
+      # Block-style helper which runs the ripple animation while the
+      # provided block executes. The cursor is hidden for the duration and
+      # restored afterwards. This method attempts to return a sensible
+      # value depending on the :output option (see code).
+      #
+      # @param string [String] the label text to animate
+      # @param options [Hash] configuration options forwarded to Ripple.new
+      # @yield the work to perform while the animation runs
+      # @return [Object,nil] returns block result or boolean depending on :output
       Signal.trap('INT') do
         Thread.current.kill
         nil

data/lib/ruby-progress/utils.rb

@@ -1,17 +1,37 @@
 # frozen_string_literal: true
 
 module RubyProgress
-  # Universal terminal utilities shared between progress indicators
+  # Universal terminal utilities shared between progress indicators.
+  #
+  # This module provides common functionality for terminal manipulation,
+  # cursor control, and output formatting used across all progress indicator types.
   module Utils
-    # Terminal cursor control
+    # Hides the terminal cursor.
+    #
+    # @return [void]
+    # @example
+    #   RubyProgress::Utils.hide_cursor
     def self.hide_cursor
       $stderr.print "\e[?25l"
     end
 
+    # Shows the terminal cursor.
+    #
+    # @return [void]
+    # @example
+    #   RubyProgress::Utils.show_cursor
     def self.show_cursor
       $stderr.print "\e[?25h"
     end
 
+    # Clears the current terminal line.
+    #
+    # @param output_stream [Symbol, IO] Stream to clear (:stdout, :stderr, or IO object)
+    # @return [void]
+    # @example Clear to stderr (default)
+    #   RubyProgress::Utils.clear_line
+    # @example Clear to stdout
+    #   RubyProgress::Utils.clear_line(:stdout)
     def self.clear_line(output_stream = :stderr)
       io = case output_stream
            when :stdout
@@ -26,18 +46,40 @@ module RubyProgress
       io.print "\r\e[K"
     end
 
-    # Enhanced line clearing for daemon mode that handles output interruption
+    # Enhanced line clearing for daemon mode that handles output interruption.
+    #
+    # Clears the current line and the line above it, useful when daemon
+    # output has been interrupted by other command output.
+    #
+    # @return [void]
+    # @example
+    #   RubyProgress::Utils.clear_line_aggressive
     def self.clear_line_aggressive
       $stderr.print "\r\e[2K"    # Clear entire current line
       $stderr.print "\e[1A\e[2K" # Move up one line and clear it too
       $stderr.print "\r"         # Return to start of line
     end
 
-    # Universal completion message display
+    # Displays a completion message with optional icons and formatting.
+    #
+    # Universal completion message display that handles success/error states,
+    # custom icons, and output stream selection.
+    #
     # @param message [String] The message to display
-    # @param success [Boolean] Whether this represents success or failure
+    # @param success [Boolean] Whether this represents success (true) or failure (false)
     # @param show_checkmark [Boolean] Whether to show checkmark/X symbols
-    # @param output_stream [Symbol] Where to output (:stdout, :stderr, :warn)
+    # @param output_stream [Symbol, IO] Where to output (:stdout, :stderr, :warn, or IO object)
+    # @param icons [Hash] Custom icons hash with :success and :error keys
+    # @option icons [String] :success Custom success icon (overrides default ✅)
+    # @option icons [String] :error Custom error icon (overrides default 🛑)
+    # @return [void]
+    # @example Basic success message
+    #   RubyProgress::Utils.display_completion("Done!", success: true, show_checkmark: true)
+    # @example With custom icons
+    #   RubyProgress::Utils.display_completion("Build complete",
+    #     success: true,
+    #     show_checkmark: true,
+    #     icons: { success: '🚀', error: '💥' })
     def self.display_completion(message, success: true, show_checkmark: false, output_stream: :warn, icons: {})
       return unless message
 
@@ -87,16 +129,42 @@ module RubyProgress
       end
     end
 
-    # Clear current line and display completion message
-    # Convenience method that combines line clearing with message display
+    # Clears the current line and displays a completion message.
+    #
+    # Convenience method that combines line clearing with message display.
+    # Note: When output_stream is :warn, line clearing is already included
+    # in display_completion.
+    #
+    # @param message [String] The message to display
+    # @param success [Boolean] Whether this represents success (true) or failure (false)
+    # @param show_checkmark [Boolean] Whether to show checkmark/X symbols
+    # @param output_stream [Symbol, IO] Where to output (:stdout, :stderr, :warn, or IO object)
+    # @param icons [Hash] Custom icons hash with :success and :error keys
+    # @return [void]
+    # @see display_completion
+    # @example
+    #   RubyProgress::Utils.complete_with_clear("Task complete", success: true, show_checkmark: true)
     def self.complete_with_clear(message, success: true, show_checkmark: false, output_stream: :warn, icons: {})
       clear_line(output_stream) if output_stream != :warn # warn already includes clear in display_completion
       display_completion(message, success: success, show_checkmark: show_checkmark, output_stream: output_stream, icons: icons)
     end
 
-    # Parse start/end characters for animation wrapping
-    # @param ends_string [String] Even-length string to split in half for start/end chars
+    # Parses start/end characters for animation wrapping.
+    #
+    # Takes an even-length string and splits it in half to create start
+    # and end decorative characters for progress indicators. Handles
+    # multi-byte characters correctly.
+    #
+    # @param ends_string [String, nil] Even-length string to split in half
     # @return [Array<String>] Array with [start_chars, end_chars]
+    # @example Basic decoration
+    #   RubyProgress::Utils.parse_ends("[]")  # => ["[", "]"]
+    # @example Multi-character decoration
+    #   RubyProgress::Utils.parse_ends("<<>>")  # => ["<<", ">>"]
+    # @example Emoji decoration
+    #   RubyProgress::Utils.parse_ends("🎯🎪")  # => ["🎯", "🎪"]
+    # @example Empty or nil input
+    #   RubyProgress::Utils.parse_ends(nil)  # => ["", ""]
     def self.parse_ends(ends_string)
       return ['', ''] unless ends_string && !ends_string.empty?
 
@@ -110,7 +178,20 @@ module RubyProgress
       [start_chars, end_chars]
     end
 
-    # Validate ends string: must be non-empty and even-length (handles multi-byte chars)
+    # Validates an ends string for proper format.
+    #
+    # Checks that the string is non-empty and has an even number of
+    # characters (handles multi-byte characters correctly).
+    #
+    # @param ends_string [String, nil] String to validate
+    # @return [Boolean] true if valid, false otherwise
+    # @example Valid strings
+    #   RubyProgress::Utils.ends_valid?("[]")  # => true
+    #   RubyProgress::Utils.ends_valid?("🎯🎪")  # => true
+    # @example Invalid strings
+    #   RubyProgress::Utils.ends_valid?("abc")  # => false (odd length)
+    #   RubyProgress::Utils.ends_valid?("")     # => false (empty)
+    #   RubyProgress::Utils.ends_valid?(nil)    # => false (nil)
     def self.ends_valid?(ends_string)
       return false unless ends_string && !ends_string.empty?
 

data/lib/ruby-progress/version.rb

@@ -2,11 +2,18 @@
 
 module RubyProgress
   # Main gem version
-  VERSION = '1.3.6'
+  # Main gem version
+  # @return [String]
+  VERSION = '1.3.7'
 
   # Component-specific versions (patch bumps)
+  # Component-specific versions (patch bumps)
+  # @return [String]
   WORM_VERSION = '1.1.6'
+  # @return [String]
   TWIRL_VERSION = '1.1.6'
+  # @return [String]
   RIPPLE_VERSION = '1.1.6'
+  # @return [String]
   FILL_VERSION = '1.0.6'
 end

data/lib/ruby-progress/worm.rb

@@ -9,6 +9,16 @@ require_relative 'cli/worm_runner'
 module RubyProgress
   # Animated progress indicator with ripple effect using Unicode combining characters
   class Worm
+    # Worm indicator renders a small ripple/wave of characters. Use this
+    # class directly to control a running indicator, or use the CLI helpers
+    # which wrap this behavior for daemonization and command execution.
+    #
+    # Public instance methods (selected): #generate_dots
+    # Public module mixins provide the main animation loop via WormRunner.
+    #
+    # @example
+    #   w = RubyProgress::Worm.new(length: 5, message: 'loading')
+    #   w.send(:generate_dots, 2, 1) # => "..o.."
     # Ripple effect styles
     RIPPLE_STYLES = {
       'circles' => {
@@ -56,6 +66,13 @@ module RubyProgress
     }.freeze
 
     def initialize(options = {})
+      # Create a new Worm indicator instance.
+      #
+      # @param options [Hash] configuration options
+      # @option options [Integer] :length number of characters in the ripple (default 3)
+      # @option options [String] :message optional label text
+      # @option options [String,Symbol] :style ripple style name or custom spec
+      # @return [void]
       @length = options[:length] || 3
       @message = options[:message]
       @speed = parse_speed(options[:speed] || 'medium')
@@ -154,7 +171,7 @@ module RubyProgress
         input_chars.all? do |char|
           idx = key_chars.index(char)
           if idx
-            key_chars = key_chars[idx + 1..-1] # Remove matched chars and continue
+            key_chars = key_chars[(idx + 1)..-1] # Remove matched chars and continue
             true
           else
             false
@@ -207,6 +224,11 @@ module RubyProgress
     # @output_capture&.redraw) will be overridden.
 
     def generate_dots(ripple_position, direction)
+      # Generate the string representing the ripple at a given position.
+      #
+      # @param ripple_position [Integer] index of the ripple peak
+      # @param direction [Integer] -1 for left-moving, +1 for right-moving
+      # @return [String] composed characters for current frame
       dots = Array.new(@length) { @style[:baseline] }
 
       # Apply ripple effect

data/project-page.md

@@ -0,0 +1,162 @@
+# Ruby Progress Indicators
+
+[![Gem Version](https://badge.fury.io/rb/ruby-progress.svg)](https://badge.fury.io/rb/ruby-progress)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.5.0-ruby.svg)](https://www.ruby-lang.org/)
+
+A collection of Ruby progress indicator projects: **Ripple**, **Worm**,
+**Twirl**, and **Fill**. All provide animated terminal progress indicators
+with different visual styles and features.
+
+## Quick Start
+
+Install the gem:
+
+{% iterm "gem install ruby-progress" %}
+
+Use the unified interface:
+
+{% iterm "prg worm --message 'Processing data' --style blocks --checkmark" %}
+
+{% iterm "prg ripple 'Loading...' --style rainbow --speed fast" %}
+
+{% iterm "prg twirl --message 'Working...' --style dots --speed fast" %}
+
+## Unified Interface
+
+The gem provides a unified `prg` command that supports all progress
+indicators through subcommands. Run commands with progress animation:
+
+{% iterm "prg worm --command 'sleep 5' --success 'Completed!' --error 'Failed!' --checkmark" %}
+
+{% iterm "prg ripple 'Building...' --command 'make build' --success 'Build complete!' --stdout" %}
+
+{% iterm "prg twirl --command 'npm install' --message 'Installing packages' --style arc" %}
+
+[See the README for more CLI examples](https://github.com/ttscoff/ruby-progress/blob/main/README.md#ripple-cli-examples)
+
+## Ripple
+
+Sophisticated text animation library that creates ripple effects across
+text strings in the terminal. Supports various animation modes including
+bidirectional movement and rainbow colors.
+
+**Key Features:**
+
+- Text ripple animations with customizable speed and direction
+- Style system supporting rainbow colors and inverse highlighting
+- Multiple animation formats: forward-only, bidirectional
+- Command execution with animated progress display
+
+Basic text animation:
+
+{% iterm "prg ripple 'Loading...'" %}
+
+With style options:
+
+{% iterm "prg ripple 'Processing Data' --speed fast --style rainbow --direction bidirectional" %}
+
+Run a command with progress animation:
+
+{% iterm "prg ripple 'Installing packages' --command 'sleep 5' --success 'Installation complete!' --checkmark" %}
+
+[See the README for more Ripple CLI examples](https://github.com/ttscoff/ruby-progress/blob/main/README.md#ripple-cli-examples)
+
+## Twirl
+
+Lightweight spinner animation system providing over 35 different spinner
+styles for terminal progress indication. Perfect for showing indefinite
+progress during command execution.
+
+**Key Features:**
+
+- 35+ spinner styles including dots, arrows, blocks, and geometric patterns
+- Flexible speed control (1-10 scale or named speeds)
+- Command execution with animated progress display
+- Daemon mode for background progress indication
+
+Basic spinner animation:
+
+{% iterm "prg twirl --message 'Processing...' --style dots" %}
+
+With command execution:
+
+{% iterm "prg twirl --command 'npm install' --message 'Installing' --style arc" %}
+
+Different spinner styles:
+
+{% iterm "prg twirl --message 'Working' --style arrows --speed fast" %}
+
+[See the README for more Twirl CLI examples](https://github.com/ttscoff/ruby-progress/blob/main/README.md#twirl-usage)
+
+## Worm
+
+Clean, Unicode-based progress indicator that creates a ripple effect using
+combining characters. Designed for running commands with visual progress
+feedback.
+
+**Key Features:**
+
+- Ripple wave animation using Unicode characters
+- Multiple visual styles (circles, blocks, geometric)
+- Configurable speed and customizable length
+- Command execution with progress indication
+- Custom styles with 3-character patterns
+
+Run indefinitely without a command:
+
+{% iterm "prg worm --message 'Loading...' --speed fast --style circles" %}
+
+Run a command with progress animation:
+
+{% iterm "prg worm --command 'sleep 5' --message 'Installing' --success 'Done!'" %}
+
+Custom animations with 3-character patterns:
+
+{% iterm "prg worm --message 'Custom style' --style 'custom=_-=' --command 'sleep 2'" %}
+
+{% iterm "prg worm --message 'Emoji worm!' --style 'custom=🟦🟨🟥' --success 'Complete!'" %}
+
+[See the README for more Worm CLI examples](https://github.com/ttscoff/ruby-progress/blob/main/README.md#worm-usage)
+
+## Background Mode
+
+All progress indicators support daemon mode for background tasks:
+
+Start a background indicator:
+
+{% iterm "prg worm --daemon-as mytask --message 'Background processing'" %}
+
+Stop it later with a message:
+
+{% iterm "prg job stop --daemon-name mytask --message 'Task complete!' --checkmark" %}
+
+[See the README for more background mode examples](https://github.com/ttscoff/ruby-progress/blob/main/README.md#example-background-mode-demo)
+
+## Installation
+
+As a gem (recommended):
+
+{% iterm "gem install ruby-progress" %}
+
+From source:
+
+{% iterm "git clone https://github.com/ttscoff/ruby-progress.git" %}
+
+{% iterm "cd ruby-progress" %}
+
+{% iterm "bundle install" %}
+
+{% iterm "bundle exec rake build" %}
+
+{% iterm "gem install pkg/ruby-progress-*.gem" %}
+
+[See the README for more installation options](https://github.com/ttscoff/ruby-progress/blob/main/README.md#installation)
+
+## Requirements
+
+- Ruby 2.7 or higher
+- Terminal with Unicode support (for Worm)
+- ANSI color support (for Ripple rainbow effects)
+
+[See the README for complete documentation](https://github.com/ttscoff/ruby-progress/blob/main/README.md)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-progress
 version: !ruby/object:Gem::Version
-  version: 1.3.6
+  version: 1.3.7
 platform: ruby
 authors:
 - Brett Terpstra
@@ -140,6 +140,7 @@ files:
 - lib/ruby-progress/utils.rb
 - lib/ruby-progress/version.rb
 - lib/ruby-progress/worm.rb
+- project-page.md
 - quick_demo.rb
 - readme_demo.rb
 - ruby-progress.gemspec