dry-cli-autocomplete 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38de4ac84fa86c4333894c4e0adc744df06379bebd399fa64353e358c5f1c522
+  data.tar.gz: adc97f1a4a65f9f606fd121e4b3aa47e91aae1c0c5e6e26c16e8894b7ebf753b
+SHA512:
+  metadata.gz: 88a9c575b4fef1827c3be3322fb5603b07a0634395ca967b0329fafd7d53349856d226f9eb5479a3bedb4b31a021d95167d87e560e4e0a14e2cdb31ef82943fe
+  data.tar.gz: b93e2fccd489c023889a5e4fe791864140c87fd1bf44e1032685fa9ad218c73425538c0202850aaabe2fff1322e506a9e1c025cc20ede67543ecb1f50beba62e

data/.rubocop.local.yml

@@ -0,0 +1,16 @@
+# Local overrides on top of the synced hanakai-rb config.
+
+# The emitters are largely lists of literal shell lines. Splitting them up
+# to satisfy a line count would make them harder to read, not easier, and
+# the zsh one is the largest piece of the gem by design (spec.md §8).
+Metrics/MethodLength:
+  Exclude:
+    - "lib/dry/cli/autocomplete/emitters/*.rb"
+
+Metrics/ClassLength:
+  Exclude:
+    - "lib/dry/cli/autocomplete/emitters/*.rb"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-22
+
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+Guidance for Claude Code (claude.ai/code) working in this repository.
+
+## What this is
+
+A Ruby gem that generates static shell completion scripts for any `Dry::CLI` application. A host registers one command; `mycli completion bash` prints a script; the user evaluates it from a shell profile.
+
+**Read `SPECIFICATION.md` first.** It carries the design decisions, the measurements behind them, and the acceptance criteria. This file covers how to work in the repository; that one covers what to build and why.
+
+The gem is a skeleton from `bundle gem` with no implementation yet. Nothing in `lib/` does anything.
+
+## Environment
+
+Ruby is managed by rbenv. Prefix every Ruby command:
+
+```bash
+eval "$(rbenv init -)" && bundle exec rspec
+```
+
+```bash
+bundle install
+bundle exec rspec              # the suite
+bundle exec rubocop            # the linter
+bundle exec rubocop -a         # autocorrect
+bundle exec rake               # both, and the default task
+bin/console                    # IRB with the gem loaded
+```
+
+The gemspec sets `required_ruby_version >= 3.2.0` and `.rubocop.yml` sets `TargetRubyVersion: 3.2`. Keep the two in step: raising one without the other produces a linter that permits syntax the gemspec claims to support, or the reverse.
+
+## The trap that has already bitten this repository once
+
+`bundle gem dry-cli-autocomplete` generates `module Dry; module Cli`. **dry-cli declares `Dry::CLI`, and it is a class, not a module.** Reopening a class as a module raises `TypeError` the moment both are loaded, and the error names neither file usefully.
+
+Six files were generated wrong and have been fixed. If you add a file under `lib/dry/cli/`, nest it as:
+
+```ruby
+module Dry
+  class CLI          # class, and CLI is an acronym
+    module Autocomplete
+```
+
+`lib/dry/cli/autocomplete/version.rb` deliberately does **not** `require "dry/cli"`, because the gemspec loads it at build time when the dependency may not be installed. It reopens `class CLI` on its own. dry-cli's `CLI` inherits from `Object`, so an empty reopening is compatible whichever loads first.
+
+For deriving names at runtime, use `dry-inflector`. `Dry::Inflector.new { |i| i.acronym("CLI") }` handles both the casing above and the `underscore` needed for shell function identifiers. `Dry::CLI::Inflector` ships with dry-cli but only has `dasherize` and is marked `@api private`; do not depend on it.
+
+## Architecture
+
+Four pieces, and the boundary between the first and the rest is load-bearing.
+
+| File                                        | Role                                                                                                                                  |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `lib/dry/cli/autocomplete/command.rb`       | The shim a host registers. Defines the command class and nothing else. `require`s the generator **inside `#call`**, never at the top. |
+| `lib/dry/cli/autocomplete/spec_builder.rb`  | Walks a registry through public API and returns a shell-agnostic description of every completion.                                     |
+| `lib/dry/cli/autocomplete/emitters/bash.rb` | Turns that description into a `complete -F` script.                                                                                   |
+| `lib/dry/cli/autocomplete/emitters/zsh.rb`  | Turns it into a native `#compdef` script with per-option descriptions.                                                                |
+
+Two rules hold this shape together, both measured rather than assumed:
+
+- **The command shim loads no emitter.** A host pays nothing at boot for a command run once per shell. `SPECIFICATION.md` §2.4.
+- **The spec builder touches only the registry.** It must be safe to run at shell startup, because it runs at every shell startup. `SPECIFICATION.md` §2.2.
+
+The emitters take the same description and share no code. A fourth shell should be a new emitter class, never a branch inside an existing one.
+
+## Conventions
+
+- **The generator is not a hot path.** It runs in 0.067ms against a 27-command registry. Do not optimise it, do not add native extensions, and do not cache anything. The reasoning is in `SPECIFICATION.md` §2.3.
+- **Read a registry through its methods, not its ivars.** `registry.get(path)` returns a result exposing `command`, `children` and `names`. `instance_variable_get(:@node)` is what the gem this one replaces does, and it will break on a dry-cli release. Do not mistake this for a public API: in 1.4.1 `Registry#get`, all of `CommandRegistry`, every `LookupResult` reader and every `Node` reader carry `@api private`. There is no public way to enumerate a registry, so an upgrade can break the walk and the fixture suite is what catches it.
+- **Test against registries this project did not write.** A generator tested against one CLI encodes that CLI's shape. `SPECIFICATION.md` §5.
+- **Validate generated shell with the shell.** `bash -n` and `zsh -n` parse without executing. A regex over generated output proves nothing about whether it runs.
+- **Commit messages**: imperative mood, 50-character subject, no full stop. A body only where the change needs explaining, saying what and why.
+- **Writing prose here**: no em dashes, active voice, plain words. Say what a thing does, not how it feels. If a sentence could appear unchanged in another project's README, it says nothing about this one and should go.
+
+## Repository layout
+
+| Path                                  | What it is                                                                                                        |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `SPECIFICATION.md`                    | What to build, why, and what "done" means                                                                         |
+| `lib/dry/cli/autocomplete.rb`         | Entry point                                                                                                       |
+| `lib/dry/cli/autocomplete/version.rb` | Version, loaded standalone by the gemspec                                                                         |
+| `sig/`                                | RBS signatures, generated by `bundle gem` and not yet real                                                        |
+| `exe/dry-cli-autocomplete`            | Generated by `bundle gem`. **Probably should be deleted**: this is a library, and a host provides the executable. |
+| `.github/workflows/main.yml`          | CI                                                                                                                |
+
+## Before the first release
+
+The gemspec still carries `bundle gem` TODOs that will refuse to build: `spec.summary`, `spec.description`, and `spec.metadata["allowed_push_host"]`. The `dry-` prefix and the `Dry::CLI::Autocomplete` namespace imply an affiliation with dry-rb that does not exist, so say so in the README, or ask them first.

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,175 @@
+# dry-cli-autocomplete
+
+[![Ruby](https://github.com/kigster/dry-cli-autocomplete/actions/workflows/main.yml/badge.svg)](https://github.com/kigster/dry-cli-autocomplete/actions/workflows/main.yml)
+![Coverage](docs/img/badge.svg)
+
+Shell completion for [dry-cli](https://github.com/dry-rb/dry-cli) applications, with no Ruby in the TAB path.
+
+> [!NOTE]
+> 
+> For the specification of this gem see [SPECIFICATION](SPECIFICATION.md)
+
+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
+mycli completion bash > /usr/local/etc/bash_completion.d/mycli
+```
+
+> **Status:** not yet released to RubyGems. The registry walk, both emitters and the command shim are written and tested, against three fixture registries, with every generated script checked by `bash -n` or `zsh -n`. Install it from git until there is a released version.
+
+## The problem
+
+A dry-cli app with nested subcommands gives the shell nothing to work with. `mycli db <TAB>` completes filenames from the current directory, which is never what you wanted.
+
+[`rngtng/dry-cli-completion`](https://github.com/rngtng/dry-cli-completion) already solves part of this, and it is worth reading before you reach for this gem. It falls short in four ways, and each one is an acceptance criterion here.
+
+**A group that has both a command and children loses the children.** Register an overview command at a group's bare name so `mycli db --help` can explain the group, and its subcommands stop completing:
+
+```ruby
+register "db", DbStatus         # the node now has a command
+register "db migrate", Migrate  # ...and children, which never get walked
+```
+
+`mycli db <TAB>` then offers `--help` and nothing else. This is what any app does when it wants group-level help.
+
+**File arguments vanish.** `Input#input_line` returns early on `<file>`, so a command with a path argument produces no `compgen -f`, no `-o default`, no `_filedir`. Completing a path is the single most common thing a user wants from a CLI, and it is the one thing that does not work.
+
+**The entry point is not free.** `command.rb` opens with a require that pulls the generator, which pulls `completely`. Every host pays for that at boot. Measured: `require "dry/cli"` costs 160ms, and adding the completion gem takes it to 190ms. Thirty milliseconds on every single invocation, for a command that runs once per shell.
+
+**zsh is a bashcompinit shim.** It emits `autoload -Uz +X bashcompinit && bashcompinit` followed by bash. That works, but zsh users get no per-option descriptions and none of the behaviour they expect from a native completion.
+
+There is a dependency argument too. `completely` pulls `colsole`, `docopt_ng` and `mister_bin`, and `mister_bin` is itself a CLI framework. That is four gems, one of them a second CLI framework, to print a shell script. This gem depends on `dry-cli` and `dry-inflector`, and nothing else.
+
+## What it generates
+
+Given this registry:
+
+```ruby
+register "version", Version
+register "deploy", Deploy
+register "db", DbStatus do |prefix|
+  prefix.register "migrate", DbMigrate
+end
+register "secret", Secret, hidden: true
+```
+
+`mycli completion bash` prints a `complete -F` function that dispatches on the command path:
+
+```bash
+_mycli_completions() {
+  # ...walks COMP_WORDS to find the current command path...
+  words=""
+  case "$path" in
+    "") words="version deploy db" ;;
+    "version") words="--format" ;;
+    "deploy") words="--force -f" ;;
+    "db") words="migrate --verbose" ;;
+  esac
+
+  COMPREPLY=($(compgen -W "$words" -- "$cur"))
+  case "$path" in
+    "db migrate") COMPREPLY+=($(compgen -f -- "$cur")) ;;
+  esac
+}
+complete -F _mycli_completions mycli
+```
+
+Read what that output proves. `db` offers `migrate` alongside its own `--verbose`, so a group with both a command and children keeps both. `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.
+
+`mycli completion zsh` prints a native `#compdef` script built on `_arguments` and `_describe`, carrying each option's `desc` as help text next to it.
+
+Enum values declared on an option or argument come through at no cost:
+
+```ruby
+option :format, values: %w[json yaml table]    # completes json yaml table
+argument :component, values: %w[major minor]   # completes major minor
+```
+
+## Installation
+
+Not yet on RubyGems. Until it is, point at the repository:
+
+```ruby
+gem "dry-cli-autocomplete", github: "kigster/dry-cli-autocomplete"
+```
+
+Register the command in your CLI:
+
+```ruby
+require "dry/cli/autocomplete/command"
+
+module MyCLI
+  extend Dry::CLI::Registry
+
+  register "version", Version
+  register "deploy", Deploy
+  register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+end
+```
+
+That require pulls in the command class and nothing else. No emitter loads until someone actually runs `mycli completion`.
+
+Then have your users write the script once and source it. For bash:
+
+```bash
+mycli completion bash > /usr/local/etc/bash_completion.d/mycli
+```
+
+For zsh, put it anywhere on your `$fpath`:
+
+```bash
+mycli completion zsh > "${fpath[1]}/_mycli"
+```
+
+Regenerate it when you add or rename commands. Nothing watches for changes, by design.
+
+## Why the script is static
+
+Cobra and clap route every TAB press to a hidden `__complete` subcommand. That is the right call for a Go or Rust binary that starts in 10ms. It is the wrong call here.
+
+| Measurement                                               |           Time |
+| --------------------------------------------------------- | -------------: |
+| Bare `ruby -e ''`                                         |          100ms |
+| `require "dry/cli"`                                       |          160ms |
+| `require "dry/cli"` + `dry-cli-completion` + `completely` |          190ms |
+| `require "tax_engine"` (a heavy host)                     |          520ms |
+| First touch of that host's data store                     |         +239ms |
+| **Registry walk and full completion spec build**          |    **0.067ms** |
+| Generated bash script for 27 commands                     | 257 lines, 9KB |
+
+Half a second of dead air per keystroke is unusable, and no amount of lazy loading gets under the host's own require cost. So there is no `__complete` command. It was considered, costed at roughly 90 lines, and rejected on that table.
+
+The same table explains two other decisions. The generator will not be optimised, because at 0.067ms it is 0.01% of the cheapest possible invocation and all the time goes to interpreter startup. Native extensions were rejected for the same reason, plus they would put a compiled artifact in every consumer's dependency chain.
+
+## What it will not do
+
+**Values your host has to compute.** The walk touches only objects dry-cli already holds. The moment an option's `values:` calls into your data layer, that cost lands at class-definition time on *every* invocation, not just completion. In the profiled host that meant 239ms of YAML parsing added to shell startup. Declare the values on the option, where dry-cli validates against them anyway and the generator sees them free.
+
+**fish, PowerShell, nushell.** Worth adding later. The emitter interface is built so a fourth shell is a new class rather than a new branch in an existing one.
+
+**Watch your registry.** Regenerating is your call, in your release process.
+
+## Development
+
+Ruby 3.2 or newer. This repository uses rbenv, so activate it first:
+
+```bash
+eval "$(rbenv init -)"
+bundle install
+bundle exec rspec       # the suite
+bundle exec rubocop     # the linter
+bundle exec rake        # both
+bin/console             # IRB with the gem loaded
+```
+
+Two conventions in the suite are worth knowing before you add to it. Fixtures include registries this project did not write, because a generator tested against one CLI quietly encodes that CLI's shape. And generated scripts are validated by the shells themselves, with `bash -n` and `zsh -n` parsing without executing, since a regex over the output proves nothing about whether it runs.
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/kigster/dry-cli-autocomplete>.
+
+A note on the name. The `dry-` prefix and the `Dry::CLI::Autocomplete` 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,39 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "timeout"
+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 exe/*.rb - README.md LICENSE.txt CHANGELOG.md]
+  t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
+  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,246 @@
+# `dry-cli-autocomplete`: Specification
+
+Generate static shell completion scripts for any `Dry::CLI` application, from the command registry alone.
+
+The intended use is one line in a shell profile:
+
+```bash
+eval "$(mycli completion bash)"    # ~/.bashrc
+eval "$(mycli completion zsh)"     # ~/.zshrc
+```
+
+The script is regenerated when the shell starts, so a new command in the host application completes as soon as it ships. Pressing TAB runs nothing: the shell matches against a word list the script already carries.
+
+## Research
+
+Research discovered a completion gems [https://github.com/rngtng/dry-cli-completion](https://github.com/rngtng/dry-cli-completion) howerver it lacks in a several areas (see below).
+
+## Motivation 
+
+## 1. Why this exists when `dry-cli-completion` already does
+
+`rngtng/dry-cli-completion` (MIT, v2.0.0) works and is the obvious starting point. Read it before writing anything. It falls short in four specific ways, each of which is an acceptance criterion below.
+
+**1.1 A node carrying both a command and children loses its children.** `Input#extract_commands` branches `if sub_node.command ... elsif sub_node.children`. An application that registers an overview command at a group's bare name, so that `mycli db --help` can explain what the group is for, gets:
+
+```ruby
+register "db", DbOverview      # node now has a command
+register "db migrate", Migrate # ...and children, which are never walked
+```
+
+Completion for `mycli db <TAB>` offers `--help` and nothing else. The subcommands are invisible. This is not exotic: it is what any application does when it wants group-level help.
+
+**1.2 File arguments are dropped silently.** `Input#input_line` opens with `return if name.include?("<file>")`. A command whose argument name matches `/path/` produces no entry at all, and the generated script contains no `compgen -f`, no `-o default`, no `_filedir`. So `mycli deploy <TAB>` on a path argument completes nothing, which is the single most common thing a user wants.
+
+**1.3 There is no light entry point.** `command.rb` opens with `require "dry/cli/completion"`, which loads the generator, which loads `completely`. A host that only wants to register the command pays for the whole tree at boot. Measured: `require "dry/cli"` is 160ms, adding the completion gem makes it 190ms. Thirty milliseconds on every invocation of a command run once per shell.
+
+**1.4 zsh is a bashcompinit shim.** It emits `autoload -Uz +X bashcompinit && bashcompinit` and then bash. It works, but zsh users get no per-option descriptions and none of the native behaviour they expect.
+
+There is also a dependency argument. `completely` pulls `colsole`, `docopt_ng` and `mister_bin`, and `mister_bin` is itself a CLI framework. Four gems, one of them a second CLI framework, to emit a shell script. This gem generates the script itself and depends on `dry-cli` and `dry-inflector` only.
+
+## 2. Design decisions, and the measurements behind them
+
+These were settled by profiling a real dry-cli application (`tax_engine`, 27 commands, 33 options, 7 arguments). Reproduce them before overturning any of this.
+
+| Measurement                                               |           Time |
+| --------------------------------------------------------- | -------------: |
+| Bare `ruby -e ''`                                         |          100ms |
+| `require "dry/cli"`                                       |          160ms |
+| `require "dry/cli"` + `dry-cli-completion` + `completely` |          190ms |
+| `require "tax_engine"` (a gem with 2.5M lines of data)    |          520ms |
+| First touch of that host's data store                     |         +239ms |
+| **Registry walk and full completion spec build**          |    **0.067ms** |
+| Generated bash script for 27 commands                     | 257 lines, 9KB |
+
+### 2.1 Static generation, never a runtime callback
+
+Cobra and clap route every TAB press to a hidden `__complete` subcommand. That is correct for a Go or Rust binary that starts in 10ms. It is wrong here: a Ruby host costs 100ms at absolute best and 520ms in the case measured above. Half a second of dead air per keystroke is unusable, and no amount of lazy loading gets under the host's own require cost.
+
+So the generated script carries every completion it will ever offer, and TAB spawns no process. **Do not add a `__complete` command.** It was considered, costed at about 90 lines, and rejected on this measurement.
+
+### 2.2 The generator reads the registry and never forces anything beyond it
+
+The full walk plus spec build takes 0.067ms because it only touches objects dry-cli already holds. The moment an option's `values:` calls into a host's data, that cost lands at class-definition time on *every* invocation of the host, not just completion. In the profiled host that would have added 239ms of YAML parsing to shell startup.
+
+Enum values *declared on an option* are free and must be included:
+
+```ruby
+option :format, values: %w[json yaml table]   # completes json yaml table
+argument :component, values: %w[major minor]  # completes major minor
+```
+
+Values a host would have to compute are out of scope. There is no API for them. A host that wants them declares them as a constant on the option, where dry-cli validates the input and the generator sees it for free.
+
+### 2.3 Optimising the generator is pointless
+
+At 0.067ms, the work this gem does is 0.01% of the cheapest possible invocation. Native extensions were considered and rejected: they cannot reduce interpreter startup, which is where all the time goes, and they would put a compiled artifact in the dependency chain of every consumer. Keep it plain Ruby.
+
+### 2.4 Nothing loads until the command runs
+
+The host registers a command whose file pulls in no emitters:
+
+```ruby
+require "dry/cli/autocomplete/command"
+register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+```
+
+`command.rb` must define the command class and nothing else, and `require` the generator inside `#call`. This is the mistake in §1.3 and it cannot be retrofitted politely, so build it this way from the first commit. Verified working: after registering the shim, `defined?(Dry::CLI::Autocomplete::Generator)` is nil and `$LOADED_FEATURES` shows nothing, until the command is invoked.
+
+## 3. Reading a registry
+
+Everything needed is public API. **Do not use `instance_variable_get(:@node)`**, which is what the existing gem does. `Registry#get` returns a lookup result exposing `command`, `children` and `names`.
+
+This walk is proven against a foreign registry:
+
+```ruby
+def walk(registry, path = [], acc = [])
+  result = registry.get(path)
+  acc << [path, result.command, (result.children || {}).keys]
+  (result.children || {}).each_key { |name| walk(registry, path + [name], acc) }
+  acc
+end
+```
+
+Available per command: `.options` and `.arguments`. Per option: `name`, `type`, `values`, `aliases`, `default`, `desc`, `required?`, `boolean?`, `array?`. Per argument: `name`, `values`, `desc`, `required?`. Per node: `children`, `command`, `aliases`, `hidden`.
+
+Registering with `hidden: true` keeps a command out of `--help`; **the generator must skip hidden commands too**.
+
+Run against a registry with three commands, one of them nested, this produces:
+
+```
+(root)       -> version deploy db
+version      -> --format json plain
+deploy       -> --force -f staging production
+db           -> migrate
+db migrate   -> --step <file>
+```
+
+Note what that output demonstrates: the `-f` alias, enum values on both an option and an argument, a nested group with no command of its own, and a file argument detected.
+
+## 4. What the generated scripts must do
+
+### 4.1 Both shells, natively
+
+**bash** emits a `complete -F _mycli_completions mycli` function using `compgen -W` over the word list for the current command path, plus `compgen -f` where an argument takes a file.
+
+**zsh** emits a real `#compdef` script using `_arguments` and `_describe`, carrying each option's `desc` as help text. It is not a bashcompinit shim. This is the largest single piece of work in the gem, roughly 120 lines, and it is the reason the gem exists rather than a patch to the existing one.
+
+### 4.2 Program names that are not identifiers
+
+A host may be installed as `my-tool`. Shell function names cannot contain a dash, so derive the identifier with `Dry::Inflector#underscore` rather than a hand-rolled `gsub`. `Dry::CLI::Inflector` ships with dry-cli but only has `dasherize` and is marked `@api private`; do not use it.
+
+### 4.3 File arguments
+
+An argument whose name suggests a path should complete filenames. Matching on the name (`/file|path/`) is a heuristic and a poor one. Prefer letting the host be explicit, and fall back to the heuristic only when nothing is declared. Whatever the mechanism, the generated script must contain real file completion, which is the gap in §1.2.
+
+## 5. Testing
+
+**Never test only against one CLI.** A generator tested against a single registry bakes in that registry's shape. The suite must carry at least three fixture registries, and at least one must come from outside this project. Candidates: the examples in dry-cli's own repository, and Hanami's CLI.
+
+Each fixture must exercise: a nested group with a command at its bare name (§1.1), a file argument (§1.2), an option with `values`, a boolean flag, an option with an alias, and a hidden command.
+
+Validate generated output by running the shells, not by matching strings: `bash -n script` and `zsh -n script` both parse without executing. Golden-file the scripts so a change in output is visible in review.
+
+Pin the laziness contract with a spec, because it erodes silently:
+
+```ruby
+it "loads no emitter until the command runs" do
+  expect(defined?(Dry::CLI::Autocomplete::Generator)).to be_nil
+end
+```
+
+## 6. Acceptance criteria
+
+1. A node with both a command and children completes its children *and* its own options.
+1. Commands with file arguments produce real file completion in the generated script.
+1. `require "dry/cli/autocomplete/command"` loads no generator and no emitter.
+1. zsh output is a native `#compdef` script with per-option descriptions, not a bashcompinit shim.
+1. `bash -n` and `zsh -n` accept the generated scripts.
+1. Hidden commands do not appear.
+1. Program names containing dashes produce valid shell identifiers.
+1. Generating completions touches nothing outside the registry.
+1. Runtime dependencies are `dry-cli` and `dry-inflector`, and nothing else.
+1. The suite passes against at least one registry not written for this project.
+
+## 7. Out of scope
+
+- A `__complete` hidden command or any per-TAB process. See §2.1.
+- Values that require the host to load data. See §2.2.
+- Native extensions. See §2.3.
+- fish, PowerShell, nushell. Worth adding later; the emitter interface should make a fourth shell a new class rather than a new branch, but do not build them now.
+
+## 8. Scope estimate
+
+About 470 lines, most of it the zsh emitter and the specs.
+
+| Part                               | Lines |
+| ---------------------------------- | ----: |
+| Registry walk and spec builder     |    60 |
+| bash emitter                       |    60 |
+| zsh emitter                        |   120 |
+| Command shim and installation help |    30 |
+| Specs, including foreign fixtures  |   200 |
+
+Suggested order: walk, then bash, then zsh. The bash emitter proves the spec builder against a real shell quickly, and the zsh emitter is where the estimate is most likely to be wrong.
+
+## 9. Work units
+
+### 1. Registry walk and spec builder
+
+This section did not exist when the folder entered Building; an implementer found nothing here to build against and split it before writing any code, per the instruction that governs exactly this case. Four units, non-overlapping in the files they own, matching §8's table. #1 has no dependency on the others; #2 and #3 depend only on #1's *interface* below, not its code, so they can be built concurrently with each other and with WU1. WU4 integrates all three and is the last to land.
+
+Owns: 
+
+- `lib/dry/cli/autocomplete/spec_builder.rb`, 
+- `spec/dry/cli/autocomplete/spec_builder_spec.rb`, 
+- `spec/support/fixtures/**`.
+
+Builds the fixture registries the whole suite depends on (§5: at least three, at least one from outside this project) and the walker (§3) that turns a registry into the `CompletionSpec` shape defined below. Owns file-argument *detection* (§4.3): the heuristic and any explicit declaration are resolved here, so emitters only ever read a plain `file?` flag and never re-derive it.
+
+Done when: builds a correct spec for every fixture; hidden commands are absent from it; a node with both a command and children reports both (§1.1 acceptance criterion); nothing outside the registry is touched (no file reads, no host constants beyond what `values:` already declared).
+
+### 2. `BASH` emitter
+
+Owns: 
+
+* `lib/dry/cli/autocomplete/emitters/bash.rb`, 
+* `spec/dry/cli/autocomplete/emitters/bash_spec.rb`.
+
+Consumes a `CompletionSpec` (build one by hand in specs against the documented shape; do not import WU1's fixtures until WU1 has landed) and emits the `complete -F` script per §4.1: `compgen -W` over each node's word list, `compgen -f` where `file?` is set.
+
+Done when: golden-file tests cover a fixture with a nested group, a file argument, an aliased option, and a hidden command absent from output; every golden file passes `bash -n`.
+
+### 3. `ZSH` emitter
+
+Owns: 
+
+* `lib/dry/cli/autocomplete/emitters/zsh.rb`
+* spec/dry/cli/autocomplete/emitters/zsh_spec.rb`.
+
+Same `CompletionSpec` input as WU2. Emits a native `#compdef` script using `_arguments`/`_describe` (§4.1), carrying each option's `desc`. Not a bashcompinit shim.
+
+Done when: golden-file tests as WU2, output validated with `zsh -n`, and per-option descriptions are visible in the generated `_describe` calls.
+
+### 4. Generator and command shim
+
+Owns:
+
+* `lib/dry/cli/autocomplete/generator.rb`, 
+* `lib/dry/cli/autocomplete/command.rb`, 
+* `spec/dry/cli/autocomplete/generator_spec.rb`, 
+* `spec/dry/cli/autocomplete/command_spec.rb`.
+
+The generator is the small piece that ties a registry to an emitter: given a registry and a shell name, run WU1's spec builder, hand the result to WU2 or WU3's emitter, return the script. `command.rb` is the shim (§2.4): defines the command class, derives the program's shell-identifier with `Dry::Inflector#underscore` (§4.2, never a hand-rolled `gsub`), and `require`s `generator` only inside `#call`.
+
+Done when: the laziness spec from §5 passes (`defined?(Dry::CLI::Autocomplete::Generator)` is `nil` after requiring only `dry/cli/autocomplete/command`); dashed program names produce valid identifiers; the command actually produces working output end-to-end through a real emitter (a stub is fine mid-flight, but the unit is not done while one remains in the diff).
+
+### Interface contract between the units
+
+`SpecBuilder.call(registry, program_name:)` returns a `CompletionSpec`:
+
+- `program_name` — String, the shell-identifier-safe name (already run through `Dry::Inflector#underscore` by whichever unit constructs it — WU4's command shim owns this call, so WU1's builder just accepts the string it's given).
+- `nodes` — Array of `{path: Array<String>, options: [...], arguments: [...], children: Array<String>}`, one entry per node in the registry, hidden nodes excluded.
+- Each option: `{name:, type:, values:, aliases:, default:, desc:, required:, boolean:, array:}`.
+- Each argument: `{name:, values:, desc:, required:, file:}` — `file:` is the resolved boolean described under WU1 above.
+
+`Emitter.call(spec)` (both `Emitters::Bash` and `Emitters::Zsh`) takes one `CompletionSpec` and returns one String: the complete generated script. Neither emitter takes a registry, and neither knows what dry-cli's own API looks like.

data/docs/img/badge.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
+  <linearGradient id="b" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <mask id="a">
+    <rect width="99" height="20" rx="3" fill="#fff"/>
+  </mask>
+  <g mask="url(#a)">
+    <path fill="#555" d="M0 0h63v20H0z"/>
+    <path fill="#4c1" d="M63 0h36v20H63z"/>
+    <path fill="url(#b)" d="M0 0h99v20H0z"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+    <text x="31.5" y="14">coverage</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">98%</text>
+    <text x="80" y="14">98%</text>
+  </g>
+</svg>

data/exe/dry-cli-autocomplete

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require_relative "../lib/dry/cli/autocomplete"

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module Dry
+  class CLI
+    module Autocomplete
+      # The command a host registers to expose `mycli completion <shell>`.
+      #
+      # This file defines the command class and nothing else. It loads no
+      # spec builder and no emitter, and it must stay that way: a host pays
+      # for whatever this require pulls on *every* invocation, while the
+      # command itself runs about once per shell. The generator is required
+      # inside #call, where the cost is actually incurred. See
+      # SPECIFICATION.md §1.3 and §2.4, and the spec that pins it.
+      class Command < Dry::CLI::Command
+        SHELLS = %w[bash zsh].freeze
+
+        # Binds the command to a registry, and optionally to the name the
+        # host is installed as. Without one, the program name is taken from
+        # $PROGRAM_NAME at call time rather than at registration, since a
+        # gem may be required long before anyone knows how it was invoked.
+        #
+        #   register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+        def self.[](registry, program_name: nil)
+          Class.new(self) do
+            @registry = registry
+            @program_name = program_name
+          end
+        end
+
+        class << self
+          attr_reader :registry, :program_name
+        end
+
+        desc "Print a shell completion script"
+
+        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)}\""
+        ]
+
+        def call(shell:, **)
+          require_relative "spec_builder"
+          require_relative "emitters/#{shell}"
+
+          spec = SpecBuilder.call(registry, program_name: program_name)
+          out.puts emitter_for(shell).call(spec)
+        end
+
+        private
+
+        def registry
+          self.class.registry or
+            raise ArgumentError, "no registry bound: register Dry::CLI::Autocomplete::Command[MyCLI]"
+        end
+
+        def program_name
+          self.class.program_name || File.basename($PROGRAM_NAME)
+        end
+
+        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
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "dry/inflector"
+
+module Dry
+  class CLI
+    module Autocomplete
+      module Emitters
+        # Turns a CompletionSpec into a bash `complete -F` script.
+        # See SPECIFICATION.md §4.1: a static, case-statement walk over
+        # COMP_WORDS resolves which node the cursor is under, then
+        # `compgen -W` fills COMPREPLY from that node's children and
+        # option flags, with `compgen -f` added where an argument is a
+        # file (§4.3).
+        #
+        # Deliberately avoids bash associative arrays (bash 4+ only):
+        # macOS still ships bash 3.2 as /bin/bash, and this script is
+        # meant to be eval'd from exactly that.
+        class Bash
+          def self.call(spec)
+            new(spec).call
+          end
+
+          def initialize(spec)
+            @spec = spec
+          end
+
+          def call
+            "#{body.join("\n")}\n"
+          end
+
+          private
+
+          attr_reader :spec
+
+          def body
+            header_lines + path_walk_lines + word_lookup_lines + footer_lines
+          end
+
+          def header_lines
+            [
+              "#{function_name}() {",
+              "  local cur path word next_path words i",
+              "  COMPREPLY=()",
+              '  cur="${COMP_WORDS[COMP_CWORD]}"',
+              '  path=""',
+              "  i=1"
+            ]
+          end
+
+          def path_walk_lines
+            path_walk_open_lines + path_walk_close_lines
+          end
+
+          def path_walk_open_lines
+            lines = [
+              '  while [ "$i" -lt "$COMP_CWORD" ]; do',
+              '    word="${COMP_WORDS[$i]}"',
+              '    next_path=""',
+              '    case "$path:$word" in'
+            ]
+            edge_arms.each { |arm| lines << "      #{arm}" }
+            lines << "    esac"
+          end
+
+          def path_walk_close_lines
+            [
+              '    if [ -z "$next_path" ]; then',
+              "      break",
+              "    fi",
+              '    path="$next_path"',
+              "    i=$((i + 1))",
+              "  done",
+              ""
+            ]
+          end
+
+          def word_lookup_lines
+            lines = ['  words=""', '  case "$path" in']
+            word_arms.each { |arm| lines << "    #{arm}" }
+            lines + ["  esac", ""]
+          end
+
+          def footer_lines
+            [
+              '  COMPREPLY=($(compgen -W "$words" -- "$cur"))',
+              *file_completion_lines,
+              "}",
+              "complete -F #{function_name} #{spec.program_name}"
+            ]
+          end
+
+          def function_name = "_#{shell_identifier}_completions"
+
+          # A program installed as `my-tool` cannot name a shell function
+          # directly. See SPECIFICATION.md §4.2.
+          def shell_identifier
+            Dry::Inflector.new.underscore(spec.program_name.to_s).gsub(/[^A-Za-z0-9_]/, "_")
+          end
+
+          def path_key(path) = path.join(" ")
+
+          def edge_arms
+            spec.nodes.flat_map do |node|
+              parent_key = path_key(node.path)
+              node.children.map do |child|
+                child_key = path_key(node.path + [child])
+                "\"#{quote(parent_key)}:#{quote(child)}\") next_path=\"#{quote(child_key)}\" ;;"
+              end
+            end
+          end
+
+          def word_arms
+            spec.nodes.filter_map do |node|
+              words = node_words(node)
+              next if words.empty?
+
+              "\"#{quote(path_key(node.path))}\") words=\"#{quote(words.join(" "))}\" ;;"
+            end
+          end
+
+          def node_words(node)
+            node.children + node.options.flat_map { |option| option_words(option) }
+          end
+
+          def option_words(option) = ["--#{option.name}"] + Array(option.aliases)
+
+          def file_completion_lines
+            paths = spec.nodes.select { |node| node.arguments.any?(&:file) }.map { |node| path_key(node.path) }
+            return [] if paths.empty?
+
+            lines = ['  case "$path" in']
+            paths.each do |key|
+              lines << "    \"#{quote(key)}\") COMPREPLY+=($(compgen -f -- \"$cur\")) ;;"
+            end
+            lines << "  esac"
+            lines
+          end
+
+          def quote(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub('"', "\\\"")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "dry/inflector"
+
+module Dry
+  class CLI
+    module Autocomplete
+      module Emitters
+        # Turns a CompletionSpec into a native zsh `#compdef` script.
+        #
+        # This is not a bashcompinit shim. Options go through `_arguments`
+        # carrying their `desc` as help text, subcommands go through
+        # `_describe`, declared enum values become a `(a b c)` action, and a
+        # file argument becomes `_files`. That per-option help is the thing
+        # zsh users lose with a shim, and the reason this emitter exists.
+        # See SPECIFICATION.md §4.1.
+        #
+        # Shares no code with the bash emitter by design: a fourth shell
+        # should be a new class here, never another branch inside one of
+        # these two.
+        class Zsh
+          def self.call(spec)
+            new(spec).call
+          end
+
+          def initialize(spec)
+            @spec = spec
+          end
+
+          def call
+            "#{body.join("\n")}\n"
+          end
+
+          private
+
+          attr_reader :spec
+
+          def body
+            header_lines + path_walk_lines + dispatch_lines + footer_lines
+          end
+
+          def header_lines
+            [
+              "#compdef #{spec.program_name}",
+              "",
+              "# Generated by dry-cli-autocomplete. Regenerate after changing commands.",
+              "",
+              "#{function_name}() {",
+              '  local curcontext="$curcontext" state line ret=1',
+              "  local -a commands",
+              "  typeset -A opt_args",
+              ""
+            ]
+          end
+
+          # Resolves which node the cursor sits under by consuming words the
+          # registry knows, exactly as the bash emitter does. words[1] is the
+          # program itself under zsh, so the scan starts at 2.
+          def path_walk_lines
+            lines = [
+              '  local path_key="" i=2',
+              "  while (( i < CURRENT )); do",
+              '    case "$path_key:${words[i]}" in'
+            ]
+            edge_arms.each { |arm| lines << "      #{arm}" }
+            lines + [
+              "      (*) break ;;",
+              "    esac",
+              "    (( i += 1 ))",
+              "  done",
+              ""
+            ]
+          end
+
+          def dispatch_lines
+            lines = ['  case "$path_key" in']
+            spec.nodes.each { |node| lines.concat(node_arm_lines(node)) }
+            lines + ["  esac", ""]
+          end
+
+          def footer_lines
+            [
+              "  return ret",
+              "}",
+              "",
+              "#{function_name} \"$@\""
+            ]
+          end
+
+          def node_arm_lines(node)
+            inner = arguments_call_lines(node) + describe_call_lines(node)
+            return [] if inner.empty?
+
+            ["    (#{single_quote(path_key(node.path))})", *inner.map { |line| "      #{line}" }, "      ;;"]
+          end
+
+          # One `_arguments` call carrying every option and positional this
+          # node declares. `-s` allows clustered single-letter flags.
+          def arguments_call_lines(node)
+            specs = node.options.flat_map { |option| option_specs(option) } +
+                    node.arguments.map { |argument| argument_spec(argument) }
+            return [] if specs.empty?
+
+            ["_arguments -s \\", *specs[0..-2].map { |s| "  #{s} \\" }, "  #{specs.last} && ret=0"]
+          end
+
+          def describe_call_lines(node)
+            return [] if node.children.empty?
+
+            entries = node.children.map do |child|
+              single_quote("#{escape_describe(child)}:#{escape_describe(child_desc(node, child))}")
+            end
+
+            ["commands=(", *entries.map { |e| "  #{e}" }, ")",
+             "_describe -t commands #{single_quote(describe_tag(node))} commands && ret=0"]
+          end
+
+          # 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.
+          def option_specs(option)
+            names = ["--#{option.name}"] + Array(option.aliases)
+            names.map { |name| single_quote("#{name}#{bracketed(option.desc)}#{option_action(option)}") }
+          end
+
+          # A boolean flag takes no value. Anything else gets one field
+          # naming what it wants and one supplying the completions for it.
+          def option_action(option)
+            return "" if option.boolean
+
+            ":#{escape_spec(option.name)}:#{value_action(option.values)}"
+          end
+
+          # A positional takes `:message:action`, with no bracketed
+          # description: zsh shows the message itself while completing, so
+          # the command's own wording goes there when it has any.
+          def argument_spec(argument)
+            action = argument.file ? "_files" : value_action(argument.values)
+            message = argument.desc.to_s.empty? ? argument.name : argument.desc
+            single_quote("*:#{escape_describe(message)}:#{action}")
+          end
+
+          def value_action(values)
+            return "" if values.nil? || values.empty?
+
+            "(#{values.map { |value| escape_spec(value) }.join(" ")})"
+          end
+
+          def bracketed(desc)
+            return "" if desc.nil? || desc.empty?
+
+            "[#{escape_bracket(desc)}]"
+          end
+
+          def child_desc(node, child)
+            found = spec.nodes.find { |candidate| candidate.path == node.path + [child] }
+            found&.desc.to_s
+          end
+
+          def describe_tag(node)
+            node.path.empty? ? "command" : "#{node.path.join(" ")} command"
+          end
+
+          def path_key(path) = path.join(" ")
+
+          # zsh reads `]` as the end of a description and `:` as the start of
+          # the next spec field, so both have to be escaped inside one.
+          def escape_bracket(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub("]", "\\\\]").gsub(":", "\\\\:")
+
+          def escape_spec(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub(":", "\\\\:").gsub(/([()\[\] ])/, '\\\\\1')
+
+          def escape_describe(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub(":", "\\\\:")
+
+          def single_quote(str) = "'#{str.to_s.gsub("'", "'\\\\''")}'"
+
+          def function_name = "_#{shell_identifier}_completions"
+
+          # A program installed as `my-tool` cannot name a shell function
+          # directly. See SPECIFICATION.md §4.2.
+          def shell_identifier
+            Dry::Inflector.new.underscore(spec.program_name.to_s).gsub(/[^A-Za-z0-9_]/, "_")
+          end
+
+          def edge_arms
+            spec.nodes.flat_map do |node|
+              node.children.map do |child|
+                "(#{single_quote("#{path_key(node.path)}:#{child}")}) " \
+                  "path_key=#{single_quote(path_key(node.path + [child]))} ;;"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Autocomplete
+      # Walks a Dry::CLI registry through its public API and returns a
+      # shell-agnostic description of every completion: one CompletionSpec
+      # carrying one Node per reachable, non-hidden command or group.
+      #
+      # Touches nothing beyond the registry and the command classes it
+      # already holds, so it stays cheap enough to run on every shell start.
+      # See SPECIFICATION.md §2.2 and §2.3.
+      class SpecBuilder
+        CompletionSpec = Struct.new(:program_name, :nodes, keyword_init: true)
+        Node = Struct.new(:path, :desc, :options, :arguments, :children, keyword_init: true)
+
+        # :values shadows Struct#values by design: it is the field name the
+        # interface contract in .plans/001.00-*/plan.md fixes for emitters.
+        OptionSpec = Struct.new(
+          :name, :type, :values, :aliases, :default, :desc, :required, :boolean, :array,
+          keyword_init: true
+        )
+        ArgumentSpec = Struct.new(:name, :values, :desc, :required, :file, keyword_init: true)
+        # rubocop:enable Lint/StructNewOverride
+
+        # A bare heuristic, used only when a host does not declare `file:`
+        # explicitly on the argument. See SPECIFICATION.md §4.3.
+        FILE_ARGUMENT_HEURISTIC = /file|path/i
+
+        def self.call(registry, program_name:)
+          new(registry, program_name).call
+        end
+
+        def initialize(registry, program_name)
+          @registry = registry
+          @program_name = program_name
+        end
+
+        def call
+          CompletionSpec.new(program_name: program_name, nodes: walk([]))
+        end
+
+        private
+
+        attr_reader :registry, :program_name
+
+        def walk(path, nodes = [])
+          result = registry.get(path)
+          visible = visible_children(result)
+
+          nodes << build_node(path, result, visible)
+          visible.each_key { |name| walk(path + [name], nodes) }
+          nodes
+        end
+
+        def visible_children(result)
+          result.children.reject { |_name, node| node.hidden }
+        end
+
+        def build_node(path, result, visible)
+          command = result.command
+
+          Node.new(
+            path: path,
+            desc: command&.description,
+            options: command ? command.options.map { |option| build_option(option) } : [],
+            arguments: command ? command.arguments.map { |argument| build_argument(argument) } : [],
+            children: visible.keys
+          )
+        end
+
+        def build_option(option)
+          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?
+          )
+        end
+
+        def build_argument(argument)
+          ArgumentSpec.new(
+            name: argument.name.to_s, values: argument.values, desc: argument.options[:desc],
+            required: argument.required? || false, file: file_argument?(argument)
+          )
+        end
+
+        def file_argument?(argument)
+          explicit = argument.options[:file]
+          return !!explicit unless explicit.nil?
+
+          argument.name.to_s.match?(FILE_ARGUMENT_HEURISTIC)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Dry
+  # Reopened rather than defined: dry-cli declares `class CLI`, not a module,
+  # and getting that wrong raises TypeError the moment both are loaded.
+  #
+  # Declared here without requiring dry-cli, because the gemspec loads this
+  # file at build time when the dependency may not be installed. dry-cli's CLI
+  # inherits from Object, so an empty reopening is compatible either way.
+  class CLI
+    module Autocomplete
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/dry/cli/autocomplete.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "autocomplete/version"
+
+module Dry
+  class CLI
+    # Generates static shell completion scripts from a Dry::CLI registry.
+    #
+    # The generator reads the registry and never forces anything beyond it:
+    # commands, subcommands, options, their declared enum values, and which
+    # arguments look like file paths. Nothing it produces requires loading a
+    # host's data, because the script is regenerated on every shell start via
+    # `eval "$(mycli completion bash)"` and a slow generator is a slow shell.
+    module Autocomplete
+      class Error < StandardError; end
+    end
+  end
+end

data/lib/dry-cli-autocomplete.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "./dry/cli/autocomplete"

data/sig/dry/cli/autocomplete.rbs

@@ -0,0 +1,8 @@
+module Dry
+  class CLI
+    module Autocomplete
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: dry-cli-autocomplete
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Konstantin Gredeskoul
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: dry-inflector
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Supports auto-completion for dry-cli powered Ruby CLI tools, including
+  sub-commands, in BASH and ZSH.
+email:
+- kigster@gmail.com
+executables:
+- dry-cli-autocomplete
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.local.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- SPECIFICATION.md
+- docs/img/badge.svg
+- exe/dry-cli-autocomplete
+- lib/dry-cli-autocomplete.rb
+- lib/dry/cli/autocomplete.rb
+- lib/dry/cli/autocomplete/command.rb
+- lib/dry/cli/autocomplete/emitters/bash.rb
+- lib/dry/cli/autocomplete/emitters/zsh.rb
+- lib/dry/cli/autocomplete/spec_builder.rb
+- lib/dry/cli/autocomplete/version.rb
+- sig/dry/cli/autocomplete.rbs
+homepage: https://github.com/kigster/dry-cli-autocomplete
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kigster/dry-cli-autocomplete
+  source_code_uri: https://github.com/kigster/dry-cli-autocomplete
+  changelog_uri: https://github.com/kigster/dry-cli-autocomplete/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: A missing auto-complete addition for dry-cli powered Ruby CLI tools for BASH
+  & ZSH
+test_files: []