aspera-cli 4.27.0 → 4.27.2

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

@@ -2,6 +2,7 @@
 
 # spellchecker: ignore workgroups mypackages passcode
 
+require 'aspera/schema/registry'
 require 'aspera/cli/plugins/oauth'
 require 'aspera/cli/extended_value'
 require 'aspera/transfer/result'
@@ -46,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
@@ -80,14 +81,12 @@ 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'
           }
@@ -108,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']
@@ -169,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 =
@@ -182,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
@@ -216,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 = {}
@@ -279,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')
@@ -325,13 +337,13 @@ module Aspera
         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
@@ -358,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?
@@ -377,26 +389,27 @@ module Aspera
         end
 
         # Per-resource configuration for admin CRUD sub-trees.
-        # Keys mirror entity_execute kwargs; extra_commands lists additional leaf commands.
+        # 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')},
+            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: :lookup_accounts_id}]}},
-            query_component:       Schema::Registry::FASPEX
+            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},
+          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},
+          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],
-            schema:       ->{Schema::Registry.req_body(Schema::Registry::FASPEX, 'file_processing.put')},
-            is_singleton: true
+            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},
+          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: {
@@ -405,19 +418,21 @@ module Aspera
                             {name: :folder_path, type: String, mandatory: false, default: '/'}]
               }
             },
-            query_component:       Schema::Registry::FASPEX
+            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))},
+            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
+            query_component: Schema::Registry::FASPEX,
+            body_component:  Schema::Registry::FASPEX
           },
           registrations:       {query_component: Schema::Registry::FASPEX},
-          saml_configs:        {query_component: Schema::Registry::FASPEX},
-          shared_inboxes:      {res_id_query: {'all': true}, query_component: Schema::Registry::FASPEX},
-          webhooks:            {query_component: Schema::Registry::FASPEX},
-          workgroups:          {res_id_query: {'all': true}, 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
 
@@ -427,7 +442,7 @@ module Aspera
           v.is_a?(Proc) ? instance_exec(&v) : v
         end
 
-        # Build exec_args hash for entity_execute from RESOURCE_CONFIG for the given resource.
+        # 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, {})
           {
@@ -439,33 +454,16 @@ module Aspera
             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,
-            schema:          resource_config_value(cfg, :schema),
-            query_component: resource_config_value(cfg, :query_component)
+            query_component: resource_config_value(cfg, :query_component),
+            body_component:  resource_config_value(cfg, :body_component)
           }.compact
         end
 
-        # Lookup methods for arguments: + lookup: on specific nodes
-
         # 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
 
-        # admin > shared_inboxes — lookup id by field/value
-        def lookup_shared_inboxes_id(field, value, **)
-          @api_v5.lookup_entity_by_field(entity: 'shared_inboxes', field: field, value: value, query: {'all': true})['id']
-        end
-
-        # admin > workgroups — lookup id by field/value
-        def lookup_workgroups_id(field, value, **)
-          @api_v5.lookup_entity_by_field(entity: 'workgroups', field: field, value: value, query: {'all': true})['id']
-        end
-
-        # admin > accounts — lookup id by field/value (used for reset_password arguments:)
-        def lookup_accounts_id(field, value, **)
-          res_lookup_id(:accounts, field, value)
-        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, {})
@@ -475,32 +473,38 @@ module Aspera
           @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
+
         # --- 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 :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'
+        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)}
+            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}"))}
+            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,
+            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 package(s)', setup: :setup_package_id
+            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)}
+            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)
@@ -515,25 +519,28 @@ module Aspera
           arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
         command :invitations,    description: 'Manage invitations', setup: :setup_api_v5
 
-        commands_under(:invitations) do
+        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}]
-          Operations::ALL.reject{ |op| op == :create}.each do |op|
-            command(op, description: "#{op.capitalize} invitation(s)")
-          end
+          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))}
+        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'))}
+        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',
+            :modify,
+            description: 'Modify user profile',
             arguments: [{name: :properties, type: Hash}],
             action: lambda do |properties:, **|
               @api_v5.update('account/preferences', properties)
@@ -542,15 +549,15 @@ module Aspera
           )
         end
 
-        commands_under(:shared_folders) do
-          command :list,   description: 'List shared folders', action: ->{Result::ObjectList.new(@api_v5.read('shared_folders')['shared_folders'])}
+        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
+        commands_under :admin do
           command :configuration, description: 'Manage Faspex 5 configuration'
           command :smtp,          description: 'Manage SMTP configuration'
           command :events,        description: 'List events'
@@ -559,127 +566,155 @@ module Aspera
           Api::Faspex::ADMIN_RESOURCES.each do |res|
             cfg          = RESOURCE_CONFIG.fetch(res, {})
             extra        = cfg[:extra_commands] || []
-            cmds         = cfg[:commands] || (Operations::ALL + extra)
             ia_cmds      = cfg[:instance_arg_commands] || {}
             is_singleton = cfg[:is_singleton] || false
-            schema_val   = cfg[:schema]
-            command(res, description: "Manage #{res.to_s.tr('_', ' ')}")
-            commands_under([:admin, res]) do
-              cmds.each do |c|
+            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
+
+              # 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] || {}
-                extra_args =
-                  if !is_singleton && c.eql?(:create)
-                    [{name: :input_data, type: Hash, bulk: true, schema: schema_val}]
-                  elsif c.eql?(:modify)
-                    [{name: :input_data, type: Hash, schema: schema_val}]
-                  else
-                    []
-                  end
-                # Merge arguments: from ia (e.g. identifier spec) with extra_args for this operation
-                merged_args = Array(ia[:arguments]) + extra_args
-                spec_kwargs = merged_args.empty? ? ia.except(:arguments) : ia.except(:arguments).merge(arguments: merged_args)
-                # Attach query_schema (full path) to :list/:delete CommandSpec so --help shows the tip.
-                # cfg[:query_component] is always a String constant so direct read is safe here (no Proc).
-                if QUERY_SCHEMA_COMMANDS.include?(c) && cfg[:query_component]
-                  entity_path = cfg[:entity] || res.to_s
-                  spec_kwargs = spec_kwargs.merge(
-                    query_schema: Schema::Registry.query_params(cfg[:query_component], entity_path)
-                  )
-                end
-                command(c, description: c.to_s.tr('_', ' ').capitalize, **spec_kwargs)
+                command c, description: c.to_s.tr('_', ' ').capitalize, **ia
               end
             end
           end
         end
 
-        commands_under(%i[admin nodes]) do
+        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
-        commands_under(%i[admin nodes shared_folders]) do
-          Operations::ALL.each{ |c| command(c, description: c.to_s.tr('_', ' ').capitalize)}
+        # 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)
-        commands_under(%i[admin nodes shared_folders user]) do
-          Operations::ALL.each{ |c| command(c, description: c.to_s.tr('_', ' ').capitalize)}
+        # 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
 
-        MEMBER_SUBS = %i[members saml_groups].freeze
+        # `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|
-          MEMBER_SUBS.each do |sub|
-            commands_under([:admin, res]) do
-              command sub, description: sub.to_s.tr('_', ' ').capitalize,
-                arguments: [{name: :res_id, type: :identifier, lookup: :"lookup_#{res}_id"}],
-                setup: :"setup_admin_#{res}_instance"
-            end
-            commands_under([:admin, res, sub]) do
-              CRUD_NO_SHOW.each do |c|
-                args = if c.eql?(:create) && sub.eql?(:members)
+          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
                   {}
                 end
-                command(c, description: c.to_s.capitalize, **args)
-              end
+              command c, description: c.to_s.capitalize, **args
             end
           end
-          commands_under([:admin, res]) do
-            command :invite_external_collaborator, description: 'Invite external collaborator',
-              arguments: [{name: :res_id, type: :identifier, lookup: :"lookup_#{res}_id"},
-                          {name: :input_data, type: Hash}]
+
+          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',
+        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))}
-          )
+            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',
+        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',
+            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))}
+            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
           )
-          command(:delete, description: 'Delete SMTP configuration', action: lambda do
-            @api_v5.delete('configuration/smtp')
-            Result::Status.new('SMTP configuration deleted')
-          end)
           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)
-            Result::ObjectList.new(list, total: total, fields: %w[event_type created_at application user.name])
-          end)
-          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, items_key: 'events')
-            Result::ObjectList.new(list, total: total)
-          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
+          )
+          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)
@@ -705,19 +740,6 @@ module Aspera
           end
         end
 
-        # admin > <resource> > create / modify / delete / show
-        Api::Faspex::ADMIN_RESOURCES.each do |res|
-          CRUD_NO_LIST.each do |op|
-            define_action_method([:admin, res, op]) do |input_data: nil, res_id: nil, **|
-              args = res_exec_args(res)
-              is_bulk = options.get_option(:bulk)
-              items = input_data
-              items = [items] if items && !items.is_a?(Array)
-              entity_execute(command: op, input_data: items, res_id: res_id, is_bulk: is_bulk, bfail: options.get_option(:bfail), **args){ |f, v| res_lookup_id(res, f, v)}
-            end
-          end
-        end
-
         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)
@@ -754,17 +776,15 @@ module Aspera
         end
 
         # Lookup shared folder id by field/value within a node's shared_folders entity.
-        # Used as lookup: on the :user command under admin > nodes > shared_folders.
-        # sf_entity is available in ctx because setup_admin_nodes_shared_folders ran first (Phase A of parent).
+        # 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
 
-        # admin > nodes > shared_folders > create/modify/delete/show/list
-        Operations::ALL.each do |op|
-          define_action_method([:admin, :nodes, :shared_folders, op]) do |sf_entity:, **|
-            entity_execute(api: @api_v5, entity: sf_entity, items_key: 'shared_folders', command: op){ |f, v| @api_v5.lookup_entity_by_field(entity: sf_entity, items_key: 'shared_folders', field: f, value: v)['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
@@ -772,17 +792,14 @@ module Aspera
           {user_path: "#{sf_entity}/#{sf_id}/custom_access_users"}
         end
 
-        # admin > nodes > shared_folders > user > create/modify/delete/show/list (custom access users)
-        Operations::ALL.each do |op|
-          define_action_method([:admin, :nodes, :shared_folders, :user, op]) do |user_path:, **|
-            entity_execute(api: @api_v5, entity: user_path, items_key: 'users', command: op){ |f, v| @api_v5.lookup_entity_by_field(entity: user_path, items_key: 'users', field: f, value: v)['id']}
-          end
-        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 |res_id:, **|
-            {res_instance_path: "#{res}/#{res_id}"}
+          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
         end
 
@@ -800,37 +817,46 @@ module Aspera
           end
         end
 
-        # admin > shared_inboxes|workgroups > members|saml_groups > create/list/modify/delete
+        # 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|
-          MEMBER_SUBS.each do |sub|
-            CRUD_NO_SHOW.each do |op|
-              if op.eql?(:create) && sub.eql?(:members)
-                define_action_method([:admin, res, sub, op]) do |users:, access:, res_instance_path:, **|
-                  res_path = "#{res_instance_path}/#{sub}"
-                  list_key = sub.eql?(:saml_groups) ? 'groups' : sub.to_s
-                  resolved = resolve_member_user_ids(users)
-                  input_data = [{user: resolved.map{ |u| {id: u, access: access}}}]
-                  entity_execute(api: @api_v5, entity: res_path, command: op, input_data: input_data, items_key: list_key) do |f, v|
-                    @api_v5.lookup_entity_by_field(entity: res_path, field: f, value: v, query: Rest.php_style({type: %w[user]}))['user_id']
-                  end
-                end
-              else
-                define_action_method([:admin, res, sub, op]) do |res_instance_path:, **|
-                  res_path = "#{res_instance_path}/#{sub}"
-                  list_key = sub.eql?(:saml_groups) ? 'groups' : sub.to_s
-                  entity_execute(api: @api_v5, entity: res_path, command: op, items_key: list_key) do |f, v|
-                    @api_v5.lookup_entity_by_field(entity: res_path, field: f, value: v, query: Rest.php_style({type: %w[user]}))['user_id']
-                  end
-                end
-              end
-            end
+          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:, res_id:, **|
-            res_instance_path = "#{res}/#{res_id}"
+          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: {}))
@@ -845,7 +871,7 @@ module Aspera
           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']}
+          transfer.httpgw_url_cb = lambda { @api_v5.read('account')['gateway_url'] }
           {}
         end
 
@@ -856,8 +882,9 @@ module Aspera
           {package_id: package_id}
         end
 
-        def action_packages_list
-          list, total = list_packages_with_filter
+        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))
@@ -866,7 +893,7 @@ module Aspera
 
         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)'}
+          Aspera.assert_array_all(ids, String) { 'Package id(s)' }
           # API returns 204, empty on success
           @api_v5.call(
             operation:    'DELETE',
@@ -899,16 +926,16 @@ module Aspera
         # 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 = 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}"}
+          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
 
@@ -920,34 +947,18 @@ module Aspera
         end
 
         def action_invitations_create(input_data:, **)
-          is_bulk = options.get_option(:bulk)
-          Result.bulk(input_data, is_bulk: is_bulk, command: :create, bfail: options.get_option(:bfail)) do |params|
+          bulk_result(input_data, command: :create) do |params|
             endpoint = params.key?('recipient_name') ? 'public_invitations' : 'invitations'
             @api_v5.create(endpoint, params)
           end
         end
 
-        # CRUD handlers for invitations (list, show, modify, delete)
-        Operations::ALL.reject{ |op| op == :create}.each do |op|
-          define_action_method([:invitations, op]) do
-            entity_execute(
-              api: @api_v5,
-              entity: 'invitations',
-              command: op,
-              items_key: 'invitations',
-              display_fields: %w[id public recipient_type recipient_name email_address]
-            ) do |field, value|
-              @api_v5.lookup_entity_by_field(entity: 'invitations', field: field, value: value, query: {})['id']
-            end
-          end
-        end
-
         def action_gateway(parameters: {}, **)
           require 'aspera/faspex_gw'
           parameters = parameters.symbolize_keys
-          uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
+          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}"}
+          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')
@@ -956,7 +967,7 @@ module Aspera
         def action_postprocessing(parameters: {}, **)
           require 'aspera/faspex_postproc' # cspell:disable-line
           parameters = parameters.symbolize_keys
-          uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
+          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))
@@ -969,7 +980,7 @@ module Aspera
         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,
-          :MEMBER_SUBS, :CRUD_NO_SHOW, :CRUD_NO_LIST
+          :CRUD_NO_SHOW, :CRUD_NO_LIST
       end
     end
   end