brut 0.0.1 → 0.0.2

data/doc-src/pages.md

@@ -0,0 +1,210 @@
+# Pages and Components
+
+A website is made up of pages.  Even a web *app* has pages.  Thus, the most basic way to create dynamic behavior with Brut is the
+*page*.  In Brut, a page is a URL, a subclass of {Brut::FrontEnd::Page}, and an ERB template.  The template is rendered in the context
+of an instance of the class whenever the URL is requested.
+
+## Overview of Rendering Pages
+
+In your `app.rb`, you first declare a page using the {Brut::SinatraHelpers::ClassMethods#page} method (inside the block given to {Brut::Framework::App.routes}):
+
+    class App < Brut::Framework::App
+
+      routes do
+
+        page "/sign_in"
+      end
+    end
+
+The name of the route must start with a `/` and the rest of the route determines the name of the page.  In the example above, Brut
+will expect to find a class named `SignInPage`, which should be located in `app/src/front_end/pages`.  You can create it with
+`bin/scaffold`:
+
+    > bin/scaffold page SignInPage
+
+The page class must subclass {Brut::FrontEnd::Page}.  You write a constructor to accept whatever your page needs to assemble the data
+needed to render it.
+
+The HTML is generated based on an ERB file located in `app/src/front_end/pages`.  In this example, that's
+`app/src/front_end/pages/sign_in_page.html.erb`.  That ERB is executed with an instance of the page class as context.  That means you
+can references any methods or ivars.
+
+## Creating a Page Class
+
+{Brut::FrontEnd::Page#render} is called by Brut and expects to receive HTML, which it will send as the body of the response. `render`
+manages the ERB rendering, so the bulk of your page's logic will be in other methods.  The constructor is where any data you need is
+provided.
+
+A page's `initialize` method must accept only keyword arguments and those keywords are used by Brut to determine what data needs to be
+passed in.  This technique, called *{file:doc-src/keyword-injection.md Keyword Injection}*, is used in several other places in Brut.
+
+When the page's URL is requested, an instance of your page class is created, passing in the values needed.  Beyond that, however, your page class is a normal Ruby class. You can save data to instance variables, implement attributes or other methods. Basically, whatever logic your page needs to render will exist in the page class.
+
+## Implementing Your ERB
+
+ERB is part of the Ruby standard library that allows the creation of dynamic templates.  Brut's ERB is close to this implementation, but has a few additional features that make working with HTML a bit safer.
+
+### Your Page is the Only Context
+
+The instance of your page class is the only context available to the ERB.  There is no set of global helpers that are injected, nor
+are there any modules added when the page is rendered.  Anything you need to do in your ERB must be available to the page class you've
+created.
+
+The reason for this is to keep things simple.  If your page's HTML needs access to a lot of stuff, your page class will be the source
+of truth as to where that stuff comes from.  You will always be able to figure out where methods are defined by looking at the page
+class or any of its ancestors.  You are free to `include` as many modules as you like, or dump lots of methods into your `AppPage`
+base class. But you don't have to.
+
+### All Strings are HTML-Escaped
+
+Any instance of a `String` is HTML-escaped by Brut before being inserted into the HTML being generated by the ERB.  This is, generally, what you want to have happen.  If you have a string that you believe is safe and does not need to be escaped, you can prevent HTML-escaping in one of two ways:
+
+* Call {Brut::FrontEnd::Component#html_safe!} on the string
+
+        <%= html_safe!(get_value) %>
+
+* Wrap the string in a {Brut::FrontEnd::Templates::HTMLSafeString}.
+
+        def get_value
+          Brut::FrontEnd::Templates::HTMLSafeString.from_string(some_value)
+        end
+
+  This is what `html_safe!` does and this is what Brut does internally. Brut doesn't monkey-patch `String`. A `String` is always
+  considered unsafe, and an `HTMLSafeString` is always considered safe.
+
+Both of these methods are verbose, but this is on purpose.  You generally don't want un-escaped HTML going into your HTML, but if you
+do, you may find it better to create a component (see below), or use {Brut::FrontEnd::Component::Helpers#html_tag} to generate markup.
+
+### Pages Have Layouts
+
+The page's ERB is rendered in the context of a *layout*.  A Layout works similar to how it works in Rails. It's intended to hold HTML
+needed by every page of your app. A minimal layout might look like so:
+
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <%= component(Brut::FrontEnd::Components::PageIdentifier.new(self.page_name)) %>
+        <link rel="preload" as="style" href="<%= asset_path('/css/styles.css') %>">
+        <link rel="stylesheet"         href="<%= asset_path('/css/styles.css') %>">
+        <script defer src="<%= asset_path('/js/app.js') %>"></script>
+      </head>
+      <body>
+        <%= yield %>
+      </body>
+    </html>
+
+The layout is rendered in the context of the page class, so every page must provide whatever features are needed by the layout. This
+is usually done by adding globally-used functions to `AppPage`, which is the base class of all your app's pages.
+
+A page can use another layout by overriding {Brut::FrontEnd::Page#layout}.  The string returned must match a file in
+`app/src/front_end/layouts/`.
+
+### There Are No Partials
+
+Rails partials are not part of ERB, and Brut does not include this feature. Instead, you would use *Components*.
+
+## Decompose and Re-Use with Components
+
+*Components* in Brut are very similar to the View Components library, though somewhat simpler.  A component is a class and an ERB
+template.  That template is rendered in the context of an instance of the class.  That class is created the same way a page is and has
+a `render` method that works just like a page's.
+
+This is all because {Brut::FrontEnd::Page} extends {Brut::FrontEnd::Component}.  A page adds the concept of a layout, but generally a
+page and a component are the same thing.
+
+### Using Components
+
+The main difference from your perspective is that generally *you* create instances of components.  This means that your page must have
+access to any data a component needs.  When you've created your component instance, use {Brut::FrontEnd::Component#component} to
+render it:
+
+    <%= component(Button.new(type: :danger, label: "Cancel Subscription")) %>
+
+### Components with Templates
+
+The most common way to use a component is with an ERB template. It is expected to be in `app/src/front_end/components`.  For the
+hypothetical `Button` component above, Brut would expect `app/src/front_end/components/button.html.erb` to exist as a template.
+
+Just like a page, the component's ERB is rendered in the context of the component only.
+
+Sometimes, components are simple enough that you don't need HTML.
+
+### Components That Render Themselves
+
+While overriding `render` in a page is generally discouraged, {Brut::FrontEnd::Component#render} can be overridden if you want to
+generate HTML yourself.  The best way to do that is with {Brut::FrontEnd::Component::Helpers#html_tag}, though you can always return a
+`String` or {Brut::FrontEnd::Templates::HTMLSafeString} that you've created yourself. Just remeber that all `String` instances will be
+HTML-escaped.
+
+As an example, here is how you might have a Markdown component that renders Markdown as HTML:
+
+    class MarkdownComponent < AppComponent
+      def initialize(markdown:)
+        @markdown = markdown
+        @renderer = Redcarpet::Markdown.new(
+          Redcarpet::Render::HTML.new(
+            filter_html: true,
+            no_images: true,
+            no_styles: true,
+            safe_links_only: true,
+          ),
+          fenced_code_blocks: true,
+          autolink: true,
+          quote: true,
+        )
+      end
+
+      def render
+       html_safe!(@renderer.render(@markdown.to_s))
+      end
+    end
+
+
+### Global Components
+
+While a component is just a class with an initializer, sometimes you need a component that is generally useful on any page, but that
+you don't want to initialize.  For example, if your component needs access to the flash, but your page does not, you don't want your
+page to require a flash just to pass to the component.  In that case, a *global component* can be used and Brut will instantiate it.
+
+{Brut::FrontEnd::Component#component} can be given a class, and Brut will use keyword injection to create it.  Consider a generic
+flash component:
+
+    class GlobalFlash < AppComponent
+
+      attr_reader :flash
+
+      def initialize(flash:)
+        @flash = flash
+      end
+    end
+
+You can use this anywhere like so:
+
+    <%= component(GlobalFlash) %>
+
+Because the flash is availble from the {Brut::FrontEnd::RequestContext}, Brut can create this component when needed.
+
+## Testing Pages and Components
+
+Pages and Components are classes with a constructor you create and a well-defined primary method called `render`.  This means you can
+test them conventionally, since they can be directly created in your tests.
+
+That said, you likely want to test the generated HTML and not the methods of the class.  All tests of a page or component have the
+methods in {Brut::SpecSupport::ComponentSupport} available.  Of particular interest is
+{Brut::SpecSupport::ComponentSupport#render_and_parse}.
+
+This method accepts an instance of a page or component, parses the resulting HTML with Nokogiri, and returns a
+{Brut::SpecSupport::EnhancedNode}, which wraps a `Nokogiri::XML::Node` or `Nokogiri::XML::Element`, depending on what was parsed.  You
+can then use Nokogiri's API locate elements and assert on them.
+
+To keep close to the web platform, it's recommended to use CSS selectors either via {Brut::SpecSupport::EnhancedNode#e} or {Brut::SpecSupport::EnhancedNode#e!} (both of which wrap Nokogiri's `css` method).
+
+Instead of creating another API for accessing HTML content, the Nokogiri API should be used directly.  You can create custom matchers
+as needed for common assertions.  Brut includes a few that you will find useful:
+
+* `have_link_to`
+* `have_html_attribute`
+* `have_i18n_string`
+
+

data/doc-src/route-hooks.md

@@ -0,0 +1,59 @@
+# Route and Page Hooks
+
+Route and page hooks allow you to perform logic or redirect the visitor before a page is rendered or action handled.
+
+## Route Hooks
+
+Route hooks are objects that are run before or after a request has been handled. They are useful for setting up cross-cutting code
+that you don't want to have inside a page or handler.
+
+To use one, call either {Brut::Framework::App.before} or {Brut::Framework::App.after}, passing it the *name* of a class to use as the
+hook (i.e. a `String`).
+
+Then, implement that class, extending {Brut::FrontEnd::RouteHook}, and provide either {Brut::FrontEnd::RouteHook#before} or {Brut::FrontEnd::RouteHook#after}.  As discussed in {file:doc-src/keyword-injection.md Keyword Injection}, your hook can be passed some managed values to allow it to work.
+
+In general, a hook will allow the request to continue or not, but using one of the following methods as the return value:
+
+* {Brut::FrontEnd::HandlingResults#redirect_to} to redirect the user instead of rendering the page or handling the request.
+* {Brut::FrontEnd::HandlingResults#http_status} to return an HTTP status instead of rendering the page or handling the request.
+* {Brut::FrontEnd::RouteHook#continue} to proceed with the request.
+
+## Page Hooks
+
+Sometimes, the behavior you want to manage before a page is rendered is specific to a page and not cross-cutting. Because a page
+exepcts to render HTML, you cannot easily put such code in your page class.
+
+If you implement {Brut::FrontEnd::Page#before_render}, you can skip page rendering entirely and redirect the user or send an error.  A
+good example of this would be a set of admin pages where the logged-in site visitor must possess some roles in order to see the page.
+
+A page hook expects one of these return values:
+
+* `URI` - redirect the visitor instead of rendering the page.
+* {Brut::FrontEnd::HttpStatus} - Send the browser this status code instead of rendering the page.
+* Anything else - render the page as normal
+
+Thus, the lifecycle of a page is:
+
+1. "Before" Route Hooks
+2. Page Initializer, injected as described in {file:doc-src/keyword-injection.md}
+3. Page's `before_render`, called with no arguments.
+4. Page's ERB generates HTML
+5. "After" Route Hooks
+
+## Handler Hooks
+
+Like page hooks, handler hooks are called before handling logic.  Implement `before_handle`.  It's arguments must be a subset of the
+arguments passed to `handle`.  Thus, any value needed by `before_handle` must be declared as a keyword argument to `handle` as well.
+
+If `before_handle` returns `nil`, `handle` is then called.  Otherwise, `handle` is skipped and the return value of `before_handle` is
+interpreted as the return value of `handle`. See {Brut::FrontEnd::Handler#handle}.
+
+This makes the lifecycle of a handler as such:
+
+1. "Before" Route Hooks
+2. Handler Initializer, called with no argument.
+3. Handler's `handle!`, injected with arguments as described in {file:doc-src/keyword-injections.md}
+   1. `handle!` calls `before_handle`, passing the arguments in.
+   2. `handle!` calls `handle`, passing the arguments in.
+4. "After" Route Hooks
+

data/docs-todo.md

@@ -0,0 +1,32 @@
+# DOCS strategy
+
+## Four types:
+
+* Tutorials
+* HOWTO
+* Explanations
+* Reference
+
+Ideally, these can interlink, espeically to avoid reference having to have too much stuff in it.
+
+## Tutorials
+
+* SHORT - Making a blog from zero to done
+* LONG  - Agile Web Development with Brut
+
+## HOWTO
+
+* Create, validate, and process a form
+* Implement Omniauth
+* ???
+
+## Explanations
+
+* Brut overall architecture
+* Brut guiding principles
+* ???
+
+## Reference
+
+* API Docs
+

data/lib/brut/back_end/seed_data.rb

@@ -1,6 +1,10 @@
 require_relative "../factory_bot"
 module Brut
-  module Backend
+  module BackEnd
+    # Base class and manager of Seed Data for the app.  Seed Data is data used for development. It is not for populating e.g.
+    # reference data or other stuff in production.
+    #
+    # Seed Data uses FactoryBot.
     class SeedData
       def self.inherited(seed_data_klass)
         @classes ||= []

data/lib/brut/back_end/validator.rb

@@ -1,3 +1,3 @@
 class Brut::BackEnd::Validators
-    autoload(:FormValidator, "brut/back_end/validators/form_validator")
+  autoload(:FormValidator, "brut/back_end/validators/form_validator")
 end

data/lib/brut/back_end/validators/form_validator.rb

@@ -1,13 +1,38 @@
-# Subclass this in your back-end to create a server-side
-# validator for your form.  This provides for a much
-# richer set of validations than you get from the browser, but
-# works basically the same way.
+# Provides a very light DSL to declaring server-side validations for your
+# {Brut::FrontEnd::Form} subclass. Unlike Active Record, these validations aren't mixed-into another object.
+# Your subclass of this class is a standalone object that will operate on a form.
+#
+# @example
+#     # Suppose you are creating a widget with a name and description.
+#     # The form requires name, but not description, however if
+#     # the user initiates a "publish" action from that form, the description is
+#     # required. This cannot be managed with HTML alone.
+#     class WidgetPublishValidator < Brut::BackEnd::Validators::FormValidator
+#       validate :description, required: true, minlength: 10
+#     end
+#
+#     # Then, in your back-end logic somewhere
+#
+#     validator = WidgetPublishValidator.new
+#     validator.validate(form)
+#     if form.constraint_violations?
+#       # return back to the user
+#     else
+#       # proceed with business logic
+#     end
+#
 class Brut::BackEnd::Validators::FormValidator
-  def self.validate(attribute,options)
+  # Called inside the subclass body to indicate that a given form input should be validated based on the given options
+  # @param [String|Symbol] input_name name of the input of the form
+  # @param [Hash] options options describing the validation to perform.
+  def self.validate(input_name,options)
     @@validations ||= {}
-    @@validations[attribute] = options
+    @@validations[input_name] = options
   end
 
+  # Validate the given form, calling {Brut::FrontEnd::Form#server_side_constraint_violation} on each validate failure found.
+  #
+  # @param [Brut::FrontEnd::Form] form the form to validate
   def validate(form)
     @@validations.each do |attribute,options|
       value = form.send(attribute)

data/lib/brut/cli/app.rb

@@ -1,9 +1,28 @@
 require "optparse"
 require_relative "../junk_drawer"
+
+# Base class for all Brut-powered CLI Apps.  Your subclass will call or override methods to declare the UI of your CLI app, including
+# the commands it provides and options it recognizes.  These mostly help to provide command-line documentation for your app, but also
+# provide basic help with accessing the command line arguments and options.  Internally, this uses Ruby's `OptionParser`.
+#
+# The types of CLIs this framework supports are *command suites* where a single CLI app has several subcommands, similar to `git`.  As
+# such, the CLI has several parts that you can configure:
+#
+# ```
+# cli_app [global options] «subcommand» [command options] [arguments]
+# ```
+#
+# * Global options appear between the CLI app's executable and the name of the subcommand. These affect any command. A common example is `--log-level`.  These are configured with {Brut::CLI::App.on} or {Brut::CLI::App.option_parser}.
+# * Subcommand is a single string representing the command to execute.  The available commands are returned by {Brut::CLI::App.commands} although it's more conventional to declare inner classes of your app that extend {Brut::CLI::Command}.
+# * Command options appear after the subcommand and apply only to that sub command.  They are declared with {Brut::CLI::Command.on} or {Brut::CLI::Command.opts}.
+# * Arguments are any additional values present on the command line.  They are defined per-command and can be documented via {Brut::CLI::Command.args}.
 class Brut::CLI::App
   include Brut::CLI::ExecutionResults
   include Brut::I18n::ForCLI
 
+  # Returns a list of {Brut::CLI::Command} classes that each represent the subcommands your CLI app accepts.
+  # By default, this will look for all internal classes that extend {Brut::CLI::Command} and use them as your subcommands.
+  # This means that you don't need to override this method and can instead define classes inside your app subclass.
   def self.commands
     self.constants.map { |name|
       self.const_get(name)
@@ -11,6 +30,11 @@ class Brut::CLI::App
       constant.kind_of?(Class) && constant.ancestors.include?(Brut::CLI::Command) && constant.instance_methods.include?(:execute)
     }
   end
+
+  # Call this to set the one-line description of your command line app.
+  #
+  # @param new_description [String] When present, sets the description of this app. 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
@@ -18,21 +42,77 @@ class Brut::CLI::App
       @description = new_description
     end
   end
+
+  # Call this for each environment variable your *app* responds to.  These would be variables that affect any of the subcommands. For
+  # command-specific environment variables, see {Brut::CLI::Command.env_var}.
+  #
+  # @param var_name [String] Declares that this app recognizes this environment variable.
+  # @param purpose [String] An explanation for how this environment variable affects the app. 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 ||= {
+      "BRUT_CLI_RAISE_ON_ERROR" => "if set, shows backtrace on errors"
+    }
+  end
+
+  # Specify the default command to use when no subcommand is given.
+  #
+  # @param new_command_name [String] if present, sets the name of the command to run when none is given on the command line. When omitted, returns the currently configured name.  The default is `help`.
   def self.default_command(new_command_name=nil)
     if new_command_name.nil?
       return @default_command || "help"
     else
-      @default_command = new_command_name.nil? ? nil : new_command_name.to_s
+      @default_command = new_command_name.to_s
     end
   end
+
+  # Provides access to an `OptionParser` you can use to declare flags and switches that should be accepted globally. 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]
+  #
+  # @example
+  #
+  #    class MyApp < Brut::CLI::App
+  #    
+  #      opts.on("--dry-run","Don't change anything, just pretend")
+  #
+  #    end
   def self.opts
     self.option_parser
   end
+
+  # Returns the configured `OptionParser` used to parse global 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} commands [command options] [args]"
     end
   end
+
+  # Call this if your CLI requires a project environment as context for what it does. For example, a command to analyze the database
+  # needs to know if it should operate on development, test, or production.  When called, this will do a few things:
+  #
+  # * Your app will recognize `--env=ENVIRONMENT` as a global option
+  # * Your app will recognize the `RACK_ENV` environment variable.
+  #
+  # When your app executes, the project environment will be determined as follows:
+  #
+  # 1. If `--env` was on the command line, that is the environment used
+  # 2. If `RACK_ENV` is set in the environment, that is used
+  # 3. Otherwise the value given to the `default:` parameter of this method is used.
+  #
+  # @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?
                         ""
@@ -42,16 +122,26 @@ class Brut::CLI::App
     opts.on("--env=ENVIRONMENT","Project environment#{default_message}")
     @default_env = ENV["RACK_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
 
+  # Call this if your app must operate before the Brut framework starts up.
   def self.configure_only!
     @configure_only = true
   end
   def self.configure_only? = !!@configure_only
 
+  # Create the App. This is called by {Brut::CLI::AppRunner}.
+  #
+  # @param [Brut::CLI::Options] global_options global options specified on the command line
+  # @param [Brut::CLI::Output] out IO to use to send output to the standard output
+  # @param [Brut::CLI::Output] err IO to use to send output to the standard error
+  # @param [Brut::CLI::Executor] executor Class to use to execute child processes instead of e.g. `system`.
   def initialize(global_options:,out:,err:,executor:)
     @global_options = global_options
     @out            = out
@@ -62,12 +152,14 @@ class Brut::CLI::App
     end
   end
 
+  # @!visibility private
   def set_env_if_needed
     if self.class.requires_project_env?
       ENV["RACK_ENV"] = options.env
     end
   end
 
+  # @!visibility private
   def load_env(project_root:)
     if !ENV["RACK_ENV"]
       ENV["RACK_ENV"] = "development"
@@ -81,15 +173,19 @@ class Brut::CLI::App
     end
   end
 
+  # Called before anything else happens. You can override this to perform any setup or other checking before Brut is started up.
   def before_execute
   end
 
+  # Called after all setup has been executed. Brut will have been started/loaded.  This will *not* be called if anything
+  # caused execution to be aborted.
   def after_bootstrap
   end
 
-  def configure!
-  end
-
+  # Executes the command.  Called by {Brut::CLI::AppRunner}.
+  #
+  # @param [Brut::CLI::Command] command the command to run, based on what was on the command line
+  # @param [Pathname] project_root root of the Brut app's project files.
   def execute!(command,project_root:)
     before_execute
     set_env_if_needed

data/lib/brut/cli/app_runner.rb

@@ -1,13 +1,20 @@
 module Brut
   module CLI
+    # Manages the execution of a CLI app that extends {Brut::CLI::App}. Generally you won't use this class directly, but will call
+    # {Brut::CLI.app}.
     class AppRunner
       include Brut::CLI::ExecutionResults
 
+      # Create the app runner with a class and project root
+      #
+      # @param [Class] app_klass The class of your app that extends {Brut::CLI::App}
+      # @param [Pathname] project_root path to the root of the project
       def initialize(app_klass:,project_root:)
         @app_klass    = app_klass
         @project_root = project_root
       end
 
+      # Runs the app, based on the CLI arguments and UNIX environment provided at the time of execution.
       def run!
         app_klass = @app_klass
         out       = Brut::CLI::Output.new(io: $stdout,prefix: "[ #{$0} ] ")
@@ -36,7 +43,7 @@ module Brut
               show_global_help(app_klass:,out:)
             else
               command_option_parser = command_klass.option_parser
-              show_command_help(global_option_parser:,command_option_parser:,command_klass:,out:)
+              show_command_help(global_option_parser:,command_option_parser:,command_klass:,out:,app_klass:)
             end
           end
           return result.to_i
@@ -52,7 +59,11 @@ module Brut
         end
 
         command_argv = remaining_argv[1..-1] || []
-        args = command_option_parser.parse!(command_argv,into:command_options)
+        begin
+          args = command_option_parser.parse!(command_argv,into:command_options)
+        rescue OptionParser::ParseError => ex
+          raise Brut::CLI::InvalidOption.new(ex, context: command_klass)
+        end
 
         cli_app = app_klass.new(global_options:, out:, err:, executor:)
         cmd = command_klass.new(command_options:Brut::CLI::Options.new(command_options),global_options:, args:, out:, err:, executor:)
@@ -133,13 +144,22 @@ module Brut
         option_parser.summarize do |line|
           out.puts_no_prefix line
         end
+        out.puts_no_prefix
+        out.puts_no_prefix "ENVIRONMENT VARIABLES"
+        out.puts_no_prefix
+        max_length = app_klass.env_vars.keys.map(&:length).max
+        printf_string = "    %-#{max_length}s - %s\n"
+        app_klass.env_vars.keys.sort.each do |var_name|
+          out.printf_no_prefix(printf_string,var_name,app_klass.env_vars[var_name])
+        end
+        out.puts_no_prefix
         if app_klass.commands.any?
           out.puts_no_prefix
           out.puts_no_prefix "COMMANDS"
           out.puts_no_prefix
           max_length = [ 4, app_klass.commands.map { |_| _.command_name.to_s.length }.max ].max
           printf_string = "    %-#{max_length}s - %s%s\n"
-          printf printf_string, "help", "Get help on a command",""
+          out.printf_no_prefix printf_string, "help", "Get help on a command",""
           app_klass.commands.sort_by(&:command_name).each  do |command|
             default_message = if command.name_matches?(app_klass.default_command)
                                 " (default)"
@@ -152,13 +172,13 @@ module Brut
                           else
                             command.description
                           end
-            printf printf_string, command.command_name, command.description, default_message
+            out.printf_no_prefix printf_string, command.command_name, command.description, default_message
           end
         end
         out.puts_no_prefix
       end
 
-      def show_command_help(global_option_parser:,command_option_parser:,command_klass:,out:)
+      def show_command_help(global_option_parser:,command_option_parser:,command_klass:,out:,app_klass:)
         banner = command_option_parser.banner % {
           app: $0,
           global_options: global_option_parser.top.list.length == 0 ? "" : "[global options]",
@@ -179,6 +199,16 @@ module Brut
         global_option_parser.summarize do |line|
           out.puts_no_prefix line
         end
+        out.puts_no_prefix
+        out.puts_no_prefix "ENVIRONMENT VARIABLES"
+        out.puts_no_prefix
+        all_vars = app_klass.env_vars.merge(command_klass.env_vars)
+        max_length = all_vars.keys.map(&:length).max
+        printf_string = "    %-#{max_length}s - %s\n"
+        all_vars.keys.sort.each do |var_name|
+          out.printf_no_prefix(printf_string,var_name,all_vars[var_name])
+        end
+        out.puts_no_prefix
         if command_option_parser.top.list.length > 0
           out.puts_no_prefix
           out.puts_no_prefix "COMMAND OPTIONS"
@@ -208,11 +238,14 @@ module Brut
         option_parser.on("--verbose","Set log level to '#{log_levels[0]}', which will produce maximum output") do
           ENV["LOG_LEVEL"] = log_levels[0]
         end
+        app_klass.env_var("LOG_LEVEL",purpose: "log level if --log-level or --verbose is omitted")
 
         hash = {}
         remaining_argv = option_parser.order!(into:hash)
         global_options = Brut::CLI::Options.new(hash)
         [ continue_execution, remaining_argv, global_options, option_parser ]
+      rescue OptionParser::ParseError => ex
+        raise Brut::CLI::InvalidOption.new(ex, context: :global)
       end
     end
   end