aspera-cli 4.27.2 → 4.27.3

data/lib/aspera/cli/command_line.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/error'
+require 'aspera/dot_container'
+require 'aspera/log'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Positional (non-option) command line token.
+    class Argument
+      # @return [String] the raw argument value
+      attr_reader :value
+      # @return [Option, nil] option token claiming this token as its value (`--opt value` form)
+      attr_accessor :owner
+      # @return [Boolean] `true` once used, as positional argument or as option value
+      attr_accessor :consumed
+
+      def initialize(value)
+        @value = value
+        @owner = nil
+        @consumed = false
+      end
+
+      # @return [Boolean] `true` if available as positional argument
+      def positional? = !@consumed && @owner.nil?
+
+      # @return [String] raw argument value
+      def to_s = @value
+    end
+
+    # Option command line token (long or short form).
+    class Option
+      # @return [String] raw token as it appeared in argv (e.g. "--log-level=debug", "-Pval")
+      attr_reader :raw
+      # @return [String, nil] option name with underscores (e.g. "log_level"), nil for short options
+      attr_reader :name
+      # @return [String, nil] single-char short option letter (e.g. "P"), nil for long options
+      attr_reader :short_char
+      # @return [Array<String>, nil] sub-keys for dot-path notation (e.g. ["field"] for --custom.field)
+      attr_reader :dot_path
+      # @return [String, nil] value given in the same token (`--opt=val` or `-Oval`)
+      attr_reader :inline_value
+      # @return [Argument, nil] next token, claimed as value when there is no inline value (`--opt val` or `-O val`)
+      attr_accessor :value_token
+      # @return [Boolean] `true` once applied to a declared option
+      attr_accessor :consumed
+      # @return [Symbol, nil] option this token was resolved to, when `name` is an abbreviation
+      attr_accessor :abbreviation_of
+
+      def initialize(raw:, name: nil, short_char: nil, dot_path: nil, inline_value: nil)
+        @raw          = raw
+        @name         = name
+        @short_char   = short_char
+        @dot_path     = dot_path
+        @inline_value = inline_value
+        @value_token  = nil
+        @consumed     = false
+        @abbreviation_of = nil
+      end
+
+      # @return [Boolean] `true` if value is in the same token
+      def inline? = !@inline_value.nil?
+
+      # @return [String, nil] inline value, or value of next token
+      def value = @inline_value || @value_token&.value
+
+      # @return [String] raw token, followed by its separate value if any
+      def to_s = @value_token.nil? ? @raw : "#{@raw} #{@value_token.value}"
+
+      class << self
+        # @param token [String] command line token
+        # @return [Boolean] `true` if token is an option, i.e. not `-`, `--`, or a negative number
+        def option?(token)
+          token.match?(/\A-\D/) && !token.eql?(STOP)
+        end
+
+        # Build an Option from a raw token
+        # @param raw [String] e.g. "--log-level=debug", "--custom.field", "-P", "-Pval"
+        # @return [Option]
+        def parse(raw)
+          if raw.start_with?(PREFIX)
+            name_raw, value = raw.delete_prefix(PREFIX).split(VALUE_SEP, 2)
+            root, *dot_path = name_raw.to_s.split(DotContainer::SEPARATOR)
+            new(raw: raw, name: root.to_s.gsub(NAME_SEP_LINE, NAME_SEP_SYMBOL), dot_path: dot_path.empty? ? nil : dot_path, inline_value: value)
+          else
+            new(raw: raw, short_char: raw[1], inline_value: raw.length > 2 ? raw[2..] : nil)
+          end
+        end
+      end
+
+      # Option name separator on command line (e.g. `--option-name`, the `-` between words)
+      NAME_SEP_LINE   = '-'
+      # Option name separator in code/symbol (e.g. `:option_name`, the `_` between words)
+      NAME_SEP_SYMBOL = '_'
+      # Separator between option name and its inline value (e.g. `--opt=val`, the `=`)
+      VALUE_SEP = '='
+      # Long-option prefix (e.g. `--opt`)
+      PREFIX = '--'
+      # When alone, stops option processing: following tokens are positional arguments
+      STOP = '--'
+    end
+
+    # Command line split in tokens, in original order.
+    # Tokens are never removed, only marked as consumed, so that positions are kept.
+    #
+    # An option without inline value claims the next token as its value (`--opt val`, `-O val`),
+    # unless that token looks like an option.
+    # If the option turns out to be a flag, the claimed token is given back to positional arguments.
+    class CommandLine
+      # @param argv [Array<String>] command line arguments
+      def initialize(argv)
+        # @type [Array<Option, Argument>]
+        @tokens = []
+        # Option token being applied (used by `@:` extended value)
+        @current_option = nil
+        # When set, only positional arguments after this token are available
+        @arguments_after = nil
+        process_options = true
+        argv.each do |value|
+          if process_options && value.eql?(Option::STOP)
+            process_options = false
+          elsif process_options && Option.option?(value)
+            @tokens.push(Option.parse(value))
+          else
+            argument = Argument.new(value)
+            previous = @tokens.last
+            if process_options && previous.is_a?(Option) && !previous.inline? && previous.value_token.nil?
+              previous.value_token = argument
+              argument.owner = previous
+            end
+            @tokens.push(argument)
+          end
+        end
+        Log.log.trace1 { "arguments=#{pending_arguments},options=#{pending_options}" }
+      end
+
+      # @return [Array<Option>] option tokens whose name was resolved as an abbreviation
+      def abbreviated_option_tokens
+        @tokens.select { |t| t.is_a?(Option) && !t.abbreviation_of.nil? }
+      end
+
+      # @return [Array<Option>] option tokens not applied yet
+      def pending_option_tokens
+        @tokens.select { |t| t.is_a?(Option) && !t.consumed }
+      end
+
+      # Mark option token as applied, and get its value.
+      # @param tok         [Option]  option token
+      # @param takes_value [Boolean] `false` for flags: claimed token is given back to positional arguments
+      # @return [String, nil] value, or `nil` for flags
+      # @raise [BadArgument] if option takes a value and none was given
+      def consume(tok, takes_value:)
+        tok.consumed = true
+        return release(tok) unless takes_value
+        return tok.inline_value if tok.inline?
+        Aspera.assert(!tok.value_token.nil?, type: BadArgument) { "Option #{tok.raw} requires a value" }
+        tok.value_token.consumed = true
+        tok.value_token.value
+      end
+
+      # Execute block with `tok` as current option
+      # @param tok [Option] option token being applied
+      def with_current_option(tok)
+        @current_option = tok
+        yield
+      ensure
+        @current_option = nil
+      end
+
+      # Execute block with only positional arguments after current option available, if any
+      def with_arguments_after_current_option
+        @arguments_after = @current_option
+        yield
+      ensure
+        @arguments_after = nil
+      end
+
+      # @return [Array<String>] values of available positional arguments
+      def pending_arguments
+        positional_tokens.map(&:value)
+      end
+
+      # @return [Array<String>] options not applied yet, with their value if separate
+      def pending_options
+        pending_option_tokens.map(&:to_s)
+      end
+
+      # Consume positional arguments.
+      # @param multiple [false, true, String] consumption mode:
+      #   false  — consume exactly one token
+      #   true   — consume all remaining tokens
+      #   String — consume up to the marker token (marker is consumed too, not returned), or all if absent
+      # @return [Array<String>] consumed values
+      def shift_arguments(multiple)
+        arg_tokens = positional_tokens
+        selected =
+          case multiple
+          when false then arg_tokens.first(1)
+          when true then arg_tokens
+          when String
+            index = arg_tokens.index { |t| t.value.eql?(multiple) }
+            arg_tokens[index].consumed = true unless index.nil?
+            arg_tokens.take(index || arg_tokens.length)
+          else Aspera.error_unexpected_value(multiple) { 'multiple' }
+          end
+        selected.each { |t| t.consumed = true }
+        selected.map(&:value)
+      end
+
+      # Add an argument before the available positional arguments
+      # @param value [String] argument value
+      def unshift_argument(value)
+        index = @tokens.index { |t| t.is_a?(Argument) && t.positional? } || @tokens.length
+        @tokens.insert(index, Argument.new(value))
+      end
+
+      # Consume all long options with a value, whether applied or not.
+      # @yieldparam tok [Option] long option token with a value
+      def each_long_option_with_value
+        @tokens.each do |tok|
+          next unless tok.is_a?(Option) && tok.short_char.nil? && !tok.value.nil?
+          yield(tok)
+          tok.consumed = true
+          tok.value_token&.consumed = true
+        end
+      end
+
+      private
+
+      # Give back claimed token to positional arguments.
+      # @param tok [Option] flag option token
+      # @return [nil]
+      def release(tok)
+        value_token = tok.value_token
+        return if value_token.nil?
+        index = @tokens.index { |t| t.equal?(value_token) }
+        Aspera.assert(@tokens[index + 1..].none? { |t| t.is_a?(Argument) && t.consumed && t.owner.nil? }) do
+          "Flag #{tok.raw} declared after following positional arguments were used"
+        end
+        value_token.owner = nil
+        tok.value_token = nil
+      end
+
+      # @return [Array<Argument>] available positional arguments, in order
+      def positional_tokens
+        start = @arguments_after.nil? ? 0 : @tokens.index { |t| t.equal?(@arguments_after) } + 1
+        @tokens[start..].select { |t| t.is_a?(Argument) && t.positional? }
+      end
+    end
+  end
+end

data/lib/aspera/cli/command_registry.rb

@@ -11,16 +11,81 @@ module Aspera
     #   register(spec)          - store a CommandSpec; raises on duplicate full_path
     #   register_option(spec)   - store an OptionSpec by name
     #   option_specs            - Hash{Symbol => OptionSpec} of all registered options
-    #   [](path)                - retrieve a CommandSpec by full path
-    #   children_of(path)       - Hash{Symbol => CommandSpec} of direct children (O(1))
-    #   all_paths               - Array of all registered full paths
+    #   [](path)                - retrieve a CommandSpec by full path (follows mounts)
+    #   children_of(path)       - Hash{Symbol => CommandSpec} of direct children (follows mounts)
+    #   resolve(path)           - [registry, path] owning the spec at path (follows mounts)
+    #   local?(path)            - true if path is owned by this registry (not reached through a mount)
+    #   mount_of(path)          - MountSpec of the local node at path, if any
+    #   mount_at(path)          - MountSpec of the node at path, if any (follows mounts)
+    #   own_children_of(path)   - Hash{Symbol => CommandSpec} of direct children declared on the node, without mounted ones
+    #   arguments_at(path)      - Array of ArgumentSpec read by the node at path (mount arguments first)
+    #   leaf_paths              - Array of all leaf paths (follows mounts, or stops at mount nodes)
+    #   all_paths               - Array of all locally registered full paths
     #   any?                    - true if at least one spec has been registered
     #   validate!               - cross-spec consistency checks; raises on violation
+    #
+    # Paths are always expressed in this registry's namespace: a path going through a
+    # mounted node (see MountSpec) is translated to the target registry transparently.
+    # Specs returned for mounted paths are the target's specs (their full_path is in the
+    # target namespace).
     class CommandRegistry
       # @param path [Array<Symbol>] full path to look up
       # @return [CommandSpec, nil]
       def [](path)
-        @specs[Array(path)]
+        registry, local_path = resolve(path)
+        registry.equal?(self) ? @specs[local_path] : registry[local_path]
+      end
+
+      # Find the registry owning `path`, following mounts.
+      # A host child always takes precedence over a mounted child with the same id.
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Array(CommandRegistry, Array<Symbol>)] owning registry and path in its namespace
+      def resolve(path)
+        path = Array(path)
+        path.each_index do |i|
+          prefix = path[0, i]
+          mount = @specs[prefix]&.mount
+          next if mount.nil? || @children_index[prefix]&.key?(path[i]) || !mount.accepts?(path[i])
+          return mount.registry.resolve(mount.at + path[i..])
+        end
+        [self, path]
+      end
+
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Boolean] true if the node at path is declared in this registry (not mounted)
+      def local?(path)
+        resolve(path).first.equal?(self)
+      end
+
+      # @param path [Array<Symbol>] local path of a node
+      # @return [MountSpec, nil] the mount declared on that node
+      def mount_of(path)
+        @specs[Array(path)]&.mount
+      end
+
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [MountSpec, nil] the mount declared on the node at path, following mounts
+      def mount_at(path)
+        registry, local_path = resolve(path)
+        registry.mount_of(local_path)
+      end
+
+      # Children declared on the node itself, without the ones exposed by its mount.
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Hash{Symbol => CommandSpec}]
+      def own_children_of(path)
+        registry, local_path = resolve(path)
+        return registry.own_children_of(local_path) unless registry.equal?(self)
+        @children_index[local_path] || {}
+      end
+
+      # Arguments read by the node at path, in order.
+      # For a child exposed by a mount, the mount's arguments come first (read by the host).
+      # @param path [Array<Symbol>] path in this registry's namespace
+      # @return [Array<ArgumentSpec>]
+      def arguments_at(path)
+        path = Array(path)
+        (path.empty? ? [] : mount_arguments(path)) + (self[path]&.arguments || [])
       end
 
       # Register a CommandSpec. Raises if the full_path is already registered.
@@ -40,14 +105,40 @@ module Aspera
 
       # Returns a Hash mapping each child id to its CommandSpec for all direct
       # children of `path`. Empty hash if no children are registered.
-      # O(1) lookup via the children index built in register().
+      # For a mount node: mounted children (filtered) followed by local children,
+      # local ones overriding mounted ones with the same id.
       # @param path [Array<Symbol>] parent path ([] for root-level commands)
       # @return [Hash{Symbol => CommandSpec}]
       def children_of(path)
-        @children_index[Array(path)] || {}
+        registry, local_path = resolve(path)
+        return registry.children_of(local_path) unless registry.equal?(self)
+        own = @children_index[local_path] || {}
+        mount = @specs[local_path]&.mount
+        return own if mount.nil?
+        mount.registry.children_of(mount.at).select { |id, _| mount.accepts?(id) }.merge(own)
+      end
+
+      # All leaf paths under path, in tree order, following mounts.
+      # A mount cycle (a sub-tree mounting one of its ancestors) is not expanded twice.
+      # @param path          [Array<Symbol>] root of the listing ([] for all)
+      # @param expand_mounts [Boolean]       `false`: a mount node is listed as a leaf, followed by its own children only
+      # @return [Array<Array<Symbol>>]
+      def leaf_paths(path = [], chain = [], expand_mounts: true)
+        children_of(path).keys.flat_map do |id|
+          child = path + [id]
+          key = subtree_key(child)
+          next [] if chain.include?(key)
+          if !expand_mounts && mount_at(child)
+            next [child] + own_children_of(child).keys.flat_map do |own_id|
+              own_child = child + [own_id]
+              children_of(own_child).empty? ? [own_child] : leaf_paths(own_child, chain + [key], expand_mounts: false)
+            end
+          end
+          children_of(child).empty? ? [child] : leaf_paths(child, chain + [key], expand_mounts: expand_mounts)
+        end
       end
 
-      # @return [Array<Array<Symbol>>] all registered full paths
+      # @return [Array<Array<Symbol>>] all locally registered full paths
       def all_paths
         @specs.keys
       end
@@ -95,42 +186,67 @@ module Aspera
         @specs.each_value do |spec|
           path = spec.full_path
 
-          # Rule: delegates_to must point to a known path when present (non-empty array or symbol)
-          if spec.delegates_to
-            dt_path =
-              case spec.delegates_to
-              when Symbol then [spec.delegates_to]
-              when Array  then spec.delegates_to
-              end
-            # An empty array [] means re-enter the root - always valid
-            unless dt_path.empty? || @specs.key?(dt_path)
-              raise ArgumentError,
-                "#{path.inspect}: delegates_to #{dt_path.inspect} points to unknown path"
-            end
+          if (mount = spec.mount)
+            # Rule: a mount needs an instance method, no action, and must point to existing target nodes
+            raise ArgumentError, "#{path.inspect}: mount requires instance:" if mount.instance.nil?
+            # Mount arguments precede the arguments of the mounted command: they cannot be optional
+            raise ArgumentError, "#{path.inspect}: mount arguments must be mandatory" unless mount.arguments.all?(&:mandatory)
+            raise ArgumentError, "#{path.inspect}: mount and action: are exclusive" if spec.action
+            raise ArgumentError, "#{path.inspect}: mount at #{mount.at.inspect} not found in #{mount.plugin}" unless mount.at.empty? || mount.registry[mount.at]
+            target_ids = mount.registry.children_of(mount.at).keys
+            unknown = Array(mount.only) + Array(mount.except) - target_ids
+            raise ArgumentError, "#{path.inspect}: mount only/except unknown in #{mount.plugin}: #{unknown.inspect}" unless unknown.empty?
+            instance_defined = plugin_class.nil? || instance_method?(plugin_class, mount.instance)
+            raise ArgumentError, "#{path.inspect}: no method #{mount.instance} on #{plugin_class}" unless instance_defined
+            next
           end
 
-          # Rule: delegate_instance requires delegates_to
-          if spec.delegate_instance && spec.delegates_to.nil?
-            raise ArgumentError,
-              "#{path.inspect}: delegate_instance requires delegates_to to be set"
-          end
-
-          # Rule: leaf commands with no explicit action must have a matching instance method
-          next if spec.action # explicit action: skip
           next if @children_index[path]&.any? # intermediate node: skip
-          next if spec.delegates_to # delegated: skip
-          next unless plugin_class
-          implicit_method = CommandSpec.action_method(path)
-          unless plugin_class.method_defined?(implicit_method) || plugin_class.private_method_defined?(implicit_method)
-            raise ArgumentError,
-              "#{path.inspect}: no action: and no method #{implicit_method} on #{plugin_class}"
+          action = spec.action
+          if action.nil?
+            next unless plugin_class
+            # Rule: leaf commands with no explicit action must have a matching instance method
+            action = CommandSpec.action_method(path)
+            unless instance_method?(plugin_class, action)
+              raise ArgumentError,
+                "#{path.inspect}: no action: and no method #{action} on #{plugin_class}"
+            end
           end
+          action = plugin_class.instance_method(action) if action.is_a?(Symbol) && plugin_class && instance_method?(plugin_class, action)
+          # Rule: the action receives the whole dispatch context as keywords (setup results, arguments),
+          # so it must accept any keyword (`**`): a lambda or method with fixed arity would raise ArgumentError.
+          # A non-lambda Proc ignores extra keywords.
+          next if action.is_a?(Symbol) || (action.is_a?(Proc) && !action.lambda?)
+          raise ArgumentError, "#{path.inspect}: action must accept any keyword (**), parameters: #{action.parameters.inspect}" unless action.parameters.any? { |kind, _| kind.eql?(:keyrest) }
         end
         self
       end
 
       private
 
+      # @return [Boolean] true if plugin_class defines instance method name (public or private)
+      def instance_method?(plugin_class, name)
+        plugin_class.method_defined?(name) || plugin_class.private_method_defined?(name)
+      end
+
+      # @param path [Array<Symbol>] non-empty path in this registry's namespace
+      # @return [Array<ArgumentSpec>] arguments of the mount exposing the last segment of path, if any
+      def mount_arguments(path)
+        registry, parent = resolve(path[0..-2])
+        return registry.send(:mount_arguments, parent + [path.last]) unless registry.equal?(self)
+        mount = @specs[parent]&.mount
+        return [] if mount.nil? || @children_index[parent]&.key?(path.last) || !mount.accepts?(path.last)
+        mount.arguments
+      end
+
+      # Identity of the sub-tree exposed at path: the mount point for a mount node, else the owning node.
+      # @return [Array(Integer, Array<Symbol>)]
+      def subtree_key(path)
+        registry, local_path = resolve(path)
+        mount = registry.mount_of(local_path)
+        mount ? [mount.registry.object_id, mount.at] : [registry.object_id, local_path]
+      end
+
       def initialize
         # Keyed by Array<Symbol> full path
         @specs = {}

data/lib/aspera/cli/command_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'aspera/schema/registry'
+require 'aspera/cli/option_types'
 
 module Aspera
   module Cli
@@ -10,7 +11,8 @@ module Aspera
     #
     # @!attribute name        [Symbol]                    Name used in help and error messages
     # @!attribute description [String]                    User-facing description
-    # @!attribute type        [Class, Array<Class>, :identifier] Validated type; :identifier triggers instance_identifier
+    # @!attribute type        [Class, Array<Class>, :identifier, nil] Validated type; :identifier triggers instance_identifier.
+    #                                                     Default: String (unless allowed:); explicit nil accepts any value
     # @!attribute mandatory   [Boolean]                   Default true; optional args must come after all mandatory ones
     # @!attribute multiple    [Boolean, String]           true: consume all remaining; String: consume until named marker
     # @!attribute default     [Object, nil]               Default value when mandatory: false and no argument provided
@@ -41,8 +43,20 @@ module Aspera
         kwargs[:multiple]     = false if kwargs[:multiple].nil?
         kwargs[:bulk]         = false if kwargs[:bulk].nil?
         kwargs[:interactive]  = false if kwargs[:interactive].nil?
+        kwargs[:type]         = String unless kwargs.key?(:type) || kwargs[:allowed]
         super
       end
+
+      # Syntax of argument for help, e.g. `<name>`, `[<name>]`, `<paths...>`, `<account:Hash>`.
+      # Type is shown only when the argument is not free text.
+      # @return [String]
+      def syntax
+        token = allowed ? allowed.join('|') : name.to_s
+        token += '...' if multiple
+        types = Array(type).grep(Class)
+        token += ":#{types.map(&:name).join('|')}" unless allowed || types.empty? || types.include?(String)
+        mandatory ? "<#{token}>" : "[<#{token}>]"
+      end
     end
 
     # Declares an option referenced by name from command declarations.
@@ -54,11 +68,14 @@ module Aspera
     # @!attribute allowed     [Array, nil]           Allowed values (forwarded to options.declare)
     # @!attribute default     [Object, nil]          Default value
     # @!attribute short       [String, nil]          Single-character short form (e.g. 'x')
-    # @!attribute handler     [Symbol, Hash, nil]
-    #   - Symbol: resolved to {o: <plugin instance>, m: <symbol>} at runtime (Category B)
-    #   - Hash:   {o: <object>, m: <method>} used as-is (Category A: singletons / class constants)
-    #   - nil:    option stores its value locally (no delegation)
-    # @!attribute deprecation [String, nil]          Forwarded to options.declare as deprecation:
+    # @!attribute on_set     [Symbol, Proc, #call, nil] Called with the new value each time the value is set
+    #   (for a flag: called without argument when the flag is found)
+    #   - Symbol: method of the plugin instance
+    #   - Proc:   executed with instance_exec on the plugin instance
+    #   - other:  object responding to `call`, e.g. `Log.instance.method(:level=)`
+    #   - nil:    no callback, the value is read with `get_option`
+    # @!attribute shorthand   [String, nil]          For a `Hash` option: a `String` value is stored as `{shorthand => value}`
+    # @!attribute deprecation [Hash, nil]            Forwarded to options.declare as deprecation: `{last:, message:}`
     # @!attribute schema      [String, nil]          JSON schema name; also derives description when nil
     OptionSpec = Struct.new(
       :name,
@@ -66,43 +83,114 @@ module Aspera
       :allowed,
       :default,
       :short,
-      :handler, # kept as-is: this is the option accessor delegation, not a command action
+      :on_set,
+      :shorthand,
       :deprecation,
       :schema,
       keyword_init: true
-    )
+    ) do
+      # Declare this option on a parser, resolving the `on_set` callback.
+      # @param parser [Parser] Parser to declare the option on
+      # @param target [Object, nil] Object for Symbol and Proc `on_set` callbacks (plugin instance); nil: such callbacks are not bound
+      # @return [void]
+      def declare_on(parser, target: nil)
+        parser.declare(
+          name,
+          description: description,
+          short:       short,
+          allowed:     allowed,
+          default:     default,
+          on_set:      resolved_on_set(target),
+          shorthand:   shorthand,
+          deprecation: deprecation,
+          schema:      schema
+        )
+      end
+
+      private
+
+      # @param target [Object, nil] Object for Symbol and Proc `on_set` callbacks
+      # @return [#call, nil] `on_set` callback for `Parser#declare`
+      def resolved_on_set(target)
+        case on_set
+        when Symbol then target&.method(on_set)
+        when Proc
+          return if target.nil?
+          proc_on_set = on_set
+          ->(*value) { target.instance_exec(*value, &proc_on_set) }
+        else on_set
+        end
+      end
+    end
+
+    # Declares that a command node exposes a sub-tree of another plugin class.
+    # The mounted children appear in the host registry (dispatch, --help, completion)
+    # as if they were declared by the host; host children with the same id take precedence.
+    #
+    # @!attribute plugin   [Class]                Target plugin class (subclass of Plugins::Base)
+    # @!attribute at       [Array<Symbol>]        Path in the target registry whose children are mounted ([] = root)
+    # @!attribute instance [Symbol]               Host instance method called with **ctx, returning the target plugin
+    #                                             instance, or [instance, ctx] where ctx seeds the target dispatch
+    #                                             (it replaces what the setups of `at` and its ancestors would provide)
+    # @!attribute only     [Array<Symbol>, nil]   Restrict mounted children to these ids
+    # @!attribute except   [Array<Symbol>, nil]   Exclude these ids from mounted children
+    # @!attribute arguments [Array<ArgumentSpec>] Arguments read by the host after the mounted command, before its own
+    #                                             arguments; resolved values are passed to `instance`
+    #                                             (e.g. `packages ls <package_id> <path>`)
+    MountSpec = Struct.new(
+      :plugin,
+      :at,
+      :instance,
+      :only,
+      :except,
+      :arguments,
+      keyword_init: true
+    ) do
+      def initialize(**kwargs)
+        kwargs[:at] = Array(kwargs[:at]).freeze
+        kwargs[:arguments] = Array(kwargs[:arguments]).map { |a| a.is_a?(Hash) ? ArgumentSpec.new(**a) : a }.freeze
+        super
+      end
+
+      # @return [CommandRegistry] registry of the target plugin class
+      def registry
+        plugin.command_registry
+      end
+
+      # @param id [Symbol] id of a child of `at` in the target registry
+      # @return [Boolean] true if this child is exposed by the mount
+      def accepts?(id)
+        (only.nil? || only.include?(id)) && !except&.include?(id)
+      end
+    end
 
     # Declares a single command node in the flat registry.
     #
     # @!attribute id               [Symbol]                      Unique identifier within its parent's namespace
     # @!attribute parent           [Symbol, Array<Symbol>, nil]  Full path to parent; nil for root commands
     # @!attribute description      [String]                      User-facing help text
-    # @!attribute options          [Array<Symbol>]               Option names consumed by this command
     # @!attribute arguments        [Array<ArgumentSpec>]         Positional arguments, in order.
     #                                                            The first ArgumentSpec with type: :identifier is treated as the instance
     #                                                            identifier for intermediate nodes (consumed in Phase A) and leaf nodes.
     # @!attribute action           [Symbol, Proc, nil]           Instance method (Symbol) or inline block (Proc) called when this is a leaf command
     # @!attribute setup            [Symbol, nil]                 Instance method called before dispatching to children; returns Hash merged into ctx
-    # @!attribute delegates_to     [Symbol, Array<Symbol>, nil]  Re-enter the command tree at this path
-    # @!attribute delegate_instance [Symbol, nil]                Instance method returning a different plugin object
     # @!attribute aliases          [Array<Symbol>, nil] Alternative names accepted for this command (each resolves to this command's id)
     # @!attribute transfer_paths   [:send, :receive, nil]        File-list resolution delegated to TransferAgent; mutually exclusive with arguments
     # @!attribute condition        [Symbol, nil]                 Instance method returning Boolean; if false command is hidden from dispatch
     # @!attribute query_schema     [String, nil]                 Schema path for --query help; when set, the runner hints `--query=help`
+    # @!attribute mount            [MountSpec, Hash, nil]        Expose children of another plugin's registry under this node
     CommandSpec = Struct.new(
       :id,
       :parent,
       :description,
-      :options,
       :arguments,
       :action,
       :setup,
-      :delegates_to,
-      :delegate_instance,
       :aliases,
       :transfer_paths,
       :condition,
       :query_schema,
+      :mount,
       keyword_init: true
     ) do
       def initialize(**kwargs)
@@ -112,6 +200,7 @@ module Aspera
             a.is_a?(Hash) ? ArgumentSpec.new(**a) : a
           end
         end
+        kwargs[:mount] = MountSpec.new(**kwargs[:mount]) if kwargs[:mount].is_a?(Hash)
         super
       end