aspera-cli 4.27.2 → 4.27.4

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

@@ -3,11 +3,11 @@
 # cspell:ignore trevents
 require 'aspera/cli/plugins/basic_auth'
 require 'aspera/preview/generator'
-require 'aspera/preview/options'
 require 'aspera/preview/utils'
 require 'aspera/preview/file_types'
 require 'aspera/preview/terminal'
 require 'aspera/transfer/spec'
+require 'aspera/schema/registry'
 require 'aspera/persistency_action_once'
 require 'aspera/temp_file_manager'
 require 'aspera/api/node'
@@ -18,6 +18,8 @@ require 'aspera/uri_reader'
 require 'aspera/log'
 require 'aspera/assert'
 require 'securerandom'
+require 'aspera/rainbow'
+using Rainbow
 
 module Aspera
   module Cli
@@ -46,53 +48,59 @@ module Aspera
           :LOG_LIMITER_SEC,
           :REMOTE_ACCESS
 
-        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)
+        # DSL option declarations
         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: Type::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: Type::STRING_ARRAY, handler: :option_skip_folders
+        option :folder_reset_cache, description: 'Force detection of generated preview by refresh cache',                                                                         allowed: %i[no header read], default: :no
+        option :skip_types,         description: 'Skip generation for those types of files',                                                                                      allowed: Type::SYMBOL_ARRAY + Aspera::Preview::FileTypes::CONVERSION_TYPES
+        option :previews_folder,    description: 'Preview folder in storage root',                                                                                                default: DEFAULT_PREVIEWS_FOLDER
+        option :skip_folders,       description: 'List of folder to skip',                                                                                                        allowed: Type::STRING_ARRAY
         option :base,               description: 'Basename of output for for test'
-        option :filter, description: 'File name filter: String (glob), Regexp, or Proc', allowed: [String, Regexp, Proc, NilClass]
-        option :mimemagic,          description: 'Use Mime type detection of gem mimemagic',                                                                                      allowed: Type::BOOLEAN, default: false
-        option :overwrite,          description: 'When to overwrite result file',                                                                                                 allowed: %i[always never mtime], handler: :option_overwrite, default: :mtime
+        option :filter,             description: 'File name filter: String (glob), Regexp, or Proc', allowed: [String, Regexp, Proc, NilClass]
+        option :detect_mime,        description: 'Detect Mime type by analyzing file', allowed: Type::BOOLEAN, default: false
+        option :overwrite,          description: 'When to overwrite result file', allowed: %i[always never mtime], default: :mtime
         option :root_url,           description: "How to read and write files on storage (#{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})", default: REMOTE_ACCESS
-        # 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])
+        # Generator options, defined in schema: values set in @gen_options
+        Schema::Registry.instance.reader(Schema::Registry::PREVIEW_OPTIONS).current['properties'].each do |name, property|
+          key = name.to_sym
+          option(
+            key,
+            description: property['description'].lines.first.strip.delete_suffix('.'),
+            allowed:     property.key?('enum') ? property['enum'].map(&:to_sym) : {'integer' => Type::INTEGER, 'number' => Type::FLOAT, 'boolean' => Type::BOOLEAN}[property['type']],
+            default:     property['default'],
+            # `Hash` value: validated with schema
+            schema:      ("#{Schema::Registry::PREVIEW_OPTIONS}:properties.#{name}" if property['type'].eql?('object')),
+            on_set:      ->(value) { @gen_options[key] = value }
+          )
         end
 
         def initialize(**_)
+          # Generator options, see `options.schema.yaml`
+          # Created before `super`, which declares options: values are set through `on_set`.
+          @gen_options = Aspera::Preview::Generator::Options.new
           super
-          # Generator configuration populated from CLI options.
-          @gen_options = Aspera::Preview::Options.new
           # Used to rate-limit periodic progress logging and checkpoint persistence.
           @periodic = TimerLimiter.new(LOG_LIMITER_SEC)
           # Optional callback used to filter entries before generation.
           @filter_block = nil
           @access_remote = true
-          # Bind generator-specific options to @gen_options (Category C: set_handler after object creation)
-          Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
-            options.set_handler(opt[:name], object: @gen_options, method: opt[:name])
-          end
-
+          # Values set through `on_set` callbacks are used below
           options.parse_options!
+          @option_skip_types = options.get_option(:skip_types)
+          @option_previews_folder = options.get_option(:previews_folder)
+          @option_folder_reset_cache = options.get_option(:folder_reset_cache)
+          # Modified during scan
+          @option_skip_folders = options.get_option(:skip_folders).dup
+          @option_overwrite = options.get_option(:overwrite)
+          # Tell which tool we will use for office docs
+          Aspera::Preview::Utils.office_tool = @gen_options.office_conversion
           Api::Node.api_options[:cache] = !@option_folder_reset_cache.eql?(:header)
           # Start from the full supported format list, then remove any skipped format.
           @preview_formats_to_generate = Aspera::Preview::Generator::PREVIEW_FORMATS.clone
           skip = options.get_option(:skip_format)
           @preview_formats_to_generate.delete(skip) if skip
+          # Created by `tools_cleanup`, only for commands that use it
           @tmp_folder = File.join(TempFileManager.instance.global_temp, "#{TMP_DIR_PREFIX}.#{SecureRandom.uuid}")
-          FileUtils.mkdir_p(@tmp_folder)
-          Log.log.debug { "tmpdir: #{@tmp_folder}" }
         end
 
         # Process legacy transfer events and trigger preview generation for completed downloads.
@@ -108,7 +116,7 @@ module Aspera
           events_filter['iteration_token'] = iteration_persistency.data.first unless iteration_persistency.nil?
           begin
             events = @api_node.read('events', events_filter)
-          rescue RestCallError => e
+          rescue Rest::CallError => e
             if e.message.include?('Invalid iteration_token')
               Log.log.warn { "Retrying without iteration token: #{e}" }
               events_filter.delete('iteration_token')
@@ -360,7 +368,7 @@ module Aspera
             Log.log.debug { "processing entry #{entry_path_with_slash}" } if @periodic.trigger?
             entry_path_with_slash = "#{entry_path_with_slash}/" unless entry_path_with_slash.end_with?('/')
             if !top_path.nil? && !top_path.start_with?(entry_path_with_slash) && !entry_path_with_slash.start_with?(top_path)
-              Log.log.debug { "#{entry['path']} folder (skip start)".bg_red }
+              Log.log.debug { "#{entry['path']} folder (skip start)".bg(:red) }
               next
             end
             Log.log.debug { "item:#{entry}" }
@@ -376,7 +384,7 @@ module Aspera
                 Log.log.debug('Ignoring link.')
               when 'folder'
                 if @option_skip_folders.include?(entry['path'])
-                  Log.log.debug { "#{entry['path']} folder (skip list)".bg_red }
+                  Log.log.debug { "#{entry['path']} folder (skip list)".bg(:red) }
                 else
                   Log.log.debug { "#{entry['path']} folder".green }
                   # get folder content
@@ -402,14 +410,16 @@ module Aspera
 
         # scan, events and trevents connect to the Node API (setup: :setup_node_api).
         # `check`, `test` and `show` work without Node API authentication.
-        command :scan,     description: 'Scan a file or folder and generate previews',      setup: :setup_node_api, arguments: [{name: :path, type: String, description: 'File or folder from which to start scanning', mandatory: false, default: '/'}]
-        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 :show,     description: 'Generate and display preview of a source file', arguments: [{name: :source_file, type: String, description: 'Local file to preview'}]
+        command :scan,     description: 'Scan a file or folder and generate previews', setup: :setup_node_api,
+          arguments: [{name: :path, description: 'File or folder from which to start scanning', mandatory: false, default: '/'}]
+        command :events,   description: 'Process file events and generate previews',        setup: :setup_node_api, action: ->(**) { run_event_loop(:events) }
+        command :trevents, description: 'Process transfer events and generate previews',    setup: :setup_node_api, action: ->(**) { run_event_loop(:trevents) }
+        command :check,    description: 'Check required tools are installed', action: ->(**) { tools_cleanup { Result::Status.new('Tools validated') } }
+        command :show,     description: 'Generate and display preview of a source file',
+          arguments: [{name: :source_file, description: 'Local file to preview'}]
         command :test,     description: 'Test preview generation for a source file',
           arguments: [
-            {name: :source_file, type: String, description: 'Local file to preview'},
+            {name: :source_file, description: 'Local file to preview'},
             {name: :format, description: 'Preview output format', allowed: Aspera::Preview::Generator::PREVIEW_FORMATS, mandatory: false, default: :png}
           ]
 
@@ -428,7 +438,7 @@ module Aspera
           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.eql?(REMOTE_ACCESS) && @access_key_self['storage']['type'].eql?('local')
+          option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.eql?(REMOTE_ACCESS) && @access_key_self['storage']&.fetch('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 ?
@@ -461,71 +471,49 @@ module Aspera
         # --- handlers ---
 
         def action_scan(path:, **)
-          check_tools_and_mimemagic
-          apifid =
-            if (selector = Parser.percent_selector(path))
-              Aspera.assert_values(selector[:field], ['id'], type: BadArgument) { 'file id' }
-              Api::NodeFileId.new(@api_node, selector[:value].to_s.empty? ? @access_key_self['root_file_id'] : selector[:value])
-            else
-              @api_node.resolve_api_fid(@access_key_self['root_file_id'], path)
-            end
-          @filter_block = Base.file_matcher(options.get_option(:filter))
-          scan_folder_files(@api_node.read("files/#{apifid.file_id}"))
-          Result::Status.new('scan finished')
-        ensure
-          cleanup_tmp_folder
-        end
-
-        def action_events(**)
-          check_tools_and_mimemagic
-          run_event_loop(:events, filter: options.get_option(:filter))
-        ensure
-          cleanup_tmp_folder
-        end
-
-        def action_trevents(**)
-          check_tools_and_mimemagic
-          run_event_loop(:trevents, filter: options.get_option(:filter))
-        ensure
-          cleanup_tmp_folder
+          tools_cleanup do
+            apifid =
+              if (selector = Parser.percent_selector(path))
+                Aspera.assert_values(selector[:field], ['id'], type: BadArgument) { 'file id' }
+                Api::NodeFileId.new(@api_node, selector[:value].to_s.empty? ? @access_key_self['root_file_id'] : selector[:value])
+              else
+                @api_node.resolve_api_fid(@access_key_self['root_file_id'], path)
+              end
+            @filter_block = Base.file_matcher(options.get_option(:filter))
+            scan_folder_files(@api_node.read("files/#{apifid.file_id}"))
+            Result::Status.new('scan finished')
+          end
         end
 
-        def action_check
-          check_tools_and_mimemagic
-          Result::Status.new('Tools validated')
-        ensure
-          cleanup_tmp_folder
-        end
+        # Status message for generation
+        MSG_GEN_TITLE = 'Generated: '
 
         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
+          tools_cleanup do
+            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("#{MSG_GEN_TITLE}#{generated_file_path}")
+          end
         end
 
         def action_show(source_file:, **)
-          check_tools_and_mimemagic
-          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}")
+          status = action_test(source_file: source_file, format: :png)
+          formatter.display_status(status.data)
+          generated_file_path = status.data.delete_prefix(MSG_GEN_TITLE)
           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)
+        # Check tools and set option flag.
+        # Create the temporary folder for the command, and clean it up after.
+        def tools_cleanup
+          Aspera::Preview::FileTypes.instance.detect_mime = options.get_option(:detect_mime, mandatory: true)
           Aspera::Preview::Utils.check_tools(@option_skip_types)
-        end
-
-        # Clean up the temporary folder after each command.
-        def cleanup_tmp_folder
+          FileUtils.mkdir_p(@tmp_folder)
+          Log.log.debug { "tmpdir: #{@tmp_folder}" }
+          yield
+        ensure
           Log.log.debug { "cleaning up temp folder #{@tmp_folder}" }
           FileUtils.rm_rf(@tmp_folder)
         end
@@ -533,23 +521,26 @@ module Aspera
         # Shared event-loop body for :events and :trevents.
         # @param command [:events, :trevents]
         # @param filter  [String, Regexp, Proc, nil] optional filter expression
-        def run_event_loop(command, filter: nil)
-          @filter_block = Base.file_matcher(filter)
-          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)
+        def run_event_loop(command)
+          tools_cleanup do
+            filter = options.get_option(:filter)
+            @filter_block = Base.file_matcher(filter)
+            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
-          send(:"process_#{command}", iteration_persistency)
-          Result::Status.new("#{command} finished")
         end
       end
     end

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

@@ -72,7 +72,7 @@ module Aspera
               username: options.get_option(:username, mandatory: true),
               password: options.get_option(:password, mandatory: true)
             },
-            test_args:    'files browse /'
+            test_args:    'browse /'
           }
         end
 
@@ -81,7 +81,6 @@ module Aspera
           @connection_type = :ssh
           @ascmd_executor = nil
           @server_transfer_spec = nil
-          options.parse_options!
           @ssh_opts = options.get_option(:ssh_options).symbolize_keys
         end
 
@@ -160,7 +159,7 @@ module Aspera
         end
 
         Sync::Operations::DIRECTIONS.each do |dir|
-          define_method(:"action_sync_#{dir}") { |path:, sync_info: {}, **| run_sync_transfer(dir, path: path, sync_info: sync_info) { @server_transfer_spec } }
+          define_action_method([:sync, dir]) { |path:, sync_info: {}, **| run_sync_transfer(dir, path: path, sync_info: sync_info) { server_transfer_spec } }
         end
 
         # --- DSL ---
@@ -169,22 +168,18 @@ module Aspera
         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))
+        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))
+          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'
@@ -192,8 +187,7 @@ module Aspera
           Sync::Operations::DIRECTIONS.each do |dir|
             command dir, description: "#{dir.capitalize}-sync with server", 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)
+          sync_admin_commands :admin
         end
 
         commands_under :health do
@@ -201,43 +195,76 @@ module Aspera
         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
+        # Arguments follow AsCmd::OPS_ARGS: one path per operation, or source and destination
+        PATHS_ARGS = [{name: :paths, multiple: true}].freeze
+        private_constant :PATHS_ARGS
 
-        command :ls,     description: 'List files',            condition: :ascmd_available?, aliases: [:browse], arguments: ASCMD_ARGS
-        command :rm,     description: 'Delete files',          condition: :ascmd_available?, aliases: [:delete], arguments: ASCMD_ARGS
-        command :mv,     description: 'Rename/move files',     condition: :ascmd_available?, aliases: [:rename], arguments: ASCMD_ARGS
-        command :cp,     description: 'Copy files',            condition: :ascmd_available?,                     arguments: ASCMD_ARGS
-        command :mkdir,  description: 'Create directory',      condition: :ascmd_available?,                     arguments: ASCMD_ARGS
-        command :df,     description: 'Show disk usage',       condition: :ascmd_available?,                     arguments: ASCMD_ARGS
-        command :du,     description: 'Show file sizes',       condition: :ascmd_available?,                     arguments: ASCMD_ARGS
-        command :md5sum, description: 'Compute MD5 checksums', condition: :ascmd_available?,                     arguments: ASCMD_ARGS
-        command :info,   description: 'Show server system information',   condition: :ascmd_available?,                     arguments: ASCMD_ARGS
+        command(
+          :ls, description: 'List files', condition: :ascmd_available?, aliases: [:browse], arguments: PATHS_ARGS,
+          action: lambda do |paths:, **|
+            execute_ascmd(:ls, paths) do |result|
+              Result::ObjectList.new(result.map(&:stringify_keys), fields: %w[zmode zuid zgid size mtime name])
+            end
+          end
+        )
+        command :rm,     description: 'Delete files', condition: :ascmd_available?, aliases: [:delete], arguments: PATHS_ARGS
+        command :mv,     description: 'Rename/move files: source destination pairs, or sources with --to-folder', condition: :ascmd_available?, aliases: [:rename], arguments: PATHS_ARGS
+        command :cp,     description: 'Copy files: source destination pairs, or sources with --to-folder',        condition: :ascmd_available?,                     arguments: PATHS_ARGS
+        command :mkdir,  description: 'Create directory', condition: :ascmd_available?, arguments: PATHS_ARGS
+        command(
+          :df, description: 'Show disk usage', condition: :ascmd_available?,
+          action: lambda do |**|
+            execute_ascmd(:df, []) do |result|
+              Result::ObjectList.new(result.map(&:stringify_keys))
+            end
+          end
+        )
+        command :du,     description: 'Show file sizes',       condition: :ascmd_available?,                     arguments: PATHS_ARGS
+        command :md5sum, description: 'Compute MD5 checksums', condition: :ascmd_available?,                     arguments: PATHS_ARGS
+        command :info,   description: 'Show server system information', condition: :ascmd_available?,
+          action: ->(**) { execute_ascmd(:info, []) { |r| Result::SingleObject.new(r.stringify_keys) } }
 
         # 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 }
+        %i[rm mkdir].each do |op|
+          define_action_method([op]) do |paths:, **|
+            execute_ascmd(op, paths) { Result::Success.new }
+          end
+        end
+
+        %i[mv cp].each do |op|
+          define_action_method([op]) do |paths:, **|
+            execute_ascmd(op, source_destination_pairs(paths)) { Result::Success.new }
           end
         end
 
-        %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) }
+        %i[du md5sum].each do |op|
+          define_action_method([op]) do |paths:, **|
+            execute_ascmd(op, paths) { |r| Result::SingleObject.new(r.stringify_keys) }
           end
         end
 
         # --- conditions ---
 
         def ascmd_available?
-          !@ascmd_executor.nil?
+          !ascmd_executor.nil?
+        end
+
+        # --- server access ---
+
+        # @return [Hash] base transfer spec, built from CLI options on first use
+        def server_transfer_spec
+          build_server_access if @server_transfer_spec.nil?
+          @server_transfer_spec
         end
 
-        # --- setup ---
+        # @return [LocalExecutor, Ssh, nil] ascmd executor, nil with WSS (ascmd not available)
+        def ascmd_executor
+          build_server_access if @server_transfer_spec.nil?
+          @ascmd_executor
+        end
 
         # Build the transfer spec and ascmd executor from CLI options.
-        # Stores results in instance variables; returns empty context hash.
-        def setup_server(**)
+        def build_server_access
           @server_transfer_spec = options_to_base_transfer_spec
           @ascmd_executor = case @connection_type
           when :local then LocalExecutor.new
@@ -245,14 +272,13 @@ module Aspera
           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
-          {}
         end
 
         # --- health ---
 
-        def action_health_transfer
+        def action_health_transfer(**)
           nagios = Nagios.new
-          probe_ts = @server_transfer_spec.merge({
+          probe_ts = server_transfer_spec.merge({
             'direction'     => 'send',
             'cookie'        => 'aspera.sync', # hide in console
             'resume_policy' => 'none',
@@ -269,24 +295,23 @@ module Aspera
 
         # --- 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
+        private
 
-        def action_df(command_arguments:, **)
-          execute_ascmd(:df, command_arguments) do |result|
-            Result::ObjectList.new(result.map(&:stringify_keys))
-          end
+        # AsCmd `cp` and `mv` take source and destination pairs.
+        # With option `to_folder`, paths are only sources, copied or moved into that folder.
+        # @param paths [Array<String>] command line arguments
+        # @return [Array<String>] flat list of source and destination pairs
+        def source_destination_pairs(paths)
+          to_folder = options.get_option(:to_folder)
+          return paths.flat_map { |source| [source, "#{to_folder.chomp('/')}/#{File.basename(source)}"] } unless to_folder.nil?
+          Aspera.assert(paths.length.even?, type: Cli::BadArgument) { 'expecting pairs: <source> <destination> ..., or sources with option to_folder' }
+          paths
         end
 
-        private
-
-        def execute_ascmd(op, command_arguments)
-          ascmd = AsCmd.new(@ascmd_executor)
+        def execute_ascmd(op, arguments)
+          ascmd = AsCmd.new(ascmd_executor)
           begin
-            result = ascmd.execute_single(op, command_arguments)
+            result = ascmd.execute_single(op, arguments)
             yield(result)
           rescue AsCmd::Error => e
             raise Cli::BadArgument, e.extended_message