aspera-cli 4.27.2 → 4.27.4

data/lib/aspera/cli/plugins/base.rb

@@ -6,6 +6,7 @@ require 'aspera/assert'
 require 'aspera/cli/result'
 require 'aspera/cli/command_registry'
 require 'aspera/cli/option_declarator'
+require 'aspera/cli/special_values'
 require 'aspera/schema/registry'
 
 module Aspera
@@ -24,18 +25,24 @@ module Aspera
           ALL = (GLOBAL + INSTANCE).freeze
         end
         class << self
-          # Per-class DSL registry (not inherited: each subclass gets its own instance).
-          # @return [CommandRegistry]
+          include OptionDeclarator
+
+          # Option sources added with `use_options`, with their `on_set` target.
+          # @return [Hash{Class, Module => Proc, nil}]
           def used_option_sources
-            @used_option_sources ||= []
+            @used_option_sources ||= {}
           end
 
           # Include options from another plugin or OptionDeclarator module.
           # @param source [Class, Module]
-          def use_options(source)
-            used_option_sources << source unless used_option_sources.include?(source)
+          # @param target [Proc, nil] Executed on the plugin instance, returns the object for Symbol and Proc `on_set` callbacks
+          #                           of `source` (e.g. `-> { http_config }`); nil: the plugin instance
+          def use_options(source, target: nil)
+            used_option_sources[source] = target unless used_option_sources.key?(source)
           end
 
+          # Per-class DSL registry (not inherited: each subclass gets its own instance).
+          # @return [CommandRegistry]
           def command_registry
             @command_registry ||= CommandRegistry.new
           end
@@ -43,25 +50,50 @@ module Aspera
           # DSL class method: register a command in this plugin's registry.
           # Inherits parent from the enclosing commands_under block when parent: is omitted.
           # @param id [Symbol]
-          # @param kwargs [Hash] forwarded to CommandSpec
+          # @param kwargs [Hash] forwarded to [CommandSpec]
           def command(id, **kwargs)
             kwargs[:parent] = @current_parent if kwargs[:parent].nil? && @current_parent
             command_registry.register(CommandSpec.new(id: id, **kwargs))
           end
 
-          # Derive a display name from an entity path:
-          # last segment after '/', underscores replaced by spaces, first letter capitalized.
-          # e.g. 'data/smtp_server' -> 'Smtp server', 'data/transfer_settings' -> 'Transfer settings'
-          def entity_display_name(entity)
-            entity.to_s.split('/').last.tr('_', ' ').capitalize
+          # Words displayed with specific case in descriptions
+          NOUN_WORDS = {'smtp' => 'SMTP', 'ldap' => 'LDAP', 'saml' => 'SAML', 'oauth' => 'OAuth', 'kms' => 'KMS', 'api' => 'API'}.freeze
+          private_constant :NOUN_WORDS
+
+          # Derive a lowercase noun from an entity path, singular unless told otherwise.
+          # e.g. 'access_keys' -> 'access key', 'data/smtp_server' -> 'SMTP server'
+          # @param entity   [String, Symbol] REST path or entity name
+          # @param singular [Boolean]        Singularize the last word
+          # @return [String]
+          def entity_noun(entity, singular: true)
+            words = entity.to_s.split('/').last.split('_').map { |w| NOUN_WORDS.fetch(w, w) }
+            words[-1] = words[-1].sub(/ies\z/, 'y').sub(/(ss|x|sh|ch)es\z/, '\1').sub(/(?<!s)s\z/, '') if singular
+            words.join(' ')
+          end
+
+          # Standard description of a CRUD operation on an entity.
+          # e.g. (:list, 'access key') -> 'List access keys', (:show, 'access key') -> 'Show access key'
+          # @param verb [Symbol] Operation
+          # @param noun [String] Singular noun of entity
+          # @return [String]
+          def operation_description(verb, noun)
+            return "#{verb.capitalize} #{noun}" unless verb.eql?(:list)
+            plural =
+              case noun
+              when /[^aeiou]y\z/ then noun.sub(/y\z/, 'ies')
+              when /(s|x|sh|ch)\z/ then "#{noun}es"
+              else "#{noun}s"
+              end
+            "List #{plural}"
           end
 
           # DSL class method: declare CRUD commands for a REST entity.
           #
           # For each verb in operations:, registers one CommandSpec with:
-          #   - description: "#{verb.capitalize} #{name}"
-          #   - arguments:   [{name: :id, type: :identifier, lookup: lookup}] for instance verbs
+          #   - description: operation_description(verb, name)
+          #   - arguments:   [{name: id_name, type: :identifier, lookup: lookup}] for instance verbs
           #                  (:show, :modify, :delete) when not a singleton; none for global verbs
+          #                  body of :create and :modify is named after the entity (e.g. <access_key>), passed as data:
           #   - action:      calls entity_<verb>(api:, entity:, **shared_kwargs, **ctx)
           #
           # api: is resolved at runtime: :@ivar -> instance_variable_get, else -> send.
@@ -71,14 +103,23 @@ module Aspera
           # @param api        [Symbol, String] Runtime API ref (:@ivar or method name) or literal string
           # @param entity     [String, Symbol] REST sub-path, or ctx key Symbol resolved at runtime
           # @param operations [Array<Symbol>]  Verbs to expose; defaults to Operations::ALL
-          # @param name       [String, nil]    Display name; defaults to last segment of entity (static only)
+          # @param name       [String, nil]    Singular display name; defaults to last segment of entity (static only)
           # @param lookup     [Symbol, nil]    Instance method for percent-selector resolution
+          # @param id_name    [Symbol, nil]    Name of identifier argument; defaults to <name>_id, or id_as_arg field, or :id
           # @param kwargs     [Hash]           Shared params forwarded to every per-verb method
-          def crud_commands(api:, entity:, operations: nil, name: nil, lookup: nil, **kwargs)
-            name       ||= entity_display_name(entity) unless entity.is_a?(Symbol)
+          def crud_commands(api:, entity:, operations: nil, name: nil, lookup: nil, id_name: nil, **kwargs)
+            name       ||= entity_noun(entity, singular: !kwargs[:is_singleton]) unless entity.is_a?(Symbol)
             operations ||= Operations::ALL
+            # Body argument is named after the entity, e.g. <access_key>, and passed as data: to entity_<verb>
+            data_name = name ? name.downcase.tr(' ', '_').to_sym : :data
+            # Identifier argument is named after the entity, e.g. <access_key_id>, and passed as id: to entity_<verb>
+            id_name ||=
+              if kwargs[:id_as_arg].is_a?(String) then kwargs[:id_as_arg].to_sym
+              elsif name then :"#{data_name}_id"
+              else :id
+              end
             operations.each do |verb|
-              id_arg = ({name: :id, type: :identifier, lookup: lookup} if Operations::INSTANCE.include?(verb) && !kwargs[:is_singleton])
+              id_arg = ({name: id_name, type: :identifier, lookup: lookup} if Operations::INSTANCE.include?(verb) && !kwargs[:is_singleton])
               schema_val =
                 if kwargs[:body_component] && entity.is_a?(String)
                   case verb
@@ -89,9 +130,9 @@ module Aspera
               args =
                 case verb
                 when :create
-                  [{name: :data, type: Hash, bulk: true, schema: schema_val}]
+                  [{name: data_name, type: Hash, bulk: true, schema: schema_val}]
                 when :modify
-                  [id_arg, {name: :data, type: Hash, schema: schema_val}].compact
+                  [id_arg, {name: data_name, type: Hash, schema: schema_val}].compact
                 when :delete
                   id_arg ? [id_arg.merge(bulk: true)] : nil
                 else
@@ -107,10 +148,13 @@ module Aspera
                     api
                   end
                 resolved_entity = entity.is_a?(Symbol) ? ctx.fetch(entity) : entity
+                ctx = ctx.merge(data: ctx[data_name]) if ctx.key?(data_name)
+                ctx = ctx.merge(id: ctx[id_name]) if ctx.key?(id_name)
                 send(:"entity_#{verb}", api: resolved_api, entity: resolved_entity, **kwargs, **ctx)
               end
-              cmd_attrs = {description: "#{verb.capitalize} #{name || entity.inspect}", action: action_proc}
+              cmd_attrs = {description: operation_description(verb, name || entity.inspect), action: action_proc}
               cmd_attrs[:arguments] = args if args
+              cmd_attrs[:query_schema] = Schema::Registry.query_params(kwargs[:query_component], entity) if verb.eql?(:list) && kwargs[:query_component] && entity.is_a?(String)
               command(verb, **cmd_attrs)
             end
           end
@@ -139,7 +183,7 @@ module Aspera
             path = Array(@current_parent) + Array(parent)
             unless command_registry[path]
               id = path.last
-              desc = description || "Manage #{entity_display_name(id)}"
+              desc = description || "Manage #{entity_noun(id, singular: false)}"
               parent_path = path[0..-2]
               saved = @current_parent
               @current_parent = parent_path.empty? ? nil : parent_path
@@ -153,101 +197,56 @@ module Aspera
             @current_parent = previous
           end
 
-          # DSL class method: declare an option in this plugin's registry.
+          # Options of this plugin class (`option` DSL, see OptionDeclarator).
           # Metadata is stored as an OptionSpec at class-load time; the actual
           # options.declare call happens in Base#initialize once the instance exists.
-          #
+          # @return [Hash{Symbol => OptionSpec}]
+          def option_specs
+            command_registry.option_specs
+          end
+
+          # Store an OptionSpec in the command registry.
           # Raises ArgumentError at class-load time if the same option name is already
           # declared by any ancestor class, preventing silent shadowing.
-          #
-          # @param name        [Symbol]          Option name
-          # @param description [String, nil]     User-facing description; if nil, derived from schema: title/description
-          # @param short       [String, nil]     Single-character short form (without leading '-')
-          # @param allowed     [Object, nil]     Allowed values (see OptionValue)
-          # @param default     [Object, nil]     Default value
-          # @param 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 / constants)
-          #   - nil:    option stores its value locally (no delegation)
-          # @param deprecation [String, nil]     Deprecation message forwarded to options.declare
-          # @param schema      [String, nil]     Schema reference (e.g. "opts:components.schemas.Foo");
-          #                                      when description: is nil, the schema title or first description line is used
-          def option(name, description: nil,
-            short: nil, allowed: nil, default: nil,
-            handler: nil, deprecation: nil, schema: nil)
+          # @param spec [OptionSpec]
+          def register_option_spec(spec)
             ancestor_owner = ancestors.drop(1).find do |klass|
               klass.is_a?(Class) && klass <= Base &&
                 klass.instance_variable_defined?(:@command_registry) &&
-                klass.command_registry.option_specs.key?(name)
+                klass.command_registry.option_specs.key?(spec.name)
             end
-            raise ArgumentError, "#{self}: option :#{name} already declared in ancestor #{ancestor_owner}" if ancestor_owner
-            command_registry.register_option(
-              OptionSpec.new(
-                name:        name,
-                description: description,
-                short:       short,
-                allowed:     allowed,
-                default:     default,
-                handler:     handler,
-                deprecation: deprecation,
-                schema:      schema
-              )
-            )
+            raise ArgumentError, "#{self}: option :#{spec.name} already declared in ancestor #{ancestor_owner}" if ancestor_owner
+            command_registry.register_option(spec)
           end
 
-          # Declare all options registered on this plugin class onto a Parser instance.
-          # Walks inherited options and any sources added via `use_options`.
-          # @param options [Aspera::Cli::Parser]
-          # @param parse [Boolean] whether to call parse_options! after declaring
-          def declare_options(options, parse: false)
-            sources = []
+          # Classes and modules whose options apply to this plugin:
+          # this class, its plugin ancestors and sources added via `use_options`.
+          # @return [Hash{Class, Module => Proc, nil}] key responds to `option_specs`, value: `on_set` target (see `use_options`)
+          def option_sources
+            sources = {}
             ancestors.each do |klass|
               next unless klass.is_a?(Class) && klass <= Base
-              sources << klass if klass.instance_variable_defined?(:@command_registry)
-              sources.concat(klass.used_option_sources) if klass.respond_to?(:used_option_sources)
+              sources[klass] = nil if klass.instance_variable_defined?(:@command_registry) && !sources.key?(klass)
+              klass.used_option_sources.each { |src, src_target| sources[src] = src_target unless sources.key?(src) }
             end
-            sources.uniq.each do |src|
-              specs =
-                if src.respond_to?(:command_registry)
-                  src.command_registry.option_specs
-                elsif src.respond_to?(:option_specs)
-                  src.option_specs
-                else
-                  {}
-                end
-              specs.each_value do |spec|
-                next if options.option_declared?(spec.name)
-                resolved_handler =
-                  case spec.handler
-                  when Hash then spec.handler
-                  end
-                options.declare(
-                  spec.name,
-                  description: spec.description,
-                  short:       spec.short,
-                  allowed:     spec.allowed,
-                  default:     spec.default,
-                  handler:     resolved_handler,
-                  deprecation: spec.deprecation,
-                  schema:      spec.schema
-                )
+            sources
+          end
+
+          # Declare all options of `option_sources` onto a Parser instance.
+          # Skips options already declared on the parser: it is shared across all plugins in a run.
+          # @param options [Aspera::Cli::Parser]
+          # @param target  [Base, nil] plugin instance for Symbol and Proc `on_set` callbacks; nil: such callbacks are not bound
+          # @param parse   [Boolean] whether to call parse_options! after declaring
+          def declare_options(options, target: nil, parse: false)
+            option_sources.each do |src, src_target|
+              src_target = src_target.nil? ? target : target&.instance_exec(&src_target)
+              src.option_specs.each_value do |spec|
+                spec.declare_on(options, target: src_target) unless options.option_declared?(spec.name)
               end
             end
             options.parse_options! if parse
           end
 
-          # DSL class method: declare a setup method to run once before root dispatch.
-          # The method is called before any command is consumed, and its return value
-          # (a Hash) is merged into the initial ctx. This is useful when conditions
-          # on root commands depend on state built during setup (e.g. @connection_type).
-          # @param method_name [Symbol]
-          def root_setup(method_name)
-            @root_setup_method = method_name
-          end
-
-          # @return [Symbol, nil]
-          attr_reader :root_setup_method
-
           # DSL class method: declare the human-readable application name shown in wizards.
           # When called with an argument, sets the name. When called with no argument, returns it.
           # Falls back to the last component of the class name if never set.
@@ -289,49 +288,9 @@ module Aspera
           # below (DSL-registered and imperative) appear under the plugin section in
           # --help output, separate from the global options.
           options.group(self.class.name.split('::').last.downcase) if @context.man_header
-          # Auto-declare all options registered via the DSL `option` class method.
-          # Walk the ancestor chain so that options declared on parent plugin classes
-          # (e.g. Oauth, BasicAuth) are also registered for sub-classes (e.g. Aoc).
-          # The options object is shared across all plugins in a run; skip options already
-          # declared by an earlier plugin (Base.option prevents duplicates within one hierarchy).
-          # Each OptionSpec is translated to an options.declare call, resolving the
-          # handler: shorthand:
-          #   Symbol handler: {o: self, m: <symbol>}  (Category B - plugin instance methods)
-          #   Hash handler:   used as-is              (Category A - singletons / class constants)
-          sources = []
-          self.class.ancestors.each do |klass|
-            next unless klass.is_a?(Class) && klass <= Base
-            sources << klass if klass.instance_variable_defined?(:@command_registry)
-            sources.concat(klass.used_option_sources) if klass.respond_to?(:used_option_sources)
-          end
-          sources.uniq.each do |src|
-            specs =
-              if src.respond_to?(:command_registry)
-                src.command_registry.option_specs
-              elsif src.respond_to?(:option_specs)
-                src.option_specs
-              else
-                {}
-              end
-            specs.each_value do |spec|
-              next if options.option_declared?(spec.name)
-              resolved_handler =
-                case spec.handler
-                when Symbol then {o: self, m: spec.handler}
-                when Hash   then spec.handler
-                end
-              options.declare(
-                spec.name,
-                description: spec.description,
-                short:       spec.short,
-                allowed:     spec.allowed,
-                default:     spec.default,
-                handler:     resolved_handler,
-                deprecation: spec.deprecation,
-                schema:      spec.schema
-              )
-            end
-          end
+          # Auto-declare all options registered via the DSL `option` class method,
+          # including those of parent plugin classes (e.g. Oauth, BasicAuth) and `use_options` sources.
+          self.class.declare_options(options, target: self)
         end
 
         # Global objects
@@ -357,46 +316,28 @@ module Aspera
         # @return [Aspera::Cli::TransferProgress, nil]
         def progress_bar; @context.progress_bar; end
 
-        def add_manual_header(_has_options = true)
-          # No-op: the group is set at the start of initialize.
-          # Kept for compatibility with Config, which calls add_manual_header(false) from Runner.
-        end
-
         # Entry point for all DSL-based plugins.
         def execute_action
           @help_path = nil
-          # Validate the registry once per class (memoised by the ivar check).
-          # Passes the plugin class so implicit handler methods can be verified.
-          unless self.class.instance_variable_defined?(:@registry_validated)
-            self.class.command_registry.validate!(plugin_class: self.class)
-            self.class.instance_variable_set(:@registry_validated, true)
-          end
-          # Run the root setup (if declared) before consuming any argument.
-          # This ensures condition methods on root commands can read instance variables
-          # populated by the setup (e.g. @connection_type in server.rb).
-          init_ctx = {}
-          if (rsm = self.class.root_setup_method)
-            init_ctx = send(rsm) || {}
-          end
-          dispatch_from_registry([], init_ctx)
+          validate_registry
+          dispatch_from_registry([])
         end
 
         # Two-phase dispatcher: run setup on the current node (Phase A), then either
         # execute a leaf directly or consume the next argument and recurse (Phase B).
         # @param current_path [Array<Symbol>] path of the node currently being dispatched
         # @param ctx [Hash] accumulated context passed down from parent nodes
-        # @param skip_setup [Boolean] when true, skip Phase A (setup already done by caller)
         # @return [Object] result suitable for CLI output
-        def dispatch_from_registry(current_path, ctx = {}, skip_setup: false)
+        def dispatch_from_registry(current_path, ctx = {})
           registry = self.class.command_registry
           spec     = registry[current_path]
           is_leaf  = spec && registry.children_of(current_path).empty?
 
-          if options.help_requested || skip_setup
+          if @context.help_requested
             # help_requested on an intermediate node: drain positional args without validation
             # so that dispatch_child can still consume the correct sub-command token
-            if !is_leaf && !skip_setup && spec&.arguments
-              spec.arguments.each do |arg_spec|
+            if !is_leaf
+              registry.arguments_at(current_path).each do |arg_spec|
                 next if ctx.key?(arg_spec.name)
                 options.get_next_argument(arg_spec.name.to_s, mandatory: false)
               end
@@ -404,24 +345,7 @@ module Aspera
           else
             # Phase A - for intermediate nodes only: resolve all ArgumentSpec declared on this node
             # before dispatching to children (leaf nodes resolve their arguments inside execute_leaf).
-            if !is_leaf
-              (spec&.arguments || []).each do |arg_spec|
-                next if ctx.key?(arg_spec.name)
-                if arg_spec.type.eql?(:identifier)
-                  lookup_cb = arg_spec.lookup
-                  res_id = if lookup_cb.nil?
-                    options.instance_identifier(description: arg_spec.name.to_s)
-                  elsif lookup_cb.is_a?(Symbol)
-                    options.instance_identifier(description: arg_spec.name.to_s) { |f, v| send(lookup_cb, f, v, **ctx) }
-                  else
-                    options.instance_identifier(description: arg_spec.name.to_s) { |f, v| instance_exec(f, v, **ctx, &lookup_cb) }
-                  end
-                  ctx = ctx.merge(arg_spec.name => res_id)
-                else
-                  ctx = ctx.merge(arg_spec.name => resolve_argument(arg_spec))
-                end
-              end
-            end
+            ctx = resolve_arguments(spec.arguments, ctx) if !is_leaf && spec&.arguments
             ctx = ctx.merge(send(spec.setup, **ctx)) if spec&.setup
           end
 
@@ -440,15 +364,15 @@ module Aspera
         # @param ctx [Hash]
         # @return [Object]
         def dispatch_leaf(current_path, spec, ctx)
-          if options.help_requested
+          if @context.help_requested
             @help_path = current_path
             raise Cli::HelpRequest, self
           end
           execute_leaf(spec, ctx)
         end
 
-        # Phase B, child branch: consume the next command argument, resolve the matching
-        # child spec, handle delegation, and recurse or execute.
+        # Phase B, child branch: consume the next command argument, then either continue
+        # on a mounted plugin instance, or recurse into the child.
         # --help is intercepted at two points:
         #   1. Before get_next_command when no positional arg is pending: raises HelpRequest
         #      immediately so the subcommand list with descriptions is shown rather than a
@@ -461,37 +385,64 @@ module Aspera
         # @return [Object]
         def dispatch_child(current_path, registry, ctx)
           children  = registry.children_of(current_path)
-          available = children.reject { |_, c| c.condition && !send(c.condition) }
-          aliases   = children.values.each_with_object({}) do |c, h|
+          # condition: methods belong to the class declaring the spec: only evaluate local ones
+          # (mounted children are only walked here for --help, see below).
+          # With --help, conditions are not evaluated: they may need the API, which is not built for help.
+          available = children.reject { |id, c| c.condition && !@context.help_requested && registry.local?(current_path + [id]) && !send(c.condition) }
+          # Aliases of available commands only: an alias must not bypass the condition of its command
+          aliases   = available.values.each_with_object({}) do |c, h|
             Array(c.aliases).each { |a| h[a] = c.id } if c.aliases
           end
 
           # Intercept --help before consuming the command token when no arg is pending.
           # This avoids MissingArgument being raised by get_next_command before HelpRequest.
-          if options.help_requested && options.command_or_arg_empty?
+          if @context.help_requested && options.command_or_arg_empty?
             @help_path = current_path
             raise Cli::HelpRequest, self
           end
 
           command = options.get_next_command(available.keys, aliases: aliases.empty? ? nil : aliases)
-          child   = available[command]
 
           # Intercept --help after a command was consumed but no further args remain.
           # (e.g. `aoc files find -h`). When further args remain, keep recursing.
-          if options.help_requested && options.command_or_arg_empty?
+          if @context.help_requested && options.command_or_arg_empty?
             @help_path = current_path + [command]
             raise Cli::HelpRequest, self
           end
 
-          # Instance delegation: hand off to a different plugin object
-          if child.delegate_instance
-            target = send(child.delegate_instance)
-            return target.dispatch_from_registry(Array(child.delegates_to), {})
-          end
-          return dispatch_from_registry(Array(child.delegates_to), ctx) if child.delegates_to
+          # Mounted child: continue on the target plugin instance, in its own namespace.
+          # For --help, keep walking the (mount-aware) registry of this class instead, so that
+          # no target instance (and thus no API connection) is needed.
+          child_path = current_path + [command]
+          return dispatch_mount(registry.mount_of(current_path), command, ctx) unless @context.help_requested || registry.local?(child_path)
+
+          # Both intermediate and leaf: arguments + setup are handled by Phase A of the next call
+          dispatch_from_registry(child_path, ctx)
+        end
 
-          # Both intermediate and leaf: instance_arg + setup are handled by Phase A of the next call
-          dispatch_from_registry(current_path + [command], ctx)
+        # Hand over dispatch of a mounted child to the target plugin instance.
+        # Setups of the mount point `at` and of its ancestors in the target are not executed:
+        # the seed ctx returned by the host's `instance` method replaces them.
+        # The mount's own arguments (if any) are read first, and passed to `instance` in ctx.
+        # @param mount   [MountSpec]
+        # @param command [Symbol] mounted child id, already consumed
+        # @param ctx     [Hash]   host context, passed to the `instance` method
+        # @return [Object]
+        def dispatch_mount(mount, command, ctx)
+          ctx = resolve_arguments(mount.arguments, ctx)
+          target = send(mount.instance, **ctx)
+          target, seed = target if target.is_a?(Array)
+          Aspera.assert_type(target, mount.plugin)
+          target.validate_registry
+          target.dispatch_from_registry(mount.at + [command], seed || {})
+        end
+
+        # Validate the registry once per class (memoised by the ivar check).
+        # Passes the plugin class so implicit action methods can be verified.
+        def validate_registry
+          return if self.class.instance_variable_defined?(:@registry_validated)
+          self.class.command_registry.validate!(plugin_class: self.class)
+          self.class.instance_variable_set(:@registry_validated, true)
         end
 
         # Resolve the action for a leaf CommandSpec.
@@ -520,10 +471,8 @@ module Aspera
         end
 
         # Execute a leaf CommandSpec: resolve arguments and call action.
-        # Arguments already present in +ctx+ (pre-resolved by a parent plugin, e.g. aoc.rb forwarding
-        # path: into execute_nodegen4_command) are skipped — the token has already been consumed.
-        # instance_arg (if any) is resolved here as an ArgumentSpec(type: :identifier) and merged
-        # into ctx, exactly like any other keyword argument received by the action.
+        # Arguments already present in `ctx` (e.g. provided by a caller or a mount seed) are skipped:
+        # they are not read again from the command line.
         # @param spec [CommandSpec] a leaf node (no children)
         # @param ctx  [Hash]        accumulated context (pre-resolved keys are not re-consumed)
         # @return [Object]
@@ -531,25 +480,40 @@ module Aspera
           a = action_for(spec)
           # Always resolve declared arguments (even when transfer_paths is set — those arguments
           # are consumed first; ts_source_paths then reads whatever remains in the queue).
-          (spec.arguments || []).each do |arg_spec|
-            next if ctx.key?(arg_spec.name)
-            if arg_spec.type.eql?(:identifier)
-              lookup_cb = arg_spec.lookup
-              block =
-                if lookup_cb.nil? then nil
-                elsif lookup_cb.is_a?(Symbol) then ->(f, v) { send(lookup_cb, f, v, **ctx) }
-                else ->(f, v) { instance_exec(f, v, **ctx, &lookup_cb) }
-                end
-              ctx = ctx.merge(arg_spec.name => resolve_argument(arg_spec, &block))
-            else
-              ctx = ctx.merge(arg_spec.name => resolve_argument(arg_spec))
+          ctx = resolve_arguments(spec.arguments, ctx) if spec.arguments
+          invoke_action(a, [], ctx)
+        end
+
+        # Resolve positional arguments from the CLI argument stream, in order.
+        # Arguments already present in `ctx` (e.g. injected by a setup method) are not read from the command line.
+        # If the next CLI argument is that same value, or `ALL`, it is skipped, so that it is not mistaken for a later argument
+        # (e.g. `faspex5 packages receive ALL` with a public link to a package).
+        # For type: :identifier, the percent-selector lookup receives the ctx accumulated so far.
+        # @param arg_specs [Array<ArgumentSpec>]
+        # @param ctx       [Hash] accumulated context
+        # @return [Hash] ctx merged with the resolved arguments
+        def resolve_arguments(arg_specs, ctx)
+          arg_specs.each do |arg_spec|
+            if ctx.key?(arg_spec.name)
+              options.get_next_argument(arg_spec.name.to_s, mandatory: false) if options.next_argument_in?([ctx[arg_spec.name].to_s, SpecialValues::ALL])
+              next
             end
+            lookup_cb = arg_spec.lookup if arg_spec.type.eql?(:identifier)
+            current = ctx
+            block =
+              case lookup_cb
+              when nil    then nil
+              when Symbol then ->(f, v) { send(lookup_cb, f, v, **current) }
+              else ->(f, v) { instance_exec(f, v, **current, &lookup_cb) }
+              end
+            ctx = ctx.merge(arg_spec.name => resolve_argument(arg_spec, &block))
           end
-          invoke_action(a, [], ctx)
+          ctx
         end
 
         # Resolve a single positional argument from the CLI argument stream.
         # When arg_spec.bulk is true, always returns an Array (normalized to [value] when non-bulk).
+        # Only such arguments are read as a list with `--bulk=yes`: others (e.g. the id of a parent node) are single values.
         # For type: :identifier, an optional block provides the percent-selector lookup.
         # @param arg_spec [ArgumentSpec]
         # @yieldparam field [String]  field name from a percent-selector (%field:value)
@@ -560,7 +524,7 @@ module Aspera
           if arg_spec.bulk
             is_bulk = options.get_option(:bulk)
             if arg_spec.type.eql?(:identifier)
-              val = options.instance_identifier(description: arg_spec.name.to_s, &block)
+              val = options.instance_identifier(description: arg_spec.name.to_s, multiple: is_bulk, &block)
             else
               val = options.get_next_argument(
                 arg_spec.name.to_s,
@@ -581,19 +545,19 @@ module Aspera
               options.instance_identifier(description: arg_spec.name.to_s, &block)
             else
               # Class or Array<Class> -> pass as validation type
-              # When interactive: true, set ask_missing_mandatory so that get_interactive is triggered
-              # when no CLI arguments are provided (mandatory is forced to true for the same reason:
-              # a non-nil default would short-circuit get_interactive before it is ever called).
-              options.ask_missing_mandatory = true if arg_spec.interactive
-              options.get_next_argument(
-                arg_spec.name.to_s,
-                mandatory:   arg_spec.interactive ? true : arg_spec.mandatory,
-                multiple:    arg_spec.multiple || false,
-                validation:  arg_spec.type,
-                accept_list: arg_spec.allowed,
-                default:     arg_spec.interactive ? nil : arg_spec.default,
-                schema:      arg_spec.schema
-              )
+              # When interactive: true, prompt for this argument only when no CLI argument is provided
+              # (mandatory is forced to true and default ignored: a non-nil default would short-circuit the prompt).
+              options.with_interactive(enabled: arg_spec.interactive) do
+                options.get_next_argument(
+                  arg_spec.name.to_s,
+                  mandatory:   arg_spec.interactive ? true : arg_spec.mandatory,
+                  multiple:    arg_spec.multiple || false,
+                  validation:  arg_spec.type,
+                  accept_list: arg_spec.allowed,
+                  default:     arg_spec.interactive ? nil : arg_spec.default,
+                  schema:      arg_spec.schema
+                )
+              end
             end
           end
         end
@@ -603,17 +567,18 @@ module Aspera
         # @param path [Array<Symbol>] starting path ([] for the full tree)
         # @return [Hash] { command_id => { description:, condition:, children: } }
         def generate_help(path = [])
-          self.class.command_registry.children_of(path).transform_values do |child_spec|
+          self.class.command_registry.children_of(path).to_h do |id, child_spec|
             annotation = child_spec.condition ? " [#{child_spec.condition}]" : ''
-            {
+            # path + [id], not child_spec.full_path: a mounted spec's full_path is in the target namespace
+            [id, {
               description: "#{child_spec.description}#{annotation}",
               condition:   child_spec.condition,
-              children:    generate_help(child_spec.full_path)
-            }
+              children:    generate_help(path + [id])
+            }]
           end
         end
 
-        # Convenience wrapper: reads :bulk and :bfail from options, normalises +items+
+        # Convenience wrapper: reads :bulk and :bfail from options, normalizes `items`
         # to an Array, then delegates to Result.bulk.
         # Use this in action methods instead of the three-line boilerplate:
         #   is_bulk = options.get_option(:bulk)
@@ -623,7 +588,7 @@ module Aspera
         # @param command   [Symbol]         Operation name (:create, :delete, ...)
         # @param id_result [String]         Key used as item identifier in the result row
         # @param fields    [Object]         Fields hint passed to Result constructor (non-bulk only)
-        # @yieldparam item [Object]         Each item in +items+
+        # @yieldparam item [Object]         Each item in `items`
         # @return [Result::ObjectList, Result::SingleObject]
         def bulk_result(items, command:, id_result: 'id', fields: :default, &block)
           items = items.is_a?(Array) ? items : [items]
@@ -645,7 +610,7 @@ module Aspera
         # NOT read from the CLI queue inside the method.
 
         # List all instances of an entity.
-        # @param api             [Aspera::Rest]  REST API object
+        # @param api             [Aspera::Rest::Client]  REST API object
         # @param entity          [String]        API sub-path
         # @param display_fields  [Array, nil]    Fields to display
         # @param items_key       [String, nil]   Sub-key in response containing the array
@@ -655,12 +620,14 @@ module Aspera
           qs_path = query_component ? Schema::Registry.query_params(query_component, entity) : nil
           data, http = api.read(entity, query_read_delete(default: list_query, schema: qs_path), ret: :both)
           return Result::Empty.new if http.code == '204'
-          # TODO: not generic : which application is this for ?
-          if http['Content-Type'].start_with?('application/vnd.api+json')
-            Log.log.debug('is vnd.api')
+          if !data.is_a?(Hash)
+            # already the list
+          elsif items_key
+            data = data[items_key]
+          elsif http['Content-Type'].start_with?(Mime::JSON_API)
+            # JSON:API: list is under the entity name
             data = data[entity]
           end
-          data = data[items_key] if items_key
           case data
           when Hash then Result::SingleObject.new(data, fields: display_fields)
           when Array
@@ -671,7 +638,7 @@ module Aspera
         end
 
         # Show one instance of an entity.
-        # @param api            [Aspera::Rest]    REST API object
+        # @param api            [Aspera::Rest::Client]    REST API object
         # @param entity         [String]          API sub-path
         # @param id             [String, nil]     Resource identifier; nil when is_singleton: true
         # @param display_fields [Array, nil]      Fields to display
@@ -683,43 +650,32 @@ module Aspera
         end
 
         # Create one or more instances of an entity (supports bulk).
-        # @param api            [Aspera::Rest]  REST API object
-        # @param entity         [String]        API sub-path
-        # @param display_fields [Array, nil]    Fields to display
-        # @param body_component [String, nil]   Registry key for request body schema
-        # @param input_data     [Array, nil]    Pre-resolved data; when nil, read from CLI
-        def entity_create(api:, entity:, display_fields: nil, body_component: nil, input_data: nil, data: nil, **)
-          schema = body_component ? Schema::Registry.req_body(body_component, "#{entity}.post") : nil
-          input_data ||= data
-          unless input_data
-            is_bulk = options.get_option(:bulk)
-            raw = options.get_next_argument('data', validation: is_bulk ? Array : Hash, schema: schema)
-            input_data = is_bulk ? raw : [raw]
-          end
-          input_data = [input_data] unless input_data.is_a?(Array)
-          bulk_result(input_data, command: :create, fields: display_fields) do |params|
+        # @param api            [Aspera::Rest::Client]      REST API object
+        # @param entity         [String]            API sub-path
+        # @param data           [Hash, Array<Hash>] Entity data (Array with bulk), from the command's declared `data` argument
+        # @param display_fields [Array, nil]        Fields to display
+        def entity_create(api:, entity:, data:, display_fields: nil, **)
+          data = [data] unless data.is_a?(Array)
+          bulk_result(data, command: :create, fields: display_fields) do |params|
             api.create(entity, params)
           end
         end
 
         # Modify an existing instance of an entity.
-        # @param api            [Aspera::Rest]    REST API object
+        # @param api            [Aspera::Rest::Client]    REST API object
         # @param entity         [String]          API sub-path
         # @param id             [String, nil]     Resource identifier; nil when is_singleton: true
         # @param is_singleton   [Boolean]         When true, entity is the full path (no id appended)
         # @param id_as_arg      [Boolean, String] When set, id is appended as ?<id_as_arg>=<id>
-        # @param body_component [String, nil]     Registry key for request body schema
-        # @param input_data     [Hash, nil]       Pre-resolved data; when nil, read from CLI
-        def entity_modify(api:, entity:, id: nil, is_singleton: false, id_as_arg: false, body_component: nil, input_data: nil, data: nil, **)
-          schema = body_component ? Schema::Registry.req_body(body_component, "#{entity}/{id}.put") : nil
+        # @param data           [Hash]            Modified fields, from the command's declared `data` argument
+        def entity_modify(api:, entity:, data:, id: nil, is_singleton: false, id_as_arg: false, **)
           path = entity_res_path(entity, id, is_singleton: is_singleton, id_as_arg: id_as_arg)
-          parameters = input_data || data || options.get_next_argument('data', validation: Hash, schema: schema)
-          api.update(path, parameters)
+          api.update(path, data)
           Result::Status.new('modified')
         end
 
         # Delete one or more instances of an entity (supports bulk).
-        # @param api             [Aspera::Rest]    REST API object
+        # @param api             [Aspera::Rest::Client]    REST API object
         # @param entity          [String]          API sub-path
         # @param id              [String, Array, nil] Resource identifier(s)
         # @param id_as_arg       [Boolean, String] When set, id is appended as ?<id_as_arg>=<id>