philiprehberger-task_runner 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e264781c1fb8c863a53e85b4d6b80f4bc1644a27bbeb17446473719d5efc10c
-  data.tar.gz: d7b4719dab1483d43ec494ac3aa00718ecfd6d408b9241c21cbbd7695e4bce2d
+  metadata.gz: dddebb2a9f61387b45cc9650f3d695c07be69388f6d2b988f551326b5cfba973
+  data.tar.gz: 2d53404bcb1eb3fbbb941091d8c7b4a4e68515fe224c6891b0473c9a609d0773
 SHA512:
-  metadata.gz: 8ea18413fb9724653c6621d57f24af1384567aa5361ea3ae4d9ba165f97d5685644d8b45c2ad2cc9e2537db2e9e19f223b4983c94bd2514640c325c8422a46dd
-  data.tar.gz: bd148577cae30e1bb877622f60cdfda40887bee65653a5568c6b6faa420f37cf38bfe95d6d8317508a7a6502c3c67395a242218f6731d16227d338266131c862
+  metadata.gz: b8d1d3691823020fdd69b5d7642fe61d26415c654f6d26d3069755aa4ee95e09a8fa3f7bd34ffc9fb004d67366c7806a297aa4a7890251a7cce421c9e70ae3f4
+  data.tar.gz: 5a0123b5b514d3d07b1d9ade8e02137a92773564253f2fc7331531de844190ff3f921e732c794fd0b5d8c86c1d393baed9281d0d4fe8342c7716d8c00333fd71

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-20
+
+### Added
+- `Result#parse_json` — parse stdout as JSON, raising `Philiprehberger::TaskRunner::ParseError` (new) when stdout is empty or not valid JSON
+- `Result#json?` — predicate for safely probing whether stdout is parseable JSON
+- Card image reference in the README for registry-side rendering
+
+## [0.6.0] - 2026-04-28
+
+### Added
+- `TaskRunner.which(cmd)` — absolute path of an executable on `PATH`, or `nil` when not found. Honors `ENV['PATHEXT']` on Windows. Raises `ArgumentError` for nil/empty input.
+
 ## [0.5.0] - 2026-04-21
 
 ### Added

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-task_runner.svg)](https://rubygems.org/gems/philiprehberger-task_runner)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-task-runner)](https://github.com/philiprehberger/rb-task-runner/commits/main)
 
+![philiprehberger-task_runner](https://raw.githubusercontent.com/philiprehberger/rb-task-runner/main/package-card.webp)
+
 Shell command runner with output capture, timeout, streaming, signal handling, and stdin piping
 
 ## Requirements
@@ -60,6 +62,22 @@ if Philiprehberger::TaskRunner.run?('which', 'git')
 end
 ```
 
+### Which
+
+Locate an executable on `PATH` (like the `which` shell builtin). Returns the
+absolute path or `nil` when not found:
+
+```ruby
+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
 
 ```ruby
@@ -118,6 +136,24 @@ Philiprehberger::TaskRunner.run('make', 'build') do |line, stream|
 end
 ```
 
+### Parsing JSON Output
+
+```ruby
+result = Philiprehberger::TaskRunner.run('kubectl', 'get', 'pod', 'web', '-o', 'json')
+
+if result.json?
+  doc = result.parse_json
+  doc['status']['phase']  # => "Running"
+end
+
+# parse_json raises ParseError when stdout isn't valid JSON
+begin
+  result.parse_json
+rescue Philiprehberger::TaskRunner::ParseError => e
+  warn "command did not return JSON: #{e.message}"
+end
+```
+
 ## API
 
 | Method / Class | Description |
@@ -125,6 +161,7 @@ end
 | `.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 |
@@ -136,6 +173,8 @@ end
 | `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#json?` | Whether stdout contains a parseable JSON document |
+| `Result#parse_json` | Parse stdout as JSON; raises `ParseError` on invalid or empty stdout |
 | `Result#to_h` | Hash representation of the result (includes `:success` and `:timed_out`) |
 
 ## Development

data/lib/philiprehberger/task_runner/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Philiprehberger
   module TaskRunner
     # Represents the result of a shell command execution.
@@ -55,6 +57,31 @@ module Philiprehberger
         %i[TERM KILL].include?(@signal)
       end
 
+      # Whether stdout contains a parseable JSON document.
+      # Empty stdout is treated as non-JSON.
+      #
+      # @return [Boolean]
+      def json?
+        return false if @stdout.nil? || @stdout.strip.empty?
+
+        JSON.parse(@stdout)
+        true
+      rescue JSON::ParserError
+        false
+      end
+
+      # Parse stdout as JSON.
+      #
+      # @return [Object] the parsed JSON document (Hash, Array, String, Numeric, true, false, or nil)
+      # @raise [ParseError] if stdout is empty or not valid JSON
+      def parse_json
+        raise ParseError, 'stdout is empty' if @stdout.nil? || @stdout.strip.empty?
+
+        JSON.parse(@stdout)
+      rescue JSON::ParserError => e
+        raise ParseError, "stdout is not valid JSON: #{e.message}"
+      end
+
       # Hash representation of the result.
       #
       # @return [Hash]

data/lib/philiprehberger/task_runner/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TaskRunner
-    VERSION = '0.5.0'
+    VERSION = '0.7.0'
   end
 end

data/lib/philiprehberger/task_runner.rb

@@ -11,6 +11,9 @@ module Philiprehberger
     class Error < StandardError; end
     class TimeoutError < Error; end
 
+    # Raised by Result#parse_json when the stdout cannot be parsed as JSON.
+    class ParseError < Error; end
+
     # Raised by run! when the command exits with a non-zero status.
     class CommandError < Error
       # @return [Result] the failed command result
@@ -81,6 +84,37 @@ module Philiprehberger
       false
     end
 
+    # Find the absolute path of an executable on PATH.
+    #
+    # Behaves like the `which` shell builtin: walks each entry in
+    # `ENV['PATH']` and returns the first directory that contains an
+    # executable file matching `cmd`. On Windows, also tries each suffix in
+    # `ENV['PATHEXT']`. Returns `nil` when nothing is found.
+    #
+    # @param cmd [String] the executable name to search for
+    # @return [String, nil] the absolute path, or nil when not found
+    # @raise [ArgumentError] if `cmd` is nil or empty
+    def self.which(cmd)
+      raise ArgumentError, 'cmd cannot be nil or empty' if cmd.nil? || cmd.to_s.empty?
+
+      exts = if Gem.win_platform?
+               (ENV['PATHEXT'] || '.COM;.EXE;.BAT;.CMD').split(';')
+             else
+               ['']
+             end
+
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
+        next if dir.empty?
+
+        exts.each do |ext|
+          candidate = File.join(dir, "#{cmd}#{ext}")
+          return File.expand_path(candidate) if File.file?(candidate) && File.executable?(candidate)
+        end
+      end
+
+      nil
+    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.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-21 00:00:00.000000000 Z
+date: 2026-05-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