aspera-cli 4.26.2 → 4.27.0

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

@@ -48,13 +48,31 @@ module Aspera
 
         attr_accessor :option_skip_types, :option_previews_folder, :option_folder_reset_cache, :option_skip_folders, :option_overwrite
 
+        # DSL option declarations (Pattern 1 and Pattern 2 - handler: Symbol resolved to self)
+        option :skip_format,        description: 'Skip this preview format',                                                                                                      allowed: Aspera::Preview::Generator::PREVIEW_FORMATS
+        # TODO: use the same option as in `node` plugin
+        option :folder_reset_cache, description: 'Force detection of generated preview by refresh cache',                                                                         allowed: %i[no header read], handler: :option_folder_reset_cache, default: :no
+        option :skip_types,         description: 'Skip generation for those types of files',                                                                                      allowed: Allowed::TYPES_SYMBOL_ARRAY + Aspera::Preview::FileTypes::CONVERSION_TYPES, handler: :option_skip_types
+        option :previews_folder,    description: 'Preview folder in storage root',                                                                                                handler: :option_previews_folder, default: DEFAULT_PREVIEWS_FOLDER
+        option :skip_folders,       description: 'List of folder to skip',                                                                                                        allowed: Allowed::TYPES_STRING_ARRAY, handler: :option_skip_folders
+        option :base,               description: 'Basename of output for for test'
+        option :scan_path,          description: 'Subpath in folder id to start scan in (default=/)'
+        option :scan_id,            description: 'Folder id in storage to start scan in, default is access key main folder id'
+        option :mimemagic,          description: 'Use Mime type detection of gem mimemagic',                                                                                      allowed: Allowed::TYPES_BOOLEAN, default: false
+        option :overwrite,          description: 'When to overwrite result file',                                                                                                 allowed: %i[always never mtime], handler: :option_overwrite, default: :mtime
+        option :root_url,           description: "How to read and write files on storage (<empty>, #{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})", default: ''
+        # Generator-specific options (Category C - bound to @gen_options via set_handler in initialize)
+        Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
+          values = if opt.key?(:values)
+            opt[:values]
+          elsif BoolValue.symbol?(opt[:default])
+            BoolValue::TYPES
+          end
+          option(opt[:name], description: opt[:description].capitalize, allowed: values, default: opt[:default])
+        end
+
         def initialize(**_)
           super
-          @option_skip_types = []
-          @option_skip_folders = []
-          @option_previews_folder = nil
-          @option_overwrite = nil
-          @option_folder_reset_cache = nil
           # Generator configuration populated from CLI options.
           @gen_options = Aspera::Preview::Options.new
           # Used to rate-limit periodic progress logging and checkpoint persistence.
@@ -62,40 +80,9 @@ module Aspera
           # Optional callback used to filter entries before generation.
           @filter_block = nil
           @access_remote = true
-          # Bind CLI options directly to generator option attributes.
-          options.declare(
-            :skip_format, 'Skip this preview format',
-            allowed: Aspera::Preview::Generator::PREVIEW_FORMATS
-          )
-          # TODO: use the same option as in `node` plugin
-          options.declare(
-            :folder_reset_cache, 'Force detection of generated preview by refresh cache',
-            allowed: %i[no header read],
-            handler: {o: self, m: :option_folder_reset_cache},
-            default: :no
-          )
-          options.declare(:skip_types, 'Skip generation for those types of files', handler: {o: self, m: :option_skip_types}, allowed: Allowed::TYPES_SYMBOL_ARRAY + Aspera::Preview::FileTypes::CONVERSION_TYPES)
-          options.declare(:previews_folder, 'Preview folder in storage root', handler: {o: self, m: :option_previews_folder}, default: DEFAULT_PREVIEWS_FOLDER)
-          options.declare(:skip_folders, 'List of folder to skip', handler: {o: self, m: :option_skip_folders}, allowed: Allowed::TYPES_STRING_ARRAY)
-          options.declare(:base, 'Basename of output for for test')
-          options.declare(:scan_path, 'Subpath in folder id to start scan in (default=/)')
-          options.declare(:scan_id, 'Folder id in storage to start scan in, default is access key main folder id')
-          options.declare(:mimemagic, 'Use Mime type detection of gem mimemagic', allowed: Allowed::TYPES_BOOLEAN, default: false)
-          options.declare(:overwrite, 'When to overwrite result file', handler: {o: self, m: :option_overwrite}, allowed: %i[always never mtime], default: :mtime)
-          options.declare(
-            :root_url,
-            "How to read and write files on storage (<empty>, #{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})",
-            allowed: Allowed::TYPES_STRING,
-            default: ''
-          )
-          # Declare generator-specific options and apply their default values.
+          # Bind generator-specific options to @gen_options (Category C: set_handler after object creation)
           Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
-            values = if opt.key?(:values)
-              opt[:values]
-            elsif BoolValue.symbol?(opt[:default])
-              BoolValue::TYPES
-            end
-            options.declare(opt[:name], opt[:description].capitalize, allowed: values, handler: {o: @gen_options, m: opt[:name]}, default: opt[:default])
+            options.set_handler(opt[:name], object: @gen_options, method: opt[:name])
           end
 
           options.parse_options!
@@ -112,7 +99,7 @@ module Aspera
         # Process legacy transfer events and trigger preview generation for completed downloads.
         #
         # @param iteration_persistency [PersistencyActionOnce, nil] stores the last processed event id
-        # @return [void]
+        # @return [nil]
         def process_trevents(iteration_persistency)
           events_filter = {
             'access_key' => @access_key_self['id'],
@@ -152,12 +139,13 @@ module Aspera
               iteration_persistency.save
             end
           end
+          nil
         end
 
         # Process recent Node API file events since the last persisted checkpoint.
         #
         # @param iteration_persistency [PersistencyActionOnce, nil] stores the last processed event id
-        # @return [void]
+        # @return [nil]
         def process_events(iteration_persistency)
           # Restrict the event stream to file-related changes for the current access key.
           events_filter = {
@@ -188,6 +176,7 @@ module Aspera
               iteration_persistency.save
             end
           end
+          nil
         end
 
         # Transfer a file to or from the configured Node storage using a tagged transfer spec.
@@ -278,7 +267,7 @@ module Aspera
         # Remote entries must include `parent_file_id`.
         #
         # @param entry [Hash] local or remote file entry to preview
-        # @return [void]
+        # @return [nil]
         def generate_preview(entry)
           # prepare generic information
           gen_infos = @preview_formats_to_generate.map do |preview_format|
@@ -406,113 +395,165 @@ module Aspera
           end
         end
 
-        ACTIONS = %i[scan events trevents check test show].freeze
+        # --- DSL ---
+
+        # Commands that connect to the Node API share a common setup.
+        # :check, :test and :show work without Node API authentication.
+        command :scan,     description: 'Scan all files and generate previews', setup: :setup_node_api
+        command :events,   description: 'Process file events and generate previews', setup: :setup_node_api
+        command :trevents, description: 'Process transfer events and generate previews', setup: :setup_node_api
+        command :check,    description: 'Check required tools are installed'
+        command :test,     description: 'Test preview generation for a source file',
+          arguments: [{name: :source_file, type: String}, {name: :format, allowed: Aspera::Preview::Generator::PREVIEW_FORMATS, mandatory: false, default: :png}]
+        command :show,     description: 'Generate and display preview of a source file',
+          arguments: [{name: :source_file, type: String}]
+
+        # --- setup ---
 
-        def execute_action
-          command = options.get_next_command(ACTIONS)
-          unless %i[check test show].include?(command)
-            # This will use node api
-            @api_node = Api::Node.new(**basic_auth_params)
-            @transfer_server_address = URI.parse(@api_node.base_url).host
-            # Get current access key information
-            @access_key_self = @api_node.read('access_keys/self')
-            # TODO: check events is activated here:
-            # note that docroot is good to look at as well
-            node_info = @api_node.read('info')
-            Log.log.debug{"root: #{node_info['docroot']}"}
-            # Default storage url to local file if not provided
-            option_root_url = options.get_option(:root_url, mandatory: true)
-            option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.empty? && @access_key_self['storage']['type'].eql?('local')
-            @access_remote = !UriReader.file?(option_root_url)
-            Log.log.debug{"remote: #{@access_remote}"}
-            # TODO: can the `previews` folder parameter be read from Node API ?
-            @option_skip_folders.push("/#{@option_previews_folder}")
-            if @access_remote
-              # NOTE: the filter "name", it's why we take the first one
-              @previews_folder_entry = @api_node.read_folder_content(@access_key_self['root_file_id'], {name: @option_previews_folder}).first
-              raise Cli::Error, "Folder #{@option_previews_folder} does not exist on node. " \
-                'Please create it in the storage root, or specify an alternate name.' if @previews_folder_entry.nil?
+        # Build the Node API and set up storage references for scan/events/trevents.
+        # @return [Hash] empty ctx (state stored in instance variables)
+        def setup_node_api(**)
+          @api_node = Api::Node.new(**basic_auth_params)
+          @transfer_server_address = URI.parse(@api_node.base_url).host
+          # Get current access key information
+          @access_key_self = @api_node.read('access_keys/self')
+          # TODO: check events is activated here:
+          # note that docroot is good to look at as well
+          node_info = @api_node.read('info')
+          Log.log.debug{"root: #{node_info['docroot']}"}
+          # Default storage url to local file if not provided
+          option_root_url = options.get_option(:root_url, mandatory: true)
+          option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.empty? && @access_key_self['storage']['type'].eql?('local')
+          @access_remote = !UriReader.file?(option_root_url)
+          Log.log.debug{"remote: #{@access_remote}"}
+          # TODO: can the `previews` folder parameter be read from Node API ?
+          @option_skip_folders.push("/#{@option_previews_folder}")
+          if @access_remote
+            # NOTE: the filter "name", it's why we take the first one
+            @previews_folder_entry = @api_node.read_folder_content(@access_key_self['root_file_id'], {name: @option_previews_folder}).first
+            raise Cli::Error, "Folder #{@option_previews_folder} does not exist on node. " \
+              'Please create it in the storage root, or specify an alternate name.' if @previews_folder_entry.nil?
+          else
+            @local_storage_root = UriReader.file_path(option_root_url)
+            # TODO: Windows could have "C:" ?
+            Aspera.assert(@local_storage_root.start_with?('/')){"not local storage: #{@local_storage_root}"}
+            Aspera.assert(File.directory?(@local_storage_root), type: Cli::Error){"Local storage root folder #{@local_storage_root} does not exist."}
+            @local_preview_folder = File.join(@local_storage_root, @option_previews_folder)
+            Aspera.assert(File.directory?(@local_preview_folder), type: Cli::Error){"Folder #{@local_preview_folder} does not exist locally. Please create it, or specify an alternate name."}
+            # Protection to avoid clash of file id for two different access keys
+            marker_file = File.join(@local_preview_folder, AK_MARKER_FILE)
+            Log.log.debug{"marker file: #{marker_file}"}
+            if File.exist?(marker_file)
+              ak = File.read(marker_file).chomp
+              Aspera.assert(@access_key_self['id'].eql?(ak)){"mismatch access key in #{marker_file}: contains #{ak}, using #{@access_key_self['id']}"}
             else
-              @local_storage_root = UriReader.file_path(option_root_url)
-              # TODO: Windows could have "C:" ?
-              Aspera.assert(@local_storage_root.start_with?('/')){"not local storage: #{@local_storage_root}"}
-              Aspera.assert(File.directory?(@local_storage_root), type: Cli::Error){"Local storage root folder #{@local_storage_root} does not exist."}
-              @local_preview_folder = File.join(@local_storage_root, @option_previews_folder)
-              Aspera.assert(File.directory?(@local_preview_folder), type: Cli::Error){"Folder #{@local_preview_folder} does not exist locally. Please create it, or specify an alternate name."}
-              # Protection to avoid clash of file id for two different access keys
-              marker_file = File.join(@local_preview_folder, AK_MARKER_FILE)
-              Log.log.debug{"marker file: #{marker_file}"}
-              if File.exist?(marker_file)
-                ak = File.read(marker_file).chomp
-                Aspera.assert(@access_key_self['id'].eql?(ak)){"mismatch access key in #{marker_file}: contains #{ak}, using #{@access_key_self['id']}"}
-              else
-                File.write(marker_file, @access_key_self['id'])
-              end
+              File.write(marker_file, @access_key_self['id'])
             end
           end
-          Aspera::Preview::FileTypes.instance.use_mimemagic = options.get_option(:mimemagic, mandatory: true)
-          # check tools that are anyway required for all cases
-          Aspera::Preview::Utils.check_tools(@option_skip_types)
-          case command
-          when :scan
-            scan_path = options.get_option(:scan_path)
-            scan_id = options.get_option(:scan_id)
-            # by default start at root
-            folder_info =
-              if scan_id.nil?
-                {
-                  'id'   => @access_key_self['root_file_id'],
-                  'name' => '/',
-                  'type' => 'folder',
-                  'path' => '/'
-                }
-              else
-                @api_node.read("files/#{scan_id}")
-              end
-            @filter_block = Api::Node.file_matcher_from_argument(options)
-            scan_folder_files(folder_info, scan_path)
-            return Result::Status.new('scan finished')
-          when :events, :trevents
-            @filter_block = Api::Node.file_matcher_from_argument(options)
-            iteration_persistency = nil
-            if options.get_option(:once_only, mandatory: true)
-              iteration_persistency = PersistencyActionOnce.new(
-                manager: persistency,
-                data:    [],
-                id:      IdGenerator.from_list(
-                  'preview_iteration',
-                  command.to_s,
-                  options.get_option(:url, mandatory: true),
-                  options.get_option(:username, mandatory: true)
-                )
-              )
+          {}
+        end
+
+        # --- handlers ---
+
+        def action_scan
+          check_tools_and_mimemagic
+          scan_path = options.get_option(:scan_path)
+          scan_id = options.get_option(:scan_id)
+          folder_info =
+            if scan_id.nil?
+              {
+                'id'   => @access_key_self['root_file_id'],
+                'name' => '/',
+                'type' => 'folder',
+                'path' => '/'
+              }
+            else
+              @api_node.read("files/#{scan_id}")
             end
-            # call processing method specified by command line command
-            send(:"process_#{command}", iteration_persistency)
-            return Result::Status.new("#{command} finished")
-          when :check
-            return Result::Status.new('Tools validated')
-          when :test
-            source = options.get_next_argument('source file')
-            format = options.get_next_argument('format', accept_list: Aspera::Preview::Generator::PREVIEW_FORMATS, default: :png)
-            generated_file_path = preview_filename(format, options.get_option(:base))
-            Aspera::Preview::Generator.new(source, generated_file_path, @gen_options, @tmp_folder).generate
-            return Result::Status.new("generated: #{generated_file_path}")
-          when :show
-            source = options.get_next_argument('source file')
-            # terminal_options = options.get_next_argument('options', validation: Hash, default: {}).symbolize_keys
-            generated_file_path = preview_filename(:png, options.get_option(:base))
-            Aspera::Preview::Generator.new(source, generated_file_path, @gen_options, @tmp_folder).generate
-            formatter.display_status("generated: #{generated_file_path}")
-            # formatter.display_status(Aspera::Preview::Terminal.build(File.read(generated_file_path), **terminal_options))
-            # return Result::Status.new("generated: #{generated_file_path}")
-            return Result::Image.new(UriReader.file_url(generated_file_path))
-          else Aspera.error_unexpected_value(command)
-          end
+          @filter_block = Api::Node.file_matcher_from_argument(options)
+          scan_folder_files(folder_info, scan_path)
+          Result::Status.new('scan finished')
         ensure
+          cleanup_tmp_folder
+        end
+
+        def action_events
+          check_tools_and_mimemagic
+          run_event_loop(:events)
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_trevents
+          check_tools_and_mimemagic
+          run_event_loop(:trevents)
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_check
+          check_tools_and_mimemagic
+          Result::Status.new('Tools validated')
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_test(source_file:, format:, **)
+          check_tools_and_mimemagic
+          generated_file_path = preview_filename(format, options.get_option(:base))
+          Aspera::Preview::Generator.new(source_file, generated_file_path, @gen_options, @tmp_folder).generate
+          Result::Status.new("generated: #{generated_file_path}")
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_show(source_file:, **)
+          check_tools_and_mimemagic
+          # terminal_options = options.get_next_argument('options', validation: Hash, default: {}).symbolize_keys
+          generated_file_path = preview_filename(:png, options.get_option(:base))
+          Aspera::Preview::Generator.new(source_file, generated_file_path, @gen_options, @tmp_folder).generate
+          formatter.display_status("generated: #{generated_file_path}")
+          # formatter.display_status(Aspera::Preview::Terminal.build(File.read(generated_file_path), **terminal_options))
+          # Result::Status.new("generated: #{generated_file_path}")
+          Result::Image.new(UriReader.file_url(generated_file_path))
+        ensure
+          cleanup_tmp_folder
+        end
+
+        private
+
+        # Check tools and set mimemagic flag (required for all commands).
+        def check_tools_and_mimemagic
+          Aspera::Preview::FileTypes.instance.use_mimemagic = options.get_option(:mimemagic, mandatory: true)
+          Aspera::Preview::Utils.check_tools(@option_skip_types)
+        end
+
+        # Clean up the temporary folder after each command.
+        def cleanup_tmp_folder
           Log.log.debug{"cleaning up temp folder #{@tmp_folder}"}
           FileUtils.rm_rf(@tmp_folder)
         end
+
+        # Shared event-loop body for :events and :trevents.
+        # @param command [:events, :trevents]
+        def run_event_loop(command)
+          @filter_block = Api::Node.file_matcher_from_argument(options)
+          iteration_persistency = nil
+          if options.get_option(:once_only, mandatory: true)
+            iteration_persistency = PersistencyActionOnce.new(
+              manager: persistency,
+              data:    [],
+              id:      IdGenerator.from_list(
+                'preview_iteration',
+                command.to_s,
+                options.get_option(:url, mandatory: true),
+                options.get_option(:username, mandatory: true)
+              )
+            )
+          end
+          send(:"process_#{command}", iteration_persistency)
+          Result::Status.new("#{command} finished")
+        end
       end
     end
   end

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

@@ -3,6 +3,7 @@
 # cspell:ignore ascmd zmode zuid zgid fasping
 require 'aspera/cli/plugins/basic_auth'
 require 'aspera/cli/sync_actions'
+require 'aspera/transfer/result'
 require 'aspera/transfer/spec'
 require 'aspera/ascmd'
 require 'aspera/ssh'
@@ -21,26 +22,17 @@ module Aspera
         LOCAL_SCHEME = 'local'
         HTTPS_SCHEME = 'https'
         URI_SCHEMES = [SSH_SCHEME, LOCAL_SCHEME, HTTPS_SCHEME].freeze
-        ASCMD_ALIASES = {
-          browse: :ls,
-          delete: :rm,
-          rename: :mv
-        }.freeze
-        TRANSFER_COMMANDS = %i[sync upload download].freeze
 
-        private_constant :SSH_SCHEME, :URI_SCHEMES, :ASCMD_ALIASES, :TRANSFER_COMMANDS
+        private_constant :SSH_SCHEME, :URI_SCHEMES
 
         class LocalExecutor
           def execute(ascmd_path, input:)
             Environment.secure_execute(ascmd_path, mode: :capture, stdin_data: input, binmode: true, exception: false).first
           end
         end
+        application_name 'HSTS Fasp/SSH'
 
         class << self
-          def application_name
-            'HSTS Fasp/SSH'
-          end
-
           # @return [Hash,NilClass]
           def detect(address_or_url)
             urls = if address_or_url.match?(%r{^[a-z]{1,6}://})
@@ -87,10 +79,8 @@ module Aspera
         def initialize(**_)
           super
           @connection_type = :ssh
-          options.declare(:ssh_keys, 'SSH key path list', allowed: Allowed::TYPES_STRING_ARRAY)
-          options.declare(:passphrase, 'SSH private key passphrase')
-          options.declare(:ssh_options, 'SSH options', allowed: Hash, default: {})
-          SyncActions.declare_options(options)
+          @ascmd_executor = nil
+          @server_transfer_spec = nil
           options.parse_options!
           @ssh_opts = options.get_option(:ssh_options).symbolize_keys
         end
@@ -169,77 +159,132 @@ module Aspera
           return server_transfer_spec
         end
 
-        def execute_transfer(command, transfer_spec)
-          case command
-          when :upload, :download
-            transfer_spec['direction'] = Transfer::Spec.transfer_type_to_direction(command)
-            return Runner.result_transfer(transfer.start(transfer_spec))
-          when :sync
-            # lets ignore the arguments provided by execute_sync_action, we just give the transfer spec
-            return execute_sync_action{transfer_spec}
+        Sync::Operations::DIRECTIONS.each do |dir|
+          define_method(:"action_sync_#{dir}"){ |**| run_sync_transfer(dir){@server_transfer_spec}}
+        end
+
+        # --- DSL ---
+
+        option :ssh_keys,    description: 'SSH key path list', allowed: Allowed::TYPES_STRING_ARRAY
+        option :passphrase,  description: 'SSH private key passphrase'
+        option :ssh_options, description: 'SSH options', allowed: Hash
+
+        # root_setup runs once before any command argument is consumed, populating
+        # @server_transfer_spec and @ascmd_executor so that condition methods work.
+        root_setup :setup_server
+
+        command :health, description: 'Check transfer health'
+        command(:upload, description: 'Upload files to server', transfer_paths: :send, action: lambda do
+          @server_transfer_spec['direction'] = Transfer::Spec.transfer_type_to_direction(:upload)
+          Runner.result_transfer(transfer.start(@server_transfer_spec))
+        end)
+        command(:download, description: 'Download files from server', transfer_paths: :receive, action: lambda do
+          @server_transfer_spec['direction'] = Transfer::Spec.transfer_type_to_direction(:download)
+          Runner.result_transfer(transfer.start(@server_transfer_spec))
+        end)
+        command :sync, description: 'Synchronize files with server'
+        commands_under(:sync) do
+          Sync::Operations::DIRECTIONS.each do |dir|
+            command(dir, description: "#{dir.capitalize}-sync with server", transfer_paths: :send)
+          end
+          command :admin, description: 'Manage sync database (admin operations)'
+          SyncActions.register_sync_admin_commands(self, %i[sync admin])
+        end
+
+        commands_under(:health) do
+          command :transfer, description: 'Check FASP transfer health'
+        end
+
+        # AsCmd operations (available only when SSH/local - not WSS)
+        ASCMD_ARGS = [{name: :command_arguments, multiple: true, mandatory: false, default: nil}].freeze
+        private_constant :ASCMD_ARGS
+
+        command :ls,     description: 'List files on server',            condition: :ascmd_available?, aliases: [:browse], arguments: ASCMD_ARGS
+        command :rm,     description: 'Delete file(s) on server',        condition: :ascmd_available?, aliases: [:delete], arguments: ASCMD_ARGS
+        command :mv,     description: 'Rename/move file(s) on server',   condition: :ascmd_available?, aliases: [:rename], arguments: ASCMD_ARGS
+        command :cp,     description: 'Copy file(s) on server',          condition: :ascmd_available?,                     arguments: ASCMD_ARGS
+        command :mkdir,  description: 'Create directory on server',       condition: :ascmd_available?,                     arguments: ASCMD_ARGS
+        command :df,     description: 'Show disk usage on server',        condition: :ascmd_available?,                     arguments: ASCMD_ARGS
+        command :du,     description: 'Show file sizes on server',        condition: :ascmd_available?,                     arguments: ASCMD_ARGS
+        command :md5sum, description: 'Compute MD5 checksums on server',  condition: :ascmd_available?,                     arguments: ASCMD_ARGS
+        command :info,   description: 'Show server system information',   condition: :ascmd_available?,                     arguments: ASCMD_ARGS
+
+        # Generate ascmd handlers - convention: action_<op>
+        %i[rm mv cp mkdir].each do |op|
+          define_action_method([op]) do |command_arguments:, **|
+            execute_ascmd(op, command_arguments){Result::Success.new}
           end
         end
 
-        # actions without ascmd
-        BASE_ACTIONS = %i[health].concat(TRANSFER_COMMANDS).freeze
-        # all actions
-        ACTIONS = [BASE_ACTIONS, AsCmd::OPERATIONS, ASCMD_ALIASES.keys].flatten.freeze
+        %i[du md5sum info].each do |op|
+          define_action_method([op]) do |command_arguments:, **|
+            execute_ascmd(op, command_arguments){ |r| Result::SingleObject.new(r.stringify_keys)}
+          end
+        end
+
+        # --- conditions ---
+
+        def ascmd_available?
+          !@ascmd_executor.nil?
+        end
+
+        # --- setup ---
 
-        def execute_action
-          server_transfer_spec = options_to_base_transfer_spec
-          ascmd_executor = case @connection_type
+        # Build the transfer spec and ascmd executor from CLI options.
+        # Stores results in instance variables; returns empty context hash.
+        def setup_server(**)
+          @server_transfer_spec = options_to_base_transfer_spec
+          @ascmd_executor = case @connection_type
           when :local then LocalExecutor.new
-          when :wss then nil
-          when :ssh then Ssh.new(server_transfer_spec['remote_host'], server_transfer_spec['remote_user'], @ssh_opts)
+          when :wss   then nil
+          when :ssh   then Ssh.new(@server_transfer_spec['remote_host'], @server_transfer_spec['remote_user'], @ssh_opts)
           else Aspera.error_unexpected_value(@connection_type){'connection type'}
           end
-          # the set of available commands depends on SSH executor availability (i.e. no WSS)
-          available_commands = ascmd_executor.nil? ? BASE_ACTIONS : ACTIONS
-          # get command and translate aliases
-          command = options.get_next_command(available_commands)
-          command = ASCMD_ALIASES[command] if ASCMD_ALIASES.key?(command)
-          case command
-          when :health
-            nagios = Nagios.new
-            command_nagios = options.get_next_command(%i[transfer])
-            case command_nagios
-            when :transfer
-              probe_ts = server_transfer_spec.merge({
-                'direction'     => 'send',
-                'cookie'        => 'aspera.sync', # hide in console
-                'resume_policy' => 'none',
-                'paths'         => [{'source' => 'faux:///pingfile?1k', 'destination' => '.fasping'}]
-              })
-              statuses = transfer.start(probe_ts)
-              if TransferAgent.session_status(statuses).eql?(:success)
-                nagios.add_ok('transfer', 'ok')
-              else
-                nagios.add_critical('transfer', statuses.reject{ |i| i.eql?(:success)}.first.to_s)
-              end
-            else Aspera.error_unexpected_value(command_nagios)
-            end
-            Result::ObjectList.new(nagios.status_list)
-          when *TRANSFER_COMMANDS
-            return execute_transfer(command, server_transfer_spec)
-          when *AsCmd::OPERATIONS
-            command_arguments = options.get_next_argument('ascmd command arguments', multiple: true, mandatory: false)
-            ascmd = AsCmd.new(ascmd_executor)
-            begin
-              result = ascmd.execute_single(command, command_arguments)
-              case command
-              when :mkdir, :mv, :cp, :rm
-                return Result::Success.new
-              when :ls
-                return Result::ObjectList.new(result.map(&:stringify_keys), fields: %w[zmode zuid zgid size mtime name])
-              when :df
-                return Result::ObjectList.new(result.map(&:stringify_keys))
-              when :du, :md5sum, :info
-                return Result::SingleObject.new(result.stringify_keys)
-              end
-            rescue AsCmd::Error => e
-              raise Cli::BadArgument, e.extended_message
-            end
-          else Aspera.error_unreachable_line
+          {}
+        end
+
+        # --- health ---
+
+        def action_health_transfer
+          nagios = Nagios.new
+          probe_ts = @server_transfer_spec.merge({
+            'direction'     => 'send',
+            'cookie'        => 'aspera.sync', # hide in console
+            'resume_policy' => 'none',
+            'paths'         => [{'source' => 'faux:///pingfile?1k', 'destination' => '.fasping'}]
+          })
+          statuses = transfer.start(probe_ts)
+          if statuses.is_a?(Transfer::Result::Success)
+            nagios.add_ok('transfer', 'ok')
+          else
+            nagios.add_critical('transfer', statuses.is_a?(Transfer::Result::Error) ? statuses.exception.message : statuses.to_s)
+          end
+          Result::ObjectList.new(nagios.status_list)
+        end
+
+        # --- ascmd handlers ---
+
+        def action_ls(command_arguments:, **)
+          execute_ascmd(:ls, command_arguments) do |result|
+            Result::ObjectList.new(result.map(&:stringify_keys), fields: %w[zmode zuid zgid size mtime name])
+          end
+        end
+
+        def action_df(command_arguments:, **)
+          execute_ascmd(:df, command_arguments) do |result|
+            Result::ObjectList.new(result.map(&:stringify_keys))
+          end
+        end
+
+        private
+
+        def execute_ascmd(op, command_arguments)
+          ascmd = AsCmd.new(@ascmd_executor)
+          begin
+            result = ascmd.execute_single(op, command_arguments)
+            yield(result)
+          rescue AsCmd::Error => e
+            raise Cli::BadArgument, e.extended_message
           end
         end
       end