brut 0.0.27 → 0.0.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad36cf0ea0c628d6ab48dafc53dfb9253f19ac5df73669e86532970ea70e759d
-  data.tar.gz: fa4dcb2b80e205fb2de2372fe8cfdfd441b6634ab69458287e41f5e681cc507f
+  metadata.gz: 3b77e4a2a30122b1805ecf5cb52a5313bb137c188364a6baac62270918cd1640
+  data.tar.gz: 393ad694666d889d5672fb592e7f188e19f78f519f19fbd4a5edb1af32ef5d21
 SHA512:
-  metadata.gz: a357cccfd1224fcd00d7909670d026a532c1d8cdc0bdd2549a92fad1621370bbdcde707b8fdab0c003ddbe71728018aef2c45201194614025f1b97520775847e
-  data.tar.gz: 042fc9088726c05c0f12b573f54eeb2d7ace79a4552a5756170fb776eaddf5ad895d2a702f1b2e5f05d94f5ff07b7ca4b560e9c3729153441458aa6c3c8e2340
+  metadata.gz: 769c54918d2cb9a3e40e007d954c70ef6ec4033bb1a159d616cc4680aaf5b5d650e0335d729a5acc10b0d9f96574c4dfe5ec5f563bbd82828c6878ea4a532338
+  data.tar.gz: 510b4299c42f476f61110382afdb26c1c71ae8f6aecf16f95bebcf30bb5ac14b0817b08bb0787e3b9b541be59add9e35d4d60df78debbe0627b371aa4639ce00

data/.gitignore

@@ -32,3 +32,9 @@
 /brut-css/dist
 # This is where the CSS lives temporarily while docs are being built
 /brut-css/src/docs/brut.css
+
+# Per-developer Bash customizations that could contain secrets
+/dx/bash_customizations.local
+
+# Gems are installed here for LSP convienience
+/local-gems

data/.projections.json

@@ -0,0 +1,10 @@
+{
+  "lib/*.rb": {
+    "alternate": "specs/{}.spec.rb",
+    "type": "source"
+  },
+  "specs/*.spec.rb": {
+    "alternate": "lib/{}.rb",
+    "type": "spec"
+  }
+}

data/.rspec

@@ -0,0 +1,3 @@
+-I specs
+--require spec_helper
+-P "specs/**/*.spec.rb"

data/Dockerfile.dx

@@ -10,28 +10,46 @@ RUN apt-get -y clean && \
     apt-get -y update && \
     apt-get install --quiet --yes ca-certificates curl gnupg rsync
 
-# Install NODE per https://github.com/nodesource/distributions?tab=readme-ov-file#using-debian-as-root-nodejs-22
-RUN curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/nodesource_setup.sh && \
-    bash /tmp/nodesource_setup.sh && \
-    apt-get install -y nodejs
-
-# Install Postgres client per https://www.postgresql.org/download/linux/debian/ - note that the 
-# automated configuration doesn't work, I think because it assumes non-root.
-RUN apt-get -y install lsb-release && \
-    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
-
 RUN echo "gem: --no-document" >> ~/.gemrc && \
     gem update --system && \
     gem install bundler
-
 # Need vim at all times
 ENV EDITOR=vim
 RUN apt-get install -y vim && \
     echo "set -o vi" >> /root/.bashrc
 
+
+# Setup a non-root user
+
+# Their user id, which ideally matches their user id on the host
+ARG user_uid=10001
+# Their group id, which ideally matches their group id on the host
+ARG user_gid=10002
+
+# Create the user's group ID if it does not exist
+RUN getent group ${user_gid} || groupadd --gid ${user_gid} appgroup
+# Create the user. 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} --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
+
+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
+
+# NOT including the group here as that will place the user's environment
+# ONLY in that group and not in all the groups in which they are a part.
+USER appuser
+
+# Install NodeJS, per https://nodejs.org/en/download
+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
+
 # Node's colors are hand-crafted to always look bad and render at least some text unreadable 
 # no matter what your setup. Cool.
 ENV NODE_DISABLE_COLORS=1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.0.27)
+    brut (0.0.29)
       concurrent-ruby
       i18n
       irb

data/bin/docs

@@ -14,14 +14,36 @@ OptionParser.new do |opts|
   end
 end.parse!
 
-public_dir = (Pathname(__FILE__).dirname / ".." / "brutrb.com" / "public" ).expand_path.to_s
-docs_dir   =  public_dir + "/api"
+public_dir = (Pathname(__FILE__).dirname / ".." / "brutrb.com" / "public" ).expand_path
+docs_dir   =  public_dir / "api"
 brutjs_dir = (Pathname(__FILE__).dirname / ".." / "brut-js" ).expand_path.to_s
 
 system(
   "bundle exec yard doc -o '#{docs_dir}' -m markdown -M rdiscount --backtrace"
 )
 
+puts "Hacking CSS"
+[
+  docs_dir /  "css" / "style.css",
+  docs_dir /  "css" / "full_list.css"
+].each do |css_file_to_hack|
+  lines = File.read(css_file_to_hack).split(/\n/)
+  File.open(css_file_to_hack, "w") do |f|
+    lines.each do |line|
+      if line =~ /\"Lucida Sans"/
+        f.puts line.gsub(/\"Lucida Sans\"/, '"Helvetica Neue", "Lucida Sans"')
+      elsif line =~ / Monaco,/
+        f.puts line.gsub(/ Monaco,/, '"Courier New", Monaco,')
+      elsif line =~ /font-family: monospace;/
+        f.puts line.gsub(/font-family: monospace;/, 'font-family: "Courier New", monospace;')
+      else
+        f.puts line
+      end
+    end
+    f.puts "code { font-family: 'Courier New', monospace; font-weight: 600; }"
+  end
+end
+
 FileUtils.chdir brutjs_dir do
   system("bin/build")
 end

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -83,7 +83,7 @@ def setup(update_gems:,setup_credentials:)
       system! "ssh-add #{key_file}"
     end
 
-    known_hosts_dest = Pathname("/") / "root" / ".ssh" / "known_hosts"
+    known_hosts_dest = Pathname("/") / "home" / "appuser" / ".ssh" / "known_hosts"
     if known_hosts_dest.exist?
       log "#{known_hosts_dest} exists, your ssh key should work with GitHub"
     else
@@ -117,7 +117,7 @@ def setup(update_gems:,setup_credentials:)
     end
     log "Your ssh key looks good"
 
-    gem_credentials_dest = Pathname("/") / "root" / ".gem" / "credentials"
+    gem_credentials_dest = Pathname("/") / "home" / "appuser" / ".gem" / "credentials"
     if gem_credentials_dest.exist?
       log "Gem credentials look good"
     else
@@ -139,7 +139,7 @@ def setup(update_gems:,setup_credentials:)
       end
     end
 
-    npm_credentials_dest = Pathname("/") / "root" / ".npmrc"
+    npm_credentials_dest = Pathname("/") / "home" / "appuser" / ".npmrc"
     if npm_credentials_dest.exist?
       log "NPM credentials look good"
     else

data/brutrb.com/.vitepress/config.mjs

@@ -39,6 +39,7 @@ export default defineConfig({
         items: [
           { text: "Routes", link: "/routes" },
           { text: "Pages", link: "/pages" },
+          { text: "Layouts", link: "/layouts" },
           { text: "Forms", link: "/forms" },
           { text: "Handlers and Actions", link: "/handlers" },
           { text: "Components", link: "/components" },

data/brutrb.com/.vitepress/theme/custom.css

@@ -5,3 +5,10 @@
 .image-bg {
   display: none;
 }
+td > code {
+  white-space: nowrap;
+}
+
+.VPHero img, .VPHome img {
+  border-radius: 0.5rem;
+}

data/brutrb.com/.vitepress/theme/style.css

@@ -51,13 +51,14 @@
 
   --blue-vp-c-brand-1: #0C00A7;
   --blue-vp-c-brand-2: #6357FF;
-  --blue-vp-c-brand-3: #1000E2;
-  --blue-vp-c-brand-soft: #FAF9FF;
+  --blue-vp-c-brand-3: #4C0606;
+  --blue-vp-c-brand-soft: #FFF9F9;
+
+  --vp-c-brand-1: #362400;
+  --vp-c-brand-2: #F1A100;
+  --vp-c-brand-3: #281B00;
+  --vp-c-brand-soft: #FFF1D6;
 
-  --vp-c-brand-1: #A70C00;
-  --vp-c-brand-2: #FF6357;
-  --vp-c-brand-3: #e21000;
-  --vp-c-brand-soft: #FFE7E5;
 
   --xvp-c-brand-1: var(--vp-c-indigo-1);
   --xvp-c-brand-2: var(--vp-c-indigo-2);
@@ -69,15 +70,25 @@
   --vp-c-tip-3: var(--vp-c-brand-3);
   --vp-c-tip-soft: var(--vp-c-brand-soft);
 
-  --vp-c-warning-1: var(--vp-c-yellow-1);
-  --vp-c-warning-2: var(--vp-c-yellow-2);
-  --vp-c-warning-3: var(--vp-c-yellow-3);
-  --vp-c-warning-soft: var(--vp-c-yellow-soft);
-
-  --vp-c-danger-1: var(--vp-c-red-1);
-  --vp-c-danger-2: var(--vp-c-red-2);
-  --vp-c-danger-3: var(--vp-c-red-3);
-  --vp-c-danger-soft: var(--vp-c-red-soft);
+  --xvp-c-warning-1: var(--vp-c-yellow-1);
+  --xvp-c-warning-2: var(--vp-c-yellow-2);
+  --xvp-c-warning-3: var(--vp-c-yellow-3);
+  --xvp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-warning-1: #9E5601;
+  --vp-c-warning-2: #FDAF53;
+  --vp-c-warning-3: #5E3301;
+  --vp-c-warning-soft: #FFF3E5;
+
+  --vp-c-danger-1: #AC0E0E;
+  --vp-c-danger-2: #F14E4E;
+  --vp-c-danger-3: #4C0606;
+  --vp-c-danger-soft: #FFF9F9;
+
+  --xvp-c-danger-1: var(--vp-c-red-1);
+  --xvp-c-danger-2: var(--vp-c-red-2);
+  --xvp-c-danger-3: var(--vp-c-red-3);
+  --xvp-c-danger-soft: var(--vp-c-red-soft);
 }
 
 /**

data/brutrb.com/deployment.md

@@ -1,66 +1,144 @@
 # Deployment
 
 Brut apps are Rack apps, so they can be deployed in conventional
-ways.   Brut apps are 12-factor apps and the scripts used for
-development are inteded to work for production as well.
+ways.
 
 ## Overview
 
-Everyone deploys apps in different ways.  Brut can't provide a
-simple solution for all deployment setups, so this document will
-outline considerations when setting up deployment.
+There are just too many ways to deploy.  Brut attempts to address this by adhering to [12-factor principles](https://12factor.net).  Brut also tries not to create artifacts like `Procfile` or `Dockerfile` that would conflict with the artifacts you'd need to manage deployment.
 
-The most direct way to understand what needs to happen is to look
-at `deploy/Dockerfile`, which is the foundation of a `Dockerfile`
-you can use.  In particular, it shows you the commands needed to
-setup and run the app in production:
+That said, Brut includes first-class support for deploying to Heroku using containers.  More options will be included as necessary, either through direct support in code/tooling, or documentation here.
 
-Beyond installing system software to run any Ruby web app, as well
-as whatever is needed for NodeJS and Postgres, the Brut-specific
-parts look like so:
+### Heroku Container-based Deployment
 
-1. Install Ruby Gems with `bundle install`
-2. Install Node modules with `npm clean-install`
-3. Build all assets with `bin/build-assets` (this will bundle all
-   CSS and Javascript, plus copy over any other [assets](/assets)
-   to the locations from where the Brut app will serve them)
-4. Run the app with `bin/run`
+When creating your Brut app with `mkbrut`, the Heroku segment can be used to create files and scripts for a [Heroku container-based deployment](https://devcenter.heroku.com/articles/container-registry-and-runtime).
 
-Your Brut app also includes `bin/release` which is a script
-intended to run in the production environment after the code has
-been deployed, but before the app starts up.  By default, it
-applies any needed migrations to the database.
+| File | Purpose | Notes |
+|------|---------|-------|
+| `bin/deploy` | Script to use to perform the deployment | This wraps `HerokuContainerBasedDeploy` in `Brut::CLI::Apps` |
+| `deploy/Dockerfile` | Template `Dockerfile` used to create a `Dockerfile` for each process type | Heroku requires each process (web, worker, release, etc.) to have its own `Dockerfile` and own image |
+| `deploy/heroku_config.rb` | Class that exports optional processes | By default, your app has a web and release process. `HerokuConfig` can export others, like Sidekiq |
+| `deploy/docker-entrypoint` | The [`ENTRYPOINT`](https://docs.docker.com/reference/dockerfile/#entrypoint) for production Docker images, which is set up to use jemalloc | You can modify or remove this as needed |
+
+How to deploy:
+
+1. Auth to Heroku from inside your dev container:
+
+   ```
+   your-computer> dx/exec bash
+   devcontainer> heroku auth:login
+   # You will need to copy/paste the URL to log in
+   devcontainer> heroku container:login
+   ```
+
+2. Create your app using the container stack:
+
+   ```
+   > heroku create --stack container -a «your heroku app name»
+   ```
+3. Ensure your app's source code is all checked in, there are no uncommitted or unadded files, and you have pushed to main.
+4. `bin/deploy`
+
+   This will generate a `Dockerfile` for each process (by default, `Dockerfile.web` and `Dockerfile.release`), build images, push those images to Heroku, and ask Heroku to release them.
+
+Debugging Tips:
+
+* Keep in mind it's hard to make general deployment tools. You are expected to understand your deployment and be capable of deploying an arbitrary Rack app manually.  Brut's tooling automates what you need to know.
+* `bin/deploy` runs the `deploy` subcommand, so `bin/deploy help deploy` can provide
+some options for debugging issues:
+
+  ```
+  devcontainer> bin/deploy help deploy
+  Usage: bin/deploy [global options] deploy [command options] 
+
+      Build images, push them to Heroku, and deploy them
+
+      Manages a deploy process based on using Heroku's Container Registry. See
+
+      https://devcenter.heroku.com/articles/container-registry-and-runtime
+
+      for details. You are assumed to understand this.
+      This command will make the process somewhat easier.
+
+      This will use deploy/Dockerfile as a template to create
+      one Dockerfile for each process you want to run in Heroku.
+      deploy/heroku_config.rb is where the processes and their
+      commands are configured.
+
+      The release phase is included automatically, based on bin/release.
+
+  GLOBAL OPTIONS
+
+      -h, --help            Get help
+          --log-level=LEVEL Set log level. Allowed values: debug,
+                            info, warn, error, fatal. Default 'fatal'
+          --verbose         Set log level to 'debug', which will produce
+                            maximum output
+
+  ENVIRONMENT VARIABLES
+
+      BRUT_CLI_RAISE_ON_ERROR - if set, shows backtrace on errors
+      LOG_LEVEL               - log level if --log-level or --verbose is omitted
+
+
+  COMMAND OPTIONS
+
+          --platform=PLATFORM  Override default platform. Can be any Docker
+                               platform.
+          --[no-]dry-run       Print the commands that would be run and
+                               don't actually do anything. Implies --skip-checks
+          --[no-]skip-checks   Skip checks for code having been
+                               committed and pushed
+          --[no-]deploy        After images are pushed, actually deploy them
+          --[no-]push          After images are created, push them
+                               to Heroku's registry. If false,
+                               implies --no-deploy
+  ```
+* Try building images first: `bin/deploy deploy --no-push --skip-checks`
+* It's possible to run the images locally.  If you are on Apple Silicon, you'll
+  need to set --platform:
+
+  * `bin/deploy deploy --no-push --skip-checks --platform linux/arm64`
+  * Create `docker-compose.yml` for your image and any other services e.g. databases
+  * Set required environment variables in `docker-compose.yml`
+  * Start up Docker compose and poke around
+
+  You'll need to have a better understanding of Docker to do this, however if you
+  are deploying with Docker, this is an understanding you hopefully already have.
+
+
+### Other Mechanisms for Deployment
+
+As a Rack app, other deployments should be possible.  To make the app work, you'll need to make sure a few things are dealt with:
+
+* `RACK_ENV` **must** be `"production"`
+* `bin/build-assets` will build all assets by default.  This must either be done on production servers or done ahead of time and the results packaged with the app.
+* `bin/build-assets` outputs files in `app/public` and `app/config`.  Those files are used at runtime.  Brut **will not** initiate the build of any assets.
+* If you are going to build assets on production servers, you *must* included developer tooling. This means NodeJS, all modules in `package.json` and all RubyGems in `Gemfile`.
+
+The `deploy/Dockerfile` created by `mkbrut --segment-heroku` is not very Heroku-specific and could serve as a reference.
 
 ## Testing
 
-If you are using Docker, you can create the `Dockerfile`s and run
-them locally to see how they work.  You will need to have local
-versions of all infrastructure (database, Redis, etc.), but if
-these work locally, there is a high chance they work in
-production.
+Testing deployments is a bit out of scope, but in general:
 
-If you are not using Docker, you will need to apply various
-techniques that are beyond the scope of this documentation.
+* A container-based deployment can theoretically be run on your computer as a test.
+* Non-production, but production-like environments can be used to validate production configurations.
+* You own the means of production…not Brut.
 
 ## Recommended Practices
 
-Brut goes to great lengths to avoid environment-specific code.
-Much of Brut's behavior works the same in dev as it does in
-production. For example, assets are hashed in all environments.
+* Avoid a lot of code that checks `Brut.container.project_env`.  Try to consolidate all prod/test/dev differences in environment variables.
+* Have a way to get a shell into your production environment for debugging.
+* Brut doesn't log much, but if you remove the `OTEL_*` environment variables, Brut will log OTel telemetry to the console, which may be useful. 
+* Setting `OTEL_LOG_LEVEL=debug` is advised if the app isn't starting or you aren't seeing any telemetry or logging
 
-Assuming your code does the same thing, there should be a minium
-of surprises.  That all being said, here are some recommendations:
+## Technical Notes
 
-* Create a way to interact with external services in a testing
-capacity. For example, ensure you have a test user with a known
-email address and trigger an email to them.  Or a company credit
-card you charge and refund.
-* Configure observability so you know what your app is doing at
-all times.
-* Configure a URL that, when accessed, produces an error. This
-allows you to check your error reporting system.
-* Create a page somewhere that shows the git SHA of your
-deployment, or some other unique, unambiguous version number. This
-will clarify what version of the code is actually running.
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
 
+_Last Updated July 3, 2025_
 
+None at this time.

data/brutrb.com/dev-environment.md

@@ -137,16 +137,17 @@ that the versions of these command line apps provided when you set up your app a
 While you are free to set up mise or rbenv or whatever to run all this on your computer, this way of
 working is currently not supported nor encouraged.  For now, Brut will focus on the Docker-based approach.
 
-You are encouraged to understand how it works, especially because the Docker skills you learn in doing so
-will help with production deployment and operations.
+The primary reason is that it's a tightly controlled environment that is almost
+entirely scriptable, but does not require devs to abandon their preffered editor.
+Environment manager-based approaches tend to be more fussy and require documentation
+to ensure they are set up.
 
-Beyond this, we recommend that you keep a few things in mind with respect to automation:
+Keep in mind a few things when adding your own automation:
 
 * The *Foundational Core* is bootstrapped in a degenerate environment without reliable tools beyond Bash.
 This is why it's almost entirely written in Bash, since it's available everywhere and relatively stable.
 * The *Workspace* **can and should** rely on the languages and third party modules that are part of your
-app. Just keep in mind that `bin/setup` can only rely on programming language runtimes and not any
-particular Ruby gem having been installed.
+app. The only exception is `bin/setup`, since it installs third party modules.  As such, it should work entirely based on Ruby and its standard library.
 
 ## Technical Notes
 

data/brutrb.com/doc-conventions.md

@@ -6,7 +6,7 @@ Brut attempts to use existing terminology where possible, particularly where tha
 
 When speaking about Ruby, we prefer the term *initializer* over constructor, *parameters* over arguments, and *methods* over messages.  We also prefer *tests* over specs, however test files *are* located in `specs/` and named `*.spec.rb` to be consistent with RSpec's nomenclature.  We prefer *end-to-end* or *e2e* tests instead of browser tests or request specs. 
 
-Further, Brut doesn't render HTML, it *generates* it.  The browser renders the HTML for the website's visitor.
+Further, Brut doesn't render HTML, it *generates* it.  The browser renders the HTML for the website's visitor. One exception is Phlex, which uses the term *render* to mean "generate HTML to an internal buffer that will be delivered to the client later".  Thus, you will need to call Phlex's `render` method from time to time, even though it is not rendering HTML but helping to generate it.
 
 Lastly, the documentation tries to talk about the person accessing a website as a "vistor" not a "user". Though the "user" nomenclature is near-ossified in software development, we feel "visitor" is more apt.