dry-cli-ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1cbc8893268017d5d41b730292d9f6a640230ff87aa2282afd4cfc0a0084487
+  data.tar.gz: 3781eb7e227b6466555153687b6cf1783a7f4acbc6dffc1b5cd86c5b209dad91
+SHA512:
+  metadata.gz: c7a31f33372b1432c461f11319daad6503755f6c173a5bba9aee8508034de826c77ef662579471c9ce18b802098f1c426942f71e46e0d6a18c0b492fbd2a3fd9
+  data.tar.gz: 96c0528c1e32b927abf1d5f042a4879bb67e5d3cc9fa408a4d655ff020e9a01d17483a99da83aaa573d632486f8e2532a7f6c760105eb46c7b94b97083357491

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [Unreleased]
+
+## [0.1.0]
+
+- Initial release of `dry-cli-ui`, which replaces `dry-cli-autocomplete` in this repository.
+- `include Dry::CLI::UI` gives a command `ui`: `debug`, `info`, `success`, `warn`, `error` and `fatal` boxes, `box`, `status`, `spinner`, `progress`, `tasks` (nested and concurrent task trees), `table`, `prompt` and `confirm`.
+- Plain-text fallback when a stream is not a terminal or runs under `TERM=dumb`; `NO_COLOR` support.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Konstantin Gredeskoul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,248 @@
+# dry-cli-ui
+
+[![Ruby](https://github.com/kigster/dry-cli-ui/actions/workflows/main.yml/badge.svg)](https://github.com/kigster/dry-cli-ui/actions/workflows/main.yml) ![Coverage](docs/img/badge.svg)
+
+Runtime terminal UI for [dry-cli](https://github.com/dry-rb/dry-cli) commands: spinners, progress bars, boxes, status lines, task trees, tables and prompts.
+
+> [!NOTE]
+> The design, and the reasons behind it, are in [SPECIFICATION](SPECIFICATION.md).
+
+A long-running command has more to say than `puts` can show well: what it is doing now, how far along it is, what went wrong. Include one module and the command gets a `ui` that says it, in colour and in place on a terminal, and as plain lines when the output is piped to a file or a CI log.
+
+## Installation
+
+```ruby
+gem "dry-cli-ui"
+```
+
+Requires Ruby 4.0 or later.
+
+## Usage
+
+```ruby
+require "dry/cli"
+require "dry-cli-ui"
+
+class Import < Dry::CLI::Command
+  include Dry::CLI::UI
+
+  def call(**)
+    ui.info "Importing tax rules..."
+
+    rules = ui.spinner("Loading tax rules") { load_rules }
+
+    ui.progress("Importing rules", total: rules.size) do |bar|
+      rules.each do |rule|
+        import(rule)
+        bar.advance
+      end
+    end
+
+    ui.success "Imported #{rules.size} rules"
+  rescue => e
+    ui.error("Import failed", e.message)
+  end
+end
+```
+
+When the output is piped, and the import fails part way:
+
+```text
+Loading tax rules...
+✓ Loading tax rules (0.3s)
+Importing rules...
+✗ Importing rules 1482/1900 (4.1s)
+┌─ Error ──────────────────────────────────────────────────┐
+│                                                          │
+│  Import failed                                           │
+│                                                          │
+│  Could not validate rule US.2026.IRC.199A: missing       │
+│  dependency taxable_income                               │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+On a terminal the spinner turns and the bar fills in place, with percent, count and ETA, and each is replaced by the same `✓` or `✗` line when its block ends.
+
+Include the module once in a base class and every command has `ui`. Including it loads nothing: the TTY gems load the first time `ui` is used.
+
+## API
+
+### Messages
+
+```ruby
+ui.debug   "Resolved 1900 rules from 14 files"
+ui.info    "Importing tax rules..."
+ui.success "Imported 1900 rules"
+ui.warn    "3 rules have no effective date"
+ui.error   "Import failed", e.message
+ui.fatal   "Database unreachable"
+```
+
+Each draws a box with a single white border and the level's name as a coloured title. Every argument is a paragraph, wrapped to fit. The box fills the terminal less a two-column margin, or takes a fixed width:
+
+```ruby
+ui.info "Short and narrow", width: 40
+ui.box "Name: Alan Turing", "Role: Cryptanalyst", title: "Profile"   # untitled without title:
+```
+
+### Status lines
+
+```ruby
+ui.status "Connected to the database", level: :success   # ✓ Connected to the database
+ui.status "Disk nearly full", level: :warn               # ⚠ Disk nearly full
+```
+
+### Spinners
+
+```ruby
+rules = ui.spinner("Loading tax rules") { load_rules }
+```
+
+Returns the block's value. Leaves `✓ Loading tax rules (0.3s)` behind, or `✗` and the re-raised error when the block fails.
+
+### Progress bars
+
+```ruby
+ui.progress("Importing rules", total: rules.size) do |bar|
+  rules.each do |rule|
+    import(rule)
+    bar.advance        # or bar.advance(10)
+  end
+end
+```
+
+The bar shows percent, `current/total` and ETA, and ends with `✓ Importing rules 1900/1900 (4.2s)`.
+
+### Task trees
+
+The block declares the tasks; they run once it returns, so the tree is drawn complete before the first one starts.
+
+```ruby
+ui.tasks("Deploy") do |t|
+  t.task("Build assets") { build }
+  t.group("Migrate") do |g|
+    g.task("users") { migrate(:users) }
+    g.task("orders") { migrate(:orders) }
+  end
+  t.group("Warm caches", concurrent: true) do |g|
+    g.task("fonts") { warm(:fonts) }
+    g.task("images") { warm(:images) }
+  end
+  t.task("Restart") { restart }
+end
+```
+
+On a terminal, once it finishes:
+
+```text
+Deploy
+├─ ✓ Build assets (0.4s)
+├─ ✓ Migrate (0.3s)
+│  ├─ ✓ users (0.1s)
+│  └─ ✓ orders (0.2s)
+├─ ✓ Warm caches (0.5s)
+│  ├─ ✓ fonts (0.5s)
+│  └─ ✓ images (0.3s)
+└─ ✓ Restart (0.3s)
+```
+
+While it runs, the tree redraws in place and every running task has its own spinner. Piped, each line is printed once it is final, and a group's line appears as `▸` when it starts. `concurrent: true` runs a group's tasks at the same time, on a group or on `ui.tasks` itself. When a task fails, it is marked `✗`, tasks already running finish, the rest are marked skipped (`–`), and the error is re-raised.
+
+### Tables
+
+```ruby
+ui.table([["Alan Turing", 41], ["Ada Lovelace", 36]], header: %w[Name Age])
+```
+
+```text
+┌──────────────┬─────┐
+│ Name         │ Age │
+├──────────────┼─────┤
+│ Alan Turing  │ 41  │
+│ Ada Lovelace │ 36  │
+└──────────────┴─────┘
+```
+
+Tables are never truncated or rotated to fit the screen.
+
+### Prompts
+
+```ruby
+name = ui.prompt("Name?", default: "Alan Turing")
+env  = ui.prompt("Environment?", choices: %w[staging production], default: "staging")
+tier = ui.prompt("Tier?", choices: { "Free" => :free, "Pro" => :pro })
+ui.confirm("Deploy to #{env}?", default: false)
+```
+
+On a terminal these use arrow-key menus and line editing. Otherwise they read lines from standard input, so answers can be piped:
+
+```bash
+printf 'production\ny\n' | mycli deploy
+```
+
+When the input runs out, a prompt returns its default, or raises `Dry::CLI::UI::NonInteractiveError` if it has none.
+
+## Where output goes
+
+| To `out` (results)                                          | To `err` (everything else)                                                      |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `info`, `success`, `box`, `table`, `status` at those levels | `debug`, `warn`, `error`, `fatal`, spinners, progress bars, task trees, prompts |
+
+`mycli export > rules.csv` therefore writes only the command's results to the file, while its progress stays on the screen. `ui` writes to the streams dry-cli was called with, so `Dry::CLI.new(registry).call(out: io, err: io)` captures everything.
+
+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.
+
+## Configuration
+
+Override `ui` to configure the console:
+
+```ruby
+class ApplicationCommand < Dry::CLI::Command
+  include Dry::CLI::UI
+
+  def ui
+    @ui ||= Dry::CLI::UI::Console.new(
+      out: out || $stdout,
+      err: err || $stderr,
+      box_width: 72,     # boxes are 72 columns rather than the whole terminal
+      color: nil,        # true or false to override detection
+      animate: nil       # true or false to override detection
+    )
+  end
+end
+```
+
+## Relationship to dry-cli-help
+
+`dry-cli-help` is static presentation: what does this command do? `dry-cli-ui` is runtime presentation: what is this command doing? Use either, or both.
+
+```ruby
+gem "dry-cli"
+gem "dry-cli-help"
+gem "dry-cli-ui"
+```
+
+## Development
+
+```bash
+bin/setup               # bundle install
+just test               # the suite, with 100% line and branch coverage enforced
+just lint               # rubocop
+just ci                 # both
+just format             # rubocop -a, then mdformat
+bin/console             # IRB with the gem loaded
+```
+
+Specs render into a `StringIO`. The animated code paths run against `FakeTTY`, a `StringIO` that answers `tty?` with true, and elapsed times come from a fake clock.
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/kigster/dry-cli-ui>.
+
+> [!WARNING]
+> The `dry-` prefix and the `Dry::CLI::UI` namespace do not imply endorsement by `dry-rb`. This is an independent gem that extends theirs.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/SPECIFICATION.md

@@ -0,0 +1,322 @@
+# `dry-cli-ui`
+
+Rich runtime terminal UI for [`dry-cli`](https://github.com/dry-rb/dry-cli) commands.
+
+## Purpose
+
+`dry-cli-ui` gives ordinary `dry-cli` commands a high-level API for presenting their **runtime state**.
+
+It is particularly useful for long-running commands where plain `puts` output does not adequately communicate progress, activity, warnings, failures, or completion.
+
+It is not intended primarily as a framework for building full-screen terminal applications.
+
+Instead, it adds rich terminal UI to normal CLI commands while preserving the familiar command-line experience and terminal scrollback.
+
+## Responsibilities
+
+- Spinners
+- Progress bars
+- Status messages
+- Success messages
+- Warning messages
+- Error messages
+- Styled boxes and panels
+- Tables
+- Task trees
+- Nested operations
+- Several operations running at once
+- Elapsed time and ETA
+- Interactive prompts
+- Terminal-aware rendering
+- Graceful fallback when ANSI/interactive output is unavailable
+
+## Example
+
+```ruby
+class Import < Dry::CLI::Command
+  include Dry::CLI::UI
+
+  def call(**)
+    ui.info "Importing tax rules..."
+
+    ui.spinner("Loading tax rules") do
+      load_rules
+    end
+
+    ui.progress("Importing rules", total: rules.size) do |bar|
+      rules.each do |rule|
+        import(rule)
+        bar.advance
+      end
+    end
+
+    ui.success "Imported #{rules.size} rules"
+  rescue => e
+    ui.error("Import failed", e.message)
+  end
+end
+```
+
+Example output, piped, when the import fails part way:
+
+```text
+Loading tax rules...
+✓ Loading tax rules (0.3s)
+Importing rules...
+✗ Importing rules 1482/1900 (4.1s)
+┌─ Error ──────────────────────────────────────────────────┐
+│                                                          │
+│  Import failed                                           │
+│                                                          │
+│  Could not validate rule US.2026.IRC.199A: missing       │
+│  dependency taxable_income                               │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+On a terminal the spinner turns and the bar fills in place (`Importing rules ███████░░░ 78%  1482/1900  ETA  4s`), and each is replaced by the same outcome line when its block ends.
+
+## API
+
+Commands depend on a small semantic API rather than directly manipulating terminal primitives:
+
+```ruby
+ui.debug(...)
+ui.info(...)
+ui.success(...)
+ui.warn(...)
+ui.error(...)
+ui.fatal(...)
+
+ui.spinner(...)
+ui.progress(...)
+ui.status(...)
+
+ui.box(...)
+ui.table(...)
+ui.tasks(...)
+
+ui.prompt(...)
+ui.confirm(...)
+```
+
+This separates **what the command wants to communicate** from **how the terminal renders it**.
+
+## Rendering
+
+The implementation builds on existing Ruby terminal libraries rather than reimplementing terminal mechanics: `tty-box`, `tty-spinner`, `tty-progressbar`, `tty-table`, `tty-prompt`, `tty-cursor`, `tty-screen`, `pastel` and `strings`.
+
+The public API does not expose these dependencies. No method returns or yields a TTY object, and no argument takes one.
+
+That leaves open the possibility of introducing other renderers later, including richer inline TUI implementations, without changing application command code.
+
+## Design Principle
+
+`dry-cli-ui` owns what the user sees **while a command runs and when it finishes**.
+
+```text
+dry-cli
+    │
+    └── dry-cli-ui
+          │
+          ├── spinner
+          ├── progress
+          ├── status
+          ├── debug/info/success/warn/error/fatal
+          ├── boxes
+          ├── tables
+          ├── task trees
+          └── prompts
+```
+
+## Relationship to dry-cli-help
+
+The two gems deliberately have separate responsibilities:
+
+```text
+dry-cli
+    │
+    ├── dry-cli-help
+    │     Static presentation
+    │
+    │     "What does this command do?"
+    │
+    └── dry-cli-ui
+          Runtime presentation
+
+          "What is this command doing?"
+```
+
+A CLI application can use either gem independently or combine them:
+
+```ruby
+gem "dry-cli"
+gem "dry-cli-help"
+gem "dry-cli-ui"
+```
+
+Together they provide richer presentation without turning `dry-cli` itself into a large terminal UI framework.
+
+## Boxes
+
+`debug`, `info`, `success`, `warn`, `error` and `fatal` each draw a box:
+
+- a single-line white border,
+- the level's name as a bold, coloured title in the top border (`┌─ Error ───`),
+- one blank row above and below the text and two columns either side,
+- each argument as its own paragraph, wrapped to fit, separated by a blank line.
+
+The width is one of:
+
+1. a fixed number of columns, per console (`Console.new(box_width: 72)`) or per call (`ui.info("...", width: 72)`), never wider than the terminal;
+1. the whole terminal less a two-column margin, which is the default.
+
+A box is never narrower than 20 columns. `ui.box(*paragraphs, title:, level:)` draws the same frame without a level, or with a level's styling and a different title.
+
+| Level     | Title   | Glyph | Colour  | Stream |
+| --------- | ------- | ----- | ------- | ------ |
+| `debug`   | Debug   | `·`   | grey    | err    |
+| `info`    | Info    | `ℹ`   | cyan    | out    |
+| `success` | Success | `✓`   | green   | out    |
+| `warn`    | Warning | `⚠`   | yellow  | err    |
+| `error`   | Error   | `✗`   | red     | err    |
+| `fatal`   | Fatal   | `✖`   | magenta | err    |
+
+`success` and `fatal` were added to the original five (`debug`, `info`, `warn`, `error`, `fatal`) because the example above uses `success`.
+
+## Design decisions
+
+### Architecture
+
+```mermaid
+flowchart LR
+  Command["Dry::CLI::Command<br/>include Dry::CLI::UI"] -->|"#ui"| Console
+  Console --> OutTerm["Terminal (out)"]
+  Console --> ErrTerm["Terminal (err)"]
+  Console --> Widgets
+  subgraph Widgets
+    Box
+    Status
+    Spinner
+    Progress
+    Tasks
+    Table
+    Prompt
+  end
+  Widgets --> TTY["TTY toolkit, Pastel, Strings"]
+```
+
+| File                          | Role                                                                       |
+| ----------------------------- | -------------------------------------------------------------------------- |
+| `lib/dry/cli/ui.rb`           | The mixin. Defines `#ui` and autoloads everything else.                    |
+| `lib/dry/cli/ui/console.rb`   | The public API. Routes each call to a widget and a stream.                 |
+| `lib/dry/cli/ui/terminal.rb`  | One stream and what it can do: TTY, animation, colour, width, height.      |
+| `lib/dry/cli/ui/theme.rb`     | Levels (title, glyph, colour, stream) and operation states.                |
+| `lib/dry/cli/ui/duration.rb`  | The monotonic clock and `0.4s` / `1m 02s` / `1h 02m` formatting.           |
+| `lib/dry/cli/ui/widgets/*.rb` | One renderer per widget, each owning its rich form and its plain fallback. |
+
+Only files under `widgets/` and `terminal.rb` touch a TTY class. A future renderer replaces widgets, not `Console`.
+
+### Including costs nothing at boot
+
+`include Dry::CLI::UI` loads the mixin and nothing else. `Console`, the widgets and every TTY gem are autoloaded on first use, so a command that never calls `ui` never loads them. A spec pins this by checking `$LOADED_FEATURES` in a fresh process.
+
+### Streams
+
+Results go to `out`; everything about the command's own progress goes to `err`. Piping a command therefore captures its results and nothing else.
+
+| `out`                             | `err`                                                                      |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| `info`, `success`, `box`, `table` | `debug`, `warn`, `error`, `fatal`, `spinner`, `progress`, `tasks`, prompts |
+| `status` at `info` or `success`   | `status` at `debug`, `warn`, `error` or `fatal`                            |
+
+`#ui` uses the command's own `out` and `err` when dry-cli has set them (`Dry::CLI#call(out:, err:)`), and `$stdout` and `$stderr` otherwise. Every write flushes, so the two streams stay in order when both are piped to the same place.
+
+### Terminal detection and fallback
+
+Each stream is judged on its own:
+
+| Condition                          | Animation and cursor movement | Colour |
+| ---------------------------------- | ----------------------------- | ------ |
+| TTY                                | yes                           | yes    |
+| TTY with `NO_COLOR` set, non-empty | yes                           | no     |
+| TTY with `TERM=dumb`               | no                            | no     |
+| not a TTY                          | no                            | no     |
+
+`Console.new(color:, animate:, width:)` overrides detection. Without animation:
+
+| Widget                | Plain output                                                                                       |
+| --------------------- | -------------------------------------------------------------------------------------------------- |
+| spinner               | `Label...` before the block, `✓ Label (1.2s)` or `✗ Label (1.2s)` after it                         |
+| progress              | `Label...` before, `✓ Label 1900/1900 (4.2s)` after, with the count reached                        |
+| tasks                 | each line printed once final: a group when it starts, a task when it ends, skipped ones at the end |
+| prompts               | the question on `err`, one line read from input                                                    |
+| boxes, tables, status | unchanged apart from colour                                                                        |
+
+### Spinners and progress bars
+
+Both run a block, return what it returns, and re-raise what it raises after marking the outcome `✗`. The elapsed time comes from a monotonic clock. `ui.progress` yields a handle with `advance(step = 1)`, `current` and `total`; progress is clamped to `0..total`, and `total: 0` is allowed.
+
+### Task trees
+
+The block declares the tree; nothing runs until it returns. Knowing the whole shape first is what lets the tree draw `├─` and `└─` correctly before the first task starts.
+
+```ruby
+ui.tasks("Deploy") do |t|
+  t.task("Build assets") { build }
+  t.group("Migrate") do |g|
+    g.task("users") { migrate(:users) }
+    g.task("orders") { migrate(:orders) }
+  end
+  t.group("Warm caches", concurrent: true) do |g|
+    g.task("fonts") { warm(:fonts) }
+    g.task("images") { warm(:images) }
+  end
+  t.task("Restart") { restart }
+end
+```
+
+- Tasks run in order. A group declared `concurrent: true`, or `ui.tasks(concurrent: true)` at the top level, runs its tasks at the same time on `concurrent-ruby` futures.
+- States are pending `○`, running `▸`, done `✓`, failed `✗` and skipped `–`. On an animated terminal a running task shows a turning spinner instead of `▸`, so a concurrent group is a multi-spinner.
+- When a task raises, it and its enclosing groups are marked failed, tasks already running beside it finish, tasks not yet started are marked skipped, and the first error is re-raised.
+- The live tree is redrawn in place with cursor movement, which cannot reach above the top of the screen. A tree with as many rows as the screen, or more, is printed line by line instead.
+- Task blocks should not write to the terminal while a live tree is drawn; the next redraw overwrites their output.
+
+### Tables
+
+`ui.table(rows, header:)` renders with box-drawing borders and a bold header. Tables are data, so they are never narrowed, truncated or rotated to fit the screen. TTY::Table otherwise measures the screen, prints a warning on STDERR, and turns a wide table on its side.
+
+### Prompts
+
+`ui.prompt(question, default:, choices:)` asks for a line of text, or for one of `choices` (an Array of names, or a Hash of names to the values returned). `ui.confirm(question, default: false)` asks yes or no.
+
+With an interactive input and output they use `tty-prompt`'s line editing and arrow-key menus. Otherwise they read lines, so answers can be piped in:
+
+```bash
+printf 'production\ny\n' | mycli deploy
+```
+
+An empty answer takes the default. An exhausted input takes the default too, and a question with no default raises `Dry::CLI::UI::NonInteractiveError` rather than inventing an answer. An answer that is not a valid choice, or not yes or no, asks again.
+
+### A TTY::Box defect worked around
+
+With a fixed width, TTY::Box 0.7 wraps text but sizes the box from the unwrapped lines, so everything past the first rows is silently dropped. `Widgets::Box` wraps the text with `Strings::Wrap` first, leaving TTY::Box nothing to wrap.
+
+## Acceptance criteria
+
+- [x] `include Dry::CLI::UI` gives a command `#ui`; including it loads no TTY gem.
+- [x] `#ui` writes to the streams dry-cli was called with.
+- [x] `debug`, `info`, `success`, `warn`, `error` and `fatal` draw white single-line boxes titled by level, wrapped, as wide as configured or the terminal less a margin, and never lose text.
+- [x] `spinner`, `progress` and `tasks` return their block's value, re-raise its error, and leave an outcome line with the elapsed time; progress shows percent, count and ETA.
+- [x] Task trees nest, run groups concurrently when asked, and mark failed and skipped tasks.
+- [x] Tables render rows and a header without truncation.
+- [x] Prompts work interactively and from piped input, and never block on an exhausted input.
+- [x] Output that is not a TTY, or runs under `TERM=dumb`, contains no escape sequences; `NO_COLOR` removes colour.
+- [x] The public API exposes no TTY object.
+- [x] 100% line and branch coverage, enforced by the suite.
+
+## Out of scope
+
+- Full-screen applications, alternate screen buffers, and a public cursor-positioning API. TTY::Cursor and TTY::Screen are used internally only.
+- Keyboard input beyond prompts.
+- Renderers other than the TTY toolkit. The widget boundary allows one later.