brut 0.4.0 → 0.8.0

data/mkbrut/templates/Base/Dockerfile.dx

@@ -0,0 +1,205 @@
+# This file is heavily documented to explain what is going on and why.
+# If you are reading this, however, you now own this file and can
+# change it how you like. Just be sure you understand how it works in the
+# context of docker-compose.dx.yml and the files in dx/,
+# which are referred to as the Workspace
+#
+# This file is a set of instructions to build a Docker _image_, which is
+# then use to _start_ a _container_.
+
+# This uses a base image where Ruby is already installed. This saves
+# us from having to install Ruby ourselves.  Change this whenever you update
+# Ruby. Note that by convention, "3.4" will be whatever the latest point
+# release of Ruby 3.4 is. If you don't want that, specify an exact Ruby version here.
+# Note that this value is intended to be in sync with the tag of the image
+# found in dx/docker-compose.env
+FROM ruby:3.4
+
+# This attempts to make RUN directives fail when UNIX pipelines are involved
+SHELL [ "/bin/bash", "-o", "pipefail", "-c" ]
+
+# This tells apt-get and friends not to ask for interactive input
+# as this creates massive confusion in the context of building a Docker image.
+ENV DEBIAN_FRONTEND=noninteractive
+
+# These packages are needed to set up other repos to install other
+# packages and/or are useful in installing other software
+#
+# - ca-certificates  - needed by Postgres client
+# - curl             - needed by various installation instructions
+# - gnupg            - needed to install Docker
+# - lsb-release      - needed by Postgres install instructions
+# - rsync            - needed by Brut's build_assets command
+# - vim              - needed when we want to edit files inside container
+RUN apt-get -y clean && \
+    apt-get -y update && \
+    apt-get install --quiet --yes \
+      ca-certificates \
+      curl \
+      gnupg \
+      lsb-release \
+      rsync \
+      vim
+
+# These are dependencies needed to install Chromium via Playright.
+# You can check this list via
+#
+#     npx playwright install-deps --dry-run chromium
+#
+RUN apt-get install -y --no-install-recommends libasound2 \
+                                               libatk-bridge2.0-0 \
+                                               libatk1.0-0 \
+                                               libatspi2.0-0 \
+                                               libcairo2 \
+                                               libcups2 \
+                                               libdbus-1-3 \
+                                               libdrm2 \
+                                               libgbm1 \
+                                               libglib2.0-0 \
+                                               libnspr4 \
+                                               libnss3 \
+                                               libpango-1.0-0 \
+                                               libx11-6 \
+                                               libxcb1 \
+                                               libxcomposite1 \
+                                               libxdamage1 \
+                                               libxext6 \
+                                               libxfixes3 \
+                                               libxkbcommon0 \
+                                               libxrandr2 \
+                                               xvfb \
+                                               fonts-noto-color-emoji \
+                                               fonts-unifont \
+                                               libfontconfig1 \
+                                               libfreetype6 \
+                                               xfonts-scalable \
+                                               fonts-liberation \
+                                               fonts-ipafont-gothic \
+                                               fonts-wqy-zenhei \
+                                               fonts-tlwg-loma-otf \
+                                               fonts-freefont-ttf
+
+
+# Install Docker itself. Note that this is installed only what is needed to run
+# the Docker CLI - the docker-compose.dx.yml will connect this docker's socket
+# to the one on the host. This sets up "Docker outside Docker" and
+# is here only to build the production Docker containers and to push
+# them to a repository. This is not intended to run containers from
+# inside this one.
+RUN install -m 0755 -d /etc/apt/keyrings && \
+    curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \
+    chmod a+r /etc/apt/keyrings/docker.gpg  && \
+    echo \
+      "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
+      "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
+      tee /etc/apt/sources.list.d/docker.list > /dev/null && \
+    apt-get update --quiet --yes && \
+    apt-get install --quiet --yes docker-ce \
+                       docker-ce-cli \
+                       containerd.io \
+                       docker-buildx-plugin \
+                       docker-compose-plugin
+
+
+# Install Postgres Client, per https://www.postgresql.org/download/linux/debian/
+# Note that ca-certificates and curl are installed above
+#
+# Also note that the version here should match the version set up in
+# docker-compose.dx.yml
+RUN sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' && \
+    wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - && \
+    apt-get update && \
+    apt-get -y install postgresql-client-16
+
+# Update RubyGems and Bundler, setting RubyGems not to generate
+# documentation as that is slow and you likely won't use it.
+RUN echo "gem: --no-document" >> ~/.gemrc && \
+    gem update --system && \
+    gem install bundler
+
+# Installs the Heroku CLI, per Heroku docs at 
+# https://devcenter.heroku.com/articles/heroku-cli#install-with-ubuntu-debian-apt-get
+RUN curl https://cli-assets.heroku.com/install-ubuntu.sh | sh
+
+# Up to now, RUN directives ran as the root user.  When using this container
+# for development, we do not want to run as the root user.  On macOS, this is not 
+# a big deal, but in Linux, the root user inside this container can create files
+# as the root user on your computer. You don't want that.
+
+# What is tricky is that we ultimately want the non-root user here
+# to have the same UID and same groups as your user on your host/computer.
+# And, we want that user to be able to run Docker commands.
+
+# First, set up some build args that `dx/build` will override with the actual values.
+# The reason these all have values is that Docker will not fail if they are omitted,
+# but it will behave strangely.
+#
+# Their user id, which ideally is overridden to match your user id on the host
+ARG user_uid=10001
+
+# Their group id, which ideally is overridden to match your group id on the host
+ARG user_gid=10002
+
+# The group id that can access /var/run/docker.sock on the host.
+# If this isn't mapped properly, no docker-out-of-docker commands will work
+ARG docker_gid=10003
+
+# This can be blank if the OS is such that the user inside the container can access
+# /var/run/docker.sock simply from being in docker_gid.  If this is not
+# the case (as on macOS), it is not only sad, but we must add the group
+# 0 (root) to the groups our new user is in.
+ARG sadly_user_must_be_added_to_root=
+
+# Create the user's group ID if it does not exist
+RUN getent group ${user_gid} || groupadd --gid ${user_gid} appgroup
+
+# Create the docker group id if it does not exist
+RUN getent group ${docker_gid} || groupadd --gid ${docker_gid} hostdocker
+
+# Create the user and set up their shell.
+# Note that we put bash_customizations in both .profile and .bashrc
+# to increase the chances they are used when running bash in various configurations
+RUN useradd --uid ${user_uid} --gid ${user_gid} --groups ${sadly_user_must_be_added_to_root}${docker_gid} --create-home --home-dir /home/appuser appuser && \
+    echo ". ~/.bash_customizations" >> /home/appuser/.profile && \
+    echo ". ~/.bash_customizations.local" >> /home/appuser/.profile && \
+    echo ". ~/.bash_customizations" >> /home/appuser/.bashrc && \
+    echo ". ~/.bash_customizations.local" >> /home/appuser/.bashrc
+
+# Now we must grant ownership to the new user over various files they will need to
+# run or use
+COPY --chown=appuser:${user_gid} dx/show-help-in-app-container-then-wait.sh /home/appuser
+COPY --chown=appuser:${user_gid} dx/bash_customizations /home/appuser/.bash_customizations
+COPY --chown=appuser:${user_gid} dx/bash_customizations.local /home/appuser/.bash_customizations.local
+
+# This switches to the new user, meaniung all subsequent RUN directives will
+# be run as this user.  The USER directive allows changing both the user
+# and the current group. We are omitting the group part of that because
+# to include would exclude the user from all other groups we just set them up
+# as belonging to.
+USER appuser
+
+# Install NodeJS, per https://nodejs.org/en/download
+#
+# Yes, this is seting up nvm just to install one version of node we will ever user in
+# here and yes, this sucks.  But it's better to use the vendor's official
+# recommendation.
+RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash && \
+    \. "$HOME/.nvm/nvm.sh" && \
+    nvm install 22 && \
+    node -v && nvm current && npm -v
+
+
+
+# This arg should have the version of playwright present in the app's Gemfile.lock.
+# This is because the playright NodeJS library and the Ruby gem must have the same
+# version or things won't work right.  The value is blank because it really has to be
+# detected during `dx/build`.
+ARG PLAYWRIGHT_VERSION
+# Now install the version of Playwright we detected as well as Chromium. NOTE, we
+# must install Chromium, not chrome, because there is no version of Chrome for an
+# ARM-based Debian linux, which is what this Dockerfile will build on an Apple
+# Silicon Mac.
+RUN \. "$HOME/.nvm/nvm.sh" && \
+    nvm use default && \
+    npm install -g playwright@$PLAYWRIGHT_VERSION && \
+    npx playwright install chromium

data/mkbrut/templates/Base/Gemfile.erb

@@ -0,0 +1,53 @@
+source "https://rubygems.org"
+
+# Gemfile organization:
+#
+# 1. Brut is always at the top
+# 2. The rest of the gems are in alphabetical order
+# 3. Do not specify a gem version unless there is a specific reason.
+# 4. Each gem should have a comment preceding it explaining
+#    what the gem is for and why the project needs it.
+# 5. If a version was specified, make sure the comment explains
+#    why it had to be specified and the conditions under which it
+#    can be removed.
+# 6. Do not create group blocks. Instead, use the group: option for each
+#    gem.  This creates a single clean list of gems in order.
+
+gem "brut", "<%= versions.brut_version_specifier %>"
+
+# Audit our dependencies
+gem "bundler-audit", groups: [ :test ]
+
+# This allows us to make assertions about test setup that are not themselves tests
+gem "confidence-check", groups: [ :test ]
+
+# Dotenv manages the environment variables in the development
+# and test environments. See .env.development, .env.development.local,
+# and .env.test
+gem "dotenv", groups: [ :development, :test ]
+
+# FactoryBot manages test and seed data
+gem "factory_bot", groups: [ :development, :test ]
+
+# Faker is used to create realistic data for test and seed data.
+gem "faker", groups: [ :development, :test ]
+
+
+# We use Postgres
+gem "pg"
+
+# Allows using Playwright from Ruby.
+# We lock the version because it must be the same as the verison
+# of playwright in package.json.  This ensures that we can reliably
+# install the right browsers and that everything will work right.
+gem "playwright-ruby-client", "1.52.0", groups: [ :test ]
+
+# Sinatra needs a webserver and puma is the best
+gem "puma"
+
+# Uses RSpec for testing
+gem "rspec", groups: [ :test ]
+
+# Allows for diagnosing failing tests
+gem "with_clues", groups: [ :test ]
+

data/mkbrut/templates/Base/Procfile.development

@@ -0,0 +1,5 @@
+web:             PORT=6502 bin/run
+css:                       bin/watch-and-build-assets css
+js:                        bin/watch-and-build-assets js
+images:                    bin/watch-and-build-assets images
+startup_message: PORT=6502 bin/startup-message

data/mkbrut/templates/Base/Procfile.test

@@ -0,0 +1 @@
+web:    PORT=6503 bin/run

data/mkbrut/templates/Base/README.md

@@ -0,0 +1,4 @@
+# Workspace
+
+The *workspace* is the part of the dev environment that runs directly on the
+developer's machine. It is made up of Bash and Docker.

data/mkbrut/templates/Base/README.md.erb

@@ -0,0 +1,40 @@
+# <%= app_name %>
+
+A great new app!
+
+## Setup
+
+1. Clone this repo
+2. Ensure you have Docker installed
+3. Build the Foundation of your dev environment:
+
+   ```
+   dx/build
+   ```
+4. Start it up:
+
+   ```
+   dx/start
+   ```
+5. In another terminal, shell into the container you just started:
+
+   ```
+   dx/exec bash
+   ```
+6. Run setup:
+
+   ```
+   dx/setup
+   ```
+7. Start the app:
+
+   ```
+   bin/dev
+   ```
+
+8. Visit `http://localhost:6502`
+9. Now get to work!
+
+
+
+

data/mkbrut/templates/Base/app/bootstrap.rb

@@ -0,0 +1,61 @@
+# Handles the configuration and startup process for your Brut-powered
+# app and anything that needs its configuration, such as a CLI.
+#
+# This class models three phases:
+#
+# 1. *Initialized* - Ruby is running, but no Brut configuration has happened.
+#
+#    ```ruby
+#    bootstrap = Bootstrap.new
+#    ```
+# 2. *Configured* - Brut's static configuration is set up.
+#    See `Brut::Framework::MCP.initialize`.
+#
+#    ```ruby
+#    configured = bootstrap.configure_only!
+#    ```
+#
+# 3. *Bootstrapped* - Everything is set up and configured, services
+#    have been connected-to and the app is generally ready to receive
+#    requests or have its logic executed.
+# 
+#    ```ruby
+#    booted = configured.bootstrap!
+#    ```
+class Bootstrap
+
+  def configure_only!
+    require "bundler"
+
+    Bundler.require(:default, ENV.fetch("RACK_ENV").to_sym)
+
+    require "brut"
+    require "pathname"
+
+    Brut.container.store_required_path(
+      "project_root",
+      "Root of the entire project's source code checkout",
+      (Pathname(__dir__) / "..").expand_path)
+
+
+    $: << File.join(Brut.container.project_root,"app","src")
+
+    require "app"
+
+    @mcp = Brut::Framework::MCP.new(app_klass: ::App)
+    @app = @mcp.app
+    self
+  end
+
+  attr_reader :rack_app, :app
+
+  # @return [Bootstrap::ConfiguredBootstrap] that contains
+  #         the {Brut::Framework::App} and {Brut::Framework::MCP}.
+  def bootstrap!
+    self.configure_only!
+    @mcp.boot!
+    @rack_app = @mcp.sinatra_app.new
+    self
+  end
+
+end

data/mkbrut/templates/Base/app/config/i18n/en/1_defaults.rb

@@ -0,0 +1,128 @@
+# Brut's defaults for various strings required by Brut's internals.
+#
+# You are discouraged from changing this file.
+{
+  # en: must be the first entry, thus indicating this is the EN translations
+  en: {
+    time:{
+      formats: { # strftime formats
+        iso_8601: "%Y-%m-%d %H:%M:%S.%6N %Z",
+        full_with_tz: "%Y-%m-%d %H:%M:%S %Z",
+        full: "%Y-%m-%d %H:%M:%S",
+        default: "%Y-%m-%d %H:%M:%S",
+        date: "%a, %b %e, %Y",
+        date_no_dow: "%b %e, %Y",
+        date_no_year: "%a, %b %e",
+        date_no_year_no_dow: "%b %e",
+        month_day_year: "%b %e, %Y",
+        month_day_year_no_year: "%b %e",
+        day_of_week: "%A",
+        time_only: "%l:%M %p",
+      },
+      am: "AM",
+      pm: "PM",
+    },
+    date: {
+      formats: {
+        iso_8601: "%Y-%m-%d",
+        full: "%Y-%m-%d",
+        default: "%a, %b %e, %Y",
+        date: "%a, %b %e, %Y",
+        date_no_dow: "%b %e, %Y",
+        date_no_year: "%a, %b %e",
+        date_no_year_no_dow: "%b %e",
+        month_day_year: "%b %e, %Y",
+        month_day_year_no_year: "%b %e",
+        day_of_week: "%A",
+        day_of_week_short: "%a",
+        time_only: "%l:%M %p",
+      },
+      abbr_day_names: [
+        "Sun",
+        "Mon",
+        "Tue",
+        "Wed",
+        "Thu",
+        "Fri",
+        "Sat",
+      ],
+      day_names: [
+        "Sunday",
+        "Monday",
+        "Tuesday",
+        "Wednesday",
+        "Thursday",
+        "Friday",
+        "Saturday",
+      ],
+      abbr_month_names: [
+        "",
+        "Jan",
+        "Feb",
+        "Mar",
+        "Apr",
+        "May",
+        "Jun",
+        "Jul",
+        "Aug",
+        "Sep",
+        "Oct",
+        "Nov",
+        "Dec",
+      ],
+      month_names: [
+        "",
+        "January",
+        "February",
+        "March",
+        "April",
+        "May",
+        "June",
+        "July",
+        "August",
+        "September",
+        "October",
+        "November",
+        "December",
+      ],
+    },
+    cv: { # short for "constraint violations" to avoid having to type that out
+      this_field: "This field",
+      cs: { # short for "client-side", again to not have to type it out
+            # These keys use camel-case because that is how the browser defines
+            # these values, based on ValidityState
+        badInput: "%{field} is the wrong type of data",
+        patternMismatch: "%{field} isn't in the right format",
+        rangeOverflow: "%{field} is too big",
+        rangeUnderflow: "%{field} is too small",
+        stepMismatch: "%{field} is not a valid value in the range",
+        tooLong: "%{field} is too long",
+        tooShort: "%{field} is too short",
+        typeMismatch: "%{field} is the wrong type",
+        valueMissing: "%{field} is required",
+        general: "Form is invalid",
+      },
+      ss: { # short for "server-side", again not to have to type it out
+            # These are snake case, which is idiomatic for Ruby.  The values
+            # here are all based on DataObjectValidator's behavior
+        required: "%{field} is required",
+        too_short: "%{field} is too short; must be at least %{minlength} characters",
+      },
+    },
+    diagnostics: { # This is to help diagnose issues with the translation system and is not
+                   # intended to store real strings to be used by your app
+      has_interpolations: "Test %{interp} Test",
+      has_pluralizations: {
+        one: "Once!",
+        other: "More than once!"
+      },
+      has_pluralizations_and_zero: {
+        zero: "ZERO",
+        one: "ONE",
+        other: "MORE",
+      },
+      simple1: "SIMPLE1",
+      simple2: "SIMPLE2",
+    }
+  },
+}

data/mkbrut/templates/Base/app/config/i18n/en/2_app.rb

@@ -0,0 +1,24 @@
+# All app-specific translations, or overrides of Brut's defaults, go here.
+{
+  # en: must be the first entry, thus indicating this is the EN translations
+  en: {
+    cv: {
+      cs: {
+      },
+      ss: {
+        email_taken: "This email has been taken",
+      },
+    },
+    pages: { # Page-specific messages - this key is relied-upon by Brut to exist
+      HomePage: {
+        title: "Welcome!",
+      }
+    },
+    components: { # Component-specific messages - this key is relied-upon by Brut to exist
+    },
+    clis: { # Messages used in CLIs - this key is relied-upon by Brut to exist
+    },
+    hello: "Hello, and welcome to Brut!",
+    # Other keys can go here and you can organize them however you like.
+  },
+}

data/mkbrut/templates/Base/app/public/static/manifest.json.erb

@@ -0,0 +1,33 @@
+{
+  "name": "<%= app_name %>",
+  "short_name": "<%= app_name %>",
+  "description": "The <%= app_name %> App",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "theme_color": "#A70C00",
+  "icons": [
+    {
+      "src": "/static/images/icon.png"
+    },
+    {
+      "src": "/static/images/apple-touch-icon-120x120.png",
+      "sizes": "120x120"
+    },
+    {
+      "src": "/static/images/apple-touch-icon-152x152.png",
+      "sizes": "152x152"
+    },
+    {
+      "src": "/static/images/apple-touch-icon-167x167.png",
+      "sizes": "167x167"
+    },
+    {
+      "src": "/static/images/apple-touch-icon-180x180.png",
+      "sizes": "180x180"
+    }
+  ]
+}
+
+
+

data/mkbrut/templates/Base/app/src/app.rb.erb

@@ -0,0 +1,37 @@
+class App < Brut::Framework::App
+  def id           = "<%= app_id %>"
+  def organization = "<%= organization %>"
+
+  def initialize
+    # Add additional initialization to this initializers.
+    # Be sure to use the lazy/block form of store because when this code
+    # runs, the app may not have access to networked resources.
+    Brut.container.override("session_class",AppSession)
+    Brut.container.override("external_id_prefix","<%= prefix %>")
+  end
+
+  def boot!
+    # Perform any additional bootstrapping here, such as configuration of
+    # job back-ends or other data stores. When this runs, you can be sure
+    # the app has access to networked resources
+  end
+
+  # Various class methods may be called here to configure your app.  See the API
+  # documentation for Brut::Framework::App.
+
+  # Generic error handler.  Is expected to return a Rack response.
+  error do |exception:, http_status_code:|
+    SemanticLogger["App"].error(exception || "Unknown error", http_status_code:)
+    [ 
+      http_status_code || 500,
+      {},
+      exception&.message || "Internal Server Error '#{http_status_code}'"
+    ]
+  end
+
+  # Declare your app's routes.
+  routes do
+    page "/" # Special route for HomePage
+  end
+end
+

data/mkbrut/templates/Base/app/src/back_end/data_models/app_data_model.rb

@@ -0,0 +1,5 @@
+AppDataModel = Class.new(Sequel::Model)
+# Base class for all your data models
+class AppDataModel
+end
+

data/mkbrut/templates/Base/app/src/back_end/data_models/db.rb

@@ -0,0 +1,19 @@
+# Namespace for all data models.  This makes it easy
+# to avoid the conflation of database table models from
+# domain models.
+module DB
+  # Execute the code in the block in a database transaction.
+  # This calls `Sequel::Model.db.transaction`, which is ultimately
+  # `Sequel::Database#transaction`. Please review that documentation as well
+  # as the documentation of your databnase so you understand
+  # how transactions work.
+  #
+  # @see https://rubydoc.info/gems/sequel/5.93.0/Sequel/Database#transaction-instance_method
+  def self.transaction(opts=:use_default,&block)
+    if opts == :use_default
+      opts = Sequel::Database::OPTS
+    end
+    Sequel::Model.db.transaction(opts,&block)
+  end
+end
+

data/mkbrut/templates/Base/app/src/back_end/data_models/migrations/20240101130000_citext.rb

@@ -0,0 +1,6 @@
+Sequel.migration do
+  up do
+    run %{CREATE EXTENSION IF NOT EXISTS citext}
+  end
+end
+

data/mkbrut/templates/Base/app/src/back_end/data_models/seed/seed_data.rb

@@ -0,0 +1,9 @@
+require "brut/back_end/seed_data"
+class SeedData < Brut::BackEnd::SeedData
+  include FactoryBot::Syntax::Methods
+  def seed!
+    # Create records here.  This method is not expected
+    # to be idempotent.  You can (and should) use your 
+    # FactoryBot factories here.
+  end
+end

data/mkbrut/templates/Base/app/src/front_end/components/app_component.rb

@@ -0,0 +1,8 @@
+# Base class for your app's components.
+class AppComponent < Brut::FrontEnd::Component
+  include Brut::Framework::Errors    # provides access to methods in this module
+  include Brut::FrontEnd::Components # Allows Brut-provided components to be
+                                     # used as a Phlex "kit"
+  include CustomElementRegistration
+end
+

data/mkbrut/templates/Base/app/src/front_end/components/custom_element_registration.rb.erb

@@ -0,0 +1,7 @@
+# Registers your app's autnomous custom elements
+# with Phlex, so you can use them like normal HTML elements.
+module CustomElementRegistration
+  def self.included(other)
+    other.register_element :<%= prefix %>_example
+  end
+end

data/mkbrut/templates/Base/app/src/front_end/css/index.css

@@ -0,0 +1,2 @@
+@import "brut-css/dist/brut.css";
+@import "svgs.css";