brut 0.17.0 → 0.18.0

data/dx/setupkit.sh.lib

@@ -1,144 +0,0 @@
-# shellcheck shell=bash
-
-fatal() {
-  remainder=${*:2}
-  if [ -z "$remainder" ]; then
-    log "🛑" "${@}"
-  else
-    log "${@}"
-  fi
-  exit 1
-}
-
-log() {
-  emoji=$1
-  remainder=${*:2}
-  if [ -z "${NO_EMOJI}" ]; then
-    echo "[ ${0} ] ${*}"
-  else
-    # if remainder is empty that means no emoji was passed
-    if [ -z "$remainder" ]; then
-      echo "[ ${0} ] ${*}"
-    else # emoji was passed, but we ignore it
-      echo "[ ${0} ] ${remainder}"
-    fi
-  fi
-}
-
-debug() {
-  message=$1
-  if [ -z "${DOCKBOX_DEBUG}" ]; then
-    return
-  fi
-  log "🐛" "${message}"
-}
-
-usage() {
-  description=$1
-  arg_names=$2
-  pre_hook=$3
-  post_hook=$4
-  echo "usage: ${0} [-h] ${arg_names}"
-  if [ -n "${description}" ]; then
-    echo
-    echo "DESCRIPTION"
-    echo "    ${description}"
-  fi
-  if [ -n "${pre_hook}" ] || [ -n "${post_hook}" ]; then
-    echo
-    echo "HOOKS"
-    if [ -n "${pre_hook}" ]; then
-      echo "    ${pre_hook} - if present, called before the main action"
-    fi
-    if [ -n "${post_hook}" ]; then
-      echo "    ${post_hook} - if present, called after the main action"
-    fi
-  fi
-  exit 0
-}
-
-usage_on_help() {
-  description=$1
-  arg_names=$2
-  pre_hook=$3
-  post_hook=$4
-  # These are the args passed to the invocation so this
-  # function can determine if the user requested help
-  cli_args=( "${@:5}" ) 
-
-  for arg in "${cli_args[@]}"; do
-    if [ "${arg}" = "-h" ] || [ "${arg}" = "--help" ]; then
-      usage "${description}" "${arg_names}" "${pre_hook}" "${post_hook}"
-    fi
-  done
-}
-
-# Read user input into the variable 'INPUT'
-#
-# Args:
-#
-# [1] - an emoji to use for messages
-# [2] - the message explaining what input is being requested
-# [3] - a default value to use if no value is provided
-#
-# Respects NO_EMOJI when outputing messages to the user
-user_input() {
-  emoji=$1
-  message=$2
-  default=$3
-  prompt=$4
-
-  if [ -z "$message" ]; then
-    echo "user_input requires a message"
-    exit 1
-  fi
-
-  INPUT=
-
-  if [ -z "${prompt}" ]; then
-    prompt=$(log "${emoji}" "Value: ")
-    if [ -n "${default}" ]; then
-      prompt=$(log "${emoji}" "Value (or hit return to use '${default}'): ")
-    fi
-  fi
-
-  while [ -z "${INPUT}" ]; do
-
-    log "$emoji" "$message"
-    read -r -p "${prompt}" INPUT
-    if [ -z "$INPUT" ]; then
-      INPUT=$default
-    fi
-    if [ -z "$INPUT" ]; then
-      log "😶", "You must provide a value"
-    fi
-  done
-}
-
-user_confirm() {
-  user_input "$1" "$2" "$3" "y/n> "
-}
-
-require_not_exist() {
-  file=$1
-  message=$2
-  if [ -e "${file}" ]; then
-    fatal "$message"
-  fi
-}
-require_exist() {
-  file=$1
-  message=$2
-  if [ ! -e "${file}" ]; then
-    fatal "$message"
-  fi
-}
-
-require_command() {
-  command_name=$1
-  if ! command -v "${command_name}" >/dev/null 2>&1; then
-    fatal "Command '${command_name}' not found - it is required for this script to run"
-  fi
-}
-
-# vim: ft=bash

data/dx/show-help-in-app-container-then-wait.sh

@@ -1,38 +0,0 @@
-#!/bin/bash
-
-set -e
-
-# Ideally, the message below is shown after everything starts up. We can't
-# achieve this using healtchecks because the interval for a healtcheck is
-# also an initial delay, and we don't really want to do healthchecks on 
-# our DB or Redis every 2 seconds.  So, we sleep just a bit to let
-# the other containers start up and vomit out their output first.
-sleep 2
-# Output some helpful messaging when invoking `dx/start` (which itself is
-# a convenience script for `docker compose up`.
-#
-# Adding this to work around the mild inconvenience of the `app` container's
-# entrypoint generating no output.
-#
-cat <<-'PROMPT'
-
-
-
- 🎉  Dev Environment Initialized! 🎉
-
- ℹ️   To use this environment, open a new terminal and run
-
-     dx/exec bash
-
- 🕹  Use `ctrl-c` to exit.
-
-
-
-PROMPT
-
-# Using `sleep infinity` instead of `tail -f /dev/null`. This may be a 
-# performance improvement based on the conversation on a semi-related
-# StackOverflow page.
-#
-# @see https://stackoverflow.com/a/41655546
-sleep infinity

data/lib/brut/cli/app.rb

@@ -1,238 +0,0 @@
-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)
-    }.select { |constant|
-      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
-    else
-      @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.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?
-                        ""
-                      else
-                        " (default '#{default}')"
-                      end
-    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
-    @err            = err
-    @executor       = executor
-    if self.class.default_env
-      @global_options.set_default(:env,self.class.default_env)
-    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"
-    end
-    env = ENV["RACK_ENV"]
-    if env != "production"
-      require "dotenv"
-      Dotenv.load(project_root / ".env.#{env}",
-                  project_root / ".env.#{env}.local")
-
-    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.
-  #
-  # @param [Brut::Framework::App] app Your Brut app.
-  def after_bootstrap(app:)
-  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
-    command.set_env_if_needed
-    load_env(project_root:)
-    command.before_execute
-    app = nil
-    bootstrap_result = begin
-                         require "#{project_root}/app/bootstrap"
-                         bootstrap = Bootstrap.new
-                         if self.class.configure_only?
-                           bootstrap.configure_only!
-                         else
-                           bootstrap.bootstrap!
-                         end
-                         app = bootstrap.app
-                         continue_execution
-                       rescue => ex
-                         as_execution_result(command.handle_bootstrap_exception(ex))
-                       end
-    if bootstrap_result.stop?
-      return bootstrap_result
-    end
-    after_bootstrap(app:)
-    command.after_bootstrap(app:)
-    if self.class.configure_only?
-      as_execution_result(command.execute)
-    else
-      result = Brut.container.instrumentation.span("CLI #{$0}", prefix: "brut.cli", class: self.class.name) do |span|
-        as_execution_result(command.execute)
-      end
-      result
-    end
-  rescue Brut::CLI::Error => ex
-    abort_execution(ex.message)
-  end
-
-private
-
-  def options = @global_options
-  def out = @out
-  def err = @err
-  def puts(...)
-    warn("Your CLI apps should use out.puts or err.puts or produce terminal output, not plain puts", uplevel: 1)
-    Kernel.puts(...)
-  end
-
-end

data/lib/brut/cli/app_runner.rb

@@ -1,252 +0,0 @@
-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} ] ")
-        err       = Brut::CLI::Output.new(io: $stderr,prefix: "[ #{$0} ] ")
-        executor  = Brut::CLI::Executor.new(out:,err:)
-
-        result,remaining_argv,global_options,global_option_parser = parse_global(app_klass:,out:)
-
-        if result.stop?
-          return result.to_i
-        end
-
-        result,command_klass = locate_command(remaining_argv:,app_klass:,err:,out:)
-
-        if result.stop?
-          if !result.ok?
-            err.puts_no_prefix "error: #{result.message}"
-            err.puts_no_prefix
-            if result.show_usage?
-              show_global_help(app_klass:,out:)
-              err.puts_no_prefix "error: #{result.message}"
-            end
-          elsif result.show_usage?
-            command_klass = result.command_klass
-            if command_klass.nil?
-              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:,app_klass:)
-            end
-          end
-          return result.to_i
-        end
-
-        command_options = {}
-
-        command_option_parser = command_klass.option_parser
-
-        command_option_parser.on("-h", "--help", "Get help on this command") do
-          show_command_help(global_option_parser:,command_option_parser:,command_klass:,out:,app_klass:)
-          return 0
-        end
-
-        command_argv = remaining_argv[1..-1] || []
-        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:)
-
-        result = cli_app.execute!(cmd, project_root:@project_root)
-
-        if result.message
-          if !result.ok?
-            err.puts "error: #{result.message}"
-            if result.show_usage?
-              err.puts
-              show_command_help(global_option_parser:,command_option_parser:,command_klass:,out:)
-            end
-          else
-            out.puts result.message
-          end
-        end
-        result.to_i
-      rescue OptionParser::InvalidArgument => ex
-        flag = ex.args.map { |_| _.gsub(/=.*$/,"") }.join(", ")
-        err.puts "error: #{ex.reason} from #{flag}: value given is not one of the allowed values"
-        65
-      rescue OptionParser::ParseError => ex
-        err.puts "error: #{ex.message}"
-        65
-      rescue => ex
-        if ENV["BRUT_CLI_RAISE_ON_ERROR"] == "true"
-          raise
-        else
-          err.puts "error: #{ex.message}"
-          70
-        end
-      end
-
-    private
-
-      def locate_command(remaining_argv:,app_klass:,err:,out:)
-
-        command_name = remaining_argv[0] || app_klass.default_command
-
-        if !command_name
-          return cli_usage_error("#{$0} requires a command")
-        end
-
-        if command_name == "help"
-          command_needing_help = remaining_argv[1]
-          if command_needing_help
-            command_klass = app_klass.commands.detect { |c| c.name_matches?(remaining_argv[1]) }
-            if command_klass
-              return show_cli_usage(command_klass)
-            end
-            return cli_usage_error("No such command '#{command_needing_help}'")
-          end
-          return show_cli_usage
-        end
-
-        command_klass = app_klass.commands.detect { |c| c.name_matches?(command_name) }
-
-        if !command_klass
-          return cli_usage_error("#{command_name} is not a known command")
-        end
-        [ continue_execution, command_klass ]
-      end
-
-
-      def show_global_help(app_klass:,out:)
-        option_parser = app_klass.option_parser
-        option_parser.banner =  option_parser.banner % {
-          app: $0,
-          global_options: option_parser.top.list.length == 0 ? "" : "[global options]",
-        }
-        out.puts_no_prefix option_parser.banner
-        out.puts_no_prefix
-        out.puts_no_prefix "   #{app_klass.description}"
-        out.puts_no_prefix
-        out.puts_no_prefix "GLOBAL OPTIONS"
-        out.puts_no_prefix
-        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"
-          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)"
-                              else
-                                ""
-                              end
-
-            description = if command.description && command.description.kind_of?(Proc)
-                            command.description.()
-                          else
-                            command.description
-                          end
-            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:,app_klass:)
-        banner = command_option_parser.banner % {
-          app: $0,
-          global_options: global_option_parser.top.list.length == 0 ? "" : "[global options]",
-          command_options: command_option_parser.top.list.length == 0 ? "" : "[command options]",
-          args: command_klass.args,
-        }
-        command_option_parser.banner = "Usage: #{banner}"
-        out.puts_no_prefix command_option_parser.banner
-        out.puts_no_prefix
-        out.puts_no_prefix "    " + command_klass.description
-        out.puts_no_prefix
-        if command_klass.detailed_description
-          out.puts_no_prefix "    " + command_klass.detailed_description.strip
-          out.puts_no_prefix
-        end
-        out.puts_no_prefix "GLOBAL OPTIONS"
-        out.puts_no_prefix
-        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"
-          if command_option_parser.summarize.any?
-            out.puts_no_prefix
-          end
-          command_option_parser.summarize do |line|
-            out.puts_no_prefix line
-          end
-        end
-      end
-
-      def parse_global(app_klass:,out:)
-        option_parser = app_klass.option_parser
-
-        option_parser.on("-h", "--help", "Get help") do
-          show_global_help(app_klass:,out:)
-          return stop_execution
-        end
-        log_levels = [ "debug", "info", "warn", "error", "fatal" ]
-        if ENV["LOG_LEVEL"].to_s == ""
-          ENV["LOG_LEVEL"] = log_levels[-1]
-        end
-        option_parser.on("--log-level=LEVEL","Set log level. Allowed values: #{log_levels.join(', ')}. Default '#{ENV["LOG_LEVEL"]}'",log_levels) do |value|
-          ENV["LOG_LEVEL"] = value
-        end
-        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
-end