aspera-cli 4.27.0 → 4.27.1

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

@@ -102,8 +102,8 @@ module Aspera
           # @param destination_folder [String] Base folder
           # @param fld                [Array]  List of fields of package
           def unique_folder(package_info, destination_folder, fld: nil, seq: false, opt: false)
-            Aspera.assert_array_all(fld, String, type: BadArgument){'fld'}
-            Aspera.assert_values(fld.length, [1, 2]){'fld length'}
+            Aspera.assert_array_all(fld, String, type: BadArgument) { 'fld' }
+            Aspera.assert_values(fld.length, [1, 2]) { 'fld length' }
             folder = Environment.instance.sanitized_filename(package_info[fld[0]])
             if seq
               folder = next_available_folder(folder, always: !opt)
@@ -113,6 +113,71 @@ module Aspera
             end
             File.join(destination_folder, folder)
           end
+
+          # @return [String] AoC REST path for an admin resource type
+          def aoc_res_path(res)
+            cfg = ADMIN_OBJECT_CONFIG.fetch(res, {})
+            return cfg[:path] if cfg[:path]
+            "#{res}s".gsub(/ys$/, 'ies')
+          end
+
+          # @return [Hash] {path:, ops:, id_result:, require_ws_id:, list_fields:, schema:, query_component:}
+          def aoc_res_cfg(res)
+            cfg    = ADMIN_OBJECT_CONFIG.fetch(res, {})
+            path   = aoc_res_path(res)
+            ops    = cfg[:ops] || (Base::Operations::ALL + (cfg[:extra_ops] || []))
+            schema = cfg[:create_schema] == false ? nil : Schema::Registry.req_body(Schema::Registry::AOC, "#{path}.post")
+            {
+              path:            path,
+              ops:             ops,
+              id_result:       cfg[:id_result] || 'id',
+              require_ws_id:   cfg[:require_ws_id] || false,
+              list_fields:     cfg.key?(:list_fields) ? cfg[:list_fields] : %w[id name],
+              schema:          schema,
+              query_component: Schema::Registry::AOC
+            }
+          end
+
+          # DSL helper: register the 5 short_link leaf commands under the given parent path
+          # and define the corresponding action methods on `base`.
+          # @param base        [Class]         the plugin class
+          # @param parent_path [Array<Symbol>] full path ending with :short_link
+          def register_short_link_commands(base, parent_path)
+            base.commands_under(parent_path) do
+              base.command(
+                :create, description: 'Create',
+                arguments: [{name: :custom_data, type: Hash, mandatory: false, default: {}}]
+              )
+              base.command(
+                :modify, description: 'Modify',
+                arguments: [{name: :short_link_id, type: :identifier}, {name: :custom_data, type: Hash, mandatory: false, default: {}}]
+              )
+              base.command(:list, description: 'List short links')
+              base.command(
+                :show, description: 'Show a short link',
+                arguments: [{name: :short_link_id, type: :identifier}]
+              )
+              base.command(
+                :delete, description: 'Delete a short link',
+                arguments: [{name: :short_link_id, type: :identifier}]
+              )
+            end
+            base.define_action_method(parent_path + [:create]) do |custom_data: {}, **ctx|
+              sl_exec_create(custom_data, **ctx)
+            end
+            base.define_action_method(parent_path + [:list]) do |**ctx|
+              sl_exec_list(**sl_fetch_list(**ctx))
+            end
+            base.define_action_method(parent_path + [:show]) do |**ctx|
+              sl_exec_show(**sl_fetch_list(**ctx))
+            end
+            base.define_action_method(parent_path + [:delete]) do |**ctx|
+              sl_exec_delete(**sl_fetch_list(**ctx), **ctx)
+            end
+            base.define_action_method(parent_path + [:modify]) do |custom_data: {}, **ctx|
+              sl_exec_modify(custom_data, **sl_fetch_list(**ctx), **ctx)
+            end
+          end
         end
 
         # @param wizard  [Wizard] The wizard object
@@ -133,7 +198,7 @@ module Aspera
               test_args:    'organization'
             }
           end
-          options.declare(:use_generic_client, description: 'Wizard: AoC: use global or org specific jwt client id', allowed: Allowed::TYPES_BOOLEAN, default: Api::AoC.saas_url?(app_url))
+          options.declare(:use_generic_client, description: 'Wizard: AoC: use global or org specific jwt client id', allowed: Type::BOOLEAN, default: Api::AoC.saas_url?(app_url))
           options.parse_options!
           # make username mandatory for jwt, this triggers interactive input
           wiz_username = options.get_option(:username, mandatory: true)
@@ -203,9 +268,11 @@ module Aspera
 
         option :workspace,         description: 'Name of workspace', allowed: [String, NilClass], default: Api::AoC::DEFAULT_WORKSPACE
         option :new_user_option,   description: 'New user creation option for unknown package recipients', allowed: [Hash, NilClass]
-        option :validate_metadata, description: 'Validate shared inbox metadata', allowed: Allowed::TYPES_BOOLEAN, default: true
+        option :validate_metadata, description: 'Validate shared inbox metadata', allowed: Type::BOOLEAN, default: true
         option :package_folder,    schema: Schema::Registry::PACKAGE_FOLDER_OPTIONS
 
+        use_options Node
+
         def initialize(**_)
           super
           @cache_workspace_info = nil
@@ -213,8 +280,6 @@ module Aspera
           @cache_api_aoc = nil
           @scope = Api::AoC::Scope::USER
           options.parse_options!
-          # add node plugin options (for manual)
-          Node.declare_options(options)
         end
 
         # Change API scope for subsequent calls, re-instantiate API object
@@ -244,7 +309,7 @@ module Aspera
             case m[:field]
             when 'name' then api.ws_ids[:name] = m[:value]
             when 'id' then api.ws_ids[:id] = m[:value]
-            else Aspera.error_unexpected_value(m[:field]){'workspace selector: only `name` or `id`'}
+            else Aspera.error_unexpected_value(m[:field]) { 'workspace selector: only `name` or `id`' }
             end
           else
             api.ws_ids[:name] = workspace
@@ -292,7 +357,7 @@ module Aspera
         # @return [String] identifier
         def get_resource_id_from_args(resource_class_path)
           return options.instance_identifier do |field, value|
-            Aspera.assert_values(field, ['name'], type: BadArgument){'selector field'}
+            Aspera.assert_values(field, ['name'], type: BadArgument) { 'selector field' }
             aoc_api.lookup_with_q(resource_class_path, value: value)['id']
           end
         end
@@ -324,7 +389,7 @@ module Aspera
         def resolve_dropbox_name_default_ws_id(query)
           if query.key?('dropbox_name')
             # convenience: specify name instead of id
-            Aspera.assert(!query.key?('dropbox_id'), type: BadArgument){'Use field dropbox_name or dropbox_id, not both'}
+            Aspera.assert(!query.key?('dropbox_id'), type: BadArgument) { 'Use field dropbox_name or dropbox_id, not both' }
             # TODO : craft a query that looks for dropbox only in current workspace
             query['dropbox_id'] = aoc_api.lookup_with_q('dropboxes', value: query.delete('dropbox_name'))['id']
           end
@@ -333,26 +398,34 @@ module Aspera
           query['exclude_dropbox_packages'] = !query.key?('dropbox_id') unless query.key?('exclude_dropbox_packages')
         end
 
-        # List all packages according to `query` option.
-        # @return [Hash] {items,total} with all packages according to combination of user's query and default query
+        # List all packages from the API using the current `--query` option.
+        # 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.
+        # @return [Array(Hash, Integer, nil)] [{items:,total:} paging result, max (or nil)]
         def list_all_packages_with_query
-          query = query_read_delete(default: {})
-          Aspera.assert_type(query, Hash){'query'}
-          PACKAGE_RECEIVED_BASE_QUERY.each{ |k, v| query[k] = v unless query.key?(k)}
+          query = query_read_delete(default: {}, schema: Schema::Registry.query_params(Schema::Registry::AOC, 'packages'))
+          Aspera.assert_type(query, Hash) { 'query' }
+          PACKAGE_RECEIVED_BASE_QUERY.each { |k, v| query[k] = v unless query.key?(k) }
           resolve_dropbox_name_default_ws_id(query)
-          return aoc_api.read_with_paging('packages', query.compact)
+          # Extract `max` before paging so callers can apply it after post-API filtering
+          max_items = query.delete(RestList::MAX_ITEMS)&.to_i
+          return aoc_api.read_with_paging('packages', query.compact), max_items
         end
 
         FILES_COMMANDS = (Node::COMMANDS_GEN4 + %i[transfer]).freeze
 
-        # Execute a node gen4 command starting at given node and file IDs
-        # @param command_repo       [Symbol] Command to execute
+        # Execute a node gen4 command starting at given node and file IDs.
+        # Arguments already resolved by the DSL (e.g. path:) are forwarded via +resolved_args+
+        # and injected into the dispatch context so node.rb does not re-consume them from the CLI.
+        # @param command_repo       [Symbol] Command to execute (from Node::COMMANDS_GEN4 or :transfer)
         # @param node_id            [String] Node identifier
-        # @param file_id            [String] Root file id for the operation. If nil, uses AK root file id.
-        # @param scope              [String] node scope (Node::SCOPE_<USER|ADMIN>), or nil (requires secret)
-        # @param transfer_direction [Symbol] :push or :pull (only for command_repo == :transfer)
-        # @param transfer_source    [String] source folder (only for command_repo == :transfer)
-        def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil, transfer_direction: nil, transfer_source: nil)
+        # @param file_id            [String, nil] Root file id; if nil, the AK root file id is used
+        # @param scope              [String, nil] node scope (Node::Scope::USER/ADMIN), or nil (requires secret)
+        # @param transfer_direction [Symbol, nil] :push or :pull (only for command_repo == :transfer)
+        # @param transfer_source    [String, nil] source folder  (only for command_repo == :transfer)
+        # @param resolved_args      [Hash] already-resolved CLI arguments (e.g. path:) forwarded to dispatch
+        def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil, transfer_direction: nil, transfer_source: nil, **resolved_args)
           top_node_api = aoc_api.node_api_from(
             node_id:        node_id,
             scope:          scope,
@@ -364,8 +437,8 @@ module Aspera
           when *Node::COMMANDS_GEN4
             # For permission: the handler consumes the path first then re-dispatches to sub-commands.
             # Calling dispatch_from_registry with skip_setup would bypass path consumption and fail.
-            return node_plugin.send(:"action_access_keys_do_#{command_repo}", do_root_file_id: file_id) if command_repo.eql?(:permission)
-            return node_plugin.dispatch_from_registry([:access_keys, :do, command_repo], {do_root_file_id: file_id}, skip_setup: true)
+            return node_plugin.send(:"action_access_keys_do_#{command_repo}", do_root_file_id: file_id, **resolved_args) if command_repo.eql?(:permission)
+            return node_plugin.dispatch_from_registry([:access_keys, :do, command_repo], {do_root_file_id: file_id, **resolved_args}, skip_setup: true)
           when :transfer
             # client side is agent
             # server side is transfer server
@@ -403,7 +476,7 @@ module Aspera
               client_direction,
               add_ts
             )))
-          else Aspera.error_unexpected_value(command_repo){'command'}
+          else Aspera.error_unexpected_value(command_repo) { 'command' }
           end
           Aspera.error_unreachable_line
         end
@@ -440,73 +513,6 @@ module Aspera
         }.freeze
         private_constant :ADMIN_OBJECT_CONFIG
 
-        class << self
-          # @return [String] AoC REST path for an admin resource type
-          def aoc_res_path(res)
-            cfg = ADMIN_OBJECT_CONFIG.fetch(res, {})
-            return cfg[:path] if cfg[:path]
-            "#{res}s".gsub(/ys$/, 'ies')
-          end
-
-          # @return [Hash] {path:, ops:, id_result:, require_ws_id:, list_fields:, schema:, query_component:}
-          def aoc_res_cfg(res)
-            cfg    = ADMIN_OBJECT_CONFIG.fetch(res, {})
-            path   = aoc_res_path(res)
-            ops    = cfg[:ops] || (Base::Operations::ALL + (cfg[:extra_ops] || []))
-            schema = cfg[:create_schema] == false ? nil : Schema::Registry.req_body(Schema::Registry::AOC, "#{path}.post")
-            {
-              path:            path,
-              ops:             ops,
-              id_result:       cfg[:id_result] || 'id',
-              require_ws_id:   cfg[:require_ws_id] || false,
-              list_fields:     cfg.key?(:list_fields) ? cfg[:list_fields] : %w[id name],
-              schema:          schema,
-              query_component: Schema::Registry::AOC
-            }
-          end
-
-          # DSL helper: register the 5 short_link leaf commands under the given parent path
-          # and define the corresponding action methods on `base`.
-          # @param base        [Class]         the plugin class
-          # @param parent_path [Array<Symbol>] full path ending with :short_link
-          def register_short_link_commands(base, parent_path)
-            base.commands_under(parent_path) do
-              base.command(
-                :create, description: 'Create',
-                arguments: [{name: :custom_data, type: Hash, mandatory: false, default: {}}]
-              )
-              base.command(
-                :modify, description: 'Modify',
-                arguments: [{name: :short_link_id, type: :identifier}, {name: :custom_data, type: Hash, mandatory: false, default: {}}]
-              )
-              base.command(:list, description: 'List short links')
-              base.command(
-                :show, description: 'Show a short link',
-                arguments: [{name: :short_link_id, type: :identifier}]
-              )
-              base.command(
-                :delete, description: 'Delete a short link',
-                arguments: [{name: :short_link_id, type: :identifier}]
-              )
-            end
-            base.define_action_method(parent_path + [:create]) do |custom_data: {}, **ctx|
-              sl_exec_create(custom_data, **ctx)
-            end
-            base.define_action_method(parent_path + [:list]) do |**ctx|
-              sl_exec_list(**sl_fetch_list(**ctx))
-            end
-            base.define_action_method(parent_path + [:show]) do |**ctx|
-              sl_exec_show(**sl_fetch_list(**ctx))
-            end
-            base.define_action_method(parent_path + [:delete]) do |**ctx|
-              sl_exec_delete(**sl_fetch_list(**ctx), **ctx)
-            end
-            base.define_action_method(parent_path + [:modify]) do |custom_data: {}, **ctx|
-              sl_exec_modify(custom_data, **sl_fetch_list(**ctx), **ctx)
-            end
-          end
-        end
-
         # Instance delegators so instance methods can call aoc_res_path/aoc_res_cfg without self.class.
         def aoc_res_path(res) = self.class.aoc_res_path(res)
         def aoc_res_cfg(res)  = self.class.aoc_res_cfg(res)
@@ -514,7 +520,7 @@ module Aspera
         # Known fixed set of AoC application types (verified against API: activity, automation, files, packages)
         APP_TYPES = %i[activity automation files packages].freeze
 
-        ADMIN_ACTIONS = %i[bearer_token application ats usage_reports analytics subscription auth_providers].concat(ADMIN_OBJECTS).freeze
+        ADMIN_ACTIONS = (%i[bearer_token application ats usage_reports analytics subscription auth_providers] + ADMIN_OBJECTS).freeze
 
         # Build analytics REST API (shared by action_admin_analytics_*)
         def build_analytics_api
@@ -575,8 +581,8 @@ module Aspera
 
         def reject_packages_from_persistency(all_packages, skip_ids_persistency)
           return if skip_ids_persistency.nil?
-          skip_package = skip_ids_persistency.data.to_h{ |i| [i, true]}
-          all_packages.reject!{ |pkg| skip_package[pkg['id']]}
+          skip_package = skip_ids_persistency.data.to_h { |i| [i, true] }
+          all_packages.reject! { |pkg| skip_package[pkg['id']] }
         end
 
         # --- DSL command declarations ---
@@ -591,31 +597,23 @@ module Aspera
           end
         )
         command :bearer_token,      description: 'Display bearer token',
-          action: ->{Result::Text.new(aoc_api.oauth.authorization)}
+          action: -> { Result::Text.new(aoc_api.oauth.authorization) }
         command :organization,      description: 'Show organization info',
-          action: ->{Result::SingleObject.new(aoc_api.read('organization'))}
+          action: -> { Result::SingleObject.new(aoc_api.read('organization')) }
         command :tier_restrictions, description: 'Show tier restrictions',
-          action: ->{Result::SingleObject.new(aoc_api.read('tier_restrictions'))}
+          action: -> { Result::SingleObject.new(aoc_api.read('tier_restrictions')) }
         command :user,              description: 'User commands'
         command :packages,          description: 'Package commands', setup: :setup_workspace_display
         command :files,             description: 'Files commands (workspace-aware)', setup: :setup_workspace_display
         command :admin, description: 'Administration commands', setup: :setup_admin_scope
-        commands_under(:admin) do
+        commands_under :admin do
           command :bearer_token,   description: 'Show admin bearer token',
-            action: ->{Result::Text.new(aoc_api.oauth.authorization)}
+            action: -> { Result::Text.new(aoc_api.oauth.authorization) }
           command :application,    description: 'Manage applications'
-          command(
-            :ats, description: 'Manage ATS (Aspera Transfer Service)',
-            action: lambda do
-              ats_api = Rest.new(**aoc_api.params.deep_merge({
-                base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
-                auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
-              }))
-              Ats.new(context: context, api: ats_api).execute_action
-            end
-          )
+          command :ats, description: 'Manage ATS (Aspera Transfer Service)',
+            delegate_instance: :build_ats_plugin, delegates_to: []
           command :usage_reports,  description: 'List usage reports',
-            action: ->{result_list('usage_reports', base_query: workspace_id_hash)}
+            action: -> { result_list('usage_reports', base_query: workspace_id_hash) }
           command :auth_providers, description: 'Manage auth providers'
           command :subscription,   description: 'Show subscription info'
           command :analytics,      description: 'Query analytics'
@@ -624,7 +622,7 @@ module Aspera
             op_setup       = cfg[:op_setup] || {}
             extra_op_args  = cfg[:extra_op_args] || {}
             is_singleton   = cfg[:singleton]
-            id_arg_spec    = is_singleton ? [] : [{name: :res_id, type: :identifier, lookup: :"lookup_aoc_#{res}_id"}]
+            id_arg_spec    = is_singleton ? [] : [{name: :"#{res}_id", type: :identifier, lookup: :"lookup_aoc_#{res}_id"}]
             ops            = if cfg[:ops]
               cfg[:ops]
             elsif is_singleton
@@ -632,8 +630,8 @@ module Aspera
             else
               Operations::ALL + (cfg[:extra_ops] || [])
             end
-            command(res, description: "Manage #{res.to_s.tr('_', ' ')}")
-            commands_under([:admin, res]) do
+            command res, description: "Manage #{res.to_s.tr('_', ' ')}"
+            commands_under res do
               ops.each do |op|
                 extra_setup = op_setup[op]
                 base_attrs = extra_setup ? {setup: extra_setup} : {}
@@ -657,13 +655,13 @@ module Aspera
                   c = aoc_res_cfg(res)
                   merged = merged.merge(query_schema: Schema::Registry.query_params(c[:query_component], c[:path]))
                 end
-                command(op, description: op.to_s.tr('_', ' ').capitalize, **merged)
+                command op, description: op.to_s.tr('_', ' ').capitalize, **merged
               end
             end
           end
         end
         # admin > workspace > shared_folder sub-tree
-        commands_under(%i[admin workspace shared_folder]) do
+        commands_under %i[admin workspace shared_folder] do
           command :list,   description: 'List shared folders'
           command :node,   description: 'Execute node command on shared folder',
             arguments: [{name: :sf_id, type: :identifier}],
@@ -672,20 +670,30 @@ module Aspera
             arguments: [{name: :sf_id, type: :identifier}],
             setup: :setup_admin_workspace_shared_folder_member
         end
-        # admin > workspace > shared_folder > node sub-tree (FILES_COMMANDS)
-        commands_under(%i[admin workspace shared_folder node]) do
-          FILES_COMMANDS.each{ |c| command(c, description: c.to_s.tr('_', ' ').capitalize)}
+        # admin > workspace > shared_folder > node sub-tree (Gen4 commands)
+        commands_under %i[admin workspace shared_folder node] do
+          command :transfer,   description: 'Transfer files (node-to-node)'
+          command :permission, description: 'Manage permissions'
+          command :sync,       description: 'Synchronize folders'
+          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
+            command cmd, **spec
+          end
         end
-        commands_under(%i[admin workspace shared_folder member]) do
+        commands_under %i[admin workspace shared_folder member] do
           command :list, description: 'List members of a shared folder'
         end
         # admin > workspace > dropbox sub-tree
-        commands_under(%i[admin workspace dropbox]) do
+        commands_under %i[admin workspace dropbox] do
           command :list, description: 'List dropboxes in workspace'
         end
-        # admin > node > do sub-tree (FILES_COMMANDS)
-        commands_under(%i[admin node do]) do
-          FILES_COMMANDS.each{ |c| command(c, description: c.to_s.tr('_', ' ').capitalize)}
+        # admin > node > do sub-tree (Gen4 commands)
+        commands_under %i[admin node do] do
+          command :transfer,   description: 'Transfer files (node-to-node)'
+          command :permission, description: 'Manage permissions'
+          command :sync,       description: 'Synchronize folders'
+          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
+            command cmd, **spec
+          end
         end
         # admin > user > preferences|notifications sub-trees
         %i[preferences notifications].each do |pref|
@@ -695,12 +703,12 @@ module Aspera
               arguments: [{name: :properties, type: Hash}]
           end
         end
-        commands_under(%i[admin auth_providers]) do
+        commands_under %i[admin auth_providers] do
           command :list, description: 'List auth providers',
-            action: ->{result_list('admin/auth_providers')}
-          command :update, description: 'Update auth provider', action: ->{Aspera.error_not_implemented}
+            action: -> { result_list('admin/auth_providers') }
+          command :update, description: 'Update auth provider', action: -> { Aspera.error_not_implemented }
         end
-        commands_under(%i[admin subscription]) do
+        commands_under %i[admin subscription] do
           command :account, description: 'Show subscription account'
           command :usage,   description: 'Show subscription usage',
             arguments: [
@@ -709,7 +717,7 @@ module Aspera
               {name: :end_date,    mandatory: false, default: nil}
             ]
         end
-        commands_under(%i[admin analytics]) do
+        commands_under %i[admin analytics] do
           command :application_events, description: 'List application events'
           command :transfers,          description: 'List transfer events',
             arguments: [
@@ -724,9 +732,9 @@ module Aspera
             ]
         end
         # application sub-commands
-        commands_under(%i[admin application]) do
+        commands_under %i[admin application] do
           command :types,      description: 'List application types',
-            action: ->{Result::ObjectList.new(aoc_api.read('admin/apps'))}
+            action: -> { Result::ObjectList.new(aoc_api.read('admin/apps')) }
           command :settings,   description: 'Manage per-app-type settings'
           command :instance,   description: 'Manage app instances'
           command :membership, description: 'Manage app memberships'
@@ -734,12 +742,12 @@ module Aspera
         APP_SETTINGS_PATH = %i[admin application settings].freeze
         APP_INSTANCE_PATH = %i[admin application instance].freeze
         private_constant :APP_SETTINGS_PATH, :APP_INSTANCE_PATH
-        commands_under(APP_SETTINGS_PATH) do
+        commands_under APP_SETTINGS_PATH do
           APP_TYPES.each do |app_type|
-            command(app_type, description: "Settings for #{app_type} app")
-            commands_under(APP_SETTINGS_PATH + [app_type]) do
+            command app_type, description: "Settings for #{app_type} app"
+            commands_under app_type do
               command :show, description: "Show #{app_type} settings",
-                action: ->{Result::SingleObject.new(aoc_api.read("/apps/#{app_type}/settings"))}
+                action: -> { Result::SingleObject.new(aoc_api.read("/apps/#{app_type}/settings")) }
               command(
                 :modify, description: "Modify #{app_type} settings",
                 arguments: [{name: :properties, type: Hash}],
@@ -751,7 +759,7 @@ module Aspera
             end
           end
         end
-        commands_under(APP_INSTANCE_PATH) do
+        commands_under APP_INSTANCE_PATH do
           command(:list, description: 'List app instances', action: lambda do
             result_list(
               'admin/apps_new',
@@ -760,64 +768,57 @@ module Aspera
             )
           end)
           APP_TYPES.each do |app_type|
-            command(app_type, description: "Show or modify a #{app_type} instance")
-            commands_under(APP_INSTANCE_PATH + [app_type]) do
+            command app_type, description: "Show or modify a #{app_type} instance"
+            commands_under app_type do
               command :show,   description: "Show a #{app_type} instance",
-                arguments: [{name: :res_id, type: :identifier}]
+                arguments: [{name: :"#{app_type}_id", type: :identifier}]
               command :modify, description: "Modify a #{app_type} instance",
-                arguments: [{name: :res_id, type: :identifier}, {name: :properties, type: Hash}]
+                arguments: [{name: :"#{app_type}_id", type: :identifier}, {name: :properties, type: Hash}]
             end
           end
         end
-        commands_under(%i[admin application membership]) do
-          command :list, description: 'List app memberships',
-            action: ->{result_list('apps/app_memberships')}
-          command :show,   description: 'Show an app membership',
-            arguments: [{name: :res_id, type: :identifier}]
-          command :delete, description: 'Delete an app membership',
-            arguments: [{name: :res_id, type: :identifier}]
-          command :create, description: 'Create an app membership',
-            arguments: [{name: :membership, type: Hash}]
+        commands_under %i[admin application membership] do
+          command :list, description: 'List app memberships', action: -> { result_list('apps/app_memberships') }
+          command :show,   description: 'Show an app membership', arguments: [{name: :membership_id, type: :identifier}]
+          command :delete, description: 'Delete an app membership', arguments: [{name: :membership_id, type: :identifier}]
+          command :create, description: 'Create an app membership', arguments: [{name: :membership, type: Hash}]
         end
         command :automation,        description: 'Automation commands (BETA)', setup: :setup_automation_api
         command :gateway,           description: 'Start AoC Faspex4 gateway',
           arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
 
         # user sub-commands
-        commands_under(:user) do
-          command :workspaces,    description: 'Workspace commands'
-          command :profile,       description: 'User profile commands'
+        commands_under :user do
+          commands_under :workspaces, description: "User's workspaces" do
+            command :list,    description: 'List workspaces', action: -> { result_list('workspaces', fields: %w[id name]) }
+            command :current, description: 'Show current workspace', action: -> { Result::SingleObject.new(aoc_api.workspace_info) }
+          end
+          # command :profile, description: 'User profile commands'
+          commands_under :profile, description: "Manager user's profile" do
+            command :show, description: 'Show user profile', action: -> { Result::SingleObject.new(aoc_api.current_user_info(exception: true)) }
+            command(
+              :modify, description: 'Modify user profile',
+              arguments: [{name: :properties, type: Hash}],
+              action: lambda do |properties:, **|
+                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", properties)
+                Result::Status.new('modified')
+              end
+            )
+          end
           command :preferences,   description: 'User interaction preferences'
           command :notifications, description: 'Notification preferences'
           command :contacts,      description: 'Manage contacts'
-          entity_command :settings, api: :aoc_api, entity: 'client_settings', description: 'Manage client settings'
-        end
-        # user > contacts sub-commands (same CRUD as admin > contact)
-        commands_under(%i[user contacts]) do
-          Operations::ALL.each{ |op| command(op, description: op.to_s.capitalize)}
-        end
-
-        commands_under(%i[user workspaces]) do
-          command :list,    description: 'List workspaces',
-            action: ->{result_list('workspaces', fields: %w[id name])}
-          command :current, description: 'Show current workspace',
-            action: ->{Result::SingleObject.new(aoc_api.workspace_info)}
-        end
-
-        commands_under(%i[user profile]) do
-          command :show, description: 'Show user profile',
-            action: ->{Result::SingleObject.new(aoc_api.current_user_info(exception: true))}
-          command(
-            :modify, description: 'Modify user profile',
-            arguments: [{name: :properties, type: Hash}],
-            action: lambda do |properties:, **|
-              aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", properties)
-              Result::Status.new('modified')
-            end
-          )
+          # user > contacts sub-commands (same CRUD as admin > contact)
+          commands_under %i[contacts] do
+            Operations::ALL.each { |op| command op, description: op.to_s.capitalize }
+          end
+          command :settings, description: 'Manage client settings'
+          commands_under %i[settings] do
+            crud_commands api: :aoc_api, entity: 'client_settings', name: 'client setting'
+          end
         end
 
-        commands_under(%i[user preferences]) do
+        commands_under %i[user preferences] do
           command(
             :show, description: 'Show user preferences',
             action: lambda do
@@ -836,7 +837,7 @@ module Aspera
           )
         end
 
-        commands_under(%i[user notifications]) do
+        commands_under %i[user notifications] do
           command(
             :show, description: 'Show notification preferences',
             action: lambda do
@@ -856,31 +857,31 @@ module Aspera
         end
 
         # packages sub-commands — instance commands consume package_id
-        commands_under(:packages) do
-          command :shared_inboxes,    description: 'Shared inbox commands'
-          command :send,              description: 'Send a package', transfer_paths: :send,
+        commands_under :packages do
+          command :shared_inboxes, description: 'Shared inbox commands'
+          command :send, description: 'Send a package', transfer_paths: :send,
             arguments: [{name: :data, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::AOC, 'packages.post')}]
-          command :receive,           description: 'Receive package(s)', aliases: [:recv], transfer_paths: :receive,
+          command :receive, description: 'Receive packages', aliases: [:recv], transfer_paths: :receive,
             arguments: [{name: :package_id, type: :identifier}]
-          command :list,              description: 'List packages'
-          command :show,              description: 'Show a package',
+          command :list, description: 'List packages'
+          command :show, description: 'Show a package',
             arguments: [{name: :package_id, type: :identifier}]
-          command :delete,            description: 'Delete package(s)',
+          command :delete, description: 'Delete packages',
             arguments: [{name: :package_id, type: :identifier}]
-          command :modify,            description: 'Modify a package',
+          command :modify, description: 'Modify a package',
             arguments: [{name: :package_id, type: :identifier}, {name: :data, type: Hash}]
           # Node Gen4 read-only actions on packages
           command :bearer_token_node, description: 'Show bearer token for package node',
             arguments: [{name: :package_id, type: :identifier}]
           command :node_info,         description: 'Show node info for package',
             arguments: [{name: :package_id, type: :identifier}]
-          command :browse,            description: 'Browse package contents',
+          command :ls,                description: 'List package contents', aliases: [:browse],
             arguments: [{name: :package_id, type: :identifier}]
           command :find,              description: 'Find files in package',
             arguments: [{name: :package_id, type: :identifier}]
         end
 
-        commands_under(%i[packages shared_inboxes]) do
+        commands_under %i[packages shared_inboxes] do
           command :list,       description: 'List shared inboxes',
             action: (lambda do
               result_list(
@@ -891,7 +892,7 @@ module Aspera
             end)
           command :show,       description: 'Show a shared inbox',
             arguments: [{name: :dropbox_id, type: :identifier, lookup: :lookup_aoc_dropbox_id}],
-            action: ->(dropbox_id:, **){Result::SingleObject.new(aoc_api.read("dropboxes/#{dropbox_id}"))}
+            action: ->(dropbox_id:, **) { Result::SingleObject.new(aoc_api.read("dropboxes/#{dropbox_id}")) }
           command :short_link, description: 'Manage shared inbox short links',
             arguments: [{name: :link_type, allowed: %i[public private]}],
             setup: :setup_packages_short_link
@@ -899,61 +900,41 @@ module Aspera
         # packages > shared_inboxes > short_link sub-commands
         register_short_link_commands(self, %i[packages shared_inboxes short_link])
 
-        # files sub-commands: all FILES_COMMANDS + :short_link
-        # Declared dynamically after FILES_COMMANDS is available (class body evaluated after constants)
-        commands_under(:files) do
+        # files sub-commands: AoC-specific commands + all Gen4 commands from COMMANDS_GEN4_SPEC
+        commands_under :files do
           command :short_link, description: 'Manage file short link',
             arguments: [{name: :folder_dest, type: String}, {name: :link_type, allowed: %i[public private]}],
             setup: :setup_files_short_link
           command :transfer, description: 'Transfer files (node-to-node)',
             arguments: [{name: :direction, allowed: %i[push pull]}, {name: :source_folder, type: String}]
-          command :mkdir,            description: 'Create folder'
-          command :mklink,           description: 'Create symbolic link'
-          command :mkfile,           description: 'Create file'
-          command :rename,           description: 'Rename entry'
-          command :delete,           description: 'Delete entry'
-          command :upload,           description: 'Upload files',   transfer_paths: :send
-          command :download,         description: 'Download files', transfer_paths: :receive
-          command :sync,             description: 'Synchronize folders'
-          command :cat,              description: 'Show file contents'
-          command :show,             description: 'Show file info'
-          command :modify,           description: 'Modify file'
-          command :permission,       description: 'Manage permissions'
-          command :thumbnail,        description: 'Show file thumbnail'
-          command :v3,               description: 'Legacy v3 commands on files'
-          command :bearer_token_node, description: 'Show bearer token for file node'
-          command :node_info,         description: 'Show node info for file'
-          command :browse,            description: 'Browse files'
-          command :find,              description: 'Find files'
+          command :permission, description: 'Manage permissions'
+          command :sync,       description: 'Synchronize folders'
+          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
+            command cmd, **spec
+          end
         end
         # files > short_link sub-commands
         register_short_link_commands(self, %i[files short_link])
 
         # automation sub-commands
-        commands_under(:automation) do
-          entity_command :instances, description: 'Manage workflow instances', api: :aoc_api, entity: 'workflow_instances'
-          command :workflows, description: 'Manage workflows'
-        end
-
-        commands_under(%i[automation workflows]) do
-          command :create,  description: 'Create a workflow'
-          command :list,    description: 'List workflows'
-          command :show,    description: 'Show a workflow'
-          command :modify,  description: 'Modify a workflow'
-          command :delete,  description: 'Delete a workflow'
-          command :launch, description: 'Launch a workflow',
-            arguments: [{name: :wf_id, type: :identifier}],
-            action: ->(wf_id:, **){Result::SingleObject.new(@automation_api.create("workflows/#{wf_id}/launch", {}))}
-          command :action, description: 'Add action to workflow (TODO)'
-        end
+        commands_under :automation  do
+          commands_under :instances do
+            crud_commands api: :aoc_api, entity: 'workflow_instances', name: 'workflow instance'
+          end
 
-        commands_under(%i[automation workflows action]) do
-          command :list,   description: 'List actions (TODO)',
-            arguments: [{name: :wf_id, type: :identifier}]
-          command :create, description: 'Create an action (TODO)',
-            arguments: [{name: :wf_id, type: :identifier}]
-          command :show,   description: 'Show an action (TODO)',
-            arguments: [{name: :wf_id, type: :identifier}]
+          commands_under :workflows do
+            crud_commands api: :@automation_api, entity: 'workflows'
+            command :launch, description: 'Launch a workflow',
+              arguments: [{name: :wf_id, type: :identifier}],
+              action: ->(wf_id:, **) { Result::SingleObject.new(@automation_api.create("workflows/#{wf_id}/launch", {})) }
+            commands_under :action, description: 'Add action to workflow (TODO)' do
+              %i[list create show].each do |cmd|
+                command cmd,
+                  description: "#{cmd.capitalize} action (TODO)",
+                  arguments:   [{name: :wf_id, type: :identifier}]
+              end
+            end
+          end
         end
 
         # --- setup methods ---
@@ -1015,15 +996,16 @@ module Aspera
           skip_ids_persistency = package_persistency
           case ids_to_download
           when SpecialValues::INIT
-            all_packages = list_all_packages_with_query[:items]
+            all_packages, = list_all_packages_with_query
             Aspera.assert(skip_ids_persistency, 'INIT requires option once_only')
-            skip_ids_persistency.data.clear.concat(all_packages.map{ |e| e['id']})
+            skip_ids_persistency.data.clear.concat(all_packages[:items].map { |e| e['id'] })
             skip_ids_persistency.save
             return Result::Status.new("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
           when SpecialValues::ALL
-            all_packages = list_all_packages_with_query[:items]
-            reject_packages_from_persistency(all_packages, skip_ids_persistency)
-            ids_to_download = all_packages.map{ |e| e['id']}
+            all_packages, max_items = list_all_packages_with_query
+            reject_packages_from_persistency(all_packages[:items], skip_ids_persistency)
+            all_packages[:items] = all_packages[:items][0, max_items] if max_items
+            ids_to_download = all_packages[:items].map { |e| e['id'] }
             formatter.display_status("Found #{ids_to_download.length} package(s).")
           else
             ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
@@ -1061,9 +1043,10 @@ module Aspera
 
         # packages > list
         def action_packages_list
-          result = list_all_packages_with_query
+          result, max_items = list_all_packages_with_query
           skip_ids_persistency = package_persistency
           reject_packages_from_persistency(result[:items], skip_ids_persistency)
+          result[:items] = result[:items][0, max_items] if max_items
           display_fields = PACKAGE_LIST_DEFAULT_FIELDS
           display_fields += ['workspace_id'] if aoc_api.workspace_info[:id].nil?
           Result::ObjectList.new(result[:items], fields: display_fields, total: result[:total])
@@ -1076,10 +1059,8 @@ module Aspera
 
         # packages > delete
         def action_packages_delete(package_id:, **)
-          is_bulk = options.get_option(:bulk)
-          items = package_id.is_a?(Array) ? package_id : [package_id]
-          Result.bulk(items, is_bulk: is_bulk, command: :delete, bfail: options.get_option(:bfail)) do |one_id|
-            Aspera.assert_type(one_id, String, Integer){'identifier'}
+          bulk_result(package_id, command: :delete) do |one_id|
+            Aspera.assert_type(one_id, String, Integer) { 'identifier' }
             aoc_api.delete("packages/#{one_id}")
           end
         end
@@ -1090,7 +1071,7 @@ module Aspera
           Result::Status.new('modified')
         end
 
-        # packages > bearer_token_node / node_info / browse / find
+        # packages > bearer_token_node / node_info / ls / find
         # (NODE4_READ_ACTIONS dispatched by full path: action_packages_bearer_token_node, etc.)
         Node::NODE4_READ_ACTIONS.each do |action|
           define_action_method([:packages, action]) do |package_id:, **|
@@ -1134,12 +1115,12 @@ module Aspera
               created_data = shared_apifid.node_api.create('permissions', perm_data)
               aoc_api.permissions_send_event(event_data: created_data, app_info: shared_apifid.node_api.app_info)
             when :update
-              found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).find{ |i| i['access_id'].eql?(id)}
-              Aspera.assert(!found.nil?, type: Error){"Short link not found: #{id}"}
+              found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).find { |i| i['access_id'].eql?(id) }
+              Aspera.assert(!found.nil?, type: Error) { "Short link not found: #{id}" }
               shared_apifid.node_api.update("permissions/#{found['id']}", {access_levels: Api::AoC.expand_access_levels(access_levels)})
             when :delete
               found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).first
-              Aspera.assert(!found.nil?, type: Error){"Short link not found: #{id}"}
+              Aspera.assert(!found.nil?, type: Error) { "Short link not found: #{id}" }
               shared_apifid.node_api.delete("permissions/#{found['id']}")
             else Aspera.error_unexpected_value(op)
             end
@@ -1216,7 +1197,7 @@ module Aspera
         def sl_exec_delete(sl_shared_data_ws:, sl_short_list:, sl_link_type:, sl_perm_block:, short_link_id: nil, **)
           one_id = short_link_id
           if sl_link_type.eql?(:public)
-            found = sl_short_list[:items].find{ |item| item['id'].eql?(one_id)}
+            found = sl_short_list[:items].find { |item| item['id'].eql?(one_id) }
             raise BadIdentifier.new('Short link', one_id) if found.nil?
             sl_perm_block&.call(:delete, found['resource_id'], nil)
           end
@@ -1232,14 +1213,14 @@ module Aspera
         # Shared implementation for short_link > show
         def sl_exec_show(sl_short_list:, short_link_id: nil, **)
           one_id = short_link_id
-          found = sl_short_list[:items].find{ |item| item['id'].eql?(one_id)}
+          found = sl_short_list[:items].find { |item| item['id'].eql?(one_id) }
           raise BadIdentifier.new('Short link', one_id) if found.nil?
           Result::SingleObject.new(found, fields: Formatter.all_but('data'))
         end
 
         # Shared implementation for short_link > modify
         def sl_exec_modify(custom_data = {}, sl_shared_data:, sl_short_list:, sl_link_type:, sl_perm_block:, short_link_id: nil, **)
-          Aspera.assert_values(sl_link_type, [:public], type: Cli::BadArgument){'link_type'}
+          Aspera.assert_values(sl_link_type, [:public], type: Cli::BadArgument) { 'link_type' }
           one_id = short_link_id
           node_file = sl_shared_data.slice(:node_id, :file_id)
           modify_payload = {edit_access: true, json_query: node_file}
@@ -1251,7 +1232,7 @@ module Aspera
             modify_payload[:password_enabled] = false
           end
           if custom_data.delete('access_levels')
-            found = sl_short_list[:items].find{ |item| item['id'].eql?(one_id)}
+            found = sl_short_list[:items].find { |item| item['id'].eql?(one_id) }
             raise BadIdentifier.new('Short link', one_id) if found.nil?
             sl_perm_block&.call(:update, found['resource_id'], nil)
           end
@@ -1272,20 +1253,22 @@ module Aspera
         end
 
         # files > FILES_COMMANDS (all Gen4 node commands except :transfer, handled above)
-        FILES_COMMANDS.reject{ |a| a.eql?(:transfer)}.each do |action|
-          define_action_method([:files, action]) do
-            execute_nodegen4_command(action, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER)
+        FILES_COMMANDS.reject { |a| a.eql?(:transfer) }.each do |action|
+          define_action_method([:files, action]) do |**ctx|
+            execute_nodegen4_command(action, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER, **ctx)
           end
         end
 
         # admin > application > instance > <type> > show|modify
         APP_TYPES.each do |app_type|
-          define_action_method([:admin, :application, :instance, app_type, :show]) do |res_id:, **|
-            Result::SingleObject.new(aoc_api.read("admin/apps_new/#{app_type}/#{res_id}", query_read_delete))
+          define_action_method([:admin, :application, :instance, app_type, :show]) do |**kwargs|
+            app_id = kwargs[:"#{app_type}_id"]
+            Result::SingleObject.new(aoc_api.read("admin/apps_new/#{app_type}/#{app_id}", query_read_delete))
           end
 
-          define_action_method([:admin, :application, :instance, app_type, :modify]) do |properties:, res_id:, **|
-            aoc_api.update("admin/apps_new/#{app_type}/#{res_id}", properties)
+          define_action_method([:admin, :application, :instance, app_type, :modify]) do |properties:, **kwargs|
+            app_id = kwargs[:"#{app_type}_id"]
+            aoc_api.update("admin/apps_new/#{app_type}/#{app_id}", properties)
             Result::Status.new('modified')
           end
         end
@@ -1293,18 +1276,18 @@ module Aspera
         def action_admin_application_membership_create(membership:, **)
           data = membership.dup
           app_type = data.delete('app_type')
-          Aspera.assert_type(app_type, String){'app_type'}
-          Aspera.assert_values(app_type.to_sym, APP_TYPES){'app_type'}
+          Aspera.assert_type(app_type, String) { 'app_type' }
+          Aspera.assert_values(app_type.to_sym, APP_TYPES) { 'app_type' }
           Result::SingleObject.new(aoc_api.create("apps/#{app_type}/app_memberships", data))
         end
 
         # admin > application > membership > show|delete
-        def action_admin_application_membership_show(res_id:, **)
-          Result::SingleObject.new(aoc_api.read("apps/app_memberships/#{res_id}", query_read_delete))
+        def action_admin_application_membership_show(membership_id:, **)
+          Result::SingleObject.new(aoc_api.read("apps/app_memberships/#{membership_id}", query_read_delete))
         end
 
-        def action_admin_application_membership_delete(res_id:, **)
-          aoc_api.delete("apps/app_memberships/#{res_id}")
+        def action_admin_application_membership_delete(membership_id:, **)
+          aoc_api.delete("apps/app_memberships/#{membership_id}")
           Result::Status.new('deleted')
         end
 
@@ -1337,14 +1320,12 @@ module Aspera
 
         # admin > analytics > application_events
         def action_admin_analytics_application_events
-          analytics_api = build_analytics_api
-          events = analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/application_events")['application_events']
+          events = build_analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/application_events")['application_events']
           Result::ObjectList.new(events)
         end
 
         # admin > analytics > transfers
         def action_admin_analytics_transfers(event_resource_type:, event_resource_id:, **)
-          analytics_api = build_analytics_api
           event_resource_id ||=
             case event_resource_type
             when :organizations then aoc_api.current_user_info['organization_id']
@@ -1367,15 +1348,14 @@ module Aspera
             filter['start_time'] = start_date_time unless start_date_time.nil?
             filter['stop_time']  = stop_date_time
           end
-          events = analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers", filter)['transfers']
+          events = build_analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers", filter)['transfers']
           start_date_persistency&.save
-          events.each{ |tr_event| context.mailer.send_email_template(values: {ev: tr_event})} if !options.get_option(:notify_to).nil?
+          events.each { |tr_event| context.mailer.send_email_template(values: {ev: tr_event}) } if !options.get_option(:notify_to).nil?
           Result::ObjectList.new(events)
         end
 
         # admin > analytics > files
         def action_admin_analytics_files(event_resource_type:, event_resource_id:, event_uuid:, **)
-          analytics_api = build_analytics_api
           event_resource_id =
             case event_resource_type
             when :organizations then aoc_api.current_user_info['organization_id']
@@ -1385,13 +1365,13 @@ module Aspera
             end if event_resource_id.to_s.empty?
           filter = query_read_delete(default: {})
           filter['limit'] ||= 100
-          events = analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers/#{event_uuid}/files", filter)['files']
+          events = build_analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers/#{event_uuid}/files", filter)['files']
           Result::ObjectList.new(events)
         end
 
         # Lookup methods for arguments:(:identifier) + lookup: on admin resources.
         # One method per non-singleton resource; each delegates to get_resource_id_from_args.
-        ADMIN_OBJECTS.reject{ |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton)}.each do |res|
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) }.each do |res|
           define_method(:"lookup_aoc_#{res}_id") do |_field, value, **|
             aoc_api.lookup_with_q(aoc_res_path(res), value: value)['id']
           end
@@ -1406,8 +1386,9 @@ module Aspera
         end
 
         # admin > <res> > show
-        ADMIN_OBJECTS.reject{ |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton)}.each do |res|
-          define_action_method([:admin, res, :show]) do |res_id:, **|
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) }.each do |res|
+          define_action_method([:admin, res, :show]) do |**kwargs|
+            res_id = kwargs[:"#{res}_id"]
             c = aoc_res_cfg(res)
             Result::SingleObject.new(aoc_api.read("#{c[:path]}/#{res_id}", query_read_delete), fields: Formatter.all_but('certificate'))
           end
@@ -1421,15 +1402,14 @@ module Aspera
         end
 
         # admin > <res> > create
-        ADMIN_OBJECTS.reject{ |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton)}.each do |res|
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) }.each do |res|
           define_action_method([:admin, res, :create]) do |data:, **|
             c = aoc_res_cfg(res)
             path = c[:path]
             # Special case: client_registration_token has a different creation URL
             path = 'admin/client_registration/token' if path.eql?('admin/client_registration_tokens')
             workspace_id = aoc_api.workspace_info[:id] if c[:require_ws_id]
-            is_bulk = options.get_option(:bulk)
-            Result.bulk(data, is_bulk: is_bulk, command: :create, id_result: c[:id_result], bfail: options.get_option(:bfail)) do |params|
+            bulk_result(data, command: :create, id_result: c[:id_result]) do |params|
               params['workspace_id'] = workspace_id if c[:require_ws_id] && workspace_id && !params.key?('workspace_id')
               aoc_api.create(path, params)
             end
@@ -1437,8 +1417,9 @@ module Aspera
         end
 
         # admin > <res> > modify
-        ADMIN_OBJECTS.reject{ |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) || ADMIN_OBJECT_CONFIG.dig(r, :ops)&.then{ |o| !o.include?(:modify)}}.each do |res|
-          define_action_method([:admin, res, :modify]) do |data:, res_id:, **|
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) || ADMIN_OBJECT_CONFIG.dig(r, :ops)&.then { |o| !o.include?(:modify) } }.each do |res|
+          define_action_method([:admin, res, :modify]) do |data:, **kwargs|
+            res_id = kwargs[:"#{res}_id"]
             c = aoc_res_cfg(res)
             aoc_api.update("#{c[:path]}/#{res_id}", data)
             Result::Status.new('modified')
@@ -1450,11 +1431,10 @@ module Aspera
           cfg = ADMIN_OBJECT_CONFIG.fetch(r, {})
           cfg[:singleton] || (cfg[:ops] && !cfg[:ops].include?(:delete))
         end.each do |res|
-          define_action_method([:admin, res, :delete]) do |res_id:, **|
+          define_action_method([:admin, res, :delete]) do |**kwargs|
+            res_id = kwargs[:"#{res}_id"]
             c = aoc_res_cfg(res)
-            is_bulk = options.get_option(:bulk)
-            items = res_id.is_a?(Array) ? res_id : [res_id]
-            Result.bulk(items, is_bulk: is_bulk, command: :delete, bfail: options.get_option(:bfail)) do |one_id|
+            bulk_result(res_id, command: :delete) do |one_id|
               aoc_api.delete("#{c[:path]}/#{one_id}")
               {'id' => one_id}
             end
@@ -1469,33 +1449,44 @@ module Aspera
         end
 
         # admin > client > set_pub_key
-        def action_admin_client_set_pub_key(private_key_pem:, res_id:, **)
+        def action_admin_client_set_pub_key(private_key_pem:, client_id:, **)
           c = aoc_res_cfg(:client)
           the_public_key = OpenSSL::PKey::RSA.new(private_key_pem).public_key.to_s
-          aoc_api.update("#{c[:path]}/#{res_id}", {jwt_grant_enabled: true, public_key: the_public_key})
+          aoc_api.update("#{c[:path]}/#{client_id}", {jwt_grant_enabled: true, public_key: the_public_key})
           Result::Success.new
         end
 
+        # admin > ats — build and return an Ats plugin instance wired to the AoC ATS API.
+        # Used as delegate_instance: target so --help traverses the Ats registry.
+        # @return [Ats] configured Ats plugin instance
+        def build_ats_plugin
+          ats_api = Rest.new(**aoc_api.params.deep_merge({
+            base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
+            auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
+          }))
+          Ats.new(context: context, api: ats_api)
+        end
+
         # admin > node > do | bearer_token — setup reuses the generic instance setup
         # (setup_admin_node_instance is auto-generated above, providing res_id:)
 
         # admin > node > do > <FILES_COMMAND>
         FILES_COMMANDS.each do |cmd|
-          define_action_method([:admin, :node, :do, cmd]) do |res_id:, **|
-            execute_nodegen4_command(cmd, res_id, scope: Api::Node::Scope::ADMIN)
+          define_action_method([:admin, :node, :do, cmd]) do |node_id:, **ctx|
+            execute_nodegen4_command(cmd, node_id, scope: Api::Node::Scope::ADMIN, **ctx)
           end
         end
 
         # admin > node > bearer_token
-        def action_admin_node_bearer_token(scope:, res_id:, **)
+        def action_admin_node_bearer_token(scope:, node_id:, **)
           scope ||= Api::Node::Scope::ADMIN
-          node_api = aoc_api.node_api_from(node_id: res_id, scope: scope)
+          node_api = aoc_api.node_api_from(node_id: node_id, scope: scope)
           Result::Text.new(node_api.oauth.authorization)
         end
 
         # admin > workspace > dropbox — res_id: already in ctx via arguments:(:identifier)
-        def setup_admin_workspace_dropbox(res_id:, **)
-          {ws_res_id: res_id}
+        def setup_admin_workspace_dropbox(workspace_id:, **)
+          {ws_res_id: workspace_id}
         end
 
         # admin > workspace > dropbox > list
@@ -1505,11 +1496,11 @@ module Aspera
         end
 
         # admin > workspace > shared_folder — res_id: already in ctx via arguments:(:identifier)
-        def setup_admin_workspace_shared_folder(res_id:, **)
-          resource_instance_path = "#{aoc_res_path(:workspace)}/#{res_id}"
-          query = options.get_option(:query) || Api::AoC.workspace_access(res_id).merge({'admin' => true})
+        def setup_admin_workspace_shared_folder(workspace_id:, **)
+          resource_instance_path = "#{aoc_res_path(:workspace)}/#{workspace_id}"
+          query = options.get_option(:query) || Api::AoC.workspace_access(workspace_id).merge({'admin' => true})
           shared_folders = aoc_api.read_with_paging("#{resource_instance_path}/permissions", query)[:items]
-          {ws_res_id: res_id, shared_folders: shared_folders}
+          {ws_res_id: workspace_id, shared_folders: shared_folders}
         end
 
         # admin > workspace > shared_folder > list
@@ -1519,7 +1510,7 @@ module Aspera
 
         # admin > workspace > shared_folder > node|member — sf_id: already in ctx via arguments:(:identifier)
         def resolve_sf_item(shared_folders:, sf_id:, **)
-          sf_item = shared_folders.find{ |i| i['id'].eql?(sf_id)}
+          sf_item = shared_folders.find { |i| i['id'].eql?(sf_id) }
           Aspera.assert(sf_item, 'shared folder not found')
           {sf_item: sf_item}
         end
@@ -1529,8 +1520,8 @@ module Aspera
 
         # admin > workspace > shared_folder > node > <FILES_COMMAND>
         FILES_COMMANDS.each do |cmd|
-          define_action_method([:admin, :workspace, :shared_folder, :node, cmd]) do |sf_item:, **|
-            execute_nodegen4_command(cmd, sf_item['node_id'], file_id: sf_item['file_id'], scope: Api::Node::Scope::ADMIN)
+          define_action_method([:admin, :workspace, :shared_folder, :node, cmd]) do |sf_item:, **ctx|
+            execute_nodegen4_command(cmd, sf_item['node_id'], file_id: sf_item['file_id'], scope: Api::Node::Scope::ADMIN, **ctx)
           end
         end
 
@@ -1562,26 +1553,19 @@ module Aspera
         # (setup_admin_user_instance is auto-generated, providing res_id:)
         %i[preferences notifications].each do |pref|
           pref_path = pref.eql?(:preferences) ? 'user_interaction_preferences' : 'notification_preferences'
-          define_action_method([:admin, :user, pref, :show]) do |res_id:, **|
-            Result::SingleObject.new(aoc_api.read("#{aoc_res_path(:user)}/#{res_id}/#{pref_path}"))
+          define_action_method([:admin, :user, pref, :show]) do |user_id:, **|
+            Result::SingleObject.new(aoc_api.read("#{aoc_res_path(:user)}/#{user_id}/#{pref_path}"))
           end
-          define_action_method([:admin, :user, pref, :modify]) do |properties:, res_id:, **|
-            aoc_api.update("#{aoc_res_path(:user)}/#{res_id}/#{pref_path}", properties)
+          define_action_method([:admin, :user, pref, :modify]) do |properties:, user_id:, **|
+            aoc_api.update("#{aoc_res_path(:user)}/#{user_id}/#{pref_path}", properties)
             Result::Status.new('modified')
           end
         end
 
-        # automation > workflows > CRUD operations
-        Operations::ALL.each do |op|
-          define_action_method([:automation, :workflows, op]) do
-            entity_execute(api: @automation_api, entity: 'workflows', command: op)
-          end
-        end
-
         # automation > workflows > action > * (TODO: not fully implemented)
         %i[list create show].each do |cmd|
           define_action_method([:automation, :workflows, :action, cmd]) do |wf_id:, **|
-            Log.log.warn{"Not implemented: #{cmd}"}
+            Log.log.warn { "Not implemented: #{cmd}" }
             step = @automation_api.create('steps', {'workflow_id' => wf_id})
             @automation_api.update("workflows/#{wf_id}", {'step_order' => [step['id']]})
             action = @automation_api.create('actions', {'step_id' => step['id'], 'type' => 'manual'})
@@ -1593,9 +1577,9 @@ module Aspera
         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, aoc_api, aoc_api.workspace_info[:id])
           server.start
           return Result::Status.new('Gateway terminated')