ruby-progress 1.3.1 → 1.3.4

data/demo_screencast.rb

@@ -13,6 +13,8 @@
 # and clear visual separation of different features.
 
 require 'io/console'
+require 'shellwords'
+require 'tmpdir'
 
 # Demo runner that exercises the major features of the ruby-progress gem
 # used by the documentation and screencast recordings.
@@ -26,6 +28,11 @@ class ProgressDemo
       header: "\e[1;36m",    # Bright cyan
       command: "\e[1;33m",   # Bright yellow
       description: "\e[0;32m", # Green
+      exec: "\e[1;33m",      # executable (bright yellow)
+      tool: "\e[1;35m",      # prg/tool (bright magenta)
+      flag: "\e[1;36m",      # flags (bright cyan)
+      value: "\e[1;37m",     # flag values (bright white)
+      prompt: "\e[2m",       # prompt (dim)
       reset: "\e[0m",        # Reset
       dim: "\e[2m"           # Dim
     }
@@ -33,12 +40,13 @@ class ProgressDemo
 
   def run
     clear_screen
-    show_title
+
+    # show_title
 
     # Introduction
-    show_section_header('Ruby Progress Gem Demo')
-    show_description('Demonstrating terminal progress indicators with style!')
-    pause_for_narration(3)
+    # show_section_header('Ruby Progress Gem Demo')
+    # show_description('Demonstrating terminal progress indicators with style!')
+    # pause_for_narration(3)
 
     # Basic examples for each command
     demo_basic_commands
@@ -63,17 +71,17 @@ class ProgressDemo
 
     # Ripple - basic expanding circle animation
     show_demo_header('Ripple', 'Expanding circle animation for tasks with unknown duration')
-    run_command("#{ruby_cmd} ripple --command 'sleep 4' --success 'Download complete!' --checkmark")
+    run_command("#{ruby_cmd} ripple --command 'sleep 2' --success 'Download complete!' --checkmark PROCESSING")
     pause_between_demos
 
     # Worm - progress bar animation
     show_demo_header('Worm', 'Animated progress bar for visual feedback')
-    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 5' --success 'Processing finished!' --checkmark")
+    run_command("#{ruby_cmd} worm --length 4 --command 'sleep 5' --success 'Processing finished!' --checkmark --message 'Loading'")
     pause_between_demos
 
     # Twirl - spinning indicator
     show_demo_header('Twirl', 'Classic spinning indicator for quick tasks')
-    run_command("#{ruby_cmd} twirl --command 'sleep 3' --success 'Task completed!' --checkmark")
+    run_command("#{ruby_cmd} twirl --command 'sleep 2' --success 'Task completed!' --checkmark")
     pause_between_demos
   end
 
@@ -83,39 +91,35 @@ class ProgressDemo
     # Ripple styles
     show_demo_header('Ripple Styles', 'Different visual patterns')
     show_command_info('Default ripple style')
-    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Default style'")
-    pause_between_demos(2)
-
-    show_command_info('Pulse style')
-    run_command("#{ruby_cmd} ripple --style pulse --command 'sleep 3' --success 'Pulse style'")
+    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Default style' 'Rippling Progress Default Style'")
     pause_between_demos
 
+    # show_command_info('Pulse style')
+    # run_command("#{ruby_cmd} ripple --style pulse --command 'sleep 3' --success 'Pulse style' 'Rippling Progress'")
+    # pause_between_demos
+
     # Worm styles
     show_demo_header('Worm Styles', 'Various progress bar animations')
     show_command_info('Classic worm style')
-    run_command("#{ruby_cmd} worm --length 10 --style classic --command 'sleep 4' --success 'Classic worm'")
-    pause_between_demos(2)
-
-    show_command_info('Emoji worm style')
-    run_command("#{ruby_cmd} worm --length 10 --style emoji --command 'sleep 4' --success 'Emoji worm! 🎉'")
-    pause_between_demos(2)
+    run_command("#{ruby_cmd} worm --length 10 --style classic --command 'sleep 4' --success 'Classic worm' --message 'Classic'")
+    pause_between_demos
 
     show_command_info('Blocks worm style')
-    run_command("#{ruby_cmd} worm --length 10 --style blocks --command 'sleep 4' --success 'Block worm'")
+    run_command("#{ruby_cmd} worm --length 10 --style blocks --command 'sleep 4' --success 'Block worm' --message 'Blocks'")
     pause_between_demos
 
     # Twirl styles
     show_demo_header('Twirl Styles', 'Different spinning patterns')
     show_command_info('Classic spinner')
-    run_command("#{ruby_cmd} twirl --style classic --command 'sleep 3' --success 'Classic spin'")
-    pause_between_demos(2)
+    run_command("#{ruby_cmd} twirl --style classic --command 'sleep 3' --success 'Classic spin' --message 'Loading'")
+    pause_between_demos
 
     show_command_info('Dots spinner')
     run_command("#{ruby_cmd} twirl --style dots --command 'sleep 3' --success 'Dotty!'")
-    pause_between_demos(2)
+    pause_between_demos
 
     show_command_info('Arrow spinner')
-    run_command("#{ruby_cmd} twirl --style arrow --command 'sleep 3' --success 'Arrow spin'")
+    run_command("#{ruby_cmd} twirl --style arrow --command 'sleep 2' --success 'Arrow spin' --message 'Loading'")
     pause_between_demos
   end
 
@@ -125,80 +129,170 @@ class ProgressDemo
     # Error handling
     show_demo_header('Error Handling', 'Graceful failure with custom messages')
     show_command_info('Simulating a failed task')
-    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 2 && exit 1' --error 'Something went wrong!' --fail-icon")
+    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 3 && exit 1' --error 'Error message!' --checkmark")
     pause_between_demos
 
     # Custom colors (if supported)
     show_demo_header('Success Messages', 'Custom completion messages')
     show_command_info('Custom success message with checkmark')
-    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Data synchronized successfully' --checkmark")
-    pause_between_demos(2)
-
-    show_command_info('Different success icon')
-    run_command("#{ruby_cmd} twirl --command 'sleep 3' --success 'Backup completed' --icon '✓'")
+    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Data synchronized successfully' --checkmark --message 'Syncing data...'")
     pause_between_demos
 
+    # show_command_info('Different success icon')
+    # run_command("#{ruby_cmd} twirl --command 'sleep 3' --success 'Backup completed' --success-icon '✓' --checkmark")
+    # pause_between_demos
+
     # No completion message
     show_demo_header('Silent Completion', 'Progress without completion messages')
     show_command_info('Silent completion (no message)')
-    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 3'")
+    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 2'")
     pause_between_demos
   end
 
   def demo_new_features
-    show_section_header('New in v1.2.0 - Enhanced Features')
+    # show_section_header('New in v1.2.0 - Enhanced Features')
 
     # Universal --ends flag
     show_demo_header('Universal --ends Flag', 'Add decorative start/end characters')
     show_command_info("Ripple with square brackets: --ends '[]'")
-    run_command("#{ruby_cmd} ripple --ends '[]' --command 'sleep 4' --success 'Framed ripple!'")
-    pause_between_demos(2)
+    run_command("#{ruby_cmd} ripple --ends '[]' --command 'sleep 3' --success 'Framed ripple!' 'With a frame'")
+    pause_between_demos
 
-    show_command_info("Worm with angle brackets: --ends '<<>>'")
-    run_command("#{ruby_cmd} worm --length 10 --ends '<<>>' --command 'sleep 4' --success 'Angled worm!'")
-    pause_between_demos(2)
+    # show_command_info("Worm with angle brackets: --ends '<<>>'")
+    # run_command("#{ruby_cmd} worm --length 10 --ends '<<>>' --command 'sleep 4' --success 'Angled worm!'")
+    # pause_between_demos
 
-    show_command_info("Twirl with emoji decoration: --ends '🎯🎪'")
-    run_command("#{ruby_cmd} twirl --ends '🎯🎪' --command 'sleep 3' --success 'Emoji decorated!'")
-    pause_between_demos
+    # show_command_info("Twirl with emoji decoration: --ends '🎯🎪'")
+    # run_command("#{ruby_cmd} twirl --ends '🎯🎪' --command 'sleep 3' --success 'Emoji decorated!'")
+    # pause_between_demos
 
     # Worm direction control
     show_demo_header('Worm Direction Control', 'Forward-only vs bidirectional movement')
     show_command_info('Bidirectional worm (default back-and-forth)')
-    run_command("#{ruby_cmd} worm --length 10 --direction bidirectional --command 'sleep 5' --success 'Back and forth!'")
-    pause_between_demos(2)
+    run_command("#{ruby_cmd} worm --length 10 --direction bidirectional --command 'sleep 3' --speed fast --success 'Both ways'")
+    pause_between_demos
 
     show_command_info('Forward-only worm (resets at end)')
-    run_command("#{ruby_cmd} worm --length 10 --direction forward --command 'sleep 5' --success 'Always forward!'")
+    run_command("#{ruby_cmd} worm --length 5 --direction forward --command 'sleep 4' --speed fast --success 'Forward only!'")
     pause_between_demos
 
     # Custom worm styles
-    show_demo_header('Custom Worm Styles', 'User-defined 3-character patterns')
-    show_command_info('ASCII custom style: --style custom=_-=')
-    run_command("#{ruby_cmd} worm --length 10 --style custom=_-= --command 'sleep 4' --success 'Custom ASCII!'")
-    pause_between_demos(2)
+    # show_demo_header('Custom Worm Styles', 'User-defined 3-character patterns')
+    # show_command_info('ASCII custom style: --style custom=_-=')
+    # run_command("#{ruby_cmd} worm --length 10 --style custom=_-= --command 'sleep 4' --success 'Custom ASCII!'")
+    # pause_between_demos
 
     show_command_info('Unicode custom style: --style custom=▫▪■')
-    run_command("#{ruby_cmd} worm --length 10 --style custom=▫▪■ --command 'sleep 4' --success 'Custom Unicode!'")
-    pause_between_demos(2)
+    run_command("#{ruby_cmd} worm --length 10 --style custom=▫▪■ --command 'sleep 3' --speed fast --success 'Custom Unicode!'")
+    pause_between_demos
 
     show_command_info('Emoji custom style: --style custom=🟦🟨🟥')
-    run_command("#{ruby_cmd} worm --length 10 --style custom=🟦🟨🟥 --command 'sleep 4' --success 'Custom emoji!'")
+    run_command("#{ruby_cmd} worm --length 10 --style custom=🟦🟨🟥 --command 'sleep 3' --speed fast --success 'Custom emoji!'")
     pause_between_demos
 
     # Combining features
-    show_demo_header('Feature Combinations', 'Mixing multiple options together')
-    show_command_info('Custom style + direction + ends: the full package!')
-    # Split the long command string to avoid RuboCop line-length issues while preserving behavior
-    part1 = "#{ruby_cmd} worm --length 10 --style custom=.🟡* --direction forward "
-    part2 = "--ends '【】' --command 'sleep 5' --success 'Ultimate combo!' --checkmark"
-    run_command(part1 + part2)
+    # show_demo_header('Feature Combinations', 'Mixing multiple options together')
+    # show_command_info('Custom style + direction + ends: the full package!')
+    # # Split the long command string to avoid RuboCop line-length issues while preserving behavior
+    # part1 = "#{ruby_cmd} worm --length 10 --style custom=.🟡* --direction forward "
+    # part2 = "--ends '【】' --command 'sleep 5' --success 'Ultimate combo!' --checkmark"
+    # run_command(part1 + part2)
+    # pause_between_demos
+
+    # v1.3.x additions: output capture and job queue demo snippets
+    # show_section_header('New in v1.3.x - Output Capture & Job Queue')
+    show_demo_header('Worm --command (output capture)', 'Run a command and reserve terminal rows for output while preserving animation')
+    show_command_info('Capture command stdout/stderr into reserved rows:')
+    # ensure a trailing space so flags aren't squashed onto the command string
+    part_a = %(#{ruby_cmd} worm --style blocks --length 10 --speed fast --command "ruby -e 'for i in 1..3 do; puts \\"line:\#{i}\\"; sleep 1; end'" )
+    part_b = "--stdout --success 'Captured!' --checkmark"
+    run_command(part_a + part_b)
+    pause_between_demos
+
+    show_command_info('Capture command stdout/stderr and display live:')
+    part_a = %(#{ruby_cmd} worm --style blocks --length 10 --speed fast --command "ruby -e 'for i in 1..5 do; puts \\"line:\#{i}\\"; sleep 0.5; end'" )
+    part_b = "--output-lines 3 --output-position top --stdout-live --success 'Captured live!' --checkmark"
+    run_command(part_a + part_b)
     pause_between_demos
+
+    # show_demo_header('prg job send (enqueue a job)', 'Send a job to a running daemon using the file-based job queue')
+    # show_command_info('Example: create a job payload and atomically enqueue it for the daemon')
+    # show_command_info('Use the bundled helper to enqueue control/action jobs:')
+    # puts "#{@colors[:command]}$ prg job send --daemon-name demo --advance#{@colors[:reset]}"
+    # puts "#{@colors[:command]}$ prg job send --daemon-name demo --percent 42#{@colors[:reset]}"
+    # puts
+    # show_command_info('Or enqueue a shell command:')
+
+    # # For the demo we run the worker in the foreground so you can see the
+    # # live animation and completion message inline. Daemon mode (started with
+    # # `--daemon` or `--daemon-as`) detaches to the background and processes
+    # # jobs via the file-based queue; `prg job send` targets a background
+    # # daemon and prints the job result JSON, but won't show the daemon's
+    # # animation in the foreground.
+    # show_command_info('Start a named fill daemon that processes percent/action jobs')
+    # # Start the fill daemon in non-detaching background mode so animation remains visible
+    # run_command("#{ruby_cmd} fill --daemon-as demo --no-detach --output-lines 3 --output-position top --success 'Captured!' --checkmark")
+    # pause_between_demos(1)
+
+    # show_command_info('We will enqueue several percent actions via a small shell script')
+    # demo_script = <<~BASH
+    #       #!/usr/bin/env bash
+    #       set -eu
+    #       echo "Sending percent updates to demo daemon (atomic mktemp+mv writes)"
+
+    #       job_dir="/tmp/ruby-progress/demo.jobs"
+    #       mkdir -p "$job_dir"
+
+    #       enqueue_percent() {
+    #         percent=$1
+    #         # Build JSON payload
+    #         id=$(uuidgen 2>/dev/null || echo "job-$(date +%s%N)")
+    #         tmp=$(mktemp "$job_dir/${id}.json.tmp.XXXXXX")
+    #         printf '%s\n' '{"id":"'"${id}"'","action":"percent","value":'"${percent}"'}' > "$tmp"
+    #         mv "$tmp" "$job_dir/${id}.json"
+
+    #         # Wait for the daemon to process the job (poll for .processing.result)
+    #         result_path="$job_dir/${id}.json.processing.result"
+    #         start=$(date +%s)
+    #         timeout=10
+    #         while [ ! -f "$result_path" ]; do
+    #           sleep 0.1
+    #           now=$(date +%s)
+    #           if [ $((now - start)) -gt $timeout ]; then
+    #             echo "Timed out waiting for result for job ${id}" >&2
+    #             return 2
+    #           fi
+    #         done
+    #         cat "$result_path"
+    #       }
+
+    #       enqueue_percent 10
+    #       sleep 1
+    #       enqueue_percent 40
+    #       sleep 1
+    #       enqueue_percent 70
+    #       sleep 1
+    #       enqueue_percent 100
+
+    #   # After updates, stop the daemon cleanly (call local bin/prg to avoid global conflicts)
+    #   #{ruby_cmd} fill --stop-id demo --stop-success 'Demo daemon stopped'
+    # BASH
+
+    # # Show the simulated script contents
+    # puts "#{@colors[:command]}$ cat demo_percent_updates.sh#{@colors[:reset]}"
+    # puts demo_script
+
+    # # Write and execute the script (run in a subshell so output doesn't interleave too badly)
+    # script_path = File.join(Dir.tmpdir, "demo_percent_updates_#{Time.now.to_i}.sh")
+    # File.write(script_path, demo_script)
+    # File.chmod(0o755, script_path)
+    # run_command("bash #{Shellwords.escape(script_path)}")
+    # pause_between_demos
   end
 
   def show_finale
     show_section_header('Demo Complete!')
-    show_description('Ruby Progress Gem v1.2.0 - Making terminal progress beautiful! 🚀')
+    show_description('Ruby Progress Gem v1.3.2 - Making terminal progress beautiful! 🚀')
     puts
     show_description('Key features demonstrated:')
     puts "#{@colors[:description]}  • Three animation types: ripple, worm, twirl#{@colors[:reset]}"
@@ -217,18 +311,20 @@ class ProgressDemo
   # Utility methods
 
   def ruby_cmd
-    "ruby -I #{@lib_path} #{@gem_path}"
+    # "ruby -I #{@lib_path} #{@gem_path}"
+    'bin/prg'
   end
 
   def clear_screen
     system('clear') || system('cls')
+    system('tput cup 15 0')
   end
 
   def show_title
     puts
     puts "#{@colors[:header]}#{'=' * 60}#{@colors[:reset]}"
     puts "#{@colors[:header]}  RUBY PROGRESS GEM - DEMO SCREENCAST#{@colors[:reset]}"
-    puts "#{@colors[:header]}  Version 1.2.0 Feature Demonstration#{@colors[:reset]}"
+    puts "#{@colors[:header]}  Version 1.3.2 Feature Demonstration#{@colors[:reset]}"
     puts "#{@colors[:header]}#{'=' * 60}#{@colors[:reset]}"
     puts
   end
@@ -257,19 +353,75 @@ class ProgressDemo
   end
 
   def run_command(cmd)
-    puts "#{@colors[:command]}$ #{cmd}#{@colors[:reset]}"
+    # Type the command with syntax highlighting
+    type_command("$ #{cmd.sub(%r{^bin/}, '')}")
     puts
     system(cmd)
     puts
   end
 
+  # Type out a shell command with simple token-based syntax highlighting.
+  # - executable (first token) uses @colors[:exec]
+  # - flags (tokens starting with '-') use @colors[:flag]
+  # - values use @colors[:value]
+  # The function prints one character at a time to simulate typing.
+  def type_command(line, speed: 0.02)
+    tokens = line.scan(/'[^']*'|"[^"]*"|\S+/)
+    pos = 0
+
+    # Determine the executable token position (skip leading prompt '$' tokens)
+    exec_pos = tokens.find_index { |t| !t.start_with?('$') }
+    subcmd_pos = exec_pos ? exec_pos + 1 : nil
+
+    tokens.each_with_index do |token, idx|
+      # Find token in original line starting at pos (to preserve spacing)
+      start_idx = line.index(token, pos) || pos
+
+      # print any intermediate whitespace
+      inter = line[pos...start_idx]
+      $stdout.print(inter) if inter && !inter.empty?
+
+      # Default color for tokens is value
+      color = @colors[:value]
+
+      if token.start_with?('$')
+        color = @colors[:prompt]
+      elsif idx == exec_pos && token == 'prg'
+        # Highlight the bundled tool name in magenta
+        color = @colors[:tool]
+      elsif idx == exec_pos
+        # Executable token (e.g. ruby or other) - keep exec color
+        color = @colors[:exec]
+      elsif idx == subcmd_pos
+        # Subcommand (ripple/twirl/worm/fill etc.) highlighted in yellow
+        color = @colors[:command]
+      elsif token.start_with?('-')
+        color = @colors[:flag]
+      end
+
+      # Print the token one char at a time
+      token.each_char do |ch|
+        $stdout.print("#{color}#{ch}#{@colors[:reset]}")
+        $stdout.flush
+        sleep(speed)
+      end
+
+      pos = start_idx + token.length
+    end
+
+    # Print any trailing whitespace/newline
+    trailing = line[pos..-1]
+    $stdout.print(trailing) if trailing
+    $stdout.flush
+  end
+
   def pause_for_narration(seconds = 2)
-    puts "#{@colors[:dim]}[Pausing #{seconds}s for narration...]#{@colors[:reset]}"
-    sleep(seconds)
+    # puts "#{@colors[:dim]}[Pausing #{seconds}s for narration...]#{@colors[:reset]}"
+    # sleep(seconds)
   end
 
-  def pause_between_demos(seconds = 3)
-    puts "#{@colors[:dim]}[Pausing #{seconds}s between demos...]#{@colors[:reset]}"
+  def pause_between_demos(seconds = 1)
+    # puts "#{@colors[:dim]}[Pausing #{seconds}s between demos...]#{@colors[:reset]}"
     sleep(seconds)
   end
 end
@@ -278,14 +430,14 @@ end
 if __FILE__ == $PROGRAM_NAME
   demo = ProgressDemo.new
 
-  puts 'Ruby Progress Gem Demo Screencast'
-  puts '================================='
-  puts
-  puts 'This script will demonstrate various features of the ruby-progress gem.'
-  puts 'Press ENTER to start the demo, or Ctrl+C to exit.'
-  puts
-  print 'Ready? '
-  gets
+  # puts 'Ruby Progress Gem Demo Screencast'
+  # puts '================================='
+  # puts
+  # puts 'This script will demonstrate various features of the ruby-progress gem.'
+  # puts 'Press ENTER to start the demo, or Ctrl+C to exit.'
+  # puts
+  # print 'Ready? '
+  # gets
 
   begin
     demo.run

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

@@ -5,7 +5,9 @@ require 'optparse'
 module RubyProgress
   module FillCLI
     # Option parsing extracted to reduce module length in FillCLI
+    # rubocop:disable Metrics/AbcSize, Metrics/BlockLength
     module Options
+      # rubocop :disable Metrics/MethodLength
       def self.parse_cli_options
         options = {
           style: :blocks,
@@ -60,6 +62,10 @@ module RubyProgress
               options[:output_lines] = n
             end
 
+            opts.on('--stdout-live', 'Stream captured output to STDOUT as it arrives (non-blocking)') do
+              options[:stdout_live] = true
+            end
+
             opts.separator ''
             opts.separator 'Progress Control:'
 
@@ -106,6 +112,14 @@ module RubyProgress
               options[:success_message] = msg
             end
 
+            opts.on('--success-icon ICON', 'Custom success icon to show with completion messages') do |ic|
+              options[:success_icon] = ic
+            end
+
+            opts.on('--error-icon ICON', 'Custom error icon to show with failure messages') do |ic|
+              options[:error_icon] = ic
+            end
+
             opts.on('--error MESSAGE', 'Error message to display on cancellation') do |msg|
               options[:error_message] = msg
             end
@@ -121,6 +135,21 @@ module RubyProgress
               options[:daemon] = true
             end
 
+            opts.on('--daemon-as NAME', 'Run in daemon mode with custom name (creates /tmp/ruby-progress/NAME.pid)') do |name|
+              options[:daemon] = true
+              options[:daemon_name] = name
+            end
+
+            # Accept --daemon-name as alias for --daemon-as
+            opts.on('--daemon-name NAME', 'Alias for --daemon-as (compat)') do |name|
+              options[:daemon] = true
+              options[:daemon_name] = name
+            end
+
+            opts.on('--no-detach', 'When used with --daemon/--daemon-as: run background child but do not fully detach from the terminal') do
+              options[:no_detach] = true
+            end
+
             opts.on('--pid-file FILE', 'PID file location (default: /tmp/ruby-progress/fill.pid)') do |file|
               options[:pid_file] = file
             end
@@ -129,10 +158,36 @@ module RubyProgress
               options[:stop] = true
             end
 
+            opts.on('--stop-id NAME', 'Stop daemon by name (implies --stop)') do |name|
+              # Backwards-compatible shorthand used in demos: set stop flag
+              options[:stop] = true
+              # Normalize to canonical keys used by FillCLI (daemon_name/status_name)
+              options[:stop_name] = name
+              options[:daemon_name] = name
+              options[:status_name] = name
+            end
+
             opts.on('--status', 'Show daemon status') do
               options[:status] = true
             end
 
+            opts.on('--status-id NAME', 'Show daemon status by name') do |name|
+              options[:status] = true
+              # Normalize to canonical key
+              options[:status_name] = name
+              options[:daemon_name] = name
+            end
+
+            opts.on('--stop-success MESSAGE', 'Stop daemon with success message (implies --stop)') do |msg|
+              options[:stop] = true
+              options[:stop_success] = msg
+            end
+            opts.on('--stop-error MESSAGE', 'Stop daemon with error message (implies --stop)') do |msg|
+              options[:stop] = true
+              options[:stop_error] = msg
+            end
+            opts.on('--stop-checkmark', 'When stopping, include a success checkmark') { options[:stop_checkmark] = true }
+
             opts.separator ''
             opts.separator 'General:'
 
@@ -155,9 +210,9 @@ module RubyProgress
           warn "Run 'prg fill --help' for more information."
           exit 1
         end
-
         options
       end
+      # rubocop :enable Metrics/MethodLength
 
       def self.help_text
         opts = OptionParser.new
@@ -211,5 +266,6 @@ module RubyProgress
         opts.to_s
       end
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/BlockLength
   end
 end

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

@@ -28,12 +28,43 @@ module JobCLI
       options = { wait: false }
       opt = OptionParser.new do |o|
         o.banner = 'Usage: prg job send [options]'
-        o.on('--pid-file PATH', 'Path to daemon pid file') { |v| options[:pid_file] = v }
-        o.on('--daemon-name NAME', 'Daemon name (maps to /tmp/ruby-progress/NAME.pid)') { |v| options[:daemon_name] = v }
-        o.on('--command CMD', 'Command to run') { |v| options[:command] = v }
-        o.on('--stdin', 'Read command from stdin (overrides --command)') { options[:stdin] = true }
-        o.on('--wait', 'Wait for result file and print it') { options[:wait] = true }
-        o.on('--timeout SECONDS', Integer, 'Timeout seconds for wait') { |v| options[:timeout] = v }
+        o.on('--pid-file PATH', 'Path to daemon pid file') do |v|
+          options[:pid_file] = v
+        end
+        o.on('--daemon-name NAME', 'Daemon name (maps to /tmp/ruby-progress/NAME.pid)') do |v|
+          options[:daemon_name] = v
+        end
+        o.on('--command CMD', 'Command to run') do |v|
+          options[:command] = v
+        end
+        o.on('--stdin', 'Read command from stdin (overrides --command)') do
+          options[:stdin] = true
+        end
+        o.on('--advance', 'Send an advance action (no value)') do
+          options[:action] = 'advance'
+        end
+        o.on('--percent N', Integer, 'Send a percent action with value N') do |v|
+          options[:action] = 'percent'
+          options[:value] = v
+        end
+        o.on('--complete', 'Send a complete action (no value)') do
+          options[:action] = 'complete'
+        end
+        o.on('--cancel', 'Send a cancel action (no value)') do
+          options[:action] = 'cancel'
+        end
+        o.on('--action ACTION', 'Send a custom action name') do |v|
+          options[:action] = v
+        end
+        o.on('--value VAL', 'Value for the action (string or number)') do |v|
+          options[:value] = v
+        end
+        o.on('--wait', 'Wait for result file and print it') do
+          options[:wait] = true
+        end
+        o.on('--timeout SECONDS', Integer, 'Timeout seconds for wait') do |v|
+          options[:timeout] = v
+        end
       end
 
       rest = opt.parse(argv)
@@ -63,16 +94,25 @@ module JobCLI
             opts[:command]
           end
 
-    unless cmd && !cmd.strip.empty?
-      warn 'No command specified. Use --command or --stdin.'
-      exit 1
+    is_action = !opts[:action].nil? && opts[:action] != false
+
+    if is_action
+      if cmd && !cmd.strip.empty?
+        warn 'Cannot specify both --command/--stdin and an action flag'
+        exit 1
+      end
+    else
+      unless cmd && !cmd.strip.empty?
+        warn 'No command specified. Use --command, --stdin, or pass an action flag.'
+        exit 1
+      end
     end
 
     job_id = SecureRandom.uuid
     tmp = File.join(job_dir, "#{job_id}.json.tmp")
     final = File.join(job_dir, "#{job_id}.json")
 
-    payload = { 'id' => job_id, 'command' => cmd }
+    payload = build_payload(opts, job_id, cmd)
 
     File.write(tmp, JSON.dump(payload))
     FileUtils.mv(tmp, final)
@@ -96,4 +136,24 @@ module JobCLI
       puts job_id
     end
   end
+
+  # Build the JSON payload for a job based on parsed options.
+  def self.build_payload(opts, job_id, cmd)
+    payload = { 'id' => job_id }
+
+    is_action = !opts[:action].nil? && opts[:action] != false
+
+    if is_action
+      payload['action'] = opts[:action]
+      if opts.key?(:value)
+        val = opts[:value]
+        payload['value'] = val.to_i if val.is_a?(String) && val =~ /^\d+$/
+        payload['value'] ||= val
+      end
+    else
+      payload['command'] = cmd
+    end
+
+    payload
+  end
 end