dry-cli-autocomplete 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e13789705a3120d92019f20ba4bb4c7619a2b76c3d5fe99639dd9ba29c96696
-  data.tar.gz: dba1d9805eb867d76c1c547f688dbadea1ece6714fc73cef2bcd1c93c30a62c3
+  metadata.gz: b392efc439cb2a04ce5858ab9f8931cf3be6c987df699c4ef56e0c20782775d9
+  data.tar.gz: 749295c776797acfd2a82a059d632df3d1f02170e158c4b3e8ad260def61009a
 SHA512:
-  metadata.gz: 207eb7f84aea51e36d8a5ed3e08a45a5b2f278d1c3cf5d42e408d2caa353ce35b91514889390aba9298c851882e1d3eb25b3582084c32e68ef1f969f3b4443c8
-  data.tar.gz: bbeed56314a20aec94d8fabd92e43532c316d470348a546ae952a70ace686e84209fb22d99bf1fb3a7b6a529b1e2785d2fe0b57b80ec05cb1fa16074eea3bc7a
+  metadata.gz: b33692dd9535f11c1057a75c5c689dc05d6dff0850094478b7f7cf4867436272855786d6b2c7a1f406ecf029da678be33ff13738d7cbecca69fe1536fde292ef
+  data.tar.gz: 5dacc2b7a57ddc9ca177ec1f0c29a1f9d6514e08f0eeec9ce1863a3c88217583ce6f9013f02d0293671fecdf7657e19d9c8d3a57224e34d71bd9aa7be7ac6f1a

data/.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/bower_components": true,
+    "**/*.code-search": true,
+    "**/.ruby-lsp": true,
+    "**/.rubymate": true
+  },
+  "files.watcherExclude": {
+    ".git/objects/**": true,
+    ".git/subtree-cache/**": true,
+    ".hg/store/**": true,
+    "*/.git/objects/**": true,
+    "*/.git/subtree-cache/**": true,
+    "*/.hg/store/**": true,
+    "**/.trunk/*actions/": true,
+    "**/.trunk/*logs/": true,
+    "**/.trunk/*notifications/": true,
+    "**/.trunk/*out/": true,
+    "**/.trunk/*plugins/": true,
+    "**/.rubymate": true
+  }
+}

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+- Options complete the way dry-cli parses them. `option :as_of` completed as `--as_of`, which dry-cli accepts but its own help never shows; it is now `--as-of`. A boolean also completes its `--no-` form, and an alias declared without dashes (`aliases: ["f"]`) gains them (`-f`). A name with capitals is downcased as dry-cli registers it: `option :dryRun` completes as `--dryrun`.
+- In zsh, a `type: :flag` option no longer takes a value. `run --quiet x` completed `x` as `--quiet`'s argument, while dry-cli parses it as `quiet: true` and an argument `x`.
+- In zsh, a boolean's two forms exclude each other, so once `--force` is on the line zsh stops offering `--no-force`. The `--no-` form is described as `Turn off --force` rather than repeating the description, which read backwards.
+- `Command[MyCLI]` keeps its description and examples. dry-cli empties both on every subclass, so `mycli completion --help` printed usage alone. The examples now name the bound `program_name:`.
+- `completion` now writes to the stream a host passes to `Dry::CLI#call(out:)`. It used to write to `$stdout` regardless, so a launcher's own STDOUT, and an in-process Aruba run, received nothing. Called directly, outside `Dry::CLI`, it still falls back to `$stdout`.
+
 ## [0.5.0] - 2026-09-16
 
 Documentation only; no change to the gem's behaviour.

data/README.md

@@ -12,6 +12,60 @@ ______________________________________________________________________
 > [!WARNING]
 > This gem was written with a collaboration with Claude Code. Most of the ruby was written by a human (myself), reviewed and pushed to GitHub by Claude (anyone loves writing commit descriptions?). The part where Claude authored the most code is the ZSH autocompletion code as I'm less familiar with it than BASH. If you prefer not to use gems that had some AI contributions that were reviewed by a human, do not use this gem.
 
+## Usage
+
+For the impatient:
+
+```bash
+gem install dry-cli dry-cli-autocomplete -N
+```
+
+Register one command:
+
+```ruby
+require "dry/cli"
+require "dry/cli/autocomplete/command"
+
+module MyCLI
+  extend Dry::CLI::Registry
+
+  register "deploy", Deploy
+  register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+end
+```
+
+Then load the script from your shell's initialization file:
+
+```bash
+eval "$(mycli completion bash)"   # ~/.bashrc
+eval "$(mycli completion zsh)"    # ~/.zshrc, after compinit
+```
+
+### Real Example
+
+[`examples/`](examples/README.md) holds a working CLI with the command registered, to try it end to end.
+
+```bash
+$ cd examples && bundle exec bin/mycli -h
+mycli
+
+Downloads URLs and finds hosts on the local network, several at once.
+
+USAGE
+  mycli COMMAND [OPTIONS]
+
+COMMANDS
+  version, v               Print version
+  download-urls, download  Download URLs, each to its own file
+  find-hosts, hosts        Find hosts on the local network that listen on
+                           common TCP ports
+  completion               Print a shell completion script
+
+OPTIONS
+  -h, --help               Show help
+  -v, --version            Print version
+```
+
 Your CLI knows its own commands, options, aliases and enum values. The shell does not. This gem walks your registry once, prints a bash or zsh script, and you source it from your profile. Pressing TAB then spawns nothing and costs nothing, because every completion the script will ever offer is already inside it.
 
 ```bash
@@ -90,8 +144,8 @@ _mycli_completions() {
   case "$path" in
     "") words="version deploy db" ;;
     "version") words="--format" ;;
-    "deploy") words="--force -f staging production" ;;
-    "db") words="migrate --verbose" ;;
+    "deploy") words="--force --no-force -f staging production" ;;
+    "db") words="migrate --verbose --no-verbose" ;;
     "db migrate") words="--step" ;;
   esac
 
@@ -109,6 +163,7 @@ Read what that output proves:
 - `db migrate` gets real file completion.
 - `secret` is absent, because hidden commands stay hidden.
 - The `-f` alias on `deploy` is there because you declared it.
+- `--no-force` is there because `--force` is a boolean, and dry-cli accepts both forms. Options are spelled the way dry-cli parses them, so `option :dry_run` completes as `--dry-run`, and an alias declared as `"f"` completes as `-f`.
 - `mycli version --format <TAB>` offers `json plain`, and nothing else.
 - `mycli deploy <TAB>` offers `staging production`, the values declared on the positional.
 
@@ -120,12 +175,14 @@ The script uses no associative arrays, so it runs under the bash 3.2 that macOS
     ('deploy')
       _arguments -s \
         '--force[Skip confirmation]' \
+        '--no-force[Skip confirmation]' \
         '-f[Skip confirmation]' \
         '*:Target environment:(staging production)' && ret=0
       ;;
     ('db')
       _arguments -s \
-        '--verbose[Print full migration history]' && ret=0
+        '--verbose[Print full migration history]' \
+        '--no-verbose[Print full migration history]' && ret=0
       commands=(
         'migrate:Run pending migrations'
       )

data/lib/dry/cli/autocomplete/command.rb

@@ -22,10 +22,17 @@ module Dry
         # gem may be required long before anyone knows how it was invoked.
         #
         #   register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+        #
+        # dry-cli's inherited hook empties a subclass's description and
+        # examples, and this returns a subclass, so both are set again here.
+        # The examples name the bound program, not whatever loaded the gem.
         def self.[](registry, program_name: nil)
           Class.new(self) do
             @registry = registry
             @program_name = program_name
+
+            desc superclass.description
+            example examples_for(program_name || File.basename($PROGRAM_NAME))
           end
         end
 
@@ -33,24 +40,33 @@ module Dry
           attr_reader :registry, :program_name
         end
 
+        def self.examples_for(name)
+          [
+            "bash > /usr/local/etc/bash_completion.d/#{name}",
+            "zsh  > \"${fpath[1]}/_#{name}\""
+          ]
+        end
+
         desc "Print a shell completion script"
 
-        argument :shell, required: true, values: SHELLS,
-                         desc: "Shell to generate completions for"
+        argument :shell, required: true, values: SHELLS, desc: "Shell to generate completions for"
 
-        example [
-          "bash > /usr/local/etc/bash_completion.d/#{File.basename($PROGRAM_NAME)}",
-          "zsh  > \"${fpath[1]}/_#{File.basename($PROGRAM_NAME)}\""
-        ]
+        example examples_for(File.basename($PROGRAM_NAME))
 
         def call(shell:, **)
           require_relative "spec_builder"
           require_relative "emitters/#{shell}"
 
-          spec = SpecBuilder.call(registry, program_name: program_name)
+          spec = SpecBuilder.call(registry, program_name:)
+
           out.puts emitter_for(shell).call(spec)
         end
 
+        # Dry::CLI sets @out from Dry::CLI#call(out:) before it calls a command,
+        # and only when the command has not set @out itself, so never assign it
+        # here. $stdout is for a command called directly, outside Dry::CLI.
+        def out = @out || $stdout
+
         private
 
         def registry
@@ -65,9 +81,6 @@ module Dry
         def emitter_for(shell)
           Emitters.const_get(shell.capitalize)
         end
-
-        # Overridable so specs can capture output without reaching for $stdout.
-        def out = $stdout
       end
     end
   end

data/lib/dry/cli/autocomplete/emitters/bash.rb

@@ -127,12 +127,10 @@ module Dry
           # legitimate next words at this point in the line.
           def node_words(node)
             node.children +
-              node.options.flat_map { |option| option_words(option) } +
+              node.options.flat_map(&:flags) +
               node.arguments.flat_map { |argument| Array(argument.values) }
           end
 
-          def option_words(option) = ["--#{option.name}"] + Array(option.aliases)
-
           # An option that declares values gets its own arm, keyed on the word
           # before the cursor. Typing `--format ` then TAB should offer what
           # --format accepts, not the command list again, so this arm answers
@@ -145,7 +143,7 @@ module Dry
                 next if values.empty?
 
                 key = path_key(node.path)
-                option_words(option).map do |name|
+                option.flags.map do |name|
                   "    \"#{quote(key)}:#{quote(name)}\") " \
                     "COMPREPLY=($(compgen -W \"#{quote(values.join(' '))}\" -- \"$cur\")); return ;;"
                 end

data/lib/dry/cli/autocomplete/emitters/zsh.rb

@@ -132,15 +132,34 @@ module Dry
           # Each alias gets its own spec rather than a {-f,--force} group:
           # the grouped form needs its description outside the quotes, and
           # one entry per flag is easier to read in the generated file.
+          #
+          # A boolean's two forms exclude each other, so once `--force` is on
+          # the line zsh stops offering `--no-force`, and the reverse. The
+          # `--no-` form says what it turns off rather than repeating the
+          # description, which would read backwards.
           def option_specs(option)
-            names = ["--#{option.name}"] + Array(option.aliases)
-            names.map { |name| single_quote("#{name}#{bracketed(option.desc)}#{option_action(option)}") }
+            positives = [option.long, *option.alias_flags]
+            specs = positives.map do |name|
+              single_quote("#{exclusion([option.negation])}#{name}#{bracketed(option.desc)}#{option_action(option)}")
+            end
+            return specs unless option.negation
+
+            specs.insert(1, single_quote("#{exclusion(positives)}#{option.negation}[Turn off #{option.long}]"))
+          end
+
+          # A zsh exclusion list such as `(--no-force)`, or nothing when there
+          # is nothing to exclude.
+          def exclusion(names)
+            names = names.compact
+            names.empty? ? "" : "(#{names.join(' ')})"
           end
 
-          # A boolean flag takes no value. Anything else gets one field
-          # naming what it wants and one supplying the completions for it.
+          # A boolean or a `type: :flag` option takes no value: dry-cli parses
+          # `run --quiet x` as `quiet: true` with `x` as an argument. Anything
+          # else gets one field naming what it wants and one supplying the
+          # completions for it.
           def option_action(option)
-            return "" if option.boolean
+            return "" if option.boolean || option.flag
 
             ":#{escape_spec(option.name)}:#{value_action(option.values)}"
           end

data/lib/dry/cli/autocomplete/spec_builder.rb

@@ -25,9 +25,19 @@ module Dry
         # method Struct defines and Data does not.
         CompletionSpec = ::Data.define(:program_name, :nodes)
         Node = ::Data.define(:path, :desc, :options, :arguments, :children)
+        # `long`, `negation` and `alias_flags` are spelled the way dry-cli
+        # 1.4.1 spells them in Option#parser_options and #alias_names, so
+        # both emitters offer exactly what the parser accepts. `flag` is a
+        # `type: :flag` option: like a boolean it takes no value, but dry-cli
+        # gives it no `--no-` form.
         OptionSpec = ::Data.define(
-          :name, :type, :values, :aliases, :default, :desc, :required, :boolean, :array
-        )
+          :name, :type, :values, :aliases, :default, :desc, :required, :boolean, :array,
+          :flag, :long, :negation, :alias_flags
+        ) do
+          # @return [Array<String>] every spelling: the long name, its `--no-`
+          #   form for a boolean, then the aliases
+          def flags = [long, negation, *alias_flags].compact
+        end
         ArgumentSpec = ::Data.define(:name, :values, :desc, :required, :file)
 
         # A bare heuristic, used only when a host does not declare `file:`
@@ -77,13 +87,29 @@ module Dry
         end
 
         def build_option(option)
+          long = "--#{dasherize(option.name)}"
           OptionSpec.new(
             name: option.name.to_s, type: option.type, values: option.values,
             aliases: option.aliases, default: option.default, desc: option.options[:desc],
-            required: option.required? || false, boolean: option.boolean?, array: option.array?
+            required: option.required? || false, boolean: option.boolean?, array: option.array?,
+            flag: option.respond_to?(:flag?) && option.flag?, long: long,
+            negation: option.boolean? ? long.sub("--", "--no-") : nil,
+            alias_flags: Array(option.aliases).map { |name| alias_flag(name) }.uniq
           )
         end
 
+        # What Dry::CLI::Inflector.dasherize does, without depending on a
+        # module dry-cli marks private: `dry_run` becomes `--dry-run` and `dryRun`
+        # becomes `--dryrun`, as dry-cli registers them.
+        def dasherize(name) = name.to_s.downcase.gsub(/[[:space:]_]/, "-")
+
+        # One letter gets one dash and anything longer two, whatever the host
+        # wrote: `"f"`, `"-f"` and `"--f"` all register as `-f`.
+        def alias_flag(name)
+          bare = name.to_s.sub(/\A-{1,2}/, "")
+          bare.size == 1 ? "-#{bare}" : "--#{bare}"
+        end
+
         def build_argument(argument)
           ArgumentSpec.new(
             name: argument.name.to_s, values: argument.values, desc: argument.options[:desc],

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-autocomplete
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -46,6 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".secrets.baseline"
+- ".vscode/settings.json"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
@@ -86,7 +87,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: A missing auto-complete addition for dry-cli powered Ruby CLI tools for BASH
   & ZSH