brut 0.18.2 → 0.19.1

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

@@ -19,15 +19,27 @@ class Brut::CLI::Commands::BaseCommand
     self.run
   end
 
+  def delegate_to_command(command,execution_context=:use_ivar)
+    execution_context = if execution_context == :use_ivar
+                          @execution_context
+                        else
+                          execution_context
+                        end
+    if execution_context.nil?
+      raise ArgumentError, "No execution context provided and none set on this command"
+    end
+    command.execute(execution_context)
+  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.
+  # By default, 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
+  def 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
@@ -35,11 +47,15 @@ class Brut::CLI::Commands::BaseCommand
   #
   # @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
+  def default_rack_env = nil
 
   # @return [String] description of this command for use in help output
   def description = ""
 
+  # Returns a more detaile description of the command. This can includes paragraphs which will be maintained, however
+  # any additional formatting is not rendered or used.
+  def detailed_description = nil
+
   # @return [String] description of the arguments this command accepts. Used for documentation only.
   def args_description = nil
 
@@ -85,13 +101,6 @@ class Brut::CLI::Commands::BaseCommand
   #         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.
   #
@@ -104,6 +113,11 @@ class Brut::CLI::Commands::BaseCommand
     }.map(&:new)
   end
 
+  def theme
+    @theme = Brut::CLI::TerminalTheme.new(terminal:)
+  end
+
+
 private
 
   # Provides access the `Brut::CLI::Commands::ExecutionContext` used the last time `#execute` was called.
@@ -121,25 +135,48 @@ private
   # 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)
+    output = ""
+    block ||= ->(output_chunk) {
+      output << output_chunk
+    }
+    begin
+      self.execution_context.executor.system!(*args,&block)
+    ensure
+      if output.length > 0
+        progname = args.detect { it.kind_of?(String) }.split(" ")
+        output.lines.each do |line|
+          self.execution_context.logger.add(Logger::INFO, line.chomp, progname)
+        end
+      end
+    end
   end
 
   # Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#stdout`'s  `puts`.
   # @!visibility public
   def puts(*args)
-    self.execution_context.stdout.puts(*args)
+    if !options.quiet?
+      self.execution_context.stdout.puts(*args)
+    end
+  end
+  def print(*args)
+    if !options.quiet?
+      self.execution_context.stdout.print(*args)
+    end
+  end
+
+  def debug(message) = self.execution_context.logger.debug(message)
+  def info(message)  = self.execution_context.logger.info(message)
+  def warn(message)  = self.execution_context.logger.warn(message)
+  def error(message) = self.execution_context.logger.error(message)
+  def fatal(message) = self.execution_context.logger.fatal(message)
+
+  def terminal
+    @terminal ||= Brut::CLI::Terminal.new
   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
@@ -163,12 +200,11 @@ private
   # @!visibility public
   def run
     if argv[0]
-      stderr.puts "No such command '#{argv[0]}'"
+      puts theme.error.render("No such command '#{argv[0]}'")
       return 1
     end
 
-
-    stderr.puts "Command is required"
+    puts theme.error.render("Command is required")
     1
   end
 end

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

@@ -16,12 +16,10 @@ class Brut::CLI::Commands::CompoundCommand < Brut::CLI::Commands::BaseCommand
   def execute(execution_context)
     @commands.each do |command|
       execute_result = Brut::CLI::ExecuteResult.new do
-        command.execute(execution_context)
+        delegate_to_command(command,execution_context)
       end
       if execute_result.failed?
-        return execute_result.exit_status do |error_message|
-          @stderr.puts error_message
-        end
+        return execute_result.actual_result
       end
     end
     0

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

@@ -1,6 +1,6 @@
 # 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).
+# the three I/O streams (stderr, stdout, stdin).
 class Brut::CLI::Commands::ExecutionContext
 
   def initialize(
@@ -10,15 +10,21 @@ class Brut::CLI::Commands::ExecutionContext
     stdout: :default,
     stderr: :default,
     stdin: :default,
-    executor: :default
+    executor: :default,
+    logger: :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
+    @argv       =    argv == :default ? []                                                          : argv
+    @options  =   options == :default ? Brut::CLI::Options.new({})                                  : options
+    @env      =       env == :default ? {}                                                          : env
+    @stdout   =    stdout == :default ? $stdout                                                     : stdout
+    @stderr   =    stderr == :default ? $stderr                                                     : stderr
+    @stdin    =     stdin == :default ? $stdin                                                      : stdin
+    @logger   =    logger == :default ? Brut::CLI::Logger.new(app_name: $0, stdout: @stdout, stderr: @stderr) : logger
+    @executor =  executor == :default ? Brut::CLI::Executor.new(logger: @logger, out: self.stdout, err: self.stderr) : executor
+
+    @logger.level         = @options.log_level
+    @logger.log_file      = @options.log_file
+    @logger.log_to_stdout = @options.log_stdout?
   end
 
   attr_reader :argv,
@@ -27,6 +33,7 @@ class Brut::CLI::Commands::ExecutionContext
               :stdout,
               :stderr,
               :stdin,
-              :executor
+              :executor,
+              :logger
 
 end

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

@@ -9,18 +9,124 @@ class Brut::CLI::Commands::Help < Brut::CLI::Commands::BaseCommand
 
   def commands = []
 
+  class DescriptionList
+    def initialize(term_align: :right, padding_bottom: 1)
+      @term_align = term_align
+      @padding_bottom = padding_bottom
+      @rows       = []
+    end
+    def <<(row)
+      @rows << row
+    end
+
+    def lipgloss_table(theme:, terminal:)
+      indent = "  "
+      term_width = @rows.map { |r| r[0].length }.max
+      description_width = terminal.cols - indent.length - term_width - 2
+      formatted_rows = @rows.map { |row|
+        [
+          row[0],
+          theme.wrap(row[1], indent: 0, max_width: description_width).strip,
+        ]
+      }
+      Lipgloss::Table.new.
+        border(:hidden).
+        rows(formatted_rows).
+        style_func(rows: formatted_rows.length, columns: 2) { |row,column|
+        if column == 0
+          Lipgloss::Style.new.inherit(theme.subheader).padding_bottom(@padding_bottom).align(@term_align)
+        else
+          Lipgloss::Style.new.padding_bottom(@padding_bottom)
+        end
+      }
+    end
+  end
+  
+
   def run
-    stdout.puts_no_prefix @option_parser.to_s
+    cli = [@command.name ]
+    cmd = @command
+    while cmd.parent_command
+      cmd = cmd.parent_command
+      cli.unshift cmd.name
+    end
+    invocation = cli.join(" ")
+    puts theme.code.render(invocation) + " - " + theme.title.render(theme.wrap(@command.description, indent: invocation.length + 3, max_width: 65).strip)
+    puts
+    usage = theme.code.render(invocation)
+    options = @option_parser.top.list
+    if options.size > 0
+      usage << theme.weak.render(" [options]")
+    end
     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}"
+      usage << theme.code.render(" command")
+    end
+    if @command.args_description
+      usage << " #{@command.args_description}"
+    end
+    puts theme.header.render("USAGE")
+    puts
+    puts "  " + usage
+    puts
+    if @command.detailed_description
+      puts theme.header.render("DESCRIPTION")
+      puts
+      puts theme.wrap(@command.detailed_description.strip, indent: 2, max_width: 65)
+      puts
+    end
+    if options.size > 0
+      puts theme.header.render("OPTIONS")
+      list = DescriptionList.new
+      options.each do |option|
+        switches = option.long.map { |switch|
+          if option.arg
+            if option.arg[0] == "="
+              "#{switch.strip}#{theme.weak.render(option.arg.strip)}"
+            else
+              "#{switch.strip}=#{theme.weak.render(option.arg.strip)}"
+            end
+          else
+            switch
+          end
+        } + option.short.map { |switch|
+          if option.arg
+            "#{switch} #{theme.weak.render(option.arg)}"
+          else
+            switch
+          end
+        }
+        list << [
+          switches.join("\n"),
+          option.desc.join(" "),
+        ]
+      end
+      puts list.lipgloss_table(theme:, terminal:).render
+    end
+    if @command.env_vars.any?
+      puts theme.header.render("ENVIRONMENT VARIABLES")
+      list = DescriptionList.new
+      @command.env_vars.sort_by(&:first).each do |env_var|
+        list << [
+          env_var[0],
+          env_var[1],
+        ]
       end
+      puts list.lipgloss_table(theme:, terminal:).render
+    end
+    if @command.commands.any?
+      puts theme.header.render("COMMANDS")
+      list = DescriptionList.new(term_align: :left, padding_bottom: 0)
+      @command.commands.sort_by(&:name).each do |command|
+        list << [
+          command.name,
+          command.description,
+        ]
+      end
+      puts list.lipgloss_table(theme:, terminal:).render
     end
     0
   end
+
   def bootstrap? = false
   def default_rack_env = nil
 end

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

@@ -4,7 +4,7 @@ class Brut::CLI::Commands::OutputError < Brut::CLI::Commands::BaseCommand
     @exception = exception
   end
   def run
-    stderr.puts @exception.message
+    error(@exception.message)
     65
   end
 

data/lib/brut/cli/execute_result.rb

@@ -1,11 +1,15 @@
 # Wraps the result of calling `Brut::CLI::Commands::BaseCommand#execute` and 
 # interpreting it as an exit code
 class Brut::CLI::ExecuteResult
+  attr_reader :actual_result
   def initialize(&block)
     @actual_result = begin
                        block.()
                      rescue Brut::CLI::Error => ex
                        ex
+                     rescue => ex2
+                       raise
+
                      end
   end
 

data/lib/brut/cli/executor.rb

@@ -9,11 +9,10 @@ require "open3"
 class Brut::CLI::Executor
   # Create the executor
   #
-  # @param [Brut::CLI::Output] out an IO used to send messages to the standard output
-  # @param [Brut::CLI::Output] err an IO used to send messages to the standard error
-  def initialize(out:,err:)
-    @out = out
-    @err = err
+  def initialize(out:,err:,logger:)
+    @out    = out
+    @err    = err
+    @logger = logger
   end
 
   # Execute a command, logging it to the standard output and outputing the 
@@ -57,7 +56,7 @@ class Brut::CLI::Executor
       @out.flush
     }
 
-    @out.puts "Executing #{args}"
+    @logger.info "Executing #{args}"
     wait_thread = Open3.popen3(*args) do |_stdin,stdout,stderr,wait_thread|
       o = stdout.read_nonblock(10, exception: false)
       e = stderr.read_nonblock(10, exception: false)
@@ -79,8 +78,9 @@ class Brut::CLI::Executor
       wait_thread
     end
     if wait_thread.value.success?
-      @out.puts "#{args.length == 1 ? args[0] : args} succeeded"
+      @logger.info "#{args.length == 1 ? args[0] : args} succeeded"
     else
+      @logger.info "'#{args.length == 1 ? args[0] : args}' failed with exit status #{wait_thread.value.exitstatus}"
       raise Brut::CLI::SystemExecError.new(args,wait_thread.value.exitstatus)
     end
     0

data/lib/brut/cli/logger.rb

@@ -0,0 +1,122 @@
+require "logger"
+require "fileutils"
+require "delegate"
+
+class Brut::CLI::Logger < SimpleDelegator
+  def initialize(app_name:, stdout:, stderr:, theme: nil)
+    @app_name = app_name
+    @stdout   = stdout
+    @logger   = ::Logger.new("/dev/null")
+
+    super(@logger)
+
+    @simple_formatter =  ->(severity, _time, progname, msg) {
+      formatted_severity = if theme
+                               case severity
+                               when "DEBUG"
+                                 theme.weak.render("DEBUG")
+                               when "INFO"
+                                 theme.header.render("INFO")
+                               when "WARN"
+                                 theme.warning.render("WARN")
+                               when "ERROR"
+                                 theme.error.render("ERROR")
+                               when "FATAL"
+                                 theme.error.render("FATAL")
+                               else
+                                 severity
+                               end
+                           else
+                             severity
+                           end
+      [
+        theme ? theme.weak.render("[ #{progname} ]") : "[ #{progname} ]",
+        "{#{formatted_severity}}",
+        msg,
+      ].join(" ") + "\n"
+    }
+    @file_formatter =  ->(severity, time, progname, msg) {
+      "#{time} - [ #{progname} ]{#{severity}} #{msg}\n"
+    }
+
+    @stdout_logger = ::Logger.new("/dev/null")
+    @stderr_logger = if stderr.nil? 
+                       ::Logger.new("/dev/null")
+                     else
+                       ::Logger.new(stderr, progname: @app_name, formatter: @simple_formatter)
+                     end
+
+    @log_file = nil
+  end
+
+  def level=(level)
+    if level
+      @logger.level = level
+      @stdout_logger.level = level
+      @stderr_logger.level = level
+    end
+  end
+
+  def log_file=(log_file)
+    @log_file = log_file
+    if log_file
+      log_dir = log_file.dirname
+      if !log_dir.exist?
+        FileUtils.mkdir_p(log_dir)
+      end
+      @logger = ::Logger.new(@log_file, formatter: @file_formatter, progname: @app_name, level: @logger.level)
+      __setobj__(@logger)
+      if @logger.level == ::Logger::DEBUG
+        @stdout.puts "Logging to file #{@log_file}"
+      end
+    end
+  end
+
+  def log_to_stdout=(log_to_stdout)
+    @log_to_stdout = log_to_stdout
+    if @log_to_stdout
+      @stdout_logger = ::Logger.new(@stdout, formatter: @simple_formatter, progname: @app_name, level: @logger.level)
+    else
+      @stdout_logger = ::Logger.new("/dev/null")
+    end
+  end
+  def debug(message=nil,&block)
+    @logger.debug(message,&block)
+    @stdout_logger.debug(message,&block)
+  end
+  def info(message=nil,&block)
+    @logger.info(message,&block)
+    @stdout_logger.info(message,&block)
+  end
+  def warn(message=nil,&block)
+    @logger.warn(message,&block)
+    @stdout_logger.warn(message,&block)
+    @stderr_logger.warn(message,&block)
+  end
+  def error(message=nil,&block)
+    @logger.error(message,&block)
+    @stdout_logger.error(message,&block)
+    @stderr_logger.error(message,&block)
+  end
+  def fatal(message=nil,&block)
+    @logger.fatal(message,&block)
+    @stdout_logger.fatal(message,&block)
+    @stderr_logger.fatal(message,&block)
+  end
+
+  def add(severity, message=nil, progname=nil, &block)
+    @logger.add(severity, message, progname, &block)
+    @stdout_logger.add(severity, message, progname, &block)
+    if severity >= ::Logger::WARN
+      @stderr_logger.add(severity, message, progname, &block)
+    end
+  end
+
+  def without_stderr
+    logger = self.class.new(app_name: @app_name, stdout: @stdout, stderr: nil)
+    logger.level = @logger.level
+    logger.log_file = @log_file
+    logger.log_to_stdout = @log_to_stdout
+    logger
+  end
+end

data/lib/brut/cli/output.rb

@@ -1,18 +1,8 @@
-# An `IO`-like class that provides user-helpful output, to be used in place of `puts`.  This is not strictly an `IO` and is intended to provide only a few options for sending output to a human.
+# An `IO`-like class that provides user-helpful output, to be used in place of `puts` and a logger. This is not replaceable for an IO.
 #
-# Command line apps that a human runs are often executed in the context of other apps or themselves spawn child processes.  Thus, it
-# can be hard to know what output is coming from where.  This class addresses that by prefixing every line with the name of the
-# command line app:
-#
-# ```
-# > bin/my_app doit
-# [ bin/my_app ] About to do sometohing
-# Cannot connect to house
-# [ bin/my_app ] Problem connecting
-# ```
-#
-# 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.
+# The problem this solves is allowing your CLI app to be clutter-free in the user's terminal, but to not hide information
+# unnecessarily or make it unclear where the output is coming from.  Your CLI should use this class (or the methods that proxy
+# to it, see `Brut::CLI::Commands::BaseCommand`) for all output and logging.
 class Brut::CLI::Output
 
   def self.from_io(io_or_output)
@@ -20,7 +10,7 @@ class Brut::CLI::Output
     in Brut::CLI::Output
       io_or_output
     else
-      self.new(io: io_or_output, prefix: "")
+      self.new(io: io_or_output, app_name: $0)
     end
   end
 
@@ -30,55 +20,29 @@ class Brut::CLI::Output
   # 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`.
-  # @param [String] prefix a prefix to be placed in front of all messages (unless a `_no_prefix` version is called)
-  def initialize(io:, prefix:)
+  # @param [String] app_name the name of the app that would be using this to generate output.
+  def initialize(io:, app_name:)
     @io          = io
-    @prefix      = prefix
+    @app_name    = app_name
     @sync_status = @io.sync
   end
 
-  # Calls `puts` without the prefix.  This is useful if the output is going to be obvious to the human user (e.g. CLI help), or if
-  # it's intended to be piped into another app.
-  #
-  # @see https://ruby-doc.org/3.3.6/Kernel.html#method-i-puts
-  def puts_no_prefix(*objects)
-    @io.puts(*objects)
-  end
-
-  # Calls `puts`, adding a prefix to each of the objects in `*objects`.  This is useful for sending messages that a human may want to
-  # read.
-  #
   # @see https://ruby-doc.org/3.3.6/Kernel.html#method-i-puts
   def puts(*objects)
     if objects.empty?
       objects << ""
     end
     objects.each do |object|
-      @io.puts(@prefix + object.to_s)
+      @io.puts(object)
     end
     nil
   end
 
-  # Calls `print` without any prefix.  In theory, this is the escape hatch to sending arbitrary data to the underlying `IO` without
-  # expose said `IO`
-  #
-  # @see https://ruby-doc.org/3.3.6/Kernel.html#method-i-print
-  def print(*objects)
-    @io.print(*objects)
-  end
-
   # Prints a string via `printf`, using the prefix.  This is useful for communciating to a human, but you need more power for
   # formatting than is afforded by {#puts}.
   #
   # @see https://ruby-doc.org/3.3.6/Kernel.html#method-i-printf
   def printf(format_string,*objects)
-    @io.printf(@prefix + format_string,*objects)
-  end
-
-  # Prints a string via `printf`, without the prefix.
-  #
-  # @see https://ruby-doc.org/3.3.6/Kernel.html#method-i-printf
-  def printf_no_prefix(format_string,*objects)
     @io.printf(format_string,*objects)
   end