ruby-progress 1.0.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df0ca84734879ec0824018482709764c6380d33e6c03036d442eb584d2bc079b
-  data.tar.gz: 284b601b3bfdb42512549f90af2a174226259dd305a707729988f807c13c59bf
+  metadata.gz: 49879f3480e89d03b3f7448dc582514f20e0637fc9e2c0252c9c0782eecbbd05
+  data.tar.gz: aa099474b01118ef950d1e9c4dd50059f0f0acf8d9bb8a256e72d9e9e257fc37
 SHA512:
-  metadata.gz: 946ec374e45b2048a4702b76108b5eec7c52ddbabcacf5744cfee7f131e1d730e414878afcdbf8296111e64a91419c3d7e20f38e4faa4c60426b8f014484a1f3
-  data.tar.gz: 6597651f4119954be581cbc10f1400832c1a3da2bc0bb5dfda446d5785c9f461ca19ed357012ffc60767a433dd0531b40e3c684d541403906b5007726742e597
+  metadata.gz: 3665c5d3f73d04d9fc890d4360165a177c4d26fd5bc01765dc49ab654c60b6a069b3364fbfc87e2226038d2af92c226dc1d89b739a98464dbdaf9d93b5903025
+  data.tar.gz: f4335241b770d265cd400eb535a6d65be9d0097d391524604ab7d84307ab5fccc49a8a2874acf9f51ac33f074f556fcfaa51a7c11e215045d08e3f873f7d09f1

data/.editorconfig

@@ -0,0 +1,14 @@
+# EditorConfig helps maintain consistent coding styles
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.md]
+# Keep Markdown tidy
+trim_trailing_whitespace = true
+# Avoid excessive vertical spacing while requiring clear blocks
+# (linting will enforce blanks around headings/lists)

data/.markdownlint.json

@@ -0,0 +1,9 @@
+{
+  "MD031": true,
+  "MD032": true,
+  "MD047": true,
+  "MD012": true,
+  "MD025": {
+    "front_matter_title": ""
+  }
+}

data/CHANGELOG.md

@@ -5,9 +5,61 @@ 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.1.2] - 2025-10-09
+
+### Fixed
+
+- **Critical gem execution issue**: Fixed installed gem binaries not executing due to `__FILE__ == $PROGRAM_NAME` check failing when paths differ between gem binary location and RubyGems wrapper script
+
+## [1.1.1] - 2025-10-09
+
+### Added
+
+- **New Twirl subcommand**: Extracted spinner functionality into dedicated `prg twirl` subcommand with 35+ spinner styles
+- **Enhanced daemon management**: Added `--daemon-as NAME` for named daemon instances creating `/tmp/ruby-progress/NAME.pid`
+- **Simplified daemon control**: Added `--stop-id NAME` and `--status-id NAME` for controlling named daemons
+- **Automatic flag implications**: `--stop-success`, `--stop-error`, and `--stop-id` now automatically imply `--stop`
+- **Global style listing**: Added `prg --list-styles` to show all available styles across all subcommands
+- **Unified style system**: Replaced ripple's `--rainbow` and `--inverse` flags with `--style` argument supporting `--style rainbow,inverse`
+- **Integrated case transformation**: Converted `--caps` flag to `--style caps` for consistent style system, supports combinations like `--style caps,inverse`
+
+### Changed
+
+- **Refactored CLI architecture**: Three-subcommand structure (ripple, worm, twirl) with consistent daemon management
+- **Improved option parsing**: Eliminated OptionParser ambiguities by using explicit `--stop-id`/`--status-id` instead of optional arguments
+- **Updated documentation**: Comprehensive README updates with new examples and cleaner daemon workflow syntax
+- **Enhanced gemspec**: Updated description from "Two different animated progress indicators" to "Animated progress indicators"
+
+### Deprecated
+
+- **Ripple style flags**: `--spinner`, `--rainbow`, `--inverse`, and `--caps` flags deprecated in favor of unified `--style` system (backward compatibility maintained)
+
+### Fixed
+
+- **OptionParser conflicts**: Resolved parsing issues with optional arguments that could consume following flags
+- **Daemon workflow**: Streamlined daemon start/stop workflow eliminating need for redundant flag combinations
+
 ## [1.0.1] - 2025-01-01
 
+## [1.1.0] - 2025-10-09
+
 ### Added
+
+- Shared daemon helpers module `RubyProgress::Daemon` for default PID file, control message file, status, and stop logic
+- Unified daemon flags across ripple and worm: `--daemon`, `--status`, `--stop`, `--pid-file`, `--stop-success`, `--stop-error`, `--stop-checkmark`
+- Ripple: daemon parity with worm, including clean shutdown on SIGUSR1/TERM/HUP/INT
+
+### Changed
+
+- `bin/prg` now delegates status/stop/default PID handling to `RubyProgress::Daemon`
+- README updated with new daemon usage examples and flag descriptions
+
+### Deprecated
+
+- `--stop-pid` remains available but is deprecated in favor of `--stop [--pid-file FILE]`
+
+### Added
+
 - Packaged as proper Ruby gem with library structure
 - Added RSpec test suite with comprehensive coverage
 - Added Rake tasks for version management and packaging
@@ -17,23 +69,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Enhanced command-line interface with consistent flag support across both tools**
 - **Added `RubyProgress::Utils` module with universal terminal control utilities**
 - **Centralized cursor control, line clearing, and completion message functionality**
+- **Added daemon mode for background progress indicators in bash scripts**
+- **Implemented signal-based control (SIGUSR1) for clean daemon shutdown**
 
 ### Changed
+
 - Moved classes into RubyProgress module
 - Separated logic into lib/ruby-progress/ structure
 - Created proper bin/ executables for ripple and worm
 - Updated README with gem installation and usage instructions
 
 ### Fixed
+
 - Fixed duplicate error messages in Worm error handling
 - Improved signal handling and cursor management
 
 ## [1.0.0] - 2025-10-09
 
 ### Added
+
 - Initial release with two progress indicators:
   - Ripple: Text ripple animation with 30+ spinner styles, rainbow effects, and command execution
   - Worm: Unicode wave animation with multiple styles and configurable options
 - Command-line interfaces for both tools
 - Support for custom speeds, messages, and styling options
-- Integration with system commands and process monitoring
+- Integration with system commands and process monitoring
+
+[1.1.1]: https://github.com/ttscoff/ruby-progress/releases/tag/v1.1.1
+[1.1.0]: https://github.com/ttscoff/ruby-progress/releases/tag/v1.1.0
+[1.0.1]: https://github.com/ttscoff/ruby-progress/releases/tag/v1.0.1
+[1.0.0]: https://github.com/ttscoff/ruby-progress/releases/tag/v1.0.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-progress (1.0.1)
+    ruby-progress (1.1.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -6,11 +6,11 @@
 [![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-55%25-yellow.svg)](#)
 
-This repository contains two different Ruby progress indicator projects: **Ripple** and **Worm**. Both provide animated terminal progress indicators with different visual styles and features.
+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.
 
 ## Unified Interface
 
-The gem provides a unified `prg` command that supports both progress indicators through subcommands:
+The gem provides a unified `prg` command that supports all progress indicators through subcommands:
 
 ```bash
 # Install the gem
@@ -19,45 +19,99 @@ gem install ruby-progress
 # Use worm-style animation
 prg worm --message "Processing data" --style blocks --checkmark
 
-# Use ripple-style animation  
-prg ripple "Loading..." --rainbow --speed fast
+# Use ripple-style animation
+prg ripple "Loading..." --style rainbow --speed fast
+
+# Use twirl spinner animation
+prg twirl --message "Working..." --style dots --speed fast
 
 # With command execution
 prg worm --command "sleep 5" --success "Completed!" --error "Failed!" --checkmark
 prg ripple "Building..." --command "make build" --success "Build complete!" --stdout
+prg twirl --command "npm install" --message "Installing packages" --style arc
 ```
 
 ### Global Options
+
 - `prg --help` - Show main help
 - `prg --version` - Show version info
+- `prg --list-styles` - Show all available styles for all subcommands
 - `prg <subcommand> --help` - Show specific subcommand help
 
 ### Common Options (available for both subcommands)
+
 - `--speed SPEED` - Animation speed (fast/medium/slow or f/m/s)
 - `--message MESSAGE` - Message to display
 - `--command COMMAND` - Command to execute during animation
 - `--success MESSAGE` - Success message after completion
 - `--error MESSAGE` - Error message on failure
-- `--checkmark` - Show checkmarks (✅ success, 🛑 failure)  
+- `--checkmark` - Show checkmarks (✅ success, 🛑 failure)
 - `--stdout` - Output command results to STDOUT
 
+### Daemon Mode (Background Progress)
+
+For shell scripts where you need a continuous progress indicator across multiple steps, use daemon mode. You can use named daemons or custom PID files.
+
+```bash
+# Start in background (uses default PID file)
+prg worm --daemon --message "Working..."
+
+# Start with a custom name (creates /tmp/ruby-progress/NAME.pid)
+prg worm --daemon-as mytask --message "Processing data..."
+
+# ... run your tasks ...
+
+# Stop with a success message and checkmark (--stop-success implies --stop)
+prg worm --stop-success "All done" --stop-checkmark
+
+# Stop a named daemon (--stop-id implies --stop)
+prg worm --stop-id mytask --stop-success "Task complete!" --stop-checkmark
+
+# Or stop with an error message and checkmark
+prg worm --stop-error "Failed during step" --stop-checkmark
+
+# Check status at any time
+prg worm --status
+prg worm --status-id mytask
+
+# Use a completely custom PID file path
+prg worm --daemon --pid-file /tmp/custom-progress.pid
+prg worm --status --pid-file /tmp/custom-progress.pid
+prg worm --stop-success "Complete" --pid-file /tmp/custom-progress.pid
+```
+
+Notes:
+
+- The CLI detaches itself (double-fork); do not append `&`. This prevents shell job notifications like “job … has ended.” The command returns immediately.
+- `--stop-success` and `--stop-error` are mutually exclusive; whichever you provide determines the success state and icon if `--stop-checkmark` is set.
+- The indicator clears its line on shutdown and prints the final message to STDOUT.
+- `--stop-pid` is still supported for backward compatibility, but `--stop [--pid-file FILE]` is preferred.
+
 ## Table of Contents
 
 - [Ruby Progress Indicators](#ruby-progress-indicators)
   - [Unified Interface](#unified-interface)
     - [Global Options](#global-options)
     - [Common Options (available for both subcommands)](#common-options-available-for-both-subcommands)
+    - [Daemon Mode (Background Progress)](#daemon-mode-background-progress)
+  - [Table of Contents](#table-of-contents)
   - [Ripple](#ripple)
     - [Ripple Features](#ripple-features)
     - [Ripple Usage](#ripple-usage)
-      - [Command Line](#command-line)
+      - [Ripple CLI examples](#ripple-cli-examples)
       - [Ripple Command Line Options](#ripple-command-line-options)
     - [Ripple Library Usage](#ripple-library-usage)
-    - [Available Spinners](#available-spinners)
+  - [Twirl](#twirl)
+    - [Twirl Features](#twirl-features)
+    - [Twirl Usage](#twirl-usage)
+      - [Command Line](#command-line)
+      - [Twirl Command Line Options](#twirl-command-line-options)
+    - [Available Spinner Styles](#available-spinner-styles)
   - [Worm](#worm)
     - [Worm Features](#worm-features)
     - [Worm Usage](#worm-usage)
       - [Command Line](#command-line-1)
+      - [Daemon mode (background indicator)](#daemon-mode-background-indicator)
       - [Worm Command Line Options](#worm-command-line-options)
     - [Worm Library Usage](#worm-library-usage)
     - [Animation Styles](#animation-styles)
@@ -66,6 +120,12 @@ prg ripple "Building..." --command "make build" --success "Build complete!" --st
       - [Geometric](#geometric)
   - [Requirements](#requirements)
   - [Installation](#installation)
+    - [As a Gem (Recommended)](#as-a-gem-recommended)
+    - [From Source](#from-source)
+    - [Development](#development)
+  - [Universal Utilities](#universal-utilities)
+    - [Terminal Control](#terminal-control)
+    - [Completion Messages](#completion-messages)
   - [Contributing](#contributing)
   - [License](#license)
 
@@ -73,50 +133,52 @@ prg ripple "Building..." --command "make build" --success "Build complete!" --st
 
 ## Ripple
 
-Ripple is a sophisticated text animation library that creates ripple effects across text strings in the terminal. It supports various animation modes including bidirectional movement, rainbow colors, spinners, and case transformations.
+Ripple is a sophisticated text animation library that creates ripple effects across text strings in the terminal. It supports various animation modes including bidirectional movement, and rainbow colors.
 
 ### Ripple Features
 
 - **Text ripple animations** with customizable speed and direction
-- **Rainbow color effects** that cycle through colors
-- **30+ built-in spinner styles** (dots, arrows, blocks, etc.)
+- **Style system** supporting rainbow colors and inverse highlighting
 - **Multiple animation formats**: forward-only, bidirectional
 - **Command execution** with animated progress display
 - **Custom success/failure messages** with optional checkmarks
 - **Case transformation modes** (uppercase/lowercase rippling)
-- **Inverse highlighting** for different visual effects
+- **Composable styles** using comma-separated values
 
 ### Ripple Usage
 
-#### Command Line
+#### Ripple CLI examples
 
 ```bash
 # Basic text animation
-./ripple "Loading..."
+prg ripple "Loading..."
 
-# With options
-./ripple "Processing Data" --speed fast --rainbow --direction bidirectional
+# With style options
+prg ripple "Processing Data" --speed fast --style rainbow --direction bidirectional
 
-# Run a command with progress animation
-./ripple "Installing packages" --command "sleep 5" --success "Installation complete!" --checkmark
+# Multiple styles combined
+prg ripple "Loading..." --style rainbow,inverse
+
+# Case transformation mode
+prg ripple "Processing Text" --style caps,inverse
 
-# Use a spinner instead of text ripple
-./ripple "Working" --spinner dots --spinner-pos before
+# Run a command with progress animation
+prg ripple "Installing packages" --command "sleep 5" --success "Installation complete!" --checkmark
 ```
 
 #### Ripple Command Line Options
 
-| Option                  | Description                                                   |
-| ----------------------- | ------------------------------------------------------------- |
-| `-s, --speed SPEED`     | Animation speed (1-10, fast/medium/slow, or f/m/s)            |
-| `-l, --length LENGTH`   | Number of dots to display                                     |
-| `-m, --message MESSAGE` | Message to display before animation                           |
-| `--style STYLE`         | Animation style (blocks/geometric/circles or b/g/c)           |
-| `-c, --command COMMAND` | Command to run (optional - runs indefinitely without command) |
-| `--success TEXT`        | Text to display on successful completion                      |
-| `--error TEXT`          | Text to display on error                                      |
-| `--checkmark`           | Show checkmarks (✅ for success, 🛑 for failure)                |
-| `--stdout`              | Output captured command result to STDOUT                      |
+| Option                  | Description                                                     |
+| ----------------------- | --------------------------------------------------------------- |
+| `-s, --speed SPEED`     | Animation speed (1-10, fast/medium/slow, or f/m/s)              |
+| `-d, --direction DIR`   | Animation direction (forward/bidirectional or f/b)              |
+| `-m, --message MESSAGE` | Message to display before animation                             |
+| `--style STYLES`        | Visual styles (rainbow, inverse, caps - can be comma-separated) |
+| `-c, --command COMMAND` | Command to run (optional - runs indefinitely without command)   |
+| `--success TEXT`        | Text to display on successful completion                        |
+| `--error TEXT`          | Text to display on error                                        |
+| `--checkmark`           | Show checkmarks (✅ for success, 🛑 for failure)                  |
+| `--stdout`              | Output captured command result to STDOUT                        |
 
 ### Ripple Library Usage
 
@@ -145,19 +207,80 @@ end
 RubyProgress::Ripple.show_cursor
 ```
 
-### Available Spinners
+---
+
+## Twirl
+
+Twirl is a lightweight spinner animation system providing over 35 different spinner styles for terminal progress indication. It's perfect for showing indefinite progress during command execution.
 
-Ripple includes 30+ different spinner styles:
+### Twirl Features
 
-- **Classic**: `|`, `/`, `—`, `\`
-- **Dots**: Various braille dot patterns (dots, dots_2, dots_3, etc.)
-- **Arrows**: Arrow patterns and pulsing arrows
-- **Blocks**: Block characters in different patterns
-- **Geometric**: Circles, triangles, arcs
-- **Progress bars**: Bounce, push, pulse effects
+- **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
+- **Custom success/failure messages** with optional checkmarks
+- **Signal handling** for graceful shutdown and status updates
+
+### Twirl Usage
+
+#### Command Line
+
+```bash
+# Basic spinner animation
+prg twirl --message "Processing..." --style dots
+
+# With command execution
+prg twirl --command "npm install" --message "Installing" --style arc
+
+# Different spinner styles
+prg twirl --message "Working" --style arrows --speed fast
+prg twirl --message "Loading" --style blocks --speed slow
+
+# With success/error handling
+prg twirl --command "make build" --success "Build complete!" --error "Build failed!" --checkmark
+
+# Daemon mode for background tasks
+prg twirl --daemon --message "Background processing" --style geometric
+prg twirl --daemon-as mytask --message "Named task" --style dots
+
+# ... do other work ...
+prg twirl --stop-success "Processing complete!"
+prg twirl --stop-id mytask --stop-success "Task finished!"
+```
+
+#### Twirl Command Line Options
+
+| Option                  | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `-s, --speed SPEED`     | Animation speed (1-10, fast/medium/slow, or f/m/s)            |
+| `-m, --message MESSAGE` | Message to display before spinner                             |
+| `--style STYLE`         | Spinner style (see --list-styles for all options)             |
+| `-c, --command COMMAND` | Command to run (optional - runs indefinitely without command) |
+| `--success TEXT`        | Text to display on successful completion                      |
+| `--error TEXT`          | Text to display on error                                      |
+| `--checkmark`           | Show checkmarks (✅ for success, 🛑 for failure)                |
+| `--stdout`              | Output captured command result to STDOUT                      |
+| `--daemon`              | Run in background daemon mode                                 |
+| `--daemon-as NAME`      | Run in daemon mode with custom name                           |
+| `--stop`                | Stop a running daemon                                         |
+| `--stop-id NAME`        | Stop daemon by name (implies --stop)                          |
+| `--status`              | Check daemon status                                           |
+| `--status-id NAME`      | Check daemon status by name                                   |
+
+### Available Spinner Styles
+
+Twirl includes over 35 different spinner animations:
+
+- **Dots**: `dots`, `dots_2`, `dots_3`, `dots_pulse`, `dots_scrolling`
+- **Arrows**: `arrow`, `arrow_pulse`, `arrows`, `arrows_2`
+- **Blocks**: `blocks`, `blocks_2`, `toggle`, `toggle_2`
+- **Lines**: `line`, `line_2`, `pipe`, `vertical_bar`
+- **Geometric**: `arc`, `circle`, `triangle`, `square_corners`
+- **Classic**: `classic`, `bounce`, `push`, `flip`
 - **And many more!**
 
-Use `./ripple --list-spinners` to see all available options.
+Use `prg --list-styles` to see all available spinner options.
 
 ---
 
@@ -202,6 +325,30 @@ Worm is a clean, Unicode-based progress indicator that creates a ripple effect u
 ./worm.rb --command "echo 'Build output'" --success "Build complete!" --checkmark --stdout
 ```
 
+#### Daemon mode (background indicator)
+
+Run the worm indicator as a background daemon and stop it later (useful in shell scripts):
+
+```bash
+# Start in the background (default PID file: /tmp/ruby-progress/progress.pid)
+prg worm --daemon
+
+# ... run your tasks ...
+
+# Stop using the default PID file
+prg worm --stop
+
+# Use a custom PID file
+prg worm --daemon --pid-file /tmp/custom-worm.pid
+
+# Stop using the matching custom PID file
+prg worm --stop --pid-file /tmp/custom-worm.pid
+```
+
+Stopping clears the progress line for clean output. You can also provide a success message and checkmark while stopping by sending SIGUSR1; the CLI handles cleanup automatically.
+
+Note: You don’t need `&` when starting the daemon. The command detaches itself and returns right away, which also avoids “job … has ended” messages from your shell.
+
 #### Worm Command Line Options
 
 | Option                  | Description                                         |
@@ -245,16 +392,19 @@ worm.run_with_command
 Worm supports three built-in animation styles:
 
 #### Circles
+
 - Baseline: `·` (middle dot)
 - Midline: `●` (black circle)
 - Peak: `⬤` (large circle)
 
 #### Blocks
+
 - Baseline: `▁` (lower eighth block)
 - Midline: `▄` (lower half block)
 - Peak: `█` (full block)
 
 #### Geometric
+
 - Baseline: `▪` (small black square)
 - Midline: `▫` (small white square)
 - Peak: `■` (large black square)
@@ -264,6 +414,7 @@ Worm supports three built-in animation styles:
 ## Requirements
 
 Both projects require:
+
 - Ruby 2.5 or higher
 - Terminal with Unicode support (for Worm)
 - ANSI color support (for Ripple rainbow effects)
@@ -280,6 +431,7 @@ gem install ruby-progress
 
 1. Clone this repository
 2. Build and install:
+
    ```bash
    bundle install
    bundle exec rake build
@@ -290,10 +442,13 @@ gem install ruby-progress
 
 1. Clone the repository
 2. Install dependencies:
+
    ```bash
    bundle install
    ```
+
 3. Run tests:
+
    ```bash
    bundle exec rspec
    ```
@@ -321,14 +476,14 @@ RubyProgress::Utils.display_completion("Task completed!")
 
 # With success/failure indication and checkmarks
 RubyProgress::Utils.display_completion(
-  "Build successful!", 
-  success: true, 
+  "Build successful!",
+  success: true,
   show_checkmark: true
 )
 
 RubyProgress::Utils.display_completion(
-  "Build failed!", 
-  success: false, 
+  "Build failed!",
+  success: false,
   show_checkmark: true,
   output_stream: :stdout  # :stdout, :stderr, or :warn (default)
 )
@@ -342,7 +497,7 @@ RubyProgress::Utils.complete_with_clear(
 )
 ```
 
-These utilities are used internally by both Ripple and Worm classes and are available for use in your own applications.
+These utilities are used internally by Ripple, Worm, and Twirl classes and are available for use in your own applications.
 
 ## Contributing
 
@@ -350,4 +505,4 @@ Feel free to submit issues and pull requests to improve either project!
 
 ## License
 
-Both projects are provided as-is for educational and practical use.
+Both projects are provided as-is for educational and practical use.