brut 0.5.0 → 0.8.0

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

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -e
+
+# Ideally, the message below is shown after everything starts up. We can't
+# achieve this using healthchecks 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/mkbrut/templates/Base/dx/start

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${0}" )" > /dev/null 2>&1 && pwd )
+
+. "${SCRIPT_DIR}/dx.sh.lib"
+require_command "docker"
+load_docker_compose_env
+
+usage_on_help "Starts all services, including a container in which to run your app" "" "" "" "${@}"
+
+log "🚀" "Starting docker-compose.dx.yml"
+
+BUILD=--build
+if [ "${1}" == "--no-build" ]; then
+    BUILD=
+fi
+
+docker \
+  compose \
+    --file docker-compose.dx.yml \
+    --project-name "${PROJECT_NAME}" \
+    --env-file "${ENV_FILE}" \
+  up \
+    "${BUILD}" \
+    --timestamps \
+    --force-recreate
+
+# vim: ft=bash

data/mkbrut/templates/Base/dx/stop

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${0}" )" > /dev/null 2>&1 && pwd )
+
+. "${SCRIPT_DIR}/dx.sh.lib"
+require_command "docker"
+load_docker_compose_env
+
+usage_on_help "Stops all services, the container in which to run your app and removes any volumes" "" "" "" "${@}"
+
+log "🚀" "Stopping docker-compose.dx.yml"
+
+docker \
+  compose \
+    --file docker-compose.dx.yml \
+    --project-name "${PROJECT_NAME}" \
+    --env-file "${ENV_FILE}" \
+  down \
+    --volumes
+
+# vim: ft=bash

data/mkbrut/templates/Base/package.json.erb

@@ -0,0 +1,37 @@
+{
+  "name": "<%= app_name %>",
+  "type": "module",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "brut-css": "<%= versions.brut_css_version_specifier %>",
+    "brut-js": "<%= versions.brut_js_version_specifier %>"
+  },
+  "devDependencies": {
+    "chokidar-cli": "^3.0.0",
+    "esbuild": "^0.20.2",
+    "jsdom": "^25.0.1",
+    "mocha": "^10.7.3",
+    "playwright": "1.50.1",
+    "typescript": "^5.8.3",
+    "typescript-language-server": "^4.3.4",
+    "vscode-langservers-extracted": "^4.10.0"
+  },
+  "notes": {
+    "note": "This section provides documentation on what the various information in here is for",
+    "type": "Needs to be 'module' so that the web components unit tests work properly",
+    "dependencies": {
+      "brut-css": "Basic CSS library to get you started. See Brut's docs for how to use or remove",
+      "brut-js": "Autonomous custom elements and utilities. See Brut's docs for how to use and why you should not remove"
+    },
+    "devDependencies": {
+      "chokidar-cli": "Used to watch files and and rebuild stuff on changes",
+      "esbuild": "Bundles JS and CSS - you may need this in dependencies depending on how you deploy",
+      "jsdom": "Used for unit testing custom elements",
+      "mocha": "Used for unit testing custom elements",
+      "playwright": "Used for end-to-end testing. This version is locked and must be the same as the one in the Gemfile for playwright-ruby-client.",
+      "typescript": "Needed for the JS and CSS LSP servers",
+      "typescript-language-server": "Provides a JS LSP server",
+      "vscode-langservers-extracted": "Despite the name, provides a CSS LSP server"
+    }
+  }
+}

data/mkbrut/templates/Base/puma.config.rb

@@ -0,0 +1,53 @@
+# Mostly based on Heroku's guidance:
+# https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server
+
+# Ensures the logger is setup and availbale as early as possible
+require "semantic_logger"
+
+# workers should be set to the # of cores. Heroku
+# recommends the following, with 2 as a default if you don't have a good
+# reason to change it.
+workers Integer(ENV["WEB_CONCURRENCY"] || 2)
+
+# Heroku recommens 5 as a default, with the ability
+# to change it as needed.
+threads_count = Integer(ENV["PUMA_MAX_THREADS"] || 5)
+
+# This actually sets the min and max # of threads.
+# Heroku recommends setting them both to the thread_count
+# above.
+threads threads_count, threads_count
+
+# Indicate that the app should be loaded before any
+# forking or thread creation. Despite the bang,
+# this doesn't actually do anything - it just sets configuration
+preload_app!
+
+# Support IPv6 by binding to host `::` instead of `0.0.0.0`
+port(ENV["PORT"] || 3000, "::")
+
+# Turn off keepalive support for better long tails response time with Router 2.0
+# Remove this line when https://github.com/puma/puma/issues/3487 is closed, and the fix is released
+if respond_to?(:enable_keep_alives)
+  enable_keep_alives(false)
+end
+
+# Commenting this out as a) we don't default DefaultRackup
+# and b) I don't exactly know what it means or does.
+# rackup      DefaultRackup if defined?(DefaultRackup)
+
+# Set the environment based on RACK_ENV
+environment ENV["RACK_ENV"]
+
+before_fork do
+  # Per http://sequel.jeremyevans.net/rdoc/files/doc/fork_safety_rdoc.html
+  # we must disconnect before forking.  Sequel will reconnect as needed.
+  Sequel::DATABASES.each(&:disconnect)
+end
+
+on_worker_boot do
+  # Per https://logger.rocketjob.io/forking.html we want to reopen
+  # this to avoid issues
+  SemanticLogger.reopen
+end
+

data/mkbrut/templates/Base/specs/e2e/home_page.spec.rb.erb

@@ -0,0 +1,23 @@
+require "spec_helper"
+
+RSpec.describe "The home page works" do
+  it "shows a welcome message" do
+    # Instead of hard-coding URLs, you can use the 
+    # page classes to navigate to their routing.
+    page.goto(HomePage.routing)
+
+    # The Brut::FrontEnd::Components::PageIdentifier component
+    # renders a <meta> tag that Brut's `be_page_for` will look for.
+    # This is a useful check that you ended up on the page you meant to.
+    expect(page).to be_page_for(HomePage)
+
+    # In Playwright, elements are "located" asynchronously.  What is returned
+    # here is an object that will look for an <h1> only when an expectation
+    # is made on it.
+    h1 = page.locator("h1")
+
+    # This will actually locate the <h1> (waiting for some time for it to
+    # show up if it's not there), and then assert its text content.
+    expect(h1).to have_text("Welcome to Brut")
+  end
+end

data/mkbrut/templates/Base/specs/front_end/js/SpecHelper.js

@@ -0,0 +1,24 @@
+import { createTestBasedOnHTML } from "brut-js/testing"
+
+import path from "node:path"
+import fs   from "node:fs"
+
+const __dirname = import.meta.dirname
+
+const appRoot               = path.resolve(__dirname,"..","..","..","app")
+const publicRoot            = path.resolve(appRoot,"public")
+const assetMetadataFilePath = path.resolve(appRoot,"config","asset_metadata.json")
+const assetMetadata         = JSON.parse(fs.readFileSync(assetMetadataFilePath))
+
+const withHTML = (html) => {
+  return createTestBasedOnHTML({
+    html,
+    assetMetadata,
+    publicRoot
+  })
+}
+
+export {
+  withHTML,
+}
+

data/mkbrut/templates/Base/specs/front_end/pages/home_page.spec.rb

@@ -0,0 +1,22 @@
+require "spec_helper"
+
+RSpec.describe HomePage do
+  it "should show the H1" do
+    # Page specs should evaluate the generated HTML, so
+    # the generate_and_parse help will accept an instaniated 
+    # page (or components), generate its HTML, then use Nokogiri
+    # to parse it, return the result.
+    result = generate_and_parse(described_class.new)
+
+    # e! is provided by Brut::SpecSupport::EnhancedNode which
+    # delegates everything to the underlying Nokogiri::XML::Node
+    # while adding a few methods.  e! requires that exactly
+    # one element match the given CSS selector, then returns it.
+    #
+    # Thus, this expectation will fail if:
+    # * there is no <h1> (and the error message would indcate this)
+    # * there is is more than one <h1> (and the error message would indcate this)
+    # * the only <h1>'s text is not exactly "Welcome to Brut"
+    expect(result.e!("h1").text).to eq("Welcome to Brut")
+  end
+end

data/mkbrut/templates/Base/specs/lint_factories.spec.rb

@@ -0,0 +1,7 @@
+require "spec_helper"
+RSpec.describe "factories" do
+  it "should be possible to create them all" do
+    FactoryBot.lint traits: true
+  end
+end
+

data/mkbrut/templates/Base/specs/spec_helper.rb

@@ -0,0 +1,78 @@
+ENV["RACK_ENV"] = "test"
+require_relative "../app/bootstrap"
+Bootstrap.new.bootstrap!
+
+require "brut/spec_support"
+
+require "nokogiri"
+require "playwright"
+require "playwright/test"
+require "confidence_check/for_rspec"
+require "with_clues"
+
+require_relative "support"
+
+RSpec.configure do |config|
+  # This configuration has two main parts.
+  #
+  # The first part is here: a call to Brut::SpecSupport::RSpecSetup,
+  # which will set configuration values required for Brut's spec
+  # helpers and other APIs. In generally, you do not want to change
+  # this configuration.
+  rspec_setup = Brut::SpecSupport::RSpecSetup.new(rspec_config: config)
+  rspec_setup.setup!
+
+  # The second part is here and is RSpec configuration that you may want
+  # to change. Changing the configuration below here should not break
+  # any of Brut's internal behavior around tests.  The values
+  # and configuration options set are a recommended default, but you
+  # can certainly change it to suit your needs.
+
+
+  # Confidence Check allows you to wrap test expectations
+  # with confidence_check as a way to indicate those expectations are
+  # checking that the test is setup properly and not testing
+  # the behavior of the code under test
+  config.include ConfidenceCheck::ForRSpec
+
+  # With Clues allows you to wrap expectations in 
+  # a with_clues block that will provide more details
+  # about the failure and make it easier to diagnose 
+  # why a test failed.
+  config.include WithClues::Method
+  config.include FactoryBot::Syntax::Methods
+
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  # Not that you should be using shared contexts, but if you are, please
+  # see https://rubydoc.info/gems/rspec-core/3.13.5/RSpec/Core/Configuration#shared_context_metadata_behavior-instance_method
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  config.filter_run_when_matching :focus
+
+  # Can't find docs on how this path is resolved, so disabling
+  # config.example_status_persistence_file_path = "spec/examples.txt"
+
+  config.disable_monkey_patching!
+
+  config.warnings = ENV.fetch("RSPEC_WARNINGS","false") == "true"
+
+  if config.files_to_run.one?
+    config.default_formatter = "doc"
+  end
+
+  if ENV["RSPEC_PROFILE_EXAMPLES"]
+    config.profile_examples = ENV["RSPEC_PROFILE_EXAMPLES"].to_i
+  end
+
+  config.order = :random
+
+  Kernel.srand config.seed
+end
+

data/mkbrut/templates/Base/specs/support.rb

@@ -0,0 +1,2 @@
+module Support
+end

data/mkbrut/templates/segments/BareBones/app/src/front_end/handlers/trigger_exception_handler.rb

@@ -0,0 +1,24 @@
+# Allows manually triggering an exception so you can see
+# the exception handling mechanism execute without waiting
+# for a real exception to happen.
+class TriggerExceptionHandler < AppHandler
+  # These arguments are query string parameters that 
+  # can be given to the URL connected to this handler.
+  # See https://brutrb.com/keyword-injection.html for more details.
+  def initialize(message: "no message provided", status: nil, key: nil)
+    @message = message
+    @status  = status
+    @key     = key
+  end
+
+  def handle
+    if @key != Brut.container.trigger_exception_key
+      http_status(404)
+    elsif @status
+      http_status(@status)
+    else
+      raise @message
+    end
+  end
+end
+

data/mkbrut/templates/segments/BareBones/app/src/front_end/js/Example.js.erb

@@ -0,0 +1,49 @@
+import { BaseCustomElement } from "brut-js"
+
+// This is very similar to a vanilla on-spec
+// implementation of an autonomous custom element.
+// The only difference is BaseCustomElement (which
+// extends HTMLElement) provides a few convenience
+// methods to make it easier to build your own custom
+// elements.
+class Example extends BaseCustomElement {
+  // tagName allows BaseCustomElement's define() method to
+  // define your custom element
+  static tagName = "<%= prefix %>-example"
+
+  static observedAttributes = [
+    "transform",
+    "show-warnings", // recognized by BaseCustomElement to allow
+                     // for debugguing in the browser console,
+                     // but clean consoles in production.
+  ]
+
+  #transform = "upper"
+
+  // Called by BaseCustomElement's attributeChangedCallback.
+  transformChangedCallback({newValue}) {
+    this.#transform = newValue
+  }
+
+  // Called by connectCallback and attributeChangedCallback, this
+  // method should make whatever changes are necessary based on the current
+  // state of the element.
+  update() {
+    const content = this.textContent
+    if (this.#transform == "upper") {
+      this.textContent = content.toLocaleUpperCase()
+    }
+    else if (this.#transform == "lower") {
+      this.textContent = content.toLocaleLowerCase()
+    }
+    else {
+      // Example of debugging. if show-warnings is not set, this message
+      // is not shown in the console. If show-warnings IS set (including
+      // when you override it in production using the browser's devtools)
+      // this message WILL be shown
+      this.logger.info("We only support upper or lower, but got %s",this.#transform)
+    }
+  }
+}
+
+export default Example

data/mkbrut/templates/segments/BareBones/specs/front_end/handlers/trigger_exception_handler.spec.rb

@@ -0,0 +1,41 @@
+require "spec_helper"
+
+RSpec.describe TriggerExceptionHandler do
+  describe "#handle!" do
+    context "key is correct" do
+      context "http status given" do
+        it "returns that status" do
+          handler = described_class.new(status: 401, key: "test-trigger-exception")
+          result = handler.handle!
+          expect(result).to have_returned_http_status(401)
+        end
+      end
+      context "no http status given" do
+        context "message provided" do
+          it "raises with that message" do
+            handler = described_class.new(message: "test message", key: "test-trigger-exception")
+            expect {
+              handler.handle!
+            }.to raise_error("test message")
+          end
+        end
+        context "no message provided" do
+          it "raises with a default message" do
+            handler = described_class.new(key: "test-trigger-exception")
+            expect {
+              handler.handle!
+            }.to raise_error("no message provided")
+          end
+        end
+      end
+    end
+    context "key is incorrect" do
+      it "returns 404" do
+        handler = described_class.new(status: 401, message: "test message")
+        result = handler.handle!
+        expect(result).to have_returned_http_status(404)
+      end
+    end
+  end
+end
+

data/mkbrut/templates/segments/BareBones/specs/front_end/js/Example.spec.js.erb

@@ -0,0 +1,38 @@
+import { withHTML } from "./SpecHelper.js"
+
+// Autonomouse custom element support is very basic.
+// In this spec, we use `withHTML` which was defined in SpecHelper.js,
+// which ultimately uses `createTestBasedOnHTML` from BrutJS.
+// This will configure JSDom with the HTML you provide, then execute
+// your test as if that HTML is the document.
+describe("<<%= prefix %>-example>", () => {
+
+  // The example custom element will transform its contents to 
+  // either upper or lower case. In this test, we assert that, by
+  // default, it transforms to upper case. To do that,
+  // create an HTML document you can see below.  The element
+  // will have been connected (connectedCallback will have been 
+  // called) by the time the test executes.  Thus, 
+  // document.querySelector(...) will find the element and its
+  // .textContent will have already been transformed.
+  withHTML(`
+  <<%= prefix %>-example>This is some Text</<%= prefix %>-example>
+  `).test("upper case by default", ({document,assert}) => {
+    const element = document.querySelector("<%= prefix %>-example")
+    assert.equal(element.textContent,"THIS IS SOME TEXT")
+  })
+
+  withHTML(`
+  <<%= prefix %>-example transform="lower">This is some Text</<%= prefix %>-example>
+  `).test("lower case when asked", ({document,assert}) => {
+    const element = document.querySelector("<%= prefix %>-example")
+    assert.equal(element.textContent,"this is some text")
+    // Remember that setAttribute is synchronous, so by the time
+    // its done executing, attributeChangedCallback will have been called,
+    // and thus the element's `update()` method will have been called and
+    // its textContent transformed.
+    element.setAttribute("transform","upper")
+    assert.equal(element.textContent,"THIS IS SOME TEXT")
+  })
+})
+

data/mkbrut/templates/segments/Demo/app/src/back_end/data_models/db/guestbook_message.rb

@@ -0,0 +1,3 @@
+class DB::GuestbookMessage < AppDataModel
+  has_external_id "gm"
+end

data/mkbrut/templates/segments/Demo/app/src/back_end/data_models/migrations/20250628194124_guestbook.rb

@@ -0,0 +1,14 @@
+Sequel.migration do
+  up do
+    create_table :guestbook_messages,
+      comment: "Messages people have left in the guestbook",
+      external_id: true do 
+
+      column :name, :text
+      column :message, :text
+      column :ip_address, :inet
+
+      key [ :ip_address ]
+    end
+  end
+end

data/mkbrut/templates/segments/Demo/app/src/front_end/components/flash_component.rb

@@ -0,0 +1,36 @@
+class FlashComponent < AppComponent
+  def initialize(flash:)
+    @flash = flash
+  end
+
+  CLASSES = [
+    "f-1",
+    "fw-bold",
+    "w-50",
+    "mv-3",
+    "shadow-3",
+    "pa-3",
+    "ba",
+    "br-3",
+    "tc"
+  ]
+  COLORS = [
+    "%{color}-300",
+    "bg-%{color}-800",
+    "bc-%{color}-700",
+  ]
+
+  def view_template
+    if @flash.notice?
+      div(role: "status",
+          class: CLASSES + COLORS.map { it % { color: "blue" } }) do
+        t(@flash.notice)
+      end
+    elsif @flash.alert?
+      div(role: "alert",
+          class: CLASSES + COLORS.map { it % { color: "orange" } }) do
+        t(@flash.alert)
+      end
+    end
+  end
+end

data/mkbrut/templates/segments/Demo/app/src/front_end/css/constraint-violations.css

@@ -0,0 +1,18 @@
+/* Hide <brut-cv> tags so that we don't see
+ * client-side errors before the form is submitted */
+brut-cv {
+  display: none;
+  color: var(--red-400);
+}
+
+/* Server-side errors are always visible */
+brut-cv[server-side] {
+  display: block;
+}
+
+/* Only when a form submission is attempted do 
+ * we show the <brut-cv>s that are not server-side,
+ * and thus client-side */
+brut-form[submitted-invalid] brut-cv {
+  display: block;
+}

data/mkbrut/templates/segments/Demo/app/src/front_end/css/fonts.css

@@ -0,0 +1,19 @@
+/* Example of font-management. */
+@font-face {
+  font-family: "Monaspace Xenon";
+  /** url is relative to this file. When bin/build-assets runs,
+   * esbuild will see this and modify it to work with the bundle
+   * that is ultimately produced */
+  src: url("../fonts/monaspace-xenon.ttf") format("truetype");
+  font-display: swap;
+}
+
+:root {
+  /* Sets the mono font for BrutCSS */
+  --ff-mono: 'Monaspace Xenon', monospace;
+}
+
+code {
+  /* Uses the mono font for <code> elements */
+  font-family: var(--ff-mono);
+}

data/mkbrut/templates/segments/Demo/app/src/front_end/forms/guestbook_message_form.rb

@@ -0,0 +1,4 @@
+class GuestbookMessageForm < AppForm
+  input :name, minlength: 2
+  input :message, minlength: 10
+end

data/mkbrut/templates/segments/Demo/app/src/front_end/handlers/guestbook_message_handler.rb

@@ -0,0 +1,64 @@
+class GuestbookMessageHandler < AppHandler
+  def initialize(form:, flash:, rack_request_ip:, session:)
+    @form            = form
+    @flash           = flash
+    @rack_request_ip = rack_request_ip
+    @session         = session
+  end
+  def handle
+    # If client-side constraint violation checking was skipped,
+    # but there ARE such violations, the form will be able to check
+    # that server-side and return true for #constraint_violations?
+    if @form.valid?
+      save_message
+    end
+
+    if @form.constraint_violations?
+      @flash.alert = :guestbook_not_saved
+      return NewGuestbookMessagePage.new(form: @form,
+                                         session: @session)
+    else
+      @flash.notice = :guestbook_saved
+      redirect_to(
+        GuestbookPage,
+        anchor: @session.guestbook_message&.external_id
+      )
+    end
+  end
+
+private
+
+  def save_message
+    # While we don't recommend business logic be placed
+    # inside handlers, we're leaving it here to avoid
+    # anchoring you on any particular way of managing
+    # the logic in your app.
+    if @form.message.split(/\s+/).length < 2
+      @form.server_side_constraint_violation(
+        input_name: "message",
+        key: :not_enough_words
+      )
+    else
+      if DB::GuestbookMessage.find(ip_address: @rack_request_ip)
+        @form.server_side_constraint_violation(
+          input_name: "name",
+          key: :already_posted
+        )
+      else
+        begin
+          guestbook_message = DB::GuestbookMessage.create(
+            name: @form.name,
+            message: @form.message,
+            ip_address: @rack_request_ip,
+          )
+          @session.signed_guestbook(guestbook_message)
+        rescue Sequel::UniqueConstraintViolation => ex
+          @form.server_side_constraint_violation(
+            input_name: "name",
+            key: :already_posted
+          )
+        end
+      end
+    end
+  end
+end