aspera-cli 4.26.2 → 4.27.1

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

@@ -26,7 +26,7 @@ module Aspera
                 login_page = Rest
                   .new(base_url: url, redirect_max: 2)
                   .read('', headers: {'Accept'=>'text/html'})
-                raise 'not Shares' unless login_page.include?('aspera-Shares')
+                Aspera.assert(login_page.include?('aspera-Shares')) { 'not Shares' }
                 if (m = login_page.match(/\(v([0-9a-f\.]+)\)/))
                   version = m[1]
                   if (m = login_page.match(/Patch level ([0-9]+)/))
@@ -91,129 +91,362 @@ module Aspera
 
         def initialize(**_)
           super
+          @api_shares_admin = nil
         end
 
         SAML_IMPORT_MANDATORY = %w[id name_id].freeze
-        SAML_IMPORT_ALLOWED = %w[email given_name surname].concat(SAML_IMPORT_MANDATORY).freeze
+        SAML_IMPORT_ALLOWED = (%w[email given_name surname] + SAML_IMPORT_MANDATORY).freeze
 
-        ACTIONS = %i[health info files admin].freeze
         # common to users and groups
         USR_GRP_SETTINGS = %i[transfer_settings app_authorizations share_permissions].freeze
+        # share_permissions is read-only (Rails only exposes index+show)
+        SHARE_PERMISSIONS_OPS = %i[list show].freeze
+        # group users: Rails only exposes index+show+update+destroy (no create)
+        GROUP_USERS_OPS = (Operations::ALL - %i[create]).freeze
 
-        def execute_action
-          command = options.get_next_command(ACTIONS, aliases: {repository: :files})
-          case command
-          when :health
-            nagios = Nagios.new
-            shares_url = options.get_option(:url, mandatory: true)
-            health = self.class.health_check(shares_url)
-            nagios.add_ok('version', health[:version]) if health[:version].is_a?(String)
-            if health[:ping].is_a?(String)
-              nagios.add_ok('ping', health[:ping])
-            else
-              nagios.add_critical('ping', health[:ping].to_s)
+        # --- DSL ---
+
+        command :health,   description: 'Check Shares health'
+        command :info,     description: 'Show server information', action: -> { Result::SingleObject.new(basic_auth_api(NODE_API_PATH).read('info', headers: {'Content-Type'=>'application/json'})) }
+        command :files,    description: 'Browse and transfer files on Shares', aliases: [:repository], setup: :setup_shares_node
+        command :admin,    description: 'Administer Shares', setup: :setup_admin
+
+        commands_under :admin do
+          commands_under :node do
+            crud_commands entity: 'data/nodes', api: :@api_shares_admin
+          end
+          commands_under :ldap_config, description: 'LDAP configuration' do
+            crud_commands entity: 'data/ldap_configs', api: :@api_shares_admin
+          end
+          command :share,             description: 'Manage shares'
+          command :transfer_settings, description: 'Manage transfer settings'
+          command :user,              description: 'Manage users'
+          command :group,             description: 'Manage groups'
+          commands_under :smtp_server, description: 'SMTP server' do
+            crud_commands entity: 'data/smtp_server',
+              api: :@api_shares_admin,
+              is_singleton: true,
+              body_component: Schema::Registry::SHARES,
+              operations: %i[show create modify]
+          end
+          # user / group: sub-commands per location, generated for both entity types
+          %i[user group].each do |entity_type|
+            commands_under entity_type do
+              command :all,   description: "#{entity_type.capitalize}s from all sources"
+              command :local, description: "Local #{entity_type}s"
+              command :ldap,  description: "LDAP #{entity_type}s"
+              command :saml,  description: "SAML #{entity_type}s"
+
+              # all: list/show/delete only (no create, no modify — users/groups/:all has no update route)
+              lookup_method_all = :"lookup_shares_#{entity_type}_all_id"
+              commands_under :all do
+                (Operations::ALL - %i[create modify]).each do |op|
+                  id_args = Operations::GLOBAL.include?(op) ? {} : {arguments: [{name: :"#{entity_type}_id", type: :identifier, lookup: lookup_method_all}]}
+                  command op, description: "#{op.capitalize} #{entity_type}s", **id_args
+                end
+                USR_GRP_SETTINGS.each do |setting|
+                  # share_permissions: Rails only exposes index+show (read-only)
+                  setting_ops = setting.eql?(:share_permissions) ? SHARE_PERMISSIONS_OPS : %i[show modify]
+                  command setting,
+                    description: "Manage #{setting} for a #{entity_type}",
+                    arguments: [{name: :"#{entity_type}_id", type: :identifier, lookup: lookup_method_all}]
+                  commands_under setting do
+                    setting_ops.each do |op|
+                      # share_permissions > show needs a permission identifier (list does not)
+                      perm_id_arg = if setting.eql?(:share_permissions) && op.eql?(:show)
+                        [{name: :permission_id, type: :identifier, lookup: :lookup_share_id}]
+                      else
+                        []
+                      end
+                      command op,
+                        description: "#{op.capitalize} #{setting} for a #{entity_type}",
+                        arguments: perm_id_arg.empty? ? nil : perm_id_arg
+                    end
+                  end
+                end
+                if entity_type.eql?(:group)
+                  command :users,
+                    description: 'Manage users of a group',
+                    arguments: [{name: :group_id, type: :identifier, lookup: :lookup_shares_group_all_id}]
+                  commands_under :users do
+                    GROUP_USERS_OPS.each do |op|
+                      command op, description: "#{op.capitalize} users of a group"
+                    end
+                  end
+                end
+              end
+
+              # local: full CRUD only — no nested settings (Rails does not nest transfer_settings/app_authorizations/share_permissions under local_users/local_groups)
+              commands_under :local do
+                lookup_method_local = :"lookup_shares_#{entity_type}_local_id"
+                Operations::ALL.each do |op|
+                  id_args = Operations::GLOBAL.include?(op) ? {} : {arguments: [{name: :"#{entity_type}_id", type: :identifier, lookup: lookup_method_local}]}
+                  command op, description: "#{op.capitalize} #{entity_type}s", **id_args
+                end
+                if entity_type.eql?(:group)
+                  command :users,
+                    description: 'Manage users of a group',
+                    arguments: [{name: :group_id, type: :identifier, lookup: :lookup_shares_group_local_id}]
+                  commands_under :users do
+                    GROUP_USERS_OPS.each do |op|
+                      command op, description: "#{op.capitalize} users of a group"
+                    end
+                  end
+                end
+              end
+
+              # ldap: add only
+              commands_under :ldap do
+                command :add, description: "Add a LDAP #{entity_type}",
+                  arguments: [{name: :entity_name, type: String, bulk: true}]
+              end
+
+              # saml: import only
+              commands_under :saml do
+                command :import, description: "Import a SAML #{entity_type}",
+                  arguments: [{name: :entity_parameters, type: Hash, bulk: true}]
+              end
+            end
+          end
+        end
+
+        ENTITY_LOCATIONS = %i[all local].freeze
+        SHARE_DISPLAY_FIELDS = %w[id name node_id directory percent_free].freeze
+        private_constant :ENTITY_LOCATIONS, :SHARE_DISPLAY_FIELDS
+
+        # Lookup methods used by arguments:(:identifier, lookup:) on setting nodes.
+        # One method per entity_type/location combination; each returns the entity id.
+        %i[user group].each do |entity_type|
+          ENTITY_LOCATIONS.each do |location|
+            lookup_method = :"lookup_shares_#{entity_type}_#{location}_id"
+            define_method(lookup_method) do |field, value, **|
+              path = admin_entity_path(entity_type, location)
+              RestList.lookup_entity_generic(entity: entity_type, field: field, value: value) { @api_shares_admin.read(path) }['id']
             end
-            if health[:api].is_a?(String)
-              nagios.add_ok('API', health[:api])
-            else
-              nagios.add_critical('API', health[:api].to_s)
+            private lookup_method
+          end
+        end
+
+        commands_under %i[admin share] do
+          crud_commands entity:         'data/shares',
+            api:            :@api_shares_admin,
+            display_fields: SHARE_DISPLAY_FIELDS,
+            body_component: Schema::Registry::SHARES,
+            lookup:         :lookup_share_id
+          command :user_permissions,
+            description: 'Manage user permissions on a share',
+            arguments: [{name: :share_id, type: :identifier, lookup: :lookup_share_id}]
+          command :group_permissions,
+            description: 'Manage group permissions on a share',
+            arguments: [{name: :share_id, type: :identifier, lookup: :lookup_share_id}]
+        end
+
+        # share user_permissions and group_permissions: Rails only exposes index+show (read-only)
+        %i[user_permissions group_permissions].each do |perm_type|
+          commands_under [:admin, :share, perm_type] do
+            SHARE_PERMISSIONS_OPS.each do |op|
+              command op, description: "#{op.capitalize} #{perm_type}"
             end
-            Result::ObjectList.new(nagios.status_list)
-          when :info
-            return Result::SingleObject.new(basic_auth_api(NODE_API_PATH).read('info', headers: {'Content-Type'=>'application/json'}))
-          when :files
-            api_shares_node = basic_auth_api(NODE_API_PATH)
-            repo_command = options.get_next_command(Node::COMMANDS_SHARES)
-            return Node
-                .new(context: context, api: api_shares_node)
-                .execute_action(repo_command)
-          when :admin
-            api_shares_admin = basic_auth_api(ADMIN_API_PATH)
-            admin_command = options.get_next_command(%i[node share transfer_settings user group].freeze)
-            lookup_share = ->(field, value){RestList.lookup_entity_generic(entity: 'share', field: field, value: value){api_shares_admin.read('data/shares')}['id']}
-            case admin_command
-            when :node
-              return entity_execute(api: api_shares_admin, entity: 'data/nodes')
-            when :share
-              share_command = options.get_next_command(%i[user_permissions group_permissions].concat(Operations::ALL))
-              case share_command
-              when *Operations::ALL
-                return entity_execute(
-                  api:            api_shares_admin,
-                  entity:         'data/shares',
-                  command:        share_command,
-                  display_fields: %w[id name node_id directory percent_free],
-                  &lookup_share
-                )
-              when :user_permissions, :group_permissions
-                share_id = options.instance_identifier(&lookup_share)
-                return entity_execute(api: api_shares_admin, entity: "data/shares/#{share_id}/#{share_command}")
-              end
-            when :transfer_settings
-              xfer_settings_command = options.get_next_command(%i[show modify])
-              return entity_execute(
-                api: api_shares_admin,
-                entity: 'data/transfer_settings',
-                command: xfer_settings_command,
-                is_singleton: true
-              )
-            when :user, :group
-              entity_type = admin_command
-              entities_location = options.get_next_command(%i[all local ldap saml])
-              entities_prefix = entities_location.eql?(:all) ? '' : "#{entities_location}_"
-              entities_path = "data/#{entities_prefix}#{entity_type}s"
-              entity_commands = nil
-              case entities_location
-              when :all
-                entity_commands = %i[list show delete]
-                entity_commands.concat(USR_GRP_SETTINGS)
-                entity_commands.push(:users) if entity_type.eql?(:group)
-                entity_commands.freeze
-              when :local
-                entity_commands = %i[list show delete create modify]
-                entity_commands.push(:users) if entity_type.eql?(:group)
-                entity_commands.freeze
-              when :ldap
-                entity_commands = %i[add].freeze
-              when :saml
-                entity_commands = %i[import].freeze
+          end
+        end
+
+        commands_under %i[admin transfer_settings] do
+          crud_commands entity: 'data/transfer_settings',
+            api: :@api_shares_admin,
+            is_singleton: true,
+            operations: %i[show modify]
+        end
+
+        # --- setup ---
+
+        # Build the Shares node API plugin and inject into ctx.
+        # @return [Hash] context hash containing :shares_node_plugin
+        def setup_shares_node(**)
+          api_shares_node = basic_auth_api(NODE_API_PATH)
+          {shares_node_plugin: Node.new(context: context, api: api_shares_node)}
+        end
+
+        # Build the admin REST API and store in ivar.
+        # @return [Hash] empty ctx (state stored in @api_shares_admin)
+        def setup_admin(**)
+          @api_shares_admin = basic_auth_api(ADMIN_API_PATH)
+          {}
+        end
+
+        # Lookup a share id by field/value using the admin API.
+        def lookup_share_id(field, value, **)
+          RestList.lookup_entity_generic(entity: 'share', field: field, value: value) { @api_shares_admin.read('data/shares') }['id']
+        end
+
+        # --- health ---
+
+        def action_health
+          nagios = Nagios.new
+          shares_url = options.get_option(:url, mandatory: true)
+          health = self.class.health_check(shares_url)
+          nagios.add_ok('version', health[:version]) if health[:version].is_a?(String)
+          if health[:ping].is_a?(String)
+            nagios.add_ok('ping', health[:ping])
+          else
+            nagios.add_critical('ping', health[:ping].to_s)
+          end
+          if health[:api].is_a?(String)
+            nagios.add_ok('API', health[:api])
+          else
+            nagios.add_critical('API', health[:api].to_s)
+          end
+          Result::ObjectList.new(nagios.status_list)
+        end
+
+        # --- files sub-commands (restricted to COMMANDS_SHARES, delegated to Node) ---
+
+        commands_under :files do
+          Node::COMMANDS_SHARES.each do |cmd|
+            next if cmd.eql?(:sync) # intermediate node with sub-commands, declared separately below
+            spec = Node::COMMANDS_GEN3_SPEC[cmd] || {description: "Node #{cmd} command"}
+            command cmd, **spec
+          end
+          command :sync, description: 'Synchronize folders (Gen3)'
+          commands_under :sync do
+            Sync::Operations::DIRECTIONS.each do |dir|
+              command dir, description: "#{dir.capitalize}-sync (Gen3)", transfer_paths: :send, arguments: SyncActions::PATH_AND_INFO_ARGS
+            end
+            command :admin, description: 'Manage sync database (admin operations)'
+            SyncActions.register_sync_admin_commands(self, :admin)
+          end
+        end
+
+        # One handler per COMMANDS_SHARES command (except :sync which is an intermediate node).
+        Node::COMMANDS_SHARES.reject { |cmd| cmd.eql?(:sync) }.each do |cmd|
+          define_action_method([:files, cmd]) do |shares_node_plugin:, **ctx|
+            shares_node_plugin.dispatch_v3_command(cmd, **ctx)
+          end
+        end
+
+        # Handlers for files > sync > <direction>: delegate to Node's [:sync, dir] leaf.
+        Sync::Operations::DIRECTIONS.each do |dir|
+          define_action_method([:files, :sync, dir]) do |shares_node_plugin:, **ctx|
+            shares_node_plugin.dispatch_from_registry([:sync, dir], ctx, skip_setup: true)
+          end
+        end
+        # Handlers for files > sync > admin > <op>: delegate to Node's [:sync, :admin, op] leaf.
+        SyncActions::ADMIN_COMMANDS.each do |op|
+          define_action_method([:files, :sync, :admin, op]) do |shares_node_plugin:, **ctx|
+            shares_node_plugin.dispatch_from_registry([:sync, :admin, op], ctx, skip_setup: true)
+          end
+        end
+
+        private
+
+        # @return [String] admin API path for the given entity_type and location
+        def admin_entity_path(entity_type, location)
+          prefix = location.eql?(:all) ? '' : "#{location}_"
+          "data/#{prefix}#{entity_type}s"
+        end
+
+        # --- admin > user|group handlers ---
+
+        # Shared handler for list/show/delete/create/modify on user or group.
+        # @param entity_type [Symbol] :user or :group
+        # @param location    [Symbol] :all or :local
+        # @param op          [Symbol] CRUD operation
+        def action_admin_entity_crud(entity_type, location, op)
+          path = admin_entity_path(entity_type, location)
+          lookup = ->(f, v) { RestList.lookup_entity_generic(entity: entity_type, field: f, value: v) { @api_shares_admin.read(path) }['id'] }
+          display_fields = entity_type.eql?(:user) ? %w[id user_id username first_name last_name email] : nil
+          display_fields&.push('directory_user') if entity_type.eql?(:user) && location.eql?(:all)
+          # :all excludes :create; :local has a documented POST+PUT requestBody for both users and groups
+          body_component = location.eql?(:local) ? Schema::Registry::SHARES : nil
+          id = Operations::INSTANCE.include?(op) ? options.instance_identifier(&lookup) : nil
+          send(:"entity_#{op}", api: @api_shares_admin, entity: path, id: id, display_fields: display_fields, body_component: body_component)
+        end
+
+        # Shared handler for USR_GRP_SETTINGS (transfer_settings, app_authorizations, share_permissions)
+        # @param entity_type [Symbol] :user or :group
+        # @param location    [Symbol] :all or :local
+        # @param setting     [Symbol] one of USR_GRP_SETTINGS
+        # @param op          [Symbol] CRUD operation
+        # entity_id: resolved via arguments:(:identifier) on each setting leaf command
+        def action_admin_entity_setting(entity_type, location, setting, op, entity_id:, permission_id: nil, **)
+          path = admin_entity_path(entity_type, location)
+          entity_path = "#{path}/#{entity_id}/#{setting}"
+          is_singleton = !setting.eql?(:share_permissions)
+          id = permission_id || (Operations::INSTANCE.include?(op) && !is_singleton ? options.instance_identifier { |f, v| lookup_share_id(f, v) } : nil)
+          send(:"entity_#{op}", api: @api_shares_admin, entity: entity_path, id: id, is_singleton: is_singleton)
+        end
+
+        # Shared handler for :users (group only)
+        # group_id: resolved by Phase A via arguments:(:identifier) on the :users node
+        def action_admin_entity_users(entity_type, location, op, group_id:, **)
+          path = admin_entity_path(entity_type, location)
+          prefix = location.eql?(:all) ? '' : "#{location}_"
+          id = Operations::INSTANCE.include?(op) ? options.instance_identifier : nil
+          send(:"entity_#{op}", api: @api_shares_admin, entity: "#{path}/#{group_id}/#{prefix}users", id: id)
+        end
+
+        # Generate action_admin_<user|group>_<location>_<verb> for all combinations
+        %i[user group].each do |entity_type|
+          # all: list/show/delete only (no create, no modify — no update route on /users and /groups)
+          # local: full CRUD only — no nested settings under local_users/local_groups
+          ENTITY_LOCATIONS.each do |location|
+            ops = location.eql?(:all) ? (Operations::ALL - %i[create modify]) : Operations::ALL
+            ops.each do |op|
+              define_action_method([:admin, entity_type, location, op]) do
+                action_admin_entity_crud(entity_type, location, op)
               end
-              entity_verb = options.get_next_command(entity_commands)
-              lookup_block = ->(field, value){RestList.lookup_entity_generic(entity: entity_type, field: field, value: value){api_shares_admin.read(entities_path)}['id']}
-              case entity_verb
-              when *Operations::ALL
-                display_fields = entity_type.eql?(:user) ? %w[id user_id username first_name last_name email] : nil
-                display_fields.push('directory_user') if entity_type.eql?(:user) && entities_location.eql?(:all)
-                return entity_execute(
-                  api:            api_shares_admin,
-                  entity:         entities_path,
-                  command:        entity_verb,
-                  display_fields: display_fields,
-                  &lookup_block
-                )
-              when *USR_GRP_SETTINGS # transfer_settings, app_authorizations, share_permissions
-                group_id = options.instance_identifier(&lookup_block)
-                entities_path = "#{entities_path}/#{group_id}/#{entity_verb}"
-                return entity_execute(api: api_shares_admin, entity: entities_path, is_singleton: !entity_verb.eql?(:share_permissions), &lookup_share)
-              when :import # saml
-                return do_bulk_operation(command: entity_verb, descr: 'user information') do |entity_parameters|
-                  entity_parameters = entity_parameters.transform_keys{ |k| k.gsub(/\s+/, '_').downcase}
-                  Aspera.assert_type(entity_parameters, Hash)
-                  SAML_IMPORT_MANDATORY.each{ |p| raise "missing mandatory field: #{p}" if entity_parameters[p].nil?}
-                  entity_parameters.each_key do |p|
-                    raise "unsupported field: #{p}, use: #{SAML_IMPORT_ALLOWED.join(',')}" unless SAML_IMPORT_ALLOWED.include?(p)
+            end
+            unless location.eql?(:local)
+              USR_GRP_SETTINGS.each do |setting|
+                # share_permissions: Rails only exposes index+show (read-only)
+                setting_ops = setting.eql?(:share_permissions) ? SHARE_PERMISSIONS_OPS : %i[show modify]
+                setting_ops.each do |op|
+                  define_action_method([:admin, entity_type, location, setting, op]) do |**kwargs|
+                    action_admin_entity_setting(entity_type, location, setting, op, entity_id: kwargs[:"#{entity_type}_id"], permission_id: kwargs[:permission_id])
                   end
-                  api_shares_admin.create("#{entities_path}/import", entity_parameters)
-                end
-              when :add # ldap
-                return do_bulk_operation(command: entity_verb, descr: "#{entity_type} name", values: String) do |entity_name|
-                  api_shares_admin.create(entities_path, {entity_type=>entity_name})
                 end
-              when :users # group
-                return entity_execute(api: api_shares_admin, entity: "#{entities_path}/#{options.instance_identifier(&lookup_block)}/#{entities_prefix}users")
-              else Aspera.error_unexpected_value(entity_verb)
               end
             end
+            next unless entity_type.eql?(:group)
+            # group users: no create route (Rails only exposes index+show+update+destroy)
+            GROUP_USERS_OPS.each do |op|
+              define_action_method([:admin, entity_type, location, :users, op]) do |group_id:, **|
+                action_admin_entity_users(entity_type, location, op, group_id: group_id)
+              end
+            end
+          end
+
+          # ldap: add
+          define_action_method([:admin, entity_type, :ldap, :add]) do |entity_name:, **|
+            path = admin_entity_path(entity_type, :ldap)
+            bulk_result(entity_name, command: :add, id_result: entity_type.to_s) do |entity_name|
+              @api_shares_admin.create(path, {entity_type => entity_name})
+            end
+          end
+
+          # saml: import
+          define_action_method([:admin, entity_type, :saml, :import]) do |entity_parameters:, **|
+            path = admin_entity_path(entity_type, :saml)
+            bulk_result(entity_parameters, command: :import) do |entity_parameters|
+              entity_parameters = entity_parameters.transform_keys { |k| k.gsub(/\s+/, '_').downcase }
+              Aspera.assert_type(entity_parameters, Hash)
+              SAML_IMPORT_MANDATORY.each { |p| raise "missing mandatory field: #{p}" if entity_parameters[p].nil? }
+              entity_parameters.each_key do |p|
+                Aspera.assert_values(p, SAML_IMPORT_ALLOWED) { 'SAML field' }
+              end
+              @api_shares_admin.create("#{path}/import", entity_parameters)
+            end
+          end
+        end
+
+        # Handlers for admin > share > user_permissions|group_permissions > op
+        # share_id: resolved by Phase A via arguments:(:identifier, lookup: :lookup_share_id) on the perm_type node
+        # Rails only exposes index+show for share permissions (read-only)
+        %i[user_permissions group_permissions].each do |perm_type|
+          SHARE_PERMISSIONS_OPS.each do |op|
+            define_action_method([:admin, :share, perm_type, op]) do |share_id:, **|
+              id = Operations::INSTANCE.include?(op) ? options.instance_identifier : nil
+              send(:"entity_#{op}", api: @api_shares_admin, entity: "data/shares/#{share_id}/#{perm_type}", id: id)
+            end
           end
         end
       end

data/lib/aspera/cli/preset_actions.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Mixin for Config plugin: preset CRUD actions
+    module PresetActions
+      # Used to identify the global default preset keyword
+      GLOBAL_DEFAULT_KEYWORD = 'GLOBAL'
+      # Display columns for preset overview
+      CONF_OVERVIEW_KEYS = %w[preset parameter value].freeze
+
+      def action_preset_list(**)
+        Result::ValueList.new(presets.config_presets.keys, name: 'name')
+      end
+
+      def action_preset_overview(**)
+        cp = presets.config_presets
+        # Display process modifies the value (hide secrets): we do not want to save removed secrets
+        data = PresetManager.deep_clone(cp)
+        formatter.hide_secrets(data)
+        result = []
+        data.each do |config, preset|
+          preset.each do |parameter, value|
+            result.push(CONF_OVERVIEW_KEYS.zip([config, parameter, value]).to_h)
+          end
+        end
+        Result::ObjectList.new(result, fields: CONF_OVERVIEW_KEYS)
+      end
+
+      def action_preset_lookup(**)
+        Plugins::BasicAuth.declare_options(options, parse: true)
+        url = options.get_option(:url, mandatory: true)
+        user = options.get_option(:username, mandatory: true)
+        result = presets.lookup_preset(url: url, username: user)
+        Aspera.assert(!result.nil?, type: Error) { 'no such config found' }
+        Result::SingleObject.new(result)
+      end
+
+      def action_preset_secure(config_name: nil, **)
+        cp = presets.config_presets
+        preset_names = config_name.nil? ? cp.keys : [config_name]
+        preset_names.each do |preset_name|
+          preset = cp[preset_name]
+          next unless preset.is_a?(Hash)
+          preset.each_key do |option_name|
+            secure_preset_option(preset, preset_name, option_name)
+          end
+        end
+        Result::Status.new('Secrets secured in vault: Make sure to save the vault password securely.')
+      end
+
+      private
+
+      SECRET_KEYWORDS = %w[password secret].freeze
+
+      # If +option_name+ ends with a secret keyword and the vault is configured,
+      # move the clear-text value into the vault and replace it with a @vault: reference.
+      # @param preset      [Hash]   the preset hash (modified in place)
+      # @param preset_name [String] name used as base for the vault label
+      # @param option_name [String] option key to inspect
+      def secure_preset_option(preset, preset_name, option_name)
+        return unless SECRET_KEYWORDS.any? { |kw| option_name.end_with?(kw) }
+        # Never auto-secure the global preset: it holds vault credentials themselves
+        return if preset_name.eql?(presets.global_default_preset)
+        return if vault.nil?
+        value = preset[option_name]
+        # Already a vault reference or nil — nothing to do
+        return if value.nil? || value.to_s.start_with?('@vault:')
+        vault_label = preset_name
+        incr = 0
+        until vault.get(label: vault_label, exception: false).nil?
+          vault_label = "#{preset_name}#{incr}"
+          incr += 1
+        end
+        Log.log.info { "Securing #{preset_name}.#{option_name} -> vault label: #{vault_label}" }
+        vault.set({label: vault_label, password: value})
+        preset[option_name] = "@vault:#{vault_label}.password"
+      end
+
+      public
+
+      def action_preset_show(name:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        cp = presets.config_presets
+        raise "no such preset: #{name}" unless cp.key?(name)
+        Result::SingleObject.new(PresetManager.deep_clone(cp[name]))
+      end
+
+      def action_preset_delete(name:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        cp = presets.config_presets
+        raise "no such preset: #{name}" unless cp.key?(name)
+        cp.delete(name)
+        Result::Status.new("Deleted: #{name}")
+      end
+
+      def action_preset_get(name:, param_name:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        cp = presets.config_presets
+        raise "no such preset: #{name}" unless cp.key?(name)
+        value = cp[name][param_name]
+        raise "no such option in preset #{name} : #{param_name}" if value.nil?
+        case value
+        when Numeric, String then return Result::Text.new(ExtendedValue.instance.evaluate(value.to_s, context: 'preset'))
+        end
+        Result::SingleObject.new(value)
+      end
+
+      def action_preset_unset(name:, param_name:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        cp = presets.config_presets
+        raise "no such preset: #{name}" unless cp.key?(name)
+        cp[name].delete(param_name)
+        Result::Status.new("Removed: #{name}: #{param_name}")
+      end
+
+      def action_preset_set(name:, param_name:, param_value:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        param_name = Parser.option_line_to_name(param_name)
+        presets.set_key(name, param_name, Parser.smart_convert(param_value))
+        secure_preset_option(presets.config_presets[name], name, param_name)
+        Result::Nothing.new
+      end
+
+      def action_preset_initialize(name:, config_value:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        cp = presets.config_presets
+        Log.log.warn { "configuration already exists: #{name}, overwriting" } if cp.key?(name)
+        cp[name] = config_value
+        Result::Status.new("Modified: #{@option_config_file}")
+      end
+
+      def action_preset_update(name:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        unprocessed_options = options.unprocessed_options_with_value
+        Log.dump(:opts, unprocessed_options)
+        cp = presets.config_presets
+        cp[name] ||= {}
+        cp[name].merge!(unprocessed_options)
+        unprocessed_options.each_key { |k| secure_preset_option(cp[name], name, k) }
+        Result::Status.new("Updated: #{name}")
+      end
+
+      def action_preset_ask(name:, option_names:, **)
+        name = presets.global_default_preset if name.eql?(GLOBAL_DEFAULT_KEYWORD)
+        cp = presets.config_presets
+        cp[name] ||= {}
+        option_names.each do |option_name|
+          option_value = options.get_interactive(option_name, check_option: true)
+          cp[name][option_name] = option_value
+          secure_preset_option(cp[name], name, option_name)
+        end
+        Result::Status.new("Updated: #{name}")
+      end
+    end
+  end
+end