brut 0.5.0 → 0.8.0

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";

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

@@ -0,0 +1,12 @@
+/* Gives all SVGS a somewhat small height so as CSS loads,
+ * you don't have a big huge SVG */
+svg {
+  width: 1em;
+  height: 1em;
+}
+
+/* Assuming SVGs are monochrome line art,
+ * this ensures the lines are drawn in the current color */
+svg path {
+  fill: currentColor;
+}

data/mkbrut/templates/Base/app/src/front_end/forms/app_form.rb

@@ -0,0 +1,4 @@
+# Base class for your app's forms.
+class AppForm < Brut::FrontEnd::Form
+end
+

data/mkbrut/templates/Base/app/src/front_end/handlers/app_handler.rb

@@ -0,0 +1,4 @@
+# Base class for your app's handlers.
+class AppHandler < Brut::FrontEnd::Handler
+end
+

data/mkbrut/templates/Base/app/src/front_end/images/mkicons.sh

@@ -0,0 +1,6 @@
+set -e 
+magick icon.png -define icon:auto-resize=16,32,48 favicon.ico
+sizes=(120 152 167 180)
+for size in "${sizes[@]}"; do
+  magick icon.png -resize ${size}x${size} apple-touch-icon-${size}x${size}.png
+done

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

@@ -0,0 +1,6 @@
+import { BrutCustomElements } from "brut-js"
+
+document.addEventListener("DOMContentLoaded", () => {
+  BrutCustomElements.define() // Define all of BrutJS's autnomous custom elements
+})
+

data/mkbrut/templates/Base/app/src/front_end/layouts/default_layout.rb.erb

@@ -0,0 +1,73 @@
+# The default layout used by all pages.
+# This code is heavily commented to explain what each 
+# line that isn't hopefully obvious does. Feel free to remove.
+class DefaultLayout < Brut::FrontEnd::Layout
+  include Brut::FrontEnd::Components
+
+  def initialize(page_name:)
+    @page_name = page_name
+  end
+
+  # Brut::FrontEnd::Page's view_template ultimately calls this method
+  # to wrap itself in the layout defined below.
+  def view_template
+    doctype
+    html(lang: "en") do
+      head do
+        meta(charset: "utf-8")
+        meta(content: "width=device-width,initial-scale=1", name:"viewport")
+        meta(content: "website", property:"og:type")
+        # Sets this up as a PWA - see app/public/static/manifest.json
+        link(rel: "manifest",  href: "/static/manifest.json")
+
+        # Load the bundled stylesheet.  asset_path translates the logical
+        # path to the hased value produced by esbuild
+        link(rel: "preload", as: "style", href: asset_path("/css/styles.css"))
+        link(rel: "stylesheet",           href: asset_path("/css/styles.css"))
+
+        # Load the bundled JavaScript.  asset_path translates the logical
+        # path to the hased value produced by esbuild
+        script(defer: true, src: asset_path("/js/app.js"))
+
+        title do
+          "<%= app_name %>"
+        end
+
+        # Brut::FrontEnd::Components::PageIdentifier, which produces
+        # a <meta> tag with the page's name. Useful for end to end tests.
+        PageIdentifier(@page_name)
+
+        # Brut::FrontEnd::Components::I18nTranslations, which includes
+        # translations starting with cv.cs for use with client-side
+        # constraint violation messaging.
+        I18nTranslations("cv.cs")
+        # Brut::FrontEnd::Components::I18nTranslations, which includes
+        # translations for cv.this_field, which is used with client-side
+        # constraint violation messaging.
+        I18nTranslations("cv.this_field")
+        # Brut::FrontEnd::Components::Traceparent, which stores
+        # the OpenTelemetry traceparent in a <meta> attribute for use
+        # by the <brut-tracing> element.
+        Traceparent()
+        # Brut::FrontEnd::Components::LocaleDetection, which
+        # will send the browser's locale and timezone back to the server to
+        # help with locale determination.
+        render(
+          Brut::FrontEnd::RequestContext.inject(
+            Brut::FrontEnd::Components::LocaleDetection
+          )
+        )
+      end
+      # Adds the page's name as a class name. You can use this for
+      # CSS if needed.
+      body(class: @page_name) do
+        # Render the <brut-tracing> element, which will send
+        # OpenTelemetry traces back to the server to be joined up with
+        # the server's traces.
+        brut_tracing url: "/__brut/instrumentation", show_warnings: true
+        yield # Contents of the page are inserted here
+      end
+    end
+  end
+end
+

data/mkbrut/templates/Base/app/src/front_end/pages/app_page.rb

@@ -0,0 +1,11 @@
+# Base class for all pages in the app
+# Note that while Brut::FrontEnd::Page is a subclass
+# of Brut::FrontEnd::Component, that is not the case
+# for your app's pages and components.  Thus, there is a small amount
+# of duplication here.
+class AppPage < Brut::FrontEnd::Page
+  include Brut::Framework::Errors    # See AppComponent
+  include CustomElementRegistration  # See AppComponent
+  include Brut::FrontEnd::Components # See AppComponent
+end
+