brut 0.16.0 → 0.18.0

data/lib/brut/tui/ansi_escape_code.rb

@@ -0,0 +1,104 @@
+# Maps ANSI escape codes to logical names to make it easier to use in code.
+# This is not intended to be exhaustive, but could grow over time as needed.
+class Brut::TUI::AnsiEscapeCode
+
+  attr_reader :name
+
+  # Create a new AnsiEscapeCode with the given name and code.
+  #
+  # @param name [String, Symbol] The logical name of the escape code.
+  #                              This should not have spaces and generally be able to be used as a Ruby identifier.
+  # @param code [String] The actual ANSI escape code (without the leading `\e[` and trailing `m`).
+  def initialize(name, code)
+    @name = name.to_sym
+    @code = code
+  end
+
+  # Returns the code suitable for sending to the terminal.
+  def to_s = "\e[#{@code}m"
+
+  # Defines methods for each known code.  This module can be included
+  # into other classes so you can write `self.ansi.bright_blue` (e.g.)
+  # Note that `Brut::TUI::AnsiEscapeCode` _extends_ this module so you
+  # can always do `Brut::TUI::AnsiEscapeCode.ansi.bright_blue`.
+  module Mod
+    CODES = [
+      Brut::TUI::AnsiEscapeCode.new("reset"         , "0")  ,
+      Brut::TUI::AnsiEscapeCode.new("bold"          , "1")  ,
+      Brut::TUI::AnsiEscapeCode.new("normal"        , "22") ,
+      Brut::TUI::AnsiEscapeCode.new("italic"        , "3")  ,
+      Brut::TUI::AnsiEscapeCode.new("italic_off"    , "23") ,
+      Brut::TUI::AnsiEscapeCode.new("strike"        , "9")  ,
+      Brut::TUI::AnsiEscapeCode.new("strike_off"    , "29") ,
+      Brut::TUI::AnsiEscapeCode.new("weak"          , "2")  ,
+      Brut::TUI::AnsiEscapeCode.new("underline"     , "4")  ,
+      Brut::TUI::AnsiEscapeCode.new("underline_off" , "24") ,
+      Brut::TUI::AnsiEscapeCode.new("overline"      , "53") ,
+      Brut::TUI::AnsiEscapeCode.new("overline_off"  , "55") ,
+      Brut::TUI::AnsiEscapeCode.new("black"         , "30") ,
+      Brut::TUI::AnsiEscapeCode.new("red"           , "31") ,
+      Brut::TUI::AnsiEscapeCode.new("green"         , "32") ,
+      Brut::TUI::AnsiEscapeCode.new("yellow"        , "33") ,
+      Brut::TUI::AnsiEscapeCode.new("blue"          , "34") ,
+      Brut::TUI::AnsiEscapeCode.new("magenta"       , "35") ,
+      Brut::TUI::AnsiEscapeCode.new("cyan"          , "36") ,
+      Brut::TUI::AnsiEscapeCode.new("white"         , "37") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_black"  , "90") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_red"    , "91") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_green"  , "92") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_yellow" , "93") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_blue"   , "94") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_magenta", "95") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_cyan"   , "96") ,
+      Brut::TUI::AnsiEscapeCode.new("bright_white"  , "97") , 
+    ].map { [ it.name, it ] }.to_h.freeze
+
+    # The object returned by `#ansi` that has all the dynamically-defined methods
+    # on it.  Generally don't call this method directly.
+    def object
+      @object ||= begin
+                    object = Object.new
+                    CODES.each do |name, code|
+                      object.define_singleton_method(name) do
+                        code
+                      end
+                    end
+                    object
+                  end
+    end
+
+    # Method for accessing the pre-defined ANSI escape codes.  This method
+    # works in two ways: RGB mode and predefined mode based on the arguments passed.
+    #
+    # @param name [String|Symbol|Array<Integer>] If called with no arguments, return `#object`, allowing you to call
+    #        a dynamically-defined method based on the AnsiEscapeCode names in `CODES`.
+    #        If called with a String or Symbol, will return the AnsiEscapeCode for that name from `CODES`.
+    #        Otherwise, this should be exactly three integers, each between 0 and 255 that
+    #        represent red, green, and blue, respectively. In this case, the ANSI escape code
+    #        for an RGB value is returned.
+    # @return [Object|Brut::TUI::AnsiEscapeCode] The corresponding ANSI escape code object or the special `#object`.
+    #
+    # @example Using predefined codes
+    #   Brut::TUI::AnsiEscapeCode.ansi.red
+    #   Brut::TUI::AnsiEscapeCode.ansi.bold
+    #   Brut::TUI::AnsiEscapeCode.ansi.underline
+    #
+    # @example Using RGB codes
+    #   Brut::TUI::AnsiEscapeCode.ansi(87, 255, 128)
+    #
+    # @example Using code names
+    #   Brut::TUI::AnsiEscapeCode.ansi(:bright_blue)
+    #
+    def ansi(*name)
+      case name
+      in [ r, g, b ]
+        Brut::TUI::AnsiEscapeCode.new("rgb(#{r},#{g},#{b})", "38;2;#{r};#{g};#{b}")
+      in []
+        object
+      else
+        CODES.fetch(name[0].to_sym)
+      end
+    end
+  end
+  extend Mod
+end

data/lib/brut/tui/event_loop.rb

@@ -0,0 +1,168 @@
+# An event loop used to power any TUI, including those that just print
+# out messages.  This is intended to be used across multiple threads, with this running on the "main" thread
+# that is allowed to write to the screen.
+class Brut::TUI::EventLoop
+
+  # Create a new EventLoop.
+  #
+  # @param tick [true|false] if true, a "tick" event is fired every 50ms to allow progress spinners to animate.
+  def initialize(tick: true)
+
+    @queue = Deque.new
+
+    @queue << Brut::TUI::Events::EventLoopStarted.new
+
+    @event_bus = Brut::TUI::Events::EventBus.new
+    @tick = tick
+  end
+
+  # Queue an event for later processing. This is safe to do from another thread.
+  #
+  # @param event [Brut::TUI::Events::BaseEvent] the event to queue.
+  def <<(event)
+    @queue << event
+  end
+
+  # Subscribe to a specific event.  This requires that `subscriber` implement the handler method
+  # exposed by {Brut::TUI::Events::BaseEvent.handler_method_name}.  The method's arguments must be 
+  # one of three forms:
+  #
+  # * no-args (or a single `:rest` arg, like `(*)`) - the method is called when the event occurs, no arguments are passed, thus no information about the event is available.
+  # * single required arg (e.g. `(event)`) - the event instance is passed.
+  # * keyword args (e.g. `(description:, command:)`) - the event is splatted via `deconstruct_keys` and passed in for any keyword arg.  If
+  #   required keyword args aren't available from the event, an exception is raised.  If optional keyword args aren't available from the event,
+  #   their default values are provided.  Each event should document what keyword args are available.
+  #  
+  # In all cases, if the method raises an exception, it is captured and sent as a {Brut::TUI::Events::Exception} event, potentially to be
+  # handled by other subscribers.  See `#run` for how this interacts with the loop.
+  #
+  # @param event_class [Class] the event `subscriber` should be notified about. This should be a subclass of {Brut::TUI::Events::BaseEvent}.
+  # @param subscriber [Object] object to be notified about the given event.
+  def subscribe(event_class, subscriber)
+    @event_bus.subscribe(event_class, subscriber)
+  end
+
+  # Subscribe to all events.  `subscriber` will only be notified if it
+  # implements an event's {Brut::TUI::Events::BaseEvent.handler_method_name} *or* if the subscriber implements
+  # `on_any_event`. If both are implemented, only the more specific method is called. See `#subscribe` for a description of
+  # how the method is invoked.  If a specific method is not provided, `on_any_event` is invoked with
+  # the event instance. There is no keyword splatting in this case.
+  #
+  # @param subscriber [Object] object to be notified about the given event.
+  def subscribe_to_all(subscriber)
+    @event_bus.subscribe_to_all(subscriber)
+  end
+
+  # Start the event loop.  Don't call this more than once.  It will block and continue running
+  # until an event is received that returns true for {Brut::TUI::Events::BaseEvent#exit?}
+  # or {Brut::TUI::Events::BaseEvent#drain_then_exit?}.
+  #
+  # If {Brut::TUI::Events::BaseEvent#exit?} returns true, the loop is exited and any events left
+  # in the queue are unprocessed, essentially ignored/discarded.
+  #
+  # If {Brut::TUI::Events::BaseEvent#drain_then_exit?}
+  # returns true, anything currently in the queue is processed before exiting. If any subscriber adds events to the queue
+  # they will not be processed. If no event handler produces errors, the CLI should exit cleanly. If, however, any
+  # of the event handlers themselves produce errors, those errors will be handled, but the script will exit nonzero.
+  def run
+    debug "EventLoop: starting"
+    start = Time.now
+    loop do
+      event = @queue.pop(timeout: 0.05)
+      debug "EventLoop: got event #{event.class.name}\n                    #{event.inspect}"
+      if event
+        errors = @event_bus.notify(event)
+        debug "EventLoop: notified subscribers of #{event.class.name}, got #{errors.length} errors"
+
+        # future screen rendering here
+
+        handle_errors_from_notify(errors)
+
+        if event.drain_then_exit?
+          debug "EventLoop: exiting"
+          all_errors = []
+          @queue.size.times do
+            event = @queue.pop(timeout: 0.05)
+            if event
+              debug "EventLoop (exiting): got event #{event.class.name}\n                    #{event.inspect}"
+              errors = @event_bus.notify(event)
+              all_errors = all_errors + errors
+              # future screen rendering here
+            end
+          end
+          handle_errors_from_notify(all_errors, immediate: true)
+          break
+        elsif event.exit?
+          debug "EventLoop: exiting"
+          break
+        end
+      end
+      if @tick
+        errors = @event_bus.notify(Brut::TUI::Events::Tick.new(Time.now - start))
+        handle_errors_from_notify(errors)
+      end
+    end
+  end
+
+private
+
+  def handle_errors_from_notify(errors, immediate: false)
+    exit_now = immediate || errors.any? { |it| it.kind_of?(Brut::TUI::Events::Exception) && it.exit? }
+    if exit_now
+      errors.each do
+        $stderr.puts("FATAL Exception: #{it.exception.class}: #{it.exception.message}\n    #{it.exception.backtrace.join("\n    ")}")
+      end
+      exit 1
+    else
+      errors.each { @queue.unshift(Brut::TUI::Events::Exception.new(it)) }
+    end
+  end
+
+  def debug(*) = nil#$stderr.puts(*)
+
+  # @!visibility private
+  class Deque
+    def initialize
+      @mutex              = Thread::Mutex.new
+      @condition_variable = Thread::ConditionVariable.new
+      @array              = []
+    end
+
+    def <<(val)
+      @mutex.synchronize {
+        @array << val
+        @condition_variable.signal
+      }
+    end
+
+    def unshift(val)
+      @mutex.synchronize {
+        @array.unshift(val)
+        @condition_variable.signal
+      }
+    end
+
+    def pop(timeout:)
+      @mutex.synchronize {
+        deadline = Time.now + timeout
+        while @array.empty?
+          remaining = deadline - Time.now
+          if remaining <= 0
+            return nil 
+          end
+          @condition_variable.wait(@mutex, remaining)
+        end
+        @array.shift
+      }
+    end
+
+    def empty?
+      @mutex.synchronize { @array.empty? }
+    end
+
+    def size
+      @mutex.synchronize { @array.size }
+    end
+  end
+
+end

data/lib/brut/tui/events/base_event.rb

@@ -0,0 +1,29 @@
+require "brut/junk_drawer"
+
+# Base class for all events the TUI will manage.  You can create custom
+# events but they must subclass this one (or conform to its interface, which may change).
+class Brut::TUI::Events::BaseEvent
+  # Returns the method name that subscribers must implement to handle this event.
+  # By default, this is based on the underscorized simple class name (name without module namespacing)
+  # suffixed with `on_`.
+  def self.handler_method_name 
+    @handler_method_name ||= begin
+                               simple_class_name = RichString.new(self.name.split("::").last)
+                               "on_#{simple_class_name.underscorized}"
+                             end
+  end
+
+  # Provides `class_name` and `handler_method_name`. Subclasses are expected to call this
+  # so they are included with their keys.
+  def deconstruct_keys(keys=nil)
+    { class_name: self.class.name, handler_method_name: self.class.handler_method_name }
+  end
+
+  # True if the reception of this event indicates the app should exit right now, potentially
+  # leaving un-handled events.
+  def exit? = false
+
+  # True if this event indicates the TUI should exit, but draining any
+  # outstanding events is OK first.
+  def drain_then_exit? = false
+end

data/lib/brut/tui/events/event_bus.rb

@@ -0,0 +1,73 @@
+# @!visibility private
+class Brut::TUI::Events::EventBus
+  def initialize
+    @subscribers = {}
+  end
+
+  # Notify all subscribers of the given event.
+  def notify(event)
+    handler_method_name = event.class.handler_method_name
+
+    errors = []
+
+    subscribers(event.class).each do |subscriber|
+      begin
+        subscriber.send(handler_method_name, event)
+      rescue => ex
+        errors << ex
+      end
+    end
+
+    subscribers(:all).each do |subscriber|
+      begin
+        if subscriber.respond_to?(handler_method_name)
+          params = subscriber.method(handler_method_name).parameters
+          if params.size == 0 || (params.size == 1 && params[0][0] == :rest)
+            subscriber.send(handler_method_name)
+          elsif params.size == 1 && params[0][0] == :req
+            subscriber.send(handler_method_name, event)
+          elsif params.all? { |it| it[0] == :keyreq || it[0] == :key }
+            param_keys = params.map { |it| it[1] }
+            args = event.deconstruct_keys.slice(*param_keys)
+            subscriber.send(handler_method_name, **args)
+          else
+            raise "#{subscriber.class}##{handler_method_name} has unsupported parameters. It must take either zero parameters, one required parameter (the event), or keyword parameters matching the event's attributes. Method's parameters: #{params.inspect}"
+          end
+        elsif subscriber.respond_to?(:on_any_event)
+          params = subscriber.method(:on_any_event).parameters
+          if params.size == 1 && (params[0][0] == :req || params[0][0] == :rest)
+            subscriber.on_any_event(event)
+          else
+            raise "#{subscriber.class}#on_any_event has unsupported parameters. It must take one required parameter (the event). Method's parameters: #{params.inspect}"
+          end
+        end
+      rescue => ex
+        errors << ex
+      end
+    end
+    errors
+  end
+
+  # Subscribe to all events the subscriber can handle. If the subscriber implements
+  # the event's handler_method_name method, it will be called when the event is fired.
+  # If the subscriber implements on_any_event, that method will be called for every event.
+  def subscribe_to_all(subscriber)
+    subscribers(:all) << subscriber
+  end
+
+  # Subscribe to a specific event class. The subscriber must implement the event's
+  # handler_method_name method.
+  def subscribe(event_class, subscriber)
+    if subscriber.respond_to?(event_class.handler_method_name)
+      subscribers(event_class) << subscriber
+    else
+      raise ArgumentError, "Subscriber #{subscriber} does not implement handler method #{event_class.handler_method_name} for event #{event_class}"
+    end
+  end
+
+private
+
+  def subscribers(event_class_or_all)
+    @subscribers[event_class_or_all] ||= []
+  end
+end

data/lib/brut/tui/events/event_loop_started.rb

@@ -0,0 +1,5 @@
+# Indicates that the loop has started. In general, this is the first event
+# that will be fired for any TUI.
+class Brut::TUI::Events::EventLoopStarted < Brut::TUI::Events::BaseEvent
+  def to_s = "EventLoopStarted"
+end

data/lib/brut/tui/events/exception.rb

@@ -0,0 +1,24 @@
+# Fired when an exception is caught. In general, your code should endeavor
+# to catch exceptions, wrap them in this, and fir it.
+#
+# You can control if the app should exit by setting `fatal: true` when
+# creating the event. Note that by default, all exceptions are treated
+# as fatal, since you generally don't want to use them for control flow.
+class Brut::TUI::Events::Exception < Brut::TUI::Events::BaseEvent
+  attr_reader :exception
+  def initialize(exception)
+    @exception = exception
+  end
+
+  # Returns true if this event is not considered fatal.
+  def drain_then_exit? = !exit?
+
+  # By default, all exceptions should cause an immediate exit.  You may subclass this event to do
+  # something different, noting that `#drain_then_exit?` returns true if this returns false.
+  def exit?            =  true
+
+  # Includes `exception`, which is the exception that triggered this event.
+  def deconstruct_keys(keys=nil)
+    super.merge({ exception: @exception})
+  end
+end

data/lib/brut/tui/events/tick.rb

@@ -0,0 +1,12 @@
+# An event that indicates time has passed.
+class Brut::TUI::Events::Tick < Brut::TUI::Events::BaseEvent
+  def initialize(elapsed_time)
+    @elapsed_time = elapsed_time
+  end
+
+  # Includes `elapsed_time`, which is the number of seconds since the
+  # event loop started.
+  def deconstruct_keys(keys=nil)
+    super.merge({ elapsed_time: @elapsed_time })
+  end
+end

data/lib/brut/tui/events.rb

@@ -0,0 +1,7 @@
+class Brut::TUI::Events
+  autoload(:BaseEvent, "brut/tui/events/base_event")
+  autoload(:EventLoopStarted, "brut/tui/events/event_loop_started")
+  autoload(:Exception, "brut/tui/events/exception")
+  autoload(:EventBus, "brut/tui/events/event_bus")
+  autoload(:Tick, "brut/tui/events/tick")
+end

data/lib/brut/tui/markup_string.rb

@@ -0,0 +1,70 @@
+# A string that responds to limited markup that can be used to apply styles to the string
+class Brut::TUI::MarkupString
+  # Create a MarkupString from a normal string.
+  #
+  # @param string [String|Brut::TUI::MarkupString] string to convert.
+  # @return [Brut::TUI::MarkupString] if `string` is a `Brut::TUI::MarkupString` already, returns that, otherwise, wraps
+  #         `string` in a `Brut::TUI::MarkupString`.
+  def self.from_string(string)
+    string.kind_of?(Brut::TUI::MarkupString) ? string : self.new(string.to_s)
+  end
+
+  def initialize(string)
+    @string = string
+  end
+
+  DELIMITERS = {
+    "*" => :bold,
+    "_" => :weak,
+    "`" => :code,
+    "~" => :strike,
+  }.freeze
+
+  def to_s = @string
+
+  # Parse the string for known markup, yielding at key parsing events.
+  #
+  # @yield [directive, value] called for each parsing event, where value depends on directive.  The block
+  #        will be called for all parts of the string.
+  # @yieldparam directive [Symbol] one of `:start`, `:stop`, or `:text`. `:text` is for any text and doesn't include
+  #             the markup characters. `:start` and `:stop` are called when a markup start or stop is found.
+  # @yieldparam value [String|Symbol] For the `:text` `directive`, this is the text fragment from the string, so
+  #             for the string `"*foo*"`, `:text` would be called with `"foo"`.  For `:start` or `:stop`, the value
+  #             is the type of markup encountered, one of `:bold`, `:weak`, `:code`, or `:strike`.
+  def parse(&block)
+    in_delimiter = DELIMITERS.keys.map { [ it, false ] }.to_h
+
+    previous_character          = nil
+    previous_previous_character = nil
+
+    @string.each_char do |char|
+      if DELIMITERS.key?(char) && previous_character != "\\" && previous_previous_character != "\\"
+        style = DELIMITERS[char]
+        if in_delimiter[char]
+          block.(:stop, style)
+          in_delimiter[char] = false
+        else
+          inside_code = in_delimiter["`"]
+          if inside_code
+            block.(:text, char)
+          else
+            block.(:start, style)
+            in_delimiter[char] = true
+          end
+        end
+      else
+        if char == "\\"
+          if previous_character == "\\"
+            block.(:text, char)
+          else
+            # eat it - it is escaping something maybe
+          end
+        else
+          block.(:text, char)
+        end
+      end
+      previous_previous_character = previous_character
+      previous_character          = char
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# A step whose behavior is a given block of code.
+# Fires {Brut::TUI::Script::Events::StepStarted} before
+# the code executes and {Brut::TUI::Script::Events::StepCompleted}
+# *only* if the block completes without an exception being thrown.
+class Brut::TUI::Script::BlockStep < Brut::TUI::Script::Step
+  def initialize(event_loop, description, &block)
+    super(event_loop, description)
+    @block = block
+  end
+
+  def run!
+    event_loop << Events::StepStarted.new(step: self)
+    @block.().tap {
+      event_loop << Events::StepCompleted.new(step: self)
+    }
+  end
+end

data/lib/brut/tui/script/events/command_execution_failed.rb

@@ -0,0 +1,4 @@
+# Fired when a subcommand exited nonzero
+class Brut::TUI::Script::Events::CommandExecutionFailed < Brut::TUI::Script::Events::ExecutingCommand
+  def exit? = true
+end

data/lib/brut/tui/script/events/command_execution_succeeded.rb

@@ -0,0 +1,3 @@
+# Fired when a subcommand exited zero (i.e. was successful)
+class Brut::TUI::Script::Events::CommandExecutionSucceeded < Brut::TUI::Script::Events::ExecutingCommand
+end

data/lib/brut/tui/script/events/command_std_err.rb

@@ -0,0 +1,3 @@
+# Fired when a command has provided at least some output on its standard error.
+class Brut::TUI::Script::Events::CommandStdErr < Brut::TUI::Script::Events::CommandStdOut
+end

data/lib/brut/tui/script/events/command_std_out.rb

@@ -0,0 +1,14 @@
+# Fired when a command has provided at least some output on its standard output.
+class Brut::TUI::Script::Events::CommandStdOut < Brut::TUI::Events::BaseEvent
+  def initialize(step:, output:, show: false)
+    @step   = step
+    @output = output
+    @show   = show
+  end
+
+  # Adds `description`, `command` and `output` to the event keywords. `output` is a string
+  # containing whatever output was available. This is likely not terminated with a newline.
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @step.description, command: @step.command, output: @output, show: @show })
+  end
+end

data/lib/brut/tui/script/events/executing_command.rb

@@ -0,0 +1,12 @@
+# Fired when a command is executed (this also serves as a base class for the results
+# of such execution).
+class Brut::TUI::Script::Events::ExecutingCommand < Brut::TUI::Events::BaseEvent
+  def initialize(step:)
+    @step = step
+  end
+
+  # Includes `description` and `command` in the keyword arguments
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @step.description, command: @step.command })
+  end
+end

data/lib/brut/tui/script/events/message.rb

@@ -0,0 +1,15 @@
+# Fired when a step produces a message
+class Brut::TUI::Script::Events::Message < Brut::TUI::Events::BaseEvent
+  def initialize(message:, type:)
+    @message = message
+    @type    = type
+  end
+
+  def to_s = @message
+
+  # Includes `message` and `type`. `type` will be `:notify`, `:warning`, `:success`,
+  # `:error`, or `:done`, however it could be anything else the script may choose to use.
+  def deconstruct_keys(keys=nil)
+    super.merge({ message: @message, type: @type })
+  end
+end

data/lib/brut/tui/script/events/phase_completed.rb

@@ -0,0 +1,4 @@
+# Fired when a phase completes
+class Brut::TUI::Script::Events::PhaseCompleted < Brut::TUI::Script::Events::PhaseStarted
+  def to_s = "#{@name} completed"
+end

data/lib/brut/tui/script/events/phase_started.rb

@@ -0,0 +1,14 @@
+# Fired when a phase starts, but before any steps have executed
+class Brut::TUI::Script::Events::PhaseStarted < Brut::TUI::Events::BaseEvent
+  def initialize(description, step_number:, total_steps:)
+    @description = description
+    @step_number = step_number
+    @total_steps = total_steps
+  end
+
+  # Adds `description`, `step_number` (1-based), and `total_steps` to the keyword arguments.
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @description, step_number: @step_number, total_steps: @total_steps })
+  end
+  def to_s = @description
+end

data/lib/brut/tui/script/events/script_completed.rb

@@ -0,0 +1,5 @@
+# Fired when the script has completed
+class Brut::TUI::Script::Events::ScriptCompleted < Brut::TUI::Events::BaseEvent
+  def drain_then_exit? = true
+  def to_s = "Done"
+end

data/lib/brut/tui/script/events/script_started.rb

@@ -0,0 +1,12 @@
+# Fired when the script is just starting
+class Brut::TUI::Script::Events::ScriptStarted < Brut::TUI::Events::BaseEvent
+  def initialize(phases:)
+    @phases = phases
+  end
+  # Adds `phases` as an array of `[description,Proc]` representing the phases.
+  # You are discouraged from interacting with the `Proc` objects.
+  def deconstruct_keys(keys=nil)
+    super.merge({ phases: @phases })
+  end 
+  def to_s = "Starting"
+end

data/lib/brut/tui/script/events/step_completed.rb

@@ -0,0 +1,3 @@
+# Fired when a step completes.
+class Brut::TUI::Script::Events::StepCompleted < Brut::TUI::Script::Events::StepStarted
+end

data/lib/brut/tui/script/events/step_started.rb

@@ -0,0 +1,12 @@
+# Fired when a step is about to execute
+class Brut::TUI::Script::Events::StepStarted < Brut::TUI::Events::BaseEvent
+  def initialize(step:)
+    @step = step
+  end
+
+  # Adds `description` to the keyword arguments
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @step.description })
+  end
+  def to_s = @description
+end

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

@@ -0,0 +1,14 @@
+module Brut::TUI::Script::Events
+  autoload :ScriptStarted  , "brut/tui/script/events/script_started"
+  autoload :ScriptCompleted , "brut/tui/script/events/script_completed"
+  autoload :PhaseStarted   , "brut/tui/script/events/phase_started"
+  autoload :PhaseCompleted , "brut/tui/script/events/phase_completed"
+  autoload :StepStarted   , "brut/tui/script/events/step_started"
+  autoload :StepCompleted , "brut/tui/script/events/step_completed"
+  autoload :ExecutingCommand , "brut/tui/script/events/executing_command"
+  autoload :CommandStdOut, "brut/tui/script/events/command_std_out"
+  autoload :CommandStdErr, "brut/tui/script/events/command_std_err"
+  autoload :CommandExecutionSucceeded , "brut/tui/script/events/command_execution_succeeded"
+  autoload :CommandExecutionFailed , "brut/tui/script/events/command_execution_failed"
+  autoload :Message , "brut/tui/script/events/message"
+end