brut 0.16.0 → 0.17.0

data/lib/brut/tui/script.rb

@@ -0,0 +1,211 @@
+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: "bin/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.
+  # @yield if `exec` is `nil`, this block will be executed for the step
+  def step(description, exec: nil, &block)
+    step = if exec.nil?
+             BlockStep.new(@event_loop, description, &block)
+           else
+             ExecStep.new(@event_loop, description, command: exec)
+           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

data/lib/brut/tui/terminal_theme.rb

@@ -0,0 +1,140 @@
+# A terminal theme is a set of semantic styles for the terminal that
+# map to actual colors or styles based on the terminal's metadata or
+# the user's preferences or both.
+#
+# This class is coupled to the behavior of ANSI escape
+# codes in the terminal, in that they aren't markup, but more
+# like drawing with a pen.
+
+# That said, this class' API does abstract from the codes
+# themselves and creates a semantic layer, for example
+# the definition of "succes" or "weak".
+
+# For subclass implementors, there are various private
+# methods that do encapsulate the ANSI escape codes, and these
+# can be used or overridden.
+#
+# This particular implementation avoids the use of black or white, and uses
+# the normal ANSI colors.  This should, in theory, work with any terminal
+# theme where all colors are legible on the chosen background.
+class Brut::TUI::TerminalTheme
+
+  def self.based_on_background(terminal)
+    if dark_background?(terminal)
+      Brut::TUI::Themes::Dark.new(terminal)
+    else
+      Brut::TUI::Themes::Light.new(terminal)
+    end
+  end
+
+  def self.dark_background?(terminal)
+    r, g, b = terminal.background_color.map { it / 255.0 }
+    luminance = (0.21 * r) + (0.72 * g) + (0.07 * b)
+
+    return luminance < 0.5  
+  end
+
+  def initialize(terminal)
+    @terminal = terminal
+  end
+
+  # Returns a string with its markup turned into escape codes.
+  # Note that due to the way ANSI escape codes work, the state
+  # of the terminal may not be in the same state you found it.
+  #
+  # This method tries to turn features on and off (e.g. after a bold
+  # string, the codes to turn off bold are applied), but if a subclass
+  # mixes colors and styles, any text output after this one may
+  # not look like the text before it.
+  def with_markup(string, text: :normal, reset: true)
+    result = +""
+    result << send(text)
+    Brut::TUI::MarkupString.from_string(string).parse do |directive, value|
+      case directive
+      in :start
+        case value
+        in :bold
+          result << bold
+        in :strike
+          result << strike
+        in :code
+          result << code
+        in :weak
+          result << weak
+        end
+      in :stop
+        case value
+        in :bold
+          result << bold_off << send(text)
+        in :strike
+          result << strike_off << send(text)
+        in :code
+          result << code_off << send(text)
+        in :weak
+          result << weak_off << send(text)
+        end
+      in :text
+        result << value
+      end
+    end
+    if reset
+      result << self.reset
+    end
+    result
+  end
+
+  def success = bold + bright_green
+  def error   = bold + bright_red
+  def warning = bold + yellow
+
+  def bold     = esc("1")
+  def bold_off = normal
+
+  def bright     = esc("1")
+  def bright_off = normal
+
+  def italic     = esc("3")
+  def italic_off = esc("23")
+
+  def strike     = esc("9")
+  def strike_off = esc("29")
+
+  def weak     = esc("2")
+  def weak_off = normal
+
+  def code     = underline
+  def code_off = underline_off
+
+  def normal = esc("22")
+
+  def reset = esc("0")
+
+  def heading = bold + underline + bright_blue
+
+private
+
+  def underline     = esc("4")
+  def underline_off = esc("24")
+
+  def black   = esc("30")
+  def red     = esc("31")
+  def green   = esc("32")
+  def yellow  = esc("33")
+  def blue    = esc("34")
+  def magenta = esc("35")
+  def cyan    = esc("36")
+  def white   = esc("37")
+
+  def bright_black   = esc("90")
+  def bright_red     = esc("91")
+  def bright_green   = esc("92")
+  def bright_yellow  = esc("93")
+  def bright_blue    = esc("94")
+  def bright_magenta = esc("95")
+  def bright_cyan    = esc("96")
+  def bright_white   = esc("97")
+
+  def esc(code)
+    "\e[#{code}m"
+  end
+end

data/lib/brut/tui/themes/dark.rb

@@ -0,0 +1,14 @@
+# A theme designed to work on a dark background terminal.
+class Brut::TUI::Themes::Dark < Brut::TUI::TerminalTheme
+  def black         = esc("38;2;96;96;96")
+  def bright_black  = esc("38;2;128;128;128")
+  def white         = esc("38;2;233;233;233")
+  def bright_white  = esc("38;2;255;255;255")
+  def yellow        = esc("38;2;191;191;0")
+  def bright_yellow = esc("38;2;255;255;0")
+  def normal        = super + white
+  def code          = esc("38;2;0;255;0")
+  def code_off      = normal
+  def bright        = bright_white
+  def bright_off    = normal
+end

data/lib/brut/tui/themes/light.rb

@@ -0,0 +1,17 @@
+# A theme designed to work on a white background terminal.
+class Brut::TUI::Themes::Light < Brut::TUI::TerminalTheme
+  def black         = esc("38;2;0;0;0")
+  def bright_black  = esc("38;2;64;64;64")
+  def bright_white  = esc("38;2;128;128;128")
+  def white         = esc("38;2;191;191;191")
+  def yellow        = esc("38;2;191;191;0")
+  def bright_yellow = esc("38;2;255;255;0")
+  def normal        = super + black
+  def code          = esc("38;2;0;128;0")
+  def code_off      = normal
+  def green         = esc("38;2;25;105;0")
+  def bright_green  = esc("38;2;34;155;0")
+  def bright        = bright_blue
+  def bright_off    = normal
+end
+

data/lib/brut/tui/themes/none.rb

@@ -0,0 +1,9 @@
+# A theme without any ANSI styling at all.  This is suitable
+# for showing to a user who does not want any colors or styles, but
+# still wants to see output in a somewhat conventional way.
+class Brut::TUI::Themes::None < Brut::TUI::TerminalTheme
+  def esc(*) = ""
+end
+
+
+

data/lib/brut/tui/themes.rb

@@ -0,0 +1,5 @@
+module Brut::TUI::Themes
+  autoload(:Light , "brut/tui/themes/light")
+  autoload(:Dark  , "brut/tui/themes/dark")
+  autoload(:None  , "brut/tui/themes/none")
+end

data/lib/brut/tui.rb

@@ -0,0 +1,15 @@
+module Brut
+  # Brut provides a basic API for creating rich text user interfaces. Currently, Brut
+  # provides {Brut::TUI::Script} to create more user-friendly scripts like `bin/setup` or
+  # `bin/ci`.
+  module TUI
+    autoload(:EventLoop, "brut/tui/event_loop")
+    autoload(:Events, "brut/tui/events")
+    autoload(:AnsiEscapeCode, "brut/tui/ansi_escape_code")
+    autoload(:Script, "brut/tui/script")
+    autoload(:Terminal, "brut/tui/terminal")
+    autoload(:TerminalTheme, "brut/tui/terminal_theme")
+    autoload(:Themes, "brut/tui/themes")
+    autoload(:MarkupString, "brut/tui/markup_string")
+  end
+end

data/lib/brut/version.rb

@@ -1,4 +1,4 @@
 module Brut
   # @!visibility private
-  VERSION = "0.16.0"
+  VERSION = "0.17.0"
 end

data/lib/brut.rb

@@ -16,5 +16,6 @@ module Brut
   autoload(:Instrumentation,"brut/instrumentation")
   autoload(:SinatraHelpers, "brut/sinatra_helpers")
   # DO NOT autoload(:CLI) - that is intended to be require-able on its own
+  # DO NOT autoload(:TUI) - that is intended to be require-able on its own
 end
 require "sequel/plugins"

data/mkbrut/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mkbrut (0.16.0)
+    mkbrut (0.17.0)
 
 GEM
   remote: https://rubygems.org/

data/mkbrut/lib/mkbrut/version.rb

@@ -1,3 +1,3 @@
 module MKBrut
-  VERSION = "0.16.0"
+  VERSION = "0.17.0"
 end

data/specs/brut/tui/ansi_escape_code.spec.rb

@@ -0,0 +1,30 @@
+require "spec_helper"
+require "brut/tui"
+
+RSpec.describe Brut::TUI::AnsiEscapeCode do
+  describe "#to_s" do
+    it "returns the ANSI escape code as a string" do
+      code = Brut::TUI::AnsiEscapeCode.new(:red, "31")
+      expect(code.to_s).to eq("\e[31m")
+    end
+  end
+
+  describe ".ansi" do
+    it "returns the correct ANSI escape code for a given name" do
+      red_code = Brut::TUI::AnsiEscapeCode.ansi(:red)
+      expect(red_code.to_s).to eq("\e[31m")
+    end
+
+    it "returns an RGB ANSI escape code when given RGB values" do
+      rgb_code = Brut::TUI::AnsiEscapeCode.ansi(255, 0, 0)
+      expect(rgb_code.to_s).to eq("\e[38;2;255;0;0m")
+    end
+
+    it "returns a fluent objects when called without arguments" do
+      fluent = Brut::TUI::AnsiEscapeCode.ansi
+      expect(fluent.bold.to_s).to eq("\e[1m")
+      expect(fluent.red.to_s).to eq("\e[31m")
+    end
+
+  end
+end

data/specs/brut/tui/event_loop.spec.rb

@@ -0,0 +1,70 @@
+require "spec_helper"
+require "brut/tui"
+
+RSpec.describe Brut::TUI::EventLoop do
+  subject(:event_loop) { described_class.new(tick: false) }
+
+  class ExitEvent < Brut::TUI::Events::BaseEvent
+    def exit? = true
+  end
+
+  class RaiseExceptionEvent < Brut::TUI::Events::BaseEvent
+    def initialize(message)
+      @message = message
+    end
+    def raise_exception!
+      raise StandardError.new(@message)
+    end
+  end
+
+  class GeneralSubscriber
+    attr_reader :events
+    def initialize
+      @events = []
+    end
+    def on_any_event(event)
+      if event.respond_to?(:raise_exception!)
+        event.raise_exception!
+      else
+        @events << event
+      end
+    end
+  end
+
+  it "stops the loop when an event returns true for exit?" do
+    main_thread = Thread.new {
+      event_loop.run
+    }
+    event_loop << ExitEvent.new
+    main_thread.join(0.1)
+    expect(main_thread.alive?).to eq(false)
+  end
+
+  def start_loop(event_loop, wait_time: 0.1)
+    exception = nil
+    main_thread = Thread.new {
+      begin
+      event_loop.run
+      rescue => ex
+        exception = ex
+      end
+    }
+    main_thread.join(wait_time)
+    expect(exception).to eq(nil)
+  end
+
+  it "fires the event LoopStarted event when run" do
+    general_subscriber = GeneralSubscriber.new
+    event_loop.subscribe_to_all(general_subscriber)
+    start_loop(event_loop)
+    expect(general_subscriber.events[0].class).to eq(Brut::TUI::Events::EventLoopStarted)
+  end
+
+  it "fires exception events when errors are raised" do
+    general_subscriber = GeneralSubscriber.new
+    event_loop.subscribe_to_all(general_subscriber)
+    event_loop << RaiseExceptionEvent.new("Test exception")
+    start_loop(event_loop)
+    expect(general_subscriber.events[1].class).to eq(Brut::TUI::Events::Exception)
+  end
+end

data/specs/brut/tui/events/base_event.spec.rb

@@ -0,0 +1,26 @@
+require "spec_helper"
+require "brut/tui"
+
+RSpec.describe Brut::TUI::Events::BaseEvent do
+  class TestEvent < Brut::TUI::Events::BaseEvent; end
+  module Deeply
+    module Nested
+      class TestEvent < Brut::TUI::Events::BaseEvent; end
+    end
+  end
+
+  describe ".handler_method_name" do
+    it "returns the underscorized simple class name prefixed with 'on_'" do
+
+      expect(TestEvent.handler_method_name).to eq("on_test_event")
+      expect(Deeply::Nested::TestEvent.handler_method_name).to eq("on_test_event")
+    end
+  end
+
+  describe "#exit?" do
+    it "returns false by default" do
+      event = Brut::TUI::Events::BaseEvent.new
+      expect(event.exit?).to be false
+    end
+  end
+end