philiprehberger-task_runner 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fb5481d773646ae680a865d98ac5519d57ca677a53e08ce87b05de1e0db978b
-  data.tar.gz: ad16cc33bf847e8a83576e4d794b2554d5c549f370cde3c572a30f0b246e2e5f
+  metadata.gz: 0edebc1ac881ac5547d09cc825898875461f22b5b13edd6c5c01b3efc9d7a13f
+  data.tar.gz: f7172ad5068e86cb31fa0cb48f1eac41b21f239ff884f9333f52b52d33df29bb
 SHA512:
-  metadata.gz: 49d9861467feb9494893096aa551974a02a448db8c42bf2e51ed1c62ee0fb281377afc31d4bec6e49ab317c6803ea22493a8c8437b79af6dfe4b324acb47b074
-  data.tar.gz: 22636d10befe17c115036b5336e2e71597ee07c7f381122dc6e5c3e0356c938dbc765505268b0653a6ec4248bda87924593b250e961c062c37eebff23b647018
+  metadata.gz: 96f98887b963b6e19cd0025b1d2621571422b21ec7c7e72f936892b4f768b0f023590da3591b575deaf8b6395c8d5b27fe3a6ff56bb0a057159f594383323a40
+  data.tar.gz: 84271258a850cc7dbb6a3bda26db60c55b7a43b61b9323659eec0ecbe4bc83f1bfe804ade2b33922de9643418becdc8f595231fa9cf84e9663e57b85ca1a8e15

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-20
+
+### Added
+- `Result#failure?` — logical inverse of `#success?` for clearer branching
+- `Result#timed_out?` — true when the process was killed by the task runner for exceeding its timeout (`:TERM` or `:KILL` signal)
+- `:timed_out` key added to `Result#to_h` alongside the existing `:success` flag
+
+## [0.3.0] - 2026-04-09
+
+### Added
+- `TaskRunner.run!` raises `CommandError` on non-zero exit code (same API as `run`)
+- `CommandError#result` exposes the full `Result` object for inspection
+- `Result#to_h` for hash serialization of command results
+
 ## [0.2.1] - 2026-03-31
 
 ### Changed

data/README.md

@@ -36,6 +36,21 @@ puts result.success?     # => true
 puts result.duration     # => 0.012
 ```
 
+### Raising on Failure
+
+```ruby
+# 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
+```
+
 ### Timeout
 
 ```ruby
@@ -99,14 +114,19 @@ end
 | 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 |
+| `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
 

data/lib/philiprehberger/task_runner/result.rb

@@ -38,6 +38,37 @@ module Philiprehberger
       def success?
         @exit_code.zero?
       end
+
+      # Whether the command exited with a non-zero status, was killed by a
+      # signal, or timed out. The logical inverse of {#success?}.
+      #
+      # @return [Boolean]
+      def failure?
+        !success?
+      end
+
+      # Whether the command was terminated by the task runner because it
+      # exceeded its timeout (SIGTERM or SIGKILL).
+      #
+      # @return [Boolean]
+      def timed_out?
+        %i[TERM KILL].include?(@signal)
+      end
+
+      # Hash representation of the result.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          stdout: @stdout,
+          stderr: @stderr,
+          exit_code: @exit_code,
+          duration: @duration,
+          signal: @signal,
+          success: success?,
+          timed_out: timed_out?
+        }
+      end
     end
   end
 end

data/lib/philiprehberger/task_runner/version.rb

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

data/lib/philiprehberger/task_runner.rb

@@ -11,6 +11,17 @@ module Philiprehberger
     class Error < StandardError; end
     class TimeoutError < Error; end
 
+    # Raised by run! when the command exits with a non-zero status.
+    class CommandError < Error
+      # @return [Result] the failed command result
+      attr_reader :result
+
+      def initialize(result)
+        @result = result
+        super("command exited with code #{result.exit_code}")
+      end
+    end
+
     # Run a shell command with output capture, optional timeout, streaming, signal handling, and stdin piping.
     #
     # When a block is given, each line of stdout/stderr is yielded as it arrives.
@@ -45,6 +56,20 @@ module Philiprehberger
       end
     end
 
+    # Run a shell command, raising CommandError on non-zero exit.
+    #
+    # Accepts the same arguments as {.run}.
+    #
+    # @return [Result] the command result
+    # @raise [CommandError] if the command exits with a non-zero status
+    # @raise [TimeoutError] if the command exceeds the timeout
+    def self.run!(cmd, ...)
+      result = run(cmd, ...)
+      raise CommandError, result unless result.success?
+
+      result
+    end
+
     # @api private
     def self.run_capture(env_hash, full_cmd, spawn_opts, timeout, start_time, signal, kill_after, stdin_data)
       stdout_buf = +''

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-task_runner
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies: []
 description: Run shell commands with captured stdout/stderr, exit code, duration measurement,
   configurable timeout, environment variables, line-by-line streaming, graceful signal
@@ -25,11 +25,11 @@ files:
 - 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
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-task_runner
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-task-runner
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-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