ruby-progress 1.2.0 → 1.3.1

data/README.md

@@ -8,6 +8,27 @@
 
 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.
 
+## Table of Contents
+
+- [Unified Interface](#unified-interface)
+  - [Submitting jobs to a running daemon](#submitting-jobs-to-a-running-daemon)
+- [Job result schema](#job-result-schema)
+- [Example: start a daemon and send a job (simple)](#example-start-a-daemon-and-send-a-job-simple)
+- [Ripple](#ripple)
+  - [Ripple Features](#ripple-features)
+  - [Ripple Usage](#ripple-usage)
+- [Twirl](#twirl)
+- [Worm](#worm)
+  - [Daemon mode (background indicator)](#daemon-mode-background-indicator)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Universal Utilities](#universal-utilities)
+  - [Terminal Control](#terminal-control)
+  - [Completion Messages](#completion-messages)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Unified Interface
 
 The gem provides a unified `prg` command that supports all progress indicators through subcommands:
@@ -25,119 +46,97 @@ prg ripple "Loading..." --style rainbow --speed fast
 # Use twirl spinner animation
 prg twirl --message "Working..." --style dots --speed fast
 
-# With command execution
+# Dedicated `fill` shim
+# If you prefer a dedicated binary for the determinate progress bar, a thin `fill` shim is available that delegates to `prg fill`:
+
+# Run fill directly (delegates to prg)
+fill --report --percent 50
+
+### 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
+prg fill --command "sleep 5" --success "Done!" --checkmark
 
-# With start/end character decoration using --ends
+### With start/end character decoration using --ends
 prg ripple "Loading data" --ends "[]" --style rainbow
 prg worm --message "Processing" --ends "()" --style blocks
 prg twirl --message "Building" --ends "<<>>" --style dots
 
-# Complex --ends patterns with emojis
+### Complex --ends patterns with emojis
 prg worm --message "Magic" --ends "🎯🎪" --style "custom=🟦🟨🟥"
 ```
 
 ### 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 all subcommands)
+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.
 
-- `--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)
-- `--stdout` - Output command results to STDOUT
-- `--ends CHARS` - Start/end characters (even number of chars, split in half)
+### Submitting jobs to a running daemon
 
-### Daemon Mode (Background Progress)
+When running a long-lived daemon (for example `prg worm --daemon`), you can submit additional commands to run and have their output displayed without disrupting the animation using the `prg job send` helper.
 
-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.
+Basic usage:
 
 ```bash
-# Start in background (uses default PID file)
-prg worm --daemon --message "Working..."
+# Enqueue a command to the default daemon PID
+prg job send --command "./deploy-step.sh"
 
-# Start with a custom name (creates /tmp/ruby-progress/NAME.pid)
-prg worm --daemon-as mytask --message "Processing data..."
+# Enqueue to a named daemon (creates /tmp/ruby-progress/<name>.pid)
+prg job send --daemon-name mytask --command "rsync -av ./dist/ user@host:/srv/app"
 
-# ... run your tasks ...
+# Read command from stdin (useful in scripts)
+echo "bundle exec rake db:migrate" | prg job send --stdin --daemon-name mytask
 
-# Stop with a success message and checkmark (--stop-success implies --stop)
-prg worm --stop-success "All done" --stop-checkmark
+# Wait for the job result and print the job result JSON (default timeout 10s)
+prg job send --daemon-name mytask --command "./deploy-step.sh" --wait --timeout 30
+```
 
-# Stop a named daemon (--stop-id implies --stop)
-prg worm --stop-id mytask --stop-success "Task complete!" --stop-checkmark
+Behavior and file layout:
 
-# Or stop with an error message and checkmark
-prg worm --stop-error "Failed during step" --stop-checkmark
+- Jobs are written as JSON files into the daemon's job directory, which is derived from the daemon PID file. For example, a PID file `/tmp/ruby-progress/mytask.pid` maps to the job directory `/tmp/ruby-progress/mytask.jobs`.
+- The CLI writes the job atomically by first writing a `*.json.tmp` temporary file and then renaming it to `*.json`.
+- The daemon's job processor claims jobs atomically by renaming the job file to `*.processing`, writes a `*.processing.result` JSON file when finished, and moves processed jobs to `processed-*`.
 
-# Check status at any time
-prg worm --status
-prg worm --status-id mytask
+This mechanism allows you to submit many commands to a single running indicator and have their output shown in reserved terminal rows while the animation continues.
 
-# 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
-```
+## Job result schema
 
-Notes:
+When a job is processed the daemon writes a small JSON result file next to the claimed job with the suffix `.processing.result` containing at least these keys:
 
-- 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.
+- `id` - the job id (string)
+- `status` - `"done"` or `"error"`
+- `time` - epoch seconds when the job finished (integer)
 
-## Table of Contents
+Depending on the job handler, additional keys may be present:
+
+- `exit_status` - the numeric process exit status (integer or nil if unknown)
+- `output` - a string with the last captured lines of output (if available)
+- `error` - an error message when `status` is `error`
+
+Example:
 
-- [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)
-      - [Ripple CLI examples](#ripple-cli-examples)
-      - [Ripple Command Line Options](#ripple-command-line-options)
-    - [Ripple Library Usage](#ripple-library-usage)
-  - [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)
-      - [Circles](#circles)
-      - [Blocks](#blocks)
-      - [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)
+```json
+{
+  "id": "8a1f6c1e-4b7a-4f2c-b0a8-9e9f1c2f1a2b",
+  "status": "done",
+  "time": 1634044800,
+  "exit_status": 0,
+  "output": "Step 1 completed\nStep 2 completed"
+}
+```
+
+This file is intended for short messages and small captured output snippets (the CLI captures the last N lines). If you need larger logs, write them to a persistent file from the command itself and include a reference in the job metadata.
 
+## Example: start a daemon and send a job (simple)
+
+Below is an example script that demonstrates starting a worm daemon, sending a job, waiting for the result, and stopping the daemon.
 ---
 
 ## Ripple
@@ -159,19 +158,19 @@ Ripple is a sophisticated text animation library that creates ripple effects acr
 #### Ripple CLI examples
 
 ```bash
-# Basic text animation
+### Basic text animation
 prg ripple "Loading..."
 
-# With style options
+### With style options
 prg ripple "Processing Data" --speed fast --style rainbow --direction bidirectional
 
-# Multiple styles combined
+### Multiple styles combined
 prg ripple "Loading..." --style rainbow,inverse
 
-# Case transformation mode
+### Case transformation mode
 prg ripple "Processing Text" --style caps,inverse
 
-# Run a command with progress animation
+### Run a command with progress animation
 prg ripple "Installing packages" --command "sleep 5" --success "Installation complete!" --checkmark
 ```
 
@@ -196,12 +195,12 @@ You can also use Ripple as a Ruby library:
 ```ruby
 require 'ruby-progress'
 
-# Simple progress block
+### Simple progress block
 result = RubyProgress::Ripple.progress("Processing...") do
   sleep 5  # Your actual work here
 end
 
-# With options
+### With options
 rippler = RubyProgress::Ripple.new("Loading Data", {
   speed: :fast,
   format: :bidirectional,
@@ -236,24 +235,24 @@ Twirl is a lightweight spinner animation system providing over 35 different spin
 #### Command Line
 
 ```bash
-# Basic spinner animation
+### Basic spinner animation
 prg twirl --message "Processing..." --style dots
 
-# With command execution
+### With command execution
 prg twirl --command "npm install" --message "Installing" --style arc
 
-# Different spinner styles
+### Different spinner styles
 prg twirl --message "Working" --style arrows --speed fast
 prg twirl --message "Loading" --style blocks --speed slow
 
-# With success/error handling
+### With success/error handling
 prg twirl --command "make build" --success "Build complete!" --error "Build failed!" --checkmark
 
-# Daemon mode for background tasks
+### 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 ...
+### ... do other work ...
 prg twirl --stop-success "Processing complete!"
 prg twirl --stop-id mytask --stop-success "Task finished!"
 ```
@@ -312,39 +311,48 @@ Worm is a clean, Unicode-based progress indicator that creates a ripple effect u
 #### Command Line
 
 ```bash
-# Run indefinitely without a command (like ripple)
+### Run indefinitely without a command (like ripple)
 prg worm --message "Loading..." --speed fast --style circles
 
-# Run a command with progress animation
+### Run a command with progress animation
 prg worm --command "sleep 5" --message "Installing" --success "Done!"
 
-# Customize the animation
+### Customize the animation
 prg worm --command "make build" --speed fast --length 5 --style blocks
 
-# With custom error handling
+### With custom error handling
 prg worm --command "risky_operation" --error "Operation failed" --style geometric
 
-# With checkmarks for visual feedback
+### With checkmarks for visual feedback
 prg worm --command "npm install" --success "Installation complete!" --checkmark
 
-# Control animation direction (forward-only or bidirectional)
+### Control animation direction (forward-only or bidirectional)
 prg worm --message "Processing" --direction forward --style circles
 prg worm --command "sleep 3" --direction bidirectional --style blocks
 
-# Create custom animations with 3-character patterns
+### Create custom animations with 3-character patterns
 prg worm --message "Custom style" --style "custom=_-=" --command "sleep 2"
 prg worm --message "Emoji worm!" --style "custom=🟦🟨🟥" --success "Complete!"
 prg worm --message "Mixed chars" --style "custom=.🟡*" --direction forward
 
-# Add start/end characters around the animation
+### Add start/end characters around the animation
 prg worm --message "Bracketed" --ends "[]" --style circles
 prg worm --message "Parentheses" --ends "()" --style blocks --direction forward
 prg worm --message "Emoji ends" --ends "🎯🎪" --style "custom=🟦🟨🟥"
 
-# Capture and display command output
+### Capture and display command output
 prg worm --command "git status" --message "Checking status" --stdout
 
-# Combine checkmarks and stdout output
+You can reserve terminal rows for captured command output so the animation doesn't interleave with the script output. Use:
+
+- `--output-position POSITION` — `above` (default) or `below` the animation
+- `--output-lines N` — how many terminal rows to reserve for captured output (default: 3)
+
+Examples:
+
+prg worm --command "git status" --stdout --output-position above --output-lines 4
+
+### Combine checkmarks and stdout output
 prg worm --command "echo 'Build output'" --success "Build complete!" --checkmark --stdout
 ```
 
@@ -353,18 +361,18 @@ prg worm --command "echo 'Build output'" --success "Build complete!" --checkmark
 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)
+### Start in the background (default PID file: /tmp/ruby-progress/progress.pid)
 prg worm --daemon
 
-# ... run your tasks ...
+### ... run your tasks ...
 
-# Stop using the default PID file
+### Stop using the default PID file
 prg worm --stop
 
-# Use a custom PID file
+### Use a custom PID file
 prg worm --daemon --pid-file /tmp/custom-worm.pid
 
-# Stop using the matching custom PID file
+### Stop using the matching custom PID file
 prg worm --stop --pid-file /tmp/custom-worm.pid
 ```
 
@@ -399,7 +407,7 @@ Note: You don’t need `&` when starting the daemon. The command detaches itself
 ```ruby
 require 'ruby-progress'
 
-# Create and run animation with a block
+### Create and run animation with a block
 worm = RubyProgress::Worm.new(
   length: 4,
   message: "Processing",
@@ -416,7 +424,7 @@ result = worm.animate(
   some_long_running_task
 end
 
-# With custom style and forward direction
+### With custom style and forward direction
 worm = RubyProgress::Worm.new(
   message: "Custom animation",
   style: 'custom=🔴🟡🟢',
@@ -425,7 +433,7 @@ worm = RubyProgress::Worm.new(
 
 result = worm.animate { sleep 3 }
 
-# Or run with a command
+### Or run with a command
 worm = RubyProgress::Worm.new(command: "bundle install")
 worm.run_with_command
 ```
@@ -457,16 +465,16 @@ Worm supports three built-in animation styles plus custom patterns:
 Create your own animation patterns using the `custom=XXX` format, where `XXX` is a 3-character pattern representing baseline, midline, and peak states:
 
 ```bash
-# ASCII characters
+### ASCII characters
 prg worm --style "custom=_-=" --message "Custom ASCII"
 
-# Unicode characters
+### Unicode characters
 prg worm --style "custom=▫▪■" --message "Custom geometric"
 
-# Emojis (supports multi-byte characters)
+### Emojis (supports multi-byte characters)
 prg worm --style "custom=🟦🟨🟥" --message "Color progression"
 
-# Mixed ASCII and emoji
+### Mixed ASCII and emoji
 prg worm --style "custom=.🟡*" --message "Mixed characters"
 ```
 
@@ -538,7 +546,7 @@ The gem provides universal utilities in the `RubyProgress::Utils` module for com
 ```ruby
 require 'ruby-progress'
 
-# Cursor control
+### Cursor control
 RubyProgress::Utils.hide_cursor    # Hide terminal cursor
 RubyProgress::Utils.show_cursor    # Show terminal cursor
 RubyProgress::Utils.clear_line     # Clear current line
@@ -547,10 +555,10 @@ RubyProgress::Utils.clear_line     # Clear current line
 ### Completion Messages
 
 ```ruby
-# Basic completion message
+### Basic completion message
 RubyProgress::Utils.display_completion("Task completed!")
 
-# With success/failure indication and checkmarks
+### With success/failure indication and checkmarks
 RubyProgress::Utils.display_completion(
   "Build successful!",
   success: true,
@@ -564,7 +572,7 @@ RubyProgress::Utils.display_completion(
   output_stream: :stdout  # :stdout, :stderr, or :warn (default)
 )
 
-# Clear line and display completion (useful for replacing progress indicators)
+### Clear line and display completion (useful for replacing progress indicators)
 RubyProgress::Utils.complete_with_clear(
   "Processing complete!",
   success: true,

data/Rakefile

@@ -7,6 +7,13 @@ require 'rubocop/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
+# Convenience aliases
+# `rake test` -> runs the :spec task (RSpec)
+task test: :spec
+
+# Provide a `rake lint` alias that runs RuboCop (which defines the :rubocop task)
+task lint: :rubocop
+
 task default: [:spec]
 
 # Used by markdown tasks

data/bin/fill

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Thin shim to delegate to the unified prg CLI
+prg = File.expand_path(File.join(__dir__, 'prg'))
+if File.executable?(prg)
+  exec prg, 'fill', *ARGV
+else
+  exec 'prg', 'fill', *ARGV
+end