aspera-cli 4.27.2 → 4.27.3

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

@@ -18,11 +18,13 @@ require 'aspera/assert'
 require 'aspera/graphql'
 require 'securerandom'
 require 'date'
+require 'aspera/rainbow'
+using Rainbow
 
 module Aspera
   module Cli
     module Plugins
-      class Aoc < Oauth
+      class Aoc < Oauth # rubocop:disable Metrics/ClassLength
         # default redirect for AoC web auth
         REDIRECT_LOCALHOST = 'http://localhost:12345'
         # admin objects that can be manipulated
@@ -70,7 +72,7 @@ module Aspera
             base_url = "#{base_url}.#{Api::AoC::SAAS_DOMAIN_PROD}" unless base_url.include?('.')
             # AoC is only https
             return unless base_url.start_with?('https://')
-            location = Rest.new(base_url: base_url, redirect_max: 0).call(operation: 'GET', subpath: 'auth/ping', exception: false, ret: :resp)['Location']
+            location = Rest::Client.new(base_url: base_url, redirect_max: 0).call(operation: 'GET', subpath: 'auth/ping', exception: false, ret: :resp)['Location']
             return if location.nil?
             redirect_uri = URI.parse(location)
             od = Api::AoC.split_org_domain(URI.parse(base_url))
@@ -145,25 +147,25 @@ module Aspera
           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: {}}]
+                :create, description: base.operation_description(:create, 'short link'),
+                arguments: [{name: :short_link, 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: {}}]
+                :modify, description: base.operation_description(:modify, 'short link'),
+                arguments: [{name: :short_link_id, type: :identifier}, {name: :short_link, type: Hash, mandatory: false, default: {}}]
               )
-              base.command(:list, description: 'List short links')
+              base.command(:list, description: base.operation_description(:list, 'short link'))
               base.command(
-                :show, description: 'Show a short link',
+                :show, description: base.operation_description(:show, 'short link'),
                 arguments: [{name: :short_link_id, type: :identifier}]
               )
               base.command(
-                :delete, description: 'Delete a short link',
+                :delete, description: base.operation_description(:delete, 'short link'),
                 arguments: [{name: :short_link_id, type: :identifier}]
               )
             end
-            base.define_action_method(parent_path + [:create]) do |custom_data: {}, **ctx|
-              sl_exec_create(custom_data, **ctx)
+            base.define_action_method(parent_path + [:create]) do |short_link: {}, **ctx|
+              sl_exec_create(short_link, **ctx)
             end
             base.define_action_method(parent_path + [:list]) do |**ctx|
               sl_exec_list(**sl_fetch_list(**ctx))
@@ -174,8 +176,8 @@ module Aspera
             base.define_action_method(parent_path + [:delete]) do |**ctx|
               sl_exec_delete(**sl_fetch_list(**ctx), **ctx)
             end
-            base.define_action_method(parent_path + [:modify]) do |custom_data: {}, **ctx|
-              sl_exec_modify(custom_data, **sl_fetch_list(**ctx), **ctx)
+            base.define_action_method(parent_path + [:modify]) do |short_link: {}, **ctx|
+              sl_exec_modify(short_link, **sl_fetch_list(**ctx), **ctx)
             end
           end
         end
@@ -187,7 +189,7 @@ module Aspera
           pub_link_info = Api::AoC.link_info(app_url)
           # public link case
           if pub_link_info.key?(:token)
-            pub_api = Rest.new(base_url: "https://#{URI.parse(pub_link_info[:url]).host}/api/v1")
+            pub_api = Rest::Client.new(base_url: "https://#{URI.parse(pub_link_info[:url]).host}/api/v1")
             pub_info = pub_api.read('env/url_token_check', {token: pub_link_info[:token]})
             preset_value = {
               link: app_url
@@ -198,8 +200,6 @@ module Aspera
               test_args:    'organization'
             }
           end
-          options.declare(:use_generic_client, description: 'Wizard: AoC: use global or org specific jwt client id', allowed: Type::BOOLEAN, default: Api::AoC.saas_url?(app_url))
-          options.parse_options!
           # make username mandatory for jwt, this triggers interactive input
           wiz_username = options.get_option(:username, mandatory: true)
           wizard.check_email(wiz_username)
@@ -216,7 +216,10 @@ module Aspera
           client_id = options.get_option(:client_id)
           client_secret = options.get_option(:client_secret)
           if client_id.nil? || client_secret.nil?
-            if options.get_option(:use_generic_client)
+            use_generic_client = options.get_option(:use_generic_client)
+            # Default depends on URL
+            use_generic_client = Api::AoC.saas_url?(app_url) if use_generic_client.nil?
+            if use_generic_client
               client_id = client_secret = nil
               formatter.display_status('Using global client_id.')
             else
@@ -270,6 +273,7 @@ module Aspera
         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: Type::BOOLEAN, default: true
         option :package_folder,    schema: Schema::Registry::PACKAGE_FOLDER_OPTIONS
+        option :use_generic_client, description: 'Wizard: AoC: use global or org specific jwt client id (default: global for SaaS URL)', allowed: Type::BOOLEAN
 
         use_options Node
 
@@ -279,7 +283,6 @@ module Aspera
           @cache_home_node_file = nil
           @cache_api_aoc = nil
           @scope = Api::AoC::Scope::USER
-          options.parse_options!
         end
 
         # Change API scope for subsequent calls, re-instantiate API object
@@ -293,7 +296,7 @@ module Aspera
 
         # Create an API object with the options from CLI, but with a different subpath
         # @param base_path [String] Base path for APIs.
-        # @return [Api::AoC] API object for AoC (is Rest)
+        # @return [Api::AoC] API object for AoC (is Rest::Client)
         def api_from_options(base_path)
           # Get all existing OAuth kwargs from `options`.
           api = Api::AoC.new(
@@ -318,7 +321,7 @@ module Aspera
         end
 
         # AoC Rest object
-        # @return [Api::AoC] API object for AoC (is Rest)
+        # @return [Api::AoC] API object for AoC (is Rest::Client)
         def aoc_api
           if @cache_api_aoc.nil?
             @cache_api_aoc = api_from_options(Api::AoC::API_V1)
@@ -337,8 +340,8 @@ module Aspera
         # @param name   [Boolean] Include name
         # @return [Hash{Symbol, String => String}] the modified hash containing:
         #   * `workspace_id` [String] the unique identifier.
-        #   * `workspace_name` [String] (optional) the name, included if +name+ is true.
-        # @note The key type (String or Symbol) depends on the +string+ parameter.
+        #   * `workspace_name` [String] (optional) the name, included if `name` is true.
+        # @note The key type (String or Symbol) depends on the `string` parameter.
         def workspace_id_hash(hash = nil, string: false, name: false)
           info = aoc_api.workspace_info
           hash = {} if hash.nil?
@@ -352,21 +355,6 @@ module Aspera
           return hash
         end
 
-        # Get resource identifier from command line, either directly specifying the `id` or from `name` (percent selector).
-        # @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_values(field, ['name'], type: BadArgument) { 'selector field' }
-            aoc_api.lookup_with_q(resource_class_path, value: value)['id']
-          end
-        end
-
-        # Get resource path from command line
-        def get_resource_path_from_args(resource_class_path)
-          return "#{resource_class_path}/#{get_resource_id_from_args(resource_class_path)}"
-        end
-
         # List all entities, given additional, default and user's queries
         # @param resource_class_path [String]     path to query on API
         # @param fields              [Array, nil] fields to display
@@ -409,87 +397,98 @@ module Aspera
           PACKAGE_RECEIVED_BASE_QUERY.each { |k, v| query[k] = v unless query.key?(k) }
           resolve_dropbox_name_default_ws_id(query)
           # Extract `max` before paging so callers can apply it after post-API filtering
-          max_items = query.delete(RestList::MAX_ITEMS)&.to_i
+          max_items = query.delete(Rest::List::MAX_ITEMS)&.to_i
           return aoc_api.read_with_paging('packages', query.compact), max_items
         end
 
-        FILES_COMMANDS = (Node::COMMANDS_GEN4 + %i[transfer]).freeze
-
-        # Execute a node gen4 command starting at given node and file IDs.
-        # Arguments already resolved by the DSL (e.g. path:) are forwarded via +resolved_args+
-        # and injected into the dispatch context so node.rb does not re-consume them from the CLI.
-        # @param command_repo       [Symbol] Command to execute (from Node::COMMANDS_GEN4 or :transfer)
-        # @param node_id            [String] Node identifier
-        # @param file_id            [String, nil] Root file id; if nil, the AK root file id is used
-        # @param scope              [String, nil] node scope (Node::Scope::USER/ADMIN), or nil (requires secret)
-        # @param transfer_direction [Symbol, nil] :push or :pull (only for command_repo == :transfer)
-        # @param transfer_source    [String, nil] source folder  (only for command_repo == :transfer)
-        # @param resolved_args      [Hash] already-resolved CLI arguments (e.g. path:) forwarded to dispatch
-        def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil, transfer_direction: nil, transfer_source: nil, **resolved_args)
-          top_node_api = aoc_api.node_api_from(
+        # Arguments of the node-to-node `transfer` command (files, admin node do, shared folder node)
+        TRANSFER_ARGS = [{name: :direction, allowed: %i[push pull]}, {name: :source_folder}].freeze
+        # Mount of the Node plugin Gen4 commands (`node access_keys do <id> ...`), instance: set per mount point
+        NODE_GEN4_MOUNT = {plugin: Node, at: %i[access_keys do]}.freeze
+        # Package identifier argument, `%name:` selector (lookup method shared with `admin package`)
+        PACKAGE_ID_ARG = {name: :package_id, type: :identifier, lookup: :lookup_aoc_package_id}.freeze
+        # Resource of analytics events (`admin analytics transfers|files`)
+        EVENT_RESOURCE_TYPE_ARG = {name: :event_resource_type, allowed: %i[organizations users nodes]}.freeze
+        EVENT_RESOURCE_ID_ARG = {name: :event_resource_id, description: 'Resource identifier, empty for the one of the current user'}.freeze
+        private_constant :TRANSFER_ARGS, :NODE_GEN4_MOUNT, :PACKAGE_ID_ARG, :EVENT_RESOURCE_TYPE_ARG, :EVENT_RESOURCE_ID_ARG
+
+        # Node API on a Gen4 node, and its root file id.
+        # @param node_id [String]      Node identifier
+        # @param file_id [String, nil] Root file id; if nil, the access key root file id is used
+        # @param scope   [String, nil] node scope (Api::Node::Scope::USER/ADMIN), or nil (requires secret)
+        # @return [Array(Api::Node, String)]
+        def nodegen4_root(node_id, file_id: nil, scope: nil)
+          node_api = aoc_api.node_api_from(
             node_id:        node_id,
             scope:          scope,
             **workspace_id_hash(name: true)
           )
-          file_id = top_node_api.read("access_keys/#{top_node_api.app_info.node_info['access_key']}")['root_file_id'] if file_id.nil?
-          node_plugin = Node.new(context: context, api: top_node_api)
-          case command_repo
-          when *Node::COMMANDS_GEN4
-            # For permission: the handler consumes the path first then re-dispatches to sub-commands.
-            # Calling dispatch_from_registry with skip_setup would bypass path consumption and fail.
-            return node_plugin.send(:"action_access_keys_do_#{command_repo}", do_root_file_id: file_id, **resolved_args) if command_repo.eql?(:permission)
-            return node_plugin.dispatch_from_registry([:access_keys, :do, command_repo], {do_root_file_id: file_id, **resolved_args}, skip_setup: true)
-          when :transfer
-            # client side is agent
-            # server side is transfer server
-            # in same workspace
-            push_pull = transfer_direction
-            source_folder = transfer_source
-            case push_pull
-            when :push
-              client_direction = Transfer::Spec::DIRECTION_SEND
-              client_folder = source_folder
-              server_folder = transfer.destination_folder(client_direction)
-            when :pull
-              client_direction = Transfer::Spec::DIRECTION_RECEIVE
-              client_folder = transfer.destination_folder(client_direction)
-              server_folder = source_folder
-            else Aspera.error_unreachable_line
-            end
-            client_apifid = top_node_api.resolve_api_fid(file_id, client_folder)
-            server_apifid = top_node_api.resolve_api_fid(file_id, server_folder)
-            # force node as transfer agent
-            transfer.agent_instance = Agent::Node.new(
-              url:      client_apifid.node_api.base_url,
-              username: client_apifid.node_api.app_info.node_info['access_key'],
-              password: client_apifid.node_api.oauth.authorization,
-              root_id:  client_apifid.file_id
-            )
-            # additional node to node TS info
-            add_ts = {
-              'remote_access_key'   => server_apifid.node_api.app_info.node_info['access_key'],
-              'destination_root_id' => server_apifid.file_id,
-              'source_root_id'      => client_apifid.file_id
-            }
-            return Runner.result_transfer(transfer.start(server_apifid.node_api.transfer_spec_gen4(
-              server_apifid.file_id,
-              client_direction,
-              add_ts
-            )))
-          else Aspera.error_unexpected_value(command_repo) { 'command' }
-          end
-          Aspera.error_unreachable_line
+          file_id = node_api.read("access_keys/#{node_api.app_info.node_info['access_key']}")['root_file_id'] if file_id.nil?
+          [node_api, file_id]
+        end
+
+        # Node plugin for Gen4 commands on a node, with the seed ctx of its `access_keys do` sub-tree.
+        # Used as `instance:` of mounts of NODE_GEN4_MOUNT.
+        # @return [Array(Node, Hash)]
+        def nodegen4_plugin(node_id, file_id: nil, scope: nil)
+          node_api, file_id = nodegen4_root(node_id, file_id: file_id, scope: scope)
+          [Node.new(context: context, api: node_api), {do_root_file_id: file_id}]
+        end
+
+        # Node-to-node transfer: client side is agent, server side is transfer server, in same workspace.
+        # @param direction     [Symbol] :push or :pull
+        # @param source_folder [String] source folder
+        # @return [Result]
+        def nodegen4_transfer(node_id, direction:, source_folder:, file_id: nil, scope: nil)
+          top_node_api, file_id = nodegen4_root(node_id, file_id: file_id, scope: scope)
+          case direction
+          when :push
+            client_direction = Transfer::Spec::DIRECTION_SEND
+            client_folder = source_folder
+            server_folder = transfer.destination_folder(client_direction)
+          when :pull
+            client_direction = Transfer::Spec::DIRECTION_RECEIVE
+            client_folder = transfer.destination_folder(client_direction)
+            server_folder = source_folder
+          else Aspera.error_unexpected_value(direction) { 'direction' }
+          end
+          client_apifid = top_node_api.resolve_api_fid(file_id, client_folder)
+          server_apifid = top_node_api.resolve_api_fid(file_id, server_folder)
+          # force node as transfer agent
+          transfer.agent_instance = Agent::Node.new(
+            url:      client_apifid.node_api.base_url,
+            username: client_apifid.node_api.app_info.node_info['access_key'],
+            password: client_apifid.node_api.oauth.authorization,
+            root_id:  client_apifid.file_id
+          )
+          # additional node to node TS info
+          add_ts = {
+            'remote_access_key'   => server_apifid.node_api.app_info.node_info['access_key'],
+            'destination_root_id' => server_apifid.file_id,
+            'source_root_id'      => client_apifid.file_id
+          }
+          Runner.result_transfer(transfer.start(server_apifid.node_api.transfer_spec_gen4(
+            server_apifid.file_id,
+            client_direction,
+            add_ts
+          )))
         end
 
         # Execute an action on admin resources
         # @param resource_type [Symbol] One of ADMIN_OBJECTS
         # Per-resource configuration for admin CRUD resources.
-        # Keys: path, list_fields, id_result, require_ws_id, create_schema, extra_ops, singleton, op_setup
+        # Keys: path, list_fields, id_result, require_ws_id, create_schema, extra_ops, singleton, op_setup, op_mount, op_descriptions
         # 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).
+        # op_mount: Hash of op => mount: of that op's node.
+        # op_descriptions: Hash of op => description, for ops other than standard ones.
         ADMIN_OBJECT_CONFIG = {
-          client:                    {extra_ops: %i[set_pub_key], extra_op_args: {set_pub_key: [{name: :private_key_pem, type: String}]}},
+          client:                    {
+            extra_ops:       %i[set_pub_key],
+            extra_op_args:   {set_pub_key: [{name: :private_key_pem}]},
+            op_descriptions: {set_pub_key: 'Set public key of client from a private key'}
+          },
           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},
@@ -500,15 +499,30 @@ module Aspera
           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 update_status], extra_op_args: {bearer_token: [{name: :scope, mandatory: false, default: nil}]}},
+          node:                      {
+            list_fields:     %w[id name host access_key],
+            extra_ops:       %i[do bearer_token update_status],
+            extra_op_args:   {bearer_token: [{name: :scope, mandatory: false, default: nil}]},
+            op_mount:        {do: NODE_GEN4_MOUNT.merge(instance: :admin_node_do_plugin)},
+            op_descriptions: {do: 'Execute command on node', bearer_token: 'Generate bearer token for node', update_status: 'Ask AoC to scan node and update its status'}
+          },
           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},
+          self:                      {singleton: true, op_descriptions: {show: 'Show current user'}},
           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}},
+          user:                      {
+            list_fields:     %w[id name email],
+            extra_ops:       %i[preferences notifications],
+            op_setup:        {preferences: :setup_admin_user_instance, notifications: :setup_admin_user_instance},
+            op_descriptions: {preferences: 'Manage user preferences', notifications: 'Manage user notification preferences'}
+          },
+          workspace:                 {
+            extra_ops:       %i[shared_folder dropbox],
+            op_setup:        {shared_folder: :setup_admin_workspace_shared_folder, dropbox: :setup_admin_workspace_dropbox},
+            op_descriptions: {shared_folder: 'Manage shared folders of workspace', dropbox: 'Manage shared inboxes of workspace'}
+          },
           workspace_membership:      {list_fields: %w[id workspace_id member_type member_id]}
         }.freeze
         private_constant :ADMIN_OBJECT_CONFIG
@@ -524,14 +538,14 @@ module Aspera
 
         # Build analytics REST API (shared by action_admin_analytics_*)
         def build_analytics_api
-          Rest.new(**aoc_api.params.deep_merge({
+          Rest::Client.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
 
         # Compute short-link purposes from shared_data keys and link_type.
-        # @param shared_data [Hash] :dropbox_id+:name or :file_id+:node_id
+        # @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)
@@ -591,35 +605,39 @@ module Aspera
         command :reminder, description: 'Send reminder email with list of orgs'
         command(
           :servers, description: 'List AoC servers (no auth)',
-          action: lambda do
+          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
         )
-        command :bearer_token,      description: 'Display bearer token',
-          action: -> { Result::Text.new(aoc_api.oauth.authorization) }
+        command :bearer_token,      description: 'Show bearer token',
+          action: ->(**) { Result::Text.new(aoc_api.oauth.authorization) }
         command :organization,      description: 'Show organization info',
-          action: -> { Result::SingleObject.new(aoc_api.read('organization')) }
+          action: ->(**) { Result::SingleObject.new(aoc_api.read('organization')) }
         command :tier_restrictions, description: 'Show tier restrictions',
-          action: -> { Result::SingleObject.new(aoc_api.read('tier_restrictions')) }
-        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
+          action: ->(**) { Result::SingleObject.new(aoc_api.read('tier_restrictions')) }
+        command :user,              description: 'Manage current user'
+        # Node Gen4 read-only commands on packages: `packages <command> <package_id> ...`
+        command :packages,          description: 'Manage packages', setup: :setup_workspace_display,
+          mount: NODE_GEN4_MOUNT.merge(instance: :package_node_plugin, only: Node::NODE4_READ_ACTIONS, arguments: [PACKAGE_ID_ARG])
+        command :files,             description: 'Manage files (workspace-aware)', setup: :setup_workspace_display,
+          mount: NODE_GEN4_MOUNT.merge(instance: :files_node_plugin)
+        command :admin, description: 'Administer AoC', setup: :setup_admin_scope
         commands_under :admin do
           command :bearer_token,   description: 'Show admin bearer token',
-            action: -> { Result::Text.new(aoc_api.oauth.authorization) }
+            action: ->(**) { Result::Text.new(aoc_api.oauth.authorization) }
           command :application,    description: 'Manage applications'
           command :ats, description: 'Manage ATS (Aspera Transfer Service)',
-            delegate_instance: :build_ats_plugin, delegates_to: []
+            mount: {plugin: Ats, instance: :build_ats_plugin}
           command :usage_reports,  description: 'List usage reports',
-            action: -> { result_list('usage_reports', base_query: workspace_id_hash) }
+            action: ->(**) { result_list('usage_reports', base_query: workspace_id_hash) }
           command :auth_providers, description: 'Manage auth providers'
           command :subscription,   description: 'Show subscription info'
           command :analytics,      description: 'Query analytics'
           ADMIN_OBJECTS.each do |res|
             cfg            = ADMIN_OBJECT_CONFIG.fetch(res, {})
             op_setup       = cfg[:op_setup] || {}
+            op_mount       = cfg[:op_mount] || {}
             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"}]
@@ -630,18 +648,19 @@ module Aspera
             else
               Operations::ALL + (cfg[:extra_ops] || [])
             end
-            command res, description: "Manage #{res.to_s.tr('_', ' ')}"
+            command res, description: "Manage #{entity_noun(res, singular: false)}"
             commands_under res do
               ops.each do |op|
                 extra_setup = op_setup[op]
                 base_attrs = extra_setup ? {setup: extra_setup} : {}
+                base_attrs[:mount] = op_mount[op] if op_mount.key?(op)
                 extra_arg_list =
                   if !is_singleton && op.eql?(:create)
                     c = aoc_res_cfg(res)
-                    [{name: :data, type: Hash, bulk: true, schema: c[:schema]}]
+                    [{name: res, 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]}]
+                    [{name: res, type: Hash, schema: c[:schema]}]
                   elsif extra_op_args.key?(op)
                     extra_op_args[op]
                   else
@@ -655,62 +674,71 @@ module Aspera
                   c = aoc_res_cfg(res)
                   merged = merged.merge(query_schema: Schema::Registry.query_params(c[:query_component], c[:path]))
                 end
-                command op, description: op.to_s.tr('_', ' ').capitalize, **merged
+                description = cfg.dig(:op_descriptions, op) ||
+                  (Operations::ALL.include?(op) ? operation_description(op, entity_noun(res, singular: false)) : op.to_s.tr('_', ' ').capitalize)
+                command op, description: description, **merged
               end
             end
           end
         end
         # admin > workspace > shared_folder sub-tree
         commands_under %i[admin workspace shared_folder] do
-          command :list,   description: 'List shared folders'
+          command :list,   description: 'List shared folders',
+            action: ->(shared_folders:, **) { Result::ObjectList.new(shared_folders, fields: %w[id node_name node_id file_id file.path tags.aspera.files.workspace.share_as]) }
           command :node,   description: 'Execute node command on shared folder',
-            arguments: [{name: :sf_id, type: :identifier}],
-            setup: :setup_admin_workspace_shared_folder_node
+            arguments: [{name: :shared_folder_id, type: :identifier}],
+            setup: :setup_admin_workspace_shared_folder_node,
+            mount: NODE_GEN4_MOUNT.merge(instance: :admin_workspace_shared_folder_node_plugin)
           command :member, description: 'Show folder members',
-            arguments: [{name: :sf_id, type: :identifier}],
+            arguments: [{name: :shared_folder_id, type: :identifier}],
             setup: :setup_admin_workspace_shared_folder_member
         end
-        # admin > workspace > shared_folder > node sub-tree (Gen4 commands)
+        # admin > workspace > shared_folder > node: Gen4 commands are mounted, plus node-to-node transfer
         commands_under %i[admin workspace shared_folder node] do
-          command :transfer,   description: 'Transfer files (node-to-node)'
-          command :permission, description: 'Manage permissions'
-          command :sync,       description: 'Synchronize folders'
-          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
-            command cmd, **spec
-          end
+          command :transfer, description: 'Transfer files (node-to-node)', arguments: TRANSFER_ARGS,
+            action: ->(sf_item:, direction:, source_folder:, **) { nodegen4_transfer(sf_item['node_id'], file_id: sf_item['file_id'], scope: Api::Node::Scope::ADMIN, direction: direction, source_folder: source_folder) }
         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'
+          command(
+            :list, description: 'List dropboxes in workspace',
+            action: lambda do |ws_res_id:, **|
+              query = query_read_delete(default: {}, schema: Schema::Registry.query_params(Schema::Registry::AOC, 'dropboxes'))
+              Result::ObjectList.new(aoc_api.read('dropboxes', query.merge({'workspace_id' => ws_res_id})), fields: %w[id name description])
+            end
+          )
         end
-        # admin > node > do sub-tree (Gen4 commands)
+        # admin > node > do: Gen4 commands are mounted (op_mount), plus node-to-node transfer
         commands_under %i[admin node do] do
-          command :transfer,   description: 'Transfer files (node-to-node)'
-          command :permission, description: 'Manage permissions'
-          command :sync,       description: 'Synchronize folders'
-          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
-            command cmd, **spec
-          end
+          command :transfer, description: 'Transfer files (node-to-node)', arguments: TRANSFER_ARGS,
+            action: ->(node_id:, direction:, source_folder:, **) { nodegen4_transfer(node_id, scope: Api::Node::Scope::ADMIN, direction: direction, source_folder: source_folder) }
         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}]
+          commands_under [:admin, :user, pref] do
+            command :show,   description: "Show user #{pref}"
+            command :modify, description: "Modify user #{pref}",
+              arguments: [{name: pref, 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 }
+            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',
+          command(
+            :account, description: 'Show subscription account',
+            action: lambda do |**|
+              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
+          )
+          command :usage, description: 'Show subscription usage',
             arguments: [
               {name: :aggregate,   mandatory: false, default: :ALL, allowed: %i[ALL MONTHLY]},
               {name: :start_date,  mandatory: false, default: nil},
@@ -718,23 +746,29 @@ module Aspera
             ]
         end
         commands_under %i[admin analytics] do
-          command :application_events, description: 'List application events'
+          command(
+            :application_events, description: 'List application events',
+            action: lambda do |**|
+              events = build_analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/application_events")['application_events']
+              Result::ObjectList.new(events)
+            end
+          )
           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}
+              EVENT_RESOURCE_TYPE_ARG,
+              EVENT_RESOURCE_ID_ARG.merge(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}
+              EVENT_RESOURCE_TYPE_ARG,
+              EVENT_RESOURCE_ID_ARG,
+              {name: :event_uuid, type: :identifier}
             ]
         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')) }
+            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'
@@ -744,15 +778,15 @@ module Aspera
         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"
+            command app_type, description: "Manage settings of #{app_type} app"
             commands_under app_type do
               command :show, description: "Show #{app_type} settings",
-                action: -> { Result::SingleObject.new(aoc_api.read("/apps/#{app_type}/settings")) }
+                action: ->(**) { Result::SingleObject.new(aoc_api.read("/apps/#{app_type}/settings")) }
               command(
                 :modify, description: "Modify #{app_type} settings",
-                arguments: [{name: :properties, type: Hash}],
-                action: lambda do |properties:, **|
-                  aoc_api.update("/apps/#{app_type}/settings", properties)
+                arguments: [{name: :settings, type: Hash}],
+                action: lambda do |settings:, **|
+                  aoc_api.update("/apps/#{app_type}/settings", settings)
                   Result::Status.new('modified')
                 end
               )
@@ -760,57 +794,63 @@ module Aspera
           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)
+          command :list, description: 'List app instances'
           APP_TYPES.each do |app_type|
-            command app_type, description: "Show or modify a #{app_type} instance"
+            command app_type, description: "Manage #{app_type} app instance"
             commands_under app_type do
-              command :show,   description: "Show a #{app_type} instance",
-                arguments: [{name: :"#{app_type}_id", type: :identifier}]
-              command :modify, description: "Modify a #{app_type} instance",
-                arguments: [{name: :"#{app_type}_id", type: :identifier}, {name: :properties, type: Hash}]
+              command :show,   description: "Show #{app_type} instance",
+                arguments: [{name: :instance_id, type: :identifier}]
+              command :modify, description: "Modify #{app_type} instance",
+                arguments: [{name: :instance_id, type: :identifier}, {name: :instance, 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: :membership_id, type: :identifier}]
-          command :delete, description: 'Delete an app membership', arguments: [{name: :membership_id, type: :identifier}]
+          command :list, description: 'List app memberships', action: ->(**) { result_list('apps/app_memberships') }
+          command :show, description: 'Show an app membership', arguments: [{name: :membership_id, type: :identifier}],
+            action: ->(membership_id:, **) { Result::SingleObject.new(aoc_api.read("apps/app_memberships/#{membership_id}", query_read_delete)) }
+          command(
+            :delete, description: 'Delete an app membership', arguments: [{name: :membership_id, type: :identifier}],
+            action: lambda do |membership_id:, **|
+              aoc_api.delete("apps/app_memberships/#{membership_id}")
+              Result::Status.new('deleted')
+            end
+          )
           command :create, description: 'Create an app membership', arguments: [{name: :membership, type: Hash}]
         end
-        command :automation,        description: 'Automation commands (BETA)', setup: :setup_automation_api
+        command :automation,        description: 'Manage automation (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
-          commands_under :workspaces, description: "User's workspaces" do
-            command :list,    description: 'List workspaces', action: -> { result_list('workspaces', fields: %w[id name]) }
-            command :current, description: 'Show current workspace', action: -> { Result::SingleObject.new(aoc_api.workspace_info) }
+          commands_under :workspaces, description: "Manage user's workspaces" do
+            command :list,    description: 'List workspaces', action: ->(**) { result_list('workspaces', fields: %w[id name]) }
+            command :current, description: 'Show current workspace', action: ->(**) { Result::SingleObject.new(aoc_api.workspace_info) }
           end
-          # command :profile, description: 'User profile commands'
-          commands_under :profile, description: "Manager user's profile" do
-            command :show, description: 'Show user profile', action: -> { Result::SingleObject.new(aoc_api.current_user_info(exception: true)) }
+          commands_under :profile, description: "Manage user's profile" do
+            command :show, description: 'Show user profile', action: ->(**) { Result::SingleObject.new(aoc_api.current_user_info(exception: true)) }
             command(
               :modify, description: 'Modify user profile',
-              arguments: [{name: :properties, type: Hash}],
-              action: lambda do |properties:, **|
-                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", properties)
+              arguments: [{name: :profile, type: Hash}],
+              action: lambda do |profile:, **|
+                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", profile)
                 Result::Status.new('modified')
               end
             )
           end
-          command :preferences,   description: 'User interaction preferences'
-          command :notifications, description: 'Notification preferences'
+          command :preferences,   description: 'Manage interaction preferences'
+          command :notifications, description: 'Manage notification preferences'
           command :contacts,      description: 'Manage contacts'
           # user > contacts sub-commands (same CRUD as admin > contact)
           commands_under %i[contacts] do
-            Operations::ALL.each { |op| command op, description: op.to_s.capitalize }
+            contact_id = {name: :contact_id, type: :identifier, lookup: :lookup_aoc_contact_id}
+            contact_schema = aoc_res_cfg(:contact)[:schema]
+            command :list,   description: operation_description(:list, 'contact')
+            command :show,   description: operation_description(:show, 'contact'), arguments: [contact_id]
+            command :create, description: operation_description(:create, 'contact'), arguments: [{name: :contact, type: Hash, bulk: true, schema: contact_schema}]
+            command :modify, description: operation_description(:modify, 'contact'), arguments: [contact_id, {name: :contact, type: Hash, schema: contact_schema}]
+            command :delete, description: operation_description(:delete, 'contact'), arguments: [contact_id]
           end
           command :settings, description: 'Manage client settings'
           commands_under %i[settings] do
@@ -821,17 +861,17 @@ module Aspera
         commands_under %i[user preferences] do
           command(
             :show, description: 'Show user preferences',
-            action: lambda do
+            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:, **|
+            arguments: [{name: :preferences, type: Hash}],
+            action: lambda do |preferences:, **|
               user_id = aoc_api.current_user_info(exception: true)['id']
-              aoc_api.update("users/#{user_id}/user_interaction_preferences", properties)
+              aoc_api.update("users/#{user_id}/user_interaction_preferences", preferences)
               Result::Status.new('modified')
             end
           )
@@ -840,100 +880,146 @@ module Aspera
         commands_under %i[user notifications] do
           command(
             :show, description: 'Show notification preferences',
-            action: lambda do
+            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:, **|
+            arguments: [{name: :notifications, type: Hash}],
+            action: lambda do |notifications:, **|
               user_id = aoc_api.current_user_info(exception: true)['id']
-              aoc_api.update("users/#{user_id}/notification_preferences", properties)
+              aoc_api.update("users/#{user_id}/notification_preferences", notifications)
               Result::Status.new('modified')
             end
           )
         end
 
         # packages sub-commands — instance commands consume package_id
+        # Not `crud_commands`: `list` has its own query and `once_only` persistency.
         commands_under :packages do
-          command :shared_inboxes, description: 'Shared inbox commands'
+          command :shared_inboxes, description: 'Manage shared inboxes'
           command :send, description: 'Send a package', transfer_paths: :send,
-            arguments: [{name: :data, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::AOC, 'packages.post')}]
+            arguments: [{name: :package, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::AOC, 'packages.post')}]
           command :receive, description: 'Receive packages', aliases: [:recv], transfer_paths: :receive,
-            arguments: [{name: :package_id, type: :identifier}]
+            arguments: [PACKAGE_ID_ARG]
           command :list, description: 'List packages'
           command :show, description: 'Show a package',
-            arguments: [{name: :package_id, type: :identifier}]
+            arguments: [PACKAGE_ID_ARG],
+            action: ->(package_id:, **) { Result::SingleObject.new(aoc_api.read("packages/#{package_id}")) }
           command :delete, description: 'Delete packages',
-            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 :ls,                description: 'List package contents', aliases: [:browse],
-            arguments: [{name: :package_id, type: :identifier}]
-          command :find,              description: 'Find files in package',
-            arguments: [{name: :package_id, type: :identifier}]
+            arguments: [PACKAGE_ID_ARG.merge(bulk: true)]
+          command(
+            :modify, description: 'Modify a package',
+            arguments: [PACKAGE_ID_ARG, {name: :package, type: Hash}],
+            action: lambda do |package:, package_id:, **|
+              aoc_api.update("packages/#{package_id}", package)
+              Result::Status.new('modified')
+            end
+          )
         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 :list,       description: 'List shared inboxes'
           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]}],
+            arguments: [{name: :link_type, allowed: %i[public private]}, {name: :dropbox_id, type: :identifier, lookup: :lookup_aoc_dropbox_id}],
             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: AoC-specific commands + all Gen4 commands from COMMANDS_GEN4_SPEC
+        # files sub-commands: Gen4 commands are mounted, plus AoC-specific commands
         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]}],
+            arguments: [{name: :folder}, {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 :permission, description: 'Manage permissions'
-          command :sync,       description: 'Synchronize folders'
-          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
-            command cmd, **spec
-          end
+          command :transfer, description: 'Transfer files (node-to-node)', arguments: TRANSFER_ARGS,
+            action: ->(direction:, source_folder:, **) { nodegen4_transfer(aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER, direction: direction, source_folder: source_folder) }
         end
         # files > short_link sub-commands
         register_short_link_commands(self, %i[files short_link])
 
         # automation sub-commands
-        commands_under :automation  do
-          commands_under :instances do
-            crud_commands api: :aoc_api, entity: 'workflow_instances', name: 'workflow instance'
-          end
-
+        # Automation API: a workflow has ordered steps (step_order), a step has ordered actions (action_order)
+        AUTOMATION_CRUD = {api: :@automation_api, body_component: Schema::Registry::AUTOMATION}.freeze
+        private_constant :AUTOMATION_CRUD
+        commands_under :automation do
           commands_under :workflows do
-            crud_commands api: :@automation_api, entity: 'workflows'
+            crud_commands(**AUTOMATION_CRUD, entity: 'workflows', items_key: 'workflows', query_component: Schema::Registry::AUTOMATION)
             command :launch, description: 'Launch a workflow',
-              arguments: [{name: :wf_id, type: :identifier}],
-              action: ->(wf_id:, **) { Result::SingleObject.new(@automation_api.create("workflows/#{wf_id}/launch", {})) }
-            commands_under :action, description: 'Add action to workflow (TODO)' do
-              %i[list create show].each do |cmd|
-                command cmd,
-                  description: "#{cmd.capitalize} action (TODO)",
-                  arguments:   [{name: :wf_id, type: :identifier}]
+              arguments: [{name: :workflow_id, type: :identifier}],
+              action: ->(workflow_id:, **) { Result::SingleObject.new(@automation_api.create("workflows/#{workflow_id}/launch", {})) }
+            command :update_state, description: 'Update state of workflow',
+              arguments: [{name: :workflow_id, type: :identifier},
+                          {name: :state, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::AUTOMATION, 'workflows/{id}/update_state.put')}],
+              action: ->(workflow_id:, state:, **) { Result::SingleObject.new(@automation_api.update("workflows/#{workflow_id}/update_state", state)) }
+            command(
+              :cancel_instances, description: 'Cancel all jobs of workflow',
+              arguments: [{name: :workflow_id, type: :identifier}],
+              action: lambda do |workflow_id:, **|
+                @automation_api.update("workflows/#{workflow_id}/cancel_instances", {})
+                Result::Status.new('canceled')
               end
-            end
+            )
+            command(
+              :delete_instances, description: 'Delete all jobs of workflow',
+              arguments: [{name: :workflow_id, type: :identifier}],
+              action: lambda do |workflow_id:, **|
+                @automation_api.delete("workflows/#{workflow_id}/delete_instances")
+                Result::Status.new('deleted')
+              end
+            )
+            command :action, description: 'Manage actions of workflow',
+              arguments: [{name: :workflow_id, type: :identifier}]
+            command :permissions, description: 'Manage permissions of workflow',
+              arguments: [{name: :workflow_id, type: :identifier}]
+          end
+          # workflow_id is resolved by the parent command
+          commands_under %i[workflows action] do
+            command :list,   description: 'List actions of all steps of workflow'
+            command :create, description: 'Add a step with one action at the end of workflow',
+              arguments: [{name: :action, type: Hash, mandatory: false, default: {}, schema: Schema::Registry.req_body(Schema::Registry::AUTOMATION, 'actions.post')}]
+          end
+          commands_under %i[workflows permissions] do
+            # API requires query parameter workflow_id
+            command(
+              :list, description: 'List permissions of workflow',
+              query_schema: Schema::Registry.query_params(Schema::Registry::AUTOMATION, 'workflow_permissions'),
+              action: lambda do |workflow_id:, **|
+                schema = Schema::Registry.query_params(Schema::Registry::AUTOMATION, 'workflow_permissions')
+                query = (query_read_delete(schema: schema) || {}).merge('workflow_id' => workflow_id)
+                Result::ObjectList.new(@automation_api.read('workflow_permissions', query))
+              end
+            )
+            command(
+              :create, description: 'Create a permission on workflow',
+              arguments: [{name: :workflow_permission, type: Hash, bulk: true, schema: Schema::Registry.req_body(Schema::Registry::AUTOMATION, 'workflow_permissions.post')}],
+              action: lambda do |workflow_id:, workflow_permission:, **|
+                bulk_result(workflow_permission, command: :create) do |params|
+                  @automation_api.create('workflow_permissions', params.merge('workflow_id' => workflow_id))
+                end
+              end
+            )
+            crud_commands(**AUTOMATION_CRUD, entity: 'workflow_permissions', name: 'workflow permission', operations: %i[modify delete])
+          end
+          commands_under :instances do
+            crud_commands(
+              **AUTOMATION_CRUD, entity: 'workflow_instances', name: 'workflow instance', operations: %i[list show delete],
+              items_key: 'workflow_instances', query_component: Schema::Registry::AUTOMATION
+            )
+            command :cancel, description: 'Cancel workflow instance',
+              arguments: [{name: :workflow_instance_id, type: :identifier}],
+              action: ->(workflow_instance_id:, **) { Result::SingleObject.new(@automation_api.update("workflow_instances/#{workflow_instance_id}", {'status' => 'canceled'})) }
+          end
+          commands_under :steps do
+            crud_commands(**AUTOMATION_CRUD, entity: 'steps', operations: %i[create show modify delete])
+          end
+          commands_under :actions do
+            crud_commands(**AUTOMATION_CRUD, entity: 'actions', operations: %i[create show modify delete])
           end
         end
 
@@ -954,13 +1040,13 @@ module Aspera
         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/'))
+          @automation_api = Rest::Client.new(**aoc_api.params, base_url: aoc_api.base_url.gsub('/api/', '/automation/'))
           {}
         end
 
         # --- handler methods ---
 
-        def action_reminder
+        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})
@@ -968,8 +1054,8 @@ module Aspera
         end
 
         # packages > send
-        def action_packages_send(data:, **)
-          package_data = data
+        def action_packages_send(package:, **)
+          package_data = package
           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')
@@ -1042,7 +1128,7 @@ module Aspera
         end
 
         # packages > list
-        def action_packages_list
+        def action_packages_list(**)
           result, max_items = list_all_packages_with_query
           skip_ids_persistency = package_persistency
           reject_packages_from_persistency(result[:items], skip_ids_persistency)
@@ -1052,11 +1138,6 @@ module Aspera
           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:, **)
           bulk_result(package_id, command: :delete) do |one_id|
@@ -1065,30 +1146,24 @@ module Aspera
           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 / ls / find
-        # (NODE4_READ_ACTIONS dispatched by full path: action_packages_bearer_token_node, etc.)
-        Node::NODE4_READ_ACTIONS.each do |action|
-          define_action_method([:packages, action]) do |package_id:, **|
-            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
+        # Used as `instance:` of the mount on packages: node of the package contents
+        # @return [Array(Node, Hash)]
+        def package_node_plugin(package_id:, **)
+          package_info = aoc_api.read("packages/#{package_id}")
+          # An id that is not a single path segment (e.g. `/`) reads the list of packages
+          Aspera.assert(package_info.is_a?(Hash), type: Cli::BadArgument) { "invalid package id: #{package_id}" }
+          nodegen4_plugin(package_info['node_id'], file_id: package_info['contents_file_id'], scope: Api::Node::Scope::USER)
         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:, **)
+        def setup_files_short_link(folder:, 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_apifid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder)
           shared_data = {
             node_id: shared_apifid.node_api.app_info.node_info['id'],
             file_id: shared_apifid.file_id
@@ -1104,7 +1179,7 @@ module Aspera
                 'access_levels' => Api::AoC.expand_access_levels(access_levels),
                 'tags'          => {
                   'url_token'        => true,
-                  'folder_name'      => File.basename(folder_dest),
+                  'folder_name'      => File.basename(folder),
                   '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'],
@@ -1135,10 +1210,9 @@ module Aspera
         end
 
         # setup: packages > shared_inboxes > short_link
-        # Reads dropbox_id, consumes link_type argument, computes purposes.
+        # link_type: and dropbox_id: resolved via arguments: on the node, 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')
+        def setup_packages_short_link(link_type:, dropbox_id:, **)
           shared_data = {dropbox_id: dropbox_id, name: ''}
           token_purpose, short_link_purpose = short_link_purposes(shared_data, link_type)
           {
@@ -1167,7 +1241,7 @@ module Aspera
               url_token_data: {data: shared_data, purpose: sl_token_purpose}
             }
           end
-          custom_data = {}
+          custom_data = custom_data.dup
           access_levels = custom_data.delete('access_levels')
           if (pass = custom_data.delete('password'))
             create_payload[:data][:url_token_data][:password] = pass
@@ -1224,7 +1298,7 @@ module Aspera
           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 = {}
+          custom_data = custom_data.dup
           if (pass = custom_data.delete('password'))
             modify_payload[:password_enabled] = true
             modify_payload[:data] = {url_token_data: {password: pass, data: node_file}}
@@ -1241,38 +1315,41 @@ module Aspera
           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 |**ctx|
-            execute_nodegen4_command(action, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER, **ctx)
-          end
+        # files - mount target: Gen4 commands on the user's home folder
+        def files_node_plugin(**)
+          nodegen4_plugin(aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER)
         end
 
         # admin > application > instance > <type> > show|modify
         APP_TYPES.each do |app_type|
           define_action_method([:admin, :application, :instance, app_type, :show]) do |**kwargs|
-            app_id = kwargs[:"#{app_type}_id"]
+            app_id = kwargs[:instance_id]
             Result::SingleObject.new(aoc_api.read("admin/apps_new/#{app_type}/#{app_id}", query_read_delete))
           end
 
-          define_action_method([:admin, :application, :instance, app_type, :modify]) do |properties:, **kwargs|
-            app_id = kwargs[:"#{app_type}_id"]
-            aoc_api.update("admin/apps_new/#{app_type}/#{app_id}", properties)
+          define_action_method([:admin, :application, :instance, app_type, :modify]) do |instance:, **kwargs|
+            app_id = kwargs[:instance_id]
+            aoc_api.update("admin/apps_new/#{app_type}/#{app_id}", instance)
             Result::Status.new('modified')
           end
         end
 
+        def action_admin_application_instance_list(**)
+          result_list(
+            'admin/apps_new',
+            fields:        %w[id app_type available workspace_id],
+            default_query: {workspace_id: aoc_api.workspace_info[:id]}
+          )
+        end
+
+        def action_packages_shared_inboxes_list(**)
+          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
+
         def action_admin_application_membership_create(membership:, **)
           data = membership.dup
           app_type = data.delete('app_type')
@@ -1281,29 +1358,12 @@ module Aspera
           Result::SingleObject.new(aoc_api.create("apps/#{app_type}/app_memberships", data))
         end
 
-        # admin > application > membership > show|delete
-        def action_admin_application_membership_show(membership_id:, **)
-          Result::SingleObject.new(aoc_api.read("apps/app_memberships/#{membership_id}", query_read_delete))
-        end
-
-        def action_admin_application_membership_delete(membership_id:, **)
-          aoc_api.delete("apps/app_memberships/#{membership_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
@@ -1318,21 +1378,20 @@ module Aspera
           Result::SingleObject.new(result['aoc'])
         end
 
-        # admin > analytics > application_events
-        def action_admin_analytics_application_events
-          events = build_analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/application_events")['application_events']
-          Result::ObjectList.new(events)
+        # @return [String] the given resource id, or the one of the current user if empty
+        def analytics_resource_id(event_resource_type, event_resource_id)
+          return event_resource_id unless event_resource_id.to_s.empty?
+          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
         end
 
         # admin > analytics > transfers
         def action_admin_analytics_transfers(event_resource_type:, event_resource_id:, **)
-          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
+          event_resource_id = analytics_resource_id(event_resource_type, event_resource_id)
           filter = query_read_delete(default: {})
           filter['limit'] ||= 100
           if options.get_option(:once_only, mandatory: true)
@@ -1356,13 +1415,7 @@ module Aspera
 
         # admin > analytics > files
         def action_admin_analytics_files(event_resource_type:, event_resource_id:, event_uuid:, **)
-          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?
+          event_resource_id = analytics_resource_id(event_resource_type, event_resource_id)
           filter = query_read_delete(default: {})
           filter['limit'] ||= 100
           events = build_analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers/#{event_uuid}/files", filter)['files']
@@ -1370,7 +1423,7 @@ module Aspera
         end
 
         # Lookup methods for arguments:(:identifier) + lookup: on admin resources.
-        # One method per non-singleton resource; each delegates to get_resource_id_from_args.
+        # One method per non-singleton resource: percent selector searches with `q=<value>`.
         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']
@@ -1379,7 +1432,7 @@ module Aspera
 
         # admin > <res> > list
         ADMIN_OBJECTS.each do |res|
-          define_action_method([:admin, res, :list]) do
+          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
@@ -1396,14 +1449,15 @@ module Aspera
 
         # admin > organization|self > show (singleton)
         %i[organization self].each do |res|
-          define_action_method([:admin, res, :show]) do
+          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:, **|
+          define_action_method([:admin, res, :create]) do |**kwargs|
+            data = kwargs.fetch(res)
             c = aoc_res_cfg(res)
             path = c[:path]
             # Special case: client_registration_token has a different creation URL
@@ -1418,7 +1472,8 @@ module Aspera
 
         # 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:, **kwargs|
+          define_action_method([:admin, res, :modify]) do |**kwargs|
+            data = kwargs.fetch(res)
             res_id = kwargs[:"#{res}_id"]
             c = aoc_res_cfg(res)
             aoc_api.update("#{c[:path]}/#{res_id}", data)
@@ -1448,6 +1503,28 @@ module Aspera
           end
         end
 
+        # automation > workflows > action > list
+        # A workflow has ordered steps (step_order), a step has ordered actions (action_order)
+        def action_automation_workflows_action_list(workflow_id:, **)
+          workflow = @automation_api.read("workflows/#{workflow_id}")
+          actions = Array(workflow['step_order']).flat_map do |step_id|
+            step = @automation_api.read("steps/#{step_id}")
+            Array(step['action_order']).map { |action_id| @automation_api.read("actions/#{action_id}") }
+          end
+          Result::ObjectList.new(actions)
+        end
+
+        # automation > workflows > action > create
+        # Default action type is `manual`
+        def action_automation_workflows_action_create(workflow_id:, action:, **)
+          workflow = @automation_api.read("workflows/#{workflow_id}")
+          step = @automation_api.create('steps', {'workflow_id' => workflow_id})
+          @automation_api.update("workflows/#{workflow_id}", {'step_order' => Array(workflow['step_order']) + [step['id']]})
+          new_action = @automation_api.create('actions', {'type' => 'manual'}.merge(action).merge('step_id' => step['id']))
+          @automation_api.update("steps/#{step['id']}", {'action_order' => [new_action['id']]})
+          Result::SingleObject.new(new_action)
+        end
+
         # admin > client > set_pub_key
         def action_admin_client_set_pub_key(private_key_pem:, client_id:, **)
           c = aoc_res_cfg(:client)
@@ -1457,10 +1534,10 @@ module Aspera
         end
 
         # admin > ats — build and return an Ats plugin instance wired to the AoC ATS API.
-        # Used as delegate_instance: target so --help traverses the Ats registry.
+        # Mount target of `admin ats`.
         # @return [Ats] configured Ats plugin instance
-        def build_ats_plugin
-          ats_api = Rest.new(**aoc_api.params.deep_merge({
+        def build_ats_plugin(**)
+          ats_api = Rest::Client.new(**aoc_api.params.deep_merge({
             base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
             auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
           }))
@@ -1470,11 +1547,9 @@ module Aspera
         # 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 |node_id:, **ctx|
-            execute_nodegen4_command(cmd, node_id, scope: Api::Node::Scope::ADMIN, **ctx)
-          end
+        # admin > node > do - mount target: Gen4 commands on the node, admin scope
+        def admin_node_do_plugin(node_id:, **)
+          nodegen4_plugin(node_id, scope: Api::Node::Scope::ADMIN)
         end
 
         # admin > node > bearer_token
@@ -1494,28 +1569,17 @@ module Aspera
           {ws_res_id: workspace_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(workspace_id:, **)
           resource_instance_path = "#{aoc_res_path(:workspace)}/#{workspace_id}"
-          query = options.get_option(:query) || Api::AoC.workspace_access(workspace_id).merge({'admin' => true})
+          query = query_read_delete(default: Api::AoC.workspace_access(workspace_id).merge({'admin' => true}))
           shared_folders = aoc_api.read_with_paging("#{resource_instance_path}/permissions", query)[:items]
           {ws_res_id: workspace_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) }
+        # admin > workspace > shared_folder > node|member — shared_folder_id: already in ctx via arguments:(:identifier)
+        def resolve_sf_item(shared_folders:, shared_folder_id:, **)
+          sf_item = shared_folders.find { |i| i['id'].eql?(shared_folder_id) }
           Aspera.assert(sf_item, 'shared folder not found')
           {sf_item: sf_item}
         end
@@ -1523,11 +1587,9 @@ module Aspera
         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:, **ctx|
-            execute_nodegen4_command(cmd, sf_item['node_id'], file_id: sf_item['file_id'], scope: Api::Node::Scope::ADMIN, **ctx)
-          end
+        # admin > workspace > shared_folder > node - mount target: Gen4 commands on the shared folder, admin scope
+        def admin_workspace_shared_folder_node_plugin(sf_item:, **)
+          nodegen4_plugin(sf_item['node_id'], file_id: sf_item['file_id'], scope: Api::Node::Scope::ADMIN)
         end
 
         # admin > workspace > shared_folder > member > list
@@ -1561,24 +1623,12 @@ module Aspera
           define_action_method([:admin, :user, pref, :show]) do |user_id:, **|
             Result::SingleObject.new(aoc_api.read("#{aoc_res_path(:user)}/#{user_id}/#{pref_path}"))
           end
-          define_action_method([:admin, :user, pref, :modify]) do |properties:, user_id:, **|
-            aoc_api.update("#{aoc_res_path(:user)}/#{user_id}/#{pref_path}", properties)
+          define_action_method([:admin, :user, pref, :modify]) do |user_id:, **kwargs|
+            aoc_api.update("#{aoc_res_path(:user)}/#{user_id}/#{pref_path}", kwargs.fetch(pref))
             Result::Status.new('modified')
           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