feat(bonfire): SSU widgets on charm v2 behind the Output interface

- Spinner, gradient progress bar and the multi-row process view ported
  from SSU to bubbletea v2 (input off, no signal handler, command
  context); boxed tables through lipgloss/table
- Prompts use huh fields and a single-select port of SSU's selector with
  its confirmation screen on an interactive terminal; line prompts off a
  terminal and under --no-ansi are unchanged (piped passwords still work)
- -q hides decoration but keeps data and errors; -n returns defaults and
  Secret fails with a hint on a terminal stdin; --no-ansi and non-TTY
  runs print today's plain lines
- Helpers: GlobalsOf, VerbosityOf, IsQuiet, Interactive, ConfirmProceed,
  Process, Current, Failed, PrintAbove, ItemProgress, ErrAborted
- diary's styled console lines print above a running live view

docs/console/introduction.md

@@ -81,9 +81,9 @@ Every command of both programs accepts these options, before or after the comman
 | Option | Effect |
 |--------|--------|
 | `-v`, `-vv`, `-vvv` (`--verbose`) | More output: `-v` shows info logs of every component, `-vv` debug logs, `-vvv` also source locations and SQL traces. |
-| `-q`, `--quiet` | Shows only warnings and errors in the console log. Implies `-n`. |
-| `--ansi`, `--no-ansi` | Forces or turns off colors and styling; the last one given wins. Without either, colors follow the terminal, `NO_COLOR` and `FORCE_COLOR`. |
-| `-n`, `--no-interaction` | Marks the run as not interactive. |
+| `-q`, `--quiet` | Hides info and success lines, spinners and progress, and shows only warnings and errors in the console log; data a command prints (tokens, keys, JSON) and errors still appear. Implies `-n`. |
+| `--ansi`, `--no-ansi` | Forces or turns off colors and styling; `--no-ansi` also stops animations. The last one given wins. Without either, colors follow the terminal, `NO_COLOR` and `FORCE_COLOR`. |
+| `-n`, `--no-interaction` | Asks no questions: prompts take their defaults, and a password prompt reads piped stdin or fails with a hint. |
 | `--env` | The configuration environment, as `SUMMER_ENV` would set it: `--env staging` or `--env=staging`. |
 
 The application binary reads these options before it loads `config/` and starts plugins, so `--env` picks the configuration and `-vv` applies from the first log line:

docs/console/writing-commands.md

@@ -57,8 +57,24 @@ A scaffolded plugin's `Commands` method returns the generated list of everything
 `bonfire.Output` is the console your command writes to. Besides `bonfire.Output.Printf` and `bonfire.Output.Println`, it provides:
 
 - status lines: `bonfire.Output.Info`, `bonfire.Output.Success`, `bonfire.Output.Warning` and `bonfire.Output.Error` (the last one writes to the error stream);
-- widgets: `bonfire.Output.Table`, `bonfire.Output.Spinner` around a function and `bonfire.Output.Progress` for a progress bar, which fall back to plain lines when the output is not a terminal;
-- prompts: `bonfire.Output.Ask`, `bonfire.Output.Confirm`, `bonfire.Output.Choice` and `bonfire.Output.Secret`. Prompts return their defaults when input ends, so a command run from cron or a script never hangs.
+- widgets: `bonfire.Output.Table`, `bonfire.Output.Spinner` around a function and `bonfire.Output.Progress` for a progress bar. On a terminal they are SSU's live views on the charm stack: a spinner, a gradient bar and boxed tables;
+- prompts: `bonfire.Output.Ask`, `bonfire.Output.Confirm`, `bonfire.Output.Choice` and `bonfire.Output.Secret`. On an interactive terminal they are huh fields and an arrow-key selector; otherwise they read lines from stdin, so a password can be piped in, and return their defaults when input ends, so a command run from cron or a script never hangs.
+
+How much of this appears depends on where the command runs and on the global options:
+
+| Run | Animation | Decoration | Data | Prompts |
+|-----|-----------|------------|------|---------|
+| Terminal | spinner, progress bar, process view | colors, symbols, boxed tables | printed | huh fields and the selector |
+| Not a terminal | none: `[...] message` and a line per tenth of progress | symbols, no colors | printed, tables tab-separated | read a line from stdin; `Confirm` returns its default |
+| `-q` | none | info, success and warning lines hidden; errors kept | printed | defaults, as with `-n` |
+| `--no-ansi` | none | symbols, no colors | printed | plain line prompts |
+| `-n` | none | as on the terminal | printed | defaults; `Secret` reads piped stdin or fails with a hint |
+
+Print the data your command exists to produce (a token, a key, JSON) with `bonfire.Output.Println` or `bonfire.Output.Printf`, never as a status line: `-q` keeps that output and drops only the decoration around it. `bonfire.IsQuiet`, `bonfire.VerbosityOf` and `bonfire.GlobalsOf` tell a command which options it runs under.
+
+Before a destructive step, ask with `bonfire.ConfirmProceed`. It asks only on an interactive terminal; off a terminal, with `-n` or `-q`, and when the scheduler calls the command, it returns true without asking, so deploys over SSH never wait for an answer.
+
+For a loop over many items, `bonfire.Process` runs a function per item and shows SSU's process view on a terminal, one row per item with its state, or prints one `✓ item` or `✗ item: error` line per item elsewhere; it returns the failures joined. Inside `bonfire.Output.Progress`, `bonfire.Current` names the item being worked on and `bonfire.Failed` records a failed one. Log lines and output printed while a live view runs appear above the view (`bonfire.PrintAbove`).
 
 Return an error from `Run` to fail the command. The binary prints it as an error block on stderr and exits with status 1; see [Errors and hints](#errors-and-hints).