philiprehberger-task_runner 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc3c30fcbfaa30b9fadae49ec53c684fc3d37dbe5412c2fa9c78c1522da43a50
-  data.tar.gz: e1afad6175080317811e29c6c35b8fe677ea7399ed6cac836ae691e99b8f7f5f
+  metadata.gz: 8fb5481d773646ae680a865d98ac5519d57ca677a53e08ce87b05de1e0db978b
+  data.tar.gz: ad16cc33bf847e8a83576e4d794b2554d5c549f370cde3c572a30f0b246e2e5f
 SHA512:
-  metadata.gz: cb7eedfdd788764d5ec22723732e083c54e799a1f40fd5436f0d3358d7fa28a405f8ef6181474e7b1db7a35a7926278f758dca2e8dd0a81a29eacfb6348d717e
-  data.tar.gz: b321900f5f3be20b69a3c761ff4df849ed0957a35f7be46634056cb5de3aa848915fcecad36e75f3021b6243050a47c78b01947f9e29ff9866d2d1858156a0e5
+  metadata.gz: 49d9861467feb9494893096aa551974a02a448db8c42bf2e51ed1c62ee0fb281377afc31d4bec6e49ab317c6803ea22493a8c8437b79af6dfe4b324acb47b074
+  data.tar.gz: 22636d10befe17c115036b5336e2e71597ee07c7f381122dc6e5c3e0356c938dbc765505268b0653a6ec4248bda87924593b250e961c062c37eebff23b647018

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-03-31
+
+### Changed
+- Standardize README badges, support section, and license format
+
+## [0.2.0] - 2026-03-30
+
+### Added
+
+- Signal handling: `run(cmd, signal: :TERM, kill_after: 5)` sends the specified signal on timeout, escalates to SIGKILL after `kill_after` seconds
+- `Result#signal` reports which signal killed the process (`:TERM`, `:KILL`, or `nil`)
+- Input piping: `run(cmd, stdin: "data")` pipes string or IO data to the process's stdin
+- Stderr streaming: two-argument blocks receive `(line, stream)` where stream is `:stdout` or `:stderr`
+- Backward compatible: single-argument blocks still receive only stdout lines
+
 ## [0.1.4] - 2026-03-26
 
 ### Changed

data/README.md

@@ -2,10 +2,9 @@
 
 [![Tests](https://github.com/philiprehberger/rb-task-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-task-runner/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-task_runner.svg)](https://rubygems.org/gems/philiprehberger-task_runner)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-task-runner)](LICENSE)
-[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-task-runner)](https://github.com/philiprehberger/rb-task-runner/commits/main)
 
-Shell command runner with output capture, timeout, and streaming
+Shell command runner with output capture, timeout, streaming, signal handling, and stdin piping
 
 ## Requirements
 
@@ -53,6 +52,29 @@ result = Philiprehberger::TaskRunner.run(
 )
 ```
 
+### Signal Handling
+
+```ruby
+result = Philiprehberger::TaskRunner.run(
+  'long-process',
+  timeout: 30,
+  signal: :TERM,
+  kill_after: 5
+)
+# On timeout: sends SIGTERM first, then SIGKILL after 5 seconds if still running
+# result.signal reports which signal killed the process (:TERM, :KILL, or nil)
+```
+
+### Input Piping
+
+```ruby
+result = Philiprehberger::TaskRunner.run('cat', stdin: "hello world")
+puts result.stdout  # => "hello world"
+
+# Also accepts IO objects
+result = Philiprehberger::TaskRunner.run('wc', '-l', stdin: File.open('data.txt'))
+```
+
 ### Streaming Output
 
 ```ruby
@@ -61,17 +83,30 @@ Philiprehberger::TaskRunner.run('tail', '-f', '/var/log/app.log', timeout: 10) d
 end
 ```
 
+### Stderr Streaming
+
+```ruby
+Philiprehberger::TaskRunner.run('make', 'build') do |line, stream|
+  case stream
+  when :stdout then puts "OUT: #{line}"
+  when :stderr then puts "ERR: #{line}"
+  end
+end
+```
+
 ## API
 
 | Method / Class | Description |
 |----------------|-------------|
-| `.run(cmd, *args, timeout:, env:, chdir:)` | Run a command and return a Result |
+| `.run(cmd, *args, timeout:, env:, chdir:, signal:, kill_after:, stdin:)` | Run a command and return a Result |
 | `.run(cmd) { \|line\| ... }` | Run with line-by-line stdout streaming |
+| `.run(cmd) { \|line, stream\| ... }` | Run with stdout and stderr streaming |
 | `Result#stdout` | Captured standard output |
 | `Result#stderr` | Captured standard error |
 | `Result#exit_code` | Process exit code |
 | `Result#success?` | Whether exit code is 0 |
 | `Result#duration` | Execution time in seconds |
+| `Result#signal` | Signal that killed the process (:TERM, :KILL, or nil) |
 
 ## Development
 
@@ -81,6 +116,24 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this project useful:
+
+⭐ [Star the repo](https://github.com/philiprehberger/rb-task-runner)
+
+🐛 [Report issues](https://github.com/philiprehberger/rb-task-runner/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+
+💡 [Suggest features](https://github.com/philiprehberger/rb-task-runner/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+
+❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)
+
+🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)
+
+💻 [GitHub Profile](https://github.com/philiprehberger)
+
+🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)
+
 ## License
 
 [MIT](LICENSE)

data/lib/philiprehberger/task_runner/result.rb

@@ -16,22 +16,27 @@ module Philiprehberger
       # @return [Float] execution duration in seconds
       attr_reader :duration
 
+      # @return [Symbol, nil] signal that killed the process (:TERM, :KILL, or nil)
+      attr_reader :signal
+
       # @param stdout [String]
       # @param stderr [String]
       # @param exit_code [Integer]
       # @param duration [Float]
-      def initialize(stdout:, stderr:, exit_code:, duration:)
+      # @param signal [Symbol, nil]
+      def initialize(stdout:, stderr:, exit_code:, duration:, signal: nil)
         @stdout = stdout
         @stderr = stderr
         @exit_code = exit_code
         @duration = duration
+        @signal = signal
       end
 
       # Whether the command exited successfully.
       #
       # @return [Boolean]
       def success?
-        @exit_code == 0
+        @exit_code.zero?
       end
     end
   end

data/lib/philiprehberger/task_runner/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskRunner
-    VERSION = "0.1.4"
+    VERSION = '0.2.1'
   end
 end

data/lib/philiprehberger/task_runner.rb

@@ -11,20 +11,26 @@ module Philiprehberger
     class Error < StandardError; end
     class TimeoutError < Error; end
 
-    # Run a shell command with output capture, optional timeout, and streaming.
+    # Run a shell command with output capture, optional timeout, streaming, signal handling, and stdin piping.
     #
-    # When a block is given, each line of stdout is yielded as it arrives.
+    # When a block is given, each line of stdout/stderr is yielded as it arrives.
+    # If the block accepts two arguments, it receives (line, stream) where stream is :stdout or :stderr.
+    # If the block accepts one argument, it receives only the line (stdout lines only, for backward compatibility).
     #
     # @param cmd [String] the command to execute
     # @param args [Array<String>] additional command arguments
     # @param timeout [Numeric, nil] maximum seconds to wait (nil for no timeout)
     # @param env [Hash, nil] environment variables to set
     # @param chdir [String, nil] working directory for the command
-    # @yield [line] each line of stdout as it arrives (streaming mode)
+    # @param signal [Symbol] signal to send on timeout (default :TERM)
+    # @param kill_after [Numeric] seconds to wait before sending SIGKILL after initial signal (default 5)
+    # @param stdin [String, IO, nil] data to pipe to the process's stdin
+    # @yield [line, stream] each line as it arrives (streaming mode)
     # @yieldparam line [String] a line of output
+    # @yieldparam stream [Symbol] :stdout or :stderr (only if block accepts 2 params)
     # @return [Result] the command result
     # @raise [TimeoutError] if the command exceeds the timeout
-    def self.run(cmd, *args, timeout: nil, env: nil, chdir: nil, &block)
+    def self.run(cmd, *args, timeout: nil, env: nil, chdir: nil, signal: :TERM, kill_after: 5, stdin: nil, &block)
       full_cmd = args.empty? ? cmd : [cmd, *args]
       spawn_opts = {}
       spawn_opts[:chdir] = chdir if chdir
@@ -33,70 +39,164 @@ module Philiprehberger
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       if block
-        run_streaming(env_hash, full_cmd, spawn_opts, timeout, start_time, &block)
+        run_streaming(env_hash, full_cmd, spawn_opts, timeout, start_time, signal, kill_after, stdin, &block)
       else
-        run_capture(env_hash, full_cmd, spawn_opts, timeout, start_time)
+        run_capture(env_hash, full_cmd, spawn_opts, timeout, start_time, signal, kill_after, stdin)
       end
     end
 
     # @api private
-    def self.run_capture(env_hash, full_cmd, spawn_opts, timeout, start_time)
-      stdout, stderr, status = if timeout
-                                 ::Timeout.timeout(timeout, TimeoutError, 'command timed out') do
-                                   Open3.capture3(env_hash, *Array(full_cmd), **spawn_opts)
-                                 end
-                               else
-                                 Open3.capture3(env_hash, *Array(full_cmd), **spawn_opts)
-                               end
-
-      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-      Result.new(stdout: stdout, stderr: stderr, exit_code: status.exitstatus || 1, duration: duration)
+    def self.run_capture(env_hash, full_cmd, spawn_opts, timeout, start_time, signal, kill_after, stdin_data)
+      stdout_buf = +''
+      stderr_buf = +''
+      killed_signal = nil
+
+      Open3.popen3(env_hash, *Array(full_cmd), **spawn_opts) do |stdin_io, stdout_io, stderr_io, wait_thr|
+        write_stdin(stdin_io, stdin_data)
+
+        if timeout
+          begin
+            ::Timeout.timeout(timeout) do
+              capture_both(stdout_io, stderr_io, stdout_buf, stderr_buf)
+            end
+          rescue ::Timeout::Error
+            killed_signal = terminate_process(wait_thr.pid, signal, kill_after)
+            stdout_buf << drain_io(stdout_io)
+            stderr_buf << drain_io(stderr_io)
+            wait_thr.value
+            Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise TimeoutError, 'command timed out'
+          end
+        else
+          capture_both(stdout_io, stderr_io, stdout_buf, stderr_buf)
+        end
+
+        exit_status = wait_thr.value
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        Result.new(
+          stdout: stdout_buf, stderr: stderr_buf,
+          exit_code: exit_status.exitstatus || 1,
+          duration: duration, signal: killed_signal
+        )
+      end
     end
 
     # @api private
-    def self.run_streaming(env_hash, full_cmd, spawn_opts, timeout, start_time, &block)
+    def self.run_streaming(env_hash, full_cmd, spawn_opts, timeout, start_time, signal, kill_after, stdin_data, &block)
       stdout_buf = +''
       stderr_buf = +''
-      exit_status = nil
+      killed_signal = nil
+      block_arity = block.arity
 
-      Open3.popen3(env_hash, *Array(full_cmd), **spawn_opts) do |_stdin, stdout, stderr, wait_thr|
-        _stdin.close
+      Open3.popen3(env_hash, *Array(full_cmd), **spawn_opts) do |stdin_io, stdout_io, stderr_io, wait_thr|
+        write_stdin(stdin_io, stdin_data)
 
         if timeout
-          ::Timeout.timeout(timeout, TimeoutError, 'command timed out') do
-            read_streams(stdout, stderr, stdout_buf, stderr_buf, &block)
-            exit_status = wait_thr.value
+          begin
+            ::Timeout.timeout(timeout) do
+              read_streams(stdout_io, stderr_io, stdout_buf, stderr_buf, block_arity, &block)
+              wait_thr.value
+            end
+          rescue ::Timeout::Error
+            killed_signal = terminate_process(wait_thr.pid, signal, kill_after)
+            wait_thr.value
+            raise TimeoutError, 'command timed out'
           end
         else
-          read_streams(stdout, stderr, stdout_buf, stderr_buf, &block)
-          exit_status = wait_thr.value
+          read_streams(stdout_io, stderr_io, stdout_buf, stderr_buf, block_arity, &block)
+          wait_thr.value
         end
-      end
 
-      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-      Result.new(
-        stdout: stdout_buf,
-        stderr: stderr_buf,
-        exit_code: exit_status&.exitstatus || 1,
-        duration: duration
-      )
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        Result.new(
+          stdout: stdout_buf, stderr: stderr_buf,
+          exit_code: wait_thr.value.exitstatus || 1,
+          duration: duration, signal: killed_signal
+        )
+      end
     end
 
     # @api private
-    def self.read_streams(stdout, stderr, stdout_buf, stderr_buf)
+    def self.read_streams(stdout, stderr, stdout_buf, stderr_buf, block_arity)
+      two_arg = block_arity == 2
       threads = []
       threads << Thread.new do
         stdout.each_line do |line|
           stdout_buf << line
-          yield line
+          if two_arg
+            yield line, :stdout
+          else
+            yield line
+          end
         end
       end
       threads << Thread.new do
-        stderr_buf << stderr.read
+        stderr.each_line do |line|
+          stderr_buf << line
+          yield line, :stderr if two_arg
+        end
       end
       threads.each(&:join)
     end
 
-    private_class_method :run_capture, :run_streaming, :read_streams
+    # @api private
+    def self.capture_both(stdout_io, stderr_io, stdout_buf, stderr_buf)
+      stderr_thread = Thread.new { stderr_buf << stderr_io.read }
+      stdout_buf << stdout_io.read
+      stderr_thread.join
+    end
+
+    # @api private
+    def self.write_stdin(stdin_io, stdin_data)
+      if stdin_data.nil?
+        stdin_io.close
+      elsif stdin_data.respond_to?(:read)
+        IO.copy_stream(stdin_data, stdin_io)
+        stdin_io.close
+      else
+        stdin_io.write(stdin_data.to_s)
+        stdin_io.close
+      end
+    end
+
+    # @api private
+    # Sends the specified signal, waits kill_after seconds, then sends SIGKILL if needed.
+    # Returns the signal that actually killed the process.
+    def self.terminate_process(pid, signal, kill_after)
+      begin
+        Process.kill(signal.to_s, pid)
+      rescue Errno::ESRCH
+        return nil
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + kill_after
+      loop do
+        begin
+          Process.kill(0, pid)
+        rescue Errno::ESRCH
+          return signal
+        end
+        break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        sleep(0.05)
+      end
+
+      begin
+        Process.kill('KILL', pid)
+        :KILL
+      rescue Errno::ESRCH
+        signal
+      end
+    end
+
+    # @api private
+    def self.drain_io(io)
+      io.read_nonblock(1_048_576)
+    rescue IO::WaitReadable, IOError
+      ''
+    end
+
+    private_class_method :run_capture, :run_streaming, :read_streams, :capture_both, :write_stdin, :terminate_process,
+                         :drain_io
   end
 end

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-task_runner
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.1
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-03-31 00:00:00.000000000 Z
 dependencies: []
 description: Run shell commands with captured stdout/stderr, exit code, duration measurement,
-  configurable timeout, environment variables, and line-by-line streaming via blocks.
+  configurable timeout, environment variables, line-by-line streaming, graceful signal
+  escalation on timeout, and stdin piping.
 email:
 - me@philiprehberger.com
 executables: []
@@ -51,5 +52,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Shell command runner with output capture, timeout, and streaming
+summary: Shell command runner with output capture, timeout, streaming, signal handling,
+  and stdin piping
 test_files: []