philiprehberger-task_runner 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99f699cbe02fe85cc5b4d5054b1751bce49d30b377e249fcf343da080a76b948
+  data.tar.gz: aeb84e373540392e271d0932e0b1000bdb4819fcb08d3b7bf1cf98b9ff044e65
+SHA512:
+  metadata.gz: d34d6526d118009beca3959b6560a7099c88b6a2fcc0143d0fcc542a77ec0617b8eadf92682759be240f8bd58a4cb09e93bc3171cec4bda80b13a0c5ab76e5e0
+  data.tar.gz: c8dce1f7683c24f6890f36e0f2e10efe2650fb3d2ae366d6c5dc6e1713bf61a049fde22bc475f03612fad1acb4315ba9b2271cb74127636ca1bb8806062b0e04

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this gem 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Shell command execution with stdout and stderr capture
+- Exit code and duration measurement on Result object
+- Configurable timeout with TimeoutError
+- Environment variable and working directory options
+- Block-based streaming for line-by-line stdout processing

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# philiprehberger-task_runner
+
+[![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)
+
+Shell command runner with output capture, timeout, and streaming.
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-task_runner"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-task_runner
+```
+
+## Usage
+
+```ruby
+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
+```
+
+### Timeout
+
+```ruby
+result = Philiprehberger::TaskRunner.run('long-process', timeout: 30)
+```
+
+### Environment Variables and Working Directory
+
+```ruby
+result = Philiprehberger::TaskRunner.run(
+  'make', 'build',
+  env: { 'DEBUG' => '1' },
+  chdir: '/path/to/project'
+)
+```
+
+### Streaming Output
+
+```ruby
+Philiprehberger::TaskRunner.run('tail', '-f', '/var/log/app.log', timeout: 10) do |line|
+  puts ">> #{line}"
+end
+```
+
+## API
+
+| Method / Class | Description |
+|----------------|-------------|
+| `.run(cmd, *args, timeout:, env:, chdir:)` | Run a command and return a Result |
+| `.run(cmd) { \|line\| ... }` | Run with line-by-line stdout 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 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/task_runner/result.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TaskRunner
+    # Represents the result of a shell command execution.
+    class Result
+      # @return [String] standard output
+      attr_reader :stdout
+
+      # @return [String] standard error
+      attr_reader :stderr
+
+      # @return [Integer] process exit code
+      attr_reader :exit_code
+
+      # @return [Float] execution duration in seconds
+      attr_reader :duration
+
+      # @param stdout [String]
+      # @param stderr [String]
+      # @param exit_code [Integer]
+      # @param duration [Float]
+      def initialize(stdout:, stderr:, exit_code:, duration:)
+        @stdout = stdout
+        @stderr = stderr
+        @exit_code = exit_code
+        @duration = duration
+      end
+
+      # Whether the command exited successfully.
+      #
+      # @return [Boolean]
+      def success?
+        @exit_code == 0
+      end
+    end
+  end
+end

data/lib/philiprehberger/task_runner/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TaskRunner
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/task_runner.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+
+require_relative 'task_runner/version'
+require_relative 'task_runner/result'
+
+module Philiprehberger
+  module TaskRunner
+    class Error < StandardError; end
+    class TimeoutError < Error; end
+
+    # Run a shell command with output capture, optional timeout, and streaming.
+    #
+    # When a block is given, each line of stdout is yielded as it arrives.
+    #
+    # @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)
+    # @yieldparam line [String] a line of output
+    # @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)
+      full_cmd = args.empty? ? cmd : [cmd, *args]
+      spawn_opts = {}
+      spawn_opts[:chdir] = chdir if chdir
+
+      env_hash = env || {}
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      if block
+        run_streaming(env_hash, full_cmd, spawn_opts, timeout, start_time, &block)
+      else
+        run_capture(env_hash, full_cmd, spawn_opts, timeout, start_time)
+      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)
+    end
+
+    # @api private
+    def self.run_streaming(env_hash, full_cmd, spawn_opts, timeout, start_time, &block)
+      stdout_buf = +''
+      stderr_buf = +''
+      exit_status = nil
+
+      Open3.popen3(env_hash, *Array(full_cmd), **spawn_opts) do |_stdin, stdout, stderr, wait_thr|
+        _stdin.close
+
+        if timeout
+          ::Timeout.timeout(timeout, TimeoutError, 'command timed out') do
+            read_streams(stdout, stderr, stdout_buf, stderr_buf, &block)
+            exit_status = wait_thr.value
+          end
+        else
+          read_streams(stdout, stderr, stdout_buf, stderr_buf, &block)
+          exit_status = 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
+      )
+    end
+
+    # @api private
+    def self.read_streams(stdout, stderr, stdout_buf, stderr_buf)
+      threads = []
+      threads << Thread.new do
+        stdout.each_line do |line|
+          stdout_buf << line
+          yield line
+        end
+      end
+      threads << Thread.new do
+        stderr_buf << stderr.read
+      end
+      threads.each(&:join)
+    end
+
+    private_class_method :run_capture, :run_streaming, :read_streams
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-task_runner
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 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.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/task_runner.rb
+- lib/philiprehberger/task_runner/result.rb
+- lib/philiprehberger/task_runner/version.rb
+homepage: https://github.com/philiprehberger/rb-task-runner
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-task-runner
+  source_code_uri: https://github.com/philiprehberger/rb-task-runner
+  changelog_uri: https://github.com/philiprehberger/rb-task-runner/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-task-runner/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Shell command runner with output capture, timeout, and streaming
+test_files: []