brut 0.0.1

data/lib/brut/back_end/result.rb

@@ -0,0 +1,46 @@
+# The result of back-end processing, which is essentially
+# a container for constraint violations and arbitrary context.
+class Brut::BackEnd::Result
+  attr_reader :constraint_violations, :context
+
+  def initialize
+    @constraint_violations = {}
+    @context = {}
+  end
+
+  def constraint_violation!(object:,
+                            field:,
+                            key:,
+                            context: {})
+    @constraint_violations[object] ||= {}
+    @constraint_violations[object][field] ||= {}
+    @constraint_violations[object][field][key] = context
+  end
+
+  def each_violation(&block)
+    @constraint_violations.each do |object,fields|
+      fields.each do |field,keys|
+        keys.each do |key,context|
+          block.(object,field,key,context)
+        end
+      end
+    end
+  end
+
+  def []=(key_in_context,object)
+    @context[key_in_context] = object
+  end
+
+  def [](key_in_context)
+    @context.fetch(key_in_context)
+  rescue KeyError => ex
+    raise KeyError.new(
+      "Context did not contain '#{key_in_context}' (#{key_in_context.class}). Context has these keys: #{@context.keys.join(',')}",
+      receiver: ex.receiver,
+      key: ex.key)
+  end
+
+
+  def constraint_violations? = self.constraint_violations.any?
+
+end

data/lib/brut/back_end/seed_data.rb

@@ -0,0 +1,24 @@
+require_relative "../factory_bot"
+module Brut
+  module Backend
+    class SeedData
+      def self.inherited(seed_data_klass)
+        @classes ||= []
+        @classes << seed_data_klass
+      end
+      def self.classes = @classes || []
+
+      def setup!
+        Brut::FactoryBot.new.setup!
+      end
+
+      def load_seeds!
+        DB.transaction do
+          self.class.classes.each do |klass|
+            klass.new.seed!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brut/back_end/validator.rb

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

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

@@ -0,0 +1,37 @@
+# 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.
+class Brut::BackEnd::Validators::FormValidator
+  def self.validate(attribute,options)
+    @@validations ||= {}
+    @@validations[attribute] = options
+  end
+
+  def validate(form)
+    @@validations.each do |attribute,options|
+      value = form.send(attribute)
+      options.each do |option, option_value|
+        case option
+        when :required
+          if option_value == true
+            if value.to_s.strip == ""
+              form.server_side_constraint_violation(input_name: attribute, key: :required)
+            end
+          end
+        when :minlength
+          if value.respond_to?(:length) || value.nil?
+            if value.nil? || value.length < option_value
+              form.server_side_constraint_violation(input_name: attribute, key: :too_short, context: { minlength: option_value })
+            end
+          else
+            raise "'#{attribute}''s value (a '#{value.class}') does not respond to 'length' - :minlength cannot be used as a validation"
+          end
+        else
+          raise "'#{option}' is not a recognized validation option"
+        end
+      end
+    end
+  end
+
+end

data/lib/brut/cli/app.rb

@@ -0,0 +1,130 @@
+require "optparse"
+require_relative "../junk_drawer"
+class Brut::CLI::App
+  include Brut::CLI::ExecutionResults
+  include Brut::I18n::ForCLI
+
+  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
+  def self.description(new_description=nil)
+    if new_description.nil?
+      return @description.to_s
+    else
+      @description = new_description
+    end
+  end
+  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
+    end
+  end
+  def self.opts
+    self.option_parser
+  end
+  def self.option_parser
+    @option_parser ||= OptionParser.new do |opts|
+      opts.banner = "%{app} %{global_options} commands [command options] [args]"
+    end
+  end
+  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
+  end
+
+  def self.default_env           = @default_env
+  def self.requires_project_env? = @requires_project_env
+
+  def self.configure_only!
+    @configure_only = true
+  end
+  def self.configure_only? = !!@configure_only
+
+  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
+
+  def set_env_if_needed
+    if self.class.requires_project_env?
+      ENV["RACK_ENV"] = options.env
+    end
+  end
+
+  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
+
+  def before_execute
+  end
+
+  def after_bootstrap
+  end
+
+  def configure!
+  end
+
+  def execute!(command,project_root:)
+    before_execute
+    set_env_if_needed
+    command.set_env_if_needed
+    load_env(project_root:)
+    command.before_execute
+    bootstrap_result = begin
+                         require "#{project_root}/app/bootstrap"
+                         bootstrap = Bootstrap.new
+                         if self.class.configure_only?
+                           bootstrap.configure_only!
+                         else
+                           bootstrap.bootstrap!
+                         end
+                         continue_execution
+                       rescue => ex
+                         as_execution_result(command.handle_bootstrap_exception(ex))
+                       end
+    if bootstrap_result.stop?
+      return bootstrap_result
+    end
+    after_bootstrap
+    as_execution_result(command.execute)
+  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

@@ -0,0 +1,219 @@
+module Brut
+  module CLI
+    class AppRunner
+      include Brut::CLI::ExecutionResults
+
+      def initialize(app_klass:,project_root:)
+        @app_klass    = app_klass
+        @project_root = project_root
+      end
+
+      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:)
+            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:)
+          return 0
+        end
+
+        command_argv = remaining_argv[1..-1] || []
+        args = command_option_parser.parse!(command_argv,into:command_options)
+
+        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
+        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",""
+          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
+            printf 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:)
+        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
+        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
+
+        hash = {}
+        remaining_argv = option_parser.order!(into:hash)
+        global_options = Brut::CLI::Options.new(hash)
+        [ continue_execution, remaining_argv, global_options, option_parser ]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+require "json"
+require "fileutils"
+
+require "brut/cli"
+
+class Brut::CLI::Apps::BuildAssets < Brut::CLI::App
+  description "Build and manage code and assets destined for the browser, such as CSS, JS, or images"
+  requires_project_env
+  default_command :all
+  configure_only!
+
+  class All < Brut::CLI::Command
+    description "Build all assets"
+    opts.on("--[no-]clean","If set the metadata file used to map the files to their hashed values is deleted before assets are built")
+
+    def execute
+      if options.clean?(default: true)
+        asset_metadata_file = Brut.container.asset_metadata_file
+        out.puts "Removing #{asset_metadata_file}"
+        FileUtils.rm_f(asset_metadata_file)
+      end
+      delegate_to_commands(Images, JS, CSS)
+    end
+  end
+
+  class Images < Brut::CLI::Command
+    description "Copy images to the public folder"
+    detailed_description %{
+This is to ensure that any images your code references will end up in the public directory, so they are served properly. This is not for managing images that may be referenced in CSS files. See the `css` command for information on that.
+    }
+
+    def execute
+      src_dir  = Brut.container.images_src_dir
+      dest_dir = Brut.container.images_root_dir
+
+      command = "rsync --archive --delete --verbose #{src_dir}/ #{dest_dir}"
+      system! command
+    end
+  end
+
+  class CSS < Brut::CLI::Command
+    description "Builds a single CSS file suitable for sending to the browser"
+    opts.on("--clean","If set, any .css files hanging around from a prevous build are deleted. Not recommended in production environments")
+
+    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.
+
+      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"
+    }
+
+    def execute
+      css_bundle          = Brut.container.css_bundle_output_dir / "styles.css"
+      css_bundle_source   = Brut.container.front_end_src_dir / "css" / "index.css"
+      esbuild_metafile    = Brut.container.tmp_dir / "build-css-meta.json"
+      asset_metadata_file = Brut.container.asset_metadata_file
+
+      if options.clean?
+        out.puts "Cleaning old CSS files from #{Brut.container.css_bundle_output_dir}"
+        Dir[Brut.container.css_bundle_output_dir / "*.*"].each do |file|
+          if File.file?(file)
+            out.puts "Deleting #{file}"
+            FileUtils.rm(file)
+          end
+        end
+      end
+
+      command = "npx esbuild --loader:.ttf=copy --loader:.otf=copy --metafile=#{esbuild_metafile} --entry-names=[name]-[hash] --sourcemap --bundle #{css_bundle_source} --outfile=#{css_bundle}"
+      out.puts "Building CSS bundle '#{css_bundle}' with '#{command}'"
+      system!(command)
+
+      if !File.exist?(esbuild_metafile)
+        err.puts "'#{esbuild_metafile}' was not generated - cannot continue"
+        exit 1
+      end
+
+      asset_metadata = Brut::FrontEnd::AssetMetadata.new(asset_metadata_file:,out:)
+      asset_metadata.merge!(extension: ".css", esbuild_metafile:)
+      asset_metadata.save!
+    end
+  end
+  class JS < Brut::CLI::Command
+    description "Builds and bundles JavaScript destined for the browser"
+    opts.on("--clean","If set, any .js files hanging around from a prevous build are deleted. Not recommended in production environments")
+    opts.on("--output-file=FILE","Bundle to create that will be sent to the browser, relative to the JS public folder. Default is app.js")
+    opts.on("--source-file=FILE","Entry point used to create the bundle, relative to the source JS folder. Default is index.js")
+
+    def execute
+      js_bundle           = Brut.container.js_bundle_output_dir / options.output_file(default: "app.js")
+      js_bundle_source    = Brut.container.front_end_src_dir /  "js" / options.source_file(default: "index.js")
+      esbuild_metafile    = Brut.container.tmp_dir / "build-js-meta.json"
+      asset_metadata_file = Brut.container.asset_metadata_file
+
+      name_with_hash_regexp = /app\/public\/(?<path>.+)\/(?<name>.+)\-(?<hash>.+)\.js/
+      if options.clean?
+        out.puts "Cleaning old JS files from #{Brut.container.js_bundle_output_dir}"
+        Dir[Brut.container.js_bundle_output_dir / "*.*"].each do |file|
+          if File.file?(file)
+            out.puts "Deleting #{file}"
+            FileUtils.rm(file)
+          end
+        end
+      end
+
+      command = "npx esbuild --metafile=#{esbuild_metafile} --entry-names=[name]-[hash] --sourcemap --bundle #{js_bundle_source} --outfile=#{js_bundle}"
+      env_for_command = {
+        "NODE_PATH" => (Brut.container.project_root / "lib").to_s, # Not needed once Brut is properly bundled
+      }
+      out.puts "Building JS bundle '#{js_bundle}' with '#{command}'"
+      system!(env_for_command,command)
+
+      if !File.exist?(esbuild_metafile)
+        err.puts "'#{esbuild_metafile}' was not generated - cannot continue"
+        exit 1
+      end
+
+      asset_metadata = Brut::FrontEnd::AssetMetadata.new(asset_metadata_file:,out:)
+      asset_metadata.merge!(extension: ".js", esbuild_metafile:)
+      asset_metadata.save!
+    end
+
+  end
+
+end