ruby-progress 1.2.4 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 446ecad2fd85e194293130a638b9e986270c5849ad5cd8a65733b5c2f01198df
-  data.tar.gz: 35686adf5664171676333a89d48f3f296dcc03751636eea49711a3885ea86d4d
+  metadata.gz: 5c5a7ddc53059cb7f6d2b7bd1c066653058e1dbb281f4c23aa04229ce360a594
+  data.tar.gz: 0446a713142b93f16b9fe3e102c8a3c0db3194db17da25de7f1f7f31e5090907
 SHA512:
-  metadata.gz: d5cd10f336fae3e523e00c70bc9939f6b4162b1b9473424e1c481b0aa9f077b5f0e08037bb53f96f23f5d07a38a0ac5c72947daf90d545127736f002db692c77
-  data.tar.gz: 86f820e4b75c810e45801f1a214d219f7103e386e4c53bd733eb22a231a3162900b0b011c566f2d134b0a78e06947d33ddf1e2f9fea5c8a35552f56bc4b1f7e0
+  metadata.gz: 3cda8e32c95b8bd03d6c8549de1b3f4fc488f868cb028a554ddc44654428978bfd1db4178a1cb0a0a71c9a0c8ea46a1cc8da844c4026ef9b84ed45c1b43f4691
+  data.tar.gz: 39c31e85f87ea2201cbf3267fefedff1f4946f6bef9b1ee6178b8e1b5ecf8569a8391c20519582a1077bd6d352d229b01997ceedb358eeb049cf484c895028ed

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-10-09 14:47:16 UTC using RuboCop version 1.75.7.
+# on 2025-10-13 12:49:46 UTC using RuboCop version 1.75.7.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -22,11 +22,10 @@ Layout/TrailingEmptyLines:
   Exclude:
     - 'test_worm_flags.rb'
 
-# Offense count: 4
+# Offense count: 2
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
-    - 'bin/prg'
     - 'lib/ruby-progress/utils.rb'
     - 'lib/ruby-progress/worm.rb'
 
@@ -36,6 +35,12 @@ Lint/EmptyBlock:
   Exclude:
     - 'spec/worm_integration_spec.rb'
 
+# Offense count: 1
+# Configuration parameters: MaximumRangeSize.
+Lint/MissingCopEnableDirective:
+  Exclude:
+    - 'lib/ruby-progress/fill_cli.rb'
+
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Lint/ScriptPermission:
@@ -43,63 +48,49 @@ Lint/ScriptPermission:
     - 'demo_gem.rb'
     - 'demo_worm_infinite.rb'
 
-# Offense count: 1
-Lint/SelfAssignment:
-  Exclude:
-    - 'lib/ruby-progress/ripple.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
-# NotImplementedExceptions: NotImplementedError
-Lint/UnusedMethodArgument:
-  Exclude:
-    - 'lib/ruby-progress/worm.rb'
-
-# Offense count: 23
+# Offense count: 22
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AutoCorrect.
 Lint/UselessAssignment:
   Exclude:
     - 'demo_gem.rb'
-    - 'lib/ruby-progress/worm.rb'
     - 'spec/cli_integration_spec.rb'
 
-# Offense count: 20
+# Offense count: 52
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 114
+  Max: 122
 
-# Offense count: 17
+# Offense count: 49
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 109
+  Max: 111
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 254
+  Max: 268
 
-# Offense count: 12
+# Offense count: 30
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 19
+  Max: 26
 
-# Offense count: 31
+# Offense count: 68
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 131
+  Max: 156
 
-# Offense count: 3
+# Offense count: 9
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 206
+  Max: 285
 
-# Offense count: 10
+# Offense count: 31
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 20
+  Max: 27
 
 # Offense count: 1
 # Configuration parameters: ExpectMatchingDefinition, CheckDefinitionPathHierarchy, CheckDefinitionPathHierarchyRoots, Regex, IgnoreExecutableScripts, AllowedAcronyms.
@@ -110,7 +101,7 @@ Naming/FileName:
     - 'Rakefile.rb'
     - 'lib/ruby-progress.rb'
 
-# Offense count: 17
+# Offense count: 10
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
 # AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
@@ -127,15 +118,6 @@ Style/Documentation:
     - 'lib/ruby-progress.rb'
     - 'lib/ruby-progress/daemon.rb'
 
-# Offense count: 4
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: allowed_in_returns, forbidden
-Style/DoubleNegation:
-  Exclude:
-    - 'bin/prg'
-    - 'lib/ruby-progress/worm.rb'
-
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AutoCorrect, EnforcedStyle, AllowComments.
@@ -167,14 +149,13 @@ Style/InfiniteLoop:
   Exclude:
     - 'lib/ruby-progress/ripple.rb'
 
-# Offense count: 2
+# Offense count: 1
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
 # SupportedStyles: predicate, comparison
 Style/NumericPredicate:
   Exclude:
     - 'spec/**/*'
-    - 'bin/prg'
     - 'lib/ruby-progress/ripple.rb'
 
 # Offense count: 1
@@ -193,7 +174,7 @@ Style/StringLiterals:
   Exclude:
     - 'test_worm_flags.rb'
 
-# Offense count: 3
+# Offense count: 39
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https

data/CHANGELOG.md

@@ -1,4 +1,3 @@
-
 # CHANGELOG
 
 All notable changes to this project will be documented in this file.
@@ -6,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.3.0 - 2025-10-12
+
+### Added
+
+- PTY-based output capture: `RubyProgress::OutputCapture` now allows running commands under a PTY, keeps a rolling buffer of the last N lines for live redraw, and optionally writes the full streamed output to a `log_path` file.
+- File-based daemon job queue: `RubyProgress::Daemon.process_jobs` implements atomic job enqueue/claim/processing with `.processing.result` metadata files and processed-archive behavior.
+- `prg job send` CLI helper: atomically writes jobs to daemon job dirs and supports `--wait` to poll for results, `--daemon-name`, `--pid-file`, `--stdin`, and `--timeout`.
+- Integration of job processing into Ripple/Twirl/Worm daemon modes so a running daemon can accept and display job output without interrupting animations.
+- CLI options for output handling: `--output-position` and `--output-lines` to reserve terminal rows for captured output.
+
+### Changed
+
+- Job result files now merge any Hash returned by the job handler into the `.processing.result` JSON (e.g., `exit_status`, `output`, `log_path`).
+
+### Tests
+
+- Added unit and integration tests covering job enqueueing, processing, and result persistence.
+
+### Release notes
+
+- Merge commit: 99d9c39 (squash-merge of feature/output-handling)
+
+## 1.3.2 - 2025-10-13
+
+### Added
+
+- `fill` subcommand: added `-c, --command COMMAND` so the determinate progress bar can run and capture command output like the other subcommands. This includes `--output-lines` and `--output-position` support for reserving terminal rows during capture.
+
+### Changed
+
+- Added `--stop-id NAME` shorthand for targeting named daemons (implies `--stop` and normalizes the name to the canonical PID filename). This is a small convenience used by the demo and scripts.
+- Demo: updated `demo_screencast.rb` to call the local `bin/prg` when stopping the demo daemon to avoid conflicts with system-installed versions.
+
+### Changed
+
+- Bumped `FILL_VERSION` (patch) to reflect the new CLI behavior.
+
+
 ## 1.2.3 - 2025-10-11
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-progress (1.2.4)
+    ruby-progress (1.3.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -8,6 +8,27 @@
 
 This repository contains three different Ruby progress indicator projects: **Ripple**, **Worm**, and **Twirl**. All provide animated terminal progress indicators with different visual styles and features.
 
+## Table of Contents
+
+- [Unified Interface](#unified-interface)
+  - [Submitting jobs to a running daemon](#submitting-jobs-to-a-running-daemon)
+- [Job result schema](#job-result-schema)
+- [Example: start a daemon and send a job (simple)](#example-start-a-daemon-and-send-a-job-simple)
+- [Ripple](#ripple)
+  - [Ripple Features](#ripple-features)
+  - [Ripple Usage](#ripple-usage)
+- [Twirl](#twirl)
+- [Worm](#worm)
+  - [Daemon mode (background indicator)](#daemon-mode-background-indicator)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Universal Utilities](#universal-utilities)
+  - [Terminal Control](#terminal-control)
+  - [Completion Messages](#completion-messages)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Unified Interface
 
 The gem provides a unified `prg` command that supports all progress indicators through subcommands:
@@ -30,12 +51,12 @@ prg twirl --message "Working..." --style dots --speed fast
 
 # Run fill directly (delegates to prg)
 fill --report --percent 50
-```
 
 ### With command execution
 prg worm --command "sleep 5" --success "Completed!" --error "Failed!" --checkmark
 prg ripple "Building..." --command "make build" --success "Build complete!" --stdout
 prg twirl --command "npm install" --message "Installing packages" --style arc
+prg fill --command "sleep 5" --success "Done!" --checkmark
 
 ### With start/end character decoration using --ends
 prg ripple "Loading data" --ends "[]" --style rainbow
@@ -49,160 +70,123 @@ prg worm --message "Magic" --ends "🎯🎪" --style "custom=🟦🟨🟥"
 ### Global Options
 
 - `prg --help` - Show main help
-- `prg --version` - Show version info
-- `prg --list-styles` - Show all available styles for all subcommands
-- `prg <subcommand> --help` - Show specific subcommand help
 
-### Common Options (available for all subcommands)
+Notes:
 
-- `--speed SPEED` - Animation speed (fast/medium/slow or f/m/s)
-- `--message MESSAGE` - Message to display
-- `--command COMMAND` - Command to execute during animation
-- `--success MESSAGE` - Success message after completion
-- `--error MESSAGE` - Error message on failure
-- `--checkmark` - Show checkmarks (✅ success, 🛑 failure)
-- `--stdout` - Output command results to STDOUT
-- `--ends CHARS` - Start/end characters (even number of chars, split in half)
+- The CLI detaches itself (double-fork); do not append `&`. This prevents shell job notifications like “job … has ended.” The command returns immediately.
+- `--stop-success` and `--stop-error` are mutually exclusive; whichever you provide determines the success state and icon if `--stop-checkmark` is set.
+- The indicator clears its line on shutdown and prints the final message to STDOUT.
+- `--stop-pid` is still supported for backward compatibility, but `--stop [--pid-file FILE]` is preferred.
 
-### Daemon Mode (Background Progress)
+### Submitting jobs to a running daemon
 
-For shell scripts where you need a continuous progress indicator across multiple steps, use daemon mode. You can use named daemons or custom PID files.
+When running a long-lived daemon (for example `prg worm --daemon`), you can submit additional commands to run and have their output displayed without disrupting the animation using the `prg job send` helper.
+
+Basic usage:
 
 ```bash
-### Start in background (uses default PID file)
-prg worm --daemon --message "Working..."
+# Enqueue a command to the default daemon PID
+prg job send --command "./deploy-step.sh"
 
-### Start with a custom name (creates /tmp/ruby-progress/NAME.pid)
-prg worm --daemon-as mytask --message "Processing data..."
+# Enqueue to a named daemon (creates /tmp/ruby-progress/<name>.pid)
+prg job send --daemon-name mytask --command "rsync -av ./dist/ user@host:/srv/app"
 
-### ... run your tasks ...
+# Read command from stdin (useful in scripts)
+echo "bundle exec rake db:migrate" | prg job send --stdin --daemon-name mytask
 
-### Stop with a success message and checkmark (--stop-success implies --stop)
-prg worm --stop-success "All done" --stop-checkmark
+# Wait for the job result and print the job result JSON (default timeout 10s)
+prg job send --daemon-name mytask --command "./deploy-step.sh" --wait --timeout 30
+```
 
-### Stop a named daemon (--stop-id implies --stop)
-prg worm --stop-id mytask --stop-success "Task complete!" --stop-checkmark
+You can also send control/action jobs (no shell command) to a running daemon. These are JSON payloads with an `action` key handled by the daemon's job processor. The helper supports a few common actions:
 
-### Or stop with an error message and checkmark
-prg worm --stop-error "Failed during step" --stop-checkmark
+```bash
+# Send a simple 'advance' action (no value)
+prg job send --daemon-name demo --advance
+
+# Send a 'percent' action with a numeric value
+prg job send --daemon-name demo --percent 42
 
-### Check status at any time
-prg worm --status
-prg worm --status-id mytask
+# Example using `fill` as a named daemon and sending percent updates
+```bash
+# Start a named fill worker (non-detaching so animation remains visible)
+prg fill --daemon-as demo --no-detach --output-lines 3 --output-position top
 
-### Use a completely custom PID file path
-prg worm --daemon --pid-file /tmp/custom-progress.pid
-prg worm --status --pid-file /tmp/custom-progress.pid
-prg worm --stop-success "Complete" --pid-file /tmp/custom-progress.pid
+# Send percent updates to the named worker
+prg job send --daemon-name demo --percent 10 --wait
+prg job send --daemon-name demo --percent 50 --wait
+prg job send --daemon-name demo --percent 100 --wait
 ```
 
-Notes:
+# Or use the generic action/value pair
+prg job send --daemon-name demo --action percent --value 42
+```
 
-- The CLI detaches itself (double-fork); do not append `&`. This prevents shell job notifications like “job … has ended.” The command returns immediately.
-- `--stop-success` and `--stop-error` are mutually exclusive; whichever you provide determines the success state and icon if `--stop-checkmark` is set.
-- The indicator clears its line on shutdown and prints the final message to STDOUT.
-- `--stop-pid` is still supported for backward compatibility, but `--stop [--pid-file FILE]` is preferred.
-o- [Ruby Progress Indicators](#ruby-progress-indicators)
-- [Unified Interface](#unified-interface)
-  - [With command execution](#with-command-execution)
-  - [With start/end character decoration using --ends](#with-startend-character-decoration-using-ends)
-  - [Complex --ends patterns with emojis](#complex-ends-patterns-with-emojis)
-  - [Start in background (uses default PID file)](#start-in-background-uses-default-pid-file)
-  - [Start with a custom name (creates /tmp/ruby-progress/NAME.pid)](#start-with-a-custom-name-creates-tmpruby-progressnamepid)
-  - [... run your tasks ...](#-run-your-tasks-)
-  - [Stop with a success message and checkmark (--stop-success implies --stop)](#stop-with-a-success-message-and-checkmark-stop-success-implies-stop)
-  - [Stop a named daemon (--stop-id implies --stop)](#stop-a-named-daemon-stop-id-implies-stop)
-  - [Or stop with an error message and checkmark](#or-stop-with-an-error-message-and-checkmark)
-  - [Check status at any time](#check-status-at-any-time)
-  - [Use a completely custom PID file path](#use-a-completely-custom-pid-file-path)
-  - [Basic text animation](#basic-text-animation)
-  - [With style options](#with-style-options)
-  - [Multiple styles combined](#multiple-styles-combined)
-  - [Case transformation mode](#case-transformation-mode)
-  - [Run a command with progress animation](#run-a-command-with-progress-animation)
-  - [Simple progress block](#simple-progress-block)
-  - [With options](#with-options)
-  - [Basic spinner animation](#basic-spinner-animation)
-  - [With command execution](#with-command-execution)
-  - [Different spinner styles](#different-spinner-styles)
-  - [With success/error handling](#with-successerror-handling)
-  - [Daemon mode for background tasks](#daemon-mode-for-background-tasks)
-  - [... do other work ...](#-do-other-work-)
-  - [Run indefinitely without a command (like ripple)](#run-indefinitely-without-a-command-like-ripple)
-  - [Run a command with progress animation](#run-a-command-with-progress-animation)
-  - [Customize the animation](#customize-the-animation)
-  - [With custom error handling](#with-custom-error-handling)
-  - [With checkmarks for visual feedback](#with-checkmarks-for-visual-feedback)
-  - [Control animation direction (forward-only or bidirectional)](#control-animation-direction-forward-only-or-bidirectional)
-  - [Create custom animations with 3-character patterns](#create-custom-animations-with-3-character-patterns)
-  - [Add start/end characters around the animation](#add-startend-characters-around-the-animation)
-  - [Capture and display command output](#capture-and-display-command-output)
-  - [Combine checkmarks and stdout output](#combine-checkmarks-and-stdout-output)
-  - [Start in the background (default PID file: /tmp/ruby-progress/progress.pid)](#start-in-the-background-default-pid-file-tmpruby-progressprogresspid)
-  - [... run your tasks ...](#-run-your-tasks-)
-  - [Stop using the default PID file](#stop-using-the-default-pid-file)
-  - [Use a custom PID file](#use-a-custom-pid-file)
-  - [Stop using the matching custom PID file](#stop-using-the-matching-custom-pid-file)
-  - [Create and run animation with a block](#create-and-run-animation-with-a-block)
-  - [Your work here](#your-work-here)
-  - [With custom style and forward direction](#with-custom-style-and-forward-direction)
-  - [Or run with a command](#or-run-with-a-command)
-  - [ASCII characters](#ascii-characters)
-  - [Unicode characters](#unicode-characters)
-  - [Emojis (supports multi-byte characters)](#emojis-supports-multi-byte-characters)
-  - [Mixed ASCII and emoji](#mixed-ascii-and-emoji)
-  - [Cursor control](#cursor-control)
-  - [Basic completion message](#basic-completion-message)
-  - [With success/failure indication and checkmarks](#with-successfailure-indication-and-checkmarks)
-  - [Clear line and display completion (useful for replacing progress indicators)](#clear-line-and-display-completion-useful-for-replacing-progress-indicators)
+Note about stopping named daemons:
 
-## Table of Contents
+You can target named daemons directly using the `--stop-id NAME` shorthand which implies `--stop` and targets the named daemon (it is normalized to the canonical daemon name used for the PID file). This is convenient for scripts and demos. Example:
 
-- [Ruby Progress Indicators](#ruby-progress-indicators)
-  - [Unified Interface](#unified-interface)
-    - [With command execution](#with-command-execution)
-    - [With start/end character decoration using --ends](#with-startend-character-decoration-using---ends)
-    - [Complex --ends patterns with emojis](#complex---ends-patterns-with-emojis)
-  - [Table of Contents](#table-of-contents)
-  - [Ripple](#ripple)
-    - [Ripple Features](#ripple-features)
-    - [Ripple Usage](#ripple-usage)
-      - [Ripple CLI examples](#ripple-cli-examples)
-      - [Ripple Command Line Options](#ripple-command-line-options)
-    - [Ripple Library Usage](#ripple-library-usage)
-  - [Twirl](#twirl)
-    - [Twirl Features](#twirl-features)
-    - [Twirl Usage](#twirl-usage)
-      - [Command Line](#command-line)
-      - [Twirl Command Line Options](#twirl-command-line-options)
-    - [Available Spinner Styles](#available-spinner-styles)
-  - [Worm](#worm)
-    - [Worm Features](#worm-features)
-    - [Worm Usage](#worm-usage)
-      - [Command Line](#command-line-1)
-      - [Daemon mode (background indicator)](#daemon-mode-background-indicator)
-      - [Worm Command Line Options](#worm-command-line-options)
-    - [Worm Library Usage](#worm-library-usage)
-    - [Animation Styles](#animation-styles)
-      - [Circles](#circles)
-      - [Blocks](#blocks)
-      - [Geometric](#geometric)
-      - [Custom Styles](#custom-styles)
-      - [Direction Control](#direction-control)
-  - [Requirements](#requirements)
-  - [Installation](#installation)
-    - [As a Gem (Recommended)](#as-a-gem-recommended)
-    - [From Source](#from-source)
-    - [Development](#development)
-  - [Universal Utilities](#universal-utilities)
-    - [Terminal Control](#terminal-control)
-    - [Completion Messages](#completion-messages)
-  - [Contributing](#contributing)
-  - [License](#license)
+```bash
+# Stop a named fill worker with a success message
+prg fill --stop-id demo --stop-success 'Demo finished'
+```
+
+Behavior and file layout:
+
+- Jobs are written as JSON files into the daemon's job directory, which is derived from the daemon PID file. For example, a PID file `/tmp/ruby-progress/mytask.pid` maps to the job directory `/tmp/ruby-progress/mytask.jobs`.
+- The CLI writes the job atomically by first writing a `*.json.tmp` temporary file and then renaming it to `*.json`.
+- The daemon's job processor claims jobs atomically by renaming the job file to `*.processing`, writes a `*.processing.result` JSON file when finished, and moves processed jobs to `processed-*`.
+
+This mechanism allows you to submit many commands to a single running indicator and have their output shown in reserved terminal rows while the animation continues.
+
+## Job result schema
+
+When a job is processed the daemon writes a small JSON result file next to the claimed job with the suffix `.processing.result` containing at least these keys:
+
+- `id` - the job id (string)
+- `status` - `"done"` or `"error"`
+- `time` - epoch seconds when the job finished (integer)
+
+Depending on the job handler, additional keys may be present:
+
+- `exit_status` - the numeric process exit status (integer or nil if unknown)
+- `output` - a string with the last captured lines of output (if available)
+- `error` - an error message when `status` is `error`
+
+Example:
+
+```json
+{
+  "id": "8a1f6c1e-4b7a-4f2c-b0a8-9e9f1c2f1a2b",
+  "status": "done",
+  "time": 1634044800,
+  "exit_status": 0,
+  "output": "Step 1 completed\nStep 2 completed"
+}
+```
 
+This file is intended for short messages and small captured output snippets (the CLI captures the last N lines). If you need larger logs, write them to a persistent file from the command itself and include a reference in the job metadata.
 
+## Example: start a daemon and send a job (simple)
+
+Below is an example script that demonstrates starting a worm daemon, sending a job, waiting for the result, and stopping the daemon.
 ---
 
+If you want the background worker to continue writing to the same terminal (so you can visually watch the animation while your script continues), use the non-detaching background mode:
+
+```bash
+# Start a named worm worker that backgrounds but does not fully detach
+prg worm --daemon-as demo --no-detach
+
+# In the same script or a subsequent command, enqueue a job to that worker
+prg job send --daemon-name demo --command "echo hello; sleep 1; echo done" --wait
+
+# Stop the worker with a success message
+prg worm --stop-id demo --stop-success "Demo finished"
+```
+
+Note: Non-detaching mode keeps the child process attached to the controlling TTY. That means both the worker and the invoking shell may write to the terminal and outputs can interleave.
+
 ## Ripple
 
 Ripple is a sophisticated text animation library that creates ripple effects across text strings in the terminal. It supports various animation modes including bidirectional movement, and rainbow colors.
@@ -407,6 +391,15 @@ prg worm --message "Emoji ends" --ends "🎯🎪" --style "custom=🟦🟨🟥"
 ### Capture and display command output
 prg worm --command "git status" --message "Checking status" --stdout
 
+You can reserve terminal rows for captured command output so the animation doesn't interleave with the script output. Use:
+
+- `--output-position POSITION` — `above` (default) or `below` the animation
+- `--output-lines N` — how many terminal rows to reserve for captured output (default: 3)
+
+Examples:
+
+prg worm --command "git status" --stdout --output-position above --output-lines 4
+
 ### Combine checkmarks and stdout output
 prg worm --command "echo 'Build output'" --success "Build complete!" --checkmark --stdout
 ```

data/Rakefile

@@ -108,7 +108,6 @@ namespace :markdown do
     !!(line =~ /^\s*```|^\s*~~~/)
   end
 
-  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   def format_markdown(content)
     lines = content.split("\n", -1)
     out = []
@@ -167,8 +166,6 @@ namespace :markdown do
     out << '' if (last = out.last) && !last.empty?
     out.join("\n")
   end
-  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-
   desc 'Lint markdown (reports files that would be changed)'
   task :lint do
     changed = []

data/bin/prg

@@ -7,6 +7,7 @@ require 'optparse'
 require 'json'
 require 'English'
 
+require_relative '../lib/ruby-progress/cli/job_cli'
 # Load extracted per-subcommand CLI modules
 require_relative '../lib/ruby-progress/cli/ripple_cli'
 require_relative '../lib/ruby-progress/cli/worm_cli'
@@ -20,6 +21,18 @@ module PrgCLI
       exit 1
     end
 
+    # Handle `job` subcommands early
+    if ARGV[0] && ARGV[0].downcase == 'job'
+      ARGV.shift
+      sub = ARGV.shift
+      case sub
+      when 'send'
+        JobCLI.send(ARGV)
+      else
+        puts 'job subcommands: send'
+        exit 1
+      end
+    end
     # Early scan: detect --ends flag and validate its argument before dispatching
     if (i = ARGV.index('--ends')) && ARGV[i + 1]
       ends_val = ARGV[i + 1]
@@ -113,6 +126,43 @@ module PrgCLI
     puts '== fill =='
   end
 
+  # Detach the current process into a background daemon. Uses Process.daemon
+  # when available, otherwise falls back to a basic fork/exit helper. This is
+  # intentionally simple for the test environment.
+  def self.daemonize
+    if Process.respond_to?(:daemon)
+      Process.daemon(true)
+    else
+      pid = fork
+      if pid
+        # parent exits so child can continue as daemon
+        exit(0)
+      else
+        # child: detach from controlling terminal
+        begin
+          Process.setsid
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+
+  # Spawn a background child but do NOT fully detach from the controlling
+  # terminal. This keeps the child attached to the same TTY so animations
+  # remain visible, while the parent exits immediately allowing the caller
+  # (shell or script) to continue. Use when the user requests a non-detaching
+  # background worker (e.g. `--daemon-as NAME --no-detach`).
+  def self.backgroundize
+    pid = fork
+    return unless pid
+
+    # parent: exit so the invoking shell/script continues
+    exit(0)
+
+    # child: continue without setsid/IO close so output remains on the TTY
+  end
+
   # Attempt to stop processes for the given subcommand. Return true if any
   # process was signaled/stopped; false otherwise. Keep quiet on missing
   # processes to satisfy integration tests.