ruby-progress 1.2.0 → 1.3.1

data/demo_screencast.rb

@@ -0,0 +1,296 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Ruby Progress Gem Demo Screencast Script
+# ========================================
+#
+# This script creates a comprehensive demonstration of the ruby-progress gem
+# showing all major features across the three subcommands: ripple, worm, and twirl.
+#
+# Usage: ruby demo_screencast.rb
+#
+# The script includes pauses between demonstrations to allow for narration
+# and clear visual separation of different features.
+
+require 'io/console'
+
+# Demo runner that exercises the major features of the ruby-progress gem
+# used by the documentation and screencast recordings.
+class ProgressDemo
+  def initialize
+    @gem_path = File.expand_path('bin/prg', __dir__)
+    @lib_path = File.expand_path('lib', __dir__)
+
+    # Colors for terminal output
+    @colors = {
+      header: "\e[1;36m",    # Bright cyan
+      command: "\e[1;33m",   # Bright yellow
+      description: "\e[0;32m", # Green
+      reset: "\e[0m",        # Reset
+      dim: "\e[2m"           # Dim
+    }
+  end
+
+  def run
+    clear_screen
+    show_title
+
+    # Introduction
+    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
+
+    # Style demonstrations
+    demo_styles
+
+    # Advanced options
+    demo_advanced_options
+
+    # New v1.2.0 features
+    demo_new_features
+
+    # Finale
+    show_finale
+  end
+
+  private
+
+  def demo_basic_commands
+    show_section_header('Basic Commands Overview')
+
+    # 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")
+    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")
+    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")
+    pause_between_demos
+  end
+
+  def demo_styles
+    show_section_header('Style Variations')
+
+    # 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'")
+    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)
+
+    show_command_info('Blocks worm style')
+    run_command("#{ruby_cmd} worm --length 10 --style blocks --command 'sleep 4' --success 'Block worm'")
+    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)
+
+    show_command_info('Dots spinner')
+    run_command("#{ruby_cmd} twirl --style dots --command 'sleep 3' --success 'Dotty!'")
+    pause_between_demos(2)
+
+    show_command_info('Arrow spinner')
+    run_command("#{ruby_cmd} twirl --style arrow --command 'sleep 3' --success 'Arrow spin'")
+    pause_between_demos
+  end
+
+  def demo_advanced_options
+    show_section_header('Advanced Options')
+
+    # 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")
+    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 '✓'")
+    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'")
+    pause_between_demos
+  end
+
+  def demo_new_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)
+
+    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("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)
+
+    show_command_info('Forward-only worm (resets at end)')
+    run_command("#{ruby_cmd} worm --length 10 --direction forward --command 'sleep 5' --success 'Always forward!'")
+    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_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)
+
+    show_command_info('Emoji custom style: --style custom=🟦🟨🟥')
+    run_command("#{ruby_cmd} worm --length 10 --style custom=🟦🟨🟥 --command 'sleep 4' --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)
+    pause_between_demos
+  end
+
+  def show_finale
+    show_section_header('Demo Complete!')
+    show_description('Ruby Progress Gem v1.2.0 - Making terminal progress beautiful! 🚀')
+    puts
+    show_description('Key features demonstrated:')
+    puts "#{@colors[:description]}  • Three animation types: ripple, worm, twirl#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Multiple built-in styles#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Universal --ends flag for decoration#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Worm direction control#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Custom user-defined styles#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Success/error handling#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Multi-byte character support (Unicode/emoji)#{@colors[:reset]}"
+    puts
+    show_description('Install: gem install ruby-progress')
+    show_description('GitHub: https://github.com/ttscoff/ruby-progress')
+    puts
+  end
+
+  # Utility methods
+
+  def ruby_cmd
+    "ruby -I #{@lib_path} #{@gem_path}"
+  end
+
+  def clear_screen
+    system('clear') || system('cls')
+  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]}#{'=' * 60}#{@colors[:reset]}"
+    puts
+  end
+
+  def show_section_header(title)
+    puts
+    puts "#{@colors[:header]}#{'-' * 50}#{@colors[:reset]}"
+    puts "#{@colors[:header]} #{title}#{@colors[:reset]}"
+    puts "#{@colors[:header]}#{'-' * 50}#{@colors[:reset]}"
+    puts
+  end
+
+  def show_demo_header(title, description)
+    puts
+    puts "#{@colors[:header]}### #{title}#{@colors[:reset]}"
+    puts "#{@colors[:description]}#{description}#{@colors[:reset]}"
+    puts
+  end
+
+  def show_command_info(description)
+    puts "#{@colors[:dim]}#{description}#{@colors[:reset]}"
+  end
+
+  def show_description(text)
+    puts "#{@colors[:description]}#{text}#{@colors[:reset]}"
+  end
+
+  def run_command(cmd)
+    puts "#{@colors[:command]}$ #{cmd}#{@colors[:reset]}"
+    puts
+    system(cmd)
+    puts
+  end
+
+  def pause_for_narration(seconds = 2)
+    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]}"
+    sleep(seconds)
+  end
+end
+
+# Script execution
+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
+
+  begin
+    demo.run
+  rescue Interrupt
+    puts "\n\nDemo interrupted. Thanks for watching!"
+    exit(0)
+  end
+end

data/examples/daemon_job_example.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+# Example: start a worm daemon, send a job, wait for result, then stop.
+# This script assumes you're running from the project root and have a working
+# `bin/prg` script in the repository.
+
+set -eu
+
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PRG_BIN="$PROJECT_ROOT/bin/prg"
+
+echo "Starting worm daemon (named 'example')..."
+# prg detaches in daemon mode so no & needed
+$PRG_BIN worm --daemon-as example --message "Example daemon"
+
+sleep 0.2
+
+echo "Sending job and waiting for result..."
+$PRG_BIN job send --daemon-name example --command "echo hello; sleep 0.1" --wait --timeout 10
+
+sleep 0.1
+
+echo "Stopping daemon with success message..."
+$PRG_BIN worm --stop-success "Example finished" --stop-checkmark --daemon-name example
+
+echo "Done."

data/experimental_terminal.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 # Experimental terminal line protection for daemon mode
 # This demonstrates potential solutions for the daemon output interruption problem
 
 module RubyProgress
+  # SmartTerminal: experimental helpers for safer terminal cursor/line operations
+  # used by daemon-mode demos and scripts where output can interleave with animations.
   module SmartTerminal
     # Save current cursor position
     def self.save_cursor_position
@@ -16,6 +20,8 @@ module RubyProgress
     end
 
     # Get current cursor position (requires terminal interaction)
+    # rubocop:disable Naming/AccessorMethodName
+    # Intentionally named get_cursor_position because it performs an I/O request
     def self.get_cursor_position
       # This is complex and requires reading from stdin
       # which may not work reliably in daemon mode
@@ -24,6 +30,7 @@ module RubyProgress
       # Would need to read response: "\e[{row};{col}R"
       # But this requires terminal input capability
     end
+    # rubocop:enable Naming/AccessorMethodName
 
     # Alternative: Use absolute positioning
     def self.position_cursor_absolute(row, col)

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

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module RubyProgress
+  module FillCLI
+    # Option parsing extracted to reduce module length in FillCLI
+    module Options
+      def self.parse_cli_options
+        options = {
+          style: :blocks,
+          length: 20,
+          speed: :medium,
+          percent: nil,
+          advance: false,
+          complete: false,
+          cancel: false,
+          success_message: nil,
+          error_message: nil,
+          checkmark: false,
+          daemon: false,
+          pid_file: nil,
+          stop: false,
+          status: false,
+          current: false,
+          output_position: :above,
+          output_lines: 3,
+          report: false
+        }
+
+        begin
+          OptionParser.new do |opts|
+            opts.banner = 'Usage: prg fill [options]'
+            opts.separator ''
+            opts.separator 'Progress Bar Options:'
+
+            opts.on('-l', '--length LENGTH', Integer, 'Progress bar length (default: 20)') do |length|
+              options[:length] = length
+            end
+
+            opts.on('-s', '--style STYLE', 'Progress bar style (blocks, classic, dots, etc. or custom=XY)') do |style|
+              options[:style] = style
+            end
+
+            opts.on('--ends CHARS', 'Start/end characters (even number of chars, split in half)') do |chars|
+              options[:ends] = chars
+            end
+
+            opts.separator 'Output capture:'
+
+            opts.on('-c', '--command COMMAND', 'Command to run and capture output (optional)') do |cmd|
+              options[:command] = cmd
+            end
+
+            opts.on('--output-position POSITION', 'Position to render captured output: above or below (default: above)') do |pos|
+              options[:output_position] = pos.to_sym
+            end
+
+            opts.on('--output-lines N', Integer, 'Number of output lines to reserve for captured output (default: 3)') do |n|
+              options[:output_lines] = n
+            end
+
+            opts.separator ''
+            opts.separator 'Progress Control:'
+
+            opts.on('-p', '--percent PERCENT', Float, 'Set progress to percentage (0-100)') do |percent|
+              options[:percent] = percent
+            end
+
+            opts.on('--advance', 'Advance progress by one step') do
+              options[:advance] = true
+            end
+
+            opts.on('--complete', 'Complete the progress bar') do
+              options[:complete] = true
+            end
+
+            opts.on('--cancel', 'Cancel the progress bar') do
+              options[:cancel] = true
+            end
+
+            opts.on('--current', 'Show current progress percentage (0-100 float)') do
+              options[:current] = true
+            end
+
+            opts.on('--report', 'Show detailed progress report') do
+              options[:report] = true
+            end
+
+            opts.separator ''
+            opts.separator 'Auto-advance Mode:'
+
+            opts.on('--speed SPEED', 'Auto-advance speed (fast/medium/slow or numeric)') do |speed|
+              options[:speed] = case speed.downcase
+                                when /^f/ then :fast
+                                when /^m/ then :medium
+                                when /^s/ then :slow
+                                else speed.to_f.positive? ? speed.to_f : :medium
+                                end
+            end
+
+            opts.separator ''
+            opts.separator 'Messages:'
+
+            opts.on('--success MESSAGE', 'Success message to display on completion') do |msg|
+              options[:success_message] = msg
+            end
+
+            opts.on('--error MESSAGE', 'Error message to display on cancellation') do |msg|
+              options[:error_message] = msg
+            end
+
+            opts.on('--checkmark', 'Show checkmarks (✅ success, 🛑 failure)') do
+              options[:checkmark] = true
+            end
+
+            opts.separator ''
+            opts.separator 'Daemon Mode:'
+
+            opts.on('--daemon', 'Run in background daemon mode') do
+              options[:daemon] = true
+            end
+
+            opts.on('--pid-file FILE', 'PID file location (default: /tmp/ruby-progress/fill.pid)') do |file|
+              options[:pid_file] = file
+            end
+
+            opts.on('--stop', 'Stop daemon') do
+              options[:stop] = true
+            end
+
+            opts.on('--status', 'Show daemon status') do
+              options[:status] = true
+            end
+
+            opts.separator ''
+            opts.separator 'General:'
+
+            opts.on('--show-styles', 'Show available fill styles with visual previews') do
+              options[:show_styles] = true
+            end
+
+            opts.on('-v', '--version', 'Show version') do
+              options[:version] = true
+            end
+
+            opts.on('-h', '--help', 'Show this help') do
+              options[:help] = true
+            end
+          end.parse!
+        rescue OptionParser::InvalidOption => e
+          warn "Invalid option: #{e.args.first}"
+          warn ''
+          warn 'Usage: prg fill [options]'
+          warn "Run 'prg fill --help' for more information."
+          exit 1
+        end
+
+        options
+      end
+
+      def self.help_text
+        opts = OptionParser.new
+
+        opts.banner = 'Usage: prg fill [options]'
+        opts.separator ''
+        opts.separator 'Progress Bar Options:'
+
+        opts.on('-l', '--length LENGTH', Integer, 'Progress bar length (default: 20)')
+        opts.on('-s', '--style STYLE', 'Progress bar style (blocks, classic, dots, etc. or custom=XY)')
+        opts.on('--ends CHARS', 'Start/end characters (even number of chars, split in half)')
+
+        opts.separator ''
+        opts.separator 'Progress Control:'
+        opts.on('-p', '--percent PERCENT', Float, 'Set progress to percentage (0-100)')
+        opts.on('--advance', 'Advance progress by one step')
+        opts.on('--complete', 'Complete the progress bar')
+        opts.on('--cancel', 'Cancel the progress bar')
+        opts.on('--current', 'Show current progress percentage (0-100 float)')
+        opts.on('--report', 'Show detailed progress report')
+
+        opts.separator ''
+        opts.separator 'Auto-advance Mode:'
+        opts.on('--speed SPEED', 'Auto-advance speed (fast/medium/slow or numeric)')
+
+        opts.separator ''
+        opts.separator 'Messages:'
+        opts.on('--success MESSAGE', 'Success message to display on completion')
+        opts.on('--error MESSAGE', 'Error message to display on cancellation')
+        opts.on('--checkmark', 'Show checkmarks (✅ success, 🛑 failure)')
+
+        opts.separator ''
+        opts.separator ''
+        opts.separator 'Output capture:'
+        opts.on('--output-position POSITION', 'Position to render captured output: above or below (default: above)')
+        opts.on('--output-lines N', Integer, 'Number of output lines to reserve for captured output (default: 3)')
+
+        opts.separator ''
+        opts.separator 'Daemon Mode:'
+        opts.on('--daemon', 'Run in background daemon mode')
+        opts.on('--pid-file FILE', 'PID file location (default: /tmp/ruby-progress/fill.pid)')
+        opts.on('--stop', 'Stop daemon')
+        opts.on('--status', 'Show daemon status')
+
+        opts.separator ''
+        opts.separator 'General:'
+        opts.on('--show-styles', 'Show available fill styles with visual previews')
+        opts.on('-v', '--version', 'Show version')
+        opts.on('-h', '--help', 'Show this help')
+
+        opts.to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# CLI: prg job
+
+# Provides the `prg job send` helper to enqueue commands into a daemon's
+# job directory. This file contains a minimal implementation used by tests.
+
+require 'optparse'
+require 'json'
+require 'securerandom'
+require 'fileutils'
+require_relative '../daemon'
+
+# Job CLI helpers
+#
+# Exposed as `prg job send`.
+module JobCLI
+  # JobCLI
+  #
+  # Small CLI module that exposes `prg job send` for enqueuing jobs into the
+  # daemon job directory. This is intentionally minimal: it writes a single
+  # JSON file atomically and optionally waits for a result file created by
+  # the daemon's job processor.
+  # Simple CLI for submitting jobs to a running daemon job directory.
+  # Usage: prg job send --pid-file /tmp/... --command "echo hi" [--wait]
+  class Options
+    def self.parse(argv)
+      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 }
+      end
+
+      rest = opt.parse(argv)
+      options[:command] ||= rest.join(' ') unless rest.empty?
+      options
+    end
+  end
+
+  def self.send(argv = ARGV)
+    opts = Options.parse(argv)
+
+    # Resolve pid file
+    pid_file = if opts[:pid_file]
+                 opts[:pid_file]
+               elsif opts[:daemon_name]
+                 "/tmp/ruby-progress/#{opts[:daemon_name]}.pid"
+               else
+                 RubyProgress::Daemon.default_pid_file
+               end
+
+    job_dir = RubyProgress::Daemon.job_dir_for_pid(pid_file)
+    FileUtils.mkdir_p(job_dir)
+
+    cmd = if opts[:stdin]
+            $stdin.read
+          else
+            opts[:command]
+          end
+
+    unless cmd && !cmd.strip.empty?
+      warn 'No command specified. Use --command or --stdin.'
+      exit 1
+    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 }
+
+    File.write(tmp, JSON.dump(payload))
+    FileUtils.mv(tmp, final)
+
+    if opts[:wait]
+      timeout = opts[:timeout] || 10
+      start = Time.now
+      result_path = "#{final}.processing.result"
+      loop do
+        if File.exist?(result_path)
+          puts File.read(result_path)
+          break
+        end
+        if Time.now - start > timeout
+          warn 'Timed out waiting for result'
+          exit 2
+        end
+        sleep 0.1
+      end
+    else
+      puts job_id
+    end
+  end
+end