brut 0.16.0 → 0.18.0

data/lib/brut/cli/parsed_command_line.rb

@@ -0,0 +1,143 @@
+require "optparse"
+require "brut/framework/project_environment"
+
+# Parses the command line and makes everything parsed available as attributes.
+class Brut::CLI::ParsedCommandLine
+
+  # The command that should be executed based on what was parsed from the command line
+  #
+  # @return [Brut::CLI::Commands::BaseCommand]
+  attr_reader :command
+
+  # The remaining unparsed command line arguments.
+  #
+  # @return [Array<String>]
+  attr_reader :argv
+
+  # The parsed command line switches and flags.
+  #
+  # @return [Brut::CLI::Options]
+  attr_reader :options
+
+  # The project enviornment, if specified
+  # @return [Brut::Framework::ProjectEnvironment]
+  attr_reader :project_environment
+
+  # Create the ParsedCommandLine based on a base command (which provides the initial set of 
+  # command line options), the ARGV and the ENV when the command was invoked.
+  #
+  # This should always succeed, however depending on the contents of the parameters, the value
+  # for `#command` may be a command that outputs an error.
+  def initialize(app_command:, argv:, env:)
+    brut_provided_help_requested = false
+    app_option_parser = new_option_parser do |opts|
+      opts.banner = app_command.description
+      app_command.accepts.each_with_index { |class_or_class_and_proc,index| accept(opts,class_or_class_and_proc,index) }
+      app_command.opts.each do |option|
+        opts.on(*option)
+      end
+      opts.on("--help", "-h", "Show help") do
+        brut_provided_help_requested = true
+      end
+    end
+
+    options = {
+      'log-level': "error",
+    }
+    remaining_argv = app_option_parser.order!(argv,into: options)
+
+    if remaining_argv[0] == "help"
+      brut_provided_help_requested = true
+      remaining_argv.shift
+    end
+
+    help_command = if brut_provided_help_requested
+                     Brut::CLI::Commands::Help.new(app_command,app_option_parser)
+                   end
+
+    command = app_command
+    loop do
+      arg = remaining_argv.shift
+      command_found = command.commands.detect { it.name == arg }
+      if command_found
+        command_found.parent_command = command
+        command = command_found
+      else
+        if arg
+          remaining_argv.unshift(arg)
+        end
+        break
+      end
+    end
+
+
+    if command != app_command
+      command_option_parser = new_option_parser do |opts|
+        opts.banner = command.description
+        app_command.accepts.each_with_index { |class_or_class_and_proc,index| accept(opts,class_or_class_and_proc,index) }
+        command.accepts.each_with_index { |class_or_class_and_proc,index| accept(opts,class_or_class_and_proc,index) }
+        opts.on("--help", "-h", "Show help") do
+          brut_provided_help_requested = true
+        end
+        app_command.opts.each { opts.on(*it) }
+        command.opts.each { opts.on(*it) }
+      end
+      remaining_argv = command_option_parser.parse!(remaining_argv, into: options)
+      if brut_provided_help_requested
+        help_command = Brut::CLI::Commands::Help.new(command,command_option_parser)
+      elsif help_command
+        help_command.option_parser = command_option_parser
+      end
+    end
+
+    if help_command
+      command = help_command
+    else
+      if remaining_argv.empty? && command.default_command
+        command = command.default_command
+      end
+    end
+
+    if options[:env]
+      @project_environment = options.delete(:env)
+    end
+
+    @command = command
+    @argv    = remaining_argv
+    @options = Brut::CLI::Options.new(options)
+  rescue => ex
+    @command = if env["BRUT_DEBUG"] == "true"
+      Brut::CLI::Commands::RaiseError.new(ex)
+    else
+      Brut::CLI::Commands::OutputError.new(ex)
+    end
+    @argv = argv
+    @options = Brut::CLI::Options.new({})
+  end
+
+private
+
+  def new_option_parser(&block)
+    OptionParser.new do |opts|
+      opts.accept(Brut::Framework::ProjectEnvironment) do |value|
+        Brut::Framework::ProjectEnvironment.new(value)
+      end
+      opts.on("--env=ENVIRONMENT", Brut::Framework::ProjectEnvironment,
+              "Project environment, e.g. test, development, production. Default depends on the command")
+      opts.on("--log-level=LOG_LEVEL", [ "debug", "info", "warn", "error", "fatal" ],
+              "Log level, which should be debug, info, warn, error, or fatal. Defaults to error")
+      block.(opts)
+    end
+  end
+
+  def accept(opts,class_or_class_and_proc,index)
+    klass,conversion_proc = if class_or_class_and_proc.kind_of?(Class)
+                              [ class_or_class_and_proc, ->(arg) { class_or_class_and_proc.new(arg) } ]
+                            elsif class_or_class_and_proc.kind_of?(Array) && class_or_class_and_proc.size == 2
+                              class_or_class_and_proc
+                            else
+                              raise "def accepts must return an array whose elements are either a class or a 2-element array of a class and a conversion proc.  Index #{index} had a #{class_or_class_and_proc.class}"
+                            end
+    opts.accept(klass,&conversion_proc)
+  end
+end

data/lib/brut/cli/runner.rb

@@ -0,0 +1,124 @@
+# Runs a CLI app/command.  Handles all the logic of parsing command line arguments, locating
+# the command object to process the execution, allow for help requests, and understanding the output.
+class Brut::CLI::Runner
+
+  # Create the runner, which can be used to run `app_command` with whatever command line was provided.
+  #
+  # @param [Brut::CLI::Commands::BaseCommand] app_command The app that is being executed, in which all command line arguments
+  #        should be interpreted.
+  # @param [IO] stdout the standard output, which will receive all output that isn't related to error messages.
+  # @param [IO] stderr the standard error, which will receive error messages
+  # @param [IO] stdin the standard input
+  # @param [Pathname] project_root root of the Brut project (i.e. where `Gemfile`, `app` et. al. are located)
+  def initialize(app_command, stdout:, stderr:,stdin:, project_root:)
+    prefix = if $0 =~ /\/brut$/
+               "brut"
+             else
+               $0
+             end
+    @app_command  = app_command
+    @stdout       = Brut::CLI::Output.new(io: stdout, prefix: "[ #{prefix} ] ")
+    @stderr       = Brut::CLI::Output.new(io: stderr, prefix: "[ #{prefix} ] ")
+    @stdin        = stdin
+    @project_root = project_root
+  end
+
+  # Run the commmand or subcommand based on the `app_command` given to the constructor and the command line
+  # provided in `argv`.
+  #
+  # @param [Array] argv The arguments provided to the command. Outside of tests, this is almost certainly `ARGV`.
+  # @param [ENV|Hash] env The UNIX environment available when the command was executed.  This should be treated
+  #        as if it's `ENV`, even though it may just be a hash.
+  # @return [Integer] the exit code to pass back to the shell that invoked the command, with 0 meaning the 
+  #         command succeeded and any other value meaning failure.  Generally, this value should be between 0 and 255.
+  def run!(argv, env)
+
+    parsed_command_line = Brut::CLI::ParsedCommandLine.new(app_command: @app_command, argv:, env:)
+
+    load_unix_environment!(env, parsed_command_line)
+    setup_log_level(env, parsed_command_line)
+    bootstrap!(env, parsed_command_line)
+
+    execute_result = Brut::CLI::ExecuteResult.new do
+      execution_context = Brut::CLI::Commands::ExecutionContext.new(
+        argv: parsed_command_line.argv,
+        options: Brut::CLI::Options.new(parsed_command_line.options),
+        env:,
+        stdout: @stdout,
+        stderr: @stderr,
+        stdin: @stdin
+      )
+      parsed_command_line.command.execute(execution_context)
+    end
+    execute_result.exit_status do |error_message|
+      @stderr.puts error_message
+    end
+  end
+
+private
+
+  def load_unix_environment!(env, parsed_command_line)
+    if env["RACK_ENV"]
+      if parsed_command_line.project_environment
+        @stderr.puts "RACK_ENV is set in the environment, which supercedes the command line, --env ignored"
+      end
+    else
+      env["RACK_ENV"] = if parsed_command_line.project_environment
+                          parsed_command_line.project_environment.to_s
+                        else
+                          parsed_command_line.command.default_rack_env
+                        end
+    end
+
+    rack_env = RichString.from_string(env["RACK_ENV"])
+
+    if !rack_env
+      return
+    end
+    require "bundler"
+    if rack_env == "production"
+      Bundler.require(:default)
+      return
+    end
+
+    Bundler.require(:default, rack_env.to_sym)
+
+    require "dotenv"
+
+    Dotenv.load(@project_root / ".env.#{rack_env}.local",
+                @project_root / ".env.#{rack_env}")
+
+    if env != ENV
+      # To prevent us from having to depend directly on ENV, we want everything
+      # to use env, however Dotenv doesn't allow this and just populates ENV,
+      # so we want to copy everything over.
+      ENV.each do |key, value|
+        # Do not allow Dotenv to ovrerwrite RACK_ENV, since that is what we used
+        # to load these files in the first place.
+        if key != "RACK_ENV"
+          env[key] = value
+        end
+      end
+    end
+  end
+
+  def setup_log_level(env, parsed_command_line)
+    if env["LOG_LEVEL"]
+      @stderr.puts "LOG_LEVEL is set in the environment, which supercedes the command line, --log-level ignored"
+    elsif parsed_command_line.options.log_level?
+      env["LOG_LEVEL"] = parsed_command_line.options.log_level
+    end
+  end
+
+  def bootstrap!(env, parsed_command_line)
+    if env["RACK_ENV"]
+      require "#{@project_root}/app/bootstrap"
+      bootstrap = Bootstrap.new
+      if parsed_command_line.command.bootstrap?
+        bootstrap.bootstrap!
+      else
+        bootstrap.configure_only!
+      end
+    end
+  end
+end

data/lib/brut/cli.rb

@@ -6,39 +6,17 @@ module Brut
   # that your CLI will respond to. See {Brut::CLI::app}.
   module CLI
 
-    # Execute your CLI based on its command line invocation.  You would call this method inside the
-    # executable file placed in `bin/` in your project. 
-    # For example, if you have `YourApp::CLI::CleanOldFiles` and you wish to execute
-    # it via `bin/clean-files`, you'd create `bin/clean-files` like so:
-    #
-    # ```
-    # #!/usr/bin/env ruby
-    #
-    # require "bundler"
-    # Bundler.require
-    # require "pathname"
-    # require "brut/cli/apps/db"
-    # 
-    # exit Brut::CLI.app(YourApp::CLI::CleanOldFiles,
-    #                    project_root: Pathname($0).dirname / "..")
-    # ```
-    #
-    # @param app_klass [Class] your CLI app's class.
-    # @param project_root [Pathname] the path to the root of your project. This is needed before the Brut framework is initialized so
-    # it must be specified explicitly.
-    def self.app(app_klass, project_root:)
-      Brut::CLI::AppRunner.new(app_klass:,project_root:).run!
-    end
-    autoload(:App, "brut/cli/app")
-    autoload(:Command, "brut/cli/command")
+    autoload(:Commands, "brut/cli/commands")
     autoload(:Error, "brut/cli/error")
-    autoload(:SystemExecError, "brut/cli/error")
+    autoload(:ExecuteResult, "brut/cli/execute_result")
+    autoload(:Executor, "brut/cli/executor")
     autoload(:InvalidOption, "brut/cli/error")
-    autoload(:ExecutionResults, "brut/cli/execution_results")
     autoload(:Options, "brut/cli/options")
     autoload(:Output, "brut/cli/output")
-    autoload(:Executor, "brut/cli/executor")
-    autoload(:AppRunner, "brut/cli/app_runner")
+    autoload(:ParsedCommandLine, "brut/cli/parsed_command_line")
+    autoload(:Runner, "brut/cli/runner")
+    autoload(:SystemExecError, "brut/cli/error")
+
     # Holds Brut-provided CLI apps that are set up in your project.
     module Apps
       autoload(:DB,"brut/cli/apps/db")

data/lib/brut/framework/container.rb

@@ -1,4 +1,4 @@
-require "fileutils"
+autoload :FileUtils, "fileutils"
 
 module Brut
   # Provides access to the singelton container that contains all of Brut's current configuration.

data/lib/brut/framework/mcp.rb

@@ -1,24 +1,57 @@
-require_relative "container"
-require_relative "config"
-require_relative "../junk_drawer"
-require_relative "app"
+def time_it(label,&block)
+  start_time = Time.now
+  result = block.call
+  end_time = Time.now
+  duration = end_time - start_time
+  #printf "%30s - %.4f\n",label,duration
+  result
+end
+
+time_it "container" do
+  require_relative "container"
+end
+time_it "config" do
+  require_relative "config"
+end
+time_it "../junk_drawer" do
+  require_relative "../junk_drawer"
+end
+time_it "app" do
+  require_relative "app"
+end
 
-require "sequel"
+time_it "sequel" do
+  autoload :Sequel, "sequel"
+end
 
-require "semantic_logger"
-require_relative "patch_semantic_logger"
+time_it "semantic_logger" do
+  autoload :SemanticLogger, "semantic_logger"
+end
 
-require "i18n"
-require "zeitwerk"
-require "opentelemetry/sdk"
-require "opentelemetry/exporter/otlp"
+time_it "i18n" do
+  autoload :I18n, "i18n"
+end
+time_it "zeitwerk" do
+  require "zeitwerk"
+end
+time_it "opentelemetry/sdk" do
+  require "opentelemetry/sdk"
+end
+time_it "opentelemetry/exporter/otlp" do
+  require "opentelemetry/exporter/otlp"
+end
+time_it "concurrent-ruby" do
+  require "concurrent"
+end
 
 # The Master Control Program of Brut.  This handles all the bootstrapping and setup of your app. You are not
 # intended to use or interact with this class at all. End of line.
 class Brut::Framework::MCP
 
-  @otel_shutdown = Concurrent::AtomicBoolean.new(false)
-  def self.otel_shutdown = @otel_shutdown
+  @otel_shutdown = nil
+  def self.otel_shutdown 
+    @otel_shutdown ||= Concurrent::AtomicBoolean.new(false)
+  end
 
   # Create and configure the MCP.  The app will not work until {#boot!} has been called, however most of the core configuration
   # will be available via `Brut.container`.
@@ -64,6 +97,18 @@ class Brut::Framework::MCP
       "Prefix for all OTel attributes set by the app",
       otel_prefix
     )
+    Brut.container.store(
+      "app_id",
+      "String",
+      "Identifier for this app, useful in external contexts like deployment",
+      @app.id
+    )
+    Brut.container.store(
+      "app_organization",
+      "String",
+      "Organization identifier for this app, useful in external contexts like deployment",
+      @app.organization
+    )
   end
 
   # Starts up the internals of Brut and that app so that it can receive requests from
@@ -301,6 +346,7 @@ class Brut::Framework::MCP
 private
 
   def setup_logging
+    require_relative "patch_semantic_logger"
     SemanticLogger.default_level = Brut.container.log_level
     semantic_logger_appenders = Brut.container.semantic_logger_appenders
     if semantic_logger_appenders.kind_of?(Hash)

data/lib/brut/framework/project_environment.rb

@@ -11,8 +11,10 @@ class Brut::Framework::ProjectEnvironment
     when "development" then "development"
     when "test"        then "test"
     when "production"  then "production"
-    else
+    when String
       raise ArgumentError.new("'#{string_value}' is not a valid project environment")
+    else
+      raise ArgumentError.new("'#{string_value.class}' cannot be used as a project environment")
     end
   end
 

data/lib/brut/junk_drawer.rb

@@ -1,4 +1,5 @@
-require "tzinfo"
+autoload :TZInfo, "tzinfo"
+#require "tzinfo"
 # Models a clock, which is a time in the context of a time zone.  This theoretically makes it easier to get the time and date at the time zone of the user.
 class Clock
   attr_reader :timezone
@@ -142,6 +143,7 @@ class RichString
   def to_s = @string
   def to_str = self.to_s
   def length = to_s.length
+  def to_sym = to_s.to_sym
 
   def to_s_or_nil = @string.to_s.strip.empty? ? nil : self.to_s
 

data/lib/brut/spec_support/cli_command_support.rb

@@ -0,0 +1,45 @@
+require "stringio"
+require "brut/cli"
+require_relative "matchers/have_executed"
+
+# Convienience methods included in tests for CLI commands
+module Brut::SpecSupport::CLICommandSupport
+  # A subclass of {Brut::CLI::Executor} that remembers the commands it was asked to execute, instead of
+  # actually executing them.  This allows inspection later to see if expected commands had been run.
+  #
+  # This is used by the `have_executed` matcher.
+  class CapturingExecutor < Brut::CLI::Executor
+    attr_reader :commands_executed
+    def system!(*args)
+      @commands_executed ||= []
+      if args.length == 1
+        @commands_executed << args[0]
+      else
+        @commands_executed << args
+      end
+      nil
+    end
+  end
+  # Create an ExecutionContext suitable for any command, but which allows
+  # manipulating the data as needed for your test, or to access the various IO streams
+  # used by the command.
+  def test_execution_context(
+    argv: [],
+    options: {},
+    env: {},
+    stdin: StringIO.new,
+    stdout: StringIO.new,
+    stderr: StringIO.new,
+    executor: :default
+  )
+    Brut::CLI::Commands::ExecutionContext.new(
+      argv:,
+      options: Brut::CLI::Options.new({ "log-level": "error" }.merge(options)),
+      env:,
+      stdin:,
+      stdout:,
+      stderr:,
+      executor: executor == :default ? CapturingExecutor.new(out: stdout, err: stderr) : executor,
+    )
+  end
+end

data/lib/brut/spec_support/e2e_test_server.rb

@@ -1,6 +1,9 @@
 require "socket"
 require "timeout"
 
+module Brut::SpecSupport # This file is designed to be required without the parent namespace
+end
+
 # Manages running the app in test mode for the purposes of running End-to-End tests against it.
 class Brut::SpecSupport::E2ETestServer
   include SemanticLogger::Loggable

data/lib/brut/spec_support/general_support.rb

@@ -18,7 +18,7 @@ module Brut::SpecSupport::GeneralSupport
         expect(Time.now < check_again_at).to eq(true),"It's after #{check_again_at}. Implementation is needed"
       end
     end
-    # To pass bin/test audit with a class whose implementation is trivial, call this inside the RSpec `describe` block. This is better
+    # To pass brut test audit with a class whose implementation is trivial, call this inside the RSpec `describe` block. This is better
     # than an empty test as it makes it more explicit that you believe the implementation is trivial enough to not require a test. You
     # can also set an expiration for this thinking.
     #

data/lib/brut/spec_support/matchers/have_executed.rb

@@ -0,0 +1,35 @@
+RSpec::Matchers.define :have_executed do |commands|
+  match do |execution_context|
+    commands.all? { |command|
+      if command.kind_of?(Regexp)
+        execution_context.executor.commands_executed.any? { it.kind_of?(String) && it.match(command) }
+      else
+        execution_context.executor.commands_executed.include?(command)
+      end
+    }
+  end
+
+  failure_message do |execution_context|
+    not_executed  = commands.reject { |command|
+      if command.kind_of?(Regexp)
+        execution_context.executor.commands_executed.any? { it.kind_of?(String) && it.match(command) }
+      else
+        execution_context.executor.commands_executed.include?(command)
+      end
+    }
+
+    "Expected these commands to be executed, but they were not:\n#{format_system_args(not_executed)}\nAll executed commands:\n#{format_system_args(execution_context.executor.commands_executed)}"
+  end
+  def format_system_args(args)
+    args.map { |arg|
+      if arg.kind_of?(String)
+        arg.to_s
+      elsif arg.kind_of?(Regexp)
+        "Matching /#{arg.source}/"
+      else
+        "[" + arg.map(&:inspect).join(", ") + "]"
+      end
+    }.join("\n")
+  end
+
+end

data/lib/brut/spec_support/rspec_setup.rb

@@ -21,7 +21,6 @@
 # the thread local storage.  This allows any component that is injected with data from the `RequestContext` to access it as it would
 # normally.  You can also seed this with data that a component may need.
 # * Handles all infrastructure for end-to-end tests:
-#   - starting a test server using {Brut::SpecSupport::E2ETestServer}
 #   - launching Chromium via Playwright
 # * If using Sidekiq:
 #   - Jobs are cleared before each test
@@ -45,7 +44,7 @@ class Brut::SpecSupport::RSpecSetup
   # @param [RSpec::Core::Configuration] rspec_config yielded from `RSpec.configure`
   # @param [boolean] monkey_patch_summary_notification if true (the default),
   # RSpec's Notifications::SumaryNotification will be monkey-patched to show
-  # `bin/test` in the summary instead of `./rspec`, as that is how you would
+  # `brut test` in the summary instead of `./rspec`, as that is how you would
   # re-run a test.  But, it's still monkey-patching.
   def initialize(rspec_config:,
                  monkey_patch_summary_notification: true)
@@ -86,6 +85,7 @@ class Brut::SpecSupport::RSpecSetup
       end
     end
     @config.include Brut::SpecSupport::GeneralSupport
+    @config.include Brut::SpecSupport::CLICommandSupport, cli_command: true
     @config.include Brut::SpecSupport::ComponentSupport, component: true
     @config.include Brut::SpecSupport::HandlerSupport, handler: true
     @config.include Brut::SpecSupport::E2eSupport, e2e: true
@@ -127,7 +127,6 @@ class Brut::SpecSupport::RSpecSetup
       if example.metadata[:e2e]
         e2e_timeout = (ENV["E2E_TIMEOUT_MS"] || example.metadata[:e2e_timeout] || 5_000).to_i
         optional_sidekiq_support.disable_sidekiq_testing do
-          Brut::SpecSupport::E2ETestServer.instance.start
           Playwright.create(playwright_cli_executable_path: "./node_modules/.bin/playwright") do |playwright|
             launch_args = {
               headless: true,
@@ -160,9 +159,6 @@ class Brut::SpecSupport::RSpecSetup
         end
       end
     end
-    @config.after(:suite) do
-      Brut::SpecSupport::E2ETestServer.instance.stop
-    end
     if @monkey_patch_summary_notification
       monkey_patch_summary_notification!
     end
@@ -200,13 +196,13 @@ private
     if !klass.instance_variable_get("@_brut_has_monkeypatched")
       klass.class_eval do
         # Slightly reformatted, but the only line that's different
-        # is the one that said to use './rspec'. Now it says 'bin/test run'
+        # is the one that said to use './rspec'. Now it says 'brut test run'
         def colorized_rerun_commands(colorizer=::RSpec::Core::Formatters::ConsoleCodes)
           "\nFailed examples:\n\n" +
             failed_examples.map do |example|
               rerun_argument = rerun_argument_for(example)
               colorizer.wrap(
-                "bin/test run #{rerun_argument}", # <--- this is the only difference
+                "brut test run #{rerun_argument}", # <--- this is the only difference
                 RSpec.configuration.failure_color
               )   + 
               " " +

data/lib/brut/spec_support.rb

@@ -10,6 +10,7 @@ require_relative "spec_support/e2e_support"
 require_relative "spec_support/e2e_test_server"
 require_relative "spec_support/general_support"
 require_relative "spec_support/handler_support"
+require_relative "spec_support/cli_command_support"
 require_relative "spec_support/matcher"
 require_relative "spec_support/rspec_setup"
 require_relative "factory_bot"