brut 0.19.2 → 0.20.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 765659b6fbd1258a4b5615cfea8e7d273fbebd4336ceb6518367bc5ad329bcb8
-  data.tar.gz: 35777088ab7cc473a3ef5459087349846586798154e9f699e52b3b5be22c64db
+  metadata.gz: de61901270558680112b8b90f787067add7f777204219016020adcc90c15564d
+  data.tar.gz: 4437fee31bc132bd93fe419ac72df5bc1b1e7bb67f506a4e36ab126dc7395b85
 SHA512:
-  metadata.gz: 946899aa325e088a414c88e63b6bd58c7278380e90929f886905b9cd100c2a98d672d570a036e0edf66953719dccb4b6bd1dd5525f885fcc2421ea82da142ece
-  data.tar.gz: 9bfe8cef4bd6e4effbca418ab446796fed352999f21b404d6904ec5ccd048bff9ed18de6f9fd47e8d45ad7045b73bf782375ca7bed13a1022d2af0e1e976bde5
+  metadata.gz: fcc0ef80b40ea5703298cdbaa71f86f3ec8d22b96f8bc4e9cea336f41b09bbca109b211eea365b202759f8bca4c07ace5c35d2a6f638a7d2231f5d0534090556
+  data.tar.gz: c4bb547d99089ca6d567e744c39539fda20ff85b21c45dd2419ab7d0bcfc0e265a9004006973e7bb4f96be35f41d21354efd71502f77e2276140dbd8badf29a3

data/lib/brut/cli/apps/build_assets.rb

@@ -91,9 +91,9 @@ This is to ensure that any images your code references will end up in the public
     def description = "Builds a single CSS file suitable for sending to the browser"
 
     def detailed_description = %{
-      This produces a hashed file in every environment, in order to keep environments consistent and reduce differences.  If your CSS file references images, fonts, or other assets via url() or other CSS functions, those files will be hashed and copied into the output directory where CSS is served.
+      This produces a hashed file in every environment, in order to keep environments consistent and reduce differences.  If your CSS file references images, fonts, or other assets via `url()` or other CSS functions, those files will be hashed and copied into the output directory where CSS is served.
 
-      To ensure this happens correctly, your url() or other function must reference the file as a relative file from where your actual source CSS file is located. For example, a font named some-font.ttf would be in app/src/front_end/fonts and to reference this from app/src/front_end/css/index.css you'd use the url "../fonts/some-font.ttf"
+      To ensure this happens correctly, your `url()` or other function must reference the file as a relative file from where your actual source CSS file is located. For example, a font named `some-font.ttf` would be in `app/src/front_end/fonts`. To reference this from `app/src/front_end/css/index.css` you'd use `url("../fonts/some-font.ttf")`
     }
 
     def run

data/lib/brut/cli/apps/db.rb

@@ -51,20 +51,20 @@ class Brut::CLI::Apps::DB < Brut::CLI::Commands::BaseCommand
       rows = [
         [
           "Database Server",
-          server_up ? theme.success.render("✅ UP") : theme.error.render("❌ DOWN")
+          server_up ? theme.success.render("✅ UP") : theme.error.render("❌ DOWN"),
         ],
       ]
       if server_up
         rows << [
           "Database #{theme.code.render(database_name)}",
-          database_exists ? theme.success.render("✅ Exists") : theme.error.render("❌ DOES NOT EXIST")
+          database_exists ? theme.success.render("✅ Exists") : theme.error.render("❌ DOES NOT EXIST"),
         ]
       end
       if database_exists
         if migration_files.empty? && migrations_run.empty?
           rows << [
             "Migrations",
-            "✅ NO MIGRATION FILES TO RUN"
+            "✅ NO MIGRATION FILES TO RUN",
           ]
         else
           migration_files.each do |filename|

data/lib/brut/cli/apps/deploy.rb

@@ -19,8 +19,16 @@ class Brut::CLI::Apps::Deploy < Brut::CLI::Commands::BaseCommand
     def default_rack_env = "development"
 
     def run
+      options.set_default(:deploy, true)
+      puts "Logging in to Heroku Container Registry"
+      command = %{heroku container:login}
+      system!(command)
       execute_result = Brut::CLI::ExecuteResult.new do
-        delegate_to_command(Brut::CLI::Apps::Deploy::Build.new)
+        delegate_to_command(
+          Brut::CLI::Apps::Deploy::Build.new(
+            push: options.deploy? ? "registry.heroku.com/#{Brut.container.app_id}/%{name}": false
+          )
+        )
       end
       if execute_result.failed?
         puts theme.error.render("Build failed.")
@@ -28,47 +36,17 @@ class Brut::CLI::Apps::Deploy < Brut::CLI::Commands::BaseCommand
           puts theme.error.render("Error message from build: #{error_message}")
         end
       end
-      options.set_default(:deploy, true)
-      version = ""
-      git_guess = %{git rev-parse HEAD}
-      system!(git_guess) do |output|
-        version << output
-      end
-      version.strip!.chomp!
-      if version == ""
-        error "Attempt to use git via command '#{git_guess}' to figure out the version failed"
-        return 1
-      end
-      short_version = version[0..7]
+      names = []
       app_docker_files = AppDockerImages.new(
         project_root: Brut.container.project_root,
         organization: Brut.container.app_organization,
         app_id: Brut.container.app_id,
-        short_version:
+        short_version: "NA"
       )
-      names = []
-      puts "Logging in to Heroku Container Registry"
-      command = %{heroku container:login}
-      system!(command)
-      app_docker_files.each do |name:, image_name:|
-        heroku_image_name = "registry.heroku.com/#{Brut.container.app_id}/#{name}"
-        puts "Tagging '#{image_name}' with '#{heroku_image_name}' for Heroku"
-        command = %{docker tag #{image_name} #{heroku_image_name}}
-        system!(command)
-        begin
-          puts "Pushing '#{heroku_image_name}'"
-          command = %{docker push #{heroku_image_name}}
-          system!(command)
-        rescue Brut::CLI::SystemExecError => ex
-          error "Failed to push image '#{heroku_image_name}' to Heroku"
-          if options.log_level != "debug"
-            error "Could be you must re-authenticate to Heroku."
-            error "Try re-running with --log-level=debug to see more details"
-          end
-          return 1
-        end
+      app_docker_files.each do |name:, cmd:, dockerfile:|
         names << name
       end
+
       deploy_command = "heroku container:release #{names.join(' ')} -a #{Brut.container.app_id}"
       if options.deploy?
         puts "Deploying images to Heroku"
@@ -142,7 +120,13 @@ class Brut::CLI::Apps::Deploy < Brut::CLI::Commands::BaseCommand
     def description      = Docker.new.description
     def opts             = Docker.new.opts
     def default_rack_env = Docker.new.default_rack_env
-    def run              = delegate_to_command(Docker.new)
+
+    def initialize(push: false)
+      @push = push
+    end
+    def run
+      delegate_to_command(Docker.new(push: @push))
+    end
 
     def commands = []
 
@@ -155,6 +139,10 @@ class Brut::CLI::Apps::Deploy < Brut::CLI::Commands::BaseCommand
       ]
       def default_rack_env = "development"
 
+      def initialize(push: false)
+        @push = push
+      end
+
       def run
         if !options.skip_checks?
           execute_result = Brut::CLI::ExecuteResult.new do
@@ -177,8 +165,6 @@ class Brut::CLI::Apps::Deploy < Brut::CLI::Commands::BaseCommand
           error "Attempt to use git via command '#{git_guess}' to figure out the version failed"
           return 1
         end
-        short_version = version[0..7]
-
         short_version = version[0..7]
         app_docker_files = AppDockerImages.new(
           project_root: Brut.container.project_root,
@@ -219,12 +205,16 @@ class Brut::CLI::Apps::Deploy < Brut::CLI::Commands::BaseCommand
           puts
           rows = []
           items = []
+          push_or_load = @push ? "--push" : "--load"
           app_docker_files.each do |name:, image_name:, dockerfile:|
+            if @push && @push.kind_of?(String)
+              image_name = @push % { name: name }
+            end
             rows << [ name, theme.code.render(image_name) ]
-            command = %{docker build --build-arg app_git_sha1=#{version} --file #{Brut.container.project_root}/#{dockerfile} --platform #{options.platform} --tag #{image_name} . 2>&1}
+            command = %{docker buildx build --provenance=false --build-arg app_git_sha1=#{version} --file #{Brut.container.project_root}/#{dockerfile} --platform #{options.platform} #{push_or_load} --tag #{image_name} . 2>&1}
             items << theme.code.render(theme.wrap(command, first_indent: false, indent: 7, newline: " \\\n"))
             if !options.dry_run?
-              puts theme.subheader.render("Building '#{name}' image")
+              puts theme.subheader.render("Building #{@push ? 'and pushing' : '' } '#{name}' image")
               system!(command)
             end
           end

data/lib/brut/cli/apps/new/app.rb

@@ -53,12 +53,12 @@ class Brut::CLI::Apps::New::App < Brut::CLI::Commands::BaseCommand
     [ 
       "--app-id=ID",
       Brut::CLI::Apps::New::AppId,
-      "App identifier, which must be able to be used as a hostname or other Internet identifier. Derived from your app name, if omitted"
+      "App identifier, which must be able to be used as a hostname or other Internet identifier. Derived from your app name, if omitted",
     ],
     [
       "--organization=ORG",
       Brut::CLI::Apps::New::Organization,
-      "Organization name, e.g. what you'd use for GitHub. Defaults to the app-id value"
+      "Organization name, e.g. what you'd use for GitHub. Defaults to the app-id value",
     ],
     [
       "--[no-]interactive",
@@ -67,7 +67,7 @@ class Brut::CLI::Apps::New::App < Brut::CLI::Commands::BaseCommand
     [
       "--prefix=PREFIX",
       Brut::CLI::Apps::New::Prefix,
-      "Two-character prefix for external IDs and autonomous custom elements. Derived from your app-id, if omitted."
+      "Two-character prefix for external IDs and autonomous custom elements. Derived from your app-id, if omitted.",
     ],
     [ 
       "--segments=SEGMENTS",
@@ -76,11 +76,11 @@ class Brut::CLI::Apps::New::App < Brut::CLI::Commands::BaseCommand
     ],
     [ 
       "--dry-run",
-      "Only show what would happen, don't actually do anything"
+      "Only show what would happen, don't actually do anything",
     ],
     [
       "--[no-]demo",
-      "Include, or not, additional files that demonstrate Brut's features (default is true for now)"
+      "Include, or not, additional files that demonstrate Brut's features (default is true for now)",
     ],
   ]
 
@@ -272,7 +272,7 @@ class Brut::CLI::Apps::New::App < Brut::CLI::Commands::BaseCommand
       ],
       [ 
         "--dry-run",
-        "Only show what would happen, don't actually do anything"
+        "Only show what would happen, don't actually do anything",
       ],
     ]
 
@@ -319,7 +319,7 @@ class Brut::CLI::Apps::New::App < Brut::CLI::Commands::BaseCommand
 
       puts "Adding #{segment_name} to this app"
       segment.add!
-      segment.output_post_add_messaging(stdout:)
+      segment.output_post_add_messaging(stdout: execution_context.stdout)
       0
     end
   end

data/lib/brut/cli/apps/new/ops/insert_code_in_method.rb

@@ -19,6 +19,11 @@ class Brut::CLI::Apps::New::Ops::InsertCodeInMethod < Brut::CLI::Apps::New::Ops:
     if !@file.exist? && @ignore_if_file_not_found
       return
     end
+    if dry_run?
+      op = @class_method ? "::" : "#"
+      puts "Would add this code to #{@class_name}#{op}#{@method_name} in #{@file}:\n\n#{@code}\n\n"
+      return
+    end
     method_node = find_method(class_name: @class_name, method_name: @method_name, class_method: @class_method)
 
     insertion_point = if @where == :start

data/lib/brut/cli/apps/new/segments/heroku.rb

@@ -16,9 +16,6 @@ class Brut::CLI::Apps::New::Segments::Heroku < Brut::CLI::Apps::New::Base
     end
   end
 
-  def output_post_add_messaging(stdout:)
-  end
-
   def <=>(other)
     if self.class == other.class
       0

data/lib/brut/cli/apps/new/segments/sidekiq.rb

@@ -75,6 +75,10 @@ class Brut::CLI::Apps::New::Segments::Sidekiq < Brut::CLI::Apps::New::Base
         file: @project_root / "Gemfile",
         content: "# Sidekiq is used for background jobs\ngem \"sidekiq\"\n"
       ),
+      Brut::CLI::Apps::New::Ops::AppendToFile.new(
+        file: @project_root / "Gemfile",
+        content: "# Sets up OTel middelware for Sidekiq \ngem \"opentelemetry-instrumentation-sidekiq\"\n"
+      ),
       Brut::CLI::Apps::New::Ops::AppendToFile.new(
         file: @project_root / ".env.development",
         content: %{
@@ -110,7 +114,7 @@ SIDEKIQ_BASIC_AUTH_PASSWORD=password
       Brut::CLI::Apps::New::Ops::InsertIntoFile.new(
         file: @project_root / "specs" / "spec_helper.rb",
         before_line: "require \"brut/spec_support\"",
-        content: "require \"sidekiq/testing\""
+        content: "Sidekiq.testing!(:fake)"
       ),
       Brut::CLI::Apps::New::Ops::InsertIntoFile.new(
         file: @project_root / "config.ru",
@@ -142,10 +146,9 @@ SIDEKIQ_BASIC_AUTH_PASSWORD=password
         code: "@sidekiq_segment.boot!"
       ),
       Brut::CLI::Apps::New::Ops::InsertCodeInMethod.new(
-        file: project_root / "deploy" / "heroku_config.rb",
+        file: project_root / "deploy" / "docker_config.rb",
         class_name: "HerokuConfig",
         method_name: "additional_images",
-        class_method: true,
         ignore_if_file_not_found: true,
         code: %{
 {

data/lib/brut/cli/apps/scaffold.rb

@@ -4,6 +4,10 @@ require "brut/cli"
 class Brut::CLI::Apps::Scaffold < Brut::CLI::Commands::BaseCommand
   def description = "Create scaffolds of various files to help develop more quckly"
 
+  def commands
+    super - [ Brut::CLI::Apps::Scaffold::BaseCommand ]
+  end
+
   class BaseCommand < Brut::CLI::Commands::BaseCommand
     def bootstrap? = false
     def default_rack_env = "development"
@@ -111,7 +115,7 @@ end}
     def args_description = "test_name"
     def name = "e2e_test"
 
-    def opts = [
+    def opts = super + [
       ["--path PATH","Path within the e2e tests to create the file"],
     ]
 
@@ -193,7 +197,7 @@ end}
     def args_description = "ComponentName"
     def detailed_description = "New components go in the `components/` folder of your app, however using --page will create a 'page private' component.  To do that, the component name must be an inner class of an existing page, for example HomePage::Welcome. This component goes in a sub-folder inside the `pages/` area of your app"
 
-    def opts = [
+    def opts = super + [
       [ "--page","If set, this component is for a specific page and won't go with the other components"],
     ]
 
@@ -384,7 +388,7 @@ end}
           error "         The page may not render properly the first time you load it"
         end
 
-        routes_editor = RoutesEditor.new(app_path:,out:)
+        routes_editor = RoutesEditor.new(app_path:,stdout: execution_context.stdout)
         routes_editor.add_route!(route_code:)
 
         if !routes_editor.found_routes?
@@ -419,7 +423,7 @@ end}
     end
     def description = "Create a handler for an action"
     def args_description = "action_route"
-    def opts = [
+    def opts = super + [
       [ "--http-method=METHOD", "If present, the action will be a path available on the given route and this HTTP method. If omitted, this will create an action available via POST" ],
     ]
 
@@ -528,7 +532,7 @@ end}
         execution_context.stdout.printf printf_string,handler_class_name, handler_source_path.relative_path_from(Brut.container.project_root)
         execution_context.stdout.printf printf_string,"Spec", handler_spec_path.relative_path_from(Brut.container.project_root)
 
-        routes_editor = RoutesEditor.new(app_path:,out:)
+        routes_editor = RoutesEditor.new(app_path:,stdout: execution_context.stdout)
         routes_editor.add_route!(route_code:)
 
         if form
@@ -633,7 +637,8 @@ describe("#{description}", () => {
 
     def run
       if argv.length == 0
-        return abort_execution("You must provide a model name")
+        puts "You must provide one or more model names"
+        return 1
       end
       db_module = ModuleName.from_string("DB")
       actions = argv.map { |arg|
@@ -703,9 +708,9 @@ end
   end
 
   class RoutesEditor
-    def initialize(app_path:,out:)
+    def initialize(app_path:,stdout:)
       @app_path       = app_path
-      @out            = out
+      @stdout         = stdout
       @found_routes   = false
       @routes_existed = false
     end
@@ -726,7 +731,7 @@ end
           end
           if in_routes && line =~ /^  end\s*$/
             if !@routes_existed
-              @out.puts "Inserted route into #{@app_path.relative_path_from(Brut.container.project_root)}"
+              @stdout.puts "Inserted route into #{@app_path.relative_path_from(Brut.container.project_root)}"
               file.puts "    #{route_code}"
             end
             @found_routes = true

data/lib/brut/cli/apps/test.rb

@@ -90,6 +90,7 @@ Runs all non end-to-end tests for the app, or runs a subset of non-end-to-end te
       [ "E2E_RECORD_VIDEOS","If set to 'true', videos of each test run are saved in `./tmp/e2e-videos`" ],
       [ "E2E_SLOW_MO","If set to, will attempt to slow operations down by this many milliseconds" ],
       [ "E2E_TIMEOUT_MS","ms to wait for any browser activity before failing the test. And here you didn't think you'd get away without using sleep in browse-based tests?" ],
+      [ "E2E_STARTUP_TIMEOUT_SEC","seconds to wait for the test server to start before assuming something went wrong" ],
     ]
 
     def rspec_cli_args = "--tag e2e"
@@ -102,11 +103,17 @@ Runs all end-to-end tests for the app, or runs a subset of end-to-end tests usin
   private
 
     def run_tests
-      require "brut/spec_support/e2e_test_server"
-      Brut::SpecSupport::E2ETestServer.instance.start
-      super
-    ensure
-      Brut::SpecSupport::E2ETestServer.instance.stop
+      test_server = Brut::SpecSupport::E2ETestServer.new(
+        bin_dir: Brut.container.project_root / "bin",
+        start_timeout_seconds: ENV["E2E_STARTUP_TIMEOUT_SEC"]
+      )
+      begin
+        require "brut/spec_support/e2e_test_server"
+        test_server.start
+        super
+      ensure
+        test_server.stop
+      end
     end
   end
   class Js < Brut::CLI::Commands::BaseCommand

data/lib/brut/cli/commands/help_in_markdown.rb

@@ -0,0 +1,109 @@
+class Brut::CLI::Commands::HelpInMarkdown < Brut::CLI::Commands::BaseCommand
+  def description = "Get help for the app or a command, in Markdown"
+  attr_accessor :option_parser
+
+  def initialize(command,option_parser)
+    @command = command
+    @option_parser = option_parser
+  end
+
+  def commands = []
+
+  def run
+    if env["BRUT_HELP_IN_MARKDOWN_COMMANDS_ONLY"]
+      @command.commands.sort_by(&:name).each do |command|
+        puts command.name
+      end
+      return 0
+    end
+    cli = [@command.name ]
+    cmd = @command
+    while cmd.parent_command
+      cmd = cmd.parent_command
+      cli.unshift cmd.name
+    end
+    invocation = cli.join(" ")
+    puts "# `#{invocation}`"
+    puts
+    puts @command.description
+    puts
+
+    usage = invocation
+
+    options = @option_parser.top.list
+    if options.size > 0
+      usage << theme.weak.render(" [options]")
+    end
+    if @command.commands.any?
+      usage << theme.code.render(" command")
+    end
+    if @command.args_description
+      usage << " #{@command.args_description}"
+    end
+    puts
+    puts "## USAGE"
+    puts
+    puts "    " + usage
+    puts
+    if @command.detailed_description
+      puts
+      puts "## DESCRIPTION"
+      puts
+      puts @command.detailed_description.gsub(/ +/," ").strip
+      puts
+    end
+    if options.size > 0
+      puts
+      puts "## OPTIONS"
+      puts
+
+      options.each do |option|
+        switches = option.long.map { |switch|
+          if option.arg
+            if option.arg[0] == "="
+              "#{switch.strip}#{theme.weak.render(option.arg.strip)}"
+            else
+              "#{switch.strip}=#{theme.weak.render(option.arg.strip)}"
+            end
+          else
+            switch
+          end
+        } + option.short.map { |switch|
+          if option.arg
+            "#{switch} #{theme.weak.render(option.arg)}"
+          else
+            switch
+          end
+        }
+        puts "* `#{switches.join(", ")}` - #{option.desc.join(" ")}"
+      end
+    end
+    if @command.env_vars.any?
+      puts
+      puts "## ENVIRONMENT VARIABLES"
+      puts
+      @command.env_vars.sort_by(&:first).each do |env_var|
+        puts "* `#{env_var[0]}` -  #{env_var[1]}"
+      end
+    end
+    if @command.commands.any?
+      commands_subpath = env["BRUT_HELP_IN_MARKDOWN_COMMAND_PATH"] || "commands"
+      puts
+      puts "## COMMANDS"
+      puts
+      @command.commands.sort_by(&:name).each do |command|
+        puts "### [`#{command.name}`](./#{commands_subpath}/#{command.name})"
+        puts
+        puts "#{command.description}"
+        if command.detailed_description
+          puts
+          puts command.detailed_description.gsub(/ +/," ").strip
+        end
+      end
+    end
+    0
+  end
+
+  def bootstrap? = false
+  def default_rack_env = nil
+end

data/lib/brut/cli/commands.rb

@@ -2,6 +2,7 @@ module Brut::CLI::Commands
   autoload(:BaseCommand, "brut/cli/commands/base_command")
   autoload(:CompoundCommand, "brut/cli/commands/compound_command")
   autoload(:Help, "brut/cli/commands/help")
+  autoload(:HelpInMarkdown, "brut/cli/commands/help_in_markdown")
   autoload(:OutputError, "brut/cli/commands/output_error")
   autoload(:RaiseError, "brut/cli/commands/raise_error")
   autoload(:ExecutionContext, "brut/cli/commands/execution_context")

data/lib/brut/cli/logger.rb

@@ -1,5 +1,6 @@
 require "logger"
 require "fileutils"
+require "pathname"
 require "delegate"
 
 class Brut::CLI::Logger < SimpleDelegator
@@ -58,9 +59,9 @@ class Brut::CLI::Logger < SimpleDelegator
   end
 
   def log_file=(log_file)
-    @log_file = log_file
     if log_file
-      log_dir = log_file.dirname
+      @log_file = Pathname(log_file)
+      log_dir = @log_file.dirname
       if !log_dir.exist?
         FileUtils.mkdir_p(log_dir)
       end
@@ -69,6 +70,8 @@ class Brut::CLI::Logger < SimpleDelegator
       if @logger.level == ::Logger::DEBUG
         @stdout.puts "Logging to file #{@log_file}"
       end
+    else
+      @log_file = nil
     end
   end
 

data/lib/brut/cli/parsed_command_line.rb

@@ -30,6 +30,11 @@ class Brut::CLI::ParsedCommandLine
   # This should always succeed, however depending on the contents of the parameters, the value
   # for `#command` may be a command that outputs an error.
   def initialize(app_command:, argv:, env:)
+    help_command_class = if env["BRUT_HELP_IN_MARKDOWN"] == "true"
+                           Brut::CLI::Commands::HelpInMarkdown
+                         else
+                           Brut::CLI::Commands::Help
+                         end
     brut_provided_help_requested = false
     app_option_parser = new_option_parser(app_command.name) do |opts|
       opts.banner = app_command.description
@@ -51,7 +56,7 @@ class Brut::CLI::ParsedCommandLine
     end
 
     help_command = if brut_provided_help_requested
-                     Brut::CLI::Commands::Help.new(app_command,app_option_parser)
+                     help_command_class.new(app_command,app_option_parser)
                    end
 
     command = app_command
@@ -83,7 +88,7 @@ class Brut::CLI::ParsedCommandLine
       end
       remaining_argv = command_option_parser.parse!(remaining_argv, into: options)
       if brut_provided_help_requested
-        help_command = Brut::CLI::Commands::Help.new(command,command_option_parser)
+        help_command = help_command_class.new(command,command_option_parser)
       elsif help_command
         help_command.option_parser = command_option_parser
       end
@@ -112,12 +117,16 @@ class Brut::CLI::ParsedCommandLine
     if !@options[:'log-file']
       log_file_path = if env["XDG_STATE_HOME"]
                         Pathname(env["XDG_STATE_HOME"]) / "brut"
-                      elsif env["HOME"]
+                      elsif env["HOME"] && File.writable?(env["HOME"])
                         Pathname("#{env['HOME']}/.local/state/") / "brut"
                       else
-                        Pathname("/tmp/") / "brut"
+                        nil
                       end
-      @options[:'log-file'] = log_file_path / (app_command.name + ".log")
+      if log_file_path
+        @options[:'log-file'] = log_file_path / (app_command.name + ".log")
+      end
+    else
+      @options[:'log-file'] = Pathname(@options[:'log-file'])
     end
     if @options[:'log-stdout'].nil?
       @options[:'log-stdout'] = @options.verbose? || @options.debug?
@@ -143,8 +152,7 @@ private
               "Project environment, e.g. test, development, production. Default depends on the command")
       opts.on("--log-level=LOG_LEVEL", [ "debug", "info", "warn", "error", "fatal" ],
               "Log level, which should be debug, info, warn, error, or fatal. Defaults to error")
-      opts.on("--verbose", "Set log level to debug, and show log messages on stdout")
-      opts.on("--debug", "Set log level to debug, and show log messages on stdout")
+      opts.on("--debug", "--verbose", "Set log level to debug, and show log messages on stdout")
       opts.on("--quiet", "Set log level to error")
       opts.on("--log-file=FILE",
               "Path to a file where log messages are written. Defaults to $XDG_CACHE_HOME/brut/logs/#{app_name}.log")

data/lib/brut/framework/mcp.rb

@@ -439,6 +439,7 @@ private
       if defined?(OpenTelemetry::Instrumentation::Sidekiq)
         c.use 'OpenTelemetry::Instrumentation::Sidekiq', {
           span_naming: :job_class,
+          propagation_style: :child, # XXX: Configurable?
         }
       else
         SemanticLogger[self.class].info "OpenTelemetry::Instrumentation::Sidekiq is not loaded, so Sidekiq traces will not be captured"

data/lib/brut/front_end/asset_metadata.rb

@@ -4,7 +4,6 @@
 class Brut::FrontEnd::AssetMetadata
 
   # @param [String] asset_metadata_file to the asset metadata file
-  # @param [IO] out IO on which to write messaging
   def initialize(asset_metadata_file:,logger: :use_default)
     @asset_metadata_file = asset_metadata_file
     @logger = if logger == :use_default

data/lib/brut/front_end/forms/input_declarations.rb

@@ -1,4 +1,16 @@
-# Extended by {Brut::FrontEnd::Form} to allow declaring inputs. Do not use this module directly. Instead, call {#input} or {#select}
+# Extended by {Brut::FrontEnd::Form} to allow declaring inputs. This module creates methods per input on the form passed to your handlers. For example, if you have an `input :book_title`, then `form.book_title` will be available to access the value of the "book_title" input.
+#
+# There are two methods that could be created, per input. Examples below use
+# `book_title` as the attribute name
+#
+# * `#book_title` - returns {Brut::FrontEnd::Forms::Input#value}, which is always a string.
+# * `#book_title_coerced` - returns {Brut::FrontEnd::Forms::Input#typed_value}, which is always the correct type for the input **or `nil` if type coercion failed**. Only call this once you have checked for constraint violations
+#
+# For indexed parameters, the above methods require the index to be passed,
+# e.g. `form.book_title_coerced(4)`.  For non-indexed parameters, the index may
+# not be passed.
+#
+# Do not use this module directly. Instead, call {#input} or {#select}
 # from within your form's class definition.
 module Brut::FrontEnd::Forms::InputDeclarations
   # Declares an input for this form, to be modeled via an HTML `<INPUT>` tag.
@@ -59,11 +71,22 @@ module Brut::FrontEnd::Forms::InputDeclarations
         end
         self.input(input_definition.name, index:).value
       end
+      define_method "#{input_definition.name}_coerced" do |index=nil|
+        if index.nil?
+          raise ArgumentError,"#{input_definition.name} is an array - you must provide an index to access one of its values"
+        end
+        self.input(input_definition.name, index:).typed_value
+      end
       define_method "#{input_definition.name}_each" do |&block|
         self.inputs(input_definition.name).each_with_index do |input,i|
           block.(input.value,i)
         end
       end
+      define_method "#{input_definition.name}_each_coerced" do |&block|
+        self.inputs(input_definition.name).each_with_index do |input,i|
+          block.(input.typed_value,i)
+        end
+      end
     else
       define_method input_definition.name do |index_that_should_be_omitted=nil|
         if !index_that_should_be_omitted.nil?
@@ -71,6 +94,12 @@ module Brut::FrontEnd::Forms::InputDeclarations
         end
         self.input(input_definition.name, index: 0).value
       end
+      define_method "#{input_definition.name}_coerced" do |index_that_should_be_omitted=nil|
+        if !index_that_should_be_omitted.nil?
+          raise ArgumentError,"#{input_definition.name} is not an array - do not provide an index when accessing its value"
+        end
+        self.input(input_definition.name, index: 0).typed_value
+      end
     end
   end
 

data/lib/brut/front_end/handler.rb

@@ -23,7 +23,8 @@ module Brut::FrontEnd
     include Brut::FrontEnd::HandlingResults
     include Brut::Framework::Errors
 
-    # You must implement this to accept whatever parameters you need. See {Brut::FrontEnd::RequestContext} for how that works.
+    # You must implement this to perform whatever action your handler must perform.  Any information from the request would've been given to your initializer. See {Brut::FrontEnd::RequestContext} for how that works.
+    #
     # The type of the return value determines what will happen:
     #
     # * Instance of `URI` - browser will redirect to this URI. Typically, you would do this by calling {Brut::FrontEnd::HandlingResults#redirect_to}.
@@ -39,7 +40,7 @@ module Brut::FrontEnd
       abstract_method!
     end
 
-    # Override this to performa any checks before {#handle} is called.  This should
+    # Override this to perform any checks before {#handle} is called.  This should
     # return `nil` if {#handle} should proceed to be called. Generally, you don't need to override
     # this as {#handle} can include the logic.  Where this is useful is to share cross-cutting logic
     # across other handlers.
@@ -48,8 +49,7 @@ module Brut::FrontEnd
     #         {#handle} for what each return value means.
     def before_handle = nil
 
-    # Called by Brut to handle the request. Do not override this. If your handler responds to `before_handle` that is called with the
-    # same args as you have defined for {#handle}. If `before_handle` returns anything other than `nil`, that value is returned and
+    # Called by Brut to handle the request. Do not override this. If `before_handle` returns anything other than `nil`, that value is returned and
     # should be one of the values documented in {#handle}.  If `before_handle` returns `nil`, {#handle} is called and whatever it
     # returns is returned here.
     def handle!(**args)

data/lib/brut/rubocop_config.rb

@@ -46,9 +46,9 @@ module Brut
         "member?" => "include?",
       },
     },
-    "Style/EndlessMethod" => {
-      "EnforcedStyle" =>  "allow_single_line",
-    },
+    #"Style/EndlessMethod" => {
+    #  "EnforcedStyle" =>  "allow_single_line",
+    #},
     "Style/For" => {
       "EnforcedStyle" =>  "each",
     },

data/lib/brut/spec_support/e2e_test_server.rb

@@ -15,9 +15,10 @@ class Brut::SpecSupport::E2ETestServer
   # from the given bin dir
   #
   # @param [Pathname] bin_dir path to where the app's Brut-provide CLI apps are installed
-  def initialize(bin_dir:)
-    @bin_dir = bin_dir
-    @pid     = nil
+  def initialize(bin_dir:, start_timeout_seconds: nil)
+    @bin_dir               = bin_dir
+    @pid                   = nil
+    @start_timeout_seconds = start_timeout_seconds || 5
   end
 
   # Starts the server. Returns when the server has started
@@ -66,7 +67,7 @@ private
 
   def is_port_open?(ip, port)
     begin
-      Timeout::timeout(5) do
+      Timeout::timeout(@start_timeout_seconds) do
         loop do
           begin
             logger.debug "Attemping to conenct to '#{ip}' on port '#{port}'"

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

@@ -47,6 +47,9 @@ class Brut::SpecSupport::Matchers::HaveConstraintViolation
     if !form.kind_of?(Brut::FrontEnd::Form)
       raise "#{self.class} only works with forms, not #{form.class}"
     end
+    if field.to_s == ""
+      raise "field is required"
+    end
     @form  = form
     @field = field.to_s
     @key   = key.to_s

data/lib/brut/tui/event_loop.rb

@@ -112,7 +112,11 @@ private
       errors.each do
         $stderr.puts("FATAL Exception: #{it.exception.class}: #{it.exception.message}\n    #{it.exception.backtrace.join("\n    ")}")
       end
-      exit 1
+      if errors.any?
+        exit 1
+      else
+        exit 0
+      end
     else
       errors.each { @queue.unshift(Brut::TUI::Events::Exception.new(it)) }
     end

data/lib/brut/tui/script/exec_step.rb

@@ -29,7 +29,7 @@ class Brut::TUI::Script::ExecStep < Brut::TUI::Script::Step
       command: @command,
       strip_ansi: false,
       stdout: @stdout,
-      stderr: @stderr
+      stderr: @stderr,
     })
   end
   def run!

data/lib/brut/version.rb

@@ -1,4 +1,4 @@
 module Brut
   # @!visibility private
-  VERSION = "0.19.2"
+  VERSION = "0.20.1"
 end

data/templates/Base/app/src/back_end/data_models/db/README.md

@@ -0,0 +1,8 @@
+Data Models go here. Create them with `brut scaffold db_model`
+
+```ruby
+# db/widget.rb
+class DB::Widget < AppDataModel
+end
+```
+

data/templates/Base/bin/console

@@ -16,7 +16,7 @@ if ARGV[0] == "help"
   exit
 end
 
-ENV["RACK_ENV"] = "development"
+ENV["RACK_ENV"] ||= "development"
 if ENV["LOG_LEVEL"].to_s == ""
   ENV["LOG_LEVEL"] = "warn"
 end

data/templates/Base/bin/release

@@ -19,7 +19,7 @@ echo "[ bin/release ] started"
 echo "[ bin/release ] Creating DB if needed"
 BRUT_CLI_RAISE_ON_ERROR=true bundle exec brut db create --env=production
 echo "[ bin/release ] Migrating DB if needed"
-BRUT_CLI_RAISE_ON_ERROR=true bundle exec burt db migrate --env=production
+BRUT_CLI_RAISE_ON_ERROR=true bundle exec brut db migrate --env=production
 
 # Add additional commands here as needed
 

data/templates/Base/dx/bash_customizations.local

@@ -1,8 +1,5 @@
 # Insert developer-specifilc Bash customizations here.
-# This file is not checked into version control, so you
-# are safe to export EDITOR=vim and avoid any guff from 
-# co-workers.
-
+# This file is not checked into version control
 # Sets up a multi-line prompt since the working directory
 # may be very deep.  Customize or change at your leisure.
 PS1='\[\e[35m\]docker-container\[\e[0m\] - \[\e[37m\]\w\n\[\e[0m\]> '

data/templates/Base/dx/build

@@ -48,7 +48,7 @@ setup_playright_build_args() {
   require_command "grep"
   require_command "sed"
 
-  if [ ! -e "${SCRIPT_DIR}"/Gemfile.lock ]; then
+  if [ ! -e "${SCRIPT_DIR}"/../Gemfile.lock ]; then
     log "Could not find Gemfile.lock, which is needed to determine the playwright-ruby-client version"
     log "Assuming your app is brand-new, this should be OK"
     echo "# When this file was created, there was no Gemfile.lock, so"               >> "${SCRIPT_DIR}"/build.args
@@ -57,7 +57,7 @@ setup_playright_build_args() {
     echo "# encouraged to re-run \`dx/build\` to address this issue."                >> "${SCRIPT_DIR}"/build.args
     echo PLAYWRIGHT_VERSION=latest                                                   >> "${SCRIPT_DIR}"/build.args
   else
-    PLAYWRIGHT_VERSION=$(grep playwright-ruby-client Gemfile.lock  | grep '(' | sed 's/^.*(//' | sed 's/).*$//' | grep -v ^=)
+    PLAYWRIGHT_VERSION=$(grep playwright-ruby-client $SCRIPT_DIR/../Gemfile.lock  | grep '(' | sed 's/^.*(//' | sed 's/).*$//' | grep -v ^=)
     if [ -z "${PLAYWRIGHT_VERSION}" ]; then
       log "Could not find precise version of playwright-ruby-client from Gemfile.lock"
       log "This means that your playwright-ruby-client version and playwright NPM modules may be out of sync and may not work"

data/templates/Base/specs/spec_helper.rb

@@ -1,4 +1,7 @@
+require "dotenv"
 ENV["RACK_ENV"] = "test"
+Dotenv.load(".env.test.local", ".env.test")
+
 require_relative "../app/bootstrap"
 Bootstrap.new.bootstrap!
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brut
 version: !ruby/object:Gem::Version
-  version: 0.19.2
+  version: 0.20.1
 platform: ruby
 authors:
 - David Bryant Copeland
@@ -475,16 +475,16 @@ dependencies:
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.37
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.37
 description: An opinionated web framework build on web standards
 email:
 - davec@thirdtank.com
@@ -548,6 +548,7 @@ files:
 - lib/brut/cli/commands/compound_command.rb
 - lib/brut/cli/commands/execution_context.rb
 - lib/brut/cli/commands/help.rb
+- lib/brut/cli/commands/help_in_markdown.rb
 - lib/brut/cli/commands/output_error.rb
 - lib/brut/cli/commands/raise_error.rb
 - lib/brut/cli/error.rb
@@ -719,7 +720,6 @@ files:
 - lib/sequel/plugins/find_bang.rb
 - templates/Base/.dockerignore
 - templates/Base/.env.development.erb
-- templates/Base/.env.development.local
 - templates/Base/.env.test.erb
 - templates/Base/.gitignore
 - templates/Base/.projections.json
@@ -736,6 +736,7 @@ files:
 - templates/Base/app/src/app.rb.erb
 - templates/Base/app/src/back_end/data_models/app_data_model.rb
 - templates/Base/app/src/back_end/data_models/db.rb
+- templates/Base/app/src/back_end/data_models/db/README.md
 - templates/Base/app/src/back_end/data_models/migrations/20240101130000_citext.rb
 - templates/Base/app/src/back_end/data_models/seed/seed_data.rb
 - templates/Base/app/src/front_end/components/app_component.rb
@@ -851,7 +852,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Web Framework Built around Ruby, Web Standards, Simplicity, and Object-Orientation
 test_files: []

data/templates/Base/.env.development.local

@@ -1,2 +0,0 @@
-# Place developer-specific overrides of .env.development in here, 
-# e.g. API keys needed for local dev. DO NOT CHECK INTO VERSION CONTROL