philiprehberger-task_runner

Shell command runner with output capture, timeout, streaming, signal handling, and stdin piping

Requirements

Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-task_runner"

Or install directly:

gem install philiprehberger-task_runner

Usage

require "philiprehberger/task_runner"

result = Philiprehberger::TaskRunner.run('ls', '-la')
puts result.stdout
puts result.exit_code    # => 0
puts result.success?     # => true
puts result.duration     # => 0.012

Raising on Failure

# Raises CommandError if the command exits non-zero
result = Philiprehberger::TaskRunner.run!('make', 'build')

# The error includes the full Result for inspection
begin
  Philiprehberger::TaskRunner.run!('false')
rescue Philiprehberger::TaskRunner::CommandError => e
  puts e.message          # => "command exited with code 1"
  puts e.result.stderr    # => captured stderr
end

Boolean Success Check

# Returns true for exit 0, false otherwise (timeouts also return false)
if Philiprehberger::TaskRunner.run?('which', 'git')
  puts 'git is installed'
end

Which

Locate an executable on PATH (like the which shell builtin). Returns the absolute path or nil when not found:

Philiprehberger::TaskRunner.which("git")
# => "/usr/bin/git"

Philiprehberger::TaskRunner.which("definitely-not-installed")
# => nil

On Windows, candidate suffixes from ENV["PATHEXT"] (.COM, .EXE, .BAT, .CMD) are tried automatically.

Timeout

result = Philiprehberger::TaskRunner.run('long-process', timeout: 30)

Environment Variables and Working Directory

result = Philiprehberger::TaskRunner.run(
  'make', 'build',
  env: { 'DEBUG' => '1' },
  chdir: '/path/to/project'
)

Signal Handling

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

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

Philiprehberger::TaskRunner.run('tail', '-f', '/var/log/app.log', timeout: 10) do |line|
  puts ">> #{line}"
end

Stderr Streaming

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:, signal:, kill_after:, stdin:)`	Run a command and return a Result
`.run!(cmd, args, *opts)`	Same as `run`, raises `CommandError` on non-zero exit
`.run?(cmd, args, *opts)`	Boolean shortcut — true only when exit code is 0; timeouts return false
`.which(cmd)`	Absolute path of `cmd` on PATH (or `nil`); honors `PATHEXT` on Windows
`CommandError#result`	The failed `Result` object
`.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#failure?`	Logical inverse of `#success?`
`Result#duration`	Execution time in seconds
`Result#signal`	Signal that killed the process (:TERM, :KILL, or nil)
`Result#timed_out?`	Whether the process was killed for exceeding its timeout
`Result#to_h`	Hash representation of the result (includes `:success` and `:timed_out`)

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT