(2 of 4) Add Tree: a read-only view of CLI's commands (if accepted, must be stack-merged onto #175)

[kigster]

Proposal 2 of 4 in the dry-cli extension hooks series. This should stack on top of #175. As mentioned, I couldn't select a branch on a fork as the base, but perhaps the owners can.

Summary

A public, read-only, live view of the commands, replacing the CommandRegistry / LookupResult / Node internals that help completion gems walk today.

# Registry#tree   (also Dry::CLI#tree, Tree.for(command))
root = MyApp::Commands.tree            

root["db"]                             # by name or alias
root.dig("db", "migrate")
node, rest = root.resolve(%w[db migrate --force])  # same lookup as dispatch
root.walk(hidden: false) { |node| … }
node.options.first                     # Tree::Param: name, kind, type, desc, values, switches, metadata…

 CommandRegistry
-  #get(arguments)            # lookup inlined under the mutex
+  #get(arguments)            # synchronize { .lookup(@root, arguments) }
+  .lookup(node, arguments)   # shared with Tree::Node#resolve
+  #root

• Live: reads go to the registry, so commands and options added after tree was taken are visible (needed for dynamic completion).

• Param#metadata carries every declared key, so extensions read their own (i.e., file: true).

• CommandRegistry, Option, Argument stay @api private.

Evidence

• Before: dry-cli-autocomplete: registry.get(path).children.reject { _2.hidden }; dry-cli-help: node.parent.aliases.filter_map { … }.

• After: tree.walk(hidden: false) and node.aliases. spec/unit/dry/cli/tree_spec.rb: 30 examples, including resolve-vs-dispatch parity over 10 command lines and liveness. Full suite 661 examples, 0 failures; rubocop clean.

Merge Risk

Additive; CommandRegistry#get is refactored but behaves identically (whole suite unchanged).

Blast Radius

Believed to be small.

If merged, what changes in the futue:

• New public surface (Tree) that dry-cli would need to commit to keeping stable.