dry-cli-ui 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d64ee9f8fedbc7de0fcd1875acf59d07876ef6acaffbfcc8574b197de0e8d6fd
-  data.tar.gz: 2f7e11eca1a0dff40b3df7cba685bca7f97d4884515db1107805036e746e20bc
+  metadata.gz: ef89bfadc9ccc7f7d737abdf585a9dfa57780b085dc12635be3149c623a965ea
+  data.tar.gz: e91a1f2ad8f9ebc4f174f7df2627fba76db005fc3d278b3f50d63d760c39c53f
 SHA512:
-  metadata.gz: d9105f75325a1a7f8282e989d4c847320fb481880a7a529041d98d4bff9457dc5235d08a5c3b311c0b3d442a6dc4c3923b6c72844bd2fbb55ec04f2824b906e3
-  data.tar.gz: d095b784083ba57db9592e51ef2d56274dd9cb187fcac350d35aaea51b8e64c519a800e3f7f899b2b248acfe8035733c4fa63930b64086cdbebea17c8af4636b
+  metadata.gz: c3b9332b0cc87c0fa50a8bae398492c5994edf410168be89ae41c6ecf41104cc0d3f664257a890e7a066faad0ffa19790716b1fa74d35872c89bc3ad3c8e0107
+  data.tar.gz: a8985df9aa1c143c538557c9195dec1d060d3f54263b5041246810c2203007ddd30b2e246abdffea467cd21fae37f6db3081d21d317fc843401869ede4518b29

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [Unreleased]
+
+- `ui` reads the command's public `stdout`, `stderr` and `stdin`, the streams dry-cli was called with, when dry-cli has them. Prompts then read from the command's `stdin`.
+- Under released dry-cli (1.4 and earlier), `ui` writes to the command's protected `out` and `err`, as before, and reads prompts from `$stdin`. dry-cli with public command streams is no longer required.
+- `ui` builds its console again when those streams change, so a command registered as an instance, or run in-process by `Dry::CLI::Launcher`, writes each call to that call's streams.
+- `ui_options` configures the console `ui` builds, in place of overriding `ui`.
+- CI runs the suite against both kigster/dry-cli and the latest dry-cli release, and against the latest release every week.
+- Reserved flags: `extend Dry::CLI::UI::Flags` and `flags :dry_run, :yes, :output, :log` give a command `-n/--dry-run`, `-y/--yes`, `-o/--output [FILE]`, `-l/--log [FILE]`, `-L/--log-level LEVEL` and `--log-format FORMAT`, the same in every CLI. Loading `Flags` prepends a hook onto `Dry::CLI` that lets `-o` and `-l` go without a file, for those commands only; `Flags.arguments(argv)` is the rewrite on its own.
+- `ui.output(output) { |io| ... }` writes the command's report (what goes to `out`) to `log/<executable>-<action>.<YYYY-MM-DD>.<HHMMSS>.log` at the repository root for a bare `-o`, or to the file given, in colour, ending with the time it was closed. Spinners, bars and prompts stay on `err`.
+- `ui.logging(log, level:, format:) { ... }` logs through SemanticLogger to `log/<executable>-<action>.log`, a file, or `out` while the block runs. `ui.logger` is the command's logger, and `ui.log_exception(e)` logs an exception, with each frame's local variables when it was raised at `-L debug`. `ui.with_flags(**options) { |io| ... }` does both.
+- `ui.confirm` takes `yes:`, which answers it without asking, and on a terminal offers YES and NO as a list.
+- A stream answering `color?` with true gets colour although it is no TTY. `Terminal#inspect` leaves out the environment.
+- New dependencies: `semantic_logger`, `logger` (which semantic_logger needs on Ruby 4.0 and does not declare) and `binding_of_caller`. They load the first time a command logs.
+- A progress handle counts each unit as an outcome: `bar.advance(step = 1, as: :ok)` takes `:ok`, `:aux` (relevant but auxiliary) or `:failed`, and `bar.counts` returns `{ ok:, aux:, failed: }`. Plain `advance(n)` counts as `:ok`, as before. Works in `ui.progress` and in every row of `ui.multi_progress`.
+- A bar draws its failed units first, in red, then its auxiliary ones, in yellow, then the rest in its own colour, each part as wide as its share. A bar with neither draws as before. `Dry::CLI::UI.configure` takes `bar_failed_color` and `bar_aux_color`.
+- A bar ends `✓` even when every unit failed, and its outcome line adds the breakdown after the time: `✓ Placing forms 100/100 (2.1s)  20 failed, 5 auxiliary`. The `multi_progress` headline, when it counts units, adds the sum of its rows'.
+- A bar whose total is known and 0 when its job ends now ends `𝘅 label 0/0: nothing to process`, unless the job called `bar.fail` with a reason of its own. Before, it ended `✓`. In `multi_progress` the headline then ends `𝘅` too.
+- `ui.progress` turns a spinner before its label while it runs, as each `multi_progress` row does, and draws the bar itself rather than through `TTY::ProgressBar`. Piped output is unchanged.
+- `ui.legend(failed:, aux:, ok:)` prints one line to `err` saying what each colour of a bar means: `Color Mapping: [ red: errors and invalid files | yellow: relevant but auxiliary | green: forms ]`, or each label on its colour's background on a terminal.
+
 ## [0.6.1]
 
 - A progress handle takes `fail(reason = nil)`, as a `Line` does: the bar ends `𝘅 label 3/3: reason` without raising, in `ui.progress` and in a row of `ui.multi_progress`, where the jobs after it still run and the headline ends `𝘅`. For work that carries on after some of its units failed.
@@ -6,13 +26,6 @@
 
 - `m.spinner(label)` inside `ui.multi_progress` declares a row with a spinner in place of a bar, for a phase whose size is never known, so one widget can show phases of known and unknown size together. The row shows its `Line`'s detail while it runs and ends `[✓] label`; it counts as a job and as no units on the headline.
 
-## [0.6.0]
-
-- `ui` reads the command's public `stdout`, `stderr` and `stdin`, the streams dry-cli was called with. Before, it looked for `out` and `err`, which dry-cli no longer has, and wrote to `$stdout` and `$stderr` instead. Prompts now read from the command's `stdin`.
-- `ui` builds its console again when those streams change, so a command registered as an instance, or run in-process by `Dry::CLI::Launcher`, writes each call to that call's streams.
-- `ui_options` configures the console `ui` builds, in place of overriding `ui`.
-- Needs dry-cli with public command streams and `Dry::CLI::Launcher`; the Gemfile takes it from kigster/dry-cli until it is released.
-
 ## [0.5.1]
 
 - `ui.stoppable { |stop| ... }` makes Ctrl-C ask for a stop instead of interrupting, and `ui.multi_spinner` and `ui.multi_progress` take `stop:`. Once it is set, the jobs running finish, the rest are skipped, and the headline says `stopping`, then ends skipped. A second Ctrl-C interrupts. `Dry::CLI::UI::Stop` is the object behind it.

data/README.md

@@ -15,7 +15,7 @@ A long-running command has more to say than `puts` can show well: what it is doi
 gem "dry-cli-ui"
 ```
 
-Requires Ruby 4.0 or later and `dry-cli` 1.0 or later. The rendering comes from the [TTY toolkit](https://ttytoolkit.org) (`tty-box`, `tty-spinner`, `tty-progressbar`, `tty-table`, `tty-prompt`, `tty-cursor`, `tty-screen`), `pastel`, `strings` and `concurrent-ruby`, which Bundler installs with the gem.
+Requires Ruby 4.0 or later and `dry-cli` 1.0 or later. The rendering comes from the [TTY toolkit](https://ttytoolkit.org) (`tty-box`, `tty-spinner`, `tty-progressbar`, `tty-table`, `tty-prompt`, `tty-cursor`, `tty-screen`), `pastel`, `strings` and `concurrent-ruby`, and the [reserved flags](#reserved-flags) log through `semantic_logger` (with `logger`) and `binding_of_caller`. Bundler installs them all with the gem.
 
 Either require works, and both load the same file:
 
@@ -88,6 +88,8 @@ end
 
 `ui` writes to the command's `stdout` and `stderr`, and reads prompt answers from its `stdin`: the streams dry-cli was called with. Outside a dry-cli command it uses `$stdout`, `$stderr` and `$stdin`. The console is built again when those streams change, so a command registered as an instance writes each call to that call's streams.
 
+Released dry-cli, up to 1.4, gives a command only `out` and `err`. There `ui` writes to those and reads prompt answers from `$stdin`; `Dry::CLI.new(registry).call(out: io, err: io)` still captures everything. `stdin:`, `stdout:`, `stderr:` and `Dry::CLI::Launcher` need dry-cli with public command streams ([dry-rb/dry-cli#175](https://github.com/dry-rb/dry-cli/pull/175) to [#176](https://github.com/dry-rb/dry-cli/pull/176)).
+
 ### Without dry-cli
 
 `Dry::CLI::UI::Console` needs nothing from dry-cli, so a Rake task or a plain script can use it directly:
@@ -252,9 +254,9 @@ ui.progress("Importing rules", total: rules.size) do |bar|
 end
 ```
 
-The bar shows percent, `current/total` and ETA, `Importing rules [◼◼◼◼◼◼    ] 61%  1159/1900  ETA 2.7s`, and ends with `✓ Importing rules 1900/1900 (4.2s)`. On a terminal the `◼`s are green, between brackets, on no background; see [Configuration](#configuration) to change either.
+The bar shows a turning spinner, percent, `current/total` and ETA, `⠋ Importing rules [◼◼◼◼◼◼    ]  61%  1159/1900  ETA 2.7s`, and ends with `✓ Importing rules 1900/1900 (4.2s)`. On a terminal the `◼`s are green, between brackets, on no background; see [Configuration](#configuration) to change either.
 
-The block is given a `Dry::CLI::UI::Widgets::Progress::Handle`, never the underlying `TTY::ProgressBar`:
+The block is given a `Dry::CLI::UI::Widgets::Progress::Handle`, never a TTY toolkit object:
 
 ```ruby
 ui.progress("Copying", total: files.sum(&:size)) do |bar|
@@ -266,15 +268,72 @@ ui.progress("Copying", total: files.sum(&:size)) do |bar|
 end
 ```
 
-- `advance(step = 1)` adds to `current` and returns the handle; `current` never passes `total`.
+- `advance(step = 1, as: :ok)` adds to `current` and returns the handle; `current` never passes `total`. `as:` counts the units as `:ok`, `:aux` or `:failed`; see [Failed and auxiliary units](#failed-and-auxiliary-units).
 - `total = n` sets the total once the work finds out, such as a download learning its size, and lowers `current` to fit. Anything but a non-negative Integer raises `ArgumentError`.
 - `total:` must be a non-negative Integer, or `progress` raises `ArgumentError`.
-- `total: 0` draws no bar, and ends `✓ Copying 0/0`.
+- `total: 0` draws no bar, and ends `𝘅 Copying 0/0: nothing to process`, since there was nothing to do. A block that calls `bar.fail(reason)` first keeps its own reason.
 - `color:` paints this bar's finished part in any Pastel style, such as `color: :red`, instead of the configured `bar_color`. A style Pastel does not know raises `ArgumentError` before the block runs.
-- The outcome is `✓` whenever the block returns, even short of the total (`✓ Copying 12/20`), and `𝘅` when it raises.
+- The outcome is `✓` whenever the block returns, even short of the total (`✓ Copying 12/20`) and even when every unit failed, and `𝘅` when it raises or calls `bar.fail`.
 
 Piped, it prints `Importing rules...` when it starts and the outcome line when it ends, with no bar in between.
 
+### Failed and auxiliary units
+
+Work that goes through many files rarely succeeds on all of them. `bar.advance(as:)` counts each unit as one of three outcomes:
+
+- `:ok`, the default: the unit is what the work is for, such as a form placed.
+- `:aux`: relevant but auxiliary, such as a scaffold created or an instruction filed elsewhere.
+- `:failed`: an error, or an invalid file.
+
+Anything else raises `ArgumentError`. `bar.counts` returns the units so far by outcome, `{ ok: 7, aux: 1, failed: 2 }`, adding up to `bar.current`.
+
+The bar's finished part is drawn left to right in red for the failed units, yellow for the auxiliary ones, and the bar's own colour for the rest, each part as wide as its share of the units done: half way through, with a fifth of the files failed, the first fifth of the filled part is red and the rest green. The bar ends with `✓` and the breakdown after the time, with the numbers in their colours on a terminal. `ui.legend` prints a line saying what each colour means; call it before the first bar. Each of `failed:`, `aux:` and `ok:` is optional, and a label not given is left out. On a terminal each label is drawn on its colour's background.
+
+```ruby
+ui.legend(failed: "errors and invalid files", aux: "relevant but auxiliary", ok: "forms")
+
+ui.progress("Placing forms", total: files.size) do |bar|
+  files.each do |file|
+    case place(file)
+    in :placed then bar.advance
+    in :scaffold then bar.advance(as: :aux)
+    in :invalid then bar.advance(as: :failed)
+    end
+  end
+end
+```
+
+Piped, with two invalid files and one scaffold among ten:
+
+```text
+Color Mapping: [ red: errors and invalid files | yellow: relevant but auxiliary | green: forms ]
+Placing forms...
+✓ Placing forms 10/10 (0.0s)  2 failed, 1 auxiliary
+```
+
+`m.progress` inside `ui.multi_progress` takes the same `as:`. Each row ends with its own breakdown, and the headline, when it counts units, with the sum of them all. A row whose total is 0 when its job ends fails with `nothing to process`, and so the headline ends `𝘅`:
+
+```ruby
+ui.multi_progress("Placing forms", concurrent: false) do |m|
+  m.progress("us", total: federal.size) { |bar| federal.each { bar.advance(as: place(it) == :invalid ? :failed : :ok) } }
+  states.each do |state, forms|
+    m.progress(state, total: forms.size) { |bar| forms.each { bar.advance(as: :failed) } }
+  end
+end
+```
+
+Piped, where `us-ny` has no forms:
+
+```text
+Placing forms...
+  [✓] us 6/6 (0.0s)  2 failed
+  [✓] us-ca 2/2 (0.0s)  2 failed
+  [𝘅] us-ny 0/0: nothing to process (0.0s)
+𝘅 Placing forms 8/8 (0.0s)  4 failed
+```
+
+The colours are `bar_failed_color` and `bar_aux_color` in the [Configuration](#configuration).
+
 ### Several spinners at once
 
 ```ruby
@@ -358,7 +417,7 @@ The same shape as `multi_spinner`, with a bar per job and a headline bar that co
 └─ [ ] video.mp4
 ```
 
-Each job is given the same handle as `ui.progress`, with `advance(step = 1)`, `current` and `total`. `m.progress` takes `color:` as `ui.progress` does, so bars side by side can differ:
+Each job is given the same handle as `ui.progress`, with `advance(step = 1, as: :ok)`, `counts`, `current` and `total`. `m.progress` takes `color:` as `ui.progress` does, so bars side by side can differ:
 
 ```ruby
 ui.multi_progress("Probing #{hosts.size} hosts", total: hosts.size) do |m|
@@ -723,7 +782,7 @@ ui.confirm("Deploy to #{env}?", default: false)
 
 - `prompt` returns the answer as a String, or the default for an empty answer.
 - With an Array of `choices:`, it returns the chosen name; with a Hash, the value the chosen name maps to (`:pro` above). `default:` is the name of a choice.
-- `confirm` returns `true` or `false`, and `default:` is `false` unless given.
+- `confirm` returns `true` or `false`, and `default:` is `false` unless given. On a terminal it is a list to pick YES or NO from, starting on the default. `yes: true`, which is what the reserved `-y/--yes` flag gives (see [Reserved flags](#reserved-flags)), returns `true` without asking.
 
 When both standard input and `err` are terminals, these use arrow-key menus and line editing (TTY::Prompt). Otherwise they print the question to `err` and read lines from standard input, so answers can be piped:
 
@@ -778,6 +837,141 @@ Errors raised inside a block are never swallowed: the widget marks itself failed
 
 A stream that is not a terminal, or runs under `TERM=dumb`, gets no animation, no cursor movement and no escape codes. [`NO_COLOR`](https://no-color.org) turns colour off and leaves animation on.
 
+## Reserved flags
+
+A few flags mean the same thing in every CLI built on this gem. A command takes the ones it needs:
+
+| Flag | Long                  | Reaches `call` as | Meaning                                                                                                                  |
+| ---- | --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `-n` | `--dry-run`           | `dry_run:`        | change nothing, print what would happen                                                                                  |
+| `-y` | `--yes`               | `yes:`            | skip every interactive prompt                                                                                            |
+| `-o` | `--output [FILE]`     | `output:`         | write the command's report (tables, lists, summaries) to FILE, in colour                                                 |
+| `-l` | `--log [FILE]`        | `log:`            | log to FILE through [SemanticLogger](https://logger.rocketjob.io)                                                        |
+| `-L` | `--log-level LEVEL`   | `log_level:`      | `debug`, `info` (the default), `warn`, `error` or `fatal`                                                                |
+|      | `--log-format FORMAT` | `log_format:`     | `standard` (the default, one line per entry), `json`, or any other SemanticLogger formatter, such as `logfmt` or `color` |
+
+```ruby
+require "dry/cli"
+require "dry-cli-ui"
+
+class Export < Dry::CLI::Command
+  include Dry::CLI::UI
+  extend Dry::CLI::UI::Flags
+
+  desc "Export the rules"
+  flags :dry_run, :yes, :output, :log     # :log brings -L and --log-format with it
+
+  RULES = [["standard_deduction", 14_600], ["salt_cap", 10_000]].freeze
+
+  def call(dry_run:, yes:, **options)
+    ui.with_flags(**options) do |io|
+      ui.logger.info("Exporting", rules: RULES.size)
+      next ui.status("Would export #{RULES.size} rules", level: :warn) if dry_run
+      next unless ui.confirm("Export #{RULES.size} rules?", yes: yes)
+
+      ui.table(RULES, header: %w[Rule Amount])
+      io.puts "#{RULES.size} rules exported"
+    end
+  end
+end
+```
+
+`flags` declares ordinary dry-cli options, so they show in the command's help, and an unknown name raises `ArgumentError`:
+
+```text
+Options:
+  --dry-run, -n                # Change nothing; print what would happen, default: false
+  --yes, -y                    # Answer yes to every prompt, default: false
+  --output=VALUE, -o VALUE     # Write the report to FILE: log/ by default, - for STDOUT
+  --log=VALUE, -l VALUE        # Log to FILE: log/ by default, - for STDOUT
+  --log-level=VALUE, -L VALUE  # Log level: (debug, info, warn, error, fatal), default: "info"
+  --log-format=VALUE           # Log format: standard, json, or another SemanticLogger formatter, default: "standard"
+  --help, -h                   # Print this help
+```
+
+`-o` and `-l` may be given without a file. dry-cli requires a value for every option that takes one, so loading `Dry::CLI::UI::Flags` prepends a small hook onto `Dry::CLI` that, for the commands extending it and nothing else, turns a bare `-o`, `--output`, `-l` or `--log` into an empty value before dry-cli parses the line. A switch is bare when it comes last, or when the next argument starts with `-` and is not exactly `-`. `-o x`, `-o=x`, `--output=x`, `-ox` and `-o -` are left alone, as is everything after `--`. The rewrite is also a function of its own:
+
+```ruby
+Dry::CLI::UI::Flags.arguments(%w[export -o -l run.log])   # => ["export", "-o", "", "-l", "run.log"]
+```
+
+The hook also records the names a command was called by, which name its default files: `<executable>-<action>`, where the action is the command's names joined with `-` (`law-cli generate text` gives `law-cli-generate-text`).
+
+### Where the report goes
+
+`ui.output(output) { |io| ... }` sends what the block writes to `out` (tables, boxes and statuses at `info` and `success`) to the file `-o` named, and gives the block that file as `io` for writing to it directly. Spinners, bars, prompts and warnings stay on `err`, and so on the screen.
+
+| `-o` given         | `output:`         | The report goes to                                                                               |
+| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------ |
+| not at all         | `nil`             | the command's `out`, as usual                                                                    |
+| `-o -`             | `"-"`             | the command's `out`                                                                              |
+| `-o`               | `""`              | `log/<executable>-<action>.<YYYY-MM-DD>.<HHMMSS>.log`, stamped with the time the process started |
+| `-o reports/x.txt` | `"reports/x.txt"` | that file, relative to the current directory                                                     |
+
+`log/` is at the repository root: the nearest directory up from the current one holding `.git`, else the current directory. It is created when missing; add `/log/*` to the repository's `.gitignore` once. A file is written in colour although it is no terminal (unless `NO_COLOR` is set), its last line says when it was closed, and a line on `err` says where it is:
+
+```text
+$ mycli export -y -o | cat
+ℹ Report written to log/mycli-export.2026-10-08.031215.log
+```
+
+```text
+$ cat log/mycli-export.2026-10-08.031215.log
+┌────────────────────┬────────┐
+│ Rule               │ Amount │
+├────────────────────┼────────┤
+│ standard_deduction │ 14600  │
+│ salt_cap           │ 10000  │
+└────────────────────┴────────┘
+2 rules exported
+Closed at 2026-10-08 03:12:15 -0700
+```
+
+### Logging
+
+`ui.logging(log, level: log_level, format: log_format) { ... }` adds a SemanticLogger appender while the block runs, then flushes and removes it. `ui.logger` is a SemanticLogger logger named after the command's class, and writes nothing until an appender is added.
+
+| `-l` given   | `log:`      | The log goes to                              |
+| ------------ | ----------- | -------------------------------------------- |
+| not at all   | `nil`       | nowhere: no appender is added                |
+| `-l -`       | `"-"`       | the command's `out`                          |
+| `-l`         | `""`        | `log/<executable>-<action>.log`, appended to |
+| `-l run.log` | `"run.log"` | that file                                    |
+
+```text
+$ mycli export -n -l - | cat
+⚠ Would export 2 rules
+2026-10-08 03:11:21.436756 I [22306:1056] Export -- Exporting -- {rules: 2}
+```
+
+An unknown level or format raises `ArgumentError` naming the ones there are, as in `unknown log format "yaml", expected one of color, ecs, fluentd, json, logfmt, ...`.
+
+`ui.log_exception(e, message = nil, level: :error)` logs an exception with its backtrace. At `-L debug` the gem also records, for every exception raised while the block runs, the local variables of each frame it was raised through (with [binding_of_caller](https://github.com/banister/binding_of_caller)), and `log_exception` adds them as the payload's `locals`. Each value is its `inspect`, cut at 200 characters, for at most 25 frames, leaving out the gem's own. Recording costs time on every `raise`, which is why it happens at `debug` only. The values are whatever the program held, secrets included, so treat a debug log as you would a core dump.
+
+```ruby
+def check(amount, limit: 10_000)
+  raise ArgumentError, "over the cap" if amount > limit
+end
+
+ui.logging("-", level: "debug") do
+  check(14_600)
+rescue ArgumentError => e
+  ui.log_exception(e, "Check failed")
+end
+```
+
+```text
+2026-10-08 03:11:32.024362 E [22511:792 reporting.rb:107] check.rb -- Check failed -- {locals: [{frame: "check.rb:4", locals: {amount: "14600", limit: "10000"}}, {frame: "check.rb:8", locals: {e: "nil"}}]} -- Exception: ArgumentError: over the cap
+check.rb:4:in 'Object#check'
+check.rb:8:in 'block in <main>'
+```
+
+### All of them at once
+
+`ui.with_flags(**options) { |io| ... }` is `ui.logging` around `ui.output`, taking the whole options hash `call` receives and ignoring what it does not use, as in the `Export` command above. `dry_run:` and `yes:` are the command's to act on: return before changing anything, and pass `yes:` to `ui.confirm`.
+
+SemanticLogger and binding_of_caller load the first time a command logs, and binding_of_caller only at `debug`, so declaring the flags costs a command nothing at boot.
+
 ## Configuration
 
 Spinners and bars look the same everywhere, and are set once for the whole process:
@@ -788,10 +982,12 @@ Dry::CLI::UI.configure do
   bar_format(complete: "◼", incomplete: " ")           # or any TTY::ProgressBar bar format name, such as :box
   bar_color :green                                     # the finished part: any Pastel style, or nil
   bar_background nil                                   # the whole bar: any Pastel style, or nil
+  bar_failed_color :red                                # units counted as: :failed: any Pastel style, or nil
+  bar_aux_color :yellow                                # units counted as: :aux: any Pastel style, or nil
 end
 ```
 
-Those are the defaults: spinners turn through `⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏` ten times a second, and bars draw a green `◼` for each finished part, with nothing behind them, and brackets show where the bar begins and ends. Every spinner reads the same format, including `multi_spinner`, task trees and the status bar, and every bar reads the same characters and colours, except a bar given its own `color:`. The formats also take a definition of your own:
+Those are the defaults: spinners turn through `⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏` ten times a second, and bars draw a green `◼` for each finished part, with nothing behind them, and brackets show where the bar begins and ends. Units counted as failed or auxiliary are drawn red and yellow, and `ui.legend` names the same colours. Every spinner reads the same format, including `multi_spinner`, task trees and the status bar, and every bar reads the same characters and colours, except a bar given its own `color:`. The formats also take a definition of your own:
 
 ```ruby
 Dry::CLI::UI.configure do |config|
@@ -860,6 +1056,8 @@ Every option `Console.new` takes:
 | `clock:`     | monotonic clock       | any object whose `call` returns seconds, for elapsed times           |
 | `config:`    | `Dry::CLI::UI.config` | a `Dry::CLI::UI::Configuration` for this console alone               |
 
+`Console.new` also takes `invocation:`, a `Dry::CLI::UI::Invocation` naming the files `-o` and `-l` write (see [Reserved flags](#reserved-flags)); `ui` builds one from the command, and a console given none names them after the program alone.
+
 `config:` gives one console a look of its own without changing the process-wide one:
 
 ```ruby

data/examples/Gemfile.lock

@@ -1,10 +1,13 @@
 PATH
   remote: ..
   specs:
-    dry-cli-ui (0.6.1)
+    dry-cli-ui (0.7.0)
+      binding_of_caller (~> 2.0)
       concurrent-ruby (~> 1.3)
       dry-cli (>= 1.0)
+      logger (~> 1.6)
       pastel (~> 0.8)
+      semantic_logger (~> 5.1)
       strings (~> 0.2)
       tty-box (~> 0.7)
       tty-cursor (~> 0.7)
@@ -17,21 +20,27 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    binding_of_caller (2.0.0)
+      debug_inspector (>= 1.2.0)
     concurrent-ruby (1.3.8)
+    debug_inspector (1.2.0)
     dry-cli (1.4.1)
-    dry-cli-autocomplete (0.1.3)
+    dry-cli-autocomplete (0.6.0)
       dry-cli (>= 1.0)
       dry-inflector (>= 1.0)
-    dry-cli-help (0.2.1)
-      dry-cli (>= 1.1.1, < 2)
+    dry-cli-help (0.6.0)
+      dry-cli
       pastel (~> 0.8)
     dry-inflector (1.3.1)
     forwardable (1.4.0)
+    logger (1.7.0)
     pastel (0.8.0)
       tty-color (~> 0.5)
     prime (0.1.4)
       forwardable
       singleton
+    semantic_logger (5.1.0)
+      concurrent-ruby (~> 1.0)
     singleton (0.3.0)
     strings (0.2.1)
       strings-ansi (~> 0.2)
@@ -79,16 +88,20 @@ DEPENDENCIES
   prime
 
 CHECKSUMS
+  binding_of_caller (2.0.0) sha256=e53eebf8428a85587aede7b43a83e7419eb85b8b690938a96aa330d03052d517
   bundler (4.1.0.beta1) sha256=8a2dac8ca276ff4eff5efc2c6457b0044080fc1e431534ad7c5cc6187232b800
   concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  debug_inspector (1.2.0) sha256=9bdfa02eebc3da163833e6a89b154084232f5766087e59573b70521c77ea68a2
   dry-cli (1.4.1) sha256=b8015bb76c708aa8705a36faf694973e75eeeffca39b89c8e172dc6f66a7d874
-  dry-cli-autocomplete (0.1.3) sha256=14f76447bda0000c71739b585c827dc0a0a763e30a68a8b4b2dff91f640768e4
-  dry-cli-help (0.2.1) sha256=eaaaf6edb787ffe810425b4e4bb1a675d89397ccc759102d70b5b26e7bc692da
-  dry-cli-ui (0.6.1)
+  dry-cli-autocomplete (0.6.0) sha256=4a8b904cc802168ad1657a941cdf8dbec1915b4c825a35eb049fb0ac037947ca
+  dry-cli-help (0.6.0) sha256=10def4049bdae8c19e7412f3cefc062829048dbfa3a42155788b333c381766c9
+  dry-cli-ui (0.7.0)
   dry-inflector (1.3.1) sha256=7fb0c2bb04f67638f25c52e7ba39ab435d922a3a5c3cd196120f63accb682dcc
   forwardable (1.4.0) sha256=f1cd40cc9812937980e1c76f1aa053660990a7c9b6a98fc37d945468afcce838
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75
   prime (0.1.4) sha256=4d755ebf7c2994a6f3a3fee0d072063be3fff2d4042ebff6cd5eebd4747a225e
+  semantic_logger (5.1.0) sha256=9a8170fc0212ad47ef29e0760219cf416cb5b9973061981733234f7148b6d6ea
   singleton (0.3.0) sha256=83ea1bca5f4aa34d00305ab842a7862ea5a8a11c73d362cb52379d94e9615778
   strings (0.2.1) sha256=933293b3c95cf85b81eb44b3cf673e3087661ba739bbadfeadf442083158d6fb
   strings-ansi (0.2.0) sha256=90262d760ea4a94cc2ae8d58205277a343409c288cbe7c29416b1826bd511c88

data/lib/dry/cli/ui/configuration.rb

@@ -14,6 +14,8 @@ module Dry
       #     bar_format :box                               # any TTY::ProgressBar bar format name
       #     bar_color :cyan                               # any Pastel style, or nil
       #     bar_background nil                            # any Pastel style, or nil
+      #     bar_failed_color :red                         # any Pastel style, or nil
+      #     bar_aux_color :yellow                         # any Pastel style, or nil
       #   end
       #
       #   Dry::CLI::UI.configure do |config|
@@ -24,12 +26,15 @@ module Dry
       # Anything not set reads from {DEFAULTS}.
       class Configuration
         # What a setting reads before it is set: a green `◼` for each finished
-        # part of a bar, with no background behind it.
+        # part of a bar, with no background behind it, red for the units that
+        # failed and yellow for the auxiliary ones.
         DEFAULTS = {
           spinner_format: :dots,
           bar_format: { complete: "◼", incomplete: " " }.freeze,
           bar_color: :green,
-          bar_background: nil
+          bar_background: nil,
+          bar_failed_color: :red,
+          bar_aux_color: :yellow
         }.freeze
 
         # Every style name Pastel knows, for checking colour settings.
@@ -61,6 +66,14 @@ module Dry
         #   Reads the background the whole bar is drawn on, or sets it.
         #   @param value [Symbol, nil] a Pastel style, such as :on_blue; nil for none
         #   @return [Symbol, nil]
+        # @!method bar_failed_color(value = UNSET)
+        #   Reads the colour a bar's failed units are drawn in, or sets it.
+        #   @param value [Symbol, nil] a Pastel style, such as :red; nil for none
+        #   @return [Symbol, nil]
+        # @!method bar_aux_color(value = UNSET)
+        #   Reads the colour a bar's auxiliary units are drawn in, or sets it.
+        #   @param value [Symbol, nil] a Pastel style, such as :yellow; nil for none
+        #   @return [Symbol, nil]
         DEFAULTS.each_key do |name|
           define_method(name) do |value = UNSET|
             return @values.fetch(name) { DEFAULTS.fetch(name) } if UNSET.equal?(value)
@@ -93,6 +106,18 @@ module Dry
           @values[:bar_background] = style(:bar_background, value)
         end
 
+        # @param value [Symbol, nil] see {#bar_failed_color}
+        # @raise [ArgumentError] for a style Pastel does not know
+        def bar_failed_color=(value)
+          @values[:bar_failed_color] = style(:bar_failed_color, value)
+        end
+
+        # @param value [Symbol, nil] see {#bar_aux_color}
+        # @raise [ArgumentError] for a style Pastel does not know
+        def bar_aux_color=(value)
+          @values[:bar_aux_color] = style(:bar_aux_color, value)
+        end
+
         # @return [Array<String>] the frames a spinner cycles through
         def spinner_frames
           frames = spinner_definition(spinner_format).fetch(:frames)

data/lib/dry/cli/ui/console.rb

@@ -24,6 +24,8 @@ module Dry
       #   end
       #   ui.success "Imported #{rules.size} rules"
       class Console
+        include Reporting
+
         # @!method debug(*paragraphs, width: nil)
         #   A grey "Debug" box on `err`.
         #   @param paragraphs [Array<#to_s>] each one wrapped on its own, separated by a blank line
@@ -65,10 +67,12 @@ module Dry
         # @param box_width [Integer, nil] box width in columns; nil fills the terminal
         # @param clock [#call] returns monotonic seconds
         # @param config [Configuration] spinner and bar formats; {UI.config} by default
+        # @param invocation [Invocation, nil] names the report and log files; nil for the program alone
         def initialize(out: $stdout, err: $stderr, input: $stdin, env: ENV, color: nil, animate: nil,
-                       width: nil, box_width: nil, clock: Duration::CLOCK, config: UI.config)
+                       width: nil, box_width: nil, clock: Duration::CLOCK, config: UI.config, invocation: nil)
           @out = Terminal.new(out, env: env, color: color, animate: animate, width: width)
           @err = Terminal.new(err, env: env, color: color, animate: animate, width: width)
+          @invocation = invocation
           @input = input
           @box_width = box_width
           @clock = clock
@@ -184,6 +188,24 @@ module Dry
           Widgets::Progress.new(err, clock: clock, config: config).run(label, total: total, color: color, &)
         end
 
+        # Prints one line to `err` saying what each colour of a progress bar
+        # means, for a command to print before its first bar. Each label is
+        # optional; a label not given is left out. See {Widgets::Legend}.
+        #
+        # @example
+        #   ui.legend(failed: "errors and invalid files", aux: "relevant but auxiliary", ok: "forms")
+        #   # Color Mapping: [ red: errors and invalid files | yellow: relevant but auxiliary | green: forms ]
+        #
+        # @param failed [#to_s, nil] what the units counted `as: :failed` are
+        # @param aux [#to_s, nil] what the units counted `as: :aux` are
+        # @param ok [#to_s, nil] what the units counted `as: :ok` are
+        # @return [nil]
+        # @raise [ArgumentError] without any label
+        def legend(failed: nil, aux: nil, ok: nil) # rubocop:disable Naming/MethodParameterName
+          err.puts(Widgets::Legend.line(err, config, { failed: failed, aux: aux, ok: ok }))
+          nil
+        end
+
         # Runs several jobs at once, each with a progress bar of its own,
         # beneath a headline bar that counts them all. Each job is given a
         # {Widgets::Progress::Handle}. See {Widgets::MultiProgress}.
@@ -309,13 +331,18 @@ module Dry
           prompter.ask(question, default: default, choices: choices)
         end
 
-        # Asks a yes/no question.
+        # Asks a yes/no question: on a terminal, a list to pick YES or NO from. `yes: true`, which
+        # is what the reserved `-y/--yes` flag gives, answers it without asking.
+        #
+        # @example
+        #   exit 1 unless ui.confirm("Drop the table?", yes: yes)
         #
         # @param question [String]
         # @param default [Boolean]
+        # @param yes [Boolean] answer yes without asking
         # @return [Boolean]
-        def confirm(question, default: false)
-          prompter.confirm(question, default: default)
+        def confirm(question, default: false, yes: false)
+          yes || prompter.confirm(question, default: default)
         end
 
         private