aspera-cli 4.27.0 → 4.27.1

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

@@ -5,6 +5,7 @@ require 'aspera/cli/parser'
 require 'aspera/assert'
 require 'aspera/cli/result'
 require 'aspera/cli/command_registry'
+require 'aspera/cli/option_declarator'
 require 'aspera/schema/registry'
 
 module Aspera
@@ -25,6 +26,16 @@ module Aspera
         class << self
           # Per-class DSL registry (not inherited: each subclass gets its own instance).
           # @return [CommandRegistry]
+          def 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)
+          end
+
           def command_registry
             @command_registry ||= CommandRegistry.new
           end
@@ -38,18 +49,70 @@ module Aspera
             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})
+          # 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
+          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
+          #                  (:show, :modify, :delete) when not a singleton; none for global verbs
+          #   - action:      calls entity_<verb>(api:, entity:, **shared_kwargs, **ctx)
+          #
+          # api: is resolved at runtime: :@ivar -> instance_variable_get, else -> send.
+          # entity: may also be a Symbol — resolved at runtime as a ctx key (e.g. :sf_entity).
+          #   This covers cases where the entity path is injected by a parent setup: method.
+          #
+          # @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 lookup     [Symbol, nil]    Instance method for percent-selector resolution
+          # @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)
+            operations ||= Operations::ALL
+            operations.each do |verb|
+              id_arg = ({name: :id, type: :identifier, lookup: lookup} if Operations::INSTANCE.include?(verb) && !kwargs[:is_singleton])
+              schema_val =
+                if kwargs[:body_component] && entity.is_a?(String)
+                  case verb
+                  when :create then Schema::Registry.req_body(kwargs[:body_component], "#{entity}.post")
+                  when :modify then Schema::Registry.req_body(kwargs[:body_component], "#{entity}/{id}.put")
+                  end
+                end
+              args =
+                case verb
+                when :create
+                  [{name: :data, type: Hash, bulk: true, schema: schema_val}]
+                when :modify
+                  [id_arg, {name: :data, type: Hash, schema: schema_val}].compact
+                when :delete
+                  id_arg ? [id_arg.merge(bulk: true)] : nil
+                else
+                  id_arg ? [id_arg] : nil
+                end
+              action_proc = lambda do |**ctx|
+                resolved_api =
+                  if api.is_a?(Symbol)
+                    api.to_s.start_with?('@') ? instance_variable_get(api) : send(api)
+                  elsif api.is_a?(Proc)
+                    instance_exec(&api)
+                  else
+                    api
+                  end
+                resolved_entity = entity.is_a?(Symbol) ? ctx.fetch(entity) : entity
+                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[:arguments] = args if args
+              command(verb, **cmd_attrs)
+            end
           end
 
           # DSL class method: define an instance method whose name is derived from a path array.
@@ -62,11 +125,29 @@ module Aspera
 
           # 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
+          # If the terminal node of `parent` has not been declared yet, it is auto-declared
+          # as an intermediate command with description: "Manage <name>" (or the given description:).
+          #
+          # `parent` is always resolved relative to the current scope:
+          #   Array(@current_parent) + Array(parent)
+          #
+          # @param parent      [Symbol, Array<Symbol>] one or more path segments, relative to current scope
+          # @param description [String, nil]           Description of entity for the auto-declared node
           # @yieldreturn [void]
-          def commands_under(parent)
+          def commands_under(parent, description: nil)
+            # Always relative: append the given segments to the current scope.
+            path = Array(@current_parent) + Array(parent)
+            unless command_registry[path]
+              id = path.last
+              desc = description || "Manage #{entity_display_name(id)}"
+              parent_path = path[0..-2]
+              saved = @current_parent
+              @current_parent = parent_path.empty? ? nil : parent_path
+              command(id, description: desc)
+              @current_parent = saved
+            end
             previous = @current_parent
-            @current_parent = parent
+            @current_parent = path
             yield
           ensure
             @current_parent = previous
@@ -114,6 +195,47 @@ module Aspera
             )
           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 = []
+            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 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
+            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
@@ -135,16 +257,38 @@ module Aspera
             @application_name = name unless name.nil?
             @application_name || self.name.split('::').last
           end
+
+          # Build a filter lambda from a match expression (String glob, Regexp, Proc, or nil).
+          # @param match_expression [String, Regexp, Proc, NilClass] as in FILTER_ARGS
+          # @return [Proc] lambda(entry) -> Boolean
+          def file_matcher(match_expression)
+            case match_expression
+            when Proc    then match_expression
+            when Regexp  then ->(f) { f['name'].match?(match_expression) }
+            when String  then ->(f) { File.fnmatch(match_expression, f['name'], File::FNM_DOTMATCH) }
+            when NilClass then ->(_) { true }
+            else Aspera.error_unexpected_value(match_expression.class.name, type: ParameterError)
+            end
+          end
         end
 
+        # Shared positional argument for commands that accept an optional file name filter.
+        # Accepted types: String (shell glob matched against entry name), Regexp, or Proc.
+        # Used by node files find, and preview scan/events/trevents.
+        FILTER_ARGS = [{name: :filter, type: [String, Regexp, Proc], description: 'File name filter: String (glob), Regexp, or Proc', mandatory: false, default: nil}].freeze
+
         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
+        option :bulk,  description: 'Bulk operation (only some)',                            allowed: Type::BOOLEAN, default: false
+        option :bfail, description: 'Bulk operation error handling',                         allowed: Type::BOOLEAN, default: true
 
         def initialize(context:)
-          Aspera.assert_type(context, Context){'context'}
-          Aspera.assert_type(context.man_header, TrueClass, FalseClass){'context.man_header'}
+          Aspera.assert_type(context, Context) { 'context' }
+          Aspera.assert_type(context.man_header, TrueClass, FalseClass) { 'context.man_header' }
           @context = context
+          # Switch to the plugin-specific options group so that all options declared
+          # 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).
@@ -154,9 +298,22 @@ module Aspera
           # 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 && klass.instance_variable_defined?(:@command_registry)
-            klass.command_registry.option_specs.each_value do |spec|
+            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
@@ -175,7 +332,6 @@ module Aspera
               )
             end
           end
-          add_manual_header if @context.man_header
         end
 
         # Global objects
@@ -202,7 +358,8 @@ module Aspera
         def progress_bar; @context.progress_bar; end
 
         def add_manual_header(_has_options = true)
-          options.rename_current_group(self.class.name.split('::').last.downcase)
+          # 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.
@@ -251,11 +408,13 @@ module Aspera
               (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
+                  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
@@ -289,22 +448,36 @@ module Aspera
         end
 
         # Phase B, child branch: consume the next command argument, resolve the matching
-        # child spec, handle delegation / entity_execute shorthands, and recurse or execute.
+        # child spec, handle delegation, and recurse or execute.
+        # --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
+        #      MissingArgument error.
+        #   2. After get_next_command when no further args remain: raises HelpRequest scoped
+        #      to the consumed command (e.g. `aoc files find -h`).
         # @param current_path [Array<Symbol>]
-        # @param registry [CommandRegistry]
-        # @param ctx [Hash]
+        # @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)}
+          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
+            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?
+            @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 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.
+          # 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?
             @help_path = current_path + [command]
             raise Cli::HelpRequest, self
@@ -317,9 +490,6 @@ module Aspera
           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
@@ -349,23 +519,28 @@ module Aspera
           end
         end
 
-        # Execute a leaf CommandSpec: resolve arguments (or skip for transfer_paths) and call action.
+        # 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.
         # @param spec [CommandSpec] a leaf node (no children)
-        # @param ctx  [Hash]        accumulated context
+        # @param ctx  [Hash]        accumulated context (pre-resolved keys are not re-consumed)
         # @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|
+            next if ctx.key?(arg_spec.name)
             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
+              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))
             end
@@ -373,33 +548,6 @@ module Aspera
           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.
@@ -422,7 +570,7 @@ module Aspera
                 schema:    arg_spec.schema
               )
               if is_bulk
-                Aspera.assert_array_all(val, arg_spec.type, type: Cli::BadArgument){'type'} unless arg_spec.type.nil?
+                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
@@ -465,124 +613,147 @@ module Aspera
           end
         end
 
-        # Operations: Create, Delete, Show, List, Modify
-        # @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
-        # @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(
-          api:,
-          entity:,
-          command: nil,
-          display_fields: nil,
-          items_key: nil,
-          delete_style: nil,
-          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
+        # Convenience wrapper: reads :bulk and :bfail from options, normalises +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)
+        #   items   = x.is_a?(Array) ? x : [x]
+        #   Result.bulk(items, is_bulk: is_bulk, ...)
+        # @param items     [Object, Array]  Single item or Array; wrapped in Array when needed
+        # @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+
+        # @return [Result::ObjectList, Result::SingleObject]
+        def bulk_result(items, command:, id_result: 'id', fields: :default, &block)
+          items = items.is_a?(Array) ? items : [items]
+          Result.bulk(
+            items,
+            is_bulk:   options.get_option(:bulk),
+            command:   command,
+            id_result: id_result,
+            fields:    fields,
+            bfail:     options.get_option(:bfail),
+            &block
+          )
+        end
+
+        # --- Per-verb entity action methods ---
+        # Each method handles exactly one CRUD verb.
+        # The resource id (when needed) is received as `id:` from ctx — it must be
+        # resolved upstream via an ArgumentSpec(type: :identifier) on the command,
+        # NOT read from the CLI queue inside the method.
+
+        # List all instances of an entity.
+        # @param api             [Aspera::Rest]  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
+        # @param list_query      [Hash, nil]     Default query parameters
+        # @param query_component [String, nil]   Registry key for --query=help schema
+        def entity_list(api:, entity:, display_fields: nil, items_key: nil, list_query: nil, query_component: nil, **)
           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')
+            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
+            return Result::ObjectList.new(data, fields: display_fields) if data.empty? || data.first.is_a?(Hash)
+            Result::ValueList.new(data)
+          else Aspera.error_unexpected_value(data.class.name) { 'list type' }
+          end
+        end
 
-          if is_singleton
-            one_res_path = entity
-          elsif Operations::INSTANCE.include?(command)
-            # 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
-            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
-            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)
-              api.delete(
-                entity,
-                nil,
-                content_type: Mime::JSON,
-                body:         {delete_style => one_res_id}
-              )
-              return Result::Status.new('deleted')
-            end
-            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 Result::SingleObject.new(api.read(one_res_path), fields: display_fields)
-          when :list
-            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')
-              data = data[entity]
-            end
-            data = data[items_key] if items_key
-            case data
-            when Hash
-              return Result::SingleObject.new(data, fields: display_fields)
-            when Array
-              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
-            # 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 Result::Status.new('modified')
-          else
-            Aspera.error_unexpected_value(command){'command'}
+        # Show one instance of an entity.
+        # @param api            [Aspera::Rest]    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
+        # @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>
+        def entity_show(api:, entity:, id: nil, display_fields: nil, is_singleton: false, id_as_arg: false, **)
+          path = entity_res_path(entity, id, is_singleton: is_singleton, id_as_arg: id_as_arg)
+          Result::SingleObject.new(api.read(path), fields: display_fields)
+        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|
+            api.create(entity, params)
           end
         end
 
+        # Modify an existing instance of an entity.
+        # @param api            [Aspera::Rest]    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
+          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)
+          Result::Status.new('modified')
+        end
+
+        # Delete one or more instances of an entity (supports bulk).
+        # @param api             [Aspera::Rest]    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>
+        # @param delete_style    [String, nil]     When set, deletes by sending id array in payload
+        # @param query_component [String, nil]     Registry key for --query=help schema
+        def entity_delete(api:, entity:, id: nil, id_as_arg: false, delete_style: nil, query_component: nil, **)
+          qs_path = query_component ? Schema::Registry.query_params(query_component, entity) : nil
+          if !delete_style.nil?
+            ids = id.is_a?(Array) ? id : [id]
+            Aspera.assert_type(ids, Array, type: Cli::BadArgument)
+            api.delete(entity, nil, content_type: Mime::JSON, body: {delete_style => ids})
+            return Result::Status.new('deleted')
+          end
+          bulk_result(id, command: :delete) do |one_id|
+            api.delete(
+              id_as_arg ? "#{entity}?#{id_as_arg}=#{one_id}" : "#{entity}/#{one_id}",
+              query_read_delete(schema: qs_path)
+            )
+            {'id' => one_id}
+          end
+        end
+
+        # Build the resource path for an instance operation.
+        # @param entity       [String]          API sub-path
+        # @param id           [String, nil]     Resource identifier
+        # @param is_singleton [Boolean]         When true, entity IS the full path
+        # @param id_as_arg    [Boolean, String] When set, id appended as ?<id_as_arg>=<id>
+        # @return [String]
+        def entity_res_path(entity, id, is_singleton: false, id_as_arg: false)
+          return entity if is_singleton
+          return "#{entity}?#{id_as_arg}=#{id}" if id_as_arg
+          "#{entity}/#{id}"
+        end
+
         # 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
@@ -590,7 +761,7 @@ module Aspera
         def query_read_delete(default: nil, schema: nil)
           # Dup default, as it could be frozen
           query = options.get_option(:query, schema: schema) || default&.dup
-          Log.log.debug{"query_read_delete=#{query}".bg_red}
+          Log.dump(:query_read_delete, query)
           begin
             # Check it is suitable
             URI.encode_www_form(query) unless query.nil?