ruby-progress 1.2.4 → 1.3.2

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,12 @@ 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,12 +70,12 @@ 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 4' --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 10 --command 'sleep 5' --success 'Processing finished!' --checkmark --message 'Loading'")
     pause_between_demos
 
     # Twirl - spinning indicator
@@ -83,31 +90,27 @@ 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'")
+    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Default style' 'Rippling Progress 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 --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! 🎉'")
+    run_command("#{ruby_cmd} worm --length 10 --style classic --command 'sleep 4' --success 'Classic worm' --message 'Classic'")
     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'")
+    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'")
+    run_command("#{ruby_cmd} twirl --style classic --command 'sleep 3' --success 'Classic spin' --message 'Loading'")
     pause_between_demos(2)
 
     show_command_info('Dots spinner')
@@ -115,7 +118,7 @@ class ProgressDemo
     pause_between_demos(2)
 
     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 3' --success 'Arrow spin' --message 'Loading'")
     pause_between_demos
   end
 
@@ -125,17 +128,17 @@ 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 2 && exit 1' --error 'Something went wrong!' --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")
+    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Data synchronized successfully' --checkmark --message 'Syncing data...'")
     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} twirl --command 'sleep 3' --success 'Backup completed' --success-icon '✓' --checkmark")
     pause_between_demos
 
     # No completion message
@@ -151,7 +154,7 @@ class ProgressDemo
     # 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!'")
+    run_command("#{ruby_cmd} ripple --ends '[]' --command 'sleep 4' --success 'Framed ripple!' 'With a frame'")
     pause_between_demos(2)
 
     show_command_info("Worm with angle brackets: --ends '<<>>'")
@@ -194,11 +197,95 @@ class ProgressDemo
     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('Fill --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:')
+    part_a = "#{ruby_cmd} fill --command \"bash -lc 'for i in 1 2 3; do echo line:$i; sleep 1; done'\" "
+    part_b = "--output-lines 3 --output-position top --success 'Captured!' --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,7 +304,8 @@ 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
@@ -228,7 +316,7 @@ class ProgressDemo
     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 +345,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.04)
+    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 = 2)
+    # puts "#{@colors[:dim]}[Pausing #{seconds}s between demos...]#{@colors[:reset]}"
     sleep(seconds)
   end
 end
@@ -278,14 +422,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/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/lib/ruby-progress/cli/fill_options.rb

@@ -23,9 +23,12 @@ module RubyProgress
           stop: false,
           status: false,
           current: false,
+          output_position: :above,
+          output_lines: 3,
           report: false
         }
 
+        # rubocop:disable Metrics/BlockLength
         begin
           OptionParser.new do |opts|
             opts.banner = 'Usage: prg fill [options]'
@@ -44,6 +47,20 @@ module RubyProgress
               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:'
 
@@ -90,6 +107,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
@@ -105,6 +130,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
@@ -113,10 +153,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:'
 
@@ -132,6 +198,7 @@ module RubyProgress
               options[:help] = true
             end
           end.parse!
+        # rubocop:enable Metrics/BlockLength
         rescue OptionParser::InvalidOption => e
           warn "Invalid option: #{e.args.first}"
           warn ''
@@ -139,7 +206,6 @@ module RubyProgress
           warn "Run 'prg fill --help' for more information."
           exit 1
         end
-
         options
       end
 
@@ -173,6 +239,12 @@ module RubyProgress
         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')

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

@@ -0,0 +1,159 @@
+# 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') 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)
+      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
+
+    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 = build_payload(opts, job_id, 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
+
+  # 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