ruby-progress 1.3.5 → 1.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a22fcfc5ae8ffc222ac1f19f4d7b5295f9205c8ae95bce7ec8be8884e076f578
-  data.tar.gz: f96675ec9f6bcc1e6dd905763b45ea776bbf3f78f57629fc50a2cac4a13d22b2
+  metadata.gz: ed28989b5200a0ba018f976c1b7b90b8077916959633a5e2ea576de25bb6ddb5
+  data.tar.gz: f5c0ddea618bad931125e8f3195162e3cae7405c583fe27da5759d0febf30fa1
 SHA512:
-  metadata.gz: 4a61a58643c367f94645d5f3fded92473c44f72ee17553f47f89e27403780cbb3c7bb0fb3a3b36876be8928162434cd28aa847ef6e2ec488ec115c64f06bee2e
-  data.tar.gz: 9a7eda5a91f80ea1be162bb6bd250da3134f0567fa1c47f6c9e782f6aa80e16ed379e60da48a1ebd59f44dcb80a50cc92467ed9ec42be7196ceb973be66113fb
+  metadata.gz: 6722478a39177ac8c8618035abbd0b155afc275eb53120c7c89ff9f7a0c2194a02313efb5cf19ec59205d5f8002435edbef41c7cf5590f7e5f30ad00fa10f02d
+  data.tar.gz: 861feef40116e9c4a5f1c18e2455032a286c9c38fd7bccca19d24c1438b2554be90db4b5c820421b87301b4f21a3527a9bb17095c35140cf4ddddd0d8551539a

data/CHANGELOG.md

@@ -5,6 +5,32 @@ 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
+
+- **Interrupt handling**: Fixed Twirl and Worm CLIs to exit cleanly on Ctrl+C (SIGINT) without displaying backtraces
+  - Added top-level `trap('INT')` handlers to both `twirl_cli.rb` and `worm_cli.rb`
+  - Added `rescue Interrupt` clauses to Twirl runner methods for graceful cleanup
+  - All four progress indicators (Ripple, Worm, Twirl, Fill) now have consistent interrupt handling
+  - Properly clean up (show cursor, clear line) and exit with code 130 on interrupt
+
 ## [1.3.5] - 2025-10-15
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-progress (1.3.5)
+    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/blog-post.md

@@ -1,39 +1,154 @@
 ---
-title: "More CLI Progress Indicators: The ruby-progress Gem"
-date: 2025-10-10
+title: "Ruby Progress Indicators for Modern CLI Tools"
+date: 2025-10-15 11:00
 categories: [Ruby, CLI, Development Tools]
-tags: [ruby, cli, progress, animation, terminal]
+tags: [ruby, cli, progress, animation, terminal, daemon]
 ---
+I've been playing around with progress bars in the terminal, and I think I've
+created something genuinely useful.
 
-[ripple]: https://brettterpstra.com/2025/06/30/ripple-an-indeterminate-progress-indicator/
+Yes, I know there are multiple options
+already available for this, but I wanted something specific: a Ruby library that
+could be used for command-line scripting, with CLI executables that made it easy
+to use when scripting in *any* language --- not just Ruby.
 
-# More CLI Progress Indicators: The ruby-progress Gem
+The result is `ruby-progress`, a gem that provides four different animated
+progress indicators, each with its own visual style and use cases.
 
-The `ruby-progress` gem expands my previous work on [Ripple], adding 2 more indicator types and a new daemon mode to make it more useful in non-Ruby shell scripts.
+> If you're scripting in Ruby, I do highly recommend the TTY tools from [Piotr Murach](piotrmurach),
+such as [tty-progress](https://github.com/piotrmurach/tty-progressbar/). Piotr's
+TTY tools are much more elegant with a better Ruby API. `ruby-progress` is
+designed more for use in other shell scripts than it is for detailed Ruby
+scripting.
+{:.tip}
 
-## What is ruby-progress?
+{% gif /uploads/2025/10/ruby-progress.mp4 %}
 
-Ruby-progress provides animated progress indicators for command-line applications. Unlike traditional progress bars showing completion percentage, this gem focuses on continuous animations (indeterminate) that indicate activity - perfect for tasks with unpredictable completion times.
+## The Four Progress Indicators
 
-Three animation styles are available:
+Ripple
+: creates a wave-like effect across text, with the characters rippling
+through different visual states. It supports rainbow colors, inverse
+highlighting, and case transformations. Perfect for text-heavy operations where
+you want something more dynamic than a simple spinner.
 
-- **Ripple**: Wave-like effect across text
-- **Worm**: Moving dot pattern that crawls across the screen
-- **Twirl**: Classic spinning indicators with various symbols
+Worm
+: displays a moving dot pattern that crawls across the screen using
+Unicode characters. It includes multiple styles (circles, blocks, geometric
+shapes) and can move in any direction. Great for file operations, network
+transfers, or any continuous background task.
 
-## Quick Start
+Twirl
+: provides classic spinning indicators with over 35 different spinner
+styles --- from simple dots to complex geometric patterns. It's the most
+traditional of the four, but with way more visual variety than typical spinners.
+
+Fill : is the only determinate indicator in the bunch --- an actual progress bar
+that shows completion percentage. It can be controlled via command execution or
+updated programmatically through daemon control messages.
+
+## Installation and Quick Start
+
+Installation is straightforward:
 
 ```bash
-# Install
 gem install ruby-progress
+```
+
+All four indicators are available through a unified `prg` command:
 
+```bash
 # Basic usage
-ripple "Processing files..."
-worm --message "Loading..." --speed fast
-twirl --spinner dots
+prg ripple "Processing files..."
+prg worm --message "Loading..." --style blocks
+prg twirl --message "Working..." --style dots --speed fast
+prg fill --total 100 --report
+
+# With command execution
+prg ripple "Building..." --command "make build" --success "Build complete!" --checkmark
+```
+
+You can also use the individual commands directly: `ripple`, `worm`, `twirl`, and `fill`.
+
+## The Killer Feature: Daemon Mode
+
+Here's where things get interesting. All four indicators support daemon mode,
+which lets you run a progress indicator in the background while your scripts
+execute other commands. This is useful for complex workflows.
+
+```bash
+# Start a background spinner
+prg worm --daemon-as deployment --message "Deploying application..."
+
+# Execute your actual deployment steps
+git push production main
+kubectl apply -f manifests/
+./run-migrations.sh
+
+# Stop the spinner with a success message
+prg job stop --daemon-name deployment --message "Deployment complete!" --checkmark
+```
+
+The daemon mode uses `Process.fork` and `Process.detach`, so there are no shell
+job notifications cluttering your output. The progress indicator runs cleanly in
+the background, providing visual feedback without interfering with your script's
+execution.
+
+### Keeping Output Clean
+
+One of the challenges with daemon mode is preventing command output from
+disrupting the animation. By default, when you run a progress indicator in
+daemon mode, any STDOUT or STDERR output from commands executed in your script
+will appear on the terminal and potentially mess up the animation display.
+
+Ruby-progress handles this intelligently. When running in daemon mode, the
+animation continues on its dedicated line while your commands execute. However,
+if you want to see the output from those commands, you have options:
+
+```bash
+# Run command with animation, show output after completion
+prg ripple "Building..." --command "make build" --stdout
+
+# Stream output live while animation runs (reserves terminal rows)
+prg worm "Installing..." --command "npm install" --stdout-live --output-lines 5
+
+# Run daemon and manually capture output from your script commands
+prg worm --daemon-as build --message "Building..."
+make build > /tmp/build.log 2>&1
+prg job stop --daemon-name build --message "Build complete!" --checkmark
+cat /tmp/build.log
+```
+
+The `--stdout-live` flag is particularly useful --- it reserves a section of the
+terminal to display live command output while the animation continues above or
+below it. You control how many lines to reserve with `--output-lines` and where
+they appear with `--output-position` (above or below the animation).
+
+### Job Control Commands
+
+The `prg job` command provides subcommands for controlling background indicators:
+
+- `prg job stop` --- Stop a running daemon with an optional message
+- `prg job status` --- Check if a daemon is running and show its PID
+- `prg job advance` --- Update a fill progress bar by a specific amount
+
+```bash
+# Check if a daemon is running
+prg job status --daemon-name mytask
+
+# Advance a progress bar remotely
+prg fill --daemon-as progress --total 100
+prg job advance --daemon-name progress --amount 10
+
+# Stop with error state
+prg job stop --daemon-name mytask --message "Build failed!" --error
 ```
 
-## Ruby Integration
+{% paywall "Library and advanced usage" %}
+
+## Ruby Library Usage
+
+While the CLI is great for shell scripting, the Ruby API is just as elegant:
 
 ```ruby
 require 'ruby-progress'
@@ -44,131 +159,108 @@ RubyProgress::Ripple.progress("Processing files...") do
   upload_results
 end
 
-# Manual control
+# Manual control for complex scenarios
 worm = RubyProgress::Worm.new(
   message: "Custom task",
   style: 'blocks',
   speed: 'medium'
 )
 
-worm.animate { heavy_computation }
-```
+worm.animate do
+  heavy_computation
+  more_work
+end
 
-## Daemon Mode - The Killer Feature
+# Command execution with error handling
+RubyProgress::Twirl.new(
+  command: "bundle install",
+  message: "Installing gems...",
+  success: "Dependencies installed!",
+  error: "Installation failed",
+  checkmark: true
+).run_with_command
+```
 
-Run progress indicators in the background while your scripts execute:
+## Advanced Features Worth Knowing
 
-```bash
-# Start background indicator
-worm --daemon --pid-file /tmp/progress.pid --message "Deploying..."
+### Custom Styling and Icons
 
-# Run your actual work
-./deploy.sh
-kubectl apply -f manifests/
+All indicators support custom success and error icons:
 
-# Stop with success message
-worm --stop /tmp/progress.pid --message "Deploy complete!" --checkmark
+```bash
+prg ripple "Deploying..." \
+  --command "./deploy.sh" \
+  --success "All systems go!" \
+  --error "Houston, we have a problem" \
+  --success-icon "🚀" \
+  --error-icon "💥" \
+  --checkmark
 ```
 
-This is incredibly useful for complex deployment scripts where you want continuous visual feedback without interrupting the main process.
-
-There's a unified binary called `prg` that takes the three types as subcommands, e.g. `prg twirl --checkmark`. You can use any of them either way.
+### Visual Customization
 
-## Advanced Features
+Ripple supports rainbow colors and multiple composable styles:
 
-### Error Handling
-```ruby
-RubyProgress::Ripple.progress("Risky operation") do
-  might_fail_operation
-rescue StandardError => e
-  # Automatically stops and shows error state
-  puts "Failed: #{e.message}"
-end
+```bash
+prg ripple "Processing" --style rainbow,inverse,caps
 ```
 
-### Command Integration
-```ruby
-# Execute shell commands with progress
-RubyProgress::Worm.new(
-  command: "pg_dump mydb > backup.sql",
-  success: "Backup complete!",
-  error: "Backup failed"
-).run_with_command
-```
+Worm has directional control and custom character sets:
 
-### Visual Customization
-```ruby
-# Rainbow colors and custom styling
-RubyProgress::Ripple.progress("Colorful task",
-  rainbow: true,
-  speed: :fast,
-  format: :forward_only
-) do
-  process_with_style
-end
+```bash
+prg worm --direction rtl --style "custom=🟦🟨🟥"
 ```
 
-## Real-World Examples
+### Start/End Character Decoration
 
-### Deployment Script
+The `--ends` flag lets you wrap your progress indicator with decorative characters:
 
 ```bash
-#!/bin/bash
-worm --daemon-as deploy --message "Deploying..." &
+prg worm --message "Magic" --ends "🎯🎪" --style blocks
+prg ripple "Loading data" --ends "[]" --style rainbow
+```
 
-git push production main
-kubectl rollout status deployment/app
+### Output Capture
 
-worm --stop-id deploy --stop-success "Success!" --checkmark
-```
+When running commands, you can capture and display output:
 
-### Data Processing
-```ruby
-def import_large_csv(file)
-  RubyProgress::Ripple.progress("Importing #{File.basename(file)}...") do
-    CSV.foreach(file, headers: true) { |row| User.create!(row.to_h) }
-  end
-end
-```
+```bash
+# Show command output after completion
+prg ripple "Building..." --command "make build" --stdout
 
-### Rake Tasks
-```ruby
-task :backup do
-  RubyProgress::Worm.new(
-    command: "tar -czf backup.tar.gz app/",
-    success: "Backup created successfully!"
-  ).run_with_command
-end
+# Display live output with reserved terminal rows
+prg worm --command "npm install" --output-lines 5 --output-position above
 ```
+{% endpaywall %}
+
+## Real-World Use Cases
+
+**Deployment Scripts**: Show continuous progress during multi-step deployments
+without blocking command output.
+
+**Data Processing**: Provide visual feedback during long-running data imports or
+transformations.
 
-## Why ruby-progress?
+**Build Systems**: Integrate into Rake or Make tasks to show progress during compilation.
 
-- **Simple API**: Works in Ruby code and shell scripts
-- **Visual Appeal**: Engaging animations beyond basic spinners
-- **Unique Daemon Mode**: Background progress indicators
-- **Production Ready**: 84.55% test coverage, 113 test examples, zero failures
-- **Cross-Platform**: Linux, macOS, Windows support
-- **Reliable**: Comprehensive error handling and edge case coverage
+**CI/CD Pipelines**: Add visual indicators to pipeline scripts for better monitoring.
 
-## Installation & First Steps
+**System Administration**: Show progress during backups, database dumps, or file
+synchronization.
 
-1. **Install**: `gem install ruby-progress`
-2. **Test CLI**: `ripple "Hello World!"`
-3. **Try in Ruby**:
-   ```ruby
-   require 'ruby-progress'
-   RubyProgress::Ripple.progress("Testing...") { sleep 2 }
-   ```
+## Try It Out
 
-## Conclusion
+The easiest way to get started:
 
-Ruby-progress transforms boring CLI applications into engaging user experiences. Whether building deployment scripts, data processing tools, or utility commands, it provides the visual feedback users expect from modern command-line tools.
+{% iterm "gem install ruby-progress" %}
 
-The daemon mode alone makes it worth trying - no other progress library offers this level of flexibility for complex workflows.
+{% iterm "prg ripple 'Hello, World!'" %}
 
-**Links:**
-- [GitHub](https://github.com/ttscoff/ruby-progress)
-- [RubyGems](https://rubygems.org/gems/ruby-progress)
-- [Latest Release](https://github.com/ttscoff/ruby-progress/releases/latest)
+Or check out the [GitHub repository](https://github.com/ttscoff/ruby-progress)
+for full documentation, examples, and the complete API reference. The README
+includes detailed guides for each indicator type and advanced usage patterns.
 
-*Make your CLI tools feel alive with ruby-progress!*
+The gem is also available on
+[RubyGems](https://rubygems.org/gems/ruby-progress), and the latest release
+includes significant improvements to daemon mode handling and job control
+commands.

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,7 +7,22 @@ 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
+      exit
+    end
+
     options = TwirlCLI::Options.parse_cli_options
 
     if options[:status]
@@ -38,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
@@ -46,6 +52,11 @@ module TwirlRunner
 
       spinner_thread.kill
       RubyProgress::Utils.clear_line
+    rescue Interrupt
+      spinner_thread&.kill
+      RubyProgress::Utils.clear_line
+      RubyProgress::Utils.show_cursor
+      exit 130
     ensure
       RubyProgress::Utils.show_cursor
     end
@@ -67,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)
@@ -74,6 +89,10 @@ module TwirlRunner
     begin
       RubyProgress::Utils.hide_cursor
       loop { spinner.animate }
+    rescue Interrupt
+      RubyProgress::Utils.clear_line
+      RubyProgress::Utils.show_cursor
+      exit 130
     ensure
       RubyProgress::Utils.show_cursor
       if options[:success] || options[:checkmark]
@@ -87,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))
@@ -141,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,7 +33,16 @@ 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
+      exit
+    end
+
     options = WormCLI::Options.parse_cli_options
 
     if options[:status]
@@ -48,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,