dry-cli-autocomplete 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5de81918d8ea085c400d5578481fd513b595d21b4e6c46fa2cce70ffbbe051f1
+  data.tar.gz: b57a07d39c36db90a843474694e61c1fcf970f58a2267bc44449ed60017f3369
+SHA512:
+  metadata.gz: fd15d74c1ebece2e83817330d91f09f664b301753cbe09f2c5413ee042db260ea04acff53c6b090b1ea275b748f38949fd348f2b4bc847680446e546f57c6c68
+  data.tar.gz: c7bdc08cdeefa48c8ea9f67c9667fb76053b28a75ff96f7d1239ab2f1135d6f22a296a402a64c364fbedb7e8b7ede2b25e2ae8ebaa14087233d51cd6a3f40ca3

data/.secrets.baseline

@@ -0,0 +1,127 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-04-13T21:29:03Z"
+}

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+## [Unreleased]
+
+## [0.1.3] - 2026-08-23
+
+- The zsh script now registers itself when sourced. `eval "$(mycli completion zsh)"`
+  previously ran the completion function outside a completion context, and zsh
+  answered with `_tags:comptags:36: can only be called from completion function`.
+  The script now calls itself when autoloaded from `$fpath` and calls `compdef`
+  when sourced, so both work.
+- The zsh function is named `_mycli` rather than `_mycli_completions`, matching
+  the name a `#compdef` file is autoloaded under. The bash function is unchanged.
+
+## [0.1.2] - 2026-08-22
+
+- The bash script now completes values declared on an option. `mycli fmt --format` then TAB offered the command list again instead of the values `--format` accepts; zsh had always emitted them, so only the bash side was dropping them.
+- The bash script now offers values declared on a positional argument at that position, alongside the node's flags and subcommands.
+
+## [0.1.1] - 2026-08-22
+
+- Fixed loading inside any host that has dry-struct loaded. The value objects were built from a bare `Struct`, which resolves to `Dry::Struct` from inside `module Dry`, so `mycli completion bash` raised `wrong number of arguments` on the host's machine while this gem's own suite stayed green.
+- Value objects are `Data` rather than `Struct`: frozen, and a missing field raises instead of arriving as a silent nil.
+
+## [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,180 @@
+# 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
+```
+
+## 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
+
+```bash
+gem install dry-cli-autocomplete
+```
+
+Or add it to your `Gemfile`.
+
+Then register the command in your CLI. Require the command file, not the gem: it pulls in no emitter and no generator, so a host pays nothing at boot for a command that runs once per shell.
+
+```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"
+```
+
+Sourcing it from `.zshrc` works too, if you would rather not manage a file:
+
+```bash
+eval "$(mycli completion zsh)"
+```
+
+The script tells the two apart and registers itself either way.
+
+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>.
+
+> [!WARNING]
+> A quick 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. I hope this functionality will make it into `dry-cli` one day, however.
+
+## 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 SPECIFICATION.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