dry-cli-help 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf20fa0aacf131ed2906f0db379bc73dff9e6f73d106e9748f9db3efb589892c
-  data.tar.gz: 2407d232a6fc663f175431e8c907b1352e6ec13cda833a64530ea1f53e58b58c
+  metadata.gz: c804fb8b2d9f9e370e85b45d2e4174c27e0c06aea1139d4af5055c31fb8709f7
+  data.tar.gz: ea846d4e056da46f9762e77b9df2a65c145df4003e58b41707446de94341b74c
 SHA512:
-  metadata.gz: aaf06bce6593191d6fe7ef465df68afd6679877e1b412f8c8a654c04420b24229268c8a82a4ac9766e3d063a4b34c790636ea2aa15de77327bb291ae131755d8
-  data.tar.gz: 9c790e6b9b235577b2f92ffacf0f6648c4164ceaa00192f343e1dcb2aeae93326368f9bdace5c90763acc14fcc70411010306141881d778bcf8201142c1e7ffc
+  metadata.gz: e95c0a85b03b6a4837726c65419a6caa138f7041bcff9e184585a72bf29d49c6b7542e74bcc3f2941537f36cc06765d17cbd5be953a4ec68a0fd88d589273b9e
+  data.tar.gz: 314634677bcdcef0c69b366e01b9356e6abff0956db0896ce5e8d2fb6bf5b87cc6ed4c40b20f5935c74c46bd73bff7a53be1787249f2ebbd80661f25684a09aa

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.6.0] - Unreleased
+
+- `--help-include-hidden` prints help that also lists hidden commands and options, each marked `(hidden)`. An option is hidden when declared with `hidden: true`, which dry-cli keeps and its parser ignores; plain help leaves it out. The flag works before or after a command's name and never appears in help itself.
+- Works with the kigster fork of dry-cli as well as dry-cli 1.4: the help integration reads the CLI's streams as `stdout`/`stderr` where those exist and `out`/`err` otherwise, and `help` accepts the fork's `long:` keyword. With `long: true` a command's help prints its `long_desc` when it declares one. The spec helper passes whichever stream keywords `Dry::CLI#call` takes.
+- New setting `command_arguments`, off by default. When set, a listing prints each command with its arguments, required ones bare and optional ones in brackets: `completion SHELL`, `migrate [FILE]`. It applies to the commands of a registry level and to the subcommands on a command's own help.
+
 ## [0.5.1] - 2026-09-21
 
 - An empty example, `example [""]`, no longer raises `NoMethodError` and takes the whole help screen with it. It prints the program name on its own, which is what a command that runs with no arguments means by it.

data/README.md

@@ -132,7 +132,49 @@ OPTIONS
 Documentation: https://example.com/my-cli
 ```
 
-A command reachable as `--version` lists under Options by its dashed names. Commands marked `hidden: true` in the registry stay out of every list, and a non-dashed alias prints next to its command, as in `build, b`.
+A command reachable as `--version` lists under Options by its dashed names. Commands marked `hidden: true` in the registry stay out of every list unless `--help-include-hidden` asks for them, and a non-dashed alias prints next to its command, as in `build, b`.
+
+### Hidden commands and options
+
+dry-cli hides a command registered with `hidden: true`. This gem adds the same for options: declare one with `hidden: true` and plain help leaves it out. dry-cli's parser ignores the key, so the option still works.
+
+```ruby
+class Deploy < Dry::CLI::Command
+  desc "Deploy the application"
+  option :force, type: :boolean, aliases: ["-f"], desc: "Skip confirmation"
+  option :trace, type: :boolean, default: false, hidden: true, desc: "Print every step"
+end
+
+register "deploy", Deploy
+register "console", Console, hidden: true
+```
+
+`--help-include-hidden` prints help with every hidden command and option listed and marked. It works anywhere `-h` does, before or after the command's name, and no help screen lists it.
+
+```text
+$ my-cli --help-include-hidden
+USAGE
+  my-cli COMMAND [OPTIONS]
+
+COMMANDS
+  deploy      Deploy the application
+  console     Open a console on a server (hidden)
+
+OPTIONS
+  -h, --help  Show help
+
+$ my-cli deploy --help-include-hidden
+USAGE
+  my-cli deploy [OPTIONS]
+
+DESCRIPTION
+  Deploy the application
+
+OPTIONS
+  -f, --[no-]force  Skip confirmation
+  --[no-]trace      Print every step (hidden; default: false)
+  -h, --help        Show help
+```
 
 A block that takes an argument receives the configuration instead of running against it:
 
@@ -309,18 +351,19 @@ In a terminal the headings print bold yellow, usage lines, commands and examples
 
 The gem offers a compact DSL in the general spirit of Ruby and `dry-rb` in particular, and makes the following methods available within the `configure` block.
 
-| Setting                       | Values                           | Default         | What it does                                                                                                              |
-| ----------------------------- | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `title`                       | String                           | none            | Prints the first line of the banner, above the top-level help                                                             |
-| `description`                 | String                           | none            | Prints paragraphs under the title, reflowed to the wrap width                                                             |
-| `epilogue`                    | String                           | none            | Prints paragraphs at the very end of the top-level help                                                                   |
-| `color`                       | `true`, `false`, `:auto`         | `:auto`         | Paints headings, commands, arguments and options; `:auto` paints only a terminal                                          |
-| `wrap`                        | `true`, `false`                  | `true`          | Wraps descriptions with a hanging indent; `false` prints each one on a single line as written                             |
-| `width`                       | `:terminal`, Integer             | `:terminal`     | Sets the column text wraps at; `:terminal` follows the terminal's width                                                   |
-| `margin`                      | Integer                          | `0`             | Keeps that many columns free at the right edge when `width` is `:terminal`                                                |
-| `exit_code_without_arguments` | 0 to 255                         | `1`             | Sets the exit status of `my-cli` or `my-cli db` run with no command; `0` also prints the help to stdout instead of stderr |
-| `banner_on_subcommands`       | `true`, `false`                  | `false`         | Prints the title and description above command help and group listings too, not only above the top-level help             |
-| `command_order`               | `:registration`, `:alphabetical` | `:registration` | Lists commands in the order you registered them, or sorted by name as dry-cli does                                        |
+| Setting                       | Values                           | Default         | What it does                                                                                                                          |
+| ----------------------------- | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`                       | String                           | none            | Prints the first line of the banner, above the top-level help                                                                         |
+| `description`                 | String                           | none            | Prints paragraphs under the title, reflowed to the wrap width                                                                         |
+| `epilogue`                    | String                           | none            | Prints paragraphs at the very end of the top-level help                                                                               |
+| `color`                       | `true`, `false`, `:auto`         | `:auto`         | Paints headings, commands, arguments and options; `:auto` paints only a terminal                                                      |
+| `wrap`                        | `true`, `false`                  | `true`          | Wraps descriptions with a hanging indent; `false` prints each one on a single line as written                                         |
+| `width`                       | `:terminal`, Integer             | `:terminal`     | Sets the column text wraps at; `:terminal` follows the terminal's width                                                               |
+| `margin`                      | Integer                          | `0`             | Keeps that many columns free at the right edge when `width` is `:terminal`                                                            |
+| `exit_code_without_arguments` | 0 to 255                         | `1`             | Sets the exit status of `my-cli` or `my-cli db` run with no command; `0` also prints the help to stdout instead of stderr             |
+| `banner_on_subcommands`       | `true`, `false`                  | `false`         | Prints the title and description above command help and group listings too, not only above the top-level help                         |
+| `command_arguments`           | `true`, `false`                  | `false`         | Lists each command with its arguments, as in `deploy ENVIRONMENT` and `migrate [FILE]`: required ones bare, optional ones in brackets |
+| `command_order`               | `:registration`, `:alphabetical` | `:registration` | Lists commands in the order you registered them, or sorted by name as dry-cli does                                                    |
 
 `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.
 

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

@@ -67,6 +67,7 @@ module Dry
           margin: ->(value) { value.is_a?(Integer) && !value.negative? },
           exit_code_without_arguments: ->(value) { value.is_a?(Integer) && value.between?(0, 255) },
           banner_on_subcommands: BOOLEAN,
+          command_arguments: BOOLEAN,
           command_order: ->(value) { COMMAND_ORDERS.include?(value) }
         }.freeze
 
@@ -80,6 +81,7 @@ module Dry
           margin: 0,
           exit_code_without_arguments: 1,
           banner_on_subcommands: false,
+          command_arguments: false,
           command_order: :registration
         }.freeze
 

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

@@ -6,23 +6,58 @@ module Dry
       # The only code that touches dry-cli. Everything else renders.
       module Integration
         # Prepended to Dry::CLI. Overrides the two private methods dry-cli
-        # prints help from, and nothing else.
+        # prints help from, and the two it dispatches through, and nothing else.
         #
-        # Both are `@api private` in dry-cli, which is why the suite asserts they
-        # exist: a dry-cli release that renames them fails this gem's specs
+        # All four are `@api private` in dry-cli, which is why the suite asserts
+        # they exist: a dry-cli release that renames them fails this gem's specs
         # rather than a host's help screen.
         module CLIMethods
           HELP_FLAGS = %w[-h --help].freeze
 
+          # Asks for help that also lists hidden commands and options. No help
+          # screen lists the flag itself.
+          INCLUDE_HIDDEN_FLAG = "--help-include-hidden"
+
           private
 
-          # dry-cli calls this for `mycli deploy -h`.
-          def help(command, prog_name)
+          # dry-cli's `call` hands the arguments to one of these two. They are
+          # hooked rather than `call`, whose keywords differ between dry-cli 1.4
+          # and the kigster fork.
+          def perform_command(arguments)
+            super(without_include_hidden_flag(arguments))
+          end
+
+          def perform_registry(arguments)
+            super(without_include_hidden_flag(arguments))
+          end
+
+          # dry-cli would reject the flag as an unknown option, so it is taken
+          # out of the arguments before dry-cli sees them. A `--help` goes last
+          # in its place, unless one is there already, so the flag works before
+          # the command's name as well as after it.
+          #
+          # Everything after `--` belongs to the command, flags included.
+          def without_include_hidden_flag(arguments)
+            @help_include_hidden = false
+            options = arguments.take_while { it != "--" }
+            index = options.index(INCLUDE_HIDDEN_FLAG)
+            return arguments unless index
+
+            @help_include_hidden = true
+            rest = arguments.dup
+            rest.delete_at(index)
+            rest.insert(options.length - 1, "--help") unless options.intersect?(HELP_FLAGS)
+            rest
+          end
+
+          # dry-cli calls this for `mycli deploy -h`, and the kigster fork also
+          # for `--help`, with `long: true` so the long description is shown.
+          def help(command, prog_name, long: false)
             screen = Screens::Command.new(
-              command:, prog_name:, top_level: !kommand.nil?,
-              config: Help.config, io: out
+              command:, prog_name:, long:, top_level: !kommand.nil?,
+              config: Help.config, io: help_out, include_hidden: help_include_hidden?
             )
-            out.puts screen.render
+            help_out.puts screen.render
             exit(0)
           end
 
@@ -35,18 +70,42 @@ module Dry
 
             if unmatched.empty?
               status = config.exit_code_without_arguments
-              list(result, config, status.zero? ? out : err, status)
+              list(result, config, status.zero? ? help_out : help_err, status)
             elsif HELP_FLAGS.include?(unmatched.first)
-              list(result, config, out, 0)
+              list(result, config, help_out, 0)
             else
               suggestion = SpellChecker.call(result, arguments)
-              err.puts "#{suggestion}\n\n" if suggestion
-              list(result, config, err, 1)
+              help_err.puts "#{suggestion}\n\n" if suggestion
+              list(result, config, help_err, 1)
             end
           end
 
+          # dry-cli 1.4 holds its streams as `out` and `err`; the kigster fork
+          # renamed them `stdout` and `stderr`. Both are supported.
+          def help_out
+            plain(respond_to?(:stdout, true) ? stdout : out)
+          end
+
+          def help_err
+            plain(respond_to?(:stderr, true) ? stderr : err)
+          end
+
+          # The fork wraps each stream in a `Dry::CLI::Stream` that strips ANSI
+          # from anything written when it decides the stream has no color. The
+          # help screen has already made that decision for the same stream, so
+          # it writes to the IO underneath. The test is the class, not
+          # `respond_to?(:raw)`: `io/console` gives every IO a `raw` of its own,
+          # which puts a terminal into raw mode and raises ENOTTY on a pipe.
+          def plain(io)
+            defined?(Dry::CLI::Stream) && io.is_a?(Dry::CLI::Stream) ? io.raw : io
+          end
+
+          def help_include_hidden?
+            @help_include_hidden
+          end
+
           def list(result, config, io, status)
-            io.puts Screens::Listing.new(result:, config:, io:).render
+            io.puts Screens::Listing.new(result:, config:, io:, include_hidden: help_include_hidden?).render
             exit(status)
           end
         end

data/lib/dry/cli/help/screens/base.rb

@@ -17,8 +17,11 @@ module Dry
           # @param config [Configuration]
           # @param io [IO] where the screen prints
           # @param terminal_width [Integer]
-          def initialize(config:, io:, terminal_width: Terminal.width)
+          # @param include_hidden [Boolean] list hidden commands and options too,
+          #   as `--help-include-hidden` asks
+          def initialize(config:, io:, terminal_width: Terminal.width, include_hidden: false)
             @config = config
+            @include_hidden = include_hidden
             @format = Formatter.new(config, io, terminal_width:)
           end
 
@@ -66,15 +69,48 @@ module Dry
             format.definitions(rows, column)
           end
 
-          # The nodes of one registry level in the configured order, hidden ones left out.
+          def include_hidden?
+            @include_hidden
+          end
+
+          # The nodes of one registry level in the configured order, hidden
+          # ones left out unless asked for.
           def visible(children)
-            shown = children.to_a.reject { |_, node| node.hidden }
+            shown = children.to_a
+            shown = shown.reject { |_, node| node.hidden } unless include_hidden?
             config.command_order == :alphabetical ? shown.sort_by(&:first) : shown
           end
 
+          # A command's name as a listing prints it: followed by its arguments
+          # when `command_arguments` is set, "deploy ENVIRONMENT".
+          def command_term(name, node)
+            return name unless config.command_arguments && node.command
+
+            "#{name}#{usage_arguments(node.command)}"
+          end
+
+          # Required arguments bare, optional ones in brackets: " RULES [OUTPUT]".
+          def usage_arguments(command)
+            required = command.required_arguments.map { argument_name(it) }
+            optional = command.optional_arguments.map { "[#{argument_name(it)}]" }
+            names = [*required, *optional]
+            " #{names.join(' ')}" unless names.empty?
+          end
+
+          def argument_name(argument)
+            name = argument.name.to_s.upcase
+            argument.array? ? "#{name}..." : name
+          end
+
+          # A hidden node, listed only when asked for, says so after its description.
+          def describe_node(node)
+            text = node_description(node)
+            node.hidden ? [text, "(hidden)"].compact.join(" ") : text
+          end
+
           # A group registered without a command has no description of its own,
           # so it describes itself by what it contains.
-          def describe_node(node)
+          def node_description(node)
             return node.command.description if node.command
 
             names = visible(node.children).map(&:first)

data/lib/dry/cli/help/screens/command.rb

@@ -12,11 +12,13 @@ module Dry
           # @param prog_name [String] the program and command path, "mycli db migrate"
           # @param top_level [Boolean] true when the command is the whole CLI,
           #   as with `Dry::CLI.new(SomeCommand)`
-          def initialize(command:, prog_name:, top_level: false, **)
+          # @param long [Boolean] show the command's `long_desc` when it has one
+          def initialize(command:, prog_name:, top_level: false, long: false, **)
             super(**)
             @command = command
             @prog_name = prog_name
             @top_level = top_level
+            @long = long
           end
 
           private
@@ -32,13 +34,20 @@ module Dry
           end
 
           def render_usage
-            lines = ["#{prog_name}#{usage_arguments} [OPTIONS]"]
+            lines = ["#{prog_name}#{usage_arguments(command)} [OPTIONS]"]
             lines << "#{prog_name} COMMAND [OPTIONS]" if subcommand_rows.any?
             section(:usage, lines.map { INDENT + format.paint(it, :usage) })
           end
 
           def render_description
-            section(:description, format.paragraph(command.description, indent: INDENT))
+            section(:description, format.paragraph(description, indent: INDENT))
+          end
+
+          # The long description for `--help` where the command declares one
+          # (`long_desc`, kigster/dry-cli), otherwise the one-line `desc`.
+          def description
+            long = command.long_description if @long && command.respond_to?(:long_description)
+            long || command.description
           end
 
           def render_subcommands
@@ -60,8 +69,7 @@ module Dry
           # all", and String#split answers [] for it, so `line` is nil and only
           # the program name is left to print.
           def render_examples
-            rows = command.examples.map do |example|
-              line, comment = example.split(" # ", 2)
+            rows = example_pairs.map do |line, comment|
               term = [prog_name, line&.strip].reject { it.nil? || it.empty? }.join(" ")
               Row.new(term: term, text: comment&.strip,
                       term_style: :example, text_style: :example_comment)
@@ -69,20 +77,31 @@ module Dry
             section(:examples, format.definitions(rows, format.column_for(rows)))
           end
 
-          def aligned_rows
-            subcommand_rows + argument_rows + option_rows
+          # Every example as `[args, comment]`. dry-cli 1.4 keeps one string per
+          # example, "args # comment". The kigster fork keeps `[args, description]`
+          # pairs, and a list handed to it in the 1.4 spelling arrives as one pair
+          # holding the list and an empty description.
+          def example_pairs
+            command.examples.flat_map { pairs_of(it) }
           end
 
-          def usage_arguments
-            required = command.required_arguments.map { argument_name(it) }
-            optional = command.optional_arguments.map { "[#{argument_name(it)}]" }
-            names = [*required, *optional]
-            " #{names.join(' ')}" unless names.empty?
+          def pairs_of(example)
+            return [example.split(" # ", 2)] unless example.is_a?(Array)
+
+            text, description = example
+            return text.flat_map { pairs_of(it) } if text.is_a?(Array)
+            return pairs_of(text) if description.nil? || description.empty?
+
+            [[text, description]]
+          end
+
+          def aligned_rows
+            subcommand_rows + argument_rows + option_rows
           end
 
           def subcommand_rows
             @subcommand_rows ||= visible(command.subcommands).map do |name, node|
-              Row.new(term: name, text: describe_node(node))
+              Row.new(term: command_term(name, node), text: describe_node(node))
             end
           end
 
@@ -92,15 +111,14 @@ module Dry
             end
           end
 
+          # An option declared `hidden: true` lists only when hidden ones are asked for.
           def option_rows
-            @option_rows ||= command.options.map do |option|
-              Row.new(term: option_term(option), text: describe(option), term_style: :option)
-            end
-          end
+            @option_rows ||= command.options.filter_map do |option|
+              hidden = option.options.fetch(:hidden, false)
+              next if hidden && !include_hidden?
 
-          def argument_name(argument)
-            name = argument.name.to_s.upcase
-            argument.array? ? "#{name}..." : name
+              Row.new(term: option_term(option), text: describe(option, hidden:), term_style: :option)
+            end
           end
 
           # Short aliases, then the option, then long aliases: "-f, --[no-]force".
@@ -117,8 +135,9 @@ module Dry
           end
 
           # The description, then what a reader needs to use the value.
-          def describe(param)
+          def describe(param, hidden: false)
             notes = []
+            notes << "hidden" if hidden
             notes << "required" if param.required?
             notes << "one of: #{param.values.join(', ')}" if param.values
             notes << "default: #{param.default.inspect}" unless param.default.nil?

data/lib/dry/cli/help/screens/listing.rb

@@ -66,7 +66,7 @@ module Dry
             @command_rows ||= entries.each_with_object({}) do |(name, node, aliases), rows|
               next if name.start_with?("-")
 
-              term = [name, *aliases.reject { it.start_with?("-") }].join(", ")
+              term = [command_term(name, node), *aliases.reject { it.start_with?("-") }].join(", ")
               rows[[*result.names, name].join(" ")] = Row.new(term:, text: describe_node(node))
             end
           end

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

@@ -9,7 +9,7 @@ module Dry
   # inherits from Object, so an empty reopening is compatible either way.
   class CLI
     module Help
-      VERSION = "0.5.1"
+      VERSION = "0.6.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-help
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -86,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.22
 specification_version: 4
 summary: Configurable, wrapped, colored help screens for dry-cli applications
 test_files: []