brut 0.0.1 → 0.0.2

data/lib/brut/cli/command.rb

@@ -1,8 +1,14 @@
 require "optparse"
+# Base class for subcommands of a {Brut::CLI::App}. You must implement {#execute} to perform whatever action this command must perform.
 class Brut::CLI::Command
   include Brut::CLI::ExecutionResults
   include Brut::I18n::ForCLI
+  include Brut::Framework::Errors
 
+  # Call this to set the one-line description of this command
+  #
+  # @param new_description [String] When present, sets the description of this command. When omitted, returns the current description.
+  # @return [String] the current description (if called with no parameters)
   def self.description(new_description=nil)
     if new_description.nil?
       return @description.to_s
@@ -10,6 +16,12 @@ class Brut::CLI::Command
       @description = new_description
     end
   end
+
+
+  # Call this to set a an additional detailed description of this command. Currently, this should not be formatted and will be shown all on one line. This is shown after the `description`, so this text can follow from that, without having to restate it.
+  #
+  # @param new_description [String] When present, sets the detailed description of this command. When omitted, returns the current detailed description.
+  # @return [String] the current detailed description (if called with no parameters)
   def self.detailed_description(new_description=nil)
     if new_description.nil?
       if @detailed_description.nil?
@@ -20,6 +32,17 @@ class Brut::CLI::Command
       @detailed_description = new_description
     end
   end
+
+  # Set a description of the command line args this command accepts. Args are any part of the command line that is not a switch or
+  # flag.  The string you give will be used only for documentation. Typically, you would format it in one a few ways:
+  #
+  # * `args "some_arg"` indicates that exactly one arg called `some_arg` is required
+  # * `args "[some_arg]"` indicates that exactly one arg called `some_arg` is optional
+  # * `args "args..."` indicates that 
+  # * `args "[args...]"` indicates that zero or more args called `args` are accepted
+  #
+  # @param [String] new_args documentation for this command's args. If omitted, returns the current value.
+  # @return [String the current value (if called with no parameters)
   def self.args(new_args=nil)
     if new_args.nil?
       return @args.to_s
@@ -27,19 +50,67 @@ class Brut::CLI::Command
       @args = new_args
     end
   end
+
+  # Call this for each environment variable this *command* responds to.  These would be variables that affect only this command. For
+  # app-wide environment variables, see {Brut::CLI::App.env_var}.
+  #
+  # @param var_name [String] Declares that this command recognizes this environment variable.
+  # @param purpose [String] An explanation for how this environment variable affects the command. Used in documentation.
+  def self.env_var(var_name,purpose:)
+    env_vars[var_name] = purpose
+  end
+
+  # Access all configured environment variables.
+  # @!visibility private
+  def self.env_vars
+    @env_vars ||= {
+    }
+  end
+
+  # Returns the name of this command, for use on the command line.  By default, returns the "underscorized" name of this class
+  # (excluding any module namespaces).  For exaple, if your command's class is `MyApp::CLI::Commands::ClearFiles::DryRun`, the command
+  # name would be `"dry_run"`.  You can override this if you want something different.  It is recommended that it not include spaces
+  # or other characters meaningful to the shell, but if you like quotes, cool.
   def self.command_name = RichString.new(self.name.split(/::/).last).underscorized
+
+  # Checks if a given string matches this command name.  This exists to allow the use of underscores or dashes as delimiters.  Ruby
+  # likes underscores, but the shell vibe is often dashes.
+  #
+  # @param [String] string the command given on the command line
+  # @return [true|false] true if `string` is considered an exact match for this command's name.
   def self.name_matches?(string)
     self.command_name == string || self.command_name.to_s.gsub(/_/,"-") == string
   end
+
+  # Provides access to an `OptionParser` you can use to declare flags and switches that should be accepted only by this command.
+  # The way to use this is to call `.on` and provide a description for an option as you would to `OptionParser`.
+  # The only difference is that you should not pass a block to this. When the command line is parsed, the results will be placed
+  # into a {Brut::CLI::Options} instance made available to your command.
+  #
+  # @return [OptionParser]
   def self.opts
     self.option_parser
   end
+
+  # Returns the configured `OptionParser` used to parse the command portion of the command line.
+  # If you don't want to call {.opts}, you can create and return
+  # a fully-formed `OptionParser` by overriding this method.  By default, it will create one with a conventional banner.
+  #
+  # @return [OptionParser]
   def self.option_parser
     @option_parser ||= OptionParser.new do |opts|
       opts.banner = "%{app} %{global_options} #{command_name} %{command_options} %{args}"
     end
   end
 
+  # Call this if this command requires a project environment as context for what it does. When called, this will do a few things:
+  #
+  # * Your command (not app) will recognize `--env=ENVIRONMENT` as a global option
+  # * Your command will document that it recognizes the `RACK_ENV` environment variable.
+  #
+  # @see Brut::CLI::App.requires_project_env
+  #
+  # @param default [String] name of the environment to use if none was specified. `nil` should be used to require the environment to be specified explicitly.
   def self.requires_project_env(default: "development")
     default_message = if default.nil?
                         ""
@@ -49,11 +120,22 @@ class Brut::CLI::Command
     opts.on("--env=ENVIRONMENT","Project environment#{default_message}")
     @default_env = default
     @requires_project_env = true
+    self.env_var("RACK_ENV",purpose: "default project environment when --env is omitted")
   end
 
+  # Returns the default project env, based on the logic described in {.requires_project_env}
   def self.default_env           = @default_env
+  # Returns true if this app requires a project env
   def self.requires_project_env? = @requires_project_env
 
+  # Creates the command before executing it. Generally you would not call this directly.
+  #
+  # @param [Brut::CLI::Options] command_options the command options parsed from the command line.
+  # @param [Brut::CLI::Options] global_options the global options parsed from the command line.
+  # @param [Array] args Any unparsed arguments
+  # @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
+  # @param [Brut::CLI::Executor] executor used to execute child processes instead of e.g. `system`
   def initialize(command_options:,global_options:, args:,out:,err:,executor:)
     @command_options = command_options
     @global_options  = global_options
@@ -66,8 +148,20 @@ class Brut::CLI::Command
     end
   end
 
+  # Convienince method to call {Brut::CLI::Executor#system!} on the executor given in the constructor.
+  # @param (see Brut::CLI::Executor#system!)
+  # @return (see Brut::CLI::Executor#system!)
   def system!(*args) = @executor.system!(*args)
 
+  # Use this inside {#execute} to createa compound command that executes other commands that are a part of your CLI app.
+  # Note that each command will be given the same global and commmand options and the same arguments, so these commands must be able
+  # to complete as desired in that way.
+  #
+  # Note that since commands are just classes, you can certianly create them however you like and call `execute` yourself.
+  #
+  # @param [Enumerable<Class>] command_klasses one or more classes that subclass {Brut::CLI::Command} to delegate to.
+  # @return [Brut::CLI::ExecutionResults::Result] the first non successful result is returned and processing is stopped, otherwise returns the
+  # result of the last class executed.
   def delegate_to_commands(*command_klasses)
     result = nil
     command_klasses.each do |command_klass|
@@ -80,28 +174,52 @@ class Brut::CLI::Command
     result
   end
 
-  def delegate_to_command(command_klass)
-    command = command_klass.new(command_options: options, global_options:, args:, out:, err:, executor: @executor)
-    as_execution_result(command.execute)
-  end
-
+  # You must implement this to perform whatever action your command needs to perform.  In order to do this, you will have access to:
+  #
+  # * {#options} - the command options passed on the command line
+  # * {#global_options} - the global options passed on the command line
+  # * {#args} - the args passed on the command line
+  # * {#out} - an IO you should use to print messages to the standard out.
+  # * {#err} - on IO you should use to print messages to the standard error.
+  # * {#system!} - the method you should use to spawn child processes.
+  #
+  # @return [Brut::CLI::ExecutionResults::Result] a description of what happened during processing. It is preferable to try to return
+  # something instead of raising an exception.
+  # @raise [Brurt::CLI::Error] if thrown, this will be caught and handled by {Brut::CLI::AppRunner}.
+  # @raise [StandardError] if thrown, this will bubble up and show your user a very sad stack trace that will make them cry. Don't.
   def execute
-    raise Brut::Framework::Errors::AbstractMethod
+    abstract_method!
   end
 
+  # Called before any execution or bootstrapping happens but after {Brut::CLI::App#before_execute} is called.  This will have access
+  # to everything {#execute} can access.
+  # @raise [Brurt::CLI::Error] if thrown, this will be caught and handled by {Brut::CLI::AppRunner} and execution will be aborted.
+  # @raise [StandardError] if thrown, this will bubble up and show your user a very sad stack trace that will make them cry. Don't.
   def before_execute
   end
 
+  # @!visibility private
   def set_env_if_needed
     if self.class.requires_project_env?
       ENV["RACK_ENV"] = options.env
     end
   end
 
+  # Called if there is an exception during bootstrapping.  By default, it re-raises the exception, which cases the command to abort.
+  # The reason you may want to overrid this is that your command line app may exist to handle a bootstrapping exception.  For example,
+  # the built-in {Brut::CLI::Apps::DB} app will catch various database connection errors and then create or migrate the database.
+  #
+  # Yes, I realize this means we are using exceptions for control flow. It's fine.
+  #
+  # @param [StandardError] ex whichever exception was caught during bootstrapping
+  # @return [void] ignored
+  # @raise [Brurt::CLI::Error] if thrown, this will be caught and handled by {Brut::CLI::AppRunner} and execution will be aborted.
+  # @raise [StandardError] if thrown, this will bubble up and show your user a very sad stack trace that will make them cry. Don't.
   def handle_bootstrap_exception(ex)
     raise ex
   end
 
+  # @!visibility private
   def bootstrap!(project_root:, configure_only:)
     require "bundler"
     Bundler.require(:default, ENV["RACK_ENV"].to_sym)
@@ -116,15 +234,32 @@ class Brut::CLI::Command
 
 private
 
+  # @!visibility public
+  # @return [Brut::CLI::Options] the command options parsed on the command line
   def options        = @command_options
+  # @!visibility public
+  # @return [Brut::CLI::Options] the global options parsed on the command line
   def global_options = @global_options
+  # @!visibility public
+  # @return [Array<String>] the arguments parsed from the command line
   def args           = @args
+  # @!visibility public
+  # @return [Brut::CLI::Output] IO to use for sending messages to the standard output
   def out            = @out
+  # @!visibility public
+  # @return [Brut::CLI::Output] IO to use for sending messages to the standard error
   def err            = @err
 
+  # Exists to warn users not to use `puts`
   def puts(...)
     warn("Your CLI apps should use out and err to produce terminal output, not puts", uplevel: 1)
     Kernel.puts(...)
   end
 
+  def delegate_to_command(command_klass)
+    command = command_klass.new(command_options: options, global_options:, args:, out:, err:, executor: @executor)
+    as_execution_result(command.execute)
+  end
+
+
 end

data/lib/brut/cli/error.rb

@@ -1,12 +1,39 @@
-# Marker that means an expected error happens and
-# we don't need to show the stack trace
+# All errors from a Brut CLI should extend this.  Any error that does will be caught and handled without showing the user a stack
+# trace.
 class Brut::CLI::Error < StandardError
 end
+# Raised when a child process executed by {Brut::CLI::Executor} returns a nonzero exit status.
+#
+# @see Brut::CLI::Executor#system!
 class Brut::CLI::SystemExecError < Brut::CLI::Error
-  attr_reader :command,:exit_status
+  # @return [String|Array] command line invocation that caused the error
+  attr_reader :command
+  # @return [Integer] exit status of the command
+  attr_reader :exit_status
+  # @param [String|Array] command or args passed to {Brut::CLI::Executor#system!}.
+  # @param [Integer] exit_status the exit status of the command.
   def initialize(command,exit_status)
     super("#{command} failed - exited #{exit_status}")
     @command = command
     @exit_status = exit_status
   end
 end
+
+# Raised when an `OptionParser::ParseError` is caught to provide a more useful
+# error message given the global/command optiona dichotomy.
+class Brut::CLI::InvalidOption < Brut::CLI::Error
+  def initialize(option_parser_parse_error, context:)
+    args = option_parser_parse_error.args
+    count_message = if option_parser_parse_error.args.length == 1
+                      "isn't a valid option"
+                    else
+                      "aren't valid options"
+                    end
+    type_message = if context.kind_of?(Class)
+                     "for the '#{context.command_name}' command"
+                   else
+                     "for the app globally"
+                   end
+    super("#{args.join(", ")} #{count_message} #{type_message}")
+  end
+end

data/lib/brut/cli/execution_results.rb

@@ -1,30 +1,43 @@
 module Brut
   module CLI
+    # Included in commands to allow convienient ways to return structured information about what happened during command 
+    # execution.
     module ExecutionResults
+      # Base class for all results.
       class Result
+        # @return [Strting] any message provided in the results. Generally `nil` for successful results.
         attr_reader :message
+
+        # Create a new result
+        #
+        # @param exit_status [Integer] exit status desired for this command. 0 is treated as success by any command that called your
+        # command.  All other values have command-defined meanings.
+        # @param message [String|nil] a message to explain the results, if relevant.
         def initialize(exit_status:,message:nil)
           @exit_status = exit_status
           @message = message
         end
 
-        # Returns true if execution internal to the command should stop
+        # @return [true|false] true if execution internal to the command should stop
         def stop?       = @exit_status != 0
-        # Returns true if the execution of the command succeeded or didn't error
+        # @return [true|false] true if the execution of the command succeeded or didn't error
         def ok?         = @exit_status == 0
-        # Returns the exit status to use for the CLI
+        # @return [Integer] the exit status
         def to_i        = @exit_status
+        # @return [true|false] true if the result means that the user should be show CLI usage in addition to any messaging.
         def show_usage? = false
       end
 
-      # Stop execution, even though nothing is wrong
+      # @!visibility private
       class Stop < Result
         def initialize
           super(exit_status: 0)
         end
+        # @return [true] true
         def stop? = true
       end
 
+      # @!visibility private
       class ShowCLIUsage < Stop
         attr_reader :command_klass
         def initialize(command_klass:)
@@ -34,14 +47,14 @@ module Brut
         def show_usage? = true
       end
 
-      # Continue execution
+      # @!visibility private
       class Continue < Result
         def initialize
           super(exit_status: 0)
         end
       end
 
-      # Abort execution immediately
+      # @!visibility private
       class Abort < Result
         def initialize(exit_status:1,message:nil)
           if exit_status == 0
@@ -50,6 +63,7 @@ module Brut
           super(exit_status:,message:)
         end
       end
+      # @!visibility private
       class CLIUsageError < Abort
         def initialize(message:)
           super(message:,exit_status:65)
@@ -57,12 +71,36 @@ module Brut
         def show_usage? = true
       end
 
+      # Return this from {Brut::CLI::Command#execute} to stop execution, without signaling an error
       def stop_execution                         = Stop.new
+      # Return this from {Brut::CLI::Command#execute} to indicate any other execution may continue. This is mostly useful when one
+      # command calls another e.g. with {Brut::CLI::Command#delegate_to_commands}.
       def continue_execution                     = Continue.new
+      # Return this from {Brut::CLI::Command#execute} to stop execution and signal an error
+      #
+      # @param [String] message the error message
+      # @param [Integer] exit_status the exit status (should ideally not be 0)
       def abort_execution(message,exit_status:1) = Abort.new(message:,exit_status:)
+      # Return this from {Brut::CLI::Command#execute} to stop execution because the user messed up the CLI invocation.
+      #
+      # @param [String] message the error message
       def cli_usage_error(message)               = CLIUsageError.new(message:)
+      # Return this from {Brut::CLI::Command#execute} to stop execution, and show the user the CLI help, optionally for a specific
+      # command.
+      #
+      # @param [Class] command_klass if given, this it he class whose help will be shown.
       def show_cli_usage(command_klass=nil)      = ShowCLIUsage.new(command_klass:)
 
+      # Coerce a value to the appropriate {Brut::CLI::ExecutionResults::Result}.  Currently works as follows:
+      #
+      # 1. If `exit_status_or_execution_result` is nil or true, returns a successful result
+      # 2. If `exit_status_or_execution_result` is an integer, returns a result with no message and that value as the exit status
+      # 3. If `exit_status_or_execution_result` is false, returns {#abort_execution}.
+      # 4. If `exit_status_or_execution_result` is a {Brut::CLI::ExecutionResults::Result}, returns that
+      # 5. Otherwise, raises `ArgumentError`
+      #
+      # @param [nil|true|false|Brut::CLI::ExecutionResults::Result|Integer] exit_status_or_execution_result the value to coerce
+      # @return [Brut::CLI::ExecutionResults::Result] appropriate for the parameter
       def as_execution_result(exit_status_or_execution_result)
         if exit_status_or_execution_result.kind_of?(Numeric) || exit_status_or_execution_result.nil?
           Result.new(exit_status: exit_status_or_execution_result.to_i)

data/lib/brut/cli/executor.rb

@@ -1,9 +1,29 @@
 require "open3"
+# Abstracts the invocation of child processes, but includes useful output and exception handling that you'd need to be transparent to
+# the user.  In particular:
+#
+# * Outputs the command being executed to the standard error (via {Brut::CLI::Output}).
+# * Outputs the command's standard error and standard output in real time.  So, this should be usable for spawned commands that
+# produce real time output like test runners.
+# * Assumes spawned commands should succeed, raising an error if they do not.
 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
   end
+
+  # Execute a command, logging it to the standard output and outputing the commands output and error to the standard output and error,
+  # respecitively
+  #
+  # @see https://docs.ruby-lang.org/en/3.3/Open3.html#method-c-popen3
+  #
+  # @param [String|Array] args Whatever you would give to `Kernel#system` or `Open3.popen3`.
+  # @raise Brut::CLI::Error::SystemExecError if the spawed command exits nonzer
+  # @return [true]
   def system!(*args)
     @out.puts "Executing #{args}"
     wait_thread = Open3.popen3(*args) do |_stdin,stdout,stderr,wait_thread|
@@ -30,7 +50,7 @@ class Brut::CLI::Executor
     if wait_thread.value.success?
       @out.puts "#{args} succeeded"
     else
-      raise Brut::CLI::SystemExecError.new(*args,wait_thread.value.exitstatus)
+      raise Brut::CLI::SystemExecError.new(args,wait_thread.value.exitstatus)
     end
     true
   end

data/lib/brut/cli/options.rb

@@ -1,19 +1,46 @@
-# Convienience module to put into Hash to allow options
-# parsed to be a bit more accessible
+# Wraps parsed command line options to provide a method-like interface instead of simple `Hash` acceess.  Also allows specifying default values when an option wasn't given on the command line, as well as boolean coercion for switches.  Allows accessing options via snake_case in code, even if specified via kebab-case on the command line.
 class Brut::CLI::Options
   def initialize(parsed_options)
     @parsed_options = parsed_options
     @defaults = {}
   end
 
+  # Returns the parsed options as a `Hash`
+  # @return [Hash]
   def to_h = @parsed_options
 
+  # Access an options value directly.
+  # @param [String] key the key to use. This must be the exact name you used when calling `opts.on` or when creating the `OptionParser` for your app or command. Generally, use the {#method_missing}-provided version instead of this.
   def [](key) = @parsed_options[key]
+  # Check if `key` was provided on the command line.
+  # @param [String] key the key to use. This must be the exact name you used when calling `opts.on` or when creating the `OptionParser` for your app or command.
   def key?(key) = @parsed_options.key?(key)
+
+  # Set a default value for an option when {#method_missing} is used to access it and that flag or switch was not used on the command
+  # line.
+  # @param [Symbol] sym the symbol of the option, either in kebab-case or snake_case.
+  # @param [Object] default_value the value to return if that option was not used on the command line
   def set_default(sym,default_value)
     @defaults[sym] = default_value
   end
 
+  # Dynamically creates methods for each command-line option.  Note that this doesn't know what options could've been provided, so it
+  # will respond to any method that either takes no arguments or where the only argument is `default:`.
+  #
+  # @param [Symbol] sym kebab or snake case value of the option. A question mark should be used if the option is to be coerced to a booealn.
+  # @param [Array|Hash] args if the first arg is a Hash with the key `default:`, this value will be used if `sym` has no value
+  #
+  # @return [true|false|nil|Object] the value of the option used on the command line, or the default used in `default:`, or the
+  # preconfigured default, or `nil`.  If `sym` ended in a question mark, true or false will be returned (never nil).
+  #
+  # @example
+  #
+  #    # Suppose the user provided `--log-level=debug --dry-run` on the command line
+  #    options.log_level               # => "debug"
+  #    options.verbose                 # => nil
+  #    options.verbose(default: "yes") # => "yes"
+  #    options.dry_run?                # => true
+  #    options.slow?                   # => false
   def method_missing(sym,*args,&block)
     boolean = false
     if sym.to_s =~ /\?$/

data/lib/brut/cli/output.rb

@@ -1,14 +1,41 @@
+# 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.
+#
+# 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.
 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:)
     @io          = io
     @prefix      = prefix
     @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 << ""
@@ -19,10 +46,30 @@ class Brut::CLI::Output
     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
+
+  # Flush the underlying `IO`.
   def flush
     @io.flush
     self

data/lib/brut/cli.rb

@@ -1,6 +1,30 @@
 module Brut
+  # Brut provides a basic CLI framework for building CLIs that have access to your Brut app's innerworkings.
+  # This is an alternative to Rake tasks which suffer from poor usability and testability.
+  #
+  # To create a CLI, you will subclass {Brut::CLI::App}. That class will define your UI as well as any subcommands
+  # 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
@@ -8,11 +32,13 @@ module Brut
     autoload(:Command, "brut/cli/command")
     autoload(:Error, "brut/cli/error")
     autoload(:SystemExecError, "brut/cli/error")
+    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")
+    # Holds Brut-provided CLI apps that are set up in your project.
     module Apps
       autoload(:DB,"brut/cli/apps/db")
       autoload(:DB,"brut/cli/apps/test")

data/lib/brut/factory_bot.rb

@@ -5,7 +5,9 @@ require "active_support"
 require "factory_bot"
 require "faker"
 
+# Encompasses a Brut app's FactoryBot configuration. This allows it to be used outside of tests.
 class Brut::FactoryBot
+  # Configures FactoryBot and finds all definitions.  After this, calls like `FactoryBot.create(...)` should work.
   def setup!
     Faker::Config.locale = :en
     FactoryBot.definition_file_paths = [