aspera-cli 4.27.0 → 4.27.1

data/lib/aspera/cli/formatter.rb

@@ -2,6 +2,7 @@
 
 # cspell:ignore jsonpp
 require 'aspera/schema/registry'
+require 'aspera/cli/option_declarator'
 require 'aspera/cli/special_values'
 require 'aspera/cli/terminal_formatter'
 require 'aspera/preview/terminal'
@@ -22,6 +23,33 @@ module Aspera
   module Cli
     # Take care of CLI output on terminal
     class Formatter
+      extend OptionDeclarator
+
+      # remove a fields from the list
+      FIELDS_LESS = '-'
+      # supported output formats
+      DISPLAY_FORMATS = %i[text nagios ruby json jsonpp yaml table csv image].freeze
+      # user output levels
+      DISPLAY_LEVELS = %i[info data error].freeze
+      # column names for single object display in table
+      SINGLE_OBJECT_COLUMN_NAMES = %i[field value].freeze
+      # Terminal: vertical separator for list of strings.
+      STR_LST_SEP_VERT = "\n"
+
+      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES, :STR_LST_SEP_VERT
+
+      option :out,          description: 'Output rendering options (dot-notation: format, level, file, fields, select, table[.pivot], flat, secrets, img)', schema: Schema::Registry::OUT_OPTIONS
+      option :display,      description: 'Output only some information', allowed: DISPLAY_LEVELS, default: :data, deprecation: 'use --out.level'
+      option :format,       description: 'Output format (also: --out.format)', allowed: DISPLAY_FORMATS, default: :table
+      option :output,       description: 'Destination for results', deprecation: 'use --out.file'
+      option :fields,       description: "Comma separated list of: fields, or #{SpecialValues::ALL}, or #{SpecialValues::DEF} (also: --out.fields)", allowed: [String, Array, Regexp, Proc], default: SpecialValues::DEF
+      option :select,       description: 'Select only some items in lists: column, value (also: --out.select)', allowed: [Hash, Proc]
+      option :table_style,  description: '(Table) Display style',                                                                             allowed: [Hash], deprecation: 'use --out.table'
+      option :flat_hash,    description: '(Table) Display deep values as additional keys',                                                    allowed: Type::BOOLEAN, default: true,                    deprecation: 'use --out.flat'
+      option :multi_single, description: '(Table) Control how object list is displayed as single table, or multiple objects',                 allowed: %i[no yes single], default: :no,                 deprecation: 'use --out.table.pivot'
+      option :show_secrets, description: 'Show secrets on command output',                                                                    allowed: Type::BOOLEAN, default: false,                   deprecation: 'use --out.secrets'
+      option :image,        schema: Schema::Registry::IMAGE_OPTIONS, deprecation: 'use --out.img'
+
       class << self
         # Replace special values with a readable version on terminal
         def replace_specific_for_terminal(input_hash, string_list_separator)
@@ -58,7 +86,7 @@ module Aspera
         end
 
         def all_but(list)
-          Array(list).map{ |i| "#{FIELDS_LESS}#{i}"}.unshift(SpecialValues::ALL)
+          Array(list).map { |i| "#{FIELDS_LESS}#{i}" }.unshift(SpecialValues::ALL)
         end
       end
 
@@ -109,38 +137,20 @@ module Aspera
         end
       end
 
-      class << self
-        # Declare all formatter CLI options (metadata only - no handler binding yet).
-        # @param options [Aspera::Cli::Parser]
-        # @return [nil]
-        def declare_options(options)
-          options.declare(:display,      description: 'Output only some information',                                                                      allowed: DISPLAY_LEVELS,             default: :data)
-          options.declare(:format,       description: 'Output format',                                                                                     allowed: DISPLAY_FORMATS,            default: :table)
-          options.declare(:output,       description: 'Destination for results')
-          options.declare(:fields,       description: "Comma separated list of: fields, or #{SpecialValues::ALL}, or #{SpecialValues::DEF}", allowed: [String, Array, Regexp, Proc], default: SpecialValues::DEF)
-          options.declare(:select,       description: 'Select only some items in lists: column, value',                                                    allowed: [Hash, Proc])
-          options.declare(:table_style,  description: '(Table) Display style',                                                                             allowed: [Hash])
-          options.declare(:flat_hash,    description: '(Table) Display deep values as additional keys',                                                    allowed: Allowed::TYPES_BOOLEAN,     default: true)
-          options.declare(:multi_single, description: '(Table) Control how object list is displayed as single table, or multiple objects',                 allowed: %i[no yes single],          default: :no)
-          options.declare(:show_secrets, description: 'Show secrets on command output',                                                                    allowed: Allowed::TYPES_BOOLEAN,     default: false)
-          options.declare(:image,        schema: Schema::Registry::IMAGE_OPTIONS)
-          nil
-        end
-      end
-
       # Bind all formatter options to this instance using set_handler.
       # Called from Runner after Formatter.new.
       # @param options [Aspera::Cli::Parser]
       # @return [nil]
       def bind_options(options)
-        %i[display format output fields select table_style flat_hash multi_single show_secrets image].each do |opt|
+        @parser = options
+        %i[out display format output fields select table_style flat_hash multi_single show_secrets image].each do |opt|
           options.set_handler(opt, object: self, method: :option_handler)
         end
         nil
       end
 
       # Getter/setter handler called by the option manager for all formatter options
-      # @param option_symbol [Symbol]       Option name (one of :format, :output, :display, :fields, :select, :table_style, :flat_hash, :multi_single, :show_secrets, :image)
+      # @param option_symbol [Symbol]       Option name (one of :out, :format, :output, :display, :fields, :select, :table_style, :flat_hash, :multi_single, :show_secrets, :image)
       # @param operation     [Symbol]       :get or :set
       # @param value         [Object, nil]  Value to set (only used when operation is :set)
       # @return [Object, nil] Current option value when operation is :get; nil otherwise
@@ -148,6 +158,29 @@ module Aspera
         Aspera.assert_values(operation, %i[set get])
         case operation
         when :set
+          # --out is a composite hash: dispatch each sub-key through the parser (validation included)
+          if option_symbol.eql?(:out)
+            Aspera.assert_type(value, Hash)
+            value.each do |k, v|
+              case k.to_sym
+              when :format   then @parser.set_option(:format,       v, warn_deprecation: false)
+              when :level    then @parser.set_option(:display,      v, warn_deprecation: false)
+              when :file     then @parser.set_option(:output,       v, warn_deprecation: false)
+              when :fields   then @parser.set_option(:fields,       v, warn_deprecation: false)
+              when :select   then @parser.set_option(:select,       v, warn_deprecation: false)
+              when :table
+                Aspera.assert_type(v, Hash)
+                table_hash = v.transform_keys(&:to_sym)
+                @parser.set_option(:multi_single, table_hash.delete(:pivot).to_s, warn_deprecation: false) if table_hash.key?(:pivot)
+                @parser.set_option(:table_style,  table_hash, warn_deprecation: false) unless table_hash.empty?
+              when :flat     then @parser.set_option(:flat_hash,    v, warn_deprecation: false)
+              when :secrets  then @parser.set_option(:show_secrets, v, warn_deprecation: false)
+              when :img      then @parser.set_option(:image,        v, warn_deprecation: false)
+              else Aspera.error_unexpected_value(k) { 'out sub-option (format, level, file, fields, select, table[.pivot], flat, secrets, img)' }
+              end
+            end
+            return
+          end
           @options[option_symbol] = value
           # special handling of some options
           case option_symbol
@@ -161,12 +194,14 @@ module Aspera
             end
           when :image
             # get list if key arguments of method
-            allowed_options = Preview::Terminal.method(:build).parameters.select{ |i| i[0].eql?(:key)}.map{ |i| i[1]}
+            allowed_options = Preview::Terminal.method(:build).parameters.select { |i| i[0].eql?(:key) }.map { |i| i[1] }
             # check that only supported options are given
             unknown_options = value.keys.map(&:to_sym) - allowed_options
-            Aspera.assert(unknown_options.empty?){"Invalid parameter(s) for option image: #{unknown_options.join(', ')}, use #{allowed_options.join(', ')}"}
+            Aspera.assert(unknown_options.empty?) { "Invalid parameter(s) for option image: #{unknown_options.join(', ')}, use #{allowed_options.join(', ')}" }
           end
-        when :get then return @options[option_symbol]
+        when :get
+          return if option_symbol.eql?(:out)
+          return @options[option_symbol]
         else Aspera.error_unreachable_line
         end
         nil
@@ -212,9 +247,9 @@ module Aspera
       # @param result [Result] Result object to display
       def display_results(result)
         require 'aspera/cli/result'
-        Aspera.assert_type(result, Cli::Result){'result must be a Result object'}
+        Aspera.assert_type(result, Cli::Result) { 'result must be a Result object' }
 
-        Log.log.debug{"display_results: result class=#{result.class.name}"}
+        Log.log.debug { "display_results: result class=#{result.class.name}" }
         Log.dump(:data, result.data, level: :trace1)
         Log.dump(:fields, result.fields, level: :trace1)
 
@@ -258,14 +293,14 @@ module Aspera
 
       # @return [Array<String>] all fields of all objects in list of objects
       def all_fields(data)
-        data.each_with_object({}){ |v, m| v.each_key{ |c| m[c] = true}}.keys
+        data.each_with_object({}) { |v, m| v.each_key { |c| m[c] = true } }.keys
       end
 
       # @return [Array<String>] the list of fields to display
       # @param data    [Array<Hash>]         data to display
       # @param default [Array<String>, Proc] list of fields to display by default (may contain special values)
       def compute_fields(data, default)
-        Log.log.debug{"compute_fields: data:#{data.class} default:#{default.class} #{default}"}
+        Log.log.debug { "compute_fields: data:#{data.class} default:#{default.class} #{default}" }
         Log.dump(:compute_fields_default, default, level: :trace1)
         # the requested list of fields, but if can contain special values
         request =
@@ -273,8 +308,8 @@ module Aspera
           # when NilClass then [SpecialValues::DEF]
           when String then @options[:fields].split(',')
           when Array then @options[:fields]
-          when Regexp then return all_fields(data).select{ |i| i.match(@options[:fields])}
-          when Proc then return all_fields(data).select{ |i| @options[:fields].call(i)}
+          when Regexp then return all_fields(data).select { |i| i.match(@options[:fields]) }
+          when Proc then return all_fields(data).select { |i| @options[:fields].call(i) }
           else Aspera.error_unexpected_value(@options[:fields])
           end
         Aspera.assert_array_all(request, String)
@@ -291,12 +326,12 @@ module Aspera
             # get the list of all column names used in all lines, not just first one, as all lines may have different columns
             request.unshift(*all_fields(data))
           when SpecialValues::DEF
-            default = all_fields(data).select{ |i| default.call(i)} if default.is_a?(Proc)
+            default = all_fields(data).select { |i| default.call(i) } if default.is_a?(Proc)
             default = all_fields(data) if default.nil?
             request.unshift(*default)
           else
             if removal
-              result = result.reject{ |i| i.eql?(item)}
+              result = result.reject { |i| i.eql?(item) }
             else
               result.push(item)
             end
@@ -312,12 +347,12 @@ module Aspera
         return data unless data.is_a?(Array)
         # by default, keep all data intact
         return data if @options[:fields].eql?(SpecialValues::DEF) && @options[:select].nil?
-        Aspera.assert_array_all(data, Hash){'filter or select'}
+        Aspera.assert_array_all(data, Hash) { 'filter or select' }
         filter_columns_on_select(data)
         return data if @options[:fields].eql?(SpecialValues::DEF)
         selected_fields = compute_fields(data, @options[:fields])
-        return data.map{ |i| i[selected_fields.first]} if selected_fields.length == 1
-        return data.map{ |i| i.slice(*selected_fields)}
+        return data.map { |i| i[selected_fields.first] } if selected_fields.length == 1
+        return data.map { |i| i.slice(*selected_fields) }
       end
 
       # filter the list of items on the select option
@@ -326,12 +361,12 @@ module Aspera
         case @options[:select]
         when Proc
           begin
-            data.select!{ |i| @options[:select].call(i)}
+            data.select! { |i| @options[:select].call(i) }
           rescue StandardError => e
             raise Cli::BadArgument, "Error in user-provided ruby lambda code during select: #{e.message}"
           end
         when Hash
-          @options[:select].each{ |k, v| data.select!{ |i| i[k].eql?(v)}}
+          @options[:select].each { |k, v| data.select! { |i| i[k].eql?(v) } }
         end
       end
 
@@ -351,7 +386,7 @@ module Aspera
         format_style = @options[:table_style].symbolize_keys
         string_list_separator = format_style.delete(:str_lst_sep) || STR_LST_SEP_VERT
         # convert data to string, and keep only display fields
-        object_array.each{ |i| self.class.replace_specific_for_terminal(i, string_list_separator)}
+        object_array.each { |i| self.class.replace_specific_for_terminal(i, string_list_separator) }
         # if table has only one element, and only one field, display the value
         if object_array.length == 1 && fields.length == 1
           Log.log.debug("single element, field: #{fields.first}")
@@ -367,9 +402,9 @@ module Aspera
         Log.dump(:object_array, object_array)
         Log.dump(:fields, fields)
         # convert data to string, and keep only display fields
-        final_table_rows = object_array.map{ |r| fields.map{ |c| r[c].to_s}}
+        final_table_rows = object_array.map { |r| fields.map { |c| r[c].to_s } }
         # remove empty rows
-        final_table_rows.select!{ |i| !(i.is_a?(Hash) && i.empty?)}
+        final_table_rows.select! { |i| !(i.is_a?(Hash) && i.empty?) }
         # fields: list of column names to display
         case @options[:format]
         when :table
@@ -406,19 +441,6 @@ module Aspera
         end
         nil
       end
-
-      # remove a fields from the list
-      FIELDS_LESS = '-'
-      # supported output formats
-      DISPLAY_FORMATS = %i[text nagios ruby json jsonpp yaml table csv image].freeze
-      # user output levels
-      DISPLAY_LEVELS = %i[info data error].freeze
-      # column names for single object display in table
-      SINGLE_OBJECT_COLUMN_NAMES = %i[field value].freeze
-      # Terminal: vertical separator for list of strings.
-      STR_LST_SEP_VERT = "\n"
-
-      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES, :STR_LST_SEP_VERT
     end
   end
 end

data/lib/aspera/cli/gem_checker.rb

@@ -51,7 +51,7 @@ module Aspera
         )
         current_date = Date.today
         last_check_days = (current_date - Date.strptime(last_check_array.first, GEM_CHECK_DATE_FMT)) rescue nil
-        Log.log.debug{"gem check new version: #{delay_days}, #{last_check_days}, #{current_date}, #{last_check_array}"}
+        Log.log.debug { "gem check new version: #{delay_days}, #{last_check_days}, #{current_date}, #{last_check_array}" }
         return if !last_check_days.nil? && last_check_days < delay_days
         last_check_array[0] = current_date.strftime(GEM_CHECK_DATE_FMT)
         check_date_persist.save

data/lib/aspera/cli/hints.rb

@@ -142,10 +142,10 @@ module Aspera
                 next unless message.eql?(m)
               when Regexp
                 next unless message.match?(m)
-              else Aspera.error_unexpected_value(m){'hint match'}
+              else Aspera.error_unexpected_value(m) { 'hint match' }
               end
               hint[:remediation].each do |r|
-                Log.log.info{"#{'HINT:'.bg_green.gray.blink.freeze} #{r}"}
+                Log.log.info { "#{'HINT:'.bg_green.gray.blink.freeze} #{r}" }
               end
             end
           end

data/lib/aspera/cli/http.rb

@@ -5,6 +5,7 @@ require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/line_logger'
 require 'aspera/schema/registry'
+require 'aspera/cli/option_declarator'
 require 'aspera/rest'
 require 'aspera/oauth'
 require 'aspera/ssl'
@@ -16,6 +17,8 @@ module Aspera
     # Extracted from Plugins::Config so it can be referenced independently
     # via Context#http_config without coupling to the plugin machinery.
     class Http
+      extend OptionDeclarator
+
       # Certificate file extensions recognized when scanning a folder
       CERT_EXT = %w[crt cer pem der].freeze
       # OpenSSL constant that disables peer verification (VERIFY_NONE)
@@ -23,6 +26,13 @@ module Aspera
 
       private_constant :CERT_EXT, :SELF_SIGNED_CERT
 
+      option :insecure,           description: 'HTTP/S: Do not validate any certificate',                   allowed: Type::BOOLEAN, default: false
+      option :ignore_certificate, description: 'HTTP/S: Do not validate certificate for these URLs',        allowed: [Array, NilClass]
+      option :warn_insecure,      description: 'HTTP/S: Issue a warning if certificate is ignored',         allowed: Type::BOOLEAN, default: true
+      option :cert_stores,        description: 'HTTP/S: List of folder with trusted certificates',          allowed: Type::STRING_ARRAY
+      option :http_options,       schema: Schema::Registry::HTTP_OPTIONS
+      option :http_proxy,         description: 'HTTP/S: URL for proxy with optional credentials'
+
       def initialize
         @insecure              = false
         @warn_insecure         = true
@@ -36,23 +46,6 @@ module Aspera
       attr_accessor :insecure, :warn_insecure
       attr_reader   :ignore_cert_host_port, :http_options
 
-      class << self
-        # Declare all HTTP/S CLI options (metadata only - no handler binding yet).
-        # Called once from Config#initialize before this instance is available as a target.
-        # Handlers are bound in a second pass via bind_options once the instance exists.
-        # @param options [Aspera::Cli::Parser] CLI options manager to declare options into
-        # @return [nil]
-        def declare_options(options)
-          options.declare(:insecure,           description: 'HTTP/S: Do not validate any certificate',                   allowed: Allowed::TYPES_BOOLEAN, default: false)
-          options.declare(:ignore_certificate, description: 'HTTP/S: Do not validate certificate for these URLs',        allowed: [Array, NilClass])
-          options.declare(:warn_insecure,      description: 'HTTP/S: Issue a warning if certificate is ignored',         allowed: Allowed::TYPES_BOOLEAN, default: true)
-          options.declare(:cert_stores,        description: 'HTTP/S: List of folder with trusted certificates',          allowed: Allowed::TYPES_STRING_ARRAY)
-          options.declare(:http_options,       schema: Schema::Registry::HTTP_OPTIONS)
-          options.declare(:http_proxy,         description: 'HTTP/S: URL for proxy with optional credentials')
-          nil
-        end
-      end
-
       # Bind all HTTP options to this instance using set_handler.
       # Called from Config#initialize immediately after Http.new.
       # @param options [Aspera::Cli::Parser]
@@ -113,7 +106,7 @@ module Aspera
       def ignore_cert_host_port=(url_list)
         url_list.each do |url|
           uri = URI.parse(url)
-          Aspera.assert(uri.scheme.eql?('https')){"Expecting https scheme: #{url}"}
+          Aspera.assert(uri.scheme.eql?('https')) { "Expecting https scheme: #{url}" }
           @ignore_cert_host_port.push([uri.host, uri.port].freeze)
         end
       end
@@ -126,11 +119,11 @@ module Aspera
         if ignore_cert && @warn_insecure
           base_url = "https://#{address}:#{port}"
           unless @ssl_warned_urls.include?(base_url)
-            Log.log.warn{"Ignoring certificate for: #{base_url}. Do not deactivate certificate verification in production."}
+            Log.log.warn { "Ignoring certificate for: #{base_url}. Do not deactivate certificate verification in production." }
             @ssl_warned_urls.push(base_url)
           end
         end
-        Log.log.debug{"ignore cert? #{endpoint} -> #{ignore_cert}"}
+        Log.log.debug { "ignore cert? #{endpoint} -> #{ignore_cert}" }
         ignore_cert
       end
 
@@ -142,21 +135,21 @@ module Aspera
       # @param path_list [Array<String>] list of file/folder paths to add to the certificate store
       # @return [nil]
       def trusted_cert_locations=(path_list)
-        Aspera.assert_type(path_list, Array){'cert locations'}
+        Aspera.assert_type(path_list, Array) { 'cert locations' }
         if @certificate_store.nil?
           Log.log.debug('Creating SSL Cert store')
           @certificate_store = OpenSSL::X509::Store.new
           @certificate_paths = []
         end
         path_list.each do |path|
-          Aspera.assert_type(path, String){'Expecting a String for certificate location'}
+          Aspera.assert_type(path, String) { 'Expecting a String for certificate location' }
           paths_to_add = [path]
-          Log.log.debug{"Adding cert location: #{path}"}
+          Log.log.debug { "Adding cert location: #{path}" }
           if path.eql?(SpecialValues::DEF)
             @certificate_store.set_default_paths
             paths_to_add = [OpenSSL::X509::DEFAULT_CERT_DIR]
             paths_to_add.push(OpenSSL::X509::DEFAULT_CERT_FILE) unless defined?(JRUBY_VERSION)
-            paths_to_add.select!{ |f| File.exist?(f)}
+            paths_to_add.select! { |f| File.exist?(f) }
           elsif File.file?(path)
             @certificate_store.add_file(path)
           elsif File.directory?(path)
@@ -168,9 +161,9 @@ module Aspera
             pp = [File.realpath(p)]
             if File.directory?(p)
               pp = Dir.entries(p)
-                .map{ |e| File.realpath(File.join(p, e))}
-                .select{ |entry| File.file?(entry)}
-                .select{ |entry| CERT_EXT.any?{ |ext| entry.end_with?(ext)}}
+                .map { |e| File.realpath(File.join(p, e)) }
+                .select { |entry| File.file?(entry) }
+                .select { |entry| CERT_EXT.any? { |ext| entry.end_with?(ext) } }
             end
             @certificate_paths.concat(pp)
           end
@@ -202,13 +195,13 @@ module Aspera
         http_session.set_debug_output(LineLogger.new(:trace2)) if Log.instance.logger.trace2?
         http_session.verify_mode = SELF_SIGNED_CERT if http_session.use_ssl? && ignore_cert?(http_session.address, http_session.port)
         http_session.cert_store = @certificate_store if @certificate_store
-        Log.log.debug{"Using cert store #{http_session.cert_store} (#{@certificate_store})"} unless http_session.cert_store.nil?
+        Log.log.debug { "Using cert store #{http_session.cert_store} (#{@certificate_store})" } unless http_session.cert_store.nil?
         @http_options.each do |k, v|
           method = "#{k}=".to_sym
           if http_session.respond_to?(method)
             http_session.send(method, v)
           else
-            Log.log.error{"Unknown HTTP session attribute: #{k}"}
+            Log.log.error { "Unknown HTTP session attribute: #{k}" }
           end
         end
         nil

data/lib/aspera/cli/mailer.rb

@@ -32,16 +32,16 @@ module Aspera
         # Change keys from string into symbol
         smtp = smtp.symbolize_keys
         unsupported = smtp.keys - SMTP_CONF_PARAMS
-        Aspera.assert(unsupported.empty?, type: Cli::Error){"Unsupported SMTP parameter: #{unsupported.join(', ')}, use: #{SMTP_CONF_PARAMS.join(', ')}"}
+        Aspera.assert(unsupported.empty?, type: Cli::Error) { "Unsupported SMTP parameter: #{unsupported.join(', ')}, use: #{SMTP_CONF_PARAMS.join(', ')}" }
         # Boolean fields must be actual booleans, not strings like "false"
         SMTP_BOOL_PARAMS.each do |k|
-          Aspera.assert_values(smtp[k], [true, false], type: Cli::Error){"smtp.#{k}"} if smtp.key?(k)
+          Aspera.assert_values(smtp[k], [true, false], type: Cli::Error) { "smtp.#{k}" } if smtp.key?(k)
         end
         SMTP_INT_PARAMS.each do |k|
-          Aspera.assert_type(smtp[k], Integer, type: Cli::Error){"smtp.#{k}"} if smtp.key?(k)
+          Aspera.assert_type(smtp[k], Integer, type: Cli::Error) { "smtp.#{k}" } if smtp.key?(k)
         end
         SMTP_STR_PARAMS.each do |k|
-          Aspera.assert_type(smtp[k], String, type: Cli::Error){"smtp.#{k}"} if smtp.key?(k)
+          Aspera.assert_type(smtp[k], String, type: Cli::Error) { "smtp.#{k}" } if smtp.key?(k)
         end
         # smtp[:ssl] = nil (false)
         smtp[:tls] = !smtp[:ssl] unless smtp.key?(:tls)
@@ -56,9 +56,9 @@ module Aspera
         smtp[:from_name] ||= smtp[:from_email].sub(/@.*$/, '').gsub(/[^a-zA-Z]/, ' ').capitalize if smtp.key?(:username)
         smtp[:domain] ||= smtp[:from_email].sub(/^.*@/, '') if smtp.key?(:from_email)
         %i[server port domain].each do |n|
-          Aspera.assert(smtp.key?(n)){"Missing mandatory smtp parameter: #{n}"}
+          Aspera.assert(smtp.key?(n)) { "Missing mandatory smtp parameter: #{n}" }
         end
-        Log.log.debug{"smtp=#{smtp}"}
+        Log.dump(:smtp, smtp.reject { |k, _| k == :password })
         return smtp
       end
 
@@ -72,7 +72,7 @@ module Aspera
         values[:from_name] ||= mail_conf[:from_name]
         values[:from_email] ||= mail_conf[:from_email]
         %i[to from_email].each do |n|
-          Aspera.assert_type(values[n], String){"Missing email parameter: #{n} in config"}
+          Aspera.assert_type(values[n], String) { "Missing email parameter: #{n} in config" }
         end
         start_options = [mail_conf[:domain]]
         start_options.push(mail_conf[:username], mail_conf[:password], :login) if mail_conf.key?(:username) && mail_conf.key?(:password)

data/lib/aspera/cli/mcp_tool.rb

@@ -6,11 +6,13 @@ require 'json'
 require 'aspera/log'
 require 'aspera/cli/runner'
 require 'aspera/cli/error'
+require 'aspera/schema/reader'
+require 'aspera/schema/registry'
 unless defined?(MCP::Tool)
   begin
     require 'mcp'
   rescue LoadError
-    raise Cli::Error, "The 'mcp' gem is required. Install it with: gem install mcp"
+    raise Cli::Error, "The 'mcp' and 'rack' gems are required. Install them with: gem install mcp rack"
   end
 end
 
@@ -36,14 +38,16 @@ module Aspera
           Element 0 : plugin name (aoc, faspex5, node, server, config, …).
           Elements 1+: sub-commands, then --option=value flags in any order.
           Passing structured values: use an extended-value prefix on the relevant element:
-            "@json:{...}"   — inline JSON object or array (use for Hash/Array arguments)
+            "@json:{...}"   — inline JSON object or array (preferred for LLMs: no shell quoting, natural JSON)
             "@preset:name"  — expand a saved credential preset
             "@env:VAR"      — read value from environment variable
             "@file:/path"   — read value from a file
+          Note: the dot-path form (@: key=value ...) is designed for humans typing in a terminal shell.
+          Prefer @json: when building args programmatically or as an LLM.
 
         AUTOMATIC FLAGS
           The server automatically prepends extra_args to every call (default:
-          --interactive=no and --transfer.asynchronous=true).
+          #{DEFAULT_EXTRA_ARGS.join(' ')}).
           Do NOT repeat these flags in your args array — they are already injected.
           If you explicitly need to override one (e.g. --interactive=yes), include it
           in your args; your value will take precedence because it appears after the
@@ -175,10 +179,33 @@ module Aspera
           else
             MCP::Tool::Response.new([{type: 'text', text: result.data.to_s}])
           end
+        rescue Cli::SchemaRequest => e
+          schema_path = e.path
+          if schema_path.nil?
+            MCP::Tool::Response.new([{type: 'text', text: "#{e.class}: #{e.message} (no schema available)"}], error: true)
+          else
+            rows = schema_to_rows(Schema::Registry.instance.reader(schema_path))
+            structured = {items: rows}
+            MCP::Tool::Response.new([{type: 'text', text: JSON.generate(rows)}], structured_content: structured)
+          end
         rescue SystemExit => e
           MCP::Tool::Response.new([{type: 'text', text: "exited with status #{e.status}"}], error: !e.status.zero?)
         rescue => e
-          MCP::Tool::Response.new([{type: 'text', text: "#{e.class}: #{e.message}"}], error: true)
+          MCP::Tool::Response.new([{type: 'text', text: "#{e.class}: #{dedupe_lines(e.message)}"}], error: true)
+        end
+
+        # Delegate to Schema::Reader#to_rows — semantic fields, no ANSI, MCP/JSON-ready.
+        def schema_to_rows(reader)
+          reader.to_rows
+        end
+
+        # Collapse consecutive duplicate lines in a multi-line message.
+        # Each run of identical lines is replaced by one line + "(×N)" suffix when N > 1.
+        def dedupe_lines(msg)
+          return msg unless msg.include?("\n")
+          msg.split("\n").chunk_while { |a, b| a == b }.map do |group|
+            group.size > 1 ? "#{group.first} (x#{group.size})" : group.first
+          end.join("\n")
         end
 
         # Returns the largest prefix of +items+ whose JSON serialization fits within +max_bytes+.

data/lib/aspera/cli/option_declarator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/parser'
+require 'aspera/cli/command_spec'
+
+module Aspera
+  module Cli
+    # Mixin providing declarative CLI option definitions (`option :name, ...`)
+    # and batch declaration onto a Parser instance (`declare_options(parser)`).
+    module OptionDeclarator
+      # Registry of OptionSpec objects defined on this class/module.
+      # @return [Hash{Symbol => OptionSpec}]
+      def option_specs
+        @option_specs ||= {}
+      end
+
+      # Declare an option in this class's registry.
+      #
+      # @param name        [Symbol]          Option name
+      # @param description [String, nil]     User-facing description
+      # @param short       [String, nil]     Single-character short form
+      # @param allowed     [Object, nil]     Allowed values
+      # @param default     [Object, nil]     Default value
+      # @param handler     [Symbol, Hash, nil] Handler (Symbol or Hash)
+      # @param deprecation [String, nil]     Deprecation message
+      # @param schema      [String, nil]     Schema reference
+      def option(name, description: nil,
+        short: nil, allowed: nil, default: nil,
+        handler: nil, deprecation: nil, schema: nil)
+        raise ArgumentError, "Duplicate option: #{name.inspect}" if option_specs.key?(name)
+        option_specs[name] = OptionSpec.new(
+          name:        name,
+          description: description,
+          short:       short,
+          allowed:     allowed,
+          default:     default,
+          handler:     handler,
+          deprecation: deprecation,
+          schema:      schema
+        )
+      end
+
+      # Declare all options registered on this class onto a Parser instance.
+      # Skips options already declared on the parser.
+      #
+      # @param parser [Aspera::Cli::Parser]
+      # @param target [Object, nil] default target object for Symbol handlers (defaults to self)
+      # @return [void]
+      def declare_options(parser, target: self)
+        option_specs.each_value do |spec|
+          next if parser.option_declared?(spec.name)
+          resolved_handler =
+            case spec.handler
+            when Symbol then {o: target, m: spec.handler}
+            when Hash   then spec.handler
+            end
+          parser.declare(
+            spec.name,
+            description: spec.description,
+            short:       spec.short,
+            allowed:     spec.allowed,
+            default:     spec.default,
+            handler:     resolved_handler,
+            deprecation: spec.deprecation,
+            schema:      schema_for_spec(spec)
+          )
+        end
+      end
+
+      private
+
+      def schema_for_spec(spec)
+        spec.schema
+      end
+    end
+  end
+end