aspera-cli 4.26.2 → 4.27.0

data/lib/aspera/ascp/installation.rb

@@ -67,10 +67,10 @@ module Aspera
             product_name = ascp_location.delete_prefix(USE_PRODUCT_PREFIX)
             if product_name.eql?(FIRST_FOUND)
               pl = installed_products.first
-              raise "No Aspera transfer module or SDK found.\nRefer to the manual or install SDK with command:\nascli conf transferd install" if pl.nil?
+              Aspera.assert(!pl.nil?){"No Aspera transfer module or SDK found.\nRefer to the manual or install SDK with command:\nascli conf transferd install"}
             else
               pl = installed_products.find{ |i| i[:name].eql?(product_name)}
-              raise "No such product installed: #{product_name}" if pl.nil?
+              Aspera.assert(!pl.nil?){"No such product installed: #{product_name}"}
             end
             File.dirname(pl[:ascp_path])
           else
@@ -88,14 +88,14 @@ module Aspera
       # @return [Hash] with key = file name (String), and value = path to file
       def file_paths
         return SDK_FILES.to_h do |v|
-                 [v.to_s, begin
-                   path(v)
-                 rescue Errno::ENOENT => e
-                   e.message.gsub(/.*assertion failed: /, '').gsub(/\): .*/, ')')
-                 rescue => e
-                   e.message
-                 end]
-               end
+          [v.to_s, begin
+            path(v)
+          rescue Errno::ENOENT => e
+            e.message.gsub(/.*assertion failed: /, '').gsub(/\): .*/, ')')
+          rescue => e
+            e.message
+          end]
+        end
       end
 
       # TODO: if using another product than SDK, should use files from there
@@ -106,18 +106,18 @@ module Aspera
 
       # Get path of one resource file of currently activated product
       # keys and certs are generated locally... (they are well known values, arch. independent)
-      # @param k [Symbol] key of the resource file
+      # @param file_type [Symbol] key of the resource file
       # @return [String, nil] Full path to the resource file or nil if not found
-      def path(k)
+      def path(file_type)
         file_is_required = true
-        case k
+        case file_type
         when *EXE_FILES
-          file_is_required = k.eql?(:ascp)
+          file_is_required = file_type.eql?(:ascp)
           file = Products::Transferd.transferd_path
-          file = File.join(File.dirname(file), Environment.instance.exe_file(k.to_s)) unless k.eql?(:transferd)
+          file = File.join(File.dirname(file), Environment.instance.exe_file(file_type.to_s)) unless file_type.eql?(:transferd)
         when :ssh_private_dsa, :ssh_private_rsa
           # assume last 3 letters are type
-          type = k.to_s[-3..].to_sym
+          type = file_type.to_s[-3..].to_sym
           file = check_or_create_sdk_file("aspera_bypass_#{type}.pem"){DataRepository.instance.item(type)}
         when :aspera_license
           file = check_or_create_sdk_file('aspera-license'){DataRepository.instance.item(:license)}
@@ -134,22 +134,23 @@ module Aspera
             check_or_create_sdk_file('aspera_fallback_cert_private_key.pem', force: true){private_key.to_pem}
             check_or_create_sdk_file('aspera_fallback_cert.pem', force: true){cert.to_pem}
           end
-          file = k.eql?(:fallback_certificate) ? file_cert : file_key
-        else Aspera.error_unexpected_value(k)
+          file = file_type.eql?(:fallback_certificate) ? file_cert : file_key
+        else Aspera.error_unexpected_value(file_type)
         end
         return unless file_is_required || File.exist?(file)
-        Aspera.assert(File.exist?(file), type: Errno::ENOENT){"#{k} not found (#{file})"}
+        Aspera.assert(File.exist?(file), type: Errno::ENOENT){"#{file_type} not found (#{file})"}
         return file
       end
 
       # default bypass key phrase
-      # @return [String]
+      # @return [String] UUID used as bypass key phrase for SSH certificate
       def ssh_cert_uuid
         return DataRepository.instance.item(:uuid)
       end
 
       # get paths of SSH keys to use for ascp client
-      # @param types [Symbol] types to use
+      # @param types [Symbol] types to use (one of CLIENT_SSH_KEY_OPTIONS)
+      # @return [Array<String>] list of private key file paths
       def aspera_token_ssh_key_paths(types)
         Aspera.assert_values(types, CLIENT_SSH_KEY_OPTIONS)
         return case types
@@ -170,13 +171,11 @@ module Aspera
         Aspera.assert_type(exe_path, String)
         Aspera.assert_type(vers_arg, String)
         return unless File.exist?(exe_path)
-        exe_version = nil
-        cmd_out = %x("#{exe_path}" #{vers_arg})
-        raise "An error occurred when testing #{exe_path}: #{cmd_out}" unless $CHILD_STATUS == 0
+        cmd_out, _err, status = Environment.secure_execute(exe_path, vers_arg, mode: :capture, exception: false)
+        raise "An error occurred when testing #{exe_path}: #{cmd_out}" unless status.success?
         # get version from ascp, only after full extract, as windows requires DLLs (SSL/TLS/etc...)
         m = cmd_out.match(/ version ([0-9.]+)/)
-        exe_version = m[1].gsub(/\.$/, '') unless m.nil?
-        return exe_version
+        m.nil? ? nil : m[1].gsub(/\.$/, '')
       end
 
       # Extract some stings from ascp logs
@@ -234,15 +233,15 @@ module Aspera
         return ascp_data
       end
 
-      # @return the url for download of SDK archive for the given platform and version
+      # @return [String] the url for download of SDK archive for the given platform and version
       def sdk_url_for_platform(platform: nil, version: nil)
         all_locations = sdk_locations
         platform = Environment.instance.architecture if platform.nil?
         locations = all_locations.select{ |l| l['platform'].eql?(platform)}
-        raise "No SDK for platform: #{platform}, available: #{all_locations.map{ |i| i['platform']}.uniq}" if locations.empty?
+        Aspera.assert(!locations.empty?){"No SDK for platform: #{platform}, available: #{all_locations.map{ |i| i['platform']}.uniq}"}
         version = locations.max_by{ |entry| Gem::Version.new(entry['version'])}['version'] if version.nil?
         info = locations.select{ |entry| entry['version'].eql?(version)}
-        raise "No such version: #{version} for #{platform}" if info.empty?
+        Aspera.assert(!info.empty?){"No such version: #{version} for #{platform}"}
         return info.first['url']
       end
 
@@ -282,15 +281,14 @@ module Aspera
         end
       end
 
-      # Retrieves ascp binary for current system architecture from URL or file
+      # Downloads and extracts the SDK archive for the current platform into +folder+
       # @param folder  [String]      Destination folder path
       # @param url     [nil, String] URL to SDK archive, if nil: default url for version
       # @param version [nil, String] Specific version, if nil: latest version
       # @param backup  [Boolean]     If destination folder exists, then rename
       # @yieldparam entry_name [String] File path from archive
       # @yieldreturn [String, nil] Destination sub folder (end with /) or file, or nil to not extract
-      # @return [Array] name, ascp version (from execution), folder
-      def install_sdk(folder:, url: nil, version: nil, backup: true)
+      def download_sdk(folder:, url: nil, version: nil, backup: true)
         url ||= sdk_url_for_platform(version: version)
         # Rename old install
         if backup && Dir.exist?(folder) && !Dir.empty?(folder)
@@ -372,12 +370,13 @@ module Aspera
         end
       end
 
-      # Retrieve SDK either from specified URL, or specified version from standard location, or latest version
-      # @param url [nil, String] URL
-      # @param version [nil, String] URL
-      def retrieve_sdk(url: nil, version: nil)
+      # Downloads, installs and configures the SDK, returns name, version and install folder
+      # @param url     [nil, String] URL to SDK archive, if nil: default url for version
+      # @param version [nil, String] Specific version, if nil: latest version
+      # @return [Array<String>] sdk name, sdk version, install folder
+      def install_sdk(url: nil, version: nil)
         folder = Products::Transferd.sdk_directory
-        install_sdk(folder: folder, url: url, version: version)
+        download_sdk(folder: folder, url: url, version: version)
         # Ensure necessary files are there, or generate them, restrict file access on SDK executables
         SDK_FILES.each do |file_id_sym|
           file_path = path(file_id_sym)
@@ -433,7 +432,7 @@ module Aspera
 
       public
 
-      # @return the list of installed products in format of product_locations_on_current_os
+      # @return [Array<Hash>] the list of installed products in format of product_locations_on_current_os
       def installed_products
         return @found_products unless @found_products.nil?
         # :expected  M app name is taken from the manifest if present, else defaults to this value

data/lib/aspera/ascp/management.rb

@@ -12,7 +12,7 @@ module Aspera
       # https://www.ibm.com/support/pages/error-code-reference-tables
       # mgmtmess.c : as_mgmt_err_is_retryable
       # Note that the fact that an error is retry-able is not internally defined by protocol, it's client-side responsibility
-      # rubocop:disable Layout/FirstHashElementLineBreak
+      # rubocop:disable-next Layout/FirstHashElementLineBreak
       ERRORS = {
         # id   retry-able    mnemo/code                        message                                              additional info
         0  => {r: false, c: 'UNKNOWN',                     m: 'unknown',                                        a: 'unknown'},
@@ -93,7 +93,6 @@ module Aspera
         66 => {r: false, c: 'PEER_REQUIRES_FIPS',          m: 'Peer rejects cipher due to FIPS mode enabled on peer',
                                                                 a: 'Peer rejects cipher due to FIPS mode enabled on peer'}
       }.freeze
-      # rubocop:enable Layout/FirstHashElementLineBreak
       # cspell: disable
       OPERATIONS = %w[
         NOP
@@ -307,7 +306,7 @@ module Aspera
         def field_snake_to_native(name)
           field = name.delete('_')
           result = PARAMETERS.find{ |w| w.casecmp?(field)}
-          raise "No such field: #{name}" if result.nil?
+          Aspera.assert(!result.nil?){"No such field: #{name}"}
           result
         end
 

data/lib/aspera/cli/ascp_actions.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'aspera/agent/factory'
+require 'aspera/schema/registry'
+require 'aspera/schema/reader'
+
+module Aspera
+  module Cli
+    # Mixin for Config plugin: ASCP / Transferd related actions
+    module AscpActions
+      TRANSFERD_APP_NAME = 'sdk'
+
+      # Mapping from agent symbol to schema key in options.schema.yaml
+      # Agents without dedicated schema (connect, desktop) are omitted.
+      AGENT_SCHEMA_KEY = {
+        direct:    Schema::Registry::DIRECT_AGENT_OPTIONS,
+        node:      Schema::Registry::NODE_AGENT_OPTIONS,
+        httpgw:    Schema::Registry::HTTPGW_AGENT_OPTIONS,
+        transferd: Schema::Registry::TRANSFERD_AGENT_OPTIONS
+      }.freeze
+      private_constant :AGENT_SCHEMA_KEY
+
+      # Set the SDK directory, checking default and former locations
+      def set_sdk_dir
+        sdk_dir = Products::Transferd.sdk_directory rescue nil
+        if sdk_dir.nil?
+          @sdk_default_location = true
+          Log.log.debug('SDK folder is not set, checking default')
+          sdk_dir = self.class.default_app_main_folder(app_name: TRANSFERD_APP_NAME)
+          Log.log.debug{"Checking: #{sdk_dir}"}
+          if !Dir.exist?(sdk_dir)
+            Log.log.debug{"No such folder: #{sdk_dir}"}
+            former_sdk_folder = File.join(self.class.default_app_main_folder(app_name: Info::CMD_NAME), TRANSFERD_APP_NAME)
+            Log.log.debug{"Checking: #{former_sdk_folder}"}
+            sdk_dir = former_sdk_folder if Dir.exist?(former_sdk_folder)
+          end
+          Log.log.debug{"Using: #{sdk_dir}"}
+          Products::Transferd.sdk_directory = sdk_dir
+        end
+      end
+
+      # Install the transfer SDK (ascp + transferd) from a URL or using the default source.
+      # Version defaults to +Info::SDK_VERSION+; pass +LATEST+ as argument to install the latest available version.
+      # @param version [String, nil] version to install; nil means use the default SDK version
+      # @return [Result::Status] installation result message
+      def install_transfer_sdk(version: nil)
+        asked_version = version.nil? ? Info::SDK_VERSION : version
+        asked_version = nil if asked_version.eql?(SpecialValues::LATEST)
+        sdk_url = options.get_option(:sdk_url, mandatory: true)
+        sdk_url = nil if sdk_url.eql?(SpecialValues::DEF)
+        name, ver, folder = Ascp::Installation.instance.install_sdk(url: sdk_url, version: asked_version)
+        return Result::Status.new("Installed #{name} version #{ver} in #{folder}")
+      end
+
+      def action_ascp_show(**)
+        Result::Text.new(Ascp::Installation.instance.path(:ascp))
+      end
+
+      def action_ascp_info(**)
+        data = Ascp::Installation.instance.ascp_info
+        data['ts'] = transfer.user_transfer_spec
+        DataRepository::ELEMENTS.each_with_object(data){ |i, h| h[i.to_s] = DataRepository.instance.item(i)}
+        SecretHider::ADDITIONAL_KEYS_TO_HIDE.concat(DataRepository::ELEMENTS.map(&:to_s))
+        Result::SingleObject.new(data)
+      end
+
+      def action_ascp_install(version: nil, **)
+        install_transfer_sdk(version: version)
+      end
+
+      def action_ascp_spec(**)
+        builder = Schema::Documentation.new(TerminalFormatter, Transfer::Spec::SCHEMA, include_option: true, agent_columns: true).build
+        Result::ObjectList.new(builder.rows, fields: builder.columns)
+      end
+
+      def action_ascp_schema(agent_name: nil, **)
+        schema = Transfer::Spec::SCHEMA.current.merge({'$comment'=>'DO NOT EDIT, this file was generated from the YAML.'})
+        schema['properties'] = schema['properties'].select{ |_k, v| CommandLineBuilder.supported_by_agent(agent_name, v)} unless agent_name.nil?
+        schema['properties'] = schema['properties'].sort.to_h
+        Result::SingleObject.new(schema)
+      end
+
+      def action_ascp_errors(**)
+        error_data = []
+        Ascp::Management::ERRORS.each_pair do |code, prop|
+          error_data.push(code: code, mnemonic: prop[:c], retry: prop[:r], info: prop[:a])
+        end
+        Result::ObjectList.new(error_data)
+      end
+
+      def action_ascp_products_list(**)
+        Result::ObjectList.new(Ascp::Installation.instance.installed_products, fields: %w[name app_root])
+      end
+
+      def action_agents_list(**)
+        rows = Agent::Factory::ALL.map do |sym, names|
+          schema_key = AGENT_SCHEMA_KEY[sym]
+          param_names =
+            if schema_key
+              Schema::Registry.instance.reader(schema_key).current['properties']&.keys&.sort&.join(', ') || ''
+            else
+              ''
+            end
+          {
+            'name'       => sym.to_s,
+            'short'      => names[:short].to_s,
+            'parameters' => param_names
+          }
+        end.sort_by{ |r| r['name']}
+        Result::ObjectList.new(rows, fields: %w[name short parameters])
+      end
+
+      def action_agents_show(agent_name:, **)
+        names = Agent::Factory::ALL[agent_name]
+        schema_key = AGENT_SCHEMA_KEY[agent_name]
+        agent_info = {
+          'name'        => agent_name.to_s,
+          'short'       => names[:short].to_s,
+          'description' => schema_key ? Schema::Registry.instance.reader(schema_key).current['description'].to_s : '(no configurable parameters)'
+        }
+        if schema_key
+          properties = Schema::Registry.instance.reader(schema_key).current['properties'] || {}
+          rows = properties.map do |pname, pdef|
+            row = {'parameter' => pname, 'type' => pdef['type'].to_s, 'description' => pdef['description'].to_s}
+            row['required'] = (Schema::Registry.instance.reader(schema_key).current['required'] || []).include?(pname) ? 'yes' : 'no'
+            row['default']  = pdef.key?('default') ? pdef['default'].inspect : ''
+            row['enum']     = pdef.key?('enum')    ? pdef['enum'].join(', ') : ''
+            row
+          end
+          return Result::ObjectList.new(rows, fields: %w[parameter required type default enum description])
+        end
+        Result::SingleObject.new(agent_info)
+      end
+
+      def action_agents_parameters(agent_name:, **)
+        schema_key = AGENT_SCHEMA_KEY[agent_name]
+        return Result::Nothing.new if schema_key.nil?
+        properties = Schema::Registry.instance.reader(schema_key).current['properties'] || {}
+        rows = properties.map do |pname, pdef|
+          {'name' => pname, 'type' => pdef['type'].to_s, 'description' => pdef['description'].to_s}
+        end
+        Result::ObjectList.new(rows, fields: %w[name type description])
+      end
+
+      def action_transferd_install(**)
+        install_transfer_sdk
+      end
+
+      def action_transferd_list(**)
+        sdk_list = Ascp::Installation.instance.sdk_locations
+        Result::ObjectList.new(sdk_list, fields: sdk_list.first.keys - ['url'])
+      end
+    end
+  end
+end

data/lib/aspera/cli/async_transfer_store.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'aspera/log'
+require 'json'
+require 'securerandom'
+
+module Aspera
+  module Cli
+    # Persist the state of asynchronous transfers on the local file system.
+    #
+    # Each entry is a JSON document identified by a `job_id` (UUID generated by ascli).
+    # The underlying storage uses PersistencyFolder with the category prefix
+    # +CATEGORY+ so all async-transfer files are grouped together and can be
+    # garbage-collected independently.
+    #
+    # Schema of a stored entry:
+    #   job_id            [String]  UUID generated by ascli (= the store key)
+    #   agent_type        [String]  'desktop' | 'node' | 'connect' | 'transferd' | 'direct'
+    #   transfer_id       [String]  Opaque ID returned by the agent's start_transfer
+    #   agent_params      [Hash]    Agent-specific connection parameters for re-querying
+    #   status            [String]  'running' | 'completed' | 'failed' | 'cancelled'
+    #   bytes_transferred [Integer] Last known bytes transferred (0 if unknown)
+    #   started_at        [String]  ISO-8601 timestamp
+    #   ended_at          [String, nil] ISO-8601 timestamp once finished
+    #   error             [String, nil] Error message when status == 'failed'
+    class AsyncTransferStore
+      CATEGORY = 'async_transfer_'
+      private_constant :CATEGORY
+
+      # @param persistency [PersistencyFolder]
+      def initialize(persistency)
+        @persistency = persistency
+      end
+
+      # Persist (create or update) an async transfer entry.
+      # @param job_id [String] the ascli-generated UUID
+      # @param data   [Hash]   fields to store (will be JSON-serialised)
+      def write(job_id, data)
+        Aspera.assert_type(job_id, String){'job_id'}
+        Aspera.assert_type(data, Hash){'data'}
+        @persistency.put(store_key(job_id), JSON.generate(data))
+        nil
+      end
+
+      # Read one entry.
+      # @param job_id [String]
+      # @return [Hash, nil] the stored data, or nil if not found
+      def read(job_id)
+        Aspera.assert_type(job_id, String){'job_id'}
+        raw = @persistency.get(store_key(job_id))
+        return if raw.nil?
+        JSON.parse(raw)
+      end
+
+      # List all async transfer entries.
+      # @return [Array<Hash>] each entry includes the +job_id+ field
+      def list
+        @persistency.current_items(CATEGORY).map do |key, raw|
+          data = JSON.parse(raw)
+          data['job_id'] ||= key.sub(CATEGORY, '')
+          data
+        end
+      end
+
+      # Delete one entry.
+      # @param job_id [String]
+      def delete(job_id)
+        Aspera.assert_type(job_id, String){'job_id'}
+        @persistency.delete(store_key(job_id))
+        nil
+      end
+
+      private
+
+      # Map a job_id to the PersistencyFolder key (includes category prefix).
+      def store_key(job_id)
+        "#{CATEGORY}#{job_id}"
+      end
+    end
+  end
+end

data/lib/aspera/cli/bootstrapper.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/plugins/factory'
+require 'aspera/cli/extended_value'
+require 'aspera/cli/special_values'
+require 'aspera/cli/info'
+require 'aspera/cli/transfer_progress'
+require 'aspera/cli/preset_manager'
+require 'aspera/cli/http'
+require 'aspera/ascp/installation'
+require 'aspera/products/transferd'
+require 'aspera/transfer/parameters'
+require 'aspera/proxy_auto_config'
+require 'aspera/environment'
+require 'aspera/persistency_folder'
+require 'aspera/rest'
+require 'aspera/log'
+require 'aspera/assert'
+require 'aspera/oauth'
+require 'aspera/ssl'
+require 'aspera/schema/registry'
+
+module Aspera
+  module Cli
+    # Performs one-time bootstrap of all shared services into Context.
+    # Called by Runner before instantiating Plugins::Config, so that Config
+    # acts only as a CLI plugin (option declaration + command handlers).
+    #
+    # Responsibilities:
+    #   - resolve context.main_folder (option :home)
+    #   - populate context.persistency, context.presets, context.http_config, context.progress_bar
+    #   - register plugin lookup folders
+    #   - register @preset / @vault extended-value handlers
+    #   - configure global singletons: RestParameters, OAuth::Factory, SSL, Transfer::Parameters,
+    #     RestErrorAnalyzer
+    #   - set up the PAC proxy executor (option :fpac)
+    class Bootstrapper
+      # Folder name inside $HOME for all Aspera tool data (~/.aspera)
+      ASPERA_HOME_FOLDER_NAME  = '.aspera'
+      # Default name for the YAML config file
+      DEFAULT_CONFIG_FILENAME  = 'config.yaml'
+      # Sub-folder for user-installed plugins
+      ASPERA_PLUGINS_FOLDERNAME = 'plugins'
+      # Sub-folder for persistency data
+      PERSISTENCY_FOLDER       = 'persist_store'
+      # Sub-folder for file lists used by transfers
+      FILE_LIST_FOLDER_NAME    = 'filelists'
+      # Log file for REST call exceptions
+      REST_EXCEPTIONS_LOG_FILENAME = 'rest_exceptions.log'
+      # Extended-value prefix that resolves a named preset
+      EXTEND_PRESET = :preset
+      # Extended-value prefix that resolves a vault secret
+      EXTEND_VAULT  = :vault
+      # Default preset name for the global config section
+      CONF_GLOBAL_SYM = :config
+
+      private_constant :ASPERA_HOME_FOLDER_NAME,
+        :DEFAULT_CONFIG_FILENAME,
+        :ASPERA_PLUGINS_FOLDERNAME,
+        :PERSISTENCY_FOLDER,
+        :FILE_LIST_FOLDER_NAME,
+        :REST_EXCEPTIONS_LOG_FILENAME,
+        :EXTEND_PRESET,
+        :EXTEND_VAULT,
+        :CONF_GLOBAL_SYM
+
+      # @param context [Context] the shared context to populate
+      def initialize(context)
+        Aspera.assert_type(context, Context){'context'}
+        @context = context
+        @pac_exec = nil
+      end
+
+      # Run the full bootstrap sequence.
+      # Must be called after context.options and context.formatter are set.
+      # On return, context.persistency, context.presets, context.http_config and
+      # context.progress_bar are populated and all global singletons are configured.
+      #
+      # @param gem_plugins_folder [String]  folder of built-in plugins (from Plugins::Config)
+      # @param vault_value_cb     [Proc]    block(name): secret value (from VaultManager)
+      def run(gem_plugins_folder:, vault_value_cb:)
+        setup_main_folder
+        setup_persistency_and_plugin_folders(gem_plugins_folder)
+        setup_config_file
+        setup_extended_value_handlers(vault_value_cb)
+        setup_progress_bar
+        setup_pac_executor
+        setup_rest_and_transfer_runtime
+      end
+
+      # Public accessor used as option handler for :config_file
+      attr_accessor :config_file_option
+
+      private
+
+      # Declare + parse :home option: sets context.main_folder
+      def setup_main_folder
+        @context.options.declare(
+          :home, description: 'Home folder for tool',
+          handler: {o: @context, m: :main_folder},
+          default: default_app_main_folder(app_name: Info::CMD_NAME)
+        )
+        @context.options.parse_options!
+        Log.log.debug{"#{Info::CMD_NAME} folder: #{@context.main_folder}"}
+      end
+
+      # context.persistency + plugin lookup folders
+      def setup_persistency_and_plugin_folders(gem_plugins_folder)
+        @context.persistency = PersistencyFolder.new(File.join(@context.main_folder, PERSISTENCY_FOLDER))
+        Plugins::Factory.instance.add_lookup_folder(gem_plugins_folder)
+        Plugins::Factory.instance.add_lookup_folder(File.join(@context.main_folder, ASPERA_PLUGINS_FOLDERNAME))
+      end
+
+      # Declare + parse :config_file option: sets context.presets + context.http_config
+      def setup_config_file
+        @context.options.declare(
+          :config_file, description: 'Path to YAML file with preset configuration',
+          handler: {o: self, m: :config_file_option},
+          default: File.join(@context.main_folder, DEFAULT_CONFIG_FILENAME)
+        )
+        @context.options.parse_options!
+        @context.presets = PresetManager.new(config_file: @config_file_option)
+        @context.http_config = Http.new
+      end
+
+      # Register @preset and @vault extended-value handlers + global config default preset
+      def setup_extended_value_handlers(vault_value_cb)
+        @context.options.declare(:secret, description: 'Secret for access keys')
+        @context.options.declare(:vault, schema: Schema::Registry::VAULT_OPTIONS)
+        @context.options.declare(:vault_password, description: 'Vault password')
+        # Register @preset and @vault handlers BEFORE parse_options! so that
+        # values like --secret=@preset:name are correctly evaluated at parse time.
+        ExtendedValue.instance.on(EXTEND_PRESET){ |v| @context.presets.by_name(v)}
+        ExtendedValue.instance.on(EXTEND_VAULT, &vault_value_cb)
+        @context.options.parse_options!
+        # Load global config default preset (equivalent of add_plugin_default_preset(:config))
+        default_config_name = @context.presets.plugin_default_name(CONF_GLOBAL_SYM)
+        unless default_config_name.nil?
+          Log.log.debug{"add_plugin_default_preset:#{CONF_GLOBAL_SYM}:#{default_config_name}"}
+          @context.options.add_option_preset(@context.presets.by_name(default_config_name), 'default_plugin', override: false)
+        end
+      end
+
+      # Declare + parse :progress_bar: sets context.progress_bar
+      def setup_progress_bar
+        @context.options.declare(:progress_bar, description: 'Display progress bar', allowed: Allowed::TYPES_BOOLEAN, default: Environment.terminal?)
+        @context.options.parse_options!
+        @context.progress_bar = TransferProgress.new if @context.options.get_option(:progress_bar)
+      end
+
+      # Declare + parse :fpac / :proxy_credentials: sets up PAC executor
+      def setup_pac_executor
+        @context.options.declare(:fpac, description: 'Proxy auto configuration script')
+        @context.options.declare(:proxy_credentials, description: 'HTTP proxy credentials for fpac: user, password', allowed: [Array, NilClass])
+        @context.options.parse_options!
+        pac_script = @context.options.get_option(:fpac)
+        return unless pac_script
+
+        @context.pac_executor = ProxyAutoConfig.new(pac_script).register_uri_generic
+        proxy_user_pass = @context.options.get_option(:proxy_credentials)
+        if proxy_user_pass
+          Aspera.assert(proxy_user_pass.length.eql?(2), type: Cli::BadArgument){"proxy_credentials shall have two elements (#{proxy_user_pass.length})"}
+          @context.pac_executor.proxy_user = proxy_user_pass[0]
+          @context.pac_executor.proxy_pass = proxy_user_pass[1]
+        end
+      end
+
+      # Configure global singletons: RestParameters, SSL, Transfer, RestErrorAnalyzer.
+      # OAuth persist_mgr is NOT set here: it depends on :cache_tokens which is parsed later
+      # by Config#initialize. Runner sets it after Config.new.
+      def setup_rest_and_transfer_runtime
+        RestParameters.instance.user_agent    = Info::CMD_NAME
+        RestParameters.instance.progress_bar  = @context.progress_bar
+        RestParameters.instance.session_cb    = ->(http_session){@context.http_config.update_session(http_session)}
+        RestParameters.instance.spinner_cb    = ->(title = nil, action: :spin){@context.formatter.long_operation(title, action: action)}
+        OAuth::Web.additional_info = "#{Info::CMD_NAME} v#{Cli::VERSION}"
+        Transfer::Parameters.file_list_folder = File.join(@context.main_folder, FILE_LIST_FOLDER_NAME)
+        RestErrorAnalyzer.instance.log_file   = File.join(@context.main_folder, REST_EXCEPTIONS_LOG_FILENAME)
+        RestErrorsAspera.register_handlers
+      end
+
+      # @return [String] ~/.aspera
+      def module_family_folder
+        user_home_folder = Dir.home
+        Aspera.assert(Dir.exist?(user_home_folder), type: Cli::Error){"Home folder does not exist: #{user_home_folder}. Check your user environment."}
+        File.join(user_home_folder, ASPERA_HOME_FOLDER_NAME)
+      end
+
+      # @return [String] ~/.aspera/<app_name>
+      def default_app_main_folder(app_name:)
+        Aspera.assert_type(app_name, String)
+        Aspera.assert(!app_name.empty?, 'app_name must not be empty')
+        File.join(module_family_folder, app_name)
+      end
+    end
+  end
+end