ruby-progress 1.2.4 → 1.3.2

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

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'json'
+require 'securerandom'
 require_relative 'ripple_options'
+require_relative '../output_capture'
 
 # Enhanced Ripple CLI with unified flags (extracted from bin/prg)
 module RippleCLI
@@ -30,8 +33,13 @@ module RippleCLI
       )
       exit
     elsif options[:daemon]
-      # For daemon mode, detach so shell has no tracked job
-      PrgCLI.daemonize
+      # For daemon mode, detach so shell has no tracked job unless the user
+      # requested a non-detaching background child via --no-detach.
+      if options[:no_detach]
+        PrgCLI.backgroundize
+      else
+        PrgCLI.daemonize
+      end
 
       # For daemon mode, default message if none provided
       text = options[:message] || ARGV.join(' ')
@@ -60,17 +68,42 @@ module RippleCLI
   end
 
   def self.run_with_command(text, options)
-    captured_output = nil
-    RubyProgress::Ripple.progress(text, options) do
+    if $stdout.tty?
+      # Interactive TTY: use PTY-based capture so the animation can run while the
+      # command executes. We only print captured stdout if options[:output] == :stdout.
+      oc = RubyProgress::OutputCapture.new(command: options[:command], lines: options[:output_lines] || 3, position: options[:output_position] || :above)
+      oc.start
+
+      # Create rippler. Attach output capture only when the user requested
+      # live stdout display via --stdout; otherwise start the PTY reader so
+      # we can collect the child's exit status but do not call redraw.
+      rippler = RubyProgress::Ripple.new(text, options)
+      rippler.instance_variable_set(:@output_capture, oc) if options[:output] == :stdout
+
+      thread = Thread.new { loop { rippler.advance } }
+      oc.wait
+      thread.kill
+
+      captured_lines = oc.lines
+      captured_output = captured_lines.join("\n")
+      success = oc.exit_status.nil? || oc.exit_status.zero?
+    else
+      # Non-interactive / CI: fallback to legacy synchronous capture
       captured_output = `#{options[:command]} 2>&1`
+      success = $CHILD_STATUS.success?
     end
 
-    success = $CHILD_STATUS.success?
-
     puts captured_output if options[:output] == :stdout
+
     if options[:success_message] || options[:complete_checkmark]
       message = success ? options[:success_message] : options[:fail_message] || options[:success_message]
-      RubyProgress::Ripple.complete(text, message, options[:complete_checkmark], success)
+      RubyProgress::Ripple.complete(
+        text,
+        message,
+        options[:complete_checkmark],
+        success,
+        icons: { success: options[:success_icon], error: options[:error_icon] }
+      )
     end
     exit success ? 0 : 1
   end
@@ -90,7 +123,6 @@ module RippleCLI
     pid_file = options[:pid_file] || RubyProgress::Daemon.default_pid_file
     FileUtils.mkdir_p(File.dirname(pid_file))
     File.write(pid_file, Process.pid.to_s)
-
     begin
       # For Ripple, re-use the existing animation loop via a simple loop
       RubyProgress::Utils.hide_cursor
@@ -102,6 +134,9 @@ module RippleCLI
       Signal.trap('TERM') { stop_requested = true }
       Signal.trap('HUP')  { stop_requested = true }
 
+      job_dir = RubyProgress::Daemon.job_dir_for_pid(pid_file)
+      job_thread = Thread.new { process_daemon_jobs_for_rippler(job_dir, rippler, options) }
+
       rippler.advance until stop_requested
     ensure
       RubyProgress::Utils.clear_line
@@ -128,7 +163,8 @@ module RippleCLI
               message,
               success: success_val,
               show_checkmark: check,
-              output_stream: :stdout
+              output_stream: :stdout,
+              icons: { success: options[:success_icon], error: options[:error_icon] }
             )
           end
         rescue StandardError
@@ -142,9 +178,52 @@ module RippleCLI
         end
       end
 
+      # stop job thread and cleanup
+      job_thread&.kill
       FileUtils.rm_f(pid_file)
     end
   end
 
+  def self.process_daemon_jobs_for_rippler(job_dir, rippler, options)
+    RubyProgress::Daemon.process_jobs(job_dir) do |job|
+      jid = job['id'] || SecureRandom.uuid
+      log_path = begin
+        File.join(File.dirname(job_dir), "#{jid}.log")
+      rescue StandardError
+        nil
+      end
+
+      oc = RubyProgress::OutputCapture.new(
+        command: job['command'],
+        lines: options[:output_lines] || 3,
+        position: options[:output_position] || :above,
+        log_path: log_path
+      )
+      oc.start
+
+      rippler.instance_variable_set(:@output_capture, oc)
+      oc.wait
+      captured = oc.lines.join("\n")
+      exit_status = oc.exit_status
+      rippler.instance_variable_set(:@output_capture, nil)
+
+      success = exit_status.to_i.zero?
+      if job['message']
+        RubyProgress::Utils.display_completion(
+          job['message'],
+          success: success,
+          show_checkmark: job['checkmark'] || false,
+          output_stream: :stdout,
+          icons: { success: options[:success_icon], error: options[:error_icon] }
+        )
+      end
+
+      { 'exit_status' => exit_status, 'output' => captured, 'log_path' => log_path }
+    rescue StandardError
+      # ignore per-job errors; process_jobs will write result
+      nil
+    end
+  end
+
   # Options parsing moved to ripple_options.rb
 end

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

@@ -17,6 +17,8 @@ module RippleCLI
         fail_message: nil,
         complete_checkmark: false,
         output: :error,
+        output_position: :above,
+        output_lines: 3,
         message: nil
       }
 
@@ -57,10 +59,26 @@ module RippleCLI
             options[:command] = command
           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.on('--success MESSAGE', 'Success message to display') do |msg|
             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') do |msg|
             options[:fail_message] = msg
           end
@@ -84,6 +102,10 @@ module RippleCLI
             options[:daemon] = true
           end
 
+          opts.on('--no-detach', 'When used with --daemon: run background child but do not fully detach from the terminal') do
+            options[:no_detach] = true
+          end
+
           opts.on('--pid-file FILE', 'Write process ID to file (default: /tmp/ruby-progress/progress.pid)') do |file|
             options[:pid_file] = file
           end

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

@@ -10,7 +10,10 @@ module TwirlCLI
   # so the `TwirlCLI` module stays small and focused on dispatching.
   module Options
     def self.parse_cli_options
-      options = {}
+      options = {
+        output_position: :above,
+        output_lines: 3
+      }
 
       OptionParser.new do |opts|
         opts.banner = 'Usage: prg twirl [options]'
@@ -29,6 +32,12 @@ module TwirlCLI
           options[:style] = style
         end
 
+        opts.on('-d', '--direction DIRECTION', 'Animation direction (forward/bidirectional or f/b)') do |direction|
+          # Twirl is a spinner and doesn't visibly change with direction, but accept the
+          # flag for parity with other subcommands (Worm/Ripple) so scripts can use it.
+          options[:direction] = direction =~ /^f/i ? :forward_only : :bidirectional
+        end
+
         opts.on('--ends CHARS', 'Start/end characters (even number of chars, split in half)') do |chars|
           options[:ends] = chars
         end
@@ -40,10 +49,26 @@ module TwirlCLI
           options[:command] = command
         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.on('--success MESSAGE', 'Success message to display') do |text|
           options[:success] = text
         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') do |text|
           options[:error] = text
         end
@@ -63,6 +88,10 @@ module TwirlCLI
           options[:daemon] = true
         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('--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

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

@@ -3,6 +3,7 @@
 require 'fileutils'
 require 'json'
 require_relative 'twirl_spinner'
+require_relative '../output_capture'
 
 # Top-level runtime helper module for the Twirl CLI.
 #
@@ -22,8 +23,25 @@ module TwirlRunner
       RubyProgress::Utils.hide_cursor
       spinner_thread = Thread.new { loop { spinner.animate } }
 
-      captured_output = `#{options[:command]} 2>&1`
-      success = $CHILD_STATUS.success?
+      if $stdout.tty? && options[:stdout]
+        oc = RubyProgress::OutputCapture.new(
+          command: options[:command],
+          lines: options[:output_lines] || 3,
+          position: options[:output_position] || :above
+        )
+        oc.start
+
+        spinner.instance_variable_set(:@output_capture, oc)
+
+        # wait for command while spinner thread runs
+        oc.wait
+        captured_lines = oc.lines
+        captured_output = captured_lines.join("\n")
+        success = true
+      else
+        captured_output = `#{options[:command]} 2>&1`
+        success = $CHILD_STATUS.success?
+      end
 
       spinner_thread.kill
       RubyProgress::Utils.clear_line
@@ -40,7 +58,8 @@ module TwirlRunner
       RubyProgress::Utils.display_completion(
         final_msg,
         success: success,
-        show_checkmark: options[:checkmark]
+        show_checkmark: options[:checkmark],
+        icons: { success: options[:success_icon], error: options[:error_icon] }
       )
     end
 
@@ -60,7 +79,8 @@ module TwirlRunner
         RubyProgress::Utils.display_completion(
           options[:success] || 'Complete',
           success: true,
-          show_checkmark: options[:checkmark]
+          show_checkmark: options[:checkmark],
+          icons: { success: options[:success_icon], error: options[:error_icon] }
         )
       end
     end
@@ -82,6 +102,41 @@ module TwirlRunner
 
     begin
       RubyProgress::Utils.hide_cursor
+
+      # Start job processor thread for twirl
+      job_dir = RubyProgress::Daemon.job_dir_for_pid(pid_file)
+      job_thread = Thread.new do
+        RubyProgress::Daemon.process_jobs(job_dir) do |job|
+          oc = RubyProgress::OutputCapture.new(
+            command: job['command'],
+            lines: options[:output_lines] || 3,
+            position: options[:output_position] || :above
+          )
+          oc.start
+
+          spinner.instance_variable_set(:@output_capture, oc)
+          oc.wait
+          captured = oc.lines.join("\n")
+          exit_status = oc.exit_status
+          spinner.instance_variable_set(:@output_capture, nil)
+
+          success = exit_status.to_i.zero?
+          if job['message']
+            RubyProgress::Utils.display_completion(
+              job['message'],
+              success: success,
+              show_checkmark: job['checkmark'] || false,
+              output_stream: :stdout,
+              icons: { success: options[:success_icon], error: options[:error_icon] }
+            )
+          end
+
+          { 'exit_status' => exit_status, 'output' => captured }
+        rescue StandardError
+          # ignore
+        end
+      end
+
       spinner.animate until stop_requested
     ensure
       RubyProgress::Utils.clear_line
@@ -100,7 +155,8 @@ module TwirlRunner
               message,
               success: success_val,
               show_checkmark: check,
-              output_stream: :stdout
+              output_stream: :stdout,
+              icons: { success: options[:success_icon], error: options[:error_icon] }
             )
           end
         rescue StandardError
@@ -114,6 +170,7 @@ module TwirlRunner
         end
       end
 
+      job_thread&.kill
       FileUtils.rm_f(pid_file)
     end
   end

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

@@ -10,14 +10,29 @@ require_relative '../utils'
 class TwirlSpinner
   def initialize(message, options = {})
     @message = message
-    @style = parse_style(options[:style] || 'dots')
     @speed = parse_speed(options[:speed] || 'medium')
-    @frames = RubyProgress::INDICATORS[@style] || RubyProgress::INDICATORS[:dots]
+
+    style_opt = options[:style].to_s
+    if style_opt.start_with?('custom=')
+      chars = style_opt.sub('custom=', '')
+      @frames = if chars.length >= 3
+                  chars.chars
+                elsif chars.length == 2
+                  [chars[0], chars[1], chars[1]]
+                else
+                  [chars, chars, chars]
+                end
+      @style = :custom
+    else
+      @style = parse_style(style_opt.empty? ? 'dots' : style_opt)
+      @frames = RubyProgress::INDICATORS[@style] || RubyProgress::INDICATORS[:dots]
+    end
     @start_chars, @end_chars = RubyProgress::Utils.parse_ends(options[:ends])
     @index = 0
   end
 
   def animate
+    @output_capture&.redraw($stderr)
     if @message && !@message.empty?
       $stderr.print "\r\e[2K#{@start_chars}#{@message} #{@frames[@index]}#{@end_chars}"
     else
@@ -35,6 +50,8 @@ class TwirlSpinner
 
     style_lower = style_input.to_s.downcase.strip
 
+    # parse_style returns a symbol key for RubyProgress::INDICATORS
+
     indicator_keys = RubyProgress::INDICATORS.keys.map(&:to_s)
     return style_lower.to_sym if indicator_keys.include?(style_lower)
 

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

@@ -6,6 +6,14 @@ require_relative 'worm_options'
 
 # Enhanced Worm CLI (extracted from bin/prg)
 module WormCLI
+  def self.resolve_pid_file(options, name_key = :daemon_name)
+    return options[:pid_file] if options[:pid_file]
+
+    return "/tmp/ruby-progress/#{options[name_key]}.pid" if options[name_key]
+
+    RubyProgress::Daemon.default_pid_file
+  end
+
   def self.run
     options = WormCLI::Options.parse_cli_options
 
@@ -25,8 +33,14 @@ module WormCLI
       )
       exit
     elsif options[:daemon]
-      # Detach before starting daemon logic so there's no tracked shell job
-      PrgCLI.daemonize
+      # Detach (or background without detaching) before starting daemon logic
+      # so the invoking shell/script continues immediately.
+      if options[:no_detach]
+        PrgCLI.backgroundize
+      else
+        PrgCLI.daemonize
+      end
+
       run_daemon_mode(options)
     else
       progress = RubyProgress::Worm.new(options)
@@ -47,29 +61,57 @@ module WormCLI
     progress = RubyProgress::Worm.new(options)
 
     begin
+      # Start job processor thread for worm
+      job_dir = RubyProgress::Daemon.job_dir_for_pid(pid_file)
+      job_thread = Thread.new do
+        RubyProgress::Daemon.process_jobs(job_dir) do |job|
+          jid = job['id'] || SecureRandom.uuid
+          log_path = begin
+            File.join(File.dirname(job_dir), "#{jid}.log")
+          rescue StandardError
+            nil
+          end
+
+          oc = RubyProgress::OutputCapture.new(
+            command: job['command'],
+            lines: options[:output_lines] || 3,
+            position: options[:output_position] || :above,
+            log_path: log_path
+          )
+          oc.start
+
+          progress.instance_variable_set(:@output_capture, oc)
+          oc.wait
+          captured = oc.lines.join("\n")
+          exit_status = oc.exit_status
+          progress.instance_variable_set(:@output_capture, nil)
+
+          success = exit_status.to_i.zero?
+          if job['message']
+            RubyProgress::Utils.display_completion(
+              job['message'],
+              success: success,
+              show_checkmark: job['checkmark'] || false,
+              output_stream: :stdout,
+              icons: { success: options[:success_icon], error: options[:error_icon] }
+            )
+          end
+
+          { 'exit_status' => exit_status, 'output' => captured, 'log_path' => log_path }
+        rescue StandardError
+          # ignore per-job errors
+        end
+      end
+
       progress.run_daemon_mode(
         success_message: options[:success],
         show_checkmark: options[:checkmark],
-        control_message_file: RubyProgress::Daemon.control_message_file(pid_file)
+        control_message_file: RubyProgress::Daemon.control_message_file(pid_file),
+        icons: { success: options[:success_icon], error: options[:error_icon] }
       )
     ensure
+      job_thread&.kill
       FileUtils.rm_f(pid_file)
     end
   end
-
-  def self.resolve_pid_file(options, name_key)
-    return options[:pid_file] if options[:pid_file]
-
-    if options[name_key]
-      "/tmp/ruby-progress/#{options[name_key]}.pid"
-    else
-      RubyProgress::Daemon.default_pid_file
-    end
-  end
-
-  # parse_cli_options is intentionally kept together; further extraction possible
-  # parse_cli_options is intentionally delegated to WormCLI::Options
-  def self.parse_cli_options
-    WormCLI::Options.parse_cli_options
-  end
 end

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

@@ -9,8 +9,11 @@ module WormCLI
   # the main dispatcher to keep the CLI module small and focused.
   module Options
     def self.parse_cli_options
-      options = {}
-
+      options = {
+        output_position: :above,
+        output_lines: 3
+      }
+      # rubocop:disable Metrics/BlockLength
       begin
         OptionParser.new do |opts|
           opts.banner = 'Usage: prg worm [options]'
@@ -48,10 +51,26 @@ module WormCLI
             options[:command] = command
           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.on('--success MESSAGE', 'Success message to display') do |text|
             options[:success] = text
           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') do |text|
             options[:error] = text
           end
@@ -76,6 +95,16 @@ module WormCLI
             options[:daemon_name] = name
           end
 
+          # Accept --daemon-name as an alias for --daemon-as for compatibility
+          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', 'Write process ID to file (default: /tmp/ruby-progress/progress.pid)') do |file|
             options[:pid_file] = file
           end
@@ -149,7 +178,7 @@ module WormCLI
         puts "Run 'prg worm --help' for more information."
         exit 1
       end
-
+      # rubocop:enable Metrics/BlockLength
       options
     end
   end

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

@@ -4,6 +4,7 @@
 require 'open3'
 require 'json'
 require_relative '../utils'
+require_relative '../output_capture'
 
 # Runtime helper methods for RubyProgress::Worm
 #
@@ -56,21 +57,36 @@ module WormRunner
     stdout_content = nil
 
     begin
-      stdout_content = animate do
-        Open3.popen3(@command) do |_stdin, stdout, stderr, wait_thr|
-          captured_stdout = stdout.read
-          stderr_content = stderr.read
-          exit_code = wait_thr.value.exitstatus
-
-          unless wait_thr.value.success?
-            error_msg = @error_text || "Command failed with exit code #{exit_code}"
-            error_msg += ": #{stderr_content.strip}" if stderr_content && !stderr_content.empty?
-            raise StandardError, error_msg
-          end
-
-          captured_stdout
-        end
-      end
+      stdout_content = if $stdout.tty? && @output_stdout
+                         oc = RubyProgress::OutputCapture.new(
+                           command: @command,
+                           lines: @output_lines || 3,
+                           position: @output_position || :above
+                         )
+                         oc.start
+                         @output_capture = oc
+                         animate do
+                           oc.wait
+                         end
+                         @output_capture = nil
+                         oc.lines.join("\n")
+                       else
+                         animate do
+                           Open3.popen3(@command) do |_stdin, stdout, stderr, wait_thr|
+                             captured_stdout = stdout.read
+                             stderr_content = stderr.read
+                             exit_code = wait_thr.value.exitstatus
+
+                             unless wait_thr.value.success?
+                               error_msg = @error_text || "Command failed with exit code #{exit_code}"
+                               error_msg += ": #{stderr_content.strip}" if stderr_content && !stderr_content.empty?
+                               raise StandardError, error_msg
+                             end
+
+                             captured_stdout
+                           end
+                         end
+                       end
 
       puts stdout_content if @output_stdout && stdout_content
     rescue StandardError
@@ -103,7 +119,7 @@ module WormRunner
     @running = false
   end
 
-  def run_daemon_mode(success_message: nil, show_checkmark: false, control_message_file: nil)
+  def run_daemon_mode(success_message: nil, show_checkmark: false, control_message_file: nil, icons: {})
     @running = true
     stop_requested = false
 
@@ -146,7 +162,8 @@ module WormRunner
           final_message,
           success: final_success,
           show_checkmark: final_checkmark,
-          output_stream: :stdout
+          output_stream: :stdout,
+          icons: icons
         )
       end
 
@@ -161,6 +178,7 @@ module WormRunner
     @direction ||= 1
 
     message_part = @message && !@message.empty? ? "#{@message} " : ''
+    @output_capture&.redraw($stderr)
     $stderr.print "\r\e[2K#{@start_chars}#{message_part}#{generate_dots(@position, @direction)}#{@end_chars}"
     $stderr.flush
 
@@ -184,6 +202,7 @@ module WormRunner
 
     while @running
       message_part = @message && !@message.empty? ? "#{@message} " : ''
+      @output_capture&.redraw($stderr)
       $stderr.print "\r\e[2K#{@start_chars}#{message_part}#{generate_dots(position, direction)}#{@end_chars}"
       $stderr.flush
 
@@ -209,6 +228,7 @@ module WormRunner
 
     while @running && !stop_requested_proc.call
       message_part = @message && !@message.empty? ? "#{@message} " : ''
+      @output_capture&.redraw($stderr)
 
       $stderr.print "\r\e[2K"