aspera-cli 4.26.2 → 4.27.1

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

@@ -2,8 +2,10 @@
 
 # spellchecker: ignore workgroups mypackages passcode
 
+require 'aspera/schema/registry'
 require 'aspera/cli/plugins/oauth'
 require 'aspera/cli/extended_value'
+require 'aspera/transfer/result'
 require 'aspera/cli/special_values'
 require 'aspera/cli/wizard'
 require 'aspera/api/faspex'
@@ -18,11 +20,11 @@ module Aspera
   module Cli
     module Plugins
       class Faspex5 < Oauth
-        class << self
-          def application_name
-            'Faspex'
-          end
+        application_name 'Faspex v5'
+        # Commands that may carry a query_schema annotation
+        QUERY_SCHEMA_COMMANDS = %i[list delete].freeze
 
+        class << self
           # @return [Hash,NilClass]
           def detect(address_or_url)
             # add scheme if missing
@@ -45,7 +47,7 @@ module Aspera
               }
             rescue StandardError => e
               error = e
-              Log.log.debug{"detect error: #{e}"}
+              Log.log.debug { "detect error: #{e}" }
             end
             raise error if error
             return
@@ -79,24 +81,23 @@ module Aspera
           )
           return {
             preset_value: {
-              url:         app_url,
-              username:    wiz_username,
-              auth:        :jwt.to_s,
-              private_key: "@file:#{private_key_path}",
-              params:      {
-                client_id:     client_id,
-                client_secret: client_secret
-              }
+              url:           app_url,
+              username:      wiz_username,
+              auth:          :jwt.to_s,
+              private_key:   "@file:#{private_key_path}",
+              client_id:     client_id,
+              client_secret: client_secret
             },
             test_args:    'user profile show'
           }
         end
 
+        option :box,           description: "Package inbox, either shared inbox name or one of: #{Api::Faspex::API_LIST_MAILBOX_TYPES.join(', ')} or #{SpecialValues::ALL}", default: 'inbox_all'
+        option :shared_folder, description: 'Send package with files from shared folder'
+        option :group_type,    description: 'Type of shared box', allowed: %i[shared_inboxes workgroups], default: :shared_inboxes
+
         def initialize(**_)
           super
-          options.declare(:box, "Package inbox, either shared inbox name or one of: #{Api::Faspex::API_LIST_MAILBOX_TYPES.join(', ')} or #{SpecialValues::ALL}", default: 'inbox_all')
-          options.declare(:shared_folder, 'Send package with files from shared folder')
-          options.declare(:group_type, 'Type of shared box', allowed: %i[shared_inboxes workgroups], default: :shared_inboxes)
           options.parse_options!
           # [Aspera::Api::Faspex]
           @api_v5 = nil
@@ -106,7 +107,7 @@ module Aspera
         def normalize_recipients(parameters, type)
           type = type.to_s
           return unless parameters.key?(type)
-          Aspera.assert_type(parameters[type], Array){type}
+          Aspera.assert_type(parameters[type], Array) { type }
           recipient_types = Api::Faspex::RECIPIENT_TYPES
           if parameters.key?('recipient_types')
             recipient_types = parameters['recipient_types']
@@ -136,24 +137,24 @@ module Aspera
             # user asked to not follow
             return status if status_list.nil?
             if status['upload_status'].eql?('submitted')
-              config.progress_bar&.event(:sessions_init, session_id: nil, info: status['upload_status'])
+              progress_bar&.event(:sessions_init, session_id: nil, info: status['upload_status'])
             elsif !total_sent
-              config.progress_bar&.event(:session_start, session_id: id)
-              config.progress_bar&.event(:session_size, session_id: id, info: status['bytes_total'].to_i)
+              progress_bar&.event(:session_start, session_id: id)
+              progress_bar&.event(:session_size, session_id: id, info: status['bytes_total'].to_i)
               total_sent = true
             else
-              config.progress_bar&.event(:transfer, session_id: id, info: status['bytes_written'].to_i)
+              progress_bar&.event(:transfer, session_id: id, info: status['bytes_written'].to_i)
             end
             if status_list.include?(status['upload_status'])
-              config.progress_bar&.event(:session_end, session_id: id)
-              config.progress_bar&.event(:end)
+              progress_bar&.event(:session_end, session_id: id)
+              progress_bar&.event(:end)
               return status
             end
             sleep(1.0)
           end
         end
 
-        # @param [String] job identifier
+        # @param job_id [String] job identifier
         # @return [Hash] result of API call for job status
         def wait_for_job(job_id)
           result = nil
@@ -167,9 +168,15 @@ module Aspera
           return result
         end
 
-        # list all packages with optional filter
-        def list_packages_with_filter(query: {})
-          filter = options.get_next_argument('filter', mandatory: false, validation: Proc, default: ->(_x){true})
+        # List all packages with optional filter.
+        # The special `max` key is extracted *before* the API call and returned separately,
+        # so callers that apply a post-API filter (e.g. once_only) can enforce the limit
+        # after filtering rather than before.
+        # @param filter [Proc, nil] optional filter lambda applied to each package entry
+        # @param query  [Hash]      additional query parameters forwarded to the API
+        # @return [Array(Array, Integer|nil, Integer|nil)] [filtered list, max (or nil), total count]
+        def list_packages_with_filter(filter: nil, query: {})
+          filter ||= ->(_x) { true }
           box = options.get_option(:box)
           # Translate box name to API prefix (with ending slash)
           entity =
@@ -180,8 +187,13 @@ module Aspera
               group_type = options.get_option(:group_type)
               "#{group_type}/#{@api_v5.lookup_entity_by_field(entity: group_type, value: box)['id']}/packages"
             end
-          list, total = @api_v5.list_entities_limit_offset_total_count(entity: entity, query: query_read_delete(default: query))
-          return list.select(&filter), total
+          # Merge default query with user-provided query: user values take precedence, but defaults are preserved
+          user_query = query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'packages'))
+          merged_query = user_query.nil? ? query.dup : query.merge(user_query)
+          # Extract `max` before the API call so callers can apply it after post-API filtering
+          max_items = merged_query.delete(RestList::MAX_ITEMS)&.to_i
+          list, total = @api_v5.list_entities_limit_offset_total_count(entity: entity, query: merged_query)
+          return list.select(&filter), max_items, total
         end
 
         # Build query to get package recipients based on package info in case of shared inbox or workgroup recipient
@@ -214,22 +226,24 @@ module Aspera
           case package_ids
           when SpecialValues::INIT
             Aspera.assert(skip_ids_persistency, 'Only with option once_only')
-            skip_ids_persistency.data.clear.concat(list_packages_with_filter.first.map{ |p| p['id']})
+            skip_ids_persistency.data.clear.concat(list_packages_with_filter.first.map { |p| p['id'] }) # no filter: all packages, max ignored
             skip_ids_persistency.save
             return Result::Status.new("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
           when SpecialValues::ALL
             # TODO: if packages have same name, they will overwrite ?
-            packages = list_packages_with_filter(query: {'status' => 'completed'}).first
-            Log.dump(:package_ids, level: :trace1){packages.map{ |p| p['id']}}
+            packages, max_items = list_packages_with_filter(query: {'status' => 'completed'}) # no filter: all completed packages
+            Log.dump(:package_ids, level: :trace1) { packages.map { |p| p['id'] } }
             Log.dump(:skip_ids, skip_ids_persistency.data, level: :trace1)
-            packages.reject!{ |p| skip_ids_persistency.data.include?(p['id'])} if skip_ids_persistency
-            Log.dump(:package_ids, level: :trace1){packages.map{ |p| p['id']}}
+            packages.reject! { |p| skip_ids_persistency.data.include?(p['id']) } if skip_ids_persistency
+            # Apply `max` after once_only filtering so we get the N first not-yet-downloaded packages
+            packages = packages[0, max_items] if max_items
+            Log.dump(:package_ids, level: :trace1) { packages.map { |p| p['id'] } }
           else
             # a single id was provided, or a list of ids
             package_ids = [package_ids] unless package_ids.is_a?(Array)
-            Aspera.assert_array_all(package_ids, String){'Package id(s)'}
+            Aspera.assert_array_all(package_ids, String) { 'Package id(s)' }
             # packages = package_ids.map{|pkg_id|@api_v5.read("packages/#{pkg_id}")}
-            packages = package_ids.map{ |pkg_id| {'id'=>pkg_id}}
+            packages = package_ids.map { |pkg_id| {'id'=>pkg_id} }
           end
           result_transfer = []
           param_file_list = {}
@@ -261,7 +275,7 @@ module Aspera
             statuses = transfer.start(transfer_spec)
             result_transfer.push({'package' => pkg_id, Runner::STATUS_FIELD => statuses})
             # skip only if all sessions completed
-            if TransferAgent.session_status(statuses).eql?(:success) && skip_ids_persistency
+            if statuses.is_a?(Transfer::Result::Success) && skip_ids_persistency
               skip_ids_persistency.data.push(pkg_id)
               skip_ids_persistency.save
             end
@@ -269,8 +283,7 @@ module Aspera
           return Runner.result_transfer_multiple(result_transfer)
         end
 
-        def package_send
-          parameters = value_create_modify(command: :send, schema: Schema::Registry.req_body(Schema::Registry::FASPEX, 'packages.post'))
+        def package_send(parameters)
           # autofill recipient for public url
           if @api_v5.pub_link_context&.key?('recipient_type') && !parameters.key?('recipients')
             parameters['recipients'] = [{
@@ -278,7 +291,7 @@ module Aspera
               recipient_type: @api_v5.pub_link_context['recipient_type']
             }]
           end
-          PACKAGE_RECIPIENT_TYPES.each{ |type| normalize_recipients(parameters, type)}
+          PACKAGE_RECIPIENT_TYPES.each { |type| normalize_recipients(parameters, type) }
           # User specified content prot in tspec, but faspex requires in package creation
           # `transfer_spec/upload` will set `content_protection`
           if transfer.user_transfer_spec['content_protection'] && !parameters.key?('ear_enabled')
@@ -299,7 +312,7 @@ module Aspera
             return Runner.result_transfer(transfer.start(transfer_spec))
           else
             # send from remote shared folder
-            if (m = Manager.percent_selector(shared_folder))
+            if (m = Parser.percent_selector(shared_folder))
               shared_folder = @api_v5.lookup_entity_by_field(
                 entity: 'shared_folders',
                 field: m[:field],
@@ -320,16 +333,17 @@ module Aspera
 
         # Browse a folder
         # @param browse_endpoint [String] the endpoint to browse
-        def browse_folder(browse_endpoint, base_query = {})
-          folders_to_process = [options.get_next_argument('folder path', default: '/')]
+        # @param folder_path     [String] starting path (default: '/')
+        def browse_folder(browse_endpoint, base_query = {}, folder_path: '/')
+          folders_to_process = [folder_path]
           query = base_query.merge(query_read_delete(default: {}))
-          filters = query.delete('filters'){{}}
+          filters = query.delete('filters') { {} }
           Aspera.assert_type(filters, Hash)
           filters['basenames'] ||= []
-          Aspera.assert_type(filters, Hash){'filters'}
+          Aspera.assert_type(filters, Hash) { 'filters' }
           max_items = query.delete(RestList::MAX_ITEMS)
           recursive = query.delete('recursive')
-          use_paging = query.delete('paging'){true}
+          use_paging = query.delete('paging') { true }
           if use_paging
             browse_endpoint = "#{browse_endpoint}/page"
             query['per_page'] ||= 500
@@ -356,7 +370,7 @@ module Aspera
                 all_items = all_items.slice(0, max_items) if all_items.count > max_items
                 break
               end
-              folders_to_process.concat(data['items'].select{ |i| i['type'].eql?('directory')}.map{ |i| i['path']}) if recursive
+              folders_to_process.concat(data['items'].select { |i| i['type'].eql?('directory') }.map { |i| i['path'] }) if recursive
               if use_paging
                 iteration_token = http[Api::Faspex::HEADER_X_NEXT_ITER_TOKEN]
                 break if iteration_token.nil? || iteration_token.empty?
@@ -374,374 +388,599 @@ module Aspera
           return Result::ObjectList.new(all_items, total: total_count)
         end
 
-        def package_action
-          command = options.get_next_command(%i[show browse status delete receive send list file_processing])
-          package_id =
-            unless %i[send list].include?(command)
-              @api_v5.pub_link_context&.key?('package_id') ? @api_v5.pub_link_context['package_id'] : options.instance_identifier
-            end
-          package_instance = "packages/#{package_id}"
-          case command
-          when :show
-            return Result::SingleObject.new(@api_v5.read(package_instance))
-          when :browse
-            return browse_folder("#{package_instance}/files/#{Api::Faspex.box_type(options.get_option(:box))}", recipient_query(package_id))
-          when :status
-            status_list = options.get_next_argument('list of states, or nothing', mandatory: false, validation: Array)
-            status = wait_package_status(package_id, status_list: status_list)
-            return Result::SingleObject.new(status)
-          when :delete
-            ids = package_id
-            ids = [ids] unless ids.is_a?(Array)
-            Aspera.assert_array_all(ids, String){'Package id(s)'}
-            # API returns 204, empty on success
-            @api_v5.call(
-              operation:    'DELETE',
-              subpath:      'packages',
-              content_type: Mime::JSON,
-              body:         {ids: ids},
-              headers:      {'Accept' => Mime::JSON}
-            )
-            return Result::Status.new('Package(s) deleted')
-          when :receive
-            return package_receive(package_id)
-          when :send
-            return package_send
-          when :list
-            list, total = list_packages_with_filter
-            fields = %w[id title status sender.name recipients.0.name release_date total_bytes total_files]
-            fields.delete('recipients.0.name') if %w[inbox inbox_history].include?(options.get_option(:box))
-            fields.delete('sender.name') if %w[outbox outbox_history].include?(options.get_option(:box))
-            return Result::ObjectList.new(list, total: total, fields: fields)
-          when :file_processing
-            result, count = @api_v5.list_entities_limit_offset_total_count(
-              entity: "#{package_instance}/file_statuses",
-              items_key: 'files'
-            )
-            return Result::ObjectList.new(result, total: count)
+        # Per-resource configuration for admin CRUD sub-trees.
+        # Keys mirror entity_list/show/create/modify/delete kwargs; extra_commands lists additional leaf commands.
+        # @return [Hash{Symbol => Hash}]
+        RESOURCE_CONFIG = {
+          accounts:            {
+            display_fields:        -> { Formatter.all_but('user_profile_data_attributes') },
+            extra_commands:        [:reset_password],
+            instance_arg_commands: {reset_password: {arguments: [{name: :contact_id, type: :identifier, lookup: ->(field, value, **) { res_lookup_id(:accounts, field, value) }}]}},
+            query_component:       Schema::Registry::FASPEX,
+            body_component:        Schema::Registry::FASPEX
+          },
+          alternate_addresses: {entity: 'configuration/alternate_addresses', query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
+          contacts:            {query_component: Schema::Registry::FASPEX},
+          distribution_lists:  {entity: 'account/distribution_lists', delete_style: 'ids', query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
+          email_notifications: {id_as_arg: 'type', query_component: Schema::Registry::FASPEX},
+          file_processing:     {
+            commands:       %i[next modify],
+            body_component: Schema::Registry::FASPEX,
+            is_singleton:   true
+          },
+          jobs:                {display_fields: %w[id job_name job_type status], query_component: Schema::Registry::FASPEX},
+          metadata_profiles:   {entity: 'configuration/metadata_profiles', items_key: 'profiles', query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
+          nodes:               {
+            extra_commands:        %i[browse],
+            instance_arg_commands: {
+              browse: {
+                arguments: [{name: :node_id, type: :identifier, lookup: :lookup_node_id},
+                            {name: :folder_path, type: String, mandatory: false, default: '/'}]
+              }
+            },
+            query_component:       Schema::Registry::FASPEX,
+            body_component:        Schema::Registry::FASPEX
+          },
+          oauth_clients:       {
+            display_fields:  -> { Formatter.all_but('public_key') },
+            api:             -> { Api::Faspex.new(root: Api::Faspex::PATH_AUTH, **Oauth.kwargs_from_options(options)) },
+            list_query:      {'expand': true, 'no_api_path': true, 'client_types[]': 'public'},
+            query_component: Schema::Registry::FASPEX,
+            body_component:  Schema::Registry::FASPEX
+          },
+          registrations:       {query_component: Schema::Registry::FASPEX},
+          saml_configs:        {query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
+          shared_inboxes:      {res_id_query: {'all': true}, query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
+          webhooks:            {query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
+          workgroups:          {res_id_query: {'all': true}, query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX}
+        }.freeze
+        private_constant :RESOURCE_CONFIG
+
+        # Resolve a RESOURCE_CONFIG value that may be a Proc (evaluated in instance context).
+        def resource_config_value(cfg, key)
+          v = cfg[key]
+          v.is_a?(Proc) ? instance_exec(&v) : v
+        end
+
+        # Build args hash from RESOURCE_CONFIG for use with entity_list/show/create/modify/delete.
+        def res_exec_args(res_sym)
+          cfg = RESOURCE_CONFIG.fetch(res_sym, {})
+          {
+            api:             resource_config_value(cfg, :api) || @api_v5,
+            entity:          resource_config_value(cfg, :entity) || res_sym.to_s,
+            items_key:       resource_config_value(cfg, :items_key),
+            delete_style:    resource_config_value(cfg, :delete_style),
+            id_as_arg:       resource_config_value(cfg, :id_as_arg) || false,
+            display_fields:  resource_config_value(cfg, :display_fields),
+            list_query:      resource_config_value(cfg, :list_query),
+            is_singleton:    resource_config_value(cfg, :is_singleton) || false,
+            query_component: resource_config_value(cfg, :query_component),
+            body_component:  resource_config_value(cfg, :body_component)
+          }.compact
+        end
+
+        # admin > nodes — lookup node id by field/value
+        def lookup_node_id(field, value, **)
+          @api_v5.lookup_entity_by_field(entity: 'nodes', field: field, value: value)['id']
+        end
+
+        # Lookup id for a RESOURCE_CONFIG resource by field/value.
+        def res_lookup_id(res_sym, field, value)
+          cfg = RESOURCE_CONFIG.fetch(res_sym, {})
+          entity      = resource_config_value(cfg, :entity) || res_sym.to_s
+          items_key   = resource_config_value(cfg, :items_key)
+          res_id_query = resource_config_value(cfg, :res_id_query) || :default
+          @api_v5.lookup_entity_by_field(entity: entity, value: value, field: field, items_key: items_key, query: res_id_query)['id']
+        end
+
+        # Dynamically define lookup methods for admin resources (used by crud_commands)
+        Api::Faspex::ADMIN_RESOURCES.each do |res|
+          define_method(:"lookup_admin_#{res}_id") do |field, value, **|
+            res_lookup_id(res, field, value)
           end
         end
 
-        def execute_resource(res_sym)
-          # Arguments for Plugin::Base::entity_execute
-          exec_args = {
-            api:    @api_v5,
-            entity: res_sym.to_s
-          }
-          res_id_query = :default
-          available_commands = Operations::ALL
-          case res_sym
-          when :metadata_profiles
-            exec_args[:entity] = 'configuration/metadata_profiles'
-            exec_args[:items_key] = 'profiles'
-          when :alternate_addresses
-            exec_args[:entity] = 'configuration/alternate_addresses'
-          when :distribution_lists
-            exec_args[:entity] = 'account/distribution_lists'
-            exec_args[:delete_style] = 'ids'
-          when :email_notifications
-            exec_args.delete(:items_key)
-            exec_args[:id_as_arg] = 'type'
-          when :accounts
-            exec_args[:display_fields] = Formatter.all_but('user_profile_data_attributes')
-            available_commands += [:reset_password]
-          when :oauth_clients
-            exec_args[:display_fields] = Formatter.all_but('public_key')
-            exec_args[:api] = Api::Faspex.new(root: Api::Faspex::PATH_AUTH, **Oauth.kwargs_from_options(options))
-            exec_args[:list_query] = {'expand': true, 'no_api_path': true, 'client_types[]': 'public'}
-          when :shared_inboxes, :workgroups
-            available_commands += %i[members saml_groups invite_external_collaborator]
-            res_id_query = {'all': true}
-          when :nodes
-            available_commands += %i[shared_folders browse]
-          when :jobs
-            exec_args[:display_fields] = %w[id job_name job_type status]
-          when :file_processing
-            available_commands = %i[next modify]
-            # schema for modify
-            exec_args[:schema] = Schema::Registry.req_body(Schema::Registry::FASPEX, 'file_processing.put')
-            exec_args[:is_singleton] = true
-          end
-          res_command = options.get_next_command(available_commands)
-          return Result::ValueList.new(Api::Faspex::EMAIL_NOTIF_LIST, name: 'email_id') if res_command.eql?(:list) && res_sym.eql?(:email_notifications)
-          case res_command
-          when :create, :modify, :delete, :show
-            return entity_execute(command: res_command, **exec_args) do |field, value|
-                     @api_v5.lookup_entity_by_field(entity: exec_args[:entity], value: value, field: field, items_key: exec_args[:items_key], query: res_id_query)['id']
-                   end
-          when :list
-            data, total = exec_args[:api].list_entities_limit_offset_total_count(entity: exec_args[:entity], items_key: exec_args[:items_key], query: query_read_delete(default: exec_args[:list_query]))
-            return Result::ObjectList.new(data, total: total, fields: exec_args[:display_fields])
-          when :shared_folders
-            # nodes
-            node_id = options.instance_identifier do |field, value|
-              @api_v5.lookup_entity_by_field(entity: 'nodes', field: field, value: value)['id']
+        # --- DSL ---
+
+        # Commands that need @api_v5 carry setup: :setup_api_v5.
+        # :health and :postprocessing work without authentication, so they have no setup.
+        command :health,         description: 'Check Faspex 5 health'
+        command :version,        description: 'Show Faspex 5 version',             setup: :setup_api_v5, action: -> { Result::SingleObject.new(@api_v5.read('version')) }
+        command :bearer_token,   description: 'Show OAuth bearer token',           setup: :setup_api_v5, action: -> { Result::Text.new(@api_v5.oauth.authorization) }
+        command :packages, description: 'Manage packages', setup: :setup_api_v5
+        commands_under :packages do
+          command :list,   description: 'List packages',
+            arguments: [{name: :filter, mandatory: false, default: nil, type: Proc}]
+          command :send,   description: 'Send a package', transfer_paths: :send,
+            arguments: [{name: :data, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::FASPEX, 'packages.post')}],
+            action: ->(data:, **) { package_send(data) }
+          command :show,   description: 'Show a package', setup: :setup_package_id,
+            action: ->(package_id:, **) { Result::SingleObject.new(@api_v5.read("packages/#{package_id}")) }
+          command :browse, description: 'Browse package files', setup: :setup_package_id,
+            arguments: [{name: :folder_path, type: String, mandatory: false, default: '/'}],
+            action: ->(folder_path:, package_id:, **) { browse_folder("packages/#{package_id}/files/#{Api::Faspex.box_type(options.get_option(:box))}", recipient_query(package_id), folder_path: folder_path) }
+          command :status, description: 'Wait for package status', setup: :setup_package_id,
+            arguments: [{name: :status_list, type: Array, mandatory: false, default: nil}],
+            action: ->(status_list:, package_id:, **) { Result::SingleObject.new(wait_package_status(package_id, status_list: status_list)) }
+          command :delete, description: 'Delete packages', setup: :setup_package_id
+          command :receive, description: 'Receive a package', setup: :setup_package_id, transfer_paths: :receive,
+            action: ->(package_id:, **) { package_receive(package_id) }
+          command(:file_processing, description: 'Show file processing status', setup: :setup_package_id, action: lambda do |package_id:, **|
+            result, count = @api_v5.list_entities_limit_offset_total_count(entity: "packages/#{package_id}/file_statuses", items_key: 'files')
+            Result::ObjectList.new(result, total: count)
+          end)
+        end
+        command :admin,          description: 'Administer Faspex 5',               setup: :setup_api_v5
+        command :user,           description: 'Manage current user',               setup: :setup_api_v5
+        command :shared_folders, description: 'Browse shared folders',             setup: :setup_api_v5
+        command :gateway,        description: 'Start Faspex 4 gateway emulation',  setup: :setup_api_v5,
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
+        command :postprocessing, description: 'Start Faspex 4 post-processing server',
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
+        command :invitations,    description: 'Manage invitations', setup: :setup_api_v5
+
+        commands_under :invitations do
+          command :create, description: 'Create an invitation',
+            arguments: [{name: :input_data, type: Hash, bulk: true}]
+          command :resend, description: 'Resend an invitation',
+            arguments: [{name: :invitation_id, type: :identifier}]
+          crud_commands entity: 'invitations',
+            api:            :@api_v5,
+            operations:     Operations::ALL - %i[create],
+            items_key:      'invitations',
+            display_fields: %w[id public recipient_type recipient_name email_address]
+        end
+
+        commands_under :user do
+          command :account, description: 'Show account information', action: -> { Result::SingleObject.new(@api_v5.read('account', query_read_delete)) }
+          command :profile, description: 'Manage user profile'
+        end
+
+        commands_under %i[user profile] do
+          command :show, description: 'Show user profile', action: -> { Result::SingleObject.new(@api_v5.read('account/preferences')) }
+          command(
+            :modify,
+            description: 'Modify user profile',
+            arguments: [{name: :properties, type: Hash}],
+            action: lambda do |properties:, **|
+              @api_v5.update('account/preferences', properties)
+              Result::Status.new('modified')
             end
-            shared_folder_entity = "nodes/#{node_id}/shared_folders"
-            sh_command = options.get_next_command(Operations::ALL + [:user])
-            case sh_command
-            when *Operations::ALL
-              return entity_execute(
-                api: @api_v5,
-                entity: shared_folder_entity,
-                command: sh_command
-              ) do |field, value|
-                       @api_v5.lookup_entity_by_field(entity: shared_folder_entity, field: field, value: value)['id']
-                     end
-            when :user
-              sh_id = options.instance_identifier do |field, value|
-                @api_v5.lookup_entity_by_field(entity: shared_folder_entity, field: field, value: value)['id']
+          )
+        end
+
+        commands_under :shared_folders do
+          command :list,   description: 'List shared folders', action: -> { Result::ObjectList.new(@api_v5.read('shared_folders')['shared_folders']) }
+          command :browse, description: 'Browse a shared folder',
+            arguments: [{name: :shared_folder_id, type: :identifier, lookup: :lookup_shared_folder_id},
+                        {name: :folder_path, type: String, mandatory: false, default: '/'}]
+        end
+
+        # admin sub-tree: fixed commands + all ADMIN_RESOURCES with their sub-commands
+        commands_under :admin do
+          command :configuration, description: 'Manage Faspex 5 configuration'
+          command :smtp,          description: 'Manage SMTP configuration'
+          command :events,        description: 'List events'
+          command :clean_deleted, description: 'Clean deleted packages',
+            arguments: [{name: :input_data, type: Hash, mandatory: false, default: {}}]
+          Api::Faspex::ADMIN_RESOURCES.each do |res|
+            cfg          = RESOURCE_CONFIG.fetch(res, {})
+            extra        = cfg[:extra_commands] || []
+            ia_cmds      = cfg[:instance_arg_commands] || {}
+            is_singleton = cfg[:is_singleton] || false
+            entity_path  = cfg[:entity] || res.to_s
+            crud_ops     = ((cfg[:commands] || Operations::ALL) - %i[list]) & Operations::ALL
+
+            command res, description: "Manage #{res.to_s.tr('_', ' ')}"
+            commands_under(res) do
+              # List is handled with Faspex 5 pagination (item_list_with_total)
+              unless is_singleton
+                list_kwargs = {description: 'List'}
+                list_kwargs[:query_schema] = Schema::Registry.query_params(cfg[:query_component], entity_path) if cfg[:query_component]
+                command :list, **list_kwargs
               end
-              user_path = "#{shared_folder_entity}/#{sh_id}/custom_access_users"
-              return entity_execute(api: @api_v5, entity: user_path, items_key: 'users') do |field, value|
-                       @api_v5.lookup_entity_by_field(entity: user_path, items_key: 'users', field: field, value: value)['id']
-                     end
 
+              # Standard CRUD operations handled via crud_commands
+              crud_commands(
+                api:            -> { res_exec_args(res)[:api] },
+                entity:         entity_path,
+                operations:     crud_ops,
+                lookup:         :"lookup_admin_#{res}_id",
+                is_singleton:   is_singleton,
+                body_component: cfg[:body_component],
+                display_fields: cfg[:display_fields],
+                delete_style:   cfg[:delete_style],
+                id_as_arg:      cfg[:id_as_arg] || false
+              )
+
+              # Extra commands (e.g. browse, reset_password, next)
+              extra.each do |c|
+                ia = ia_cmds[c] || {}
+                command c, description: c.to_s.tr('_', ' ').capitalize, **ia
+              end
             end
-          when :browse
-            # nodes
-            node_id = options.instance_identifier do |field, value|
-              @api_v5.lookup_entity_by_field(entity: 'nodes', value: value, field: field)['id']
-            end
-            return browse_folder("nodes/#{node_id}/browse")
-          when :invite_external_collaborator
-            # :shared_inboxes, :workgroups
-            shared_inbox_id = options.instance_identifier{ |field, value| @api_v5.lookup_entity_by_field(entity: res_sym.to_s, field: field, value: value, query: res_id_query)['id']}
-            creation_payload = value_create_modify(command: res_command)
-            result = @api_v5.create("#{res_sym}/#{shared_inbox_id}/external_collaborator", creation_payload)
-            formatter.display_status(result['message'])
-            result = @api_v5.lookup_entity_by_field(
-              entity: "#{res_sym}/#{shared_inbox_id}/members",
-              items_key: 'members',
-              value: creation_payload['email_address'],
-              query: {}
-            )
-            return Result::SingleObject.new(result)
-          when :members, :saml_groups
-            # res_command := :shared_inboxes, :workgroups
-            res_id = options.instance_identifier{ |field, value| @api_v5.lookup_entity_by_field(entity: res_sym.to_s, field: field, value: value, query: res_id_query)['id']}
-            res_path = "#{res_sym}/#{res_id}/#{res_command}"
-            list_key = res_command.to_s
-            list_key = 'groups' if res_command.eql?(:saml_groups)
-            sub_command = options.get_next_command(%i[create list modify delete])
-            if sub_command.eql?(:create) && res_command.eql?(:members)
-              # first arg is one user name or list of users
-              users = options.get_next_argument('user id, %name:, or Array')
-              users = [users] unless users.is_a?(Array)
-              users = users.map do |user|
-                if (m = Manager.percent_selector(user))
-                  @api_v5.lookup_entity_by_field(
-                    entity: 'accounts',
-                    field: m[:field],
-                    value: m[:value],
-                    query: Rest.php_style({type: ACCOUNT_TYPES})
-                  )['id']
+          end
+        end
+
+        commands_under %i[admin nodes] do
+          command :shared_folders, description: 'Manage shared folders',
+            arguments: [{name: :node_id, type: :identifier, lookup: :lookup_node_id}],
+            setup: :setup_admin_nodes_shared_folders
+        end
+
+        # admin > nodes > shared_folders sub-tree
+        # entity: :sf_entity is resolved at runtime from ctx (injected by setup_admin_nodes_shared_folders).
+        commands_under %i[admin nodes shared_folders] do
+          crud_commands entity: :sf_entity,
+            api: :@api_v5,
+            name: 'shared folder',
+            lookup: :lookup_sf_id,
+            items_key: 'shared_folders'
+          command :user, description: 'Custom access users',
+            arguments: [{name: :sf_id, type: :identifier, lookup: :lookup_sf_id}],
+            setup: :setup_admin_nodes_shared_folders_user
+        end
+
+        # admin > nodes > shared_folders > user sub-tree (custom access users)
+        # entity: :user_path is resolved at runtime from ctx (injected by setup_admin_nodes_shared_folders_user).
+        commands_under %i[admin nodes shared_folders user] do
+          crud_commands entity: :user_path, api: :@api_v5, name: 'custom access user', lookup: :lookup_sf_user_id, items_key: 'users'
+        end
+
+        # `members` and `saml_groups`
+        CRUD_NO_SHOW = %i[create list modify delete].freeze
+        CRUD_NO_LIST = %i[create modify delete show].freeze
+
+        RES_SINGULAR = {shared_inboxes: :shared_inbox, workgroups: :workgroup}.freeze
+        private_constant :RES_SINGULAR
+
+        # admin > shared_inboxes|workgroups > members|saml_groups|invite_external_collaborator:
+        # res_id consumed via arguments:(:identifier) + lookup:, builds res_instance_path for all children
+        %i[shared_inboxes workgroups].each do |res|
+          lookup_res_id = ->(field, value, **) { @api_v5.lookup_entity_by_field(entity: res.to_s, field: field, value: value, query: {'all': true})['id'] }
+          commands_under [:admin, res] do
+            command :members, description: 'Members',
+              arguments: [{name: :"#{RES_SINGULAR[res]}_id", type: :identifier, lookup: lookup_res_id}],
+              setup: :"setup_admin_#{res}_instance"
+            command :saml_groups, description: 'Saml groups',
+              arguments: [{name: :"#{RES_SINGULAR[res]}_id", type: :identifier, lookup: lookup_res_id}],
+              setup: :"setup_admin_#{res}_instance"
+            command :invite_external_collaborator, description: 'Invite external collaborator',
+              arguments: [{name: :"#{RES_SINGULAR[res]}_id", type: :identifier, lookup: lookup_res_id},
+                          {name: :input_data, type: Hash}]
+          end
+
+          commands_under [:admin, res, :members] do
+            CRUD_NO_SHOW.each do |c|
+              args =
+                if c.eql?(:create)
+                  {arguments: [{name: :users, bulk: true}, {name: :access, mandatory: false, default: :standard}]}
+                elsif Operations::INSTANCE.include?(c)
+                  {arguments: [{name: :member_id, type: :identifier, lookup: :"lookup_#{res}_members_id"}]}
                 else
-                  # it's the user id (not member id...)
-                  user
+                  {}
                 end
-              end
-              access = options.get_next_argument('level', mandatory: false, accept_list: SHARED_INBOX_MEMBER_LEVELS, default: :standard)
-              options.unshift_next_argument({user: users.map{ |u| {id: u, access: access}}})
+              command c, description: c.to_s.capitalize, **args
             end
-            # TODO: test SAML group
-            return entity_execute(
-              api: @api_v5,
-              entity: res_path,
-              command: sub_command,
-              items_key: list_key
-            ) do |field, value|
-                     @api_v5.lookup_entity_by_field(
-                       entity: res_path,
-                       field: field,
-                       value: value,
-                       query: Rest.php_style({type: %w[user]})
-                     )['user_id']
-                   end
-          when :reset_password
-            # :accounts
-            contact_id = options.instance_identifier{ |field, value| @api_v5.lookup_entity_by_field(entity: 'accounts', field: field, value: value, query: res_id_query)['id']}
-            @api_v5.create("accounts/#{contact_id}/reset_password", {})
-            return Result::Status.new('password reset, user shall check email')
-          when :next
-            result, count = @api_v5.list_entities_limit_offset_total_count(
-              entity: exec_args[:entity],
-              operation: 'POST',
-              items_key: 'files'
-            )
-            return Result::ObjectList.new(result, total: count)
-          end
-          Aspera.error_unreachable_line
-        end
-
-        def execute_admin
-          command = options.get_next_command(%i[configuration smtp events clean_deleted].concat(Api::Faspex::ADMIN_RESOURCES).freeze)
-          case command
-          when *Api::Faspex::ADMIN_RESOURCES
-            return execute_resource(command)
-          when :clean_deleted
-            delete_data = value_create_modify(command: command, default: {})
-            delete_data = @api_v5.read('configuration').slice('days_before_deleting_package_records') if delete_data.empty?
-            res = @api_v5.create('internal/packages/clean_deleted', delete_data)
-            return Result::SingleObject.new(res)
-          when :events
-            event_type = options.get_next_command(%i[application webhook])
-            case event_type
-            when :application
-              list, total = @api_v5.list_entities_limit_offset_total_count(entity: 'application_events', query: query_read_delete)
-              return Result::ObjectList.new(list, total: total, fields: %w[event_type created_at application user.name])
-            when :webhook
-              list, total = @api_v5.list_entities_limit_offset_total_count(
-                entity: 'all_webhooks_events',
-                query: query_read_delete,
-                items_key: 'events'
-              )
-              return Result::ObjectList.new(list, total: total)
+          end
+
+          commands_under [:admin, res, :saml_groups] do
+            crud_commands entity: :saml_groups_path,
+              api: :@api_v5,
+              name: 'SAML group',
+              operations: CRUD_NO_SHOW,
+              lookup: :"lookup_#{res}_saml_groups_id",
+              items_key: 'groups'
+          end
+        end
+
+        commands_under %i[admin configuration] do
+          command :show, description: 'Show configuration', action: -> { Result::SingleObject.new(@api_v5.read('configuration')) }
+          command :modify, description: 'Modify configuration',
+            arguments: [{name: :input_data, type: Hash}],
+            action: ->(input_data:, **) { Result::SingleObject.new(@api_v5.update('configuration', input_data)) }
+        end
+
+        commands_under %i[admin smtp] do
+          command :show, description: 'Show SMTP configuration', action: -> { Result::SingleObject.new(@api_v5.read('configuration/smtp')) }
+          command :create, description: 'Create SMTP configuration',
+            arguments: [{name: :input_data, type: Hash}],
+            action: ->(input_data:, **) { Result::SingleObject.new(@api_v5.create('configuration/smtp', input_data)) }
+          command :modify, description: 'Modify SMTP configuration',
+            arguments: [{name: :input_data, type: Hash}],
+            action: ->(input_data:, **) { Result::SingleObject.new(@api_v5.update('configuration/smtp', input_data)) }
+          command(
+            :delete, description: 'Delete SMTP configuration',
+            action: lambda do
+              @api_v5.delete('configuration/smtp')
+              Result::Status.new('SMTP configuration deleted')
             end
-          when :configuration
-            conf_path = 'configuration'
-            conf_cmd = options.get_next_command(%i[show modify])
-            case conf_cmd
-            when :show
-              return Result::SingleObject.new(@api_v5.read(conf_path))
-            when :modify
-              return Result::SingleObject.new(@api_v5.update(conf_path, value_create_modify(command: conf_cmd)))
+          )
+          command :test, description: 'Test SMTP configuration',
+            arguments: [{name: :test_data, type: nil}]
+        end
+
+        commands_under %i[admin events] do
+          command(
+            :application, description: 'List application events',
+            action: lambda do
+              list, total = @api_v5.list_entities_limit_offset_total_count(entity: 'application_events', query: query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'application_events')))
+              Result::ObjectList.new(list, total: total, fields: %w[event_type created_at application user.name])
             end
-          when :smtp
-            # only one SMTP config
-            smtp_path = 'configuration/smtp'
-            smtp_cmd = options.get_next_command(%i[show create modify delete test])
-            case smtp_cmd
-            when :show
-              return Result::SingleObject.new(@api_v5.read(smtp_path))
-            when :create
-              return Result::SingleObject.new(@api_v5.create(smtp_path, value_create_modify(command: smtp_cmd)))
-            when :modify
-              return Result::SingleObject.new(@api_v5.update(smtp_path, value_create_modify(command: smtp_cmd)))
-            when :delete
-              @api_v5.delete(smtp_path)
-              return Result::Status.new('SMTP configuration deleted')
-            when :test
-              test_data = options.get_next_argument('Email or test data, see API')
-              test_data = {test_email_recipient: test_data} if test_data.is_a?(String)
-              creation = @api_v5.create(File.join(smtp_path, 'test'), test_data)
-              result = wait_for_job(creation['job_id'])
-              result['serialized_args'] = JSON.parse(result['serialized_args']) rescue result['serialized_args']
-              return Result::SingleObject.new(result)
+          )
+          command(
+            :webhook, description: 'List webhook events',
+            action: lambda do
+              list, total = @api_v5.list_entities_limit_offset_total_count(entity: 'all_webhooks_events', query: query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'all_webhooks_events')), items_key: 'events')
+              Result::ObjectList.new(list, total: total)
             end
+          )
+        end
+
+        # admin > clean_deleted handler (leaf, no sub-commands)
+        define_action_method(%i[admin clean_deleted]) do |input_data: {}, **|
+          input_data = @api_v5.read('configuration').slice('days_before_deleting_package_records') if input_data.empty?
+          Result::SingleObject.new(@api_v5.create('internal/packages/clean_deleted', input_data))
+        end
+
+        # admin > <resource> > list
+        Api::Faspex::ADMIN_RESOURCES.each do |res|
+          define_action_method([:admin, res, :list]) do
+            args = res_exec_args(res)
+            # Special case: email_notifications list returns a fixed value list
+            next Result::ValueList.new(Api::Faspex::EMAIL_NOTIF_LIST, name: 'email_id') if res.eql?(:email_notifications)
+            data, total = args[:api].list_entities_limit_offset_total_count(
+              entity: args[:entity], items_key: args[:items_key],
+              query: query_read_delete(
+                default: args[:list_query],
+                schema:  args[:query_component] ? Schema::Registry.query_params(args[:query_component], args[:entity]) : nil
+              )
+            )
+            Result::ObjectList.new(data, total: total, fields: args[:display_fields])
           end
         end
 
-        ACTIONS = %i[health version user bearer_token packages shared_folders admin gateway postprocessing invitations].freeze
+        def action_admin_smtp_test(test_data:, **)
+          test_data = {test_email_recipient: test_data} if test_data.is_a?(String)
+          creation = @api_v5.create('configuration/smtp/test', test_data)
+          result = wait_for_job(creation['job_id'])
+          begin
+            result['serialized_args'] = JSON.parse(result['serialized_args'])
+          rescue JSON::ParserError
+            # keep as string if not valid JSON
+          end
+          Result::SingleObject.new(result)
+        end
+
+        # admin > accounts > reset_password
+        def action_admin_accounts_reset_password(contact_id:, **)
+          @api_v5.create("accounts/#{contact_id}/reset_password", {})
+          Result::Status.new('password reset, user shall check email')
+        end
 
-        def execute_action
-          command = options.get_next_command(ACTIONS)
-          unless %i{postprocessing health}.include?(command)
-            # create an API object with the same options, but with a different subpath
-            @api_v5 = Api::Faspex.new(**Oauth.kwargs_from_options(options))
-            # in case user wants to use HTTPGW tell transfer agent how to get address
-            transfer.httpgw_url_cb = lambda{@api_v5.read('account')['gateway_url']}
+        # admin > file_processing > next
+        def action_admin_file_processing_next
+          args = res_exec_args(:file_processing)
+          result, count = @api_v5.list_entities_limit_offset_total_count(entity: args[:entity], operation: 'POST', items_key: 'files')
+          Result::ObjectList.new(result, total: count)
+        end
+
+        # admin > nodes > browse
+        def action_admin_nodes_browse(folder_path:, node_id:, **)
+          browse_folder("nodes/#{node_id}/browse", {}, folder_path: folder_path)
+        end
+
+        # admin > nodes > shared_folders — node_id: already in ctx via arguments: on the :shared_folders command
+        def setup_admin_nodes_shared_folders(node_id:, **)
+          {sf_entity: "nodes/#{node_id}/shared_folders"}
+        end
+
+        # Lookup shared folder id by field/value within a node's shared_folders entity.
+        # sf_entity is in ctx from setup_admin_nodes_shared_folders (Phase A of parent).
+        def lookup_sf_id(field, value, sf_entity:, **)
+          @api_v5.lookup_entity_by_field(entity: sf_entity, items_key: 'shared_folders', field: field, value: value)['id']
+        end
+
+        # Lookup custom access user id by field/value within a shared folder's users entity.
+        # user_path is in ctx from setup_admin_nodes_shared_folders_user (Phase A of parent).
+        def lookup_sf_user_id(field, value, user_path:, **)
+          @api_v5.lookup_entity_by_field(entity: user_path, items_key: 'users', field: field, value: value)['id']
+        end
+
+        # admin > nodes > shared_folders > user — sf_id: already in ctx via arguments: on the :user command
+        def setup_admin_nodes_shared_folders_user(sf_entity:, sf_id:, **)
+          {user_path: "#{sf_entity}/#{sf_id}/custom_access_users"}
+        end
+
+        # admin > shared_inboxes|workgroups — res_id: already in ctx via arguments: on the :members|:saml_groups command
+        %i[shared_inboxes workgroups].each do |res|
+          define_method(:"setup_admin_#{res}_instance") do |**kwargs|
+            res_id = kwargs[:"#{RES_SINGULAR[res]}_id"]
+            {
+              res_instance_path: "#{res}/#{res_id}",
+              saml_groups_path:  "#{res}/#{res_id}/saml_groups"
+            }
           end
-          case command
-          when :version
-            return Result::SingleObject.new(@api_v5.read('version'))
-          when :health
-            nagios = Nagios.new
-            begin
-              data, http = Rest.new(base_url: options.get_option(:url, mandatory: true))
-                .read('health', ret: :both)
-              data.each do |k, v|
-                nagios.add_ok(k, v.to_s)
-              end
-              nagios.add_ok('version', http['X-IBM-Aspera']) if http['X-IBM-Aspera']
-            rescue StandardError => e
-              nagios.add_critical('core', e.to_s)
-            end
-            Result::ObjectList.new(nagios.status_list)
-          when :user
-            case options.get_next_command(%i[account profile])
-            when :account
-              return Result::SingleObject.new(@api_v5.read('account', query_read_delete))
-            when :profile
-              case options.get_next_command(%i[show modify])
-              when :show
-                return Result::SingleObject.new(@api_v5.read('account/preferences'))
-              when :modify
-                @api_v5.update('account/preferences', options.get_next_argument('modified parameters', validation: Hash))
-                return Result::Status.new('modified')
-              end
-            end
-          when :bearer_token
-            return Result::Text.new(@api_v5.oauth.authorization)
-          when :packages
-            return package_action
-          when :shared_folders
-            all_shared_folders = @api_v5.read('shared_folders')['shared_folders']
-            case options.get_next_command(%i[list browse])
-            when :list
-              return Result::ObjectList.new(all_shared_folders)
-            when :browse
-              shared_folder_id = options.instance_identifier do |field, value|
-                matches = all_shared_folders.select{ |i| i[field].eql?(value)}
-                raise "no match for #{field} = #{value}" if matches.empty?
-                raise "multiple matches for #{field} = #{value}" if matches.length > 1
-                matches.first['id']
-              end
-              node = all_shared_folders.find{ |i| i['id'].eql?(shared_folder_id)}
-              raise "No such shared folder id #{shared_folder_id}" if node.nil?
-              return browse_folder("nodes/#{node['node_id']}/shared_folders/#{shared_folder_id}/browse")
-            end
-          when :admin
-            return execute_admin
-          when :invitations
-            invitation_endpoint = 'invitations'
-            invitation_command = options.get_next_command(%i[resend].concat(Operations::ALL))
-            case invitation_command
-            when :create
-              return do_bulk_operation(command: invitation_command, descr: 'data') do |params|
-                invitation_endpoint = params.key?('recipient_name') ? 'public_invitations' : 'invitations'
-                @api_v5.create(invitation_endpoint, params)
-              end
-            when :resend
-              @api_v5.create("#{invitation_endpoint}/#{options.instance_identifier}/resend", nil)
-              return Result::Status.new('Invitation resent')
+        end
+
+        # Resolve user ids for shared_inbox/workgroup members/create, handling percent selectors.
+        # @param users [Array] raw user ids or percent-selector strings
+        # @return [Array<String>] resolved user ids
+        def resolve_member_user_ids(users)
+          users = [users] unless users.is_a?(Array)
+          users.map do |user|
+            if (m = Parser.percent_selector(user))
+              @api_v5.lookup_entity_by_field(entity: 'accounts', field: m[:field], value: m[:value], query: Rest.php_style({type: ACCOUNT_TYPES}))['id']
             else
-              return entity_execute(
-                api: @api_v5,
-                entity: invitation_endpoint,
-                command: invitation_command,
-                items_key: invitation_endpoint,
-                display_fields: %w[id public recipient_type recipient_name email_address]
-              ) do |field, value|
-                @api_v5.lookup_entity_by_field(entity: invitation_endpoint, field: field, value: value, query: {})['id']
-              end
+              user
             end
-          when :gateway
-            require 'aspera/faspex_gw'
-            parameters = value_create_modify(command: command, default: {}).symbolize_keys
-            uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
-            server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-            Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?){"unexpected parameters: #{parameters.except(*WebServerSimple::PARAMS).keys}"}
-            server.mount(uri.path, Faspex4GWServlet, @api_v5, nil)
-            server.start
-            return Result::Status.new('Gateway terminated')
-          when :postprocessing
-            require 'aspera/faspex_postproc' # cspell:disable-line
-            parameters = value_create_modify(command: command, default: {}).symbolize_keys
-            uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
-            parameters[:root] = uri.path
-            server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-            server.mount(uri.path, Faspex4PostProcServlet, parameters.except(*WebServerSimple::PARAMS))
-            server.start
-            return Result::Status.new('Gateway terminated')
           end
         end
+
+        # Lookup methods for members/saml_groups identity resolution (used by arguments: lookup:)
+        # res_instance_path is in ctx from setup_admin_{res}_instance (Phase A of parent).
+        %i[shared_inboxes workgroups].each do |res|
+          define_method(:"lookup_#{res}_members_id") do |field, value, res_instance_path:, **|
+            res_path = "#{res_instance_path}/members"
+            @api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
+          end
+          define_method(:"lookup_#{res}_saml_groups_id") do |field, value, res_instance_path:, **|
+            res_path = "#{res_instance_path}/saml_groups"
+            @api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
+          end
+        end
+
+        # admin > shared_inboxes|workgroups > members > create/list/modify/delete
+        # (saml_groups CRUD is handled by crud_commands)
+        %i[shared_inboxes workgroups].each do |res|
+          define_action_method([:admin, res, :members, :list]) do |res_instance_path:, **|
+            entity_list(api: @api_v5, entity: "#{res_instance_path}/members", items_key: 'members')
+          end
+
+          define_action_method([:admin, res, :members, :modify]) do |res_instance_path:, **kwargs|
+            entity_modify(api: @api_v5, entity: "#{res_instance_path}/members", id: kwargs[:member_id])
+          end
+
+          define_action_method([:admin, res, :members, :delete]) do |res_instance_path:, **kwargs|
+            entity_delete(api: @api_v5, entity: "#{res_instance_path}/members", id: kwargs[:member_id])
+          end
+
+          define_action_method([:admin, res, :members, :create]) do |users:, access:, res_instance_path:, **|
+            res_path = "#{res_instance_path}/members"
+            resolved = resolve_member_user_ids(users)
+            input_data = [{user: resolved.map { |u| {id: u, access: access} }}]
+            entity_create(api: @api_v5, entity: res_path, input_data: input_data)
+          end
+        end
+
+        # admin > shared_inboxes|workgroups > invite_external_collaborator
+        %i[shared_inboxes workgroups].each do |res|
+          define_action_method([:admin, res, :invite_external_collaborator]) do |input_data:, **kwargs|
+            res_instance_path = "#{res}/#{kwargs[:"#{RES_SINGULAR[res]}_id"]}"
+            result = @api_v5.create("#{res_instance_path}/external_collaborator", input_data)
+            formatter.display_status(result['message'])
+            Result::SingleObject.new(@api_v5.lookup_entity_by_field(entity: "#{res_instance_path}/members", items_key: 'members', value: input_data['email_address'], query: {}))
+          end
+        end
+
+        # --- root setup ---
+
+        # Build @api_v5 for all commands that need it (all except :health and :postprocessing).
+        # @return [Hash] empty ctx (state stored in @api_v5)
+        def setup_api_v5(**)
+          return {} if @api_v5
+          @api_v5 = Api::Faspex.new(**Oauth.kwargs_from_options(options))
+          # in case user wants to use HTTPGW tell transfer agent how to get address
+          transfer.httpgw_url_cb = lambda { @api_v5.read('account')['gateway_url'] }
+          {}
+        end
+
+        # Setup for package sub-commands that need an id: resolves package_id from pub_link or argument.
+        # @return [Hash] ctx key: package_id
+        def setup_package_id(**)
+          package_id = @api_v5.pub_link_context&.key?('package_id') ? @api_v5.pub_link_context['package_id'] : options.instance_identifier
+          {package_id: package_id}
+        end
+
+        def action_packages_list(filter: nil, **)
+          list, max_items, total = list_packages_with_filter(filter: filter)
+          list = list[0, max_items] if max_items
+          fields = %w[id title status sender.name recipients.0.name release_date total_bytes total_files]
+          fields.delete('recipients.0.name') if %w[inbox inbox_history].include?(options.get_option(:box))
+          fields.delete('sender.name') if %w[outbox outbox_history].include?(options.get_option(:box))
+          Result::ObjectList.new(list, total: total, fields: fields)
+        end
+
+        def action_packages_delete(package_id:, **)
+          ids = package_id.is_a?(Array) ? package_id : [package_id]
+          Aspera.assert_array_all(ids, String) { 'Package id(s)' }
+          # API returns 204, empty on success
+          @api_v5.call(
+            operation:    'DELETE',
+            subpath:      'packages',
+            content_type: Mime::JSON,
+            body:         {ids: ids},
+            headers:      {'Accept' => Mime::JSON}
+          )
+          Result::Status.new('Package(s) deleted')
+        end
+
+        # --- handlers ---
+
+        def action_health
+          nagios = Nagios.new
+          begin
+            data, http = Rest.new(base_url: options.get_option(:url, mandatory: true))
+              .read('health', ret: :both)
+            data.each do |k, v|
+              nagios.add_ok(k, v.to_s)
+            end
+            nagios.add_ok('version', http['X-IBM-Aspera']) if http['X-IBM-Aspera']
+          rescue StandardError => e
+            nagios.add_critical('core', e.to_s)
+          end
+          Result::ObjectList.new(nagios.status_list)
+        end
+
+        # Lookup a shared folder id by field/value.
+        # Called via lookup: :lookup_shared_folder_id on the shared_folders > browse command.
+        def lookup_shared_folder_id(field, value, **)
+          all = @api_v5.read('shared_folders')['shared_folders']
+          matches = all.select { |i| i[field].eql?(value) }
+          Aspera.assert(!matches.empty?) { "no match for #{field} = #{value}" }
+          Aspera.assert(matches.length == 1) { "multiple matches for #{field} = #{value}" }
+          matches.first['id']
+        end
+
+        def action_shared_folders_browse(folder_path:, shared_folder_id:, **)
+          all_shared_folders = @api_v5.read('shared_folders')['shared_folders']
+          node = all_shared_folders.find { |i| i['id'].eql?(shared_folder_id) }
+          Aspera.assert(!node.nil?) { "No such shared folder id #{shared_folder_id}" }
+          browse_folder("nodes/#{node['node_id']}/shared_folders/#{shared_folder_id}/browse", {}, folder_path: folder_path)
+        end
+
+        # invitations sub-handlers
+
+        def action_invitations_resend(invitation_id:, **)
+          @api_v5.create("invitations/#{invitation_id}/resend", nil)
+          Result::Status.new('Invitation resent')
+        end
+
+        def action_invitations_create(input_data:, **)
+          bulk_result(input_data, command: :create) do |params|
+            endpoint = params.key?('recipient_name') ? 'public_invitations' : 'invitations'
+            @api_v5.create(endpoint, params)
+          end
+        end
+
+        def action_gateway(parameters: {}, **)
+          require 'aspera/faspex_gw'
+          parameters = parameters.symbolize_keys
+          uri = URI.parse(parameters.delete(:url) { WebServerSimple::DEFAULT_URL })
+          server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
+          Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?) { "unexpected parameters: #{parameters.except(*WebServerSimple::PARAMS).keys}" }
+          server.mount(uri.path, Faspex4GWServlet, @api_v5, nil)
+          server.start
+          Result::Status.new('Gateway terminated')
+        end
+
+        def action_postprocessing(parameters: {}, **)
+          require 'aspera/faspex_postproc' # cspell:disable-line
+          parameters = parameters.symbolize_keys
+          uri = URI.parse(parameters.delete(:url) { WebServerSimple::DEFAULT_URL })
+          parameters[:root] = uri.path
+          server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
+          server.mount(uri.path, Faspex4PostProcServlet, parameters.except(*WebServerSimple::PARAMS))
+          server.start
+          Result::Status.new('Gateway terminated')
+        end
         SHARED_INBOX_MEMBER_LEVELS = %i[submit_only standard shared_inbox_admin].freeze
         ACCOUNT_TYPES = %w{local_user saml_user self_registered_user external_user}.freeze
         WORKGROUP_TYPES = %w{workgroup shared_inbox}.freeze
         CONTACT_TYPES = (WORKGROUP_TYPES + %w{distribution_list user external_user}).freeze
         PACKAGE_RECIPIENT_TYPES = %i{recipients private_recipients notified_on_upload notified_on_download notified_on_receipt}
-        private_constant :SHARED_INBOX_MEMBER_LEVELS, :ACCOUNT_TYPES, :CONTACT_TYPES, :PACKAGE_RECIPIENT_TYPES
+        private_constant :SHARED_INBOX_MEMBER_LEVELS, :ACCOUNT_TYPES, :CONTACT_TYPES, :PACKAGE_RECIPIENT_TYPES,
+          :CRUD_NO_SHOW, :CRUD_NO_LIST
       end
     end
   end