aspera-cli 4.27.0 → 4.27.2

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

@@ -35,7 +35,7 @@ module Aspera
               }
             rescue StandardError => e
               error = e
-              Log.log.debug{"detect error: #{e}"}
+              Log.log.debug { "detect error: #{e}" }
             end
             raise error if error
             return
@@ -57,7 +57,7 @@ module Aspera
         end
 
         option :result,      description: "Specify result value as: 'work_step:parameter'"
-        option :synchronous, description: 'Wait for completion', allowed: Allowed::TYPES_BOOLEAN, default: false
+        option :synchronous, description: 'Wait for completion', allowed: Type::BOOLEAN, default: false
         option :ret_style,   description: 'How return type is requested in api', allowed: %i[header arg ext], default: :arg
         option :auth_style,  description: 'Authentication type', allowed: %i[arg_pass head_basic apikey], default: :head_basic
 
@@ -104,65 +104,65 @@ module Aspera
         # --- DSL ---
 
         command :health,     description: 'Check Orchestrator API health',               setup: :setup_api
-        command :info,       description: 'Ping the remote Orchestrator instance',       setup: :setup_api, action: ->{Result::SingleObject.new(call_ao('remote_node_ping', format: 'xml', xml_arrays: false))}
-        command :processes,  description: 'Show Orchestrator background process status', setup: :setup_api, action: ->{Result::ObjectList.new(call_ao('processes_status', format: 'xml')['process'])}
-        command :monitors,   description: 'Show Orchestrator monitor snapshot',          setup: :setup_api, action: ->{Result::SingleObject.new(call_ao('monitor_snapshot')['monitor'])}
-        command :plugins,    description: 'Show Orchestrator plugin versions',           setup: :setup_api, action: ->{Result::ObjectList.new(call_ao('plugin_version')['Plugin'])}
+        command :info,       description: 'Ping the remote Orchestrator instance',       setup: :setup_api, action: -> { Result::SingleObject.new(call_ao('remote_node_ping', format: 'xml', xml_arrays: false)) }
+        command :processes,  description: 'Show Orchestrator background process status', setup: :setup_api, action: -> { Result::ObjectList.new(call_ao('processes_status', format: 'xml')['process']) }
+        command :monitors,   description: 'Show Orchestrator monitor snapshot',          setup: :setup_api, action: -> { Result::SingleObject.new(call_ao('monitor_snapshot')['monitor']) }
+        command :plugins,    description: 'Show Orchestrator plugin versions',           setup: :setup_api, action: -> { Result::ObjectList.new(call_ao('plugin_version')['Plugin']) }
         command :workflows,  description: 'Manage workflows',   setup: :setup_api
         command :workorders, description: 'Manage work orders', setup: :setup_api
         command :workstep,   description: 'Manage work steps',  setup: :setup_api
 
-        commands_under(:workflows) do
+        commands_under :workflows do
           command(:list, description: 'List all workflows', action: lambda do
             Result::ObjectList.new(
               call_ao('workflows_list')['workflows']['workflow'],
               fields: %w[id portable_id name published_status published_revision_id latest_revision_id last_modification]
             )
           end)
-          command :status,     description: 'Check running status of workflow(s)',
+          command :status,     description: 'Check running status of workflows',
             arguments: [{name: :wf_id, type: :identifier}],
-            action: ->(wf_id:, **){Result::ObjectList.new(call_ao(wf_id.eql?(SpecialValues::ALL) ? 'workflows_status' : "workflows_status/#{wf_id}")['workflows']['workflow'])}
+            action: ->(wf_id:, **) { Result::ObjectList.new(call_ao(wf_id.eql?(SpecialValues::ALL) ? 'workflows_status' : "workflows_status/#{wf_id}")['workflows']['workflow']) }
           command :inputs,     description: 'Fetch input specification for a workflow',
             arguments: [{name: :wf_id, type: :identifier}],
-            action: ->(wf_id:, **){Result::SingleObject.new(call_ao("workflow_inputs_spec/#{wf_id}")['workflow_inputs_spec'])}
+            action: ->(wf_id:, **) { Result::SingleObject.new(call_ao("workflow_inputs_spec/#{wf_id}")['workflow_inputs_spec']) }
           command :details,    description: 'Check detailed running status of a workflow',
             arguments: [{name: :wf_id, type: :identifier}],
-            action: ->(wf_id:, **){Result::ObjectList.new(call_ao("workflow_details/#{wf_id}")['workflows']['workflow']['statuses'])}
+            action: ->(wf_id:, **) { Result::ObjectList.new(call_ao("workflow_details/#{wf_id}")['workflows']['workflow']['statuses']) }
           command :start,      description: 'Initiate a work order (sync or async)',
             arguments: [{name: :wf_id, type: :identifier}, {name: :external_parameters, type: Hash, mandatory: false, default: {}}]
           command :export,     description: 'Export a workflow',
             arguments: [{name: :wf_id, type: :identifier}],
-            action: ->(wf_id:, **){Result::Text.new(call_ao("export_workflow/#{wf_id}", format: nil, http: true).body)}
+            action: ->(wf_id:, **) { Result::Text.new(call_ao("export_workflow/#{wf_id}", format: nil, http: true).body) }
           command :workorders, description: 'Fetch all work orders from a workflow',
             arguments: [{name: :wf_id, type: :identifier}],
-            action: ->(wf_id:, **){Result::ObjectList.new(call_ao("work_orders_list/#{wf_id}")['work_orders'])}
+            action: ->(wf_id:, **) { Result::ObjectList.new(call_ao("work_orders_list/#{wf_id}")['work_orders']) }
           command :outputs,    description: 'Fetch output specification for a workflow',
             arguments: [{name: :wf_id, type: :identifier}],
-            action: ->(wf_id:, **){Result::ObjectList.new(call_ao("workflow_outputs_spec/#{wf_id}")['workflow_outputs_spec']['output'])}
+            action: ->(wf_id:, **) { Result::ObjectList.new(call_ao("workflow_outputs_spec/#{wf_id}")['workflow_outputs_spec']['output']) }
         end
 
-        commands_under(:workorders) do
+        commands_under :workorders do
           command :status, description: 'Check the status of a work order',
             arguments: [{name: :wo_id, type: :identifier}],
-            action: ->(wo_id:, **){Result::SingleObject.new(call_ao("work_order_status/#{wo_id}")['work_order'])}
+            action: ->(wo_id:, **) { Result::SingleObject.new(call_ao("work_order_status/#{wo_id}")['work_order']) }
           command :cancel, description: 'Cancel a work order',
             arguments: [{name: :wo_id, type: :identifier}],
-            action: ->(wo_id:, **){Result::SingleObject.new(call_ao("work_order_cancel/#{wo_id}")['work_order'])}
+            action: ->(wo_id:, **) { Result::SingleObject.new(call_ao("work_order_cancel/#{wo_id}")['work_order']) }
           command :reset,  description: 'Reset a work order',
             arguments: [{name: :wo_id, type: :identifier}],
-            action: ->(wo_id:, **){Result::SingleObject.new(call_ao("work_order_reset/#{wo_id}")['work_order'])}
+            action: ->(wo_id:, **) { Result::SingleObject.new(call_ao("work_order_reset/#{wo_id}")['work_order']) }
           command :output, description: 'Fetch output of a work order',
             arguments: [{name: :wo_id, type: :identifier}],
-            action: ->(wo_id:, **){Result::ObjectList.new(call_ao("work_order_output/#{wo_id}", format: 'xml')['variable'])}
+            action: ->(wo_id:, **) { Result::ObjectList.new(call_ao("work_order_output/#{wo_id}", format: 'xml')['variable']) }
         end
 
-        commands_under(:workstep) do
+        commands_under :workstep do
           command :status, description: 'Check the status of a work step',
             arguments: [{name: :ws_id, type: :identifier}],
-            action: ->(ws_id:, **){Result::SingleObject.new(call_ao("work_step_status/#{ws_id}"))}
+            action: ->(ws_id:, **) { Result::SingleObject.new(call_ao("work_step_status/#{ws_id}")) }
           command :cancel, description: 'Cancel a work step',
             arguments: [{name: :ws_id, type: :identifier}],
-            action: ->(ws_id:, **){Result::SingleObject.new(call_ao("work_step_cancel/#{ws_id}"))}
+            action: ->(ws_id:, **) { Result::SingleObject.new(call_ao("work_step_cancel/#{ws_id}")) }
         end
 
         # --- setup ---
@@ -221,7 +221,7 @@ module Aspera
           result_location = options.get_option(:result)
           unless result_location.nil?
             fields = result_location.split(':')
-            Aspera.assert(fields.length == 2, type: Cli::BadArgument){"Expects: work_step:result_name : #{result_location}"}
+            Aspera.assert(fields.length == 2, type: Cli::BadArgument) { "Expects: work_step:result_name : #{result_location}" }
             call_params['explicit_output_step'] = fields[0]
             call_params['explicit_output_variable'] = fields[1]
             # implicitly, call is synchronous

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

@@ -52,15 +52,14 @@ module Aspera
         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 :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: Allowed::TYPES_STRING_ARRAY, handler: :option_skip_folders
+        option :skip_folders,       description: 'List of folder to skip',                                                                                                        allowed: Type::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 :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 :root_url,           description: "How to read and write files on storage (<empty>, #{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})", default: ''
+        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)
@@ -93,7 +92,7 @@ module Aspera
           @preview_formats_to_generate.delete(skip) if skip
           @tmp_folder = File.join(TempFileManager.instance.global_temp, "#{TMP_DIR_PREFIX}.#{SecureRandom.uuid}")
           FileUtils.mkdir_p(@tmp_folder)
-          Log.log.debug{"tmpdir: #{@tmp_folder}"}
+          Log.log.debug { "tmpdir: #{@tmp_folder}" }
         end
 
         # Process legacy transfer events and trigger preview generation for completed downloads.
@@ -111,7 +110,7 @@ module Aspera
             events = @api_node.read('events', events_filter)
           rescue RestCallError => e
             if e.message.include?('Invalid iteration_token')
-              Log.log.warn{"Retrying without iteration token: #{e}"}
+              Log.log.warn { "Retrying without iteration token: #{e}" }
               events_filter.delete('iteration_token')
               retry
             end
@@ -132,7 +131,7 @@ module Aspera
             end
             # Periodically log progress and persist the latest processed event.
             next unless @periodic.trigger? || event.equal?(events.last)
-            Log.log.debug{"Processed event #{event['id']}"}
+            Log.log.debug { "Processed event #{event['id']}" }
             # Save a checkpoint to avoid replaying the full batch after a failure.
             if !iteration_persistency.nil?
               iteration_persistency.data[0] = event['id'].to_s
@@ -161,7 +160,7 @@ module Aspera
             if event.dig('data', 'type').eql?('file')
               file_entry = @api_node.read("files/#{event['data']['id']}") rescue nil
               if !file_entry.nil? &&
-                  @option_skip_folders.none?{ |d| file_entry['path'].start_with?(d)}
+                  @option_skip_folders.none? { |d| file_entry['path'].start_with?(d) }
                 file_entry['parent_file_id'] = event['data']['parent_file_id']
                 Log.log.error('TODO'.red) if event['types'].include?('file.deleted')
                 generate_preview(file_entry) if event['types'].include?('file.deleted')
@@ -169,7 +168,7 @@ module Aspera
             end
             # Periodically log progress and persist the latest processed event.
             next unless @periodic.trigger? || event.equal?(events.last)
-            Log.log.debug{"Processing event #{event['id']}"}
+            Log.log.debug { "Processing event #{event['id']}" }
             # Save a checkpoint to avoid replaying the full batch after a failure.
             if !iteration_persistency.nil?
               iteration_persistency.data[0] = event['id'].to_s
@@ -204,7 +203,11 @@ module Aspera
         # @param entry [Hash] file entry containing at least the relative path
         # @return [String] local directory where previews for this entry are stored
         def get_infos_local(gen_infos, entry)
-          local_original_filepath = File.join(@local_storage_root, entry['path'])
+          # Resolve to a real path and ensure it stays within the storage root (prevents path traversal via API response)
+          candidate = File.expand_path(File.join(@local_storage_root, entry['path']))
+          resolved_root = File.realpath(@local_storage_root)
+          Aspera.assert(candidate.start_with?("#{resolved_root}/")) { 'Preview entry path traversal attempt detected' }
+          local_original_filepath = candidate
           original_mtime = File.mtime(local_original_filepath)
           # Output directory for previews generated from the local source file.
           local_entry_preview_dir = File.join(@local_preview_folder, entry_preview_folder_name(entry))
@@ -316,14 +319,14 @@ module Aspera
             #  download original file to temp folder
             do_transfer(Transfer::Spec::DIRECTION_RECEIVE, entry['parent_file_id'], entry['name'], @tmp_folder)
           end
-          Log.log.debug{"source: #{entry['id']}: #{entry['path']}"}
+          Log.log.debug { "source: #{entry['id']}: #{entry['path']}" }
           gen_infos.each do |gen_info|
             gen_info[:generator].generate
           rescue => e
-            Log.log.error{"Ignoring: #{e.class} #{e.message}"}
+            Log.log.error { "Ignoring: #{e.class} #{e.message}" }
             Log.log.debug(e.backtrace.join("\n").red)
             # in case of any error, place a standard error image
-            FileUtils.cp(gen_info[:generator].error_asset, @destination_file_path)
+            FileUtils.cp(gen_info[:generator].error_asset, gen_info[:dst])
           end
           if @access_remote
             # upload
@@ -335,7 +338,7 @@ module Aspera
           # force read file updated previews
           @api_node.read("files/#{entry['id']}") if @option_folder_reset_cache.eql?(:read)
         rescue StandardError => e
-          Log.log.error{"Ignore: #{e.message}"}
+          Log.log.error { "Ignore: #{e.message}" }
           Log.log.debug(e.backtrace.join("\n").red)
         end
 
@@ -347,20 +350,20 @@ module Aspera
             # canonical path: start with / and ends with /
             top_path = "/#{top_path.split('/').reject(&:empty?).join('/')}/"
           end
-          Log.log.debug{"scan: #{top_entry} : #{top_path}".green}
+          Log.log.debug { "scan: #{top_entry} : #{top_path}".green }
           # don't use recursive call, use list instead
           entries_to_process = [top_entry]
           until entries_to_process.empty?
             entry = entries_to_process.shift
             # process this entry only if it is within the top_path
             entry_path_with_slash = entry['path']
-            Log.log.debug{"processing entry #{entry_path_with_slash}"} if @periodic.trigger?
+            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}"}
+            Log.log.debug { "item:#{entry}" }
             begin
               case entry['type']
               when 'file'
@@ -373,9 +376,9 @@ 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}
+                  Log.log.debug { "#{entry['path']} folder".green }
                   # get folder content
                   folder_entries = @api_node.read_folder_content(entry['id'])
                   # process all items in current folder
@@ -387,26 +390,28 @@ module Aspera
                   end
                 end
               else
-                Log.log.warn{"unknown entry type: #{entry['type']}"}
+                Log.log.warn { "unknown entry type: #{entry['type']}" }
               end
             rescue StandardError => e
-              Log.log.warn{"An error occurred: #{e}, ignoring"}
+              Log.log.warn { "An error occurred: #{e}, ignoring" }
             end
           end
         end
 
         # --- 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
+        # 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 :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}]
+          arguments: [
+            {name: :source_file, type: String, description: 'Local file to preview'},
+            {name: :format, description: 'Preview output format', allowed: Aspera::Preview::Generator::PREVIEW_FORMATS, mandatory: false, default: :png}
+          ]
 
         # --- setup ---
 
@@ -420,12 +425,12 @@ module Aspera
           # 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']}"}
+          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')
+          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')
           @access_remote = !UriReader.file?(option_root_url)
-          Log.log.debug{"remote: #{@access_remote}"}
+          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
@@ -436,16 +441,16 @@ module Aspera
           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."}
+            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."}
+            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}"}
+            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']}"}
+              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
@@ -455,38 +460,32 @@ module Aspera
 
         # --- handlers ---
 
-        def action_scan
+        def action_scan(path:, **)
           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' => '/'
-              }
+          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.read("files/#{scan_id}")
+              @api_node.resolve_api_fid(@access_key_self['root_file_id'], path)
             end
-          @filter_block = Api::Node.file_matcher_from_argument(options)
-          scan_folder_files(folder_info, scan_path)
+          @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
+        def action_events(**)
           check_tools_and_mimemagic
-          run_event_loop(:events)
+          run_event_loop(:events, filter: options.get_option(:filter))
         ensure
           cleanup_tmp_folder
         end
 
-        def action_trevents
+        def action_trevents(**)
           check_tools_and_mimemagic
-          run_event_loop(:trevents)
+          run_event_loop(:trevents, filter: options.get_option(:filter))
         ensure
           cleanup_tmp_folder
         end
@@ -509,12 +508,9 @@ module Aspera
 
         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
@@ -530,14 +526,15 @@ module Aspera
 
         # Clean up the temporary folder after each command.
         def cleanup_tmp_folder
-          Log.log.debug{"cleaning up temp folder #{@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)
+        # @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(

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

@@ -47,7 +47,7 @@ module Aspera
             error = nil
             urls.each do |base_url|
               server_uri = URI.parse(base_url)
-              Log.log.debug{"URI=#{server_uri}, host=#{server_uri.hostname}, port=#{server_uri.port}, scheme=#{server_uri.scheme}"}
+              Log.log.debug { "URI=#{server_uri}, host=#{server_uri.hostname}, port=#{server_uri.port}, scheme=#{server_uri.scheme}" }
               next unless server_uri.scheme.eql?(SSH_SCHEME)
               socket = TCPSocket.new(server_uri.hostname, server_uri.port)
               socket.puts('SSH-2.0-Ascli_0.0')
@@ -55,7 +55,7 @@ module Aspera
               return {version: version.gsub(/^SSH-2.0-/, ''), url: base_url} if version.match?(/^SSH-2.0-/)
             rescue StandardError => e
               error = e
-              Log.log.debug{"detect error: #{e}"}
+              Log.log.debug { "detect error: #{e}" }
             end
             raise error if error
             return
@@ -91,10 +91,10 @@ module Aspera
           url = options.get_option(:url, mandatory: true)
           server_transfer_spec = {}
           server_uri = URI.parse(url)
-          Log.log.debug{"URI=#{server_uri}, host=#{server_uri.hostname}, port=#{server_uri.port}, scheme=#{server_uri.scheme}"}
+          Log.log.debug { "URI=#{server_uri}, host=#{server_uri.hostname}, port=#{server_uri.port}, scheme=#{server_uri.scheme}" }
           server_transfer_spec['remote_host'] = server_uri.hostname
           unless URI_SCHEMES.include?(server_uri.scheme)
-            Log.log.warn{"Scheme [#{server_uri.scheme}] not supported in #{url}, use one of: #{URI_SCHEMES.join(', ')}. Defaulting to #{SSH_SCHEME}."}
+            Log.log.warn { "Scheme [#{server_uri.scheme}] not supported in #{url}, use one of: #{URI_SCHEMES.join(', ')}. Defaulting to #{SSH_SCHEME}." }
             server_uri.scheme = SSH_SCHEME
           end
           if server_uri.scheme.eql?(LOCAL_SCHEME)
@@ -115,13 +115,13 @@ module Aspera
             Log.log.warn('URL scheme is https but no token was provided in transfer spec.')
             Log.log.warn("If you want to access the server, not using WSS for session, then use a URL with scheme \"#{SSH_SCHEME}\" and proper SSH port")
             assumed_url = "#{SSH_SCHEME}://#{server_transfer_spec['remote_host']}:#{Transfer::Spec::SSH_PORT}"
-            Log.log.warn{"Assuming proper URL is: #{assumed_url}"}
+            Log.log.warn { "Assuming proper URL is: #{assumed_url}" }
             server_uri = URI.parse(assumed_url)
           end
           # Scheme is SSH
           if options.get_option(:username).nil?
             options.set_option(:username, Transfer::Spec::ACCESS_KEY_TRANSFER_USER)
-            Log.log.info{"No username provided: Assuming default transfer user: #{Transfer::Spec::ACCESS_KEY_TRANSFER_USER}"}
+            Log.log.info { "No username provided: Assuming default transfer user: #{Transfer::Spec::ACCESS_KEY_TRANSFER_USER}" }
           end
           server_transfer_spec['remote_user'] = options.get_option(:username, mandatory: true)
           if !server_uri.port.nil?
@@ -137,14 +137,14 @@ module Aspera
           end
           ssh_key_list = options.get_option(:ssh_keys)
           if !ssh_key_list.nil?
-            Aspera.assert_array_all(ssh_key_list, String){'ssh_keys'}
-            ssh_key_list.map!{ |p| File.expand_path(p)}
-            Log.log.debug{"SSH keys=#{ssh_key_list}"}
+            Aspera.assert_array_all(ssh_key_list, String) { 'ssh_keys' }
+            ssh_key_list.map! { |p| File.expand_path(p) }
+            Log.dump(:ssh_keys, ssh_key_list)
             if !ssh_key_list.empty?
               @ssh_opts[:keys] = ssh_key_list
               # PEM as per RFC 7468
               server_transfer_spec['ssh_private_key'] = File.read(ssh_key_list.first).strip
-              Log.log.warn{'Using only first SSH key for transfers'} unless ssh_key_list.length.eql?(1)
+              Log.log.warn { 'Using only first SSH key for transfers' } unless ssh_key_list.length.eql?(1)
               cred_set = true
             end
           end
@@ -160,12 +160,12 @@ module Aspera
         end
 
         Sync::Operations::DIRECTIONS.each do |dir|
-          define_method(:"action_sync_#{dir}"){ |**| run_sync_transfer(dir){@server_transfer_spec}}
+          define_method(:"action_sync_#{dir}") { |path:, sync_info: {}, **| run_sync_transfer(dir, path: path, sync_info: sync_info) { @server_transfer_spec } }
         end
 
         # --- DSL ---
 
-        option :ssh_keys,    description: 'SSH key path list', allowed: Allowed::TYPES_STRING_ARRAY
+        option :ssh_keys,    description: 'SSH key path list', allowed: Type::STRING_ARRAY
         option :passphrase,  description: 'SSH private key passphrase'
         option :ssh_options, description: 'SSH options', allowed: Hash
 
@@ -178,20 +178,25 @@ module Aspera
           @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(
+          :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
+        commands_under :sync do
           Sync::Operations::DIRECTIONS.each do |dir|
-            command(dir, description: "#{dir.capitalize}-sync with server", transfer_paths: :send)
+            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, %i[sync admin])
+          SyncActions.register_sync_admin_commands(self, :admin)
         end
 
-        commands_under(:health) do
+        commands_under :health do
           command :transfer, description: 'Check FASP transfer health'
         end
 
@@ -199,26 +204,26 @@ module Aspera
         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 :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
 
         # 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}
+            execute_ascmd(op, command_arguments) { 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)}
+            execute_ascmd(op, command_arguments) { |r| Result::SingleObject.new(r.stringify_keys) }
           end
         end
 
@@ -238,7 +243,7 @@ module Aspera
           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)
-          else Aspera.error_unexpected_value(@connection_type){'connection type'}
+          else Aspera.error_unexpected_value(@connection_type) { 'connection type' }
           end
           {}
         end