brut 0.0.20 → 0.0.22

data/brutrb.com/cli.md

@@ -0,0 +1,278 @@
+# CLI and Tasks
+
+Your app will likely need command-line or non-browser-based tasks.  Outside of standard needs like running a dev server or managing the database, you will have app-specific needs, like transforming data or performing one-time bulk operations.
+
+In Brut, these are done as Ruby CLI apps, powered by the standard library's `OptionParser`.
+
+## Overview
+
+The various commands installed with your Brut app in `bin/` are powered by Brut's CLI support. You can use this support to create your own tasks.
+
+The main feature this provides is a consistent startup of your app's internals and configuration. This startup is almost exactly the same as the web app, so you can safely rely on connections to the database, the ability to queue jobs, or the behavior of your business logic. There's just no web server and no front-end.
+
+### Brut CLI User Interface
+
+All Brut CLI apps produce a user interface that should be familiar if you've used CLI apps that support subcommands, like `git`:
+
+```
+> git status
+> git checkout
+> git commit
+```
+
+Each Brut CLI invocation has six parts:
+
+* The executable, e.g. `bin/db`
+* *Global Options* which are strings that start witih one or two
+dashes and control the behavior of the entire app, e.g. `--log-level=debug` These are optional and there can be any number of them.
+* The subcommand, which is a single string indicating what actual
+function to perform, e.g. `rebuild` in `bin/db rebuild`
+* *Command Options* which are just like global options, but they
+come *after* the command and apply only to that command
+* Arguments, which are any strings left over after the *command
+options* are parsed.
+
+All of this is powered by Ruby's `OptionParser`, which results in a canonical, UNIX-like UI.
+
+```
+> bin/my_cli --global-option list --command-option arg1 arg2
+  \----+---/ \-------+-----/ \-+/ \--------+-----/ \---+---/
+       |             |         |           |           |
+   Executable        |         |           |           |
+                     |         |           |           |
+                Command        |           |           |
+                   Options     |                       |
+                               |           |           |
+                             Subcommand    |           |
+                                           |           |
+                                      Command          |
+                                        Options        |
+                                                       |
+                                                       |
+                                                    Arguments
+        
+```
+
+Brut CLI apps all respond to `-h` and `--help` to view the list of subcommands, global options, and any environment variables that affect the behavior.
+
+```
+> bin/db -h 
+bin/db [global options] commands [command options] [args]
+
+   Manage your database in development, test, and production
+
+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
+
+
+COMMANDS
+
+    help          - Get help on a command
+    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, effecitvely rebuilding the entire database
+    seed          - Load seed data into the database
+    status        - Check the status of the database and migrations
+```
+
+Brut CLI apps also support the subcommand `help` which will show help on a given subcommand, including the command options and arguments.
+
+```
+>  bin/db help rebuild
+Usage: bin/db [global options] rebuild [command options] 
+
+    Drop, re-create, and run migrations, effecitvely rebuilding the entire database
+
+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
+    RACK_ENV                - default project environment when --env is omitted
+
+
+COMMAND OPTIONS
+
+        --env=ENVIRONMENT            Project environment (default 'development')
+```
+
+All of this means that the bulk of CLI-specific code you will write is specifying these options and documentation, then deferring to your business logic.
+
+### Basic CLI
+
+Every CLI app is a class that extends `Brut::CLI::App`. This class should contain one inner class for each subcommand. Those classes should extend `Brut::CLI::App`.
+
+Inside your `Brut::CLI::App` class, you can call a few class methods to declare aspects of the UI. In particular, `opts` returns the `OptionParser` in play that you can use to declare global options.  Unlike `OptionParser`'s `on` method, Brut's does not require providing a block. Brut will store the runtime options in a hash (see below).
+
+```ruby
+class MyAppCLI < Brut::CLI::App
+  description "My awesome command line app"
+
+  opts.on("--dry-run", "Only show what would happen; don't change anything")
+  opts.on("--status STATUS", "Set the status you'd like to see")
+end
+```
+
+This code means your app's global options are `--dry-run`, which will not accept an argument, and `--status` which *must* be given an argument.  The arguments to `on` are the same as those for Ruby's `OptionParser`.
+
+Declaring subcommands provides a similar API.  Let's say our app has a "status" subcommand, and a "run" subcommand.
+
+```ruby
+class MyAppCLI < Brut::CLI::App
+  description "My awesome command line app"
+
+  opts.on("--dry-run", "Only show what would happen; don't change anything")
+  opts.on("--status STATUS", "Set the status you'd like to see")
+
+  class Status < Brut::CLI::Command
+    description "Show the status"
+    args "files to get the status of"
+    opts.on("-l", "--long", "Show long-format")
+  end
+
+  class Run < Brut::CLI::Command
+    description "Run any outstanding tasks"
+    opts.on("--exit-status STATUS", "Exit status on success")
+  end
+end
+```
+
+This enables commands like `bin/my_app status -l foo.txt bar.rb` or `bin/my_app status --exit-status=3`.
+
+The names are derived from the class name. You can override them by using `command_name` inside a command class.
+
+```ruby {2}
+class Run < Brut::CLI::Command
+  command_name "exec"
+  
+  # ...
+end
+```
+
+The only thing left is to specify what happens for each subcommand. To do that, implement `execute`.
+
+```ruby {6-8,15-17}
+class Status < Brut::CLI::Command
+  description "Show the status"
+  args "files to get the status of"
+  opts.on("-l", "--long", "Show long-format")
+
+  def execute
+    # ...
+  end
+end
+
+class Run < Brut::CLI::Command
+  description "Run any outstanding tasks"
+  opts.on("--exit-status STATUS", "Exit status on success")
+
+  def execute
+    # ...
+  end
+end
+```
+
+### Implementing `execute`
+
+Once `execute` is called, your app's internals will have been setup and bootstrapped. That means all you data models can access the database, and any other setup will have ocurred. Generally, `execute` can then have whatever code makes sense.
+
+That said, `execute` has access to a few values to understand the command line invocation and to support testing.
+
+* `#options` - the command options passed on the command line, as
+a `Brut::CLI::Options`
+* `#global_options` - the global options passed on the command line, as a `Brut::CLI::Options`
+* `#args` - the args passed on the command line, as an array of
+strings
+* `#out` - an IO you should use to print messages to the standard out.
+* `#err` - on IO you should use to print messages to the standard error.
+* `#system!` - the method you should use to spawn child processes.
+This is preferable to `Kernel.system` because the command executed will be logged, and your app will raise if the command fails.  This makes it more straightfoward to safely script other command line invocations.
+
+### Advanced Options
+
+The API documentation will show you other options for creating your CLI UI, but there are a few aspects to highlight.
+
+* Calling `configure_only!` in your app, will run your app's
+subcommands without starting up Brut. This is generally not needed, but can be useful if you want to do basic scripting without worrying about connecting to the database.
+* `default_command` can be used to specify the command to run if
+none is given.  `bin/test` uses this to run `bin/test run`.
+* `requires_project_env` can be used at the app or command level
+to indicate that `--env` is accepted on the command line to set the project environment for the code to run in. Omitting this means that the actual project env used when the app runs is undefined.
+* Use `env_var` to document environment variables your app will
+use that affect its behavior.
+
+### The file in `bin`
+
+Currently, Brut doesn't provide a way to create this file, but it's relatively straightforward.  It's almost entirely boilerplate except for your class:
+
+```ruby {14}
+#!/usr/bin/env ruby
+
+require "bundler"
+Bundler.require
+require "pathname"
+
+require "brut/cli"
+
+APP_PATH = File.join(File.dirname($0),"..","app","src")
+$: << APP_PATH
+require "cli/my_app"
+
+exit Brut::CLI.app(
+  MyAppCLI,
+  project_root: Pathname($0).dirname / ".."
+)
+```
+
+## Testing
+
+Depending on how your CLI is impelmented, testing it may not be that beneficial.  If `execute` simply defers to your back-end, your tests of that back-end will generally suffice.
+
+That said, your command classes are normal Ruby classes, so you can test them in a conventional way.
+
+The initalizer of each command class looks like so:
+
+```ruby
+def initialize(
+  command_options:,
+  global_options:,
+  args:,
+  out:,
+  err:,
+  executor:
+)
+```
+
+`command_options` and `global_options` accept a `Brut::CLI::Options`, which can be created with a Hash to represent the parsed command line options.
+
+`args` is a list of Strings.  `out` and `err` are IOs, so you can use the standard library's `StringIO` to both capture the output and supress it from your test's standard output/error.
+
+`executor` is a `Brut::CLI::Executor`, which is a wrapper around the standard library's `Open3`.  You can mock this to set expectations on what child processes are launched and how they behave.
+
+## Recommended Practices
+
+`execute` should defer to classes in your back-end, ideally a single method of a single class.  Excessive logic or UI in your CLI will be hard to test and maintain.
+
+
+## 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 May 9, 2025_

data/brutrb.com/components.md

@@ -0,0 +1,243 @@
+# Components
+
+Components in Brut are Phlex Components: a class that can hold data and use that to generate HTML.  Components are the primary way you achieve re-use of markup or view logic.
+
+## Overview
+
+`Brut::FrontEnd::Component` inherits from `Phlex::HTML`, which means that to create a component you must do three things:
+
+1. Create a class in `app/src/front_end/components` that inherites from `AppComponent` (which is part of your app and inherits from `Brut::FrontEnd::Component`)
+2. Implement an initializer that receives anything your component needs to do its job.  It is recommended (but not required) that your initializer use only keyword arguments.
+3. Implement `view_template` in which you make calls to Phlex' API.
+
+### Simple Component
+
+For example, suppose you want a re-usable button component whose HTML would look like so:
+
+```html
+<button class="button button__small button__red">
+  Delete Files
+</button>
+```
+
+Your button can be large (the default) or small, and could be gray (default), green, or red.  Your button could also have an optional `formaction` attribute. Let's also suppose the label could be a string or embedded HTML.
+
+Your constructor would need to accept the size, color, label, and formaction.
+
+You can create a scaffold via `bin/scaffold`:
+
+```
+> bin/scaffold component Button
+```
+
+You'll first implement the initializer, like so:
+
+```ruby
+# app/src/front_end/components/button.rb
+class Button < AppComponent
+  def initialize(
+    size: :large,
+    color: :gray,
+    formaction: nil,
+    label: :use_block
+  )
+    @size       = size
+    @color      = color
+    @formaction = formaction
+    @label      = label
+  end
+end
+```
+
+This initializer is rather simplistic. You may want to validate the values here to prevent the construction of an invalid component.
+
+Now, implement `view_template`.  This method will receive a block if one is given when the component is used. We'll see an example in a minute.
+
+```ruby
+# app/src/front_end/components/button.rb
+class Button < AppComponent
+
+  # ...
+
+  def view_template
+    attributes = {
+      class: [
+        "button",
+        "button__#{@size}",
+        "button__#@{color}",
+      ],
+      formaction: @formaction,
+    }
+
+    button(**attributes) do
+      if @label == :use_block
+        yield
+      else
+        @label
+      end
+    end
+  end
+end
+```
+
+If you've never used Phlex before, it's refreshingly straightforward:
+
+* There's a method for each  HTML element.
+* The method's parameters produce attributes in the HTML that is generated.
+* If a parameter's value is an array (like `class:`), the values are joined with strings to form the atttribute's value in HTML.
+* If the element can have inner content, whatever happens inside a yielded block becomes that inner content.
+
+To use this component, we can call `render` in either the `view_template` of another component or the `page_template` of a [page](/pages):
+
+```ruby
+def view_template
+  form do
+    render Button.new(label: "Submit")
+    render Button.new(label: "Nevermind", size: :small, color: :red)
+    render Button.new(color: :green) do
+      img(src: "/images/ok.png", alt: "OK icon")
+    end
+  end
+end
+```
+
+Note that the block passed to `render` is the block available when `yield` is called inside `view_template`.
+
+There are two special types of components beyond what we have just seen.  *Global* Components and *Page private* components.
+
+### Global Components
+
+As we saw above, creating a component is just like creating any Ruby class: you call `.new` on it.  If you create a component that uses request-level data, such as the flash or session, it would mean that any page or component that used *that* component would need to accept the flash or session as a parameter to its initializer, even if it it was otherwise not needed.
+
+In those cases, `global_component` can be used to leverage [keyword injection](/keyword-injection) to have Brut create the component.  That way, its initializer's parameters don't need to be passed into the page or component using the global component.
+
+Suppose we had a component to display the flash:
+
+```ruby
+class FlashMessage < AppComponent
+
+  def initialize(flash:)
+    @flash = flash
+  end
+
+  def view_template
+    if @flash.notice?
+      div(role: "status") { @flash.notice }
+    elsif @flash.alert?
+      div(role: "alert") { @flash.alert }
+    end
+  end
+end
+```
+
+To use it without having to instantiate it, call `global_component` with the component's class:
+
+```ruby
+class HomePage < AppPage
+  def page_template
+    header do
+      render global_component(FlashMessage)
+    end
+  end
+end
+```
+
+> [!IMPORTANT]
+> Brut currently requires an all-or-nothing approach to global components. Either 
+> the component can be injected with all its initializer parameters or it must
+> be created explicitly by the page or component. You cannot have a component
+> receive request-level keyword injection for some parameters with the page
+> providing the rest.
+
+Components can also be scoped to a page.
+
+### Page Private Components
+
+Often, components are helpful to simplifying a page's template or managing re-use within a page, but such a component isn't designed for use outside that page.  For example, if the page renders a table, but the logic for each row is complex, you may want that in a separate component, even though it would be useless outside the page.
+
+Brut provides a way to create a *page private* component that exists as an inner class of a page.  It's not truly private, since it's still a Ruby class anyone can use, but it's form and source location communicate intent.
+
+Suppose our `HomePage` has a list of widgets on it, but we want each widget's HTML managed by a separate component:
+
+```ruby
+class HomePage < AppPage
+  def page_template
+    header do
+    h1 { "Check out these Widgets!" }
+    end
+    main do
+      ul do
+        DB::Widget.all.each do |widget|
+          render(HomePage::WidgetListItem.new(widget:))
+        end
+      end
+    end
+  end
+end
+```
+
+`HomePage::WidgetListItem` can be created like so:
+
+```
+bin/scaffold component --page=HomePage WidgetListItem
+```
+
+This will create `app/src/front_end/pages/home_page/widget_list_item.rb`, which you can then implement like a normal component:
+
+```ruby
+# app/src/front_end/pages/home_page/widget_list_item.rb
+class HomePage::WidgetListItem < AppComponent
+  def initialize(widget:)
+    @widget = widget
+  end
+
+  def view_template
+    li do
+      h2 { @widget.name }
+      p { @widget.description }
+    end
+  end
+end
+```
+
+The only special thing about a page private component is that it can access the page's I18n translations. As we'll discussion in [I18n](/i18n), The `t` method will try to locate translations based on the page on which `t` is called.  A page private component will also trigger this behavior, but a normal component will not.
+
+For example, the following code will look for `pages.HomePage.status.«status»` when generated the `<h3>`:
+
+```ruby {10}
+# app/src/front_end/pages/home_page/widget_list_item.rb
+class HomePage::WidgetListItem < AppComponent
+  def initialize(widget:)
+    @widget = widget
+  end
+
+  def view_template
+    li do
+      h2 { @widget.name }
+      h3 { t([ :status, @widget.status ]) }
+      p { @widget.description }
+    end
+  end
+end
+```
+
+## Testing
+
+Test widgets exactly as you would [pages](/pages#testing). The only difference is that components always render HTML and have no `before_generate` concept.
+
+## Recommended Practices
+
+The [recommended practices for pages](/pages#recommended-practices) all apply to components, too.
+
+Beyond that, components are intended to be lightweight, so use them liberally.  Any page or component that has complex markup can be extracted to another component and more easily unit-tested.
+
+
+## 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 May 5, 2025_
+
+As mentioned, components are Phlex components, but have various helpers mixed-into them.  Components are currently tightly coupled to Phlex and there is no plan to allow alternate implementations of view logic that isn't supported by Phlex.