ruby-progress 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35418d5ca6c2be425e6727b2480ce99da3baaa768991fc1a1e92bbcb15b54d37
-  data.tar.gz: 439632bfced82834cdd7157e33a84c187821436fa6ca3f1854627ab092c682bc
+  metadata.gz: 7f08082d9cebd17f7d3ece436ff76e4f4beb8f934d803719a6bdc3477fa8c97b
+  data.tar.gz: da85e2d2e2587c13f4c778094fb1dcd8e2aa832dd0cff34b947b90db0f4e6585
 SHA512:
-  metadata.gz: 3def99d8f6d1bde28c3fc6a273fe0d8be65db3aabbd440a9bef8b165bd606e09872f8f216a73b186477cd4ef84f06bcfd728cd3a96eae23fdfc2114926827082
-  data.tar.gz: dda2ef12f24c66481e3280e23ba34932d7691edbdfa5ae503e3c1071a917158f126862df5b4b67ccb45b066523e0010b31298a4c6009dd296557cae190016367
+  metadata.gz: f3a816024fd6cc2aba00edd334c8b82e3783d6be3916bc36238172add46c695febcd80689ba49179b0d48a2175f983dca6b381e482c143e72f2bb0d80804b247
+  data.tar.gz: 56fe19077105ebf00cdae2c939eb761d0b37ae4f4cb82b439207c0562ed46cd97abd9105e7b6c0789868fa6087f5d646736b3ad0a58d3df6d09e5028add6d4bf

data/CHANGELOG.md

@@ -1,208 +1,133 @@
-# Changelog
+# CHANGELOG
 
 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.2.0] - 2025-10-11
+## 1.3.0 - 2025-10-12
 
 ### Added
 
-- **--ends flag for all commands**: New universal option to add start/end characters around animations
-  - Accepts even-length strings split in half for start and end characters
-  - Works across all three commands: ripple, worm, and twirl
-  - Examples: `--ends "[]"` → `[animation]`, `--ends "<<>>"` → `<<animation>>`
-  - Multi-byte character support for emojis: `--ends "🎯🎪"` → `🎯animation🎪`
-  - Graceful fallback for invalid input (odd-length strings)
+- PTY-based output capture: `RubyProgress::OutputCapture` now allows running commands under a PTY, keeps a rolling buffer of the last N lines for live redraw, and optionally writes the full streamed output to a `log_path` file.
+- File-based daemon job queue: `RubyProgress::Daemon.process_jobs` implements atomic job enqueue/claim/processing with `.processing.result` metadata files and processed-archive behavior.
+- `prg job send` CLI helper: atomically writes jobs to daemon job dirs and supports `--wait` to poll for results, `--daemon-name`, `--pid-file`, `--stdin`, and `--timeout`.
+- Integration of job processing into Ripple/Twirl/Worm daemon modes so a running daemon can accept and display job output without interrupting animations.
+- CLI options for output handling: `--output-position` and `--output-lines` to reserve terminal rows for captured output.
 
-- **Comprehensive test coverage for new features**: Added extensive test suites
-  - Direction control tests: Forward-only vs bidirectional animation behavior
-  - Custom style tests: ASCII, Unicode, emoji, and mixed character pattern validation
-  - CLI integration tests: End-to-end testing for all new command-line options
-  - Ends functionality tests: Multi-byte character handling, error cases, help documentation
-  - Total: 58 new test examples covering all edge cases
+### Changed
 
-- **Worm direction control**: Fine-grained animation movement control
-  - `--direction forward` (or `-d f`): Animation moves only forward, resets at end
-  - `--direction bidirectional` (or `-d b`): Default back-and-forth movement
-  - Compatible with all worm styles including custom patterns
+- Job result files now merge any Hash returned by the job handler into the `.processing.result` JSON (e.g., `exit_status`, `output`, `log_path`).
 
-- **Worm custom styles**: User-defined 3-character animation patterns
-  - Format: `--style custom=abc` where `abc` defines baseline, midline, peak characters
-  - ASCII support: `--style custom=_-=` → `___-=___`
-  - Unicode support: `--style custom=▫▪■` → geometric patterns
-  - Emoji support: `--style custom=🟦🟨🟥` → colorful animations
-  - Mixed characters: `--style custom=.🟡*` → combined ASCII and emoji
-  - Proper multi-byte character counting for accurate 3-character validation
+### Tests
 
-### Enhanced
+- Added unit and integration tests covering job enqueueing, processing, and result persistence.
 
-- **Centralized utility functions**: Moved common functionality to `RubyProgress::Utils`
-  - `Utils.parse_ends()`: Universal start/end character parsing
-  - Eliminates code duplication across animation classes
-  - Consistent behavior and error handling
+### Release notes
 
-- **Documentation improvements**: Updated README with comprehensive examples
-  - New common options section highlighting universal flags
-  - Detailed --ends usage examples with various character patterns
-  - Enhanced help output for all commands
+- Merge commit: 99d9c39 (squash-merge of feature/output-handling)
 
-### Technical
-
-- **Version management**: Bumped all component versions to reflect new features
-  - Main version: 1.1.9 → 1.2.0 (new feature addition)
-  - Worm version: 1.0.4 → 1.1.0 (direction control + custom styles)
-  - Ripple version: 1.0.5 → 1.1.0 (ends support)
-  - Twirl version: 1.0.1 → 1.1.0 (ends support)
+## 1.3.1 - 2025-10-12
 
-## [1.1.9] - 2025-10-10
+### Added
 
-### Fixed
+- `fill` subcommand: added `-c, --command COMMAND` so the determinate progress bar can run and capture command output like the other subcommands. This includes `--output-lines` and `--output-position` support for reserving terminal rows during capture.
 
-- **Worm animation line clearing**: Resolved issue where completion messages appeared alongside animation characters
-  - Fixed stream mismatch where animations used stderr but completion messages used stdout
-  - Implemented atomic operation combining line clearing and message output on stderr
-  - Ensured clean line clearing for all scenarios (success, error, no completion message)
-  - Updated tests to match new stderr-based completion message output
-  - Clean output format: animation disappears completely before completion message appears
+### Changed
 
-### Technical
+- Bumped `FILL_VERSION` (patch) to reflect the new CLI behavior.
 
-- **Stream consistency**: All worm animation output (including completion messages) now uses stderr consistently
-- **Enhanced completion message display**: Single atomic stderr operation prevents race conditions between line clearing and message display
 
-## [1.1.8] - 2025-10-10
+## 1.2.3 - 2025-10-11
 
 ### Added
 
-- **Intelligent fuzzy matching for twirl styles**: Enhanced twirl style selector with sophisticated pattern matching
-  - Exact matches: Direct style name matching (case-insensitive)
-  - Prefix matches: `ar` matches `arc` instead of `arrow` (shortest match priority)
-  - Character-by-character fuzzy matches: `cls` matches `classic` (sequential character matching)
-  - Substring fallback: Comprehensive matching for partial inputs
-  - Works dynamically against all available indicator styles in `RubyProgress::INDICATORS`
-
-### Improved
-
-- **Worm message spacing**: Enhanced visual formatting for worm animations
-  - Automatic space insertion between `--message` text and animation
-  - Clean formatting: `"Loading data ●··●·"` instead of `"Loading data●··●·"`
-  - No extra spacing when no message is provided
-  - Consistent behavior across all worm animation methods (standard, daemon, aggressive clearing)
-
-### Technical
-
-- **Enhanced test coverage**: Added comprehensive fuzzy matching test suite for twirl styles
-  - 13 test cases covering exact, prefix, fuzzy, and edge case scenarios
-  - Validation of shortest match priority and character-order matching
-  - Integration with existing comprehensive test coverage (maintained at 70.47%)
+- Dedicated `fill` shim: added `bin/fill` that delegates to `prg fill`.
 
-## [1.1.7] - 2025-10-10
+### Changed
 
-### Added
+- Version bumps: prg 1.2.2 → 1.2.3, fill 1.0.0 → 1.0.1
 
-- **Visual style previews**: Added `--show-styles` flag to all subcommands showing visual previews of animation styles
-  - Global `prg --show-styles` displays all styles for all subcommands with visual examples
-  - Subcommand-specific `prg <subcommand> --show-styles` shows only relevant styles
-  - Ripple styles show "Progress" text with actual color/effect rendering
-  - Worm styles display wave patterns like `··●⬤●··` for circles style
-  - Twirl styles show spinner character sequences like `◜ ◠ ◝ ◞ ◡ ◟` for arc style
-- **Process management**: Added `--stop-all` flag for comprehensive process control
-  - Global `prg --stop-all` stops all prg processes across all subcommands
-  - Subcommand-specific `prg <subcommand> --stop-all` stops only processes for that animation type
-  - Smart process detection excludes current process to prevent self-termination
-  - Graceful termination using TERM signal for proper cleanup
+## 1.2.2 - 2025-10-11
 
 ### Improved
 
-- **Error handling**: Replaced verbose Ruby stack traces with clean, user-friendly error messages
-  - Invalid command-line options now show simple "Invalid option: --flag-name" messages
-  - Each error includes appropriate usage information and help guidance
-  - Consistent error format across all subcommands (ripple, worm, twirl)
-- **Style discovery**: Enhanced distinction between `--list-styles` (simple name lists) and `--show-styles` (visual previews)
-- **Silent process management**: All `--stop` and `--stop-all` commands now operate silently
-  - No status messages or confirmation output for cleaner automation
-  - Exit code 0 when processes found and stopped successfully
-  - Exit code 1 when no processes found to stop
-- **Terminal output separation**: Moved all animations to stderr for proper stream handling
-  - Animations and progress indicators use stderr (status information)
-  - Application output remains on stdout (program data)
-  - Fixes daemon mode output interruption issues
-- **Enhanced process cleanup**: Improved daemon process termination reliability
-  - Uses TERM signal first for graceful shutdown, followed by KILL if needed
-  - Comprehensive process detection and cleanup across all subcommands
-  - Better handling of orphaned processes
-- **Version display**: Enhanced `--version` output to show individual subcommand versions
-  - Main version: `prg version 1.1.7`
-  - Component versions: `ripple (v1.0.5)`, `worm (v1.0.2)`, `twirl (v1.0.0)`
-  - Enables tracking of individual component changes
+- Demo script enhancements: updated quick demo with better visual examples.
 
 ### Technical
 
-- **Test coverage**: Significantly improved test coverage from ~60% to 74.53%
-  - Added comprehensive error handling tests
-  - Enhanced daemon lifecycle testing
-  - Improved edge case coverage for all animation types
-  - Added version constant validation tests
-
-## [1.1.4] - 2025-10-09
-
-### Fixed
+- Version alignment: synchronized demo script version display with actual gem version.
 
-- **Worm default message behavior**: Removed default "Processing" message from worm subcommand when no `--message` is provided for consistent behavior across all progress indicators
-- **Development environment**: Fixed `bin/prg` to use local library files instead of installed gem versions during development
+## 1.2.4 - 2025-10-12
 
-## [1.1.3] - 2025-10-09
+### Added
 
-### Fixed
+- Small bug fixes and test stability improvements:
+    - Ensured SimpleCov finalization runs reliably across Ruby versions during tests.
+    - Minor CLI help text clarifications and version constant alignment.
 
-- **Twirl spinner animation**: Fixed spinner freezing during command execution by ensuring continuous animation loop
-- **Default message behavior**: Removed default "Processing" message when no `--message` is provided - now shows only spinner
-- **Daemon termination output**: Removed verbose "Stop signal sent to process" message for cleaner daemon workflows
+### Changed
 
-## [1.1.2] - 2025-10-09
+- Bumped gem version and synchronized component version constants where applicable.
+    - Messages now display cleanly at the beginning of a new line
+    - Affects all three commands: ripple, worm, and twirl
+    - Resolves issue where completion messages appeared mid-line after animation ended
+    - Improved professional appearance of CLI output
 
-### Fixed
+Technical
 
-- **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
+- **Enhanced display_completion method**: Added proper line clearing and cursor positioning
+    - Uses `re[2K` sequence followed by clean message display
+    - Updated test expectations to match new output format
+    - Maintains backward compatibility with existing functionality
 
-## [1.1.1] - 2025-10-09
+## 1.2.0 - 2025-10-11
 
 ### 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
+- **--ends flag for all commands**: New universal option to add start/end characters around animations
+    - Accepts even-length strings split in half for start and end characters
+    - Works across all three commands: ripple, worm, and twirl
+    - Examples: `--ends "[]"` → `[animation]`, `--ends "<<>>"` → `<<animation>>`
+    - Multi-byte character support for emojis: `--ends "🎯🎪"` → `🎯animation🎪`
+    - Graceful fallback for invalid input (odd-length strings)
 
-- **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"
+- **Comprehensive test coverage for new features**: Added extensive test suites
+    - Direction control tests: Forward-only vs bidirectional animation behavior
+    - Custom style tests: ASCII, Unicode, emoji, and mixed character pattern validation
+    - CLI integration tests: End-to-end testing for all new command-line options
+    - Ends functionality tests: Multi-byte character handling, error cases, help documentation
+    - Total: 58 new test examples covering all edge cases
 
-### Deprecated
+- **Worm direction control**: Fine-grained animation movement control
+    - `--direction forward` (or `-d f`): Animation moves only forward, resets at end
+    - `--direction bidirectional` (or `-d b`): Default back-and-forth movement
+    - Compatible with all worm styles including custom patterns
 
-- **Ripple style flags**: `--spinner`, `--rainbow`, `--inverse`, and `--caps` flags deprecated in favor of unified `--style` system (backward compatibility maintained)
+- **Worm custom styles**: User-defined 3-character animation patterns
+    - Format: `--style custom=abc` where `abc` defines baseline, midline, peak characters
+    - ASCII support: `--style custom=_-=` → `___-=___`
+    - Unicode support: `--style custom=▫▪■` → geometric patterns
+    - Emoji support: `--style custom=🟦🟨🟥` → colorful animations
+    - Mixed characters: `--style custom=.🟡*` → combined ASCII and emoji
+    - Proper multi-byte character counting for accurate 3-character validation
+- **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.0.1 - 2025-01-01
 
-## [1.1.0] - 2025-10-09
+## 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`
+- 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
@@ -210,7 +135,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `bin/prg` now delegates status/stop/default PID handling to `RubyProgress::Daemon`
 - README updated with new daemon usage examples and flag descriptions
 
-### Deprecated
+Deprecated
 
 - `--stop-pid` remains available but is deprecated in favor of `--stop [--pid-file FILE]`
 
@@ -240,18 +165,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed duplicate error messages in Worm error handling
 - Improved signal handling and cursor management
 
-## [1.0.0] - 2025-10-09
+## 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
+    - 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
 
-[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/DEMO_SCRIPTS.md

@@ -0,0 +1,162 @@
+# Ruby Progress Gem - Demo Scripts
+
+This directory contains three demo scripts designed to showcase the ruby-progress gem's features for different purposes.
+
+## Demo Scripts Overview
+
+### 1. `demo_screencast.rb` - Full Feature Demo
+**Purpose**: Comprehensive screencast demonstration with narration pauses
+**Duration**: ~10-15 minutes
+**Best for**: Complete feature showcase, video recordings, presentations
+
+**Features demonstrated**:
+- All three commands (ripple, worm, twirl)
+- Built-in styles and variations
+- Universal --ends flag (NEW in v1.2.0)
+- Worm direction control (NEW in v1.2.0)
+- Custom worm styles (NEW in v1.2.0)
+- Error handling and success messages
+- Feature combinations
+
+**Usage**:
+```bash
+./demo_screencast.rb
+# or
+ruby demo_screencast.rb
+```
+
+### 2. `quick_demo.rb` - Essential Features
+**Purpose**: Quick demonstration of key features
+**Duration**: ~3-5 minutes
+**Best for**: Quick testing, feature highlights, social media clips
+
+**Features demonstrated**:
+- Universal --ends flag examples
+- Custom worm styles with emoji
+- Direction control
+- Error handling
+- Feature combinations
+
+**Usage**:
+```bash
+./quick_demo.rb
+# or
+ruby quick_demo.rb
+```
+
+### 3. `readme_demo.rb` - Documentation Examples
+**Purpose**: Clean examples perfect for README and documentation
+**Duration**: Variable (can run sections independently)
+**Best for**: Creating documentation examples, README updates, tutorials
+
+**Features demonstrated**:
+- Basic usage examples
+- Style variations
+- New v1.2.0 features
+- Advanced features
+
+**Usage**:
+```bash
+# Run all examples
+./readme_demo.rb
+
+# Run specific sections
+./readme_demo.rb basic      # Basic usage only
+./readme_demo.rb styles     # Style variations only
+./readme_demo.rb new        # New v1.2.0 features only
+./readme_demo.rb advanced   # Advanced features only
+```
+
+## Customization Tips
+
+### Adjusting Sleep Times
+All scripts use `--command 'sleep X'` to simulate work. You can adjust timing by modifying the sleep values:
+
+- **Ripple**: 3-4 seconds shows the expanding animation well
+- **Worm**: 4-6 seconds demonstrates the full progress bar cycle
+- **Twirl**: 2-3 seconds is sufficient for spinner animations
+
+### Adding Your Own Examples
+To add new examples, follow this pattern:
+
+```ruby
+def your_demo_method
+  puts "Description of what this demonstrates:"
+  run_cmd("command --option 'value' --command 'sleep X' --success 'Message!'")
+  puts "\n"
+end
+```
+
+### Modifying Pauses
+In `demo_screencast.rb`, you can adjust pause durations:
+
+```ruby
+pause_for_narration(seconds)    # For narration breaks
+pause_between_demos(seconds)    # Between demonstrations
+```
+
+## Example Commands Demonstrated
+
+### Universal --ends Flag
+```bash
+prg ripple 'Loading...' --ends '[]' --command 'sleep 3' --success 'Complete!'
+prg worm --length 10 --ends '<<>>' --command 'sleep 4' --success 'Finished!'
+prg twirl --ends '🎯🎪' --command 'sleep 2' --success 'Done!'
+```
+
+### Custom Worm Styles
+```bash
+prg worm --length 10 --style custom=_-= --command 'sleep 4' --success 'ASCII style!'
+prg worm --length 10 --style custom=▫▪■ --command 'sleep 4' --success 'Unicode blocks!'
+prg worm --length 10 --style custom=🟦🟨🟥 --command 'sleep 4' --success 'Emoji colors!'
+```
+
+### Direction Control
+```bash
+prg worm --length 10 --direction forward --command 'sleep 5' --success 'Forward only!'
+prg worm --length 10 --direction bidirectional --command 'sleep 5' --success 'Back and forth!'
+```
+
+### Feature Combinations
+```bash
+prg worm --length 10 --style custom=.🟡* --direction forward --ends '【】' --command 'sleep 4' --success 'All features!'
+```
+
+## Recording Tips
+
+### For Screencasts
+1. Use `demo_screencast.rb` for full feature coverage
+2. Terminal window should be at least 80 characters wide
+3. Consider using a terminal recorder like `asciinema`
+4. The script includes natural pause points for narration
+
+### For Quick Demos
+1. Use `quick_demo.rb` for fast demonstrations
+2. Perfect for social media clips or quick feature highlights
+3. Focuses on the most visually impressive features
+
+### For Documentation
+1. Use `readme_demo.rb` to generate clean command-line examples
+2. Output can be copied directly into documentation
+3. Sectioned approach allows focused demonstrations
+
+## Troubleshooting
+
+### Common Issues
+- **"Please provide text to animate"**: Some commands require a message argument
+- **"Invalid option"**: Check option names (some flags changed between versions)
+- **Animation not visible**: Ensure terminal supports the characters being used
+
+### Solutions
+- Always include a message for ripple: `prg ripple 'Loading...'`
+- Check `prg --help` for current option names
+- Test with basic ASCII characters first, then add Unicode/emoji
+
+## Script Dependencies
+
+All scripts require:
+- Ruby (tested with Ruby 3.4.4)
+- The ruby-progress gem (installed locally or via `gem install ruby-progress`)
+- Terminal with Unicode support (for emoji examples)
+
+The scripts automatically detect the gem location and use the local development version if run from the gem directory.

data/Gemfile.lock

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