brut 0.16.0 → 0.18.0

data/lib/brut/cli/apps/test.rb

@@ -1,23 +1,27 @@
 require "shellwords"
 require "brut/cli"
 
-class Brut::CLI::Apps::Test < Brut::CLI::App
-  description "Run and audit tests of the app"
-  default_command :run
+class Brut::CLI::Apps::Test < Brut::CLI::Commands::BaseCommand
+  def description = "Run and audit tests of the app"
 
-  def before_execute
-    ENV["RACK_ENV"] = "test"
-  end
+  def default_rack_env = "development"
+  def default_command_class = Run
+
+  class Run < Brut::CLI::Commands::BaseCommand
+    def default_rack_env = "development"
+    def description = "Run non-e2e tests"
+    def opts = [
+      [ "--[no-]rebuild", "If true, test database is rebuilt before tests are run (default false)" ],
+      [ "--[no-]rebuild-after", "If true, test database is rebuilt after tests are run (default false)" ],
+      [ "--seed SEED", "Set the random seed to allow duplicating a test run" ],
+    ]
+    def args_description = "specs_to_run..."
 
-  class Run < Brut::CLI::Command
-    description "Run non-e2e tests"
-    opts.on("--[no-]rebuild", "If true, test database is rebuilt before tests are run (default false)")
-    opts.on("--[no-]rebuild-after", "If true, test database is rebuilt after tests are run (default false)")
-    opts.on("--seed SEED", "Set the random seed to allow duplicating a test run")
-    args "specs_to_run..."
-    env_var("LOGGER_LEVEL_FOR_TESTS",purpose: "Can be set to debug, info, warn, error, or fatal to control logging during tests. Defaults to 'warn' to avoid verbose test output")
-    env_var("RSPEC_WARNINGS", purpose: "If set to 'true', configures RSpec warnings for the test run. NOTE: this is used in the app's spec_helper.rb so could've been removed")
-    env_var("RSPEC_PROFILE_EXAMPLES", purpose: "If set to any value, it is converted to an int and set as RSpec's number of examples to profile. NOTE: this is used in the app's spec_helper.rb so could've been removed")
+    def env_vars = [
+      [ "LOGGER_LEVEL_FOR_TESTS","Can be set to debug, info, warn, error, or fatal to control logging during tests. Defaults to 'warn' to avoid verbose test output" ],
+      [ "RSPEC_WARNINGS", "If set to 'true', configures RSpec warnings for the test run. NOTE: this is used in the app's spec_helper.rb so could've been removed" ],
+      [ "RSPEC_PROFILE_EXAMPLES", "If set to any value, it is converted to an int and set as RSpec's number of examples to profile. NOTE: this is used in the app's spec_helper.rb so could've been removed" ],
+    ]
 
 
     def rspec_command
@@ -25,9 +29,9 @@ class Brut::CLI::Apps::Test < Brut::CLI::App
         "bin/rspec",
         "-I", Brut.container.app_specs_dir,
         "-I", Brut.container.app_src_dir,
-        "-I lib/", # not needed when Brut is gemified
+        #"-I lib/", # not needed when Brut is gemified
         rspec_cli_args,
-        "-P \"**/*.spec.rb\"",
+        "-P '**/*.spec.rb'",
       ]
       if options.seed
         parts << "--seed #{options.seed}"
@@ -40,72 +44,92 @@ class Brut::CLI::Apps::Test < Brut::CLI::App
     def rebuild_by_default?       = false
     def rebuild_after_by_default? = false
 
-    def execute
-      Brut.container.sequel_db_handle.disconnect
+    def run
       if options.rebuild?(default: rebuild_by_default?)
-        Brut.container.instrumentation.span("schema.rebuild.before") do
-          out.puts "Rebuilding test database schema"
-          system! "bin/db rebuild --env=test"
-        end
-      end
-      Brut.container.instrumentation.span("tests.run") do |span|
-        if args.empty?
-          span.add_prefixed_attributes("brut.cli.test", tests: :all)
-          out.puts "Running all tests"
-          system! "#{rspec_command} #{Brut.container.app_specs_dir}/"
-        else
-          span.add_prefixed_attributes("brut.cli.test", tests: args.length)
-          test_args = args.map { |_|
-            '"' + Shellwords.escape(_) + '"'
-          }.join(" ")
-          system! "#{rspec_command} #{test_args}"
+        stdout.puts "Rebuilding test database schema"
+        Bundler.with_unbundled_env do
+          system! "brut db rebuild --env=test"
         end
       end
+      run_tests
       if options.rebuild_after?(default: rebuild_after_by_default?)
-        Brut.container.instrumentation.span("schema.rebuild.after") do
-          out.puts "Re-Rebuilding test database schema"
-          system! "bin/db rebuild --env=test"
+        stdout.puts "Re-Rebuilding test database schema"
+        Bundler.with_unbundled_env do
+          system! "brut db rebuild --env=test"
         end
       end
       0
     end
+
+  private
+
+    def run_tests
+      command = if argv.empty?
+                  stdout.puts "Running all tests"
+                  "#{rspec_command} #{Brut.container.app_specs_dir}/"
+                else
+                  stdout.puts "Running only #{argv.join(", ")}"
+                  test_args = argv.map { |_|
+                    '"' + Shellwords.escape(_) + '"'
+                  }.join(" ")
+                  "#{rspec_command} #{test_args}"
+                end
+      Bundler.with_unbundled_env do
+        system! command
+      end
+    end
   end
   class E2e < Run
-    description "Run e2e tests"
-    opts.on("--[no-]rebuild", "If true, test database is rebuilt before tests are run (default true)")
-    opts.on("--[no-]rebuild-after", "If true, test database is rebuilt after tests are run (default true)")
-    opts.on("--seed SEED", "Set the random seed to allow duplicating a test run")
-    args "specs_to_run..."
-    env_var("E2E_RECORD_VIDEOS",purpose: "If set to 'true', videos of each test run are saved in `./tmp/e2e-videos`")
-    env_var("E2E_SLOW_MO",purpose: "If set to, will attempt to slow operations down by this many milliseconds")
-    env_var("E2E_TIMEOUT_MS",purpose: "ms to wait for any browser activity before failing the test. And here you didn't think you'd get away without using sleep in browse-based tests?")
-    env_var("LOGGER_LEVEL_FOR_TESTS",purpose: "Can be set to debug, info, warn, error, or fatal to control logging during tests. Defaults to 'warn' to avoid verbose test output")
-    env_var("RSPEC_WARNINGS", purpose: "If set to 'true', configures RSpec warnings for the test run. NOTE: this is used in the app's spec_helper.rb so could've been removed")
-    env_var("RSPEC_PROFILE_EXAMPLES", purpose: "If set to any value, it is converted to an int and set as RSpec's number of examples to profile. NOTE: this is used in the app's spec_helper.rb so could've been removed")
+    def description = "Run end-to-end (browser) tests"
+    def env_vars = super + [
+      [ "E2E_RECORD_VIDEOS","If set to 'true', videos of each test run are saved in `./tmp/e2e-videos`" ],
+      [ "E2E_SLOW_MO","If set to, will attempt to slow operations down by this many milliseconds" ],
+      [ "E2E_TIMEOUT_MS","ms to wait for any browser activity before failing the test. And here you didn't think you'd get away without using sleep in browse-based tests?" ],
+    ]
 
     def rspec_cli_args = "--tag e2e"
     def rebuild_by_default?       = true
     def rebuild_after_by_default? = true
+
+  private
+
+    def run_tests
+      require "brut/spec_support/e2e_test_server"
+      Brut::SpecSupport::E2ETestServer.instance.start
+      super
+    ensure
+      Brut::SpecSupport::E2ETestServer.instance.stop
+    end
   end
-  class Js < Brut::CLI::Command
-    description "Run JavaScript unit tests"
-    opts.on("--[no-]build-assets","Build all assets before running the tests")
-    def execute
+  class Js < Brut::CLI::Commands::BaseCommand
+    def default_rack_env = "development"
+    def description = "Run JavaScript unit tests"
+    def opts = [
+      [ "--[no-]build-assets","Build all assets before running the tests" ],
+    ]
+
+    def run
+      options.set_default(:"build-assets", true)
       if options.build_assets?
-        system!({ "RACK_ENV" => "test" }, "bin/build-assets")
+        Bundler.with_unbundled_env do
+          system!({ "RACK_ENV" => "test" }, "brut build-assets all")
+        end
       end
       system!({ "NODE_DISABLE_COLORS" => "1" },"npx mocha #{Brut.container.js_specs_dir} --no-color --extension 'spec.js' --recursive")
       0
     end
   end
-  class Audit < Brut::CLI::Command
-    description "Audits all of the app's classes to see if test files exist"
+  class Audit < Brut::CLI::Commands::BaseCommand
+    def default_rack_env = "development"
+    def description = "Audits all of the app's classes to see if test files exist"
 
-    opts.on("--ignore PATH[,PATH]","Ignore any files in these paths, relative to app root",Array)
-    opts.on("--type TYPE","Only audit this type of file")
-    opts.on("--show-scaffold","If set, shows the command to scaffold the missing tests")
+    def opts = [
+      [ "--ignore PATH[,PATH]","Ignore any files in these paths, relative to app root",Array ],
+      [ "--type TYPE","Only audit this type of file" ],
+      [ "--show-scaffold","If set, shows the command to scaffold the missing tests" ],
+    ]
 
-    def execute
+    def run
       app_files = Dir["#{Brut.container.app_src_dir}/**/*"].select { |file|
         if file.start_with?(Brut.container.app_specs_dir.to_s)
           false
@@ -175,43 +199,45 @@ class Brut::CLI::Apps::Test < Brut::CLI::App
             hash[:type] = :infrastructure
             hash[:test_expected] = false
           else
-            hash[:type] = type.to_sym
+            hash[:type] = pathname.relative_path_from(Brut.container.back_end_src_dir).dirname
           end
         else
           hash[:type] = :other
           hash[:test_expected] = false
         end
         hash
-      }.compact
+      }.compact.sort_by { it[:type].to_s + it[:source_file].to_s }
 
       files_missing = []
       printed_header = false
       audit.each do |file_audit|
         if !file_audit[:test_file].exist?
-          if options.audit_type.nil? || file_audit[:type] == options.audit_type
+          if options.type.nil? || file_audit[:type] == options.type.to_sym
             if file_audit[:test_expected]
               files_missing << file_audit[:source_file]
               if !printed_header
-                out.puts "These files are missing tests:"
-                out.puts ""
+                stdout.puts "These files are missing tests:"
+                stdout.puts ""
+                stdout.printf "%-25s   %s\n","Type", "Path"
+                stdout.puts "-------------------------------------------"
                 printed_header = true
               end
-              out.puts "#{file_audit[:type].to_s.ljust(15)} - #{file_audit[:source_file]}"
+              stdout.puts "#{file_audit[:type].to_s.ljust(25)} - #{file_audit[:source_file]}"
             end
           end
         end
       end
       if files_missing.empty?
-        out.puts "All tests exists!"
+        stdout.puts "All tests exists!"
         0
       else
         if options.show_scaffold?
-          out.puts
+          stdout.puts
           files_missing_args = files_missing.map { |file|
             '             "' + Shellwords.escape(file.to_s) + '"'
           }.join(" \\\n")
 
-          out.puts "Run this command to generate empty tests:\n\nbin/scaffold test \\\n#{files_missing_args}"
+          stdout.puts "Run this command to generate empty tests:\n\nbrut scaffold test \\\n#{files_missing_args}"
         end
         1
       end

data/lib/brut/cli/commands/base_command.rb

@@ -0,0 +1,174 @@
+require "brut/junk_drawer"
+class Brut::CLI::Commands::BaseCommand
+
+  attr_accessor :parent_command
+
+  # The name of the command that the developer should use on the command line. By default, this is
+  # the underscorized version of the class' simple name.
+  # @return [String] String the developer should use on the command line. If it has spaces or
+  #         characters special to the shell, you will have a great sadness and possibly other mayhem.
+  def name = RichString.new(self.class.name.split(/::/).last).underscorized
+
+  # Execute the command in the given context.  This is the method to call to execute a command programmatically, however you
+  # should not override this method. Instead, override `.run` to provide your command's logic.
+  #
+  # @param [Brut::CLI::ExecutionContext] execution_context the context in which the command will run, providing access
+  # to standard streams, the parsed options, and unparsed arguments.
+  def execute(execution_context)
+    @execution_context = execution_context
+    self.run
+  end
+
+  # True if the command requires Brut to fully bootstrap and start itself up.  Bootstrapping isn't running a web server but it will
+  # do everything else, including connecting too all databases.  Your command should return true for this if it needs to access a database
+  # or make API calls outside `Brut::CLI`. If this returns false, Brut's configuration options will still be available.
+  #
+  # By default, this returns the value for `bootstrap?` of the `default_command`. If there is no `default_command`, this returns false.
+  #
+  # @return [true|false] True if Brut should be fully bootstrap and connect to all database servers (e.g.). False if Brut should only
+  #                      set up its configuration options.
+  def bootstrap? = default_command&.bootstrap? || false
+
+  # The default `RACK_ENV` to use for this command.  This value is used when no `RACK_ENV` is present in the UNIX environment
+  # and when `--env` has not been used on the command line. Do note that setting this in an app or parent command does
+  # not translate to the subcommands.
+  #
+  # @return [String|nil] If nil, Brut configuration will not be loaded and the command will run more or less as if it were a plain
+  #         Ruby script.  If a `String`, this value will be set as the `RACK_ENV` if it's not been otherwise specified.
+  def default_rack_env = default_command&.default_rack_env
+
+  # @return [String] description of this command for use in help output
+  def description = ""
+
+  # @return [String] description of the arguments this command accepts. Used for documentation only.
+  def args_description = nil
+
+  # @return [Array<Array<String>>] Array of arrays documenting which environment variables affect this command's behavior.
+  #         The array should have two elements: the env var name as a string, and a string documenting its purpose. This is
+  #         used for documentation only.
+  def env_vars = []
+
+  # Used to specify the command line options for the command.
+  # @return [Array<Array<Object>>] an array of arrays representing this command's reecognized command line options.  Each member
+  #         of the array is treated as arguments to `OptionParser#on`.  Please consult the Rubydoc for that method to know what
+  #         you can use here.  It is quite flexible, including type conversions, documentation, and multiple forms of options.
+  def opts = []
+
+  # Specify type conversions for options.  This is a loose wrapper around `OptionParser#accept` with a convienience feature
+  # to allow simpler conversions without a proc.
+  #
+  # @example
+  #   class Type
+  #     def initialize(value)
+  #       value = value.to_s
+  #       if ["new", "old", "promoted" ].include?(value)
+  #         @value = value
+  #       else
+  #         raise ArgumentError, "'#{value}' is not a valid Type"
+  #       end
+  #     end
+  #   end
+  #   def opts = [
+  #     [ "--type=TYPE", "The type of thing", Type ]
+  #   ]
+  #   def accepts = [
+  #     Type,
+  #   ]
+  #   # or
+  #   def accepts = [
+  #     [ Type, ->(val) { Type.new(val) },
+  #   ]
+  #
+  # @return [Array<Array>|Array<Class>] Must be an array.  Any element that is a class will be used to convert any options
+  #         of that type when the type is used in `opts`.  If the element is a class, it is assumed that values can be converted
+  #         via `.new`.  If the class does not support `.new` as a conversion method, the element should be a two-element array
+  #         where index 0 is the class and index 1 is a proc to convert the command line argument to the class's type.
+  def accepts = []
+
+  # Command to run if none provided on the command line.
+  # @return [Brut::CLI::Commands::BaseCommand|nil] if `nil`, it is an error to run this command without a subcommand. If not-`nil`,
+  #         the returned command will be executed.
+  def default_command = self.commands.detect { it.class == default_command_class }
+
+  def default_command_class = nil
+
+  # Returns a list of commands that represent the subcommands available to this command. By default, this
+  # will return all commands that are inner classes of this command.
+  #
+  # @return [Array<Brut::CLI::Commands::BaseCommand>]
+  def commands
+    self.class.constants.map { |name|
+      self.class.const_get(name)
+    }.select { |constant|
+      constant.kind_of?(Class) && constant.ancestors.include?(Brut::CLI::Commands::BaseCommand)
+    }.map(&:new)
+  end
+
+private
+
+  # Provides access the `Brut::CLI::Commands::ExecutionContext` used the last time `#execute` was called.
+  # This should only be accessed in tests and sparingly.
+  def execution_context
+    @execution_context ||= Brut::CLI::Commands::ExecutionContext.new
+  end
+
+  # Access the command line arguments leftover after all options have been parsed, when `.execute` was called
+  #
+  # @return [Array<String>] leftover command line arguments
+  # @!visibility public
+  def argv = self.execution_context.argv
+
+  # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext`'s `Brut::CLI::Executor#system!`.
+  # @!visibility public
+  def system!(*args,&block)
+    self.execution_context.executor.system!(*args,&block)
+  end
+
+  # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#stdout`'s  `puts`.
+  # @!visibility public
+  def puts(*args)
+    self.execution_context.stdout.puts(*args)
+  end
+
+  # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#stderr`. You should use this over `STDERR` or `$stderr`.
+  # @!visibility public
+  def stderr  = self.execution_context.stderr
+  # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#stdin`. You should use this over `STDIN` of `$stdin`.
+  # @!visibility public
+  def stdin   = self.execution_context.stdin
+  # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#stdout`. You should use this over `STDOUT` of `$stdout`. Note
+  # that if you just want to output a string, use `puts`.
+  # @!visibility public
+  def stdout  = self.execution_context.stdout
+  # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#options`.
+  # @!visibility public
+  def options = self.execution_context.options
+  # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#env`. You should use this over `ENV`.
+  # @!visibility public
+  def env     = self.execution_context.env
+
+
+  # Runs whatever logic this command exists to execute.  This is the method you must implement, however `#execute` is the public
+  # API and what you should call if you want to programmatically execute a command.
+  #
+  # The default implementation will generate an error, which is suitable for an app or namespace command that require a subcommand.
+  #
+  # @return [Integer|Object|StandardError] When an integer is returned, that is considered the exit status of the CLI
+  #         invocation that ultimately called this command. If an `Object` (including `nil` and non-`Integer` numbers) is returned,
+  #         the command is assumed to have succeeded and the return value is ignored.  If an exception is returned, it's treated
+  #         the same as if it were raised (don't return an exception).
+  # @raise [Brut::CLI::Error|StandardError] If a `Brut::CLI::Error`, the command
+  #         is considered failed and the exception's message is printed to stderr and the exit status is nonzero. If another
+  #         type of exception, it is bubbled up and shown to the user. Generally do not return any sort of  exception - allow it to raise.
+  # @!visibility public
+  def run
+    if argv[0]
+      stderr.puts "No such command '#{argv[0]}'"
+      return 1
+    end
+
+
+    stderr.puts "Command is required"
+    1
+  end
+end

data/lib/brut/cli/commands/compound_command.rb

@@ -0,0 +1,29 @@
+# A command that exists only to call other commands in order.  This is useful if you want
+# a convienience command to call two or more other commands.  By default, each command
+# must succeed for the others to be called.
+class Brut::CLI::Commands::CompoundCommand < Brut::CLI::Commands::BaseCommand
+  # Create the compound command with the given list of commands.  Note that these
+  # commands will be executed with *this* commands `Brut::CLI::Commands::ExecutionContext`, so these commands
+  # should all be able to work with whatever command line arguments and `argv` would be provided.
+  def initialize(commands)
+    @commands = commands
+  end
+
+  # Overrides the parent class to call each command in order. Note that if you subclass this class, **`run` is
+  # not called**. If you want to perform custom logic, you must override this method, but take care to call
+  # methods on the passed `execution_context`.  Methods like `puts`, `system!`, and `options` **will not work** here
+  # since they assume an ivar named `@execution_context` has been set.
+  def execute(execution_context)
+    @commands.each do |command|
+      execute_result = Brut::CLI::ExecuteResult.new do
+        command.execute(execution_context)
+      end
+      if execute_result.failed?
+        return execute_result.exit_status do |error_message|
+          @stderr.puts error_message
+        end
+      end
+    end
+    0
+  end
+end

data/lib/brut/cli/commands/execution_context.rb

@@ -0,0 +1,32 @@
+# The context in which a command's execution is run.  This holds essentially all values that are input to
+# the command, including parsed command line options, unparsed arguments, the UNIX environment, and
+# the three s/O streams (stderr, stdout, stdin).
+class Brut::CLI::Commands::ExecutionContext
+
+  def initialize(
+    argv: :default,
+    options: :default,
+    env: :default,
+    stdout: :default,
+    stderr: :default,
+    stdin: :default,
+    executor: :default
+  )
+    @argv     =                             argv == :default ? []                                                          : argv
+    @options  =                          options == :default ? Brut::CLI::Options.new({})                                  : options
+    @env      =                              env == :default ? {}                                                          : env
+    @stdout   = Brut::CLI::Output.from_io(stdout == :default ? $stdout                                                     : stdout)
+    @stderr   = Brut::CLI::Output.from_io(stderr == :default ? $stderr                                                     : stderr)
+    @stdin    =                            stdin == :default ? $stdin                                                      : stdin
+    @executor =                         executor == :default ? Brut::CLI::Executor.new(out: self.stdout, err: self.stderr) : executor
+  end
+
+  attr_reader :argv,
+              :options,
+              :env,
+              :stdout,
+              :stderr,
+              :stdin,
+              :executor
+
+end

data/lib/brut/cli/commands/help.rb

@@ -0,0 +1,26 @@
+class Brut::CLI::Commands::Help < Brut::CLI::Commands::BaseCommand
+  def description = "Get help for the app or a command"
+  attr_accessor :option_parser
+
+  def initialize(command,option_parser)
+    @command = command
+    @option_parser = option_parser
+  end
+
+  def commands = []
+
+  def run
+    stdout.puts_no_prefix @option_parser.to_s
+    if @command.commands.any?
+      stdout.puts_no_prefix
+      stdout.puts_no_prefix "COMMANDS"
+      stdout.puts_no_prefix
+      @command.commands.each do |command|
+        stdout.puts_no_prefix "  #{command.name} - #{command.description}"
+      end
+    end
+    0
+  end
+  def bootstrap? = false
+  def default_rack_env = nil
+end

data/lib/brut/cli/commands/output_error.rb

@@ -0,0 +1,13 @@
+class Brut::CLI::Commands::OutputError < Brut::CLI::Commands::BaseCommand
+  attr_reader :exception
+  def initialize(exception)
+    @exception = exception
+  end
+  def run
+    stderr.puts @exception.message
+    65
+  end
+
+  def bootstrap? = false
+  def default_rack_env = nil
+end

data/lib/brut/cli/commands/raise_error.rb

@@ -0,0 +1,11 @@
+class Brut::CLI::Commands::RaiseError < Brut::CLI::Commands::BaseCommand
+  attr_reader :exception
+  def initialize(exception)
+    @exception = exception
+  end
+  def run
+    raise @exception
+  end
+  def bootstrap? = false
+  def default_rack_env = nil
+end

data/lib/brut/cli/commands.rb

@@ -0,0 +1,8 @@
+module Brut::CLI::Commands
+  autoload(:BaseCommand, "brut/cli/commands/base_command")
+  autoload(:CompoundCommand, "brut/cli/commands/compound_command")
+  autoload(:Help, "brut/cli/commands/help")
+  autoload(:OutputError, "brut/cli/commands/output_error")
+  autoload(:RaiseError, "brut/cli/commands/raise_error")
+  autoload(:ExecutionContext, "brut/cli/commands/execution_context")
+end

data/lib/brut/cli/execute_result.rb

@@ -0,0 +1,39 @@
+# Wraps the result of calling `Brut::CLI::Commands::BaseCommand#execute` and 
+# interpreting it as an exit code
+class Brut::CLI::ExecuteResult
+  def initialize(&block)
+    @actual_result = begin
+                       block.()
+                     rescue Brut::CLI::Error => ex
+                       ex
+                     end
+  end
+
+  def success? =  self.exit_status == 0
+  def failed?  = !self.success?
+
+  # Get the exit status for the given result.  This will call
+  # the block given with an error message if there is one.
+  #
+  # @yield [error_message] If a block is passed, it's called when a {Brut::CLI::Error} was the return
+  #        value of the command, so that you can access the message of the error.
+  # @yieldparam error_message [String] the error message from the {Brut::CLI::Error}.
+  #
+  # @return [Integer] value betweeen 0 and 255 representing the exit status to use based on the 
+  #         value the command returned.
+  def exit_status(&when_error_message)
+    when_error_message ||= ->(*){}
+    case @actual_result
+    in Integer
+      @actual_result
+    in Brut::CLI::SystemExecError
+      when_error_message.(@actual_result.message)
+      @actual_result.exit_status
+    in Brut::CLI::Error
+      when_error_message.(@actual_result.message)
+      1
+    else
+      0
+    end
+  end
+end

data/lib/brut/cli/executor.rb

@@ -50,7 +50,13 @@ class Brut::CLI::Executor
   # @param [String|Array] args Whatever you would give to `Kernel#system` or `Open3.popen3`.
   # @raise Brut::CLI::Error::SystemExecError if the spawed command exits nonzero
   # @return [int] Always returns 0
-  def system!(*args)
+  def system!(*args,&block)
+
+    block ||= ->(output) {
+      @out.print output
+      @out.flush
+    }
+
     @out.puts "Executing #{args}"
     wait_thread = Open3.popen3(*args) do |_stdin,stdout,stderr,wait_thread|
       o = stdout.read_nonblock(10, exception: false)
@@ -58,8 +64,7 @@ class Brut::CLI::Executor
       while o || e
         if o
           if o != :wait_readable
-            @out.print o
-            @out.flush
+            block.(o)
           end
           o = stdout.read_nonblock(10, exception: false)
         end
@@ -74,7 +79,7 @@ class Brut::CLI::Executor
       wait_thread
     end
     if wait_thread.value.success?
-      @out.puts "#{args} succeeded"
+      @out.puts "#{args.length == 1 ? args[0] : args} succeeded"
     else
       raise Brut::CLI::SystemExecError.new(args,wait_thread.value.exitstatus)
     end

data/lib/brut/cli/output.rb

@@ -14,6 +14,19 @@
 # The prefix allows the human to know what output was generated by the app they ran and what not.  This can be extremely helpful for
 # debugging or just understanding what is going on.
 class Brut::CLI::Output
+
+  def self.from_io(io_or_output)
+    case io_or_output
+    in Brut::CLI::Output
+      io_or_output
+    else
+      self.new(io: io_or_output, prefix: "")
+    end
+  end
+
+  attr_reader :io
+  attr_reader :prefix
+
   # Create a wrapper for the given IO that will use the given prefix
   #
   # @param [IO] io an IO where output should be sent, for example `$stdout`.