aspera-cli 4.26.1 → 4.27.0

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

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require 'aspera/cli/extended_value'
+require 'aspera/cli/parser'
 require 'aspera/assert'
+require 'aspera/cli/result'
+require 'aspera/cli/command_registry'
+require 'aspera/schema/registry'
 
 module Aspera
   module Cli
@@ -19,25 +23,168 @@ module Aspera
           ALL = (GLOBAL + INSTANCE).freeze
         end
         class << self
-          def declare_options(options)
-            options.declare(:query, 'Additional filter for for some commands (list/delete)', allowed: [Hash, Array, NilClass])
-            options.declare(:bulk, 'Bulk operation (only some)', allowed: Allowed::TYPES_BOOLEAN, default: false)
-            options.declare(:bfail, 'Bulk operation error handling', allowed: Allowed::TYPES_BOOLEAN, default: true)
+          # Per-class DSL registry (not inherited: each subclass gets its own instance).
+          # @return [CommandRegistry]
+          def command_registry
+            @command_registry ||= CommandRegistry.new
+          end
+
+          # 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
+          def command(id, **kwargs)
+            kwargs[:parent] = @current_parent if kwargs[:parent].nil? && @current_parent
+            command_registry.register(CommandSpec.new(id: id, **kwargs))
+          end
+
+          # DSL class method: shorthand for a command whose sole action is Base#entity_execute.
+          # The api: value is a Symbol resolved at runtime: if it starts with '@' it is treated
+          # as an instance variable name; otherwise it is sent as a method call.
+          # description: defaults to "Manage <last segment of entity path>" when omitted.
+          # @param id          [Symbol]        Command identifier
+          # @param api         [Symbol]        Method name or :@ivar returning the REST API at runtime
+          # @param entity      [String]        API sub-path (e.g. 'admin/dropboxes')
+          # @param description [String, nil]   User-facing help text; derived from entity when nil
+          # @param kwargs      [Hash]          Any other entity_execute params (display_fields:, command:, is_singleton:, etc.)
+          def entity_command(id, api:, entity:, description: nil, **kwargs)
+            description ||= "Manage #{entity.split('/').last}"
+            command(id, description: description, entity_execute: {api: api, entity: entity, **kwargs})
+          end
+
+          # DSL class method: define an instance method whose name is derived from a path array.
+          # Equivalent to: define_method(CommandSpec.action_method(path), &block)
+          # @param path [Array<Symbol>] command path segments, e.g. [:admin, :user, :list]
+          # @yieldparam [Hash] keyword context forwarded from dispatch
+          def define_action_method(path, &block)
+            define_method(CommandSpec.action_method(path), &block)
+          end
+
+          # DSL class method: scope block that sets a default parent for nested command() calls.
+          # Fully re-entrant: blocks may be nested for multi-level parent paths.
+          # @param parent [Symbol, Array<Symbol>] parent path applied to every command() inside
+          # @yieldreturn [void]
+          def commands_under(parent)
+            previous = @current_parent
+            @current_parent = parent
+            yield
+          ensure
+            @current_parent = previous
+          end
+
+          # DSL class method: declare an option in this plugin's registry.
+          # Metadata is stored as an OptionSpec at class-load time; the actual
+          # options.declare call happens in Base#initialize once the instance exists.
+          #
+          # 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)
+            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)
+            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
+              )
+            )
+          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.
+          # @param name [String, nil]
+          # @return [String]
+          def application_name(name = nil)
+            @application_name = name unless name.nil?
+            @application_name || self.name.split('::').last
           end
         end
 
+        option :query, description: 'Additional filter for for some commands (list/delete)', allowed: [Hash, Array, NilClass]
+        option :bulk,  description: 'Bulk operation (only some)',                            allowed: Allowed::TYPES_BOOLEAN, default: false
+        option :bfail, description: 'Bulk operation error handling',                         allowed: Allowed::TYPES_BOOLEAN, default: true
+
         def initialize(context:)
-          # Check presence in descendant of mandatory method and constant
-          Aspera.assert(respond_to?(:execute_action), type: InternalError){"Missing method 'execute_action' in #{self.class}"}
-          Aspera.assert(self.class.const_defined?(:ACTIONS), type: InternalError){"Missing constant 'ACTIONS' in #{self.class}"}
+          Aspera.assert_type(context, Context){'context'}
+          Aspera.assert_type(context.man_header, TrueClass, FalseClass){'context.man_header'}
           @context = context
+          # 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)
+          self.class.ancestors.each do |klass|
+            next unless klass.is_a?(Class) && klass <= Base && klass.instance_variable_defined?(:@command_registry)
+            klass.command_registry.option_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
           add_manual_header if @context.man_header
         end
 
         # Global objects
         attr_reader :context
+        # Path reached in the command tree at the moment --help was intercepted.
+        # Nil until set by dispatch_from_registry.
+        attr_reader :help_path
 
-        # @return [Aspera::Cli::Manager]
+        # @return [Aspera::Cli::Parser]
         def options; @context.options; end
         # @return [Aspera::Cli::TransferAgent]
         def transfer; @context.transfer; end
@@ -47,63 +194,274 @@ module Aspera
         def formatter; @context.formatter; end
         # @return [Aspera::PersistencyFolder]
         def persistency; @context.persistency; end
+        # @return [Aspera::Cli::PresetManager]
+        def presets; @context.presets; end
+        # @return [Aspera::Cli::Http]
+        def http_config; @context.http_config; end
+        # @return [Aspera::Cli::TransferProgress, nil]
+        def progress_bar; @context.progress_bar; end
 
-        def add_manual_header(has_options = true)
-          # Manual header for all plugins
-          options.parser.separator('')
-          options.parser.separator("COMMAND: #{self.class.name.split('::').last.downcase}")
-          options.parser.separator("SUBCOMMANDS: #{self.class.const_get(:ACTIONS).map(&:to_s).sort.join(' ')}")
-          options.parser.separator('OPTIONS:') if has_options
-        end
-
-        # For create and delete operations: execute one action or multiple if bulk is yes
-        # @param command [Symbol] Operation: :create, :delete, ...
-        # @param descr [String, nil] Description of the value
-        # @param values [Class, Array, Symbol] Type, or list of values, or :identifier, result is given to the block in loop
-        # @param id_result [String] Key in result Hash to use as identifier
-        # @param fields [Symbol, Array] Fields to display
-        # @param schema [Hash, nil] JSON schema for validation
-        # @yieldparam param [Object] The parameter value to process
-        # @yieldreturn [Hash, nil] Result hash for the operation (optional)
-        # @return [Hash] Result suitable for CLI output
-        def do_bulk_operation(command:, descr: nil, values: Hash, id_result: 'id', fields: :default, schema: nil, &block)
-          Aspera.assert(block_given?){'missing block'}
-          is_bulk = options.get_option(:bulk)
-          case values
-          when :identifier
-            values = options.instance_identifier(description: descr)
-          when Class
-            values = value_create_modify(command: command, description: descr, type: values, bulk: is_bulk, schema: schema)
-          end
-          # If not bulk, there is a single value
-          params = is_bulk ? values : [values]
-          Log.log.warn('Empty list given for bulk operation') if params.empty?
-          Log.dump(:bulk_operation, params)
-          result_list = []
-          params.each do |param|
-            # Init for delete
-            result = {id_result => param}
-            begin
-              # Execute custom code
-              res = yield(param)
-              # If block returns a hash, let's use this (create)
-              result = res if res.is_a?(Hash)
-              # TODO: remove when faspio gw api fixes this
-              result = res.first if res.is_a?(Array) && res.first.is_a?(Hash)
-              # Create -> created
-              result['status'] = "#{command}#{'e' unless command.to_s.end_with?('e')}d".gsub(/yed$/, 'ied')
-            rescue StandardError => e
-              raise e if options.get_option(:bfail)
-              result['status'] = e.to_s
+        def add_manual_header(_has_options = true)
+          options.rename_current_group(self.class.name.split('::').last.downcase)
+        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)
+        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)
+          registry = self.class.command_registry
+          spec     = registry[current_path]
+          is_leaf  = spec && registry.children_of(current_path).empty?
+
+          if options.help_requested || skip_setup
+            # 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|
+                next if ctx.key?(arg_spec.name)
+                options.get_next_argument(arg_spec.name.to_s, mandatory: false)
+              end
             end
-            result_list.push(result)
+          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_method = arg_spec.lookup
+                  res_id = if lookup_method
+                    options.instance_identifier(description: arg_spec.name.to_s){ |f, v| send(lookup_method, f, v, **ctx)}
+                  else
+                    options.instance_identifier(description: arg_spec.name.to_s)
+                  end
+                  ctx = ctx.merge(arg_spec.name => res_id)
+                else
+                  ctx = ctx.merge(arg_spec.name => resolve_argument(arg_spec))
+                end
+              end
+            end
+            ctx = ctx.merge(send(spec.setup, **ctx)) if spec&.setup
           end
-          display_fields = [id_result, 'status']
-          if is_bulk
-            return Main.result_object_list(result_list, fields: display_fields)
+
+          # Phase B - leaf fast-path or child dispatch
+          if is_leaf
+            dispatch_leaf(current_path, spec, ctx)
           else
-            display_fields = fields unless fields.eql?(:default)
-            return Main.result_single_object(result_list.first, fields: display_fields)
+            dispatch_child(current_path, registry, ctx)
+          end
+        end
+
+        # Phase B, leaf branch: execute a spec that is already a leaf (no children).
+        # Intercepts --help before calling execute_leaf.
+        # @param current_path [Array<Symbol>]
+        # @param spec [CommandSpec]
+        # @param ctx [Hash]
+        # @return [Object]
+        def dispatch_leaf(current_path, spec, ctx)
+          if options.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 / entity_execute shorthands, and recurse or execute.
+        # @param current_path [Array<Symbol>]
+        # @param registry [CommandRegistry]
+        # @param ctx [Hash]
+        # @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|
+            Array(c.aliases).each{ |a| h[a] = c.id} if c.aliases
+          end
+          command = options.get_next_command(available.keys, aliases: aliases.empty? ? nil : aliases)
+          child   = available[command]
+
+          # Intercept --help when no more positional args remain after consuming this command.
+          # (e.g. `aoc files -h` or `aoc files find -h`). When args remain, keep recursing.
+          if options.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
+
+          # entity_execute shorthand
+          return run_entity_execute(child, ctx) if child.entity_execute
+
+          # Both intermediate and leaf: instance_arg + setup are handled by Phase A of the next call
+          dispatch_from_registry(current_path + [command], ctx)
+        end
+
+        # Resolve the action for a leaf CommandSpec.
+        # Returns spec.action (Symbol or Proc) if explicitly set; otherwise derives a Symbol
+        # from the full path as :action_<path_segment_1>_<path_segment_2>_...
+        # (e.g. [:access_key, :list] -> :action_access_key_list).
+        # @param spec [CommandSpec]
+        # @return [Symbol, Proc]
+        def action_for(spec)
+          spec.action || spec.action_method_name
+        end
+
+        # Invoke an action (Symbol method or Proc block) with the given positional
+        # arguments and keyword context.
+        # Procs are executed via instance_exec so they share the plugin's `self`.
+        # @param action [Symbol, Proc]
+        # @param args   [Array]  positional arguments
+        # @param ctx    [Hash]   keyword context
+        # @return [Object]
+        def invoke_action(action, args, ctx)
+          if action.is_a?(Proc)
+            instance_exec(*args, **ctx, &action)
+          else
+            send(action, *args, **ctx)
+          end
+        end
+
+        # Execute a leaf CommandSpec: resolve arguments (or skip for transfer_paths) and call action.
+        # 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.
+        # @param spec [CommandSpec] a leaf node (no children)
+        # @param ctx  [Hash]        accumulated context
+        # @return [Object]
+        def execute_leaf(spec, ctx)
+          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|
+            if arg_spec.type.eql?(:identifier)
+              unless ctx.key?(arg_spec.name)
+                lookup_method = arg_spec.lookup
+                block = lookup_method ? ->(f, v){send(lookup_method, f, v, **ctx)} : nil
+                ctx = ctx.merge(arg_spec.name => resolve_argument(arg_spec, &block))
+              end
+            else
+              ctx = ctx.merge(arg_spec.name => resolve_argument(arg_spec))
+            end
+          end
+          invoke_action(a, [], ctx)
+        end
+
+        # Expand an entity_execute shorthand from a CommandSpec.
+        # Calls Base#entity_execute with the parameters from spec.entity_execute merged
+        # with the context hash (context entries are low-priority: spec params win).
+        # @param spec [CommandSpec] the command spec carrying entity_execute: Hash
+        # @param ctx [Hash] accumulated context (e.g. api:, lookup block)
+        # @return [Object]
+        def run_entity_execute(spec, ctx)
+          ee_params = spec.entity_execute.dup
+          # Resolve api: Symbol at runtime: :@ivar -> instance_variable_get, :method -> send
+          if (api_ref = ee_params[:api]).is_a?(Symbol)
+            ee_params[:api] = if api_ref.to_s.start_with?('@')
+              instance_variable_get(api_ref)
+            else
+              send(api_ref)
+            end
+          end
+          # Merge context into params (spec wins on key collision)
+          merged = ctx.merge(ee_params)
+          # Extract lookup_block before passing to entity_execute (it is not a kwarg of entity_execute)
+          block = merged.delete(:lookup_block)
+          if block
+            entity_execute(**merged, &block)
+          else
+            entity_execute(**merged)
+          end
+        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).
+        # 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)
+        # @yieldparam value [String]  value from a percent-selector
+        # @yieldreturn [String]       resolved identifier
+        # @return [Object] the resolved value, or Array when arg_spec.bulk is true
+        def resolve_argument(arg_spec, &block)
+          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)
+            else
+              val = options.get_next_argument(
+                arg_spec.name.to_s,
+                mandatory: arg_spec.mandatory,
+                validation: is_bulk ? Array : arg_spec.type,
+                default:   arg_spec.default,
+                schema:    arg_spec.schema
+              )
+              if is_bulk
+                Aspera.assert_array_all(val, arg_spec.type, type: Cli::BadArgument){'type'} unless arg_spec.type.nil?
+              end
+            end
+            # Always return an Array when bulk: true
+            is_bulk ? val : [val]
+          else
+            case arg_spec.type
+            when :identifier
+              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
+              )
+            end
+          end
+        end
+
+        # Build a nested Hash tree of the registered command tree for help display.
+        # Conditional commands are included with a '[condition_name]' annotation.
+        # @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|
+            annotation = child_spec.condition ? " [#{child_spec.condition}]" : ''
+            {
+              description: "#{child_spec.description}#{annotation}",
+              condition:   child_spec.condition,
+              children:    generate_help(child_spec.full_path)
+            }
           end
         end
 
@@ -111,13 +469,24 @@ module Aspera
         # @param api [Aspera::Rest] API to use
         # @param entity [String] Sub path in URL to resource relative to base url
         # @param command [Symbol, nil] Command to execute: :create, :show, :list, :modify, :delete
+        #   When nil, reads the next command token from the CLI (fallback, deprecated).
         # @param display_fields [Array, nil] Fields to display by default
         # @param items_key [String, nil] Result is in a sub key of the JSON
         # @param delete_style [String, nil] If set, the delete operation by array in payload
         # @param id_as_arg [Boolean, String] If set, the id is provided as url argument ?<id_as_arg>=<id>
         # @param is_singleton [Boolean] If `true`, entity is the full path to the resource
         # @param list_query [Hash, nil] Query parameters for list operation
-        # @yieldparam value [String] Value to search for identifier
+        # @param schema [String, nil] JSON schema name for create/modify validation
+        # @param query_component [String, nil] Registry component key (e.g. 'faspex', 'aoc') used to derive
+        #   the query parameters schema path from the entity name. When set, `--query=help` on list/delete
+        #   commands displays the available filter parameters from the OpenAPI spec.
+        # @param input_data [Array, Hash, nil] Pre-resolved data for :create (Array) or :modify (Hash).
+        #   When nil, data is read from the CLI (fallback, deprecated).
+        # @param res_id [String, Array, nil] Pre-resolved resource identifier(s) for instance commands.
+        #   When nil, identifier is read from the CLI (fallback, deprecated).
+        # @param is_bulk [Boolean] Whether operation runs in bulk mode (used when data: is provided)
+        # @param bfail [Boolean] When false, errors are captured as status strings instead of re-raised
+        # @yieldparam value [String] Value to search for identifier (lookup block)
         # @yieldreturn [String] The identifier
         # @return [Hash] Result suitable for CLI result
         def entity_execute(
@@ -130,25 +499,44 @@ module Aspera
           id_as_arg: false,
           is_singleton: false,
           list_query: nil,
+          schema: nil,
+          query_component: nil,
+          input_data: nil,
+          res_id: nil,
+          is_bulk: false,
+          bfail: true,
           &block
         )
+          # Fallback: read command from CLI when not provided (entity_command shorthand without command:)
           command = options.get_next_command(Operations::ALL) if command.nil?
+          # Derive query schema path from component + entity when component is given
+          qs_path = query_component ? Schema::Registry.query_params(query_component, entity) : nil
+
           if is_singleton
             one_res_path = entity
           elsif Operations::INSTANCE.include?(command)
-            one_res_id = options.instance_identifier(&block)
+            # Use pre-resolved identifier if provided; otherwise fall back to CLI read (entity_command shorthand)
+            one_res_id = res_id || options.instance_identifier(&block)
             one_res_path = "#{entity}/#{one_res_id}"
             one_res_path = "#{entity}?#{id_as_arg}=#{one_res_id}" if id_as_arg
           end
 
           case command
           when :create
-            raise BadArgument, 'cannot create singleton' if is_singleton
-            return do_bulk_operation(command: command, descr: 'data', fields: display_fields) do |params|
+            Aspera.assert(!is_singleton, type: BadArgument){'cannot create singleton'}
+            unless input_data
+              # No pre-resolved data: read from CLI
+              cli_is_bulk = options.get_option(:bulk)
+              raw = options.get_next_argument('data', validation: cli_is_bulk ? Array : Hash, schema: schema)
+              input_data = cli_is_bulk ? raw : [raw]
+              is_bulk  = cli_is_bulk
+              bfail    = options.get_option(:bfail)
+            end
+            return Result.bulk(input_data, is_bulk: is_bulk, command: command, fields: display_fields, bfail: bfail) do |params|
               api.create(entity, params)
             end
           when :delete
-            raise BadArgument, 'cannot delete singleton' if is_singleton
+            Aspera.assert(!is_singleton, type: BadArgument){'cannot delete singleton'}
             if !delete_style.nil?
               one_res_id = [one_res_id] unless one_res_id.is_a?(Array)
               Aspera.assert_type(one_res_id, Array, type: Cli::BadArgument)
@@ -158,17 +546,18 @@ module Aspera
                 content_type: Mime::JSON,
                 body:         {delete_style => one_res_id}
               )
-              return Main.result_status('deleted')
+              return Result::Status.new('deleted')
             end
-            return do_bulk_operation(command: command, values: one_res_id) do |one_id|
-              api.delete("#{entity}/#{one_id}", query_read_delete)
+            items = one_res_id.is_a?(Array) ? one_res_id : [one_res_id]
+            return Result.bulk(items, is_bulk: is_bulk, command: command, bfail: bfail) do |one_id|
+              api.delete("#{entity}/#{one_id}", query_read_delete(schema: qs_path))
               {'id' => one_id}
             end
           when :show
-            return Main.result_single_object(api.read(one_res_path), fields: display_fields)
+            return Result::SingleObject.new(api.read(one_res_path), fields: display_fields)
           when :list
-            data, http = api.read(entity, query_read_delete, ret: :both)
-            return Main.result_empty if http.code == '204'
+            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')
@@ -177,17 +566,18 @@ module Aspera
             data = data[items_key] if items_key
             case data
             when Hash
-              return Main.result_single_object(data, fields: display_fields)
+              return Result::SingleObject.new(data, fields: display_fields)
             when Array
-              return Main.result_object_list(data, fields: display_fields) if data.empty? || data.first.is_a?(Hash)
-              return Main.result_value_list(data)
+              return Result::ObjectList.new(data, fields: display_fields) if data.empty? || data.first.is_a?(Hash)
+              return Result::ValueList.new(data)
             else
               Aspera.error_unexpected_value(data.class.name){'list type'}
             end
           when :modify
-            parameters = value_create_modify(command: command)
+            # Use pre-resolved data if provided; otherwise read from CLI
+            parameters = input_data || options.get_next_argument('data', validation: Hash, schema: schema)
             api.update(one_res_path, parameters)
-            return Main.result_status('modified')
+            return Result::Status.new('modified')
           else
             Aspera.error_unexpected_value(command){'command'}
           end
@@ -195,10 +585,11 @@ module Aspera
 
         # Query parameters in URL suitable for REST: list/`GET` and delete/`DELETE`
         # @param default [Hash, nil] Default query parameters
+        # @param schema [String, nil] Contextual schema path for --query help display
         # @return [Hash, nil] Query parameters
-        def query_read_delete(default: nil)
+        def query_read_delete(default: nil, schema: nil)
           # Dup default, as it could be frozen
-          query = options.get_option(:query) || default.dup
+          query = options.get_option(:query, schema: schema) || default&.dup
           Log.log.debug{"query_read_delete=#{query}".bg_red}
           begin
             # Check it is suitable
@@ -208,34 +599,6 @@ module Aspera
           end
           return query
         end
-
-        # Retrieves an extended value from command line.
-        # Used for creation or modification of entities.
-        # @param command [Symbol] Command name for error message
-        # @param description [String, nil] Description of the value
-        # @param type [Class, nil] Expected type of value
-        # @param bulk [Boolean] If `true`, value must be an Array of `type`
-        # @param default [Object, nil] Default value if not provided
-        # @param schema [Hash, nil] JSON schema for validation
-        # @return [Hash, Array<Hash>] The value(s) to create object(s)
-        def value_create_modify(command:, description: nil, type: Hash, bulk: false, default: nil, schema: nil)
-          value = options.get_next_argument(
-            "parameters for #{command}#{" (#{description})" unless description.nil?}",
-            mandatory: default.nil?,
-            validation: bulk ? Array : type,
-            schema: schema
-          )
-          value = default if value.nil?
-          unless type.nil?
-            Aspera.assert_type(type, Class){'type'}
-            if bulk
-              Aspera.assert_array_all(value, type, type: Cli::BadArgument){'type'}
-            else
-              Aspera.assert_type(value, type, type: Cli::BadArgument){'type'}
-            end
-          end
-          return value
-        end
       end
     end
   end