philiprehberger-task_runner 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6dfc4d0ba28ecfa8f7595708a8d1ed644a6af53c0ccca5e0ea3088a059ba50e
-  data.tar.gz: 15256a978c23e405abb6a01b8045c6c03b193f9fcb43f199fd883fe5412482fc
+  metadata.gz: ac71950b0f8ccde0b9330b8962d7513e3f630bf12e7bd2b442f3dbacc4176c5d
+  data.tar.gz: 4233518a744a4cce5303b43885eeba5fe1eeea69792734ec238f301ffbfab4aa
 SHA512:
-  metadata.gz: 55115c901422f69e3fd8e3a0a104c9227a73916675d70587c5203043da7f8e4044c3d35104a88d26d28cde519fc6cedd31d5ef6a672f17959444cf77ef203e1b
-  data.tar.gz: bb70b1e19dc9dac1381f0203112dab213ef5771d5bc06459e098ec7a563ee5fb04bc79c156b286d2f9a6066613c3a692893e17e333b10398c202aabf1a1c2e8a
+  metadata.gz: 7af1c5084052976871ef648652fc5f739c27eebb91c04419a6762bad3c554a37b499637585fa3c58018f8751bf07cef5b05a9b7221933ad198b6c98b213243a2
+  data.tar.gz: e42e5cd9fbdcd1e18d0738a2e53d7d77daba4a54fd4de915364bc889efe86c2faeb023024e366ffd0a6e1bab5fef800744711e0a31d2986d032e7fff329398fd

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Add Sponsor badge and fix License link format in README
+
 ## [0.1.3] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -2,9 +2,14 @@
 
 [![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)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-task-runner)](https://github.com/philiprehberger/rb-task-runner/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-task-runner)](https://github.com/philiprehberger/rb-task-runner/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-task-runner)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-task-runner/bug)](https://github.com/philiprehberger/rb-task-runner/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-task-runner/enhancement)](https://github.com/philiprehberger/rb-task-runner/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
-Shell command runner with output capture, timeout, and streaming
+Shell command runner with output capture, timeout, streaming, signal handling, and stdin piping
 
 ## Requirements
 
@@ -52,6 +57,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
@@ -60,17 +88,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
 
@@ -80,6 +121,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
+[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+
 ## License
 
-MIT
+[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.3'
+    VERSION = '0.2.0'
   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.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-03-30 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: []