brut 0.17.0 → 0.18.0

data/lib/brut/cli/command.rb

@@ -1,258 +0,0 @@
-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
-    else
-      @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?
-        return @detailed_description
-      end
-      return @detailed_description.to_s
-    else
-      @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
-    else
-      @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?
-                        ""
-                      else
-                        " (default '#{default}')"
-                      end
-    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
-    @args            = args
-    @out             = out
-    @err             = err
-    @executor        = executor
-    if self.class.default_env
-      @command_options.set_default(:env,self.class.default_env)
-    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|
-      result = delegate_to_command(command_klass)
-      if !result.ok?
-        err.puts "#{command_klass.command_name} failed"
-        return result
-      end
-    end
-    result
-  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
-    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
-
-  # 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
-
-  # @!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
-
-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/execution_results.rb

@@ -1,119 +0,0 @@
-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
-
-        # @return [true|false] true if execution internal to the command should stop
-        def stop?       = @exit_status != 0
-        # @return [true|false] true if the execution of the command succeeded or didn't error
-        def ok?         = @exit_status == 0
-        # @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
-
-      # @!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:)
-          super()
-          @command_klass = command_klass
-        end
-        def show_usage? = true
-      end
-
-      # @!visibility private
-      class Continue < Result
-        def initialize
-          super(exit_status: 0)
-        end
-      end
-
-      # @!visibility private
-      class Abort < Result
-        def initialize(exit_status:1,message:nil)
-          if exit_status == 0
-            raise ArgumentError,"Do not use Abort for a zero exit status"
-          end
-          super(exit_status:,message:)
-        end
-      end
-      # @!visibility private
-      class CLIUsageError < Abort
-        def initialize(message:)
-          super(message:,exit_status:65)
-        end
-        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)
-        elsif exit_status_or_execution_result == true
-          Result.new(exit_status: 0)
-        elsif exit_status_or_execution_result == false
-          Abort.new
-        elsif exit_status_or_execution_result.kind_of?(Result)
-          exit_status_or_execution_result
-        else
-          raise ArgumentError,"Your method returned a #{exit_status_or_execution_result.class} when it should return an exit status or one of the methods from ExecutionResults"
-        end
-      end
-    end
-  end
-end

data/lib/brut/front_end/layouts/_internal.html.erb

@@ -1,68 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta content="width=device-width,initial-scale=1" name="viewport">
-    <title>BRUT INTERNAL</title>
-    <meta content="website" property="og:type">
-    <%= component(Brut::FrontEnd::Components::PageIdentifier.new(self.page_name)) %>
-  <style>
-html {
-  font-family: system-ui, serif;
-  background: #fefefe;
-  color: #333;
-}
-code {
-  font-family: courier, monospace;
-}
-pre:has(code) {
-  display: inline-block;
-  background: black;
-  color: #88FF88;
-    padding: 0.5rem;
-      border-radius: 0.5rem;
-}
-pre code {
-  border:none;
-  background-color: transparent;
-  padding: 0;
-}
-h1, h2, h3, h4, h5, h6 {
-  line-height: 1.2;
-}
-p {
-  line-height: 1.4;
-  max-width: 60ch;
-}
-.missing-page {
-  padding: 2rem;
-  width: 60ch;
-  margin-left: auto;
-  margin-right: auto;
-  border-radius: 1rem;
-  box-shadow: rgb(106, 106, 106) 2px 3px 6px 0px;
-  background: color-mix(in srgb, red, white 95%);
-  text-align: center;
-}
-.missing-page p { 
-  text-align: left;
-}
-.missing-page h1 {
-  padding: 1rem;
-  border-radius: 1rem;
-  color: red;
-  display: inline-block;
-  background-color: white;
-  margin:0;
-  box-shadow: rgb(180, 180, 180) -1px -1px 5px 1px inset;
-  border: solid thin #ddd;
-}
-.missing-page pre {
-  box-shadow: rgb(106, 106, 106) 2px 3px 6px 0px;
-}
-  </style>
-  </head>
-  <body>
-    <%= yield %>
-  </body>
-</html>

data/lib/brut/front_end/pages/_missing_page.html.erb

@@ -1,17 +0,0 @@
-<main class="missing-page">
-  <h1>Route Not Implemented</h1>
-  <h2>Cannot Find <code><%= class_name %></code></h2>
-  <p>
-    You defined <code><%= path_template %></code> in your app, however the class(es) that impelment it could not be found.
-  </p>
-  <% if scaffold_command %>
-    <p>
-      To create the expected <%= types_of_files_created %>, run this command:
-    </p>
-    <pre><code>bin/scaffold <%= scaffold_command %> <%= class_name %></code></pre>
-  <% else %>
-    <p>
-      Something is wrong - Brut cannot figure out what sort of route you are trying to create. This is probably a bug!
-    </p>
-  <% end %>
-</main>

data/mkbrut/.gitignore

@@ -1,16 +0,0 @@
-# AI droppings
-/.cursor
-# Local gem cache
-/local-gems
-# Forever banned from ringside
-/node_modules
-
-# Local developer credentials - should not be checked in!
-/dx/credentials
-/dx/build.args
-
-# Bundler uses this for locally-built gems.
-/pkg
-
-# From hell’s heart I stab at thee; for hate’s sake I spit my last breath at thee.
-.DS_Store

data/mkbrut/CODE_OF_CONDUCT.txt

@@ -1,100 +0,0 @@
-Contributor Covenant Code of Conduct
-
-Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-Our Standards
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others’ private information, such as a physical or email address,
-without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-professional setting
-
-Enforcement Responsibilities
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-Scope
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-Enforcement
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-abuse@thirdtank.com
-
-All complaints will be reviewed and investigated promptly and fairly.
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-Enforcement Guidelines
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-1. Correction
-Community Impact: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-Consequence: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-2. Warning
-Community Impact: A violation through a single incident or series of
-actions.
-Consequence: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-3. Temporary Ban
-Community Impact: A serious violation of community standards, including
-sustained inappropriate behavior.
-Consequence: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-4. Permanent Ban
-Community Impact: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-Consequence: A permanent ban from any sort of public interaction within the
-community.
-Attribution
-This Code of Conduct is adapted from the Contributor Covenant,
-version 2.1, available at
-https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
-Community Impact Guidelines were inspired by
-Mozilla’s code of conduct enforcement ladder.
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
-

data/mkbrut/Gemfile

@@ -1,3 +0,0 @@
-source "https://rubygems.org"
-
-gemspec

data/mkbrut/Gemfile.lock

@@ -1,20 +0,0 @@
-PATH
-  remote: .
-  specs:
-    mkbrut (0.17.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    rake (13.3.0)
-
-PLATFORMS
-  aarch64-linux
-  ruby
-
-DEPENDENCIES
-  mkbrut!
-  rake
-
-BUNDLED WITH
-   2.7.2