brut 0.17.0 → 0.18.0

data/brutrb.com/deployment.md

@@ -1,158 +0,0 @@
-# Deployment
-
-Brut apps are Rack apps, so they can be deployed in conventional
-ways.
-
-## Overview
-
-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.
-
-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.
-
-### Heroku Container-based Deployment
-
-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).
-
-| 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. Get an auth token from Heroku, which you can do from inside the container, and save it to
-   `bash_customizations.local`:
-
-   ```
-   your-computer> dx/exec bash
-   devcontainer> heroku auth:login
-   # You will need to copy/paste the URL to log in
-   devcontainer> heroku authorizations:create -d "container pushes" --expires-in 31536000
-   # Copy the token output by this command
-   devcontainer> echo "HEROKU_API_KEY=«TOKEN YOU COPIED»" >> dx/bash_customizations.local
-   ```
-2. Exit the devcontainer and  stop `dx/start` (e.g. hit `Ctrl-C` wherever you ran it)
-3. Rebuild and restart the devcontainer (this will set `HEROKU_API_KEY` for you)
-
-   ```
-   your-computer> dx/build
-   your-computer> dx/start
-   # In another terminal window
-   your-computer> dx/exec bash
-   devcontainer> echo $HEROKU_API_KEY
-   # You should see the token
-   ```
-
-   Setting this environment variable avoids having to constantly re-authenticate to Heroku.
-
-4. Create your app using the container stack:
-
-   ```
-   > heroku create --stack container -a «your heroku app name»
-   ```
-5. Ensure your app's source code is all checked in, there are no uncommitted or unadded files, and you have pushed to the `main` branch of your remote Git repository.
-6. `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 do based on what you already 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
-
-Testing deployments is a bit out of scope, but in general:
-
-* 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
-
-* 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
-
-## Technical Notes
-
-> [!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

@@ -1,186 +0,0 @@
-# Dev Environment
-
-Brut provides sophisticated tooling to manage your dev environment
-
-## Overview
-
-A development environments or *dev environment* is made up of two parts:
-
-* *Foundational Core* - the operating system and tools needed to run the app and *its* tools. This
-includes language runtimes, system libraries (like ImageMagick), and system tools like web browsers.
-* *Workspace* - the tools and code bundled with the app that you use day-to-day to work on the app itself.
-This would include scripts to run the app in development, run tests, perform scaffolding, or manage the
-database.
-
-On many teams, the Foundational Core is different per developer, since some run Linux, some run MacOs.
-Some might use mise to manage their version of Ruby while others use rbenv.  Some will set up Postgres via
-homebrew, while others might use Popstgres.app.
-
-Brut takes a different approach.  Everyone shares the same Foundational Core, and this is defined by a
-`Dockerfile`, a `docker-compose.yml` file, and some lightweight Bash scripts.
-
-This means that everyone uses the same version of everything, and they are all managed the same way.
-
-Brut also provides sophisticated tooling for the Workspace.  Like Rails, Brut provides a command-line
-based flow that can be scripted into any editor.  Unlike Rails, Brut's Workspace is comprised of separate
-command-line apps and not Rake tasks.
-
-### Conceptual Overview
-
-Your dev environment consists of a Docker container that has languages, an operating system, and other
-system components installed in it.  It will have access to the files on your computer so that it can run
-your app. The app will be exposed so that a browser on your computer can access it.  Postgres will be run
-as a separate Docker container available to the dev Docker container.
-
-Your editor and version control system run on your computer.
-
-![Diagram showing the parts of the dev environment. The foundational core is also
-labeled "Docker containers" and it contains three boxes labeled "Container".  One
-box contains ValKey, another contains Postrgres. The third box contains "Your Brut
-App", "NodeJS", "Ruby", and part of "Source Code". The "Source Code" also also
-partially inside a box containing the foundational core labeled "Your Computer".
-This box contains "Browser" and "source code editor".](/images/DevEnvironment.png)  
-
-### Foundational Core Command Line Apps
-
-These are the commands you will use to manage the *foundational core*, which is the Docker containers and
-their contents.
-
-A few brief terminology notes if you aren't familiar with Docker:
-
-* A Docker *container* is akin to a virtual machine. On Linux this isn't strictly true, but conceptually, you can think of this like a virtual computer.
-* A Docker *image* is what you use to start a container.  This is akin to a disk image you might use to
-create a new computer or virtual machine.
-* A Dockerfile (often named `Dockerfile`) is a set of instructions to create an image.
-
-A few verbs to provide additional help:
-
-* One *builds* a Docker image from a Dockerfile.
-* One *starts* a Docker container from an image.
-* One *stops* a Docker container when it's no longer needed.
-
-
-| App        | Purpose                                                                |
-|------------|------------------------------------------------------------------------|
-| `dx/build` | Builds a Docker *image* from a `Dockerfile.dx`                         |
-| `dx/start` | Starts all Docker containers, including those for databases and caches |
-| `dx/stop`  | Stops all Docker containers                                            |
-| `dx/exec`  | Execute a command inside a running Docker container                    |
-
-The workflow for the foundational core is shown in this diagram.
-
-![Foundational Core Workflow](/images/dev-env-protocol.png)
-
-In words:
-
-1. You build the images based on the latest instructions via `dx/build`.
-2. You start up the environment with `dx/start`.
-3. You then use `dx/exec` to execute commands from the Workspace (see below).
-4. When you are done working for the day, `dx/stop` shuts everything down.
-
-### Workspace Command Line Apps
-
-The workspace is where you'll run your day-to-day commands, such as running tests, starting the dev
-server, managing the database schema, etc.
-
-Several of the commands accept or require subcommands.  Each CLI app responds to `--help` and will show
-you full documentation about what the command and subcommands do.
-
-| App             | Subcommand            | Descriptions                                                                              |
-|-----------------|-----------------------|-------------------------------------------------------------------------------------------|
-| <code style="white-space: nowrap">bin/ci</code>        | None                  | Runs all tests and security checks                                                        |
-| <code style="white-space: nowrap">bin/console</code>   | None                  | Starts up a local IRB session with your app loaded                                        |
-| <code style="white-space: nowrap">bin/db</code>        |                       | Tools for managing the database                                                           |           |
-|                 | `create`              | Create the database if it does not exist                                                  |
-|                 | `drop`                | Drop the database if it exists                                                            |
-|                 | `migrate`             | Apply any outstanding migrations to the database                                          |
-|                 | `new_migration`       | Create a new migration file                                                               |
-|                 | `rebuild`             | Drop, re-create, and run migrations, effectively rebuilding the entire database           |
-|                 | `seed`                | Load seed data into the database                                                          |
-|                 | `status`              | Check the status of the database and migrations                                           |
-| <code style="white-space: nowrap">bin/dbconsole</code> | None                  | Starts up a `psql` session to your database                                               |
-| <code style="white-space: nowrap">bin/dev</code>       | None                  | Starts the app in dev mode, rebuilding assets and reload as needed                        |
-| <code style="white-space: nowrap">bin/setup</code>     | None                  | Install and setup all third party libraries and other configuration needed to use the app |
-| <code style="white-space: nowrap">bin/scaffold</code>  |                       | Generate Brut classes or files like database migrations or page classes                   |
-|                 | `action`              | Create a handler for an action                                                            |
-|                 | `component`           | Create a new component and associated test                                                |
-|                 | `custom_element_test` | Create a test for a custom element in your app                                            |
-|                 | `form`                | Create a form and handler                                                                 |
-|                 | `page`                | Create a new page and associated test                                                     |
-|                 | `db_model`            | Create one or more database models, specs, and factories, plus a migration to create the tables for those models |
-|                 | `test`                | Create the shell of a unit test based on an existing source file                          |
-|                 | `test:e2e`            | Create the shell of an end-to-end test                                                    |
-| <code style="white-space: nowrap">bin/test</code>      |                       | Run tests |
-|                 | `audit`               | Audits all of the app's classes to see if test files exist                                |
-|                 | `e2e`                 | Run e2e tests                                                                             |
-|                 | `js`                  | Run JavaScript unit tests                                                                 |
-|                 | `run`                 | Run non-e2e tests (default)                                                               |
-
-
-The workflow for your Workspace is shown in this diagram
-
-![Workspace Workflow](/images/workspace-protocol.png)
-
-In words:
-
-1. You'll run `bin/setup` to get everything set up for working.
-2. You'll start your dev server with `bin/dev`.
-3. You'll write code, using tools like `bin/db` and `bin/scaffold` to assist.
-4. Using `bin/test`, you can test any code you've written a test for.
-5. When you are at a stopping point, use `bin/ci` to test the entire app.
-
-### Extending and Enhancing
-
-TBD
-
-## Testing
-
-There aren't tests for this code, because you are using all day every day.  Brut's test suite will ensure
-that the versions of these command line apps provided when you set up your app are working.
-
-## Recommended Practices
-
-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.
-
-The primary reason is that it's a tightly controlled environment that is almost
-entirely scriptable, but does not require devs to abandon their preferred editor.
-Environment manager-based approaches tend to be more fussy and require documentation
-to ensure they are set up.
-
-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. 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
-
-> [!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 June 12, 2025_
-
-Everything in `bin/` is intended to be a short shim that calls into classes managed either by Brut or by
-your app. For example, here is `bin/db`:
-
-```ruby
-#!/usr/bin/env ruby
-
-require "bundler"
-Bundler.require
-require "pathname"
-require "brut/cli/apps/db"
-
-exit Brut::CLI.app(
-       Brut::CLI::Apps::DB,
-       project_root: Pathname($0).dirname / ".."
-     )
-```
-
-These files have some duplication, but should be relatively stable.
-
-This means that Brut-provided CLIs *will*  be updated when you update Brut.  Compare this to the files in
-`dx/` which are entire Bash scripts that will not be updated when Brut is updated.

data/brutrb.com/dir-structure.md

@@ -1,120 +0,0 @@
-# Directory Structure
-
-```
-.
-├── app
-│   ├── config
-│   │   └── i18n
-│   │       └── en
-│   ├── public
-│   │   ├── css
-│   │   ├── js
-│   │   └── static
-│   │       └── images
-│   └── src
-│       ├── back_end
-│       │   ├── data_models
-│       │       ├── db
-│       │       ├── migrations
-│       │       └── seed
-│       ├── cli
-│       └── front_end
-│           ├── components
-│           ├── css
-│           ├── fonts
-│           ├── forms
-│           ├── handlers
-│           ├── images
-│           ├── js
-│           ├── layouts
-│           ├── pages
-│           ├── route_hooks
-│           ├── support
-│           └── svgs
-├── bin
-├── deploy
-├── dx
-└── specs
-    ├── back_end
-    │   ├── data_models
-    │       └── db
-    ├── e2e
-    ├── factories
-    │   └── db
-    └── front_end
-        ├── components
-        ├── handlers
-        ├── js
-        ├── pages
-        └── support
-```
-
-## Top Level
-
-| Directory | Purpose |
-|-----------|---------|
-| `app/`    | Contains all configuration and source code specific to your app |
-| `bin/`    | Contains tasks and other CLIs to do development of your app, such as `bin/test` |
-| `dx/`     | Contains scripts to manage your development environment |
-| `specs/`  | Contains all tests |
-
-## Inside `app`/
-
-| Directory | Purpose |
-|-----------|---------|
-| `bootstrap.rb` | A ruby file that sets up your app and ensures everything is `require`d in the right way. |
-| `config/` | Configuration for your app, such as localizations and translations. Brut tries very hard to make sure there is no YAML in here at all. YAML is not good for you. |
-| `public/` | Root of public assets served by the app. |
-| `src/` | All source code for your app |
-
-Inside `app/src`
-
-| Directory | Purpose |
-|-----------|---------|
-| `app.rb` | The core of your app, mostly configuration, such as routes, hooks, middleware, etc. |
-| `back_end/` | Back end classes for your app including database schema, DB models, seed data, and your domain logic |
-| `cli/` | Any CLIs or tasks for your app |
-| `front_end/` | The front-end for your app, including pages, components, forms, handlers, JavaScript, and assets |
-
-Inside `app/src/back_end`
-
-| Directory | Purpose |
-|-----------|---------|
-| `data_models/app_data_model.rb` | Base class for all DB model classes |
-| `data_models/db` | DB model classes |
-| `data_models/db.rb` | Namespace module for DB model classes |
-| `data_models/migrations` | Database schema migrations |
-| `data_models/seed` | Seed data used for local development |
-
-Inside `app/src/front_end`
-
-|Directory       | Purpose |
-|----------------|---------|
-| `components/`  | Component classes |
-| `css/`         | CSS, managed by esbuild and `bin/build-assets` |
-| `fonts/`       | Custom fonts, managed by esbuild and `bin/build-assets` |
-| `forms/`       | Form classes |
-| `handlers/`    | Handler classes |
-| `images/`      | Images, copied to `app/public` by `bin/build-assets` |
-| `js/`          | JavaScript, managed by esbuild and `bin/build-assets` |
-| `layouts/`     | Layout classes |
-| `middlewares/` | Rack Middleware, if any |
-| `pages/`       | Page classes |
-| `route_hooks/` | Route hooks, if any |
-| `support/`     | General support classes/junk drawer. |
-| `svgs/`        | SVGs you want to render inline |
-
-## Inside `specs/`
-
-`specs/` is intended to mirror `app/src`, but has a few extra directories:
-
-
-|Directory       | Purpose |
-|----------------|---------|
-| `specs/back_end` | tests for all back-end code, organized the same as `app/src/back_end` |
-| `specs/back_end/data_models/db` | tests for all DB classes, if needed |
-| `specs/e2e` | End-to-end tests, organized however you like |
-| `specs/factories` | Root of all factories for FactoryBot. You can create subdirectories here for non-DB classes you may want to be able to create |
-| `specs/factories/db` | Factories to create DB records |
-| `specs/front_end` | tests for all front-end code, organized the same as `app/src/front_end` |
-| `specs/js`| *JavaScript* code to test any autonomous custom elements you have created |

data/brutrb.com/doc-conventions.md

@@ -1,41 +0,0 @@
-# Documentation Conventions
-
-## Terminology
-
-Brut attempts to use existing terminology where possible, particularly where that technology applies to the web platform.  For example, there is not a thing called "CSS variables", rather the term is "custom properties".
-
-Here are some common exampels:
-
-
-- HTML entities are **elements** or **tags**
-- HTML elements have **attributes**.
-- Forms don't have validations, they have **constraints** which are **violated** by invalid data.
-- Ruby classes don't have constructors, they have **initializers**.
-- Invoking behavior on a Ruby object is **calling a method**, not sending a message.
-- Despite being in `specs/`, the files in there are **tests**, not specifications or "specs".
-- Tests that use a browser are **end to end** or **e2e** tests.
-- HTML is not rendered, but **generated**. The browser renders the HTML sent to it by the server, along with the CSS.
-- Your app or site doesn't have users, it has **visitors**.
-
-## Structure of These Documents
-
-Each page here documents on aspect of Brut, called a *module*, and these pages are organized along four sections:
-
-* **Overview** - What the module does, how it works, and a brief example.
-* **Testing** - How to test the code you write in this module.
-* **Recommended Practices** - Opinions from the creators about how best to think about the code in this module.
-* **Technical Notes** - details about the technical implementations that may be
-useful as context.
-
-## Names of the Library and Associated Modules
-
-This framework is called "Brut" though may be called "BrutRB" or "brut-rp".  It lives at `brutrb.com`.  Never use "brutRB", "brut_rb", etc.
-
-The JavaScript library is called "BrutJS", but is `brut-js` in code or the filesystem. "Brut-JS" is wrong, as is `brut_js`.
-
-The CSS library is called "BrutCSS", but is `brut-css` in code or the filesystem. "Brut-CSS" is wrong, as is "brut-css".
-
-
-## On Using VitePress
-
-This site is built using [VitePress](https://vitepress.dev), which is a client-side heavy framework.  It kinda goes against the ethos of Brut, but it is allowing me to write documentation that looks decent and is mostly navigable.  I would like to use a more accessible, customized system for documenting Brut, but for now, it's more important to get the documentation out.  A better documentation experience is planned.

data/brutrb.com/dx

@@ -1 +0,0 @@
-../dx