aspera-cli 4.26.1 → 4.27.0

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/schema/registry'
 require 'aspera/cli/plugins/oauth'
 require 'aspera/cli/plugins/node'
 require 'aspera/cli/plugins/ats'
@@ -7,12 +8,14 @@ require 'aspera/cli/transfer_agent'
 require 'aspera/cli/special_values'
 require 'aspera/cli/wizard'
 require 'aspera/agent/node'
+require 'aspera/transfer/result'
 require 'aspera/transfer/spec'
 require 'aspera/api/aoc'
 require 'aspera/api/node'
 require 'aspera/persistency_action_once'
 require 'aspera/id_generator'
 require 'aspera/assert'
+require 'aspera/graphql'
 require 'securerandom'
 require 'date'
 
@@ -27,12 +30,14 @@ module Aspera
           client
           client_access_key
           client_registration_token
+          configuration_policy
           contact
           dropbox
           dropbox_membership
           group
           group_membership
           kms_profile
+          network_policy
           node
           operation
           organization
@@ -54,11 +59,9 @@ module Aspera
         PACKAGE_LIST_DEFAULT_FIELDS = %w[id name created_at files_completed bytes_transferred].freeze
 
         private_constant :REDIRECT_LOCALHOST, :ADMIN_OBJECTS, :PACKAGE_RECEIVED_BASE_QUERY, :PACKAGE_LIST_DEFAULT_FIELDS
-        class << self
-          def application_name
-            'Aspera on Cloud'
-          end
+        application_name 'Aspera on Cloud'
 
+        class << self
           # @return [Hash,NilClass]
           def detect(base_url)
             # no protocol ?
@@ -97,10 +100,10 @@ module Aspera
           # or a sequential number if extension == :seq
           # @param package_info       [Hash]   Package information
           # @param destination_folder [String] Base folder
-          # @param fld.               [Array]  List of fields of package
+          # @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([1, 2].include?(fld.length)){'fld must have 1 or 2 elements'}
+            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)
@@ -108,7 +111,6 @@ module Aspera
               # NOTE: it might already exist
               folder = "#{folder}.#{Environment.instance.sanitized_filename(fld[1])}"
             end
-            puts("sub= #{folder}")
             File.join(destination_folder, folder)
           end
         end
@@ -131,7 +133,7 @@ module Aspera
               test_args:    'organization'
             }
           end
-          options.declare(:use_generic_client, '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: Allowed::TYPES_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)
@@ -178,7 +180,7 @@ module Aspera
           end
           myself = aoc_api.read('self')
           if auto_set_pub_key
-            Aspera.assert(myself['public_key'].empty?, type: Error){'Public key is already set in profile (use --override=yes)'} unless option_override
+            Aspera.assert(myself['public_key'].empty?, 'Public key is already set in profile (use --override=yes)', type: Error) unless option_override
             formatter.display_status('Updating profile with the public key.')
             aoc_api.update("users/#{myself['id']}", {'public_key' => pub_key_pem})
           end
@@ -199,16 +201,17 @@ module Aspera
           }
         end
 
+        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 :package_folder,    schema: Schema::Registry::PACKAGE_FOLDER_OPTIONS
+
         def initialize(**_)
           super
           @cache_workspace_info = nil
           @cache_home_node_file = nil
           @cache_api_aoc = nil
           @scope = Api::AoC::Scope::USER
-          options.declare(:workspace, 'Name of workspace', allowed: [String, NilClass], default: Api::AoC::DEFAULT_WORKSPACE)
-          options.declare(:new_user_option, 'New user creation option for unknown package recipients', allowed: Hash)
-          options.declare(:validate_metadata, 'Validate shared inbox metadata', allowed: Allowed::TYPES_BOOLEAN, default: true)
-          options.declare(:package_folder, 'Handling of reception of packages in folders', allowed: Hash, default: {})
           options.parse_options!
           # add node plugin options (for manual)
           Node.declare_options(options)
@@ -231,13 +234,13 @@ module Aspera
           api = Api::AoC.new(
             scope:         @scope,
             subpath:       base_path,
-            secret_finder: config,
+            secret_finder: context.secret_finder,
             **Oauth.kwargs_from_options(options)
           )
           # User set a workspace ?
           # @type [String, nil]
           workspace = options.get_option(:workspace)
-          if !workspace.nil? && (m = Manager.percent_selector(workspace))
+          if !workspace.nil? && (m = Parser.percent_selector(workspace))
             case m[:field]
             when 'name' then api.ws_ids[:name] = m[:value]
             when 'id' then api.ws_ids[:id] = m[:value]
@@ -285,11 +288,11 @@ module Aspera
         end
 
         # Get resource identifier from command line, either directly specifying the `id` or from `name` (percent selector).
-        # @param resource_class_path url path for resource
-        # @return identifier
+        # @param resource_class_path [String] url path for resource
+        # @return [String] identifier
         def get_resource_id_from_args(resource_class_path)
           return options.instance_identifier do |field, value|
-            Aspera.assert(field.eql?('name'), type: BadArgument){'only selection by name is supported'}
+            Aspera.assert_values(field, ['name'], type: BadArgument){'selector field'}
             aoc_api.lookup_with_q(resource_class_path, value: value)['id']
           end
         end
@@ -300,26 +303,28 @@ module Aspera
         end
 
         # List all entities, given additional, default and user's queries
-        # @param resource_class_path path to query on API
-        # @param fields fields to display
-        # @param base_query a query applied always
-        # @param default_query default query unless overridden by user
+        # @param resource_class_path [String]     path to query on API
+        # @param fields              [Array, nil] fields to display
+        # @param base_query          [Hash]       a query applied always
+        # @param default_query       [Hash]       default query unless overridden by user
+        # @param query_component     [String, nil] registry component key; when set, --query=help shows filter schema
         # @yieldparam query [Hash] The user's or default query for modification
-        def result_list(resource_class_path, fields: nil, base_query: {}, default_query: {})
+        def result_list(resource_class_path, fields: nil, base_query: {}, default_query: {}, query_component: nil)
           Aspera.assert_type(base_query, Hash)
           Aspera.assert_type(default_query, Hash)
-          query = query_read_delete(default: default_query)
+          qs_path = query_component ? Schema::Registry.query_params(query_component, resource_class_path) : nil
+          query = query_read_delete(default: default_query, schema: qs_path)
           # caller may add specific modifications or checks to query
           yield(query) if block_given?
           result = aoc_api.read_with_paging(resource_class_path, base_query.merge(query).compact)
-          return Main.result_object_list(result[:items], fields: fields, total: result[:total])
+          return Result::ObjectList.new(result[:items], fields: fields, total: result[:total])
         end
 
         # Translates `dropbox_name` to `dropbox_id` and fills current workspace_id
         def resolve_dropbox_name_default_ws_id(query)
           if query.key?('dropbox_name')
             # convenience: specify name instead of id
-            raise BadArgument, 'Use field dropbox_name or dropbox_id, not both' if query.key?('dropbox_id')
+            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
@@ -329,7 +334,6 @@ module Aspera
         end
 
         # List all packages according to `query` option.
-        # @param <none>
         # @return [Hash] {items,total} with all packages according to combination of user's query and default query
         def list_all_packages_with_query
           query = query_read_delete(default: {})
@@ -342,11 +346,13 @@ module Aspera
         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
-        # @param node_id [String] Node identifier
-        # @param file_id [String] Root file id for the operation (can be AK root, or other, e.g. package, or link). If `nil` use AK root file id.
-        # @param scope [String] node scope (Node::SCOPE_<USER|ADMIN>), or nil (requires secret)
-        def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil)
+        # @param command_repo       [Symbol] Command to execute
+        # @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)
           top_node_api = aoc_api.node_api_from(
             node_id:        node_id,
             scope:          scope,
@@ -356,13 +362,16 @@ module Aspera
           node_plugin = Node.new(context: context, api: top_node_api)
           case command_repo
           when *Node::COMMANDS_GEN4
-            return node_plugin.execute_command_gen4(command_repo, file_id)
+            # 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)
           when :transfer
             # client side is agent
             # server side is transfer server
             # in same workspace
-            push_pull = options.get_next_argument('direction', accept_list: %i[push pull])
-            source_folder = options.get_next_argument('folder or source files', validation: String)
+            push_pull = transfer_direction
+            source_folder = transfer_source
             case push_pull
             when :push
               client_direction = Transfer::Spec::DIRECTION_SEND
@@ -389,7 +398,7 @@ module Aspera
               'destination_root_id' => server_apifid.file_id,
               'source_root_id'      => client_apifid.file_id
             }
-            return Main.result_transfer(transfer.start(server_apifid.node_api.transfer_spec_gen4(
+            return Runner.result_transfer(transfer.start(server_apifid.node_api.transfer_spec_gen4(
               server_apifid.file_id,
               client_direction,
               add_ts
@@ -401,578 +410,154 @@ module Aspera
 
         # Execute an action on admin resources
         # @param resource_type [Symbol] One of ADMIN_OBJECTS
-        def execute_resource_action(resource_type)
-          # Set to `true` is resource creation requires a workspace id
-          require_workspace_id = false
-          # Default fields to display
-          list_default_fields = %w[id name]
-          # Default query for `list` action
-          list_default_query = {}
-          # In result of create, what is the field that contains the id of the created resource
-          id_result = 'id'
-          supported_operations = Operations::ALL
-          # API path
-          resource_class_path = "#{resource_type}s"
-          # path in openapi where post is located to get creation schema
-          create_schema_path = resource_class_path
-          case resource_type
-          when :client
-            supported_operations += %i[set_pub_key]
-            # schema_create_modify = Schema::Registry.req_body(Schema::Registry::AOC, "#{resource_class_path}.post")
-          when :client_access_key
-            resource_class_path = "admin/#{resource_type}s"
-          when :client_registration_token
-            resource_class_path = "admin/#{resource_type}s"
-            list_default_fields = %w[id value data.client_subject_scopes data.name created_at]
-            id_result = 'token'
-          when :contact
-            list_default_fields = %w[source_type source_id name email]
-            # list_default_query = {'include_only_user_personal_contacts' => true} if @scope == Api::AoC::Scope::USER
-          when :dropbox
-            require_workspace_id = true
-            resource_class_path = "#{resource_type}es"
-            create_schema_path = resource_class_path
-          when :group, :saml_configuration
-            create_schema_path = nil
-          when :group_membership
-            list_default_fields = %w[id group_id member_type member_id]
-            create_schema_path = nil
-          when :kms_profile
-            resource_class_path = "integrations/#{resource_type}s"
-            create_schema_path = nil
-          when :node
-            list_default_fields = %w[id name host access_key]
-            supported_operations += %i[do bearer_token]
-          when :operation
-            list_default_fields = %w[id type status created_at updated_at workspace_id user_id workspace_membership_id group_membership_id]
-            supported_operations = %i[list show modify]
-          when :organization, :self
-            supported_operations = Operations::SINGLETON
-            resource_instance_path = resource_class_path = resource_type
-          when :short_link
-            list_default_fields = %w[id short_url data.url_token_data.purpose password_enabled password_protected updated_by_user_id updated_at]
-          when :user
-            list_default_fields = %w[id name email]
-            supported_operations += %i[preferences notifications]
-          when :workspace
-            supported_operations += %i[shared_folder dropbox]
-          when :workspace_membership
-            list_default_fields = %w[id workspace_id member_type member_id]
+        # Per-resource configuration for admin CRUD resources.
+        # Keys: path, list_fields, id_result, require_ws_id, create_schema, extra_ops, singleton, op_setup
+        # op_setup: Hash of op => setup method name, used for ops that require consuming an instance identifier.
+        #   For Operations::INSTANCE ops (show/modify/delete), use the auto-generated :setup_admin_<res>_instance.
+        #   For extra_ops that are instance ops, specify explicitly (or rely on the auto-generated one).
+        ADMIN_OBJECT_CONFIG = {
+          client:                    {extra_ops: %i[set_pub_key], extra_op_args: {set_pub_key: [{name: :private_key_pem, type: String}]}},
+          client_access_key:         {path: 'admin/client_access_keys'},
+          client_registration_token: {path: 'admin/client_registration_tokens', list_fields: %w[id value data.client_subject_scopes data.name created_at], id_result: 'token'},
+          configuration_policy:      {list_fields: nil},
+          contact:                   {list_fields: %w[source_type source_id name email]},
+          dropbox:                   {path: 'dropboxes', require_ws_id: true},
+          dropbox_membership:        {},
+          group:                     {create_schema: false},
+          group_membership:          {list_fields: %w[id group_id member_type member_id], create_schema: false},
+          kms_profile:               {path: 'integrations/kms_profiles', create_schema: false},
+          network_policy:            {list_fields: nil},
+          node:                      {list_fields: %w[id name host access_key], extra_ops: %i[do bearer_token], extra_op_args: {bearer_token: [{name: :scope, mandatory: false, default: nil}]}},
+          operation:                 {list_fields: %w[id type status created_at updated_at workspace_id user_id workspace_membership_id group_membership_id], ops: %i[list show modify]},
+          organization:              {singleton: true},
+          package:                   {},
+          saml_configuration:        {create_schema: false},
+          self:                      {singleton: true},
+          short_link:                {list_fields: %w[id short_url data.url_token_data.purpose password_enabled password_protected updated_by_user_id updated_at]},
+          user:                      {list_fields: %w[id name email], extra_ops: %i[preferences notifications], op_setup: {preferences: :setup_admin_user_instance, notifications: :setup_admin_user_instance}},
+          workspace:                 {extra_ops: %i[shared_folder dropbox], op_setup: {shared_folder: :setup_admin_workspace_shared_folder, dropbox: :setup_admin_workspace_dropbox}},
+          workspace_membership:      {list_fields: %w[id workspace_id member_type member_id]}
+        }.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
-          # Default location of creation payload in schema
-          schema_create_modify = Schema::Registry.req_body(Schema::Registry::AOC, "#{create_schema_path}.post") if create_schema_path && supported_operations.include?(:create)
-          command = options.get_next_command(supported_operations)
-          # Require identifier for non global commands
-          if (supported_operations != Operations::SINGLETON) && !Operations::GLOBAL.include?(command)
-            res_id = get_resource_id_from_args(resource_class_path)
-            resource_instance_path = "#{resource_class_path}/#{res_id}"
+
+          # @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
-          case command
-          when :create
-            # TODO: report inconsistency: creation url is !=, and does not return id.
-            resource_class_path = 'admin/client_registration/token' if resource_class_path.eql?('admin/client_registration_tokens')
-            workspace_id = aoc_api.workspace_info[:id] if require_workspace_id
-            return do_bulk_operation(command: command, descr: 'creation data', id_result: id_result, schema: schema_create_modify) do |params|
-              params['workspace_id'] = workspace_id if require_workspace_id && workspace_id && !params.key?('workspace_id')
-              aoc_api.create(resource_class_path, params)
+
+          # 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
-          when :list
-            return result_list(resource_class_path, fields: list_default_fields, default_query: list_default_query)
-          when :show
-            object = aoc_api.read(resource_instance_path, query_read_delete)
-            return Main.result_single_object(object, fields: Formatter.all_but('certificate'))
-          when :modify
-            changes = options.get_next_argument('properties', validation: Hash, schema: schema_create_modify)
-            return do_bulk_operation(command: command, values: res_id) do |one_id|
-              aoc_api.update("#{resource_class_path}/#{one_id}", changes)
-              {'id' => one_id}
+            base.define_action_method(parent_path + [:create]) do |custom_data: {}, **ctx|
+              sl_exec_create(custom_data, **ctx)
             end
-          when :delete
-            return do_bulk_operation(command: command, values: res_id) do |one_id|
-              aoc_api.delete("#{resource_class_path}/#{one_id}")
-              {'id' => one_id}
+            base.define_action_method(parent_path + [:list]) do |**ctx|
+              sl_exec_list(**sl_fetch_list(**ctx))
             end
-          when :set_pub_key
-            # special : reads private and generate public
-            the_private_key = options.get_next_argument('private_key PEM value', validation: String)
-            the_public_key = OpenSSL::PKey::RSA.new(the_private_key).public_key.to_s
-            aoc_api.update(resource_instance_path, {jwt_grant_enabled: true, public_key: the_public_key})
-            return Main.result_success
-          when :do
-            command_repo = options.get_next_command(FILES_COMMANDS)
-            return execute_nodegen4_command(command_repo, res_id, scope: Api::Node::Scope::ADMIN)
-          when :bearer_token
-            node_api = aoc_api.node_api_from(
-              node_id: res_id,
-              scope:   options.get_next_argument('scope', default: Api::Node::Scope::ADMIN)
-            )
-            return Main.result_text(node_api.oauth.authorization)
-          when :dropbox
-            command_shared = options.get_next_command(%i[list])
-            case command_shared
-            when :list
-              query = options.get_option(:query) || {}
-              res_data = aoc_api.read('dropboxes', query.merge({'workspace_id'=>res_id}))
-              return Main.result_object_list(res_data, fields: %w[id name description])
+            base.define_action_method(parent_path + [:show]) do |**ctx|
+              sl_exec_show(**sl_fetch_list(**ctx))
             end
-          when :shared_folder
-            query = options.get_option(:query) || Api::AoC.workspace_access(res_id).merge({'admin' => true})
-            shared_folders = aoc_api.read_with_paging("#{resource_instance_path}/permissions", query)[:items]
-            # inside a workspace
-            command_shared = options.get_next_command(%i[list node member])
-            case command_shared
-            when :list
-              return Main.result_object_list(shared_folders, fields: %w[id node_name node_id file_id file.path tags.aspera.files.workspace.share_as])
-            when :node
-              shared_folder_id = options.instance_identifier(description: 'Shared folder ID')
-              shared_folder = shared_folders.find{ |i| i['id'].eql?(shared_folder_id)}
-              Aspera.assert(shared_folder)
-              command_repo = options.get_next_command(FILES_COMMANDS)
-              return execute_nodegen4_command(command_repo, shared_folder['node_id'], file_id: shared_folder['file_id'], scope: Api::Node::Scope::ADMIN)
-            when :member
-              shared_folder_id = options.instance_identifier(description: 'Shared folder ID')
-              shared_folder = shared_folders.find{ |i| i['id'].eql?(shared_folder_id)}
-              Aspera.assert(shared_folder)
-              command_shared_member = options.get_next_command(%i[list])
-              case command_shared_member
-              when :list
-                node_api = aoc_api.node_api_from(
-                  node_id: shared_folder['node_id'],
-                  workspace_id: res_id,
-                  workspace_name: nil,
-                  scope: Api::Node::Scope::USER
-                )
-                result = node_api.read(
-                  'permissions',
-                  {'file_id' => shared_folder['file_id'], 'tag' => "aspera.files.workspace.id=#{res_id}"}
-                )
-                result.each do |item|
-                  item['member'] = begin
-                    if Api::AoC.workspace_access?(item)
-                      {'name'=>'[Internal permission]'}
-                    else
-                      aoc_api.read("admin/#{item['access_type']}s/#{item['access_id']}") rescue {'name': 'not found'}
-                    end
-                  rescue => e
-                    {'name'=>e.to_s}
-                  end
-                end
-                # TODO : read users and group name and add, if query "include_members"
-                return Main.result_object_list(result, fields: %w[access_type access_id access_level last_updated_at member.name member.email member.system_group_type member.system_group])
-              end
+            base.define_action_method(parent_path + [:delete]) do |**ctx|
+              sl_exec_delete(**sl_fetch_list(**ctx), **ctx)
             end
-          when :preferences, :notifications
-            user_preferences_res = "#{resource_instance_path}/#{command.eql?(:preferences) ? 'user_interaction_preferences' : 'notification_preferences'}"
-            case options.get_next_command(%i[show modify])
-            when :show
-              return Main.result_single_object(aoc_api.read(user_preferences_res))
-            when :modify
-              aoc_api.update(user_preferences_res, options.get_next_argument('properties', validation: Hash))
-              return Main.result_status('modified')
+            base.define_action_method(parent_path + [:modify]) do |custom_data: {}, **ctx|
+              sl_exec_modify(custom_data, **sl_fetch_list(**ctx), **ctx)
             end
-          else Aspera.error_unexpected_value(command)
           end
         end
 
-        def execute_application_action
-          apps_info = aoc_api.read('admin/apps')
-          all_app_types = apps_info.map{ |i| i['app_type'].to_sym}
-          command_apps = options.get_next_command(%i[types settings instance membership])
-          case command_apps
-          when :types
-            return Main.result_object_list(apps_info)
-          when :settings
-            app_type = options.get_next_command(all_app_types)
-            cmd_path = "/apps/#{app_type}/settings"
-            command_app_settings = options.get_next_command(Operations::SINGLETON)
-            case command_app_settings
-            when :show
-              return Main.result_single_object(aoc_api.read(cmd_path))
-            when :modify
-              aoc_api.update(cmd_path, options.get_next_argument('properties', validation: Hash))
-              return Main.result_status('modified')
-            end
-          when :instance
-            list_default_query = {workspace_id: aoc_api.workspace_info[:id]}
-            list_default_fields = %w[id app_type available workspace_id]
-            command_app_instances = options.get_next_command(%i[list] + Operations::SINGLETON)
-            resource_path = 'admin/apps_new'
-            if Operations::SINGLETON.include?(command_app_instances)
-              app_type = options.get_next_command(all_app_types)
-              resource_path = "#{resource_path}/#{app_type}/#{options.instance_identifier(description: "#{app_type} identifier")}"
-            end
-            case command_app_instances
-            when :list
-              return result_list(resource_path, fields: list_default_fields, default_query: list_default_query)
-            when :show
-              return Main.result_single_object(aoc_api.read(resource_path, query_read_delete))
-            when :modify
-              aoc_api.update(resource_path, options.get_next_argument('properties', validation: Hash))
-              return Main.result_status('modified')
-            end
-          when :membership
-            resource_path = 'apps/app_memberships'
-            command_app_member = options.get_next_command(%i[create list show delete])
-            resource_path = "#{resource_path}/#{options.instance_identifier(description: 'membership id')}" unless Operations::GLOBAL.include?(command_app_member)
-            case command_app_member
-            when :list
-              return result_list(resource_path)
-            when :delete
-              aoc_api.delete("#{resource_path}}")
-              return Main.result_status('deleted')
-            when :show
-              return Main.result_single_object(aoc_api.read(resource_path, query_read_delete))
-            when :create
-              aoc_api.update(resource_path, options.get_next_argument('membership properties', validation: Hash))
-              return Main.result_status('modified')
-            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)
+
+        # 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
 
-        def execute_admin_action
-          # change scope to admin
-          change_api_scope(Api::AoC::Scope::ADMIN)
-          command_admin = options.get_next_command(ADMIN_ACTIONS)
-          case command_admin
-          when :bearer_token
-            return Main.result_text(aoc_api.oauth.authorization)
-          when *ADMIN_OBJECTS
-            return execute_resource_action(command_admin)
-          when :application
-            return execute_application_action
-          when :auth_providers
-            command_auth_prov = options.get_next_command(%i[list update])
-            case command_auth_prov
-            when :list
-              return result_list('admin/auth_providers')
-            when :update
-              Aspera.error_not_implemented
-            end
-          when :subscription
-            org = aoc_api.read('organization')
-            bss_graphql = api_from_options('bss/platform/graphql')
-            command_subscription = options.get_next_command(%i[account usage])
-            case command_subscription
-            when :account
-              # cspell:disable
-              graphql_query = <<-GRAPHQL
-              query ($organization_id: ID!) {
-                aoc (organization_id: $organization_id) {
-                  bssSubscription {
-                    aocVersion
-                    endDate
-                    startDate
-                    termMonths
-                    plan
-                    trial
-                    termType
-                    aocOrganizations {
-                      id
-                    }
-                    additionalStorageVolumeGb
-                    additionalEgressVolumeGb
-                    term {
-                      startDate
-                      endDate
-                      transferVolumeGb
-                      egressVolumeGb
-                      storageVolumeGb
-                      transferVolumeOffsetGb
-                    }
-                    paygoRate {
-                      transferRate
-                      storageRate
-                      currency
-                    }
-                    aocPlanData {
-                      tier
-                      trial
-                      workspaces { max }
-                      users {
-                        planAmount
-                        max
-                      }
-                      samlIntegration
-                      activity
-                      sharedInboxes
-                      uniqueUrls
-                      support
-                      watermarking
-                      byok
-                      automation { planAmount, max }
-                    }
-                  }
-                }
-              }
-              GRAPHQL
-              # cspell:enable
-              result = bss_graphql.create(nil, {query: graphql_query, variables: {organization_id: org['id']}})['data']
-              return Main.result_single_object(result['aoc']['bssSubscription'])
-            when :usage
-              # cspell:disable
-              graphql_query = <<-GRAPHQL
-              query ($organization_id: ID!, $startDate: Date!, $endDate: Date!, $aggregate: TransferUsageAggregateOption!) {
-                aoc (organization_id: $organization_id) {
-                  bssSubscription {
-                    aocOrganizations { id }
-                    additionalStorageVolumeGb
-                    additionalEgressVolumeGb
-                    aocPlanData {
-                      tier
-                      trial
-                    }
-                    term {
-                      transferVolumeGb
-                      egressVolumeGb
-                      storageVolumeGb
-                      startDate
-                      endDate
-                      transferVolumeOffsetGb
-                    }
-                    termMonths
-                    transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
-                    egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
-                  }
-                  subscriptionEntitlements {
-                    id
-                    transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
-                    egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
-                  }
-                }
-              }
-              GRAPHQL
-              aggregate = options.get_next_argument('aggregation', accept_list: %i[ALL MONTHLY], default: :ALL)
-              today = Date.today
-              start_date = options.get_next_argument('start date', mandatory: false, default: today.prev_year.strftime('%Y-%m-%d'))
-              end_date = options.get_next_argument('end date', mandatory: false, default: today.strftime('%Y-%m-%d'))
-              # cspell:enable
-              result = bss_graphql.create(
-                nil,
-                {
-                  query:     graphql_query,
-                  variables: {
-                    organization_id: org['id'],
-                    aggregate:       aggregate,
-                    startDate:       start_date,
-                    endDate:         end_date
-                  }
-                }
-              )['data']
-              return Main.result_single_object(result['aoc'])
-            end
-          when :ats
-            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}}
-            }))
-            return Ats.new(context: context, api: ats_api).execute_action
-          when :analytics
-            analytics_api = Rest.new(**aoc_api.params.deep_merge({
-              base_url: "#{aoc_api.base_url.gsub('/api/v1', '')}/analytics/v2",
-              auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
-            }))
-            command_analytics = options.get_next_command(%i[application_events transfers files])
-            case command_analytics
-            when :application_events
-              event_type = command_analytics.to_s
-              events = analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/#{event_type}")[event_type]
-              return Main.result_object_list(events)
-            when :transfers
-              event_type = command_analytics.to_s
-              event_resource_type = options.get_next_argument('resource', accept_list: %i[organizations users nodes])
-              event_resource_id = options.get_next_argument("#{event_resource_type} identifier", mandatory: false) ||
-                case event_resource_type
-                when :organizations then aoc_api.current_user_info['organization_id']
-                when :users then aoc_api.current_user_info['id']
-                when :nodes then aoc_api.current_user_info['read_only_home_node_id']
-                else Aspera.error_unreachable_line
-                end
-              filter = query_read_delete(default: {})
-              filter['limit'] ||= 100
-              if options.get_option(:once_only, mandatory: true)
-                saved_date = []
-                start_date_persistency = PersistencyActionOnce.new(
-                  manager: persistency,
-                  data: saved_date,
-                  id: IdGenerator.from_list(
-                    'aoc_ana_date',
-                    options.get_option(:url, mandatory: true),
-                    aoc_api.workspace_info[:name],
-                    event_resource_type.to_s,
-                    event_resource_id
-                  )
-                )
-                start_date_time = saved_date.first
-                stop_date_time = Time.now.utc.strftime('%FT%T.%LZ')
-                saved_date[0] = stop_date_time
-                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}/#{event_type}", filter)[event_type]
-              start_date_persistency&.save
-              if !options.get_option(:notify_to).nil?
-                events.each do |tr_event|
-                  config.send_email_template(values: {ev: tr_event})
-                end
-              end
-              return Main.result_object_list(events)
-            when :files
-              event_type = command_analytics.to_s
-              event_resource_type = options.get_next_argument('resource', accept_list: %i[organizations users nodes])
-              event_resource_id = options.instance_identifier(description: "#{event_resource_type} identifier")
-              event_resource_id =
-                case event_resource_type
-                when :organizations then aoc_api.current_user_info['organization_id']
-                when :users then aoc_api.current_user_info['id']
-                when :nodes then aoc_api.current_user_info['read_only_home_node_id']
-                else Aspera.error_unreachable_line
-                end if event_resource_id.empty?
-              event_uuid = options.instance_identifier(description: 'event uuid')
-              filter = query_read_delete(default: {})
-              filter['limit'] ||= 100
-              events = analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers/#{event_uuid}/#{event_type}", filter)[event_type]
-              return Main.result_object_list(events)
-            end
-          when :usage_reports
-            return result_list('usage_reports', base_query: workspace_id_hash)
-          end
+        # Build analytics REST API (shared by action_admin_analytics_*)
+        def build_analytics_api
+          Rest.new(**aoc_api.params.deep_merge({
+            base_url: "#{aoc_api.base_url.gsub('/api/v1', '')}/analytics/v2",
+            auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
+          }))
         end
 
-        # Create a short link for the given entity: Shared folder or Shared Inbox
-        # Short link entity: `short_links` have:
-        # - a numerical id, e.g. `764412`
-        # - a resource type, e.g. `UrlToken`
-        # - a resource id, e.g. `scQ7uXPbvQ`
-        # - a short URL path, e.g. `dxyRpT9`
-        # @param shared_data [Hash] Information for shared data: dropbox_id+name or file_id+node_id
-        # @param shared_data [Hash] Shared data for the short link
-        # @yieldparam operation [Symbol] Operation type (:create, :update, :delete)
-        # @yieldparam resource_id [String] Resource ID for permission management
-        # @yieldparam access_levels [Object] Access levels for permissions
-        def short_link_command(**shared_data, &perm_block)
-          link_type = options.get_next_argument('link access (public or private)', accept_list: %i[public private])
+        # Compute short-link purposes from shared_data keys and link_type.
+        # @param shared_data [Hash] :dropbox_id+:name or :file_id+:node_id
+        # @param link_type [Symbol] :public or :private
+        # @return [Array(String,String)] [token_purpose, short_link_purpose]
+        def short_link_purposes(shared_data, link_type)
           if shared_data.keys.sort == %i[dropbox_id name]
-            # Packages app, Shared inbox
             token_purpose = 'send_package_to_dropbox'
             short_link_purpose = link_type.eql?(:public) ? 'send_package_to_dropbox' : 'shared_folder_auth_link'
           elsif shared_data.keys.sort == %i[file_id node_id]
-            # Files app, Shared folder
             token_purpose = 'view_shared_file'
             short_link_purpose = link_type.eql?(:public) ? 'token_auth_redirection' : 'shared_folder_auth_link'
           else
             Aspera.error_unexpected_value(shared_data.keys)
           end
-          command = options.get_next_command(%i[create delete list show] + (link_type.eql?(:public) ? %i[modify] : []))
-          case command
-          when :create
-            # Add workspace id
-            workspace_id_hash(shared_data)
-            create_payload = {
-              purpose:            short_link_purpose,
-              user_selected_name: nil
-            }
-            case link_type
-            when :private
-              create_payload[:data] = shared_data
-            when :public
-              create_payload[:expires_at]       = nil
-              create_payload[:password_enabled] = false
-              shared_data[:name] = ''
-              create_payload[:data] = {
-                aoc:            true,
-                url_token_data: {
-                  data:    shared_data,
-                  purpose: token_purpose
-                }
-              }
-            end
-            custom_data = value_create_modify(command: command, default: {})
-            access_levels = custom_data.delete('access_levels')
-            if (pass = custom_data.delete('password'))
-              create_payload[:data][:url_token_data][:password] = pass
-              create_payload[:password_enabled] = true
-            end
-            create_payload.deep_merge!(custom_data)
-            result_create_short_link = aoc_api.create('short_links', create_payload)
-            # Creation: perm_block: permission on node
-            yield(:create, result_create_short_link['resource_id'], access_levels) if block_given? && link_type.eql?(:public)
-            return Main.result_single_object(result_create_short_link)
-          when :delete, :list, :show, :modify
-            workspace_id_hash(shared_data)
-            query = if link_type.eql?(:private)
-              shared_data
-            else
-              {
-                url_token_data: {
-                  data:    shared_data,
-                  purpose: token_purpose
-                }
-              }
-            end
-            list_params = {
-              json_query:  query.to_json,
-              purpose:     short_link_purpose,
-              edit_access: true,
-              # embed: 'updated_by_user',
-              sort:        '-created_at'
-            }
-            short_list = aoc_api.read_with_paging('short_links', list_params.merge(query_read_delete(default: {})).compact)
-            case command
-            when :delete
-              one_id = options.instance_identifier(description: 'short link id')
-              if link_type.eql?(:public)
-                found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
-                raise BadIdentifier.new('Short link', one_id) if found.nil?
-                yield(:delete, found['resource_id'], nil)
-              end
-              aoc_api.delete("short_links/#{one_id}", {
-                edit_access: true,
-                json_query:  shared_data.to_json
-              })
-              return Main.result_status('deleted')
-            when :list
-              return Main.result_object_list(short_list[:items], fields: Formatter.all_but('data'), total: short_list[:total])
-            when :show
-              one_id = options.instance_identifier(description: 'short link id')
-              found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
-              raise BadIdentifier.new('Short link', one_id) if found.nil?
-              return Main.result_single_object(found, fields: Formatter.all_but('data'))
-            when :modify
-              one_id = options.instance_identifier(description: 'short link id')
-              node_file = shared_data.slice(:node_id, :file_id)
-              modify_payload = {
-                edit_access: true,
-                json_query:  node_file
-              }
-              custom_data = value_create_modify(command: command)
-              if (pass = custom_data.delete('password'))
-                modify_payload[:password_enabled] = true
-                modify_payload[:data] = {
-                  url_token_data: {
-                    password: pass,
-                    data:     node_file
-                  }
-                }
-              else
-                modify_payload[:password_enabled] = false
-              end
-              if custom_data.delete('access_levels')
-                # Modification: perm_block: permission on node
-                found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
-                raise BadIdentifier.new('Short link', one_id) if found.nil?
-                yield(:update, found['resource_id'], access_levels)
-              end
-              modify_payload.deep_merge!(custom_data)
-              aoc_api.update("short_links/#{one_id}", modify_payload)
-              return Main.result_status('modified')
-            end
-          else Aspera.error_unexpected_value(command)
+          [token_purpose, short_link_purpose]
+        end
+
+        # Build the list_params hash used by delete/list/show/modify short link operations.
+        # @return [Hash]
+        def short_link_list_params(shared_data:, link_type:, token_purpose:, short_link_purpose:, **)
+          query = if link_type.eql?(:private)
+            shared_data
+          else
+            {url_token_data: {data: shared_data, purpose: token_purpose}}
           end
+          {
+            json_query:  query.to_json,
+            purpose:     short_link_purpose,
+            edit_access: true,
+            sort:        '-created_at'
+          }
         end
 
-        # @return persistency object if option `once_only` is used.
+        # @return [PersistencyActionOnce, nil] persistency object if option `once_only` is used.
         def package_persistency
           return unless options.get_option(:once_only, mandatory: true)
           # TODO: add query info to id
@@ -994,288 +579,1027 @@ module Aspera
           all_packages.reject!{ |pkg| skip_package[pkg['id']]}
         end
 
-        # must be public
-        ACTIONS = %i[reminder servers bearer_token organization tier_restrictions user packages files admin automation gateway].freeze
+        # --- DSL command declarations ---
 
-        def execute_action
-          command = options.get_next_command(ACTIONS)
-          if %i[files packages].include?(command)
-            formatter.display_status("Workspace: #{aoc_api.workspace_info[:name].to_s.red}#{' (default)' if aoc_api.default_workspace?}")
-            if !aoc_api.private_link.nil?
-              folder_name = aoc_api.node_api_from(node_id: aoc_api.home[:node_id]).read("files/#{aoc_api.home[:file_id]}")['name']
-              formatter.display_status("Private Folder: #{folder_name}")
-            end
+        # Root-level commands
+        command :reminder, description: 'Send reminder email with list of orgs'
+        command(
+          :servers, description: 'List AoC servers (no auth)',
+          action: lambda do
+            no_auth_api = Api::AoC.new(url: options.get_option(:url), auth: :none)
+            Result::ObjectList.new(no_auth_api.read('servers'))
           end
-          case command
-          when :reminder
-            # send an email reminder with list of orgs
-            user_email = options.get_option(:username, mandatory: true)
-            Rest.new(base_url: "#{Api::AoC.api_base_url}/#{Api::AoC::API_V1}").create('organization_reminders', {email: user_email})
-            return Main.result_status("List of organizations user is member of, has been sent by e-mail to #{user_email}")
-          when :servers
-            return Main.result_object_list(Rest.new(base_url: "#{Api::AoC.api_base_url}/#{Api::AoC::API_V1}").read('servers'))
-          when :bearer_token
-            return Main.result_text(aoc_api.oauth.authorization)
-          when :organization
-            return Main.result_single_object(aoc_api.read('organization'))
-          when :tier_restrictions
-            return Main.result_single_object(aoc_api.read('tier_restrictions'))
-          when :user
-            user_cmd = options.get_next_command(%i[workspaces profile preferences notifications contacts])
-            case user_cmd
-            when :contacts
-              return execute_resource_action(:contact)
-            # when :settings
-            # return Main.result_object_list(aoc_api.read('client_settings/'))
-            when :workspaces
-              case options.get_next_command(%i[list current])
-              when :list
-                return result_list('workspaces', fields: %w[id name])
-              when :current
-                return Main.result_single_object(aoc_api.workspace_info)
-              end
-            when :profile
-              case options.get_next_command(%i[show modify])
-              when :show
-                return Main.result_single_object(aoc_api.current_user_info(exception: true))
-              when :modify
-                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", options.get_next_argument('properties', validation: Hash))
-                return Main.result_status('modified')
-              end
-            when :preferences, :notifications
-              user_preferences_res = "users/#{aoc_api.current_user_info(exception: true)['id']}/#{user_cmd.eql?(:preferences) ? 'user_interaction_preferences' : 'notification_preferences'}"
-              case options.get_next_command(%i[show modify])
-              when :show
-                return Main.result_single_object(aoc_api.read(user_preferences_res))
-              when :modify
-                aoc_api.update(user_preferences_res, options.get_next_argument('properties', validation: Hash))
-                return Main.result_status('modified')
-              end
+        )
+        command :bearer_token,      description: 'Display bearer token',
+          action: ->{Result::Text.new(aoc_api.oauth.authorization)}
+        command :organization,      description: 'Show organization info',
+          action: ->{Result::SingleObject.new(aoc_api.read('organization'))}
+        command :tier_restrictions, description: 'Show 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
+          command :bearer_token,   description: 'Show admin bearer token',
+            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
-          when :packages
-            package_command = options.get_next_command(%i[shared_inboxes send receive list show delete modify].concat(Node::NODE4_READ_ACTIONS), aliases: {recv: :receive})
-            case package_command
-            when :shared_inboxes
-              case options.get_next_command(%i[list show short_link])
-              when :list
-                default_query = {'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}
-                workspace_id_hash(default_query, string: true)
-                return result_list('dropbox_memberships', fields: %w[dropbox_id dropbox.name], default_query: default_query)
-              when :show
-                return Main.result_single_object(aoc_api.read(get_resource_path_from_args('dropboxes')))
-              when :short_link
-                # TODO: check name
-                return short_link_command(dropbox_id: get_resource_id_from_args('dropboxes'), name: '')
-              end
-            when :send
-              package_data = value_create_modify(command: package_command, schema: Schema::Registry.req_body(Schema::Registry::AOC, 'packages.post'))
-              new_user_option = options.get_option(:new_user_option)
-              option_validate = options.get_option(:validate_metadata)
-              # Works for both normal user auth and link auth.
-              workspace_id_hash(package_data, string: true) unless package_data.key?('workspace_id')
-              if !aoc_api.public_link.nil?
-                aoc_api.assert_public_link_types(%w[send_package_to_user send_package_to_dropbox])
-                box_type = aoc_api.public_link['purpose'].split('_').last
-                package_data['recipients'] = [{'id' => aoc_api.public_link['data']["#{box_type}_id"], 'type' => box_type}]
-                # enforce workspace id from link (should be already ok, but in case user wanted to override)
-                package_data['workspace_id'] = aoc_api.public_link['data']['workspace_id']
-              end
-              package_data['encryption_at_rest'] = true if transfer.user_transfer_spec['content_protection'].eql?('encrypt')
-              # transfer may raise an error
-              created_package = aoc_api.create_package_simple(package_data, option_validate, new_user_option)
-              Main.result_transfer(transfer.start(created_package[:spec], rest_token: created_package[:node]))
-              # return all info on package (especially package id)
-              return Main.result_single_object(created_package[:info])
-            when :receive
-              ids_to_download = nil
-              if !aoc_api.public_link.nil?
-                aoc_api.assert_public_link_types(['view_received_package'])
-                # Set the package id from link
-                ids_to_download = aoc_api.public_link['data']['package_id']
-              end
-              # Get from command line unless it was a public link
-              ids_to_download ||= options.instance_identifier
-              skip_ids_persistency = package_persistency
-              case ids_to_download
-              when SpecialValues::INIT
-                all_packages = list_all_packages_with_query[:items]
-                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.save
-                return Main.result_status("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
-              when SpecialValues::ALL
-                all_packages = list_all_packages_with_query[:items]
-                # remove from list the ones already downloaded
-                reject_packages_from_persistency(all_packages, skip_ids_persistency)
-                ids_to_download = all_packages.map{ |e| e['id']}
-                formatter.display_status("Found #{ids_to_download.length} package(s).")
-              else
-                # single id to array
-                ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
-              end
-              # download all files, or specified list only
-              ts_paths = transfer.ts_source_paths(default: ['.'])
-              per_package_def = options.get_option(:package_folder).symbolize_keys
-              save_metadata = per_package_def.delete(:inf)
-              # get value outside of loop
-              destination_folder = transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE)
-              result_transfer = []
-              ids_to_download.each do |package_id|
-                package_info = aoc_api.read("packages/#{package_id}")
-                package_node_api = aoc_api.node_api_from(
-                  node_id: package_info['node_id'],
-                  package_info: package_info,
-                  **workspace_id_hash(name: true)
-                )
-                transfer_spec = package_node_api.transfer_spec_gen4(
-                  package_info['contents_file_id'],
-                  Transfer::Spec::DIRECTION_RECEIVE,
-                  {'paths'=> ts_paths}
-                )
-                transfer.user_transfer_spec['destination_root'] = self.class.unique_folder(package_info, destination_folder, **per_package_def) unless per_package_def.empty?
-                dest_folder = transfer.user_transfer_spec['destination_root'] || destination_folder
-                formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{dest_folder}]})
-                statuses = transfer.start(
-                  transfer_spec,
-                  rest_token: package_node_api
-                )
-                File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata
-                result_transfer.push({'package' => package_id, Main::STATUS_FIELD => statuses})
-                # update skip list only if all transfer sessions completed
-                if skip_ids_persistency && TransferAgent.session_status(statuses).eql?(:success)
-                  skip_ids_persistency.data.push(package_id)
-                  skip_ids_persistency.save
+          )
+          command :usage_reports,  description: 'List usage reports',
+            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'
+          ADMIN_OBJECTS.each do |res|
+            cfg            = ADMIN_OBJECT_CONFIG.fetch(res, {})
+            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"}]
+            ops            = if cfg[:ops]
+              cfg[:ops]
+            elsif is_singleton
+              %i[show]
+            else
+              Operations::ALL + (cfg[:extra_ops] || [])
+            end
+            command(res, description: "Manage #{res.to_s.tr('_', ' ')}")
+            commands_under([:admin, res]) do
+              ops.each do |op|
+                extra_setup = op_setup[op]
+                base_attrs = extra_setup ? {setup: extra_setup} : {}
+                extra_arg_list =
+                  if !is_singleton && op.eql?(:create)
+                    c = aoc_res_cfg(res)
+                    [{name: :data, type: Hash, bulk: true, schema: c[:schema]}]
+                  elsif !is_singleton && op.eql?(:modify)
+                    c = aoc_res_cfg(res)
+                    [{name: :data, type: Hash, schema: c[:schema]}]
+                  elsif extra_op_args.key?(op)
+                    extra_op_args[op]
+                  else
+                    []
+                  end
+                # For non-global ops, prepend the identifier spec
+                arg_list = (Operations::GLOBAL.include?(op) ? [] : id_arg_spec) + extra_arg_list
+                merged = arg_list.empty? ? base_attrs : base_attrs.merge(arguments: arg_list)
+                # Attach query_schema (full path) to :list CommandSpec so --help shows the tip
+                if op.eql?(:list)
+                  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)
               end
-              return Main.result_transfer_multiple(result_transfer)
-            when :show
-              package_id = options.instance_identifier
-              package_info = aoc_api.read("packages/#{package_id}")
-              return Main.result_single_object(package_info)
-            when :list
-              result = list_all_packages_with_query
-              skip_ids_persistency = package_persistency
-              reject_packages_from_persistency(result[:items], skip_ids_persistency)
-              display_fields = PACKAGE_LIST_DEFAULT_FIELDS
-              display_fields += ['workspace_id'] if aoc_api.workspace_info[:id].nil?
-              return Main.result_object_list(result[:items], fields: display_fields, total: result[:total])
-            when :delete
-              return do_bulk_operation(command: package_command, values: options.instance_identifier) do |package_id|
-                Aspera.assert_type(package_id, String, Integer){'identifier'}
-                aoc_api.delete("packages/#{package_id}")
-              end
-            when :modify
-              package_id = options.instance_identifier
-              package_data = value_create_modify(command: package_command)
-              aoc_api.update("packages/#{package_id}", package_data)
-              return Main.result_status('modified')
-            when *Node::NODE4_READ_ACTIONS
-              package_id = options.instance_identifier
-              package_info = aoc_api.read("packages/#{package_id}")
-              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['contents_file_id'], scope: Api::Node::Scope::USER)
             end
-          when :files
-            command_repo = options.get_next_command([:short_link].concat(FILES_COMMANDS))
-            case command_repo
-            when *FILES_COMMANDS
-              return execute_nodegen4_command(command_repo, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER)
-            when :short_link
-              folder_dest = options.get_next_argument('path', validation: String)
-              home_node_api = aoc_api.node_api_from(
-                node_id: aoc_api.home[:node_id],
-                **workspace_id_hash(name: true)
-              )
-              shared_apifid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder_dest)
-              return short_link_command(
-                node_id:        shared_apifid.node_api.app_info.node_info['id'],
-                file_id:        shared_apifid.file_id
-              ) do |op, id, access_levels|
-                case op
-                when :create
-                  # `id` is the resource id
-                  perm_data = {
-                    'file_id'       => shared_apifid.file_id,
-                    'access_id'     => id,
-                    'access_type'   => 'user',
-                    'access_levels' => Api::AoC.expand_access_levels(access_levels),
-                    'tags'          => {
-                      'url_token'        => true,
-                      'folder_name'      => File.basename(folder_dest),
-                      'created_by_name'  => aoc_api.current_user_info['name'],
-                      'created_by_email' => aoc_api.current_user_info['email'],
-                      'access_key'       => shared_apifid.node_api.app_info.node_info['access_key'],
-                      'node'             => shared_apifid.node_api.app_info.node_info['name'],
-                      **workspace_id_hash(string: true, name: true)
-                    }
-                  }
-                  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
-                  # `id` is the permission_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)}
-                  raise Error, "Short link not found: #{id}" if found.nil?
-                  shared_apifid.node_api.update("permissions/#{found['id']}", {access_levels: Api::AoC.expand_access_levels(access_levels)})
-                when :delete
-                  # `id` is the resource id, i.e. `access_id`
-                  found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).first
-                  raise Error, "Short link not found: #{id}" if found.nil?
-                  shared_apifid.node_api.delete("permissions/#{found['id']}")
-                else Aspera.error_unexpected_value(op)
+          end
+        end
+        # admin > workspace > shared_folder sub-tree
+        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}],
+            setup: :setup_admin_workspace_shared_folder_node
+          command :member, description: 'Show folder members',
+            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)}
+        end
+        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
+          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)}
+        end
+        # admin > user > preferences|notifications sub-trees
+        %i[preferences notifications].each do |pref|
+          commands_under([:admin, :user, pref]) do
+            command :show,   description: "Show #{pref}"
+            command :modify, description: "Modify #{pref}",
+              arguments: [{name: :properties, type: Hash}]
+          end
+        end
+        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}
+        end
+        commands_under(%i[admin subscription]) do
+          command :account, description: 'Show subscription account'
+          command :usage,   description: 'Show subscription usage',
+            arguments: [
+              {name: :aggregate,   mandatory: false, default: :ALL, allowed: %i[ALL MONTHLY]},
+              {name: :start_date,  mandatory: false, default: nil},
+              {name: :end_date,    mandatory: false, default: nil}
+            ]
+        end
+        commands_under(%i[admin analytics]) do
+          command :application_events, description: 'List application events'
+          command :transfers,          description: 'List transfer events',
+            arguments: [
+              {name: :event_resource_type, mandatory: true,  allowed: %i[organizations users nodes]},
+              {name: :event_resource_id,   mandatory: false, default: nil}
+            ]
+          command :files,              description: 'List file events',
+            arguments: [
+              {name: :event_resource_type, mandatory: true, allowed: %i[organizations users nodes]},
+              {name: :event_resource_id,   mandatory: true},
+              {name: :event_uuid,          mandatory: true}
+            ]
+        end
+        # application sub-commands
+        commands_under(%i[admin application]) do
+          command :types,      description: 'List application types',
+            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'
+        end
+        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
+          APP_TYPES.each do |app_type|
+            command(app_type, description: "Settings for #{app_type} app")
+            commands_under(APP_SETTINGS_PATH + [app_type]) do
+              command :show, description: "Show #{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}],
+                action: lambda do |properties:, **|
+                  aoc_api.update("/apps/#{app_type}/settings", properties)
+                  Result::Status.new('modified')
                 end
-              end
+              )
+            end
+          end
+        end
+        commands_under(APP_INSTANCE_PATH) do
+          command(:list, description: 'List app instances', action: lambda do
+            result_list(
+              'admin/apps_new',
+              fields:        %w[id app_type available workspace_id],
+              default_query: {workspace_id: aoc_api.workspace_info[:id]}
+            )
+          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 :show,   description: "Show a #{app_type} instance",
+                arguments: [{name: :res_id, type: :identifier}]
+              command :modify, description: "Modify a #{app_type} instance",
+                arguments: [{name: :res_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}]
+        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'
+          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
+          )
+        end
+
+        commands_under(%i[user preferences]) do
+          command(
+            :show, description: 'Show user preferences',
+            action: lambda do
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              Result::SingleObject.new(aoc_api.read("users/#{user_id}/user_interaction_preferences"))
+            end
+          )
+          command(
+            :modify, description: 'Modify user preferences',
+            arguments: [{name: :properties, type: Hash}],
+            action: lambda do |properties:, **|
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              aoc_api.update("users/#{user_id}/user_interaction_preferences", properties)
+              Result::Status.new('modified')
             end
-          when :automation
-            change_api_scope(Api::AoC::Scope::ADMIN_USER)
-            Log.log.warn('BETA: work under progress')
-            # automation api is not in the same place
-            automation_api = Rest.new(**aoc_api.params, base_url: aoc_api.base_url.gsub('/api/', '/automation/'))
-            command_automation = options.get_next_command(%i[workflows instances])
-            case command_automation
-            when :instances
-              return entity_execute(api: aoc_api, entity: 'workflow_instances')
-            when :workflows
-              wf_command = options.get_next_command(%i[action launch].concat(Operations::ALL))
-              case wf_command
-              when *Operations::ALL
-                return entity_execute(
-                  api: automation_api,
-                  entity: 'workflows',
-                  command: wf_command
-                )
-              when :launch
-                wf_id = options.instance_identifier
-                data = automation_api.create("workflows/#{wf_id}/launch", {})
-                return Main.result_single_object(data)
-              when :action
-                # TODO: not complete
-                wf_id = options.instance_identifier
-                wf_action_cmd = options.get_next_command(%i[list create show])
-                Log.log.warn{"Not implemented: #{wf_action_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'})
-                automation_api.update("steps/#{step['id']}", {'action_order' => [action['id']]})
-                wf = automation_api.read("workflows/#{wf_id}")
-                return Main.result_single_object(wf)
+          )
+        end
+
+        commands_under(%i[user notifications]) do
+          command(
+            :show, description: 'Show notification preferences',
+            action: lambda do
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              Result::SingleObject.new(aoc_api.read("users/#{user_id}/notification_preferences"))
+            end
+          )
+          command(
+            :modify, description: 'Modify notification preferences',
+            arguments: [{name: :properties, type: Hash}],
+            action: lambda do |properties:, **|
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              aoc_api.update("users/#{user_id}/notification_preferences", properties)
+              Result::Status.new('modified')
+            end
+          )
+        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,
+            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,
+            arguments: [{name: :package_id, type: :identifier}]
+          command :list,              description: 'List packages'
+          command :show,              description: 'Show a package',
+            arguments: [{name: :package_id, type: :identifier}]
+          command :delete,            description: 'Delete package(s)',
+            arguments: [{name: :package_id, type: :identifier}]
+          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',
+            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
+          command :list,       description: 'List shared inboxes',
+            action: (lambda do
+              result_list(
+                'dropbox_memberships',
+                fields: %w[dropbox_id dropbox.name],
+                default_query: workspace_id_hash({'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}, string: true)
+              )
+            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}"))}
+          command :short_link, description: 'Manage shared inbox short links',
+            arguments: [{name: :link_type, allowed: %i[public private]}],
+            setup: :setup_packages_short_link
+        end
+        # 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
+          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'
+        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(%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}]
+        end
+
+        # --- setup methods ---
+
+        # Display workspace info before dispatching files/packages sub-commands.
+        # Returns {} so it does not inject anything into ctx.
+        def setup_workspace_display(**)
+          formatter.display_status("Workspace: #{aoc_api.workspace_info[:name].to_s.red}#{' (default)' if aoc_api.default_workspace?}")
+          if !aoc_api.private_link.nil?
+            folder_name = aoc_api.node_api_from(node_id: aoc_api.home[:node_id]).read("files/#{aoc_api.home[:file_id]}")['name']
+            formatter.display_status("Private Folder: #{folder_name}")
+          end
+          {}
+        end
+
+        # Build automation API and store in @automation_api ivar.
+        def setup_automation_api(**)
+          change_api_scope(Api::AoC::Scope::ADMIN_USER)
+          Log.log.warn('BETA: work under progress')
+          @automation_api = Rest.new(**aoc_api.params, base_url: aoc_api.base_url.gsub('/api/', '/automation/'))
+          {}
+        end
+
+        # --- handler methods ---
+
+        def action_reminder
+          user_email = options.get_option(:username, mandatory: true)
+          no_auth_api = Api::AoC.new(url: options.get_option(:url), auth: :none)
+          no_auth_api.create('organization_reminders', {email: user_email})
+          return Result::Status.new("List of organizations user is member of, has been sent by e-mail to #{user_email}")
+        end
+
+        # packages > send
+        def action_packages_send(data:, **)
+          package_data = data
+          new_user_option = options.get_option(:new_user_option)
+          option_validate = options.get_option(:validate_metadata)
+          workspace_id_hash(package_data, string: true) unless package_data.key?('workspace_id')
+          if !aoc_api.public_link.nil?
+            aoc_api.assert_public_link_types(%w[send_package_to_user send_package_to_dropbox])
+            box_type = aoc_api.public_link['purpose'].split('_').last
+            package_data['recipients'] = [{'id' => aoc_api.public_link['data']["#{box_type}_id"], 'type' => box_type}]
+            package_data['workspace_id'] = aoc_api.public_link['data']['workspace_id']
+          end
+          package_data['encryption_at_rest'] = true if transfer.user_transfer_spec['content_protection'].eql?('encrypt')
+          created_package = aoc_api.create_package_simple(package_data, option_validate, new_user_option)
+          Runner.result_transfer(transfer.start(created_package[:spec], rest_token: created_package[:node]))
+          return Result::SingleObject.new(created_package[:info])
+        end
+
+        # packages > receive — package_id: from arguments:(:identifier) (or overridden by public_link)
+        def action_packages_receive(package_id:, **)
+          ids_to_download = if aoc_api.public_link.nil?
+            package_id
+          else
+            aoc_api.assert_public_link_types(['view_received_package'])
+            aoc_api.public_link['data']['package_id']
+          end
+          skip_ids_persistency = package_persistency
+          case ids_to_download
+          when SpecialValues::INIT
+            all_packages = list_all_packages_with_query[:items]
+            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.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']}
+            formatter.display_status("Found #{ids_to_download.length} package(s).")
+          else
+            ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
+          end
+          ts_paths = transfer.ts_source_paths(default: ['.'])
+          per_package_def = options.get_option(:package_folder).symbolize_keys
+          save_metadata = per_package_def.delete(:inf)
+          destination_folder = transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE)
+          result_transfer = []
+          ids_to_download.each do |package_id|
+            package_info = aoc_api.read("packages/#{package_id}")
+            package_node_api = aoc_api.node_api_from(
+              node_id: package_info['node_id'],
+              package_info: package_info,
+              **workspace_id_hash(name: true)
+            )
+            transfer_spec = package_node_api.transfer_spec_gen4(
+              package_info['contents_file_id'],
+              Transfer::Spec::DIRECTION_RECEIVE,
+              {'paths'=> ts_paths}
+            )
+            transfer.user_transfer_spec['destination_root'] = self.class.unique_folder(package_info, destination_folder, **per_package_def) unless per_package_def.empty?
+            dest_folder = transfer.user_transfer_spec['destination_root'] || destination_folder
+            formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{dest_folder}]})
+            statuses = transfer.start(transfer_spec, rest_token: package_node_api)
+            File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata
+            result_transfer.push({'package' => package_id, Runner::STATUS_FIELD => statuses})
+            if skip_ids_persistency && statuses.is_a?(Transfer::Result::Success)
+              skip_ids_persistency.data.push(package_id)
+              skip_ids_persistency.save
+            end
+          end
+          return Runner.result_transfer_multiple(result_transfer)
+        end
+
+        # packages > list
+        def action_packages_list
+          result = list_all_packages_with_query
+          skip_ids_persistency = package_persistency
+          reject_packages_from_persistency(result[:items], skip_ids_persistency)
+          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])
+        end
+
+        # packages > show
+        def action_packages_show(package_id:, **)
+          Result::SingleObject.new(aoc_api.read("packages/#{package_id}"))
+        end
+
+        # 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'}
+            aoc_api.delete("packages/#{one_id}")
+          end
+        end
+
+        # packages > modify
+        def action_packages_modify(data:, package_id:, **)
+          aoc_api.update("packages/#{package_id}", data)
+          Result::Status.new('modified')
+        end
+
+        # packages > bearer_token_node / node_info / browse / 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:, **|
+            package_info = aoc_api.read("packages/#{package_id}")
+            execute_nodegen4_command(action, package_info['node_id'], file_id: package_info['contents_file_id'], scope: Api::Node::Scope::USER)
+          end
+        end
+
+        # setup: files > short_link
+        # Resolves the target folder, consumes link_type argument, computes purposes.
+        # @return [Hash] ctx keys: sl_shared_data, sl_link_type, sl_token_purpose, sl_short_link_purpose, sl_perm_block, sl_shared_apifid, sl_folder_dest
+        def setup_files_short_link(folder_dest:, link_type:, **)
+          home_node_api = aoc_api.node_api_from(
+            node_id: aoc_api.home[:node_id],
+            **workspace_id_hash(name: true)
+          )
+          shared_apifid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder_dest)
+          shared_data = {
+            node_id: shared_apifid.node_api.app_info.node_info['id'],
+            file_id: shared_apifid.file_id
+          }
+          token_purpose, short_link_purpose = short_link_purposes(shared_data, link_type)
+          perm_block = lambda do |op, id, access_levels|
+            case op
+            when :create
+              perm_data = {
+                'file_id'       => shared_apifid.file_id,
+                'access_id'     => id,
+                'access_type'   => 'user',
+                'access_levels' => Api::AoC.expand_access_levels(access_levels),
+                'tags'          => {
+                  'url_token'        => true,
+                  'folder_name'      => File.basename(folder_dest),
+                  'created_by_name'  => aoc_api.current_user_info['name'],
+                  'created_by_email' => aoc_api.current_user_info['email'],
+                  'access_key'       => shared_apifid.node_api.app_info.node_info['access_key'],
+                  'node'             => shared_apifid.node_api.app_info.node_info['name'],
+                  **workspace_id_hash(string: true, name: true)
+                }
+              }
+              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}"}
+              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}"}
+              shared_apifid.node_api.delete("permissions/#{found['id']}")
+            else Aspera.error_unexpected_value(op)
+            end
+          end
+          {
+            sl_shared_data:        shared_data,
+            sl_link_type:          link_type,
+            sl_token_purpose:      token_purpose,
+            sl_short_link_purpose: short_link_purpose,
+            sl_perm_block:         perm_block
+          }
+        end
+
+        # setup: packages > shared_inboxes > short_link
+        # Reads dropbox_id, consumes link_type argument, computes purposes.
+        # @return [Hash] ctx keys: sl_shared_data, sl_link_type, sl_token_purpose, sl_short_link_purpose
+        def setup_packages_short_link(link_type:, **)
+          dropbox_id = get_resource_id_from_args('dropboxes')
+          shared_data = {dropbox_id: dropbox_id, name: ''}
+          token_purpose, short_link_purpose = short_link_purposes(shared_data, link_type)
+          {
+            sl_shared_data:        shared_data,
+            sl_link_type:          link_type,
+            sl_token_purpose:      token_purpose,
+            sl_short_link_purpose: short_link_purpose,
+            sl_perm_block:         nil
+          }
+        end
+
+        # Shared implementation for short_link > create
+        def sl_exec_create(custom_data = {}, sl_shared_data:, sl_link_type:, sl_token_purpose:, sl_short_link_purpose:, sl_perm_block:, **)
+          shared_data = sl_shared_data.dup
+          workspace_id_hash(shared_data)
+          create_payload = {purpose: sl_short_link_purpose, user_selected_name: nil}
+          case sl_link_type
+          when :private
+            create_payload[:data] = shared_data
+          when :public
+            create_payload[:expires_at]       = nil
+            create_payload[:password_enabled] = false
+            shared_data[:name] = ''
+            create_payload[:data] = {
+              aoc:            true,
+              url_token_data: {data: shared_data, purpose: sl_token_purpose}
+            }
+          end
+          custom_data = {}
+          access_levels = custom_data.delete('access_levels')
+          if (pass = custom_data.delete('password'))
+            create_payload[:data][:url_token_data][:password] = pass
+            create_payload[:password_enabled] = true
+          end
+          create_payload.deep_merge!(custom_data)
+          result_create_short_link = aoc_api.create('short_links', create_payload)
+          sl_perm_block&.call(:create, result_create_short_link['resource_id'], access_levels) if sl_link_type.eql?(:public)
+          Result::SingleObject.new(result_create_short_link)
+        end
+
+        # Shared implementation for short_link > delete|list|show|modify: fetch the short_list
+        def sl_fetch_list(sl_shared_data:, sl_link_type:, sl_token_purpose:, sl_short_link_purpose:, **)
+          shared_data = sl_shared_data.dup
+          workspace_id_hash(shared_data)
+          list_params = short_link_list_params(
+            shared_data: shared_data, link_type: sl_link_type,
+            token_purpose: sl_token_purpose, short_link_purpose: sl_short_link_purpose
+          )
+          {
+            sl_short_list:     aoc_api.read_with_paging('short_links', list_params.merge(query_read_delete(default: {})).compact),
+            sl_shared_data_ws: shared_data
+          }
+        end
+
+        # Shared implementation for short_link > delete
+        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)}
+            raise BadIdentifier.new('Short link', one_id) if found.nil?
+            sl_perm_block&.call(:delete, found['resource_id'], nil)
+          end
+          aoc_api.delete("short_links/#{one_id}", {edit_access: true, json_query: sl_shared_data_ws.to_json})
+          Result::Status.new('deleted')
+        end
+
+        # Shared implementation for short_link > list
+        def sl_exec_list(sl_short_list:, **)
+          Result::ObjectList.new(sl_short_list[:items], fields: Formatter.all_but('data'), total: sl_short_list[:total])
+        end
+
+        # 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)}
+          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'}
+          one_id = short_link_id
+          node_file = sl_shared_data.slice(:node_id, :file_id)
+          modify_payload = {edit_access: true, json_query: node_file}
+          custom_data = {}
+          if (pass = custom_data.delete('password'))
+            modify_payload[:password_enabled] = true
+            modify_payload[:data] = {url_token_data: {password: pass, data: node_file}}
+          else
+            modify_payload[:password_enabled] = false
+          end
+          if custom_data.delete('access_levels')
+            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
+          modify_payload.deep_merge!(custom_data)
+          aoc_api.update("short_links/#{one_id}", modify_payload)
+          Result::Status.new('modified')
+        end
+
+        # files > transfer
+        def action_files_transfer(direction:, source_folder:, **)
+          execute_nodegen4_command(
+            :transfer, aoc_api.home[:node_id],
+            file_id:            aoc_api.home[:file_id],
+            scope:              Api::Node::Scope::USER,
+            transfer_direction: direction,
+            transfer_source:    source_folder
+          )
+        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)
+          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))
+          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)
+            Result::Status.new('modified')
+          end
+        end
+
+        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'}
+          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))
+        end
+
+        def action_admin_application_membership_delete(res_id:, **)
+          aoc_api.delete("apps/app_memberships/#{res_id}")
+          Result::Status.new('deleted')
+        end
+
+        # admin - setup: change API scope to admin once
+        def setup_admin_scope(**)
+          change_api_scope(Api::AoC::Scope::ADMIN)
+          {}
+        end
+
+        # admin > subscription > account
+        def action_admin_subscription_account
+          org = aoc_api.read('organization')
+          result = GraphQL.execute(api_from_options('bss/platform/graphql'), 'bss_subscription_account', {organization_id: org['id']})
+          Result::SingleObject.new(result['aoc']['bssSubscription'])
+        end
+
+        # admin > subscription > usage
+        def action_admin_subscription_usage(aggregate:, start_date:, end_date:, **)
+          today      = Date.today
+          aggregate  = :ALL if aggregate.nil?
+          start_date = today.prev_year.strftime('%Y-%m-%d') if start_date.nil?
+          end_date   = today.strftime('%Y-%m-%d') if end_date.nil?
+          org    = aoc_api.read('organization')
+          result = GraphQL.execute(
+            api_from_options('bss/platform/graphql'), 'bss_subscription_usage',
+            {organization_id: org['id'], aggregate: aggregate, startDate: start_date, endDate: end_date}
+          )
+          Result::SingleObject.new(result['aoc'])
+        end
+
+        # 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']
+          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']
+            when :users         then aoc_api.current_user_info['id']
+            when :nodes         then aoc_api.current_user_info['read_only_home_node_id']
+            else Aspera.error_unreachable_line
+            end
+          filter = query_read_delete(default: {})
+          filter['limit'] ||= 100
+          if options.get_option(:once_only, mandatory: true)
+            saved_date = []
+            start_date_persistency = PersistencyActionOnce.new(
+              manager: persistency,
+              data:    saved_date,
+              id:      IdGenerator.from_list('aoc_ana_date', options.get_option(:url, mandatory: true), aoc_api.workspace_info[:name], event_resource_type.to_s, event_resource_id)
+            )
+            start_date_time = saved_date.first
+            stop_date_time  = Time.now.utc.strftime('%FT%T.%LZ')
+            saved_date[0]   = stop_date_time
+            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']
+          start_date_persistency&.save
+          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']
+            when :users         then aoc_api.current_user_info['id']
+            when :nodes         then aoc_api.current_user_info['read_only_home_node_id']
+            else Aspera.error_unreachable_line
+            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']
+          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|
+          define_method(:"lookup_aoc_#{res}_id") do |_field, value, **|
+            aoc_api.lookup_with_q(aoc_res_path(res), value: value)['id']
+          end
+        end
+
+        # admin > <res> > list
+        ADMIN_OBJECTS.each do |res|
+          define_action_method([:admin, res, :list]) do
+            c = aoc_res_cfg(res)
+            result_list(c[:path], fields: c[:list_fields], query_component: c[:query_component])
+          end
+        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:, **|
+            c = aoc_res_cfg(res)
+            Result::SingleObject.new(aoc_api.read("#{c[:path]}/#{res_id}", query_read_delete), fields: Formatter.all_but('certificate'))
+          end
+        end
+
+        # admin > organization|self > show (singleton)
+        %i[organization self].each do |res|
+          define_action_method([:admin, res, :show]) do
+            Result::SingleObject.new(aoc_api.read(res.to_s, query_read_delete), fields: Formatter.all_but('certificate'))
+          end
+        end
+
+        # admin > <res> > create
+        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|
+              params['workspace_id'] = workspace_id if c[:require_ws_id] && workspace_id && !params.key?('workspace_id')
+              aoc_api.create(path, params)
+            end
+          end
+        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:, **|
+            c = aoc_res_cfg(res)
+            aoc_api.update("#{c[:path]}/#{res_id}", data)
+            Result::Status.new('modified')
+          end
+        end
+
+        # admin > <res> > delete
+        ADMIN_OBJECTS.reject do |r|
+          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:, **|
+            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|
+              aoc_api.delete("#{c[:path]}/#{one_id}")
+              {'id' => one_id}
+            end
+          end
+        end
+
+        # user > contacts > list|show|create|modify|delete (same API path as admin > contact)
+        Operations::ALL.each do |op|
+          define_action_method([:user, :contacts, op]) do |**ctx|
+            send(CommandSpec.action_method([:admin, :contact, op]), **ctx)
+          end
+        end
+
+        # admin > client > set_pub_key
+        def action_admin_client_set_pub_key(private_key_pem:, res_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})
+          Result::Success.new
+        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)
+          end
+        end
+
+        # admin > node > bearer_token
+        def action_admin_node_bearer_token(scope:, res_id:, **)
+          scope ||= Api::Node::Scope::ADMIN
+          node_api = aoc_api.node_api_from(node_id: res_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}
+        end
+
+        # admin > workspace > dropbox > list
+        def action_admin_workspace_dropbox_list(ws_res_id:, **)
+          query = options.get_option(:query) || {}
+          Result::ObjectList.new(aoc_api.read('dropboxes', query.merge({'workspace_id' => ws_res_id})), fields: %w[id name description])
+        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})
+          shared_folders = aoc_api.read_with_paging("#{resource_instance_path}/permissions", query)[:items]
+          {ws_res_id: res_id, shared_folders: shared_folders}
+        end
+
+        # admin > workspace > shared_folder > list
+        def action_admin_workspace_shared_folder_list(shared_folders:, **)
+          Result::ObjectList.new(shared_folders, fields: %w[id node_name node_id file_id file.path tags.aspera.files.workspace.share_as])
+        end
+
+        # 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)}
+          Aspera.assert(sf_item, 'shared folder not found')
+          {sf_item: sf_item}
+        end
+
+        alias_method :setup_admin_workspace_shared_folder_node,   :resolve_sf_item
+        alias_method :setup_admin_workspace_shared_folder_member, :resolve_sf_item
+
+        # 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)
+          end
+        end
+
+        # admin > workspace > shared_folder > member > list
+        def action_admin_workspace_shared_folder_member_list(ws_res_id:, sf_item:, **)
+          node_api = aoc_api.node_api_from(
+            node_id:        sf_item['node_id'],
+            workspace_id:   ws_res_id,
+            workspace_name: nil,
+            scope:          Api::Node::Scope::USER
+          )
+          result = node_api.read('permissions', {'file_id' => sf_item['file_id'], 'tag' => "aspera.files.workspace.id=#{ws_res_id}"})
+          result.each do |item|
+            item['member'] = begin
+              if Api::AoC.workspace_access?(item)
+                {'name' => '[Internal permission]'}
+              else
+                aoc_api.read("admin/#{item['access_type']}s/#{item['access_id']}") rescue {'name' => 'not found'}
               end
+            rescue => e
+              {'name' => e.to_s}
             end
-          when :admin
-            return execute_admin_action
-          when :gateway
-            require 'aspera/faspex_gw'
-            parameters = value_create_modify(command: command, default: {}).symbolize_keys
-            uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
-            server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-            Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?)
-            server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.workspace_info[:id])
-            server.start
-            return Main.result_status('Gateway terminated')
-          else Aspera.error_unreachable_line
           end
-          Aspera.error_unreachable_line
+          # TODO : read users and group name and add, if query "include_members"
+          Result::ObjectList.new(result, fields: %w[access_type access_id access_level last_updated_at member.name member.email member.system_group_type member.system_group])
         end
 
-        private :execute_admin_action
+        # admin > user > preferences|notifications > show|modify
+        # (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}"))
+          end
+          define_action_method([:admin, :user, pref, :modify]) do |properties:, res_id:, **|
+            aoc_api.update("#{aoc_res_path(:user)}/#{res_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}"}
+            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'})
+            @automation_api.update("steps/#{step['id']}", {'action_order' => [action['id']]})
+            Result::SingleObject.new(@automation_api.read("workflows/#{wf_id}"))
+          end
+        end
+
+        def action_gateway(parameters: {}, **)
+          require 'aspera/faspex_gw'
+          parameters = parameters.symbolize_keys
+          uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
+          server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
+          Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?){"unexpected parameters: #{parameters.except(*WebServerSimple::PARAMS).keys}"}
+          server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.workspace_info[:id])
+          server.start
+          return Result::Status.new('Gateway terminated')
+        end
       end
     end
   end