dry-cli-help 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8756ab593e09c6cdc0e0ab32fe6f3909d05625734a07e7d7c334e3d832ba70ac
+  data.tar.gz: 4477df389d4c4c0d984fe4024f768adf3e254772464694f7acd81609936060a4
+SHA512:
+  metadata.gz: 6a61174289b02e6a523ba5ccdae1a79cd72241ea7c5bb16de5d543e3aad488a3de9d973644a0297c2c94e0516475241c490470f5d52208f450d7efc243dfd575
+  data.tar.gz: 041553f6adda56086400f208d6bef2ce77613e635581e871ffc58488a3ead1cca4038c3ce4d89f39e79049f529ffaa7cb013dea09bea8701e9c7b5c78ea1d3eb

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-12
+
+- Initial release as `dry-cli-help`, converted from `dry-cli-autocomplete`. The shell completion generator is removed; that gem remains the place for it.
+- Help screens with a title, description and epilogue, uppercase headings, aligned and wrapped descriptions, and ANSI colors through `pastel`.
+- Settings through `Dry::CLI::Help.configure` for the whole process and a `help` block on any registry: `title`, `description`, `epilogue`, `color`, `wrap`, `width`, `margin`, `exit_code_without_arguments`, `banner_on_subcommands`, `heading_case`, `command_order`, `heading`, `style`, `group`, `sections` and `hide`.
+- `-h` and `--help` at a registry level exit 0. Running with no command keeps dry-cli's exit status 1 unless configured otherwise.
+- `Dry::CLI::Help::Colors`, a module exposing every foreground, background and text style as a method.

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-help
+
+[![Ruby](https://github.com/kigster/dry-cli-help/actions/workflows/main.yml/badge.svg)](https://github.com/kigster/dry-cli-help/actions/workflows/main.yml) ![Coverage](docs/img/badge.svg)
+
+Configurable, wrapped, colored help screens for [dry-cli](https://github.com/dry-rb/dry-cli) applications.
+
+> [!NOTE]
+> The design, the settings and every decision behind them are in [SPECIFICATION.md](SPECIFICATION.md).
+
+dry-cli prints help as it finds it: no title, no description of the program, no color, one line per description however long, and commands sorted alphabetically. This gem keeps the command structure you already declared and changes only what the user reads before a command runs. Progress bars, spinners and error panels belong in `dry-cli-ui`.
+
+## Before and after
+
+`taxlibris compile -h` with dry-cli alone:
+
+```text
+Command:
+  taxlibris compile
+
+Usage:
+  taxlibris compile RULES [OUTPUT]
+
+Description:
+  Compile tax rules
+
+Arguments:
+  RULES                             # REQUIRED Rule file to compile
+  OUTPUT                            # Where to write the compiled rules
+
+Options:
+  --format=VALUE, -f VALUE          # Output format: (json/yaml), default: "json"
+  --[no-]strict                     # Treat warnings as errors
+  --help, -h                        # Print this help
+```
+
+With `require "dry/cli/help"`:
+
+```text
+USAGE
+  taxlibris compile RULES [OUTPUT] [OPTIONS]
+
+DESCRIPTION
+  Compile tax rules
+
+ARGUMENTS
+  RULES               Rule file to compile (required)
+  OUTPUT              Where to write the compiled rules
+
+OPTIONS
+  -f, --format=VALUE  Output format (one of: json, yaml; default: "json")
+  --[no-]strict       Treat warnings as errors
+  -h, --help          Show help
+```
+
+Headings are bold and yellow, commands green, options and arguments cyan, and every description wraps to the terminal with a hanging indent.
+
+## Installation
+
+```bash
+gem install dry-cli-help
+```
+
+Or add `gem "dry-cli-help"` to your `Gemfile`.
+
+## Usage
+
+Require it after dry-cli. That alone changes every help screen in the process.
+
+```ruby
+require "dry/cli"
+require "dry/cli/help"
+```
+
+Describe the program in the registry:
+
+```ruby
+module Taxlibris
+  module CLI
+    extend Dry::CLI::Registry
+
+    help do
+      title "Taxlibris"
+
+      description <<~TEXT
+        Compile, validate, and evaluate tax rules.
+      TEXT
+
+      epilogue "Documentation: https://example.com/taxlibris"
+
+      color :auto
+      width :terminal
+      wrap true
+    end
+
+    register "compile", Compile
+    register "validate", Validate
+    register "evaluate", Evaluate
+    register "version", Version, aliases: ["--version", "-v"]
+  end
+end
+```
+
+`taxlibris -h` then prints:
+
+```text
+Taxlibris
+
+Compile, validate, and evaluate tax rules.
+
+USAGE
+  taxlibris COMMAND [OPTIONS]
+
+COMMANDS
+  compile        Compile tax rules
+  validate       Validate the rule corpus
+  evaluate       Evaluate a tax return
+  version        Show version
+
+OPTIONS
+  -h, --help     Show help
+  -v, --version  Show version
+
+Documentation: https://example.com/taxlibris
+```
+
+A command reachable as `--version` lists under Options by its dashed names.
+
+Settings for the whole process go through `configure`. A registry's `help` block overrides them:
+
+```ruby
+Dry::CLI::Help.configure do |config|
+  config.width = 100
+  config.color = false
+end
+```
+
+A `help` block that takes an argument receives the configuration instead, so `help { |h| h.title = "Taxlibris" }` works too.
+
+## Settings
+
+| Setting                       | Values                            | Default         |
+| ----------------------------- | --------------------------------- | --------------- |
+| `title`                       | String                            | none            |
+| `description`                 | String                            | none            |
+| `epilogue`                    | String                            | none            |
+| `color`                       | `true`, `false`, `:auto`          | `:auto`         |
+| `wrap`                        | `true`, `false`                   | `true`          |
+| `width`                       | `:terminal`, Integer              | `:terminal`     |
+| `margin`                      | Integer                           | `0`             |
+| `exit_code_without_arguments` | 0 to 255                          | `1`             |
+| `banner_on_subcommands`       | `true`, `false`                   | `false`         |
+| `heading_case`                | `:upcase`, `:capitalize`, `:none` | `:upcase`       |
+| `command_order`               | `:registration`, `:alphabetical`  | `:registration` |
+
+`color :auto` colors a terminal and honors [`NO_COLOR`](https://no-color.org). `width :terminal` reads `COLUMNS`, then the console, then falls back to 80, and `margin` keeps columns free at the right edge.
+
+Running the program with no command prints the top-level help and exits 1, as dry-cli does. `exit_code_without_arguments 0` prints it to stdout and exits 0 instead. `-h` and `--help` always exit 0.
+
+### Headings, sections and groups
+
+```ruby
+help do
+  heading :commands, "Available commands"
+  heading_case :capitalize
+
+  group "Rules", "compile", "validate"
+  group "Returns", "evaluate"
+
+  hide :examples
+  sections :banner, :usage, :commands, :options, :epilogue
+end
+```
+
+- `heading` replaces one section's heading text.
+- `group` lists commands under a heading of their own, in the order given. Ungrouped commands stay under Commands. A group inside a group names the full path, such as `"db migrate"`.
+- `sections` sets the order; a section left out is hidden. `hide` hides sections without restating the order.
+
+The sections are `banner`, `usage`, `description`, `commands`, `subcommands`, `arguments`, `options`, `examples` and `epilogue`. Each screen prints the ones that apply to it.
+
+### Styles
+
+```ruby
+help do
+  style :heading, :bold, :bright_blue
+  style :comment            # no styles: print it plain
+end
+```
+
+The styled elements are `title`, `heading`, `command`, `argument`, `option` and `comment`, the last being the part of an example after the first `#` surrounded by spaces, as in `"rules.form # compile one file"`.
+
+### The Colors module
+
+Every style is also available to your own code:
+
+```ruby
+class Deploy < Dry::CLI::Command
+  include Dry::CLI::Help::Colors
+
+  def call(**)
+    puts green("Deployed.")
+    puts red.bold("Rolled back.")
+  end
+end
+```
+
+The methods are the eight colors `black red green yellow blue magenta cyan white`, their `bright_` forms, the `on_` and `on_bright_` backgrounds, and `clear bold dim italic underline inverse hidden strikethrough`. `Dry::CLI::Help::Colors.enabled = false` turns them all off.
+
+## How it works
+
+The gem prepends one module to `Dry::CLI`, overriding the two private methods dry-cli prints help from. It does not replace `Dry::CLI::Banner` or `Dry::CLI::Usage`.
+
+```mermaid
+flowchart LR
+  argv[ARGV] --> call["Dry::CLI#call"]
+  call -->|"command found, -h given"| help["#help"]
+  call -->|"no command, a group, -h at a level, a typo"| spell["#spell_checker"]
+  help --> command[Screens::Command]
+  spell --> listing[Screens::Listing]
+  command --> formatter[Formatter]
+  listing --> formatter
+  config["Help.configure + registry help block"] --> formatter
+  formatter --> out[stdout or stderr]
+```
+
+Both methods are `@api private` in dry-cli. `spec/dry/cli/help/dry_cli_contract_spec.rb` asserts every internal the gem reads, so a dry-cli release that moves one fails this suite, naming what moved.
+
+## Development
+
+```bash
+just install     # bundle install
+just test        # the suite; a full run enforces 100% line and branch coverage
+just lint        # rubocop
+just ci          # both
+just lefthook    # every pre-commit hook against every file
+just format      # rubocop -a, then mdformat --wrap no on every Markdown file
+bin/console      # IRB with the gem loaded
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/kigster/dry-cli-help>.
+
+> [!WARNING]
+> The `dry-` prefix and the `Dry::CLI::Help` namespace do not imply endorsement by dry-rb. This is an independent gem that extends theirs.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+
+def shell(*args)
+  puts "running: #{args.join(' ')}"
+  system(args.join(" "))
+end
+
+task :clean do
+  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
+end
+
+task gem: [:build] do
+  shell("gem install pkg/*")
+end
+
+task permissions: [:clean] do
+  # One traversal replaces a six-level glob chain that printed "No such file
+  # or directory" for every level this project does not have, skipped dotfiles
+  # entirely, and silently stopped at depth six. .git is pruned: its objects
+  # have no business being group-readable.
+  shell("find . -path ./.git -prune -o -type d -exec chmod o+rx,g+rx {} + -o -type f -exec chmod o+r,g+r {} +")
+end
+
+task build: :permissions
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = %w[lib/**/*.rb - README.md LICENSE.txt CHANGELOG.md SPECIFICATION.md]
+  t.options.unshift("--title", '"dry-cli-help: configurable help screens for dry-cli"')
+  t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/SPECIFICATION.md

@@ -0,0 +1,200 @@
+# dry-cli-help
+
+Enhanced help presentation for [`dry-cli`](https://github.com/dry-rb/dry-cli).
+
+## Purpose
+
+`dry-cli-help` improves the **static, human-facing documentation** generated by `dry-cli`.
+
+It does not replace `dry-cli` or introduce another command framework. It takes the command structure already defined through `dry-cli` and provides richer, more configurable help output.
+
+## Responsibilities
+
+- Top-level application title and description
+- Command descriptions
+- Automatic line wrapping based on terminal width
+- ANSI color and styling
+- Configurable headings
+- Improved spacing and indentation
+- Usage formatting
+- Arguments and options formatting
+- Examples
+- Epilogues
+- Command grouping
+- Section ordering
+- Hiding or customizing sections
+- Consistent formatting across commands
+
+## Example
+
+```ruby
+require "dry/cli"
+require "dry/cli/help"
+
+Dry::CLI::Help.configure do |config|
+  config.width = :terminal
+  config.wrap = true
+  config.color = true
+end
+```
+
+An application could provide richer top-level help:
+
+```ruby
+class CLI
+  extend Dry::CLI::Registry
+
+  help do
+    title "Taxlibris"
+
+    description <<~TEXT
+      Compile, validate, and evaluate tax rules.
+    TEXT
+
+    color true
+    width :terminal
+    wrap true
+  end
+end
+```
+
+Result:
+
+```text
+Taxlibris
+
+Compile, validate, and evaluate tax rules.
+
+USAGE
+  taxlibris COMMAND [OPTIONS]
+
+COMMANDS
+  compile       Compile tax rules
+  validate      Validate the rule corpus
+  evaluate      Evaluate a tax return
+
+OPTIONS
+  --help        Show help
+  --version     Show version
+```
+
+## Design Principle
+
+`dry-cli-help` owns what the user sees **before a command runs**.
+
+It should remain focused on documentation and presentation rather than runtime command UI.
+
+Runtime features such as progress bars, spinners, status displays, and error panels belong in `dry-cli-ui`.
+
+## Relationship
+
+```text
+dry-cli
+    │
+    └── dry-cli-help
+          │
+          ├── descriptions
+          ├── usage
+          ├── wrapping
+          ├── headings
+          ├── colors
+          ├── arguments/options
+          └── examples
+```
+
+## Requirements carried from the first draft
+
+1. **Exit status without arguments.** dry-cli prints the command list and exits 1 when run with no command. The status is configurable. Asking for help with `-h` or `--help` always exits 0.
+1. **Banner.** The title and description print above the command list for `mycli`, `mycli -h` and `mycli --help`. A separate setting decides whether they also print for `mycli subcommand -h`.
+1. **Wrapping.** Three modes: no wrapping (dry-cli's behavior), wrapping at a fixed column such as 80 or 100, and wrapping at the terminal's width minus an optional margin.
+1. **Colors.** Built on `pastel`. A `Colors` module, when included, makes each style below available as a method: `red("text")` returns decorated text, and `red.bold("text")` chains.
+   - Foreground: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, and the `bright_` form of each.
+   - Background: `on_black`, `on_red`, `on_green`, `on_yellow`, `on_blue`, `on_magenta`, `on_cyan`, `on_white`, and the `on_bright_` form of each.
+   - Styles: `clear`, `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`.
+
+## Decisions
+
+### Integration
+
+Requiring `dry/cli/help` changes help output for every `Dry::CLI` in the process. It does not replace `Dry::CLI::Banner` or `Dry::CLI::Usage`. It prepends one module to `Dry::CLI` that overrides two private methods, the only two places dry-cli prints help:
+
+| dry-cli method                         | When dry-cli calls it                                      |
+| -------------------------------------- | ---------------------------------------------------------- |
+| `Dry::CLI#help(command, prog_name)`    | `mycli deploy -h`, for any command with a class            |
+| `Dry::CLI#spell_checker(result, argv)` | `mycli`, `mycli -h`, `mycli db` for a group, `mycli bogus` |
+
+Both are `@api private` in dry-cli 1.4.1. A spec asserts they exist, so a dry-cli release that renames them fails this gem's suite rather than a host's help screen. `Dry::CLI::Help::Integration` holds the override.
+
+`help` is added to `Dry::CLI::Registry`, so any module or class that extends a registry can call it.
+
+### Configuration
+
+Two levels, one vocabulary. `Dry::CLI::Help.configure` sets process-wide values. A registry's `help` block overrides them for that registry. A setting neither level sets takes the default below.
+
+Every setting reads and writes both ways: `title "Taxlibris"` inside a `help` block, and `config.title = "Taxlibris"` on the yielded object. A `help` block taking one argument receives the configuration instead of being evaluated against it.
+
+| Setting                       | Values                               | Default         | Effect                                                                 |
+| ----------------------------- | ------------------------------------ | --------------- | ---------------------------------------------------------------------- |
+| `title`                       | String                               | none            | First line of the banner                                               |
+| `description`                 | String                               | none            | Paragraphs under the title, wrapped                                    |
+| `epilogue`                    | String                               | none            | Paragraphs at the end of the top-level help                            |
+| `color`                       | `true`, `false`, `:auto`             | `:auto`         | `:auto` colors a terminal and honors `NO_COLOR`                        |
+| `wrap`                        | `true`, `false`                      | `true`          | `false` prints descriptions as written                                 |
+| `width`                       | `:terminal`, Integer                 | `:terminal`     | The column text wraps at                                               |
+| `margin`                      | Integer                              | `0`             | Columns kept free at the right edge when `width` is `:terminal`        |
+| `exit_code_without_arguments` | Integer, 0 to 255                    | `1`             | Status for `mycli` or `mycli group` with no command                    |
+| `banner_on_subcommands`       | `true`, `false`                      | `false`         | Print the title and description above `mycli command -h`               |
+| `heading_case`                | `:upcase`, `:capitalize`, `:none`    | `:upcase`       | How every heading is cased; `:capitalize` raises only the first letter |
+| `command_order`               | `:registration`, `:alphabetical`     | `:registration` | Order commands list in; dry-cli sorts alphabetically                   |
+| `heading(section, text)`      | Section name, String                 | see below       | Replaces one heading's text                                            |
+| `style(element, *styles)`     | Element name, `Colors::STYLES` names | see below       | Replaces one element's styles                                          |
+| `group(name, *commands)`      | String, command paths                | none            | Lists those commands under their own heading, in declaration order     |
+| `sections(*names)`            | Section names                        | all             | Order of sections; a section left out is hidden                        |
+| `hide(*names)`                | Section names                        | none            | Hides sections without restating the order                             |
+
+Terminal width comes from `COLUMNS`, then the console, then 80. A resolved wrap width never falls below 20 columns.
+
+### Sections
+
+In default order, with default headings:
+
+| Section       | Heading     | Top-level help | Command help                        |
+| ------------- | ----------- | -------------- | ----------------------------------- |
+| `banner`      | none        | yes            | when `banner_on_subcommands` is set |
+| `usage`       | Usage       | yes            | yes                                 |
+| `description` | Description | no             | yes                                 |
+| `commands`    | Commands    | yes            | no                                  |
+| `subcommands` | Subcommands | no             | when the command has children       |
+| `arguments`   | Arguments   | no             | yes                                 |
+| `options`     | Options     | yes            | yes                                 |
+| `examples`    | Examples    | no             | yes                                 |
+| `epilogue`    | none        | yes            | only for a single command           |
+
+A single command passed to `Dry::CLI.new(SomeCommand)` is the whole program, so its command help prints the banner and the epilogue too. It has no registry, so it renders with the process-wide settings alone.
+
+A group listing, `mycli db` where `db` has no command of its own, renders as top-level help scoped to the group, with the banner only when `banner_on_subcommands` is set, and no epilogue.
+
+Every Options section starts with `-h, --help  Show help`, because both spellings work at every level. The example above shows `--help` alone; `spec/dry/cli/help/integration_spec.rb` holds the exact output.
+
+At any level, a command registered under a name or alias starting with `-`, such as `register "version", Version, aliases: ["--version"]`, lists under Options rather than Commands.
+
+### Styled elements
+
+| Element    | Default styles   | Applies to                             |
+| ---------- | ---------------- | -------------------------------------- |
+| `title`    | `bold`           | The banner title                       |
+| `heading`  | `bold`, `yellow` | Every section heading                  |
+| `command`  | `green`          | Command names and the program in usage |
+| `argument` | `cyan`           | Argument names                         |
+| `option`   | `cyan`           | Option names                           |
+| `comment`  | `bright_black`   | The comment half of an example         |
+
+### Layout
+
+- Every section after the first starts after one blank line. Section bodies indent two columns.
+- A definition list (commands, arguments, options) aligns its descriptions in one column across the whole screen, two columns past the longest term that has a description. The column never passes half the wrap width, and a term longer than the column puts its description on the next line.
+- Examples align among themselves. A full command line is longer than any option, and sharing its column would push every other description to the right.
+- A group registered without a command has no description of its own, so it lists as `Subcommands: a, b`.
+- An argument or option description ends with what a reader needs to supply it: `(required; one of: json, yaml; default: "json")`. An array argument reads `NAME...`.
+- Descriptions wrap with a hanging indent under the description column. Paragraphs split on blank lines and reflow; a line starting with whitespace prints verbatim.
+- An example written `"prod # ship to production"` renders the part after the first `#` surrounded by spaces as its description.

data/lib/dry/cli/help/colors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Help
+      # Every pastel style as a method. Include it, or extend a module with it:
+      #
+      #   include Dry::CLI::Help::Colors
+      #
+      #   red("text")          # => decorated text
+      #   red.bold("text")     # => chained styles
+      #
+      # Whether the methods decorate is one process-wide switch, {Colors.enabled=}.
+      # Help screens do not read it: they follow the `color` setting instead.
+      module Colors
+        HUES = %i[black red green yellow blue magenta cyan white].freeze
+        FOREGROUNDS = (HUES + HUES.map { :"bright_#{it}" }).freeze
+        BACKGROUNDS = FOREGROUNDS.map { :"on_#{it}" }.freeze
+        MODIFIERS = %i[clear bold dim italic underline inverse hidden strikethrough].freeze
+        STYLES = (FOREGROUNDS + BACKGROUNDS + MODIFIERS).freeze
+
+        # Values the color switch and the `color` setting accept.
+        SETTINGS = [true, false, :auto].freeze
+
+        @enabled = :auto
+
+        class << self
+          # @return [Boolean, Symbol] true, false or :auto
+          attr_reader :enabled
+
+          # @param value [Boolean, Symbol] true, false or :auto
+          def enabled=(value)
+            raise ArgumentError, "color must be one of #{SETTINGS.inspect}, got #{value.inspect}" \
+              unless SETTINGS.include?(value)
+
+            @enabled = value
+            @pastel = nil
+          end
+
+          # @return [Pastel] shared by every includer, rebuilt when the switch changes
+          def pastel
+            @pastel ||= ::Pastel.new(enabled: enabled_for?(enabled, $stdout))
+          end
+
+          # `:auto` colors a terminal unless NO_COLOR is set to anything but
+          # the empty string. https://no-color.org
+          #
+          # @param setting [Boolean, Symbol] true, false or :auto
+          # @param io [IO, #tty?] where the text is going
+          # @return [Boolean]
+          def enabled_for?(setting, io)
+            return setting unless setting == :auto
+
+            io.respond_to?(:tty?) && io.tty? && ENV.fetch("NO_COLOR", "").empty?
+          end
+        end
+
+        # @return [Pastel]
+        def pastel
+          Colors.pastel
+        end
+
+        STYLES.each do |style|
+          define_method(style) do |*text|
+            text.empty? ? pastel.public_send(style) : pastel.public_send(style, *text)
+          end
+        end
+      end
+    end
+  end
+end