brut 0.16.0 → 0.18.0

data/lib/brut/tui/script/exec_step.rb

@@ -0,0 +1,67 @@
+require "open3"
+
+# A step whose behavior is to run a command as a child process.
+# Fires {Brut::TUI::Script::Events::StepStarted} then
+# {Brut::TUI::Script::Events::ExecutingCommand} before the command is run.
+# The command is then run with `Open3.popen3` and the stderr and stdout
+# are streamed as output is available. Each block of bytes read
+# generates a {Brut::TUI::Script::Events::CommandStdOut}
+# or a {Brut::TUI::Script::Events::CommandStdErr} event with 
+# the bytes reads.
+#
+# If the command exited nonzero, 
+# {Brut::TUI::Script::Events::CommandExecutionSucceeded} is fired,
+# otherwise {Brut::TUI::Script::Events::CommandExecutionFailed} is fired,
+# Either way, {Brut::TUI::Script::Events::StepCompleted} is fired
+# *unless* there is an unhandled exception.
+class Brut::TUI::Script::ExecStep < Brut::TUI::Script::Step
+
+  attr_reader :command
+  def initialize(event_loop, description, command:, stdout: false, stderr: false)
+    super(event_loop, description)
+    @command = command
+    @stdout  = stdout
+    @stderr  = stderr
+  end
+
+  def deconstruct_keys(keys=nil)
+    super.deconstruct_keys(keys).merge({
+      command: @command,
+      strip_ansi: false,
+      stdout: @stdout,
+      stderr: @stderr
+    })
+  end
+  def run!
+    event_loop << Events::StepStarted.new(step: self)
+    event_loop << Events::ExecutingCommand.new(step: self)
+
+    wait_thread = Open3.popen3(*@command) do |_stdin,stdout,stderr,wait_thread|
+      o = stdout.read_nonblock(10, exception: false)
+      e = stderr.read_nonblock(10, exception: false)
+      while o || e
+        if o
+          if o != :wait_readable
+            event_loop << Events::CommandStdOut.new(step: self, output: o, show: @stdout)
+          end
+          o = stdout.read_nonblock(10, exception: false)
+        end
+        if e
+          if e != :wait_readable
+            event_loop << Events::CommandStdErr.new(step: self, output: e, show: @stderr)
+          end
+          e = stderr.read_nonblock(10, exception: false)
+        end
+      end
+      wait_thread
+    end
+
+    if wait_thread.value.success?
+      event_loop << Events::CommandExecutionSucceeded.new(step: self)
+    else
+      event_loop << Events::CommandExecutionFailed.new(step: self)
+    end
+    event_loop << Events::StepCompleted.new(step: self)
+  end
+end
+

data/lib/brut/tui/script/logging_subscriber.rb

@@ -0,0 +1,98 @@
+# A subscriber that uses Ruby's logger to log messages.
+# The purpose of this is to ensure that every bit of available information about
+# a `Script` is placed somewhere for later review. This allows any output to the terminal
+# to be more brief or user-friendly without losing information.
+class Brut::TUI::Script::LoggingSubscriber
+  def initialize(progname, logfile:)
+    @logger = Logger.new(logfile, progname:)
+    @logger.formatter = proc { |severity, time, progname, msg|
+      "#{time} - [ #{progname} ] #{severity}: #{strip_ansi(msg)}\n"
+    }
+    @stdout = {}
+    @stderr = {}
+  end
+
+  def on_event_loop_started(event)
+    @logger.debug("TUI Event loop started")
+  end
+
+  def on_exception(event)
+    @logger.error("#{event.exit? ? 'FATAL' : 'non-fatal'} ExceptionEvent: #{event.exception.class}: #{event.exception.message}\n    #{event.exception.backtrace.join("\n    ")}")
+  end
+
+  def on_executing_command(command:)
+    @logger.info("Executing command `#{command}`")
+    @stdout[command] = ''
+    @stderr[command] = ''
+  end
+
+  def on_command_std_out(command:, output:)
+    @stdout[command] << output
+  end
+
+  def on_command_std_err(command:, output:)
+    @stderr[command] << output
+  end
+
+  def on_command_execution_succeeded(command:)
+    if !@stdout[command].empty?
+      @logger.info("\n#{strip_ansi(@stdout[command])}")
+    end
+    if !@stderr[command].empty?
+      @logger.warn("\n#{strip_ansi(@stderr[command])}")
+    end
+    @logger.info("Command `#{command}` executed successfully.")
+  end
+
+  def on_command_execution_failed(command:)
+    if !@stdout[command].empty?
+      @logger.info("\n#{strip_ansi(@stdout[command])}")
+    end
+    if !@stderr[command].empty?
+      @logger.warn("\n#{strip_ansi(@stderr[command])}")
+    end
+    @logger.error("Command `#{command}` failed.")
+    raise "DOH"
+  end
+
+  def on_model_updated(*)
+  end
+
+  def on_tick(*)
+  end
+
+  def on_script_completed(*)
+  end
+
+  def on_script_started(*)
+  end
+
+  def on_any_event(event)
+    case event
+    in { description: }
+      @logger.info(description)
+    in { message:, type: :warning }
+      @logger.warn(message)
+    in { message:, type: :error }
+      @logger.error(message)
+    in { message: }
+      @logger.info(message)
+    in { handler_method_name: }
+      @logger.info(handler_method_name)
+    else
+      @logger.info(event.to_s)
+    end
+  end
+private
+
+  ANSI_ESCAPE = %r{ 
+    \e\[[@-Z\\-_] |           # 1-byte sequences
+    \e\[[0-?]*[ -\/]*[@-~] |  # CSI sequences
+    \e\][^\a]*\a |            # OSC sequences
+    \eP[^\a]*\a |             # DCS
+    \e_[^\a]*\a |             # APC
+    \e\^[^\a]*\a              # PM
+  }x
+
+  def strip_ansi(string) = string.gsub(ANSI_ESCAPE, '')
+end

data/lib/brut/tui/script/puts_subscriber.rb

@@ -0,0 +1,109 @@
+# A subscriber that attempts to provide a user-friend, brief, summarized, fancy
+# output for the script that is running.  It is intended to show you
+# what's happening at a high level, but deferring all details (like child process
+# output) to the {Brut::TUI::Script::LoggingSubscriber}'s log file.
+class Brut::TUI::Script::PutsSubscriber
+  def initialize(progname, terminal:, theme:, stdout: false, stderr: false)
+    @progname      = progname
+    @terminal      = terminal
+    @theme         = theme
+    @prefix_recent = false
+    @stdout        = stdout
+    @stderr        = stderr
+    @stdout_buffer = {}
+    @stderr_buffer = {}
+    @step_indent   = "Phase 1/1 ".length
+  end
+
+  def on_phase_started(description:, step_number:, total_steps:)
+    total_format_string = if total_steps < 10
+                            "%1d"
+                          else
+                            "%2d"
+                          end
+    preamble = sprintf("Phase %d/#{total_format_string}", step_number, total_steps)
+    @step_indent = preamble.length + 1
+    println @theme.reset + @theme.bold + preamble + @theme.reset + " " + @theme.with_markup(description, text: :heading)
+  end
+
+  def on_step_started(description:)
+    println @theme.with_markup(description), step_indent: true
+  end
+
+  def on_executing_command(command:)
+    println @theme.with_markup("> `#{command}`"), step_indent: true
+    $stdout.print @theme.reset
+    @stdout_buffer[command] = ""
+    @stderr_buffer[command] = ""
+  end
+
+  def on_command_execution_failed(command:)
+    println @theme.with_markup("FAILED", text: :error), step_indent: true
+    if !@stdout
+      println ""
+      println @stdout_buffer[command] + "\n"
+    end
+    if !@stderr
+      println ""
+      println @theme.warning + @stderr_buffer[command]
+    end
+
+  end
+
+  def on_exception(exception:)
+    println @theme.error + "Exception: #{exception.class}: #{exception.message}\n    #{exception.backtrace.join("\n    ")}"
+  end
+
+  def on_command_std_out(output:, command:, show:)
+    if @stdout || show
+      @prefix_recent = false
+      $stdout.print @theme.normal + @theme.weak + output + @theme.reset
+      $stdout.flush
+    else
+      @stdout_buffer[command] << output
+    end
+  end
+
+  def on_command_std_err(output:, command:, show:)
+    if @stderr || show
+      @prefix_recent = false
+      $stdout.print @theme.warning + output + @theme.reset
+      $stdout.flush
+    else
+      @stderr_buffer[command] << output
+    end
+  end
+
+  def on_command_execution_succeeded(command:)
+    println @theme.with_markup("✅", text: :success), step_indent: true
+  end
+
+  def on_message(message:, type:)
+    if type == :done
+      println @theme.with_markup(message, text: :success)
+    else
+      println @theme.with_markup(message, text: type), step_indent: true
+    end
+  end
+
+
+private
+
+  def prefix_string = "[ #{@progname} ] "
+
+  def step_indent = @step_indent
+
+  def println(message, step_indent: false)
+    @terminal.io.puts prefix + (step_indent ? " " * self.step_indent : "") + message
+  end
+
+  def prefix
+    if @prefix_recent
+      @theme.italic + @theme.weak + prefix_string + @theme.weak_off + @theme.italic_off
+    else
+      @prefix_recent = true
+      prefix_string
+    end
+  end
+end
+

data/lib/brut/tui/script/step.rb

@@ -0,0 +1,13 @@
+# Base class for specific types of steps
+class Brut::TUI::Script::Step
+
+  Events = Brut::TUI::Script::Events
+
+  attr_reader :description
+  def initialize(event_loop, description, exec: nil, &block)
+    @event_loop = event_loop
+    @description = description
+  end
+
+  private attr_reader :event_loop
+end

data/lib/brut/tui/script.rb

@@ -0,0 +1,215 @@
+require "logger"
+require "fileutils"
+
+# A TUI script is a set of steps that are executed in order.  Steps
+# can be grouped int phases, and each step can either shell out
+# to an external command or execute Ruby code.
+#
+# You are intended to subclass this class and implement `#execute`, which can use
+# the various methods described here to describe the script.  In the context of a 
+# Brut CLI, your subclass would be used inside the {Brut::CLI::Command#execute} method, where
+# it would call `#run!` (not `#execute`).
+#
+# Inside `#execute` you should call `#phase` for each logical phase/grouping of steps. There must be at least
+# one phase.  Inside each `phase` you should call `#step` one or more times.  When a phase is actually executed,
+# it's contents are executed, so anything inside the block will be called.  Intermediate variables to allow `step`s to
+# communicate will work.
+#
+# After all phases, call `done` with a success message.
+#
+# @example
+#     def execute
+#       phase "Set up test data" do
+#         step "Initializing database",
+#              exec: "brut db rebuild -e test"
+#         step "Loading data" do
+#           MyData.each do |data|
+#             notify "Inserting #{data}"
+#             data.insert!
+#           end
+#         end
+#       end
+#       phase "Checking data integrity" do
+#         problems = []
+#         step "Analyzing data" do
+#           MyData.each do |data|
+#             if !data.analyze
+#               problems << data
+#             end
+#           end
+#         end
+#         step "Checking problems" do
+#           abort = false
+#           problems.each do |problem|
+#             if problem.warning?
+#               warning "#{problem} may be an issue, but we can proceed"
+#             else
+#               error "#{problem} will prevent our test from working"
+#               abort = true
+#             end
+#           end
+#           if abort
+#             raise "Problems prevented script from working"
+#           end
+#         end
+#       end
+#       
+#       done "All ready to go!"
+#     end
+class Brut::TUI::Script
+
+  autoload(:Step              , "brut/tui/script/step")
+  autoload(:BlockStep         , "brut/tui/script/block_step")
+  autoload(:ExecStep          , "brut/tui/script/exec_step")
+  autoload(:LoggingSubscriber , "brut/tui/script/logging_subscriber")
+  autoload(:PutsSubscriber    , "brut/tui/script/puts_subscriber")
+  autoload(:Events            , "brut/tui/script/events")
+
+  # Return the basename of a log file unique to this script. This will use
+  # the subclass name to come up with a reasonable name, however your
+  # class can override this.
+  def self.log_filename
+    name = self.name.gsub(/Script$/,"").gsub(/::$/,"").split("::").last
+    name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+  end
+
+  # Create the script. By default, two subscribers are set up: {Brut::TUI::Script::LoggingSubscriber}
+  # and {Brut::TUI::Script::PutsSubscriber}.  The logging subscriber will output a detailed
+  # log into `logs/` using the file named by {.log_filename}.  The `PutsSubscriber` will
+  # output ANSI-Fancy messages as the script proceeds.
+  #
+  # @param root_dir [String|Pathname] path to the root of the Brut project.
+  # @param ansi [true|false] if true, the {Brut::TUI::Script::PutsSubscriber} will use
+  #        ANSI escape codes to format the output. If false, it won't.
+  def initialize(root_dir: nil, ansi: true)
+    @root_dir = root_dir ? Pathname(root_dir).expand_path : nil
+    logs_dir = if @root_dir
+                @root_dir / "logs" 
+              else
+                Pathame(".") / "logs"
+              end
+    FileUtils.mkdir_p(logs_dir)
+    @event_loop = Brut::TUI::EventLoop.new
+
+    logging_subscriber = LoggingSubscriber.new($0, logfile: logs_dir / "#{self.class.log_filename}.log")
+    terminal = Brut::TUI::Terminal.new
+    theme = if ansi
+               Brut::TUI::TerminalTheme.based_on_background(terminal)
+             else
+               Brut::TUI::Themes::None.new(terminal)
+             end
+    puts_subscriber = Brut::TUI::Script::PutsSubscriber.new($0, terminal:, theme:)
+
+    @event_loop.subscribe(Brut::TUI::Events::EventLoopStarted,self)
+    @event_loop.subscribe_to_all(logging_subscriber)
+    @event_loop.subscribe_to_all(puts_subscriber)
+
+  end
+
+  # @!visibility private
+  def on_event_loop_started(event)
+    Thread.new do
+      begin
+        @phases = []
+        self.execute
+        @event_loop << Events::ScriptStarted.new(phases: @phases)
+        @phases.each_with_index do |(name,block), index|
+          step_number = index + 1
+          @event_loop << Events::PhaseStarted.new(name, step_number: step_number, total_steps: @phases.length)
+          block.()
+          @event_loop << Events::PhaseCompleted.new(name, step_number: step_number, total_steps: @phases.length)
+        end
+        @event_loop << Events::Message.new(message: @done_message || "Script completed successfully", type: :done)
+      rescue => ex
+        @event_loop << Brut::TUI::Events::Exception.new(ex)
+      end
+      @event_loop << Events::ScriptCompleted.new
+    end
+  end
+
+  # Entry point for a script. This method starts the event loop.
+  def run!
+    if !self.methods.include?(:execute)
+      raise "You must implement the execute method in your Brut::TUI::Script subclass"
+    end
+    @event_loop.run
+    0
+  end
+
+  # Create a new phase for the script. A phase is basically a named group
+  # of steps.  The block is not executed immediately, so you may not pass
+  # data from one phase to another.
+  #
+  # @param name [String] The name of the phase
+  # @param block [Proc] The block to execute for the phase
+  def phase(name, &block)
+    @phases << [ name, block ]
+  end
+
+  # A step to run inside a phase.  Steps within phases are executed immediately once the phase
+  # has started, so they can pass data to one anther.
+  #
+  # @param description [String] Message to show the user about this step.
+  # @param exec [String|nil] if non-nil, this step will execute this as a command.  A block given is ignored.
+  #        If `nil`, a block should be given that contains the step's code.
+  # @param stdout [true|false] if `exec` is set, and this is true, it means this command's stdout
+  #        is relevant to the script and should be shown if possible.
+  # @param stderr [true|false] if `exec` is set, and this is true, it means this command's stderr
+  #        is relevant to the script and should be shown if possible.
+  # @yield if `exec` is `nil`, this block will be executed for the step
+  def step(description, exec: nil, stdout: false, stderr: false, &block)
+    step = if exec.nil?
+             BlockStep.new(@event_loop, description, &block)
+           else
+             ExecStep.new(@event_loop, description, command: exec, stdout:, stderr:)
+           end
+    step.run!
+  end
+
+  # Notify the user of an event
+  #
+  # @param message [String] Message to show
+  def notify(message)
+    @event_loop << Events::Message.new(message:, type: :notification)
+  end
+
+  # Warn the user of an event
+  #
+  # @param message [String] Message to show
+  def warning(message)
+    @event_loop << Events::Message.new(message:, type: :warning)
+  end
+
+  # Let the user know something succeeded
+  #
+  # @param message [String] Message to show
+  def success(message)
+    @event_loop << Events::Message.new(message:, type: :success)
+  end
+
+  # Message to show if the script completes successful.  Should only be called once
+  # and not inside a phase or step.
+  #
+  # @param message [String] Message to show
+  def done(message)
+    @done_message = message
+  end
+
+  # Let the user know there was an error. Note that this will not stop
+  # the script.  Raise an exception to do that.
+  #
+  # @param message [String] Message to show
+  def error(message)
+    @event_loop << Events::Message.new(message:, type: :error)
+  end
+
+  # Wrap a fully-qualified filename in code markup and trim the path to only
+  # show the path relative to the root dir.  This is much friendlier than showing a
+  # long expanded path.
+  #
+  # @param path [String|Pathname] a fully-qualified path to something inside your Brut app.
+  def filename(path)
+    path = Pathname(path).expand_path
+    "`" + (@root_dir ? path.relative_path_from(@root_dir) : path).to_s + "`"
+  end
+end

data/lib/brut/tui/terminal.rb

@@ -0,0 +1,74 @@
+require "io/console"
+require "timeout"
+require "stringio"
+
+# Stores metdata about the current temrinal in use. This should provide any metadata
+# about the terminal that can be reliably determined. 
+class Brut::TUI::Terminal
+
+  def initialize
+    trap("WINCH") do
+      @winsize = IO.console.winsize
+    end
+  end
+
+  # Number of rows for the current terminal. Should be consistent even after a resize
+  def rows = winsize[0]
+  # Number of columns for the current terminal. Should be consistent even after a resize
+  def cols = winsize[1]
+
+  # The IO used for outputing information to the terminal. Prefer this over `STDOUT`.
+  def io    = $stdout
+
+  # The IO to use for requesting input from the user
+  def stdin = $stdin
+  
+  # Best attempt to guess the background color of the current terminal.
+  # This will not refresh if that color is changed, and its behavior will
+  # default to black if determining the color doesn't work or isn't supported.
+  def background_color
+    @bakground_color ||= begin
+                           io.write "\e]11;?\a"
+                           io.flush
+
+                           result = nil
+
+                           begin
+                             # Read the reply, which should look like:
+                             #   ESC ] 11 ; rgb:0000/0000/0000 BEL
+                             Timeout.timeout(0.1) do
+                               buf = +""
+                               loop do
+                                 ch = stdin.getch
+                                 buf << ch
+                                 break if ch == "\a" || buf.end_with?("\e\\") # BEL or ST terminator
+                               end
+                               result = buf
+                             end
+                           rescue Timeout::Error
+                             # no reply within 100ms — terminal probably doesn’t support it
+                           end
+
+                           rgb = [ 0, 0, 0 ]
+                           if result
+                             if result =~ /\e\]11;([^ \a\e]*)[\a\e\\]/
+                               color = Regexp.last_match(1)
+                               parts = color[/rgb:(.*)/, 1]&.split("/")
+                               if parts
+
+                                 rgb = parts.map { it.to_i(16) / 0xffff.to_f * 256 }.map(&:to_i)
+                               end
+                             end
+                           end
+                           rgb
+                         end
+  end
+
+
+private
+
+  def winsize
+    @winsize ||= IO.console.winsize
+  end
+
+end