brut 0.4.0 → 0.8.0

data/mkbrut/templates/Base/dx/docker-compose.env.erb

@@ -0,0 +1,25 @@
+# This file is an input to Docker Compose, and serves
+# as an additional set of environment variables.
+
+# IMAGE is the name of the image to be built for running
+# your app. The recommended format is ORG/REPO:TAG
+#
+# The ORG and REPO are based on the values used
+# with mkbrut.  TAG is set to mimic the value
+# in the FROM directive of the Dockerfile.
+# This will allow you to upgrade Ruby and run both
+# versions more easily.
+IMAGE=<%= organization %>/<%= app_name %>:ruby-3.4
+
+# PROJECT_NAME is used when running Docker compose
+# to help ensure the output includes your project's name.
+PROJECT_NAME=<%= app_name %>
+
+# DEFAULT_SERVICE is the name of the service (keys under 
+# service: in docker-compose.dx.yml) to use when
+# running dx/exec and no service is specified. 
+# The value "app" should match that in docker-compose.dx.yml
+# having the effect of dx/exec running commands inside your app's
+# container.
+DEFAULT_SERVICE=app
+# vim: ft=bash

data/mkbrut/templates/Base/dx/dx.sh.lib

@@ -0,0 +1,137 @@
+# shellcheck shell=bash
+
+# These are various functions needed by all the other scripts in dx/
+
+# Log a fatal error and exit nonzero
+fatal() {
+  remainder=${*:2}
+  if [ -z "$remainder" ]; then
+    log "🛑" "${@}"
+  else
+    log "${@}"
+  fi
+  exit 1
+}
+
+# Log an informational message. This is preferable to simply
+# using `echo` because it prepends the message with the name
+# of the script so you can tell where the message came from. 
+log() {
+  emoji=$1
+  remainder=${*:2}
+  if [ -z "${NO_EMOJI}" ]; then
+    echo "[ ${0} ] ${*}"
+  else
+    # if remainder is empty that means no emoji was passed
+    if [ -z "$remainder" ]; then
+      echo "[ ${0} ] ${*}"
+    else # emoji was passed, but we ignore it
+      echo "[ ${0} ] ${remainder}"
+    fi
+  fi
+}
+
+# Output a debug message if BRUT_WORKSPACE_DEBUG is set
+debug() {
+  message=$1
+  if [ -z "${BRUT_WORKSPACE_DEBUG}" ]; then
+    return
+  fi
+  log "🐛" "${message}"
+}
+
+# Output general usage information for the command and exit zero.
+#
+# Args:
+#
+# [1] the description of the command
+# [2] The names of the arguments
+# [3] If given, the name of the pre hook that the command responds to
+# [4] If given, the name of the post hook that the command responds to
+usage() {
+  description=$1
+  arg_names=$2
+  pre_hook=$3
+  post_hook=$4
+  echo "usage: ${0} [-h] ${arg_names}"
+  if [ -n "${description}" ]; then
+    echo
+    echo "DESCRIPTION"
+    echo "    ${description}"
+  fi
+  if [ -n "${pre_hook}" ] || [ -n "${post_hook}" ]; then
+    echo
+    echo "HOOKS"
+    if [ -n "${pre_hook}" ]; then
+      echo "    ${pre_hook} - if present, called before the main action"
+    fi
+    if [ -n "${post_hook}" ]; then
+      echo "    ${post_hook} - if present, called after the main action"
+    fi
+  fi
+  exit 0
+}
+
+# Show usage if the command line invocation indicated that help was requested.
+# This calls usage, so this will exit 0
+#
+# Args:
+#
+# [1] the description of the command
+# [2] The names of the arguments
+# [3] If given, the name of the pre hook that the command responds to
+# [4] If given, the name of the post hook that the command responds to
+usage_on_help() {
+  description=$1
+  arg_names=$2
+  pre_hook=$3
+  post_hook=$4
+  # These are the args passed to the invocation so this
+  # function can determine if the user requested help
+  cli_args=( "${@:5}" ) 
+
+  for arg in "${cli_args[@]}"; do
+    if [ "${arg}" = "-h" ] || [ "${arg}" = "--help" ]; then
+      usage "${description}" "${arg_names}" "${pre_hook}" "${post_hook}"
+    fi
+  done
+}
+
+# Ensure that a command line utility exists, exiting nonzero if not.
+# This is needed to avoid assumptions about what commands a user may have
+# on their computer. It attempts to provide a more useful error message
+# than "command not found".
+require_command() {
+  command_name=$1
+  if ! command -v "${command_name}" >/dev/null 2>&1; then
+    fatal "Command '${command_name}' not found - it is required for this script to run"
+  fi
+}
+
+# This loads dx/docker-compose.env as variables to the bash script, thus
+# allowing Docker Compose and these scripts to share configuration.
+load_docker_compose_env() {
+  . "${ENV_FILE}"
+}
+
+# Execute a hook if the file exists.  Note that if the hook exits
+# nonzero, the caller will need to check the return value of this function and decide
+# what to do.
+exec_hook_if_exists() {
+  script_name=$1
+  shift
+  if [ -x "${SCRIPT_DIR}"/"${script_name}" ]; then
+    log "🪝" "${script_name} exists - executing"
+    "${SCRIPT_DIR}"/"${script_name}" "${@}"
+  else
+    debug "${script_name} does not exist"
+  fi
+}
+
+require_command "realpath"
+require_command "cat"
+
+# Set up the location to the docker-compose.env file.
+ENV_FILE=$(realpath "${SCRIPT_DIR}")/docker-compose.env
+
+# vim: ft=bash

data/mkbrut/templates/Base/dx/exec

@@ -0,0 +1,68 @@
+#!/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_description="Execute a command inside the app's container. Any command other than 'bash' will be run with bash -lc. Use -B to just run the command directly."
+usage_args="[-s service] [-B] command"
+usage_pre="exec.pre"
+usage_on_help "${usage_description}" "${usage_args}" "${usage_pre}" "" "${@}"
+
+SERVICE="${SERVICE_NAME:-${DEFAULT_SERVICE}}"
+INCLUDE_PREFIX_FOR_NON_BASH=true
+while getopts "s:B" opt "${@}"; do
+  case ${opt} in
+    s )
+      SERVICE="${OPTARG}"
+      ;;
+    B )
+      INCLUDE_PREFIX_FOR_NON_BASH=false
+      ;;
+    \? )
+      log "🛑" "Unknown option: ${opt}"
+      usage "${description}" "${usage_args}" "${usage_pre}"
+      ;;
+    : )
+      log "🛑" "Invalid option: ${opt} requires an argument"
+      usage "${description}" "${usage_args}" "${usage_pre}"
+      ;;
+  esac
+done
+shift $((OPTIND -1))
+
+if [ $# -eq 0 ]; then
+  log "🛑" "You must provide a command e.g. bash or ls -l"
+  usage "${description}" "${usage_args}" "${usage_pre}"
+fi
+
+if ! exec_hook_if_exists "exec.pre"; then
+  log "build.pre failed"
+  exit 1
+fi
+
+if [ "$#" -eq 1 ] && [ "$1" = "bash" ]; then
+  COMMAND=(bash)
+elif [ "$INCLUDE_PREFIX_FOR_NON_BASH" = "true" ]; then
+  COMMAND=(bash -lc "$*")
+else
+  COMMAND=("$@")
+fi
+
+log "🚂" "Running '${COMMAND[@]}' inside container with service name '${SERVICE}'"
+
+docker \
+  compose \
+    --file docker-compose.dx.yaml \
+    --project-name "${PROJECT_NAME}" \
+    --env-file "${ENV_FILE}" \
+  exec \
+    "${SERVICE}" \
+    "${COMMAND[@]}"
+
+# vim: ft=bash

data/mkbrut/templates/Base/dx/prune

@@ -0,0 +1,19 @@
+#!/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 "Prune containers for this repo" "" "" "" "${@}"
+
+for container_id in $(docker container ls -a -f "name=^${PROJECT_NAME}-.*-1$" --format="{{.ID}}"); do
+  log "🗑" "Removing container with id '${container_id}'"
+  docker container rm "${container_id}"
+done
+echo "🧼" "Containers removed"
+
+# vim: ft=bash

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