aspera-cli 4.27.5 → 4.28.0

data/lib/aspera/cli/runner.rb

@@ -4,24 +4,29 @@ require 'aspera/cli/command_spec'
 require 'aspera/cli/context'
 require 'aspera/cli/parser'
 require 'aspera/cli/formatter'
+require 'aspera/cli/table_fitter'
 require 'aspera/cli/plugins/factory'
 require 'aspera/cli/bootstrapper'
+require 'aspera/rest/aspera_errors' # registers error handlers of Aspera REST APIs
 require 'aspera/cli/plugins/config'
 require 'aspera/cli/mailer'
 require 'aspera/cli/secret_finder'
 require 'aspera/cli/extended_value'
+require 'aspera/cli/security'
 require 'aspera/cli/transfer_agent'
 require 'aspera/cli/version'
 require 'aspera/cli/info'
 require 'aspera/cli/hints'
 require 'aspera/cli/result'
 require 'aspera/transfer/result'
+require 'aspera/duration'
 require 'aspera/secret_hider'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/schema/documentation'
 require 'aspera/schema/registry'
 require 'net/ssh/errors'
+require 'net/protocol'
 require 'openssl'
 
 module Aspera
@@ -49,6 +54,17 @@ module Aspera
           end
         end
 
+        # Result of a command that creates an object and transfers its files, e.g. `packages send`.
+        # @param object          [Hash]             Created object
+        # @param transfer_result [Transfer::Result] Typed result from TransferAgent#start
+        # @raise [StandardError] if the transfer failed
+        # @return [Result::SingleObject] The object, with field `transfer` (`job_id`) if the transfer is asynchronous
+        def result_object_transfer(object, transfer_result)
+          status = result_transfer(transfer_result)
+          object = object.merge('transfer' => status.data) if status.is_a?(Result::SingleObject)
+          Result::SingleObject.new(object)
+        end
+
         # Used when one command executes several transfer jobs (each job being possibly multi session)
         # @param status_table [Array] [{STATUS_FIELD=>Transfer::Result,...},...]
         # @return [Result] a status object suitable as command result
@@ -94,7 +110,8 @@ module Aspera
         Plugins::Factory.instance.add_plugins_from_lookup_folders
         # Help requested without command? Show global options + plugin list
         return result_usage if @option_help && @context.options.command_or_arg_empty?
-        @context.config.periodic_check_newer_gem_version
+        # Shell completion is executed on each `Tab`: no network access
+        @context.config.periodic_check_newer_gem_version unless @context.options.next_arguments?(COMPLETION_COMMAND)
         command_sym =
           if @option_show_config && @context.options.command_or_arg_empty?
             COMMAND_CONFIG
@@ -158,18 +175,18 @@ module Aspera
         begin
           result = run_with_result
           @context.formatter.display_results(result) if result
-        rescue Net::SSH::AuthenticationFailed => e; exception_info = {e: e, t: 'SSH', security: true}
-        rescue OpenSSL::SSL::SSLError => e;         exception_info = {e: e, t: 'SSL'}
-        rescue Cli::BadArgument => e;               exception_info = {e: e, t: 'Argument', usage: true}
-        rescue Cli::MissingArgument => e;           exception_info = {e: e, t: 'Missing'}
-        rescue Cli::BadIdentifier => e;             exception_info = {e: e, t: 'Identifier'}
-        rescue Cli::SchemaRequest => e;             exception_info = {e: e, t: 'Schema'}
-        rescue Cli::Error => e;                     exception_info = {e: e, t: 'Tool', usage: true}
-        rescue Transfer::Error => e;                exception_info = {e: e, t: 'Transfer'}
-        rescue Rest::CallError => e;                exception_info = {e: e, t: 'Rest'}
-        rescue SocketError => e;                    exception_info = {e: e, t: 'Network'}
-        rescue StandardError => e;                  exception_info = {e: e, t: "Other(#{e.class.name})", debug: true}
-        rescue Interrupt => e;                      exception_info = {e: e, t: 'Interruption', debug: true}
+        rescue Net::SSH::AuthenticationFailed => e;    exception_info = {e: e, t: 'SSH', security: true, exit: ExitCode::AUTH}
+        rescue OpenSSL::SSL::SSLError => e;            exception_info = {e: e, t: 'SSL', exit: ExitCode::NETWORK}
+        rescue Cli::BadArgument => e;                  exception_info = {e: e, t: 'Argument', usage: true, exit: ExitCode::USAGE}
+        rescue Cli::MissingArgument => e;              exception_info = {e: e, t: 'Missing', exit: ExitCode::USAGE}
+        rescue Cli::BadIdentifier, EntityNotFound => e; exception_info = {e: e, t: 'Identifier', exit: ExitCode::NOT_FOUND}
+        rescue Cli::SchemaRequest => e;                exception_info = {e: e, t: 'Schema', exit: ExitCode::SUCCESS}
+        rescue Cli::Error => e;                        exception_info = {e: e, t: 'Tool', usage: true, exit: ExitCode::ERROR}
+        rescue Transfer::Error => e;                   exception_info = {e: e, t: 'Transfer', exit: ExitCode::TRANSFER}
+        rescue Rest::CallError => e;                   exception_info = {e: e, t: 'Rest', exit: ExitCode.for_call_error(e)}
+        rescue *NETWORK_ERRORS => e;                   exception_info = {e: e, t: 'Network', exit: ExitCode::NETWORK}
+        rescue StandardError => e;                     exception_info = {e: e, t: "Other(#{e.class.name})", debug: true, exit: ExitCode::ERROR}
+        rescue Interrupt => e;                         exception_info = {e: e, t: 'Interruption', debug: true, exit: ExitCode::INTERRUPTED}
         end
         # 1- processing of error condition
         unless exception_info.nil?
@@ -180,35 +197,28 @@ module Aspera
           Hints.hint_for(exception_info[:e], @context.formatter)
           if exception_info[:e].is_a?(Cli::SchemaRequest)
             Log.log.info { "#{exception_info[:t]}: #{exception_info[:e].message}" }
-            schema_path = exception_info[:e].path
-            if schema_path.nil?
-              Log.log.warn { 'Sorry, no schema provided yet. Please refer to the manual or API.' }
-            else
-              reader = Schema::Registry.instance.reader(schema_path)
-              rows   = reader.to_rows.map do |row|
-                if row.key?('enum')
-                  row = row.dup
-                  row['type'] = 'enum'
-                  row['description'] = "#{row['description']}\nAllowed: #{row['enum'].join(', ')}"
-                end
-                row
-              end
-              @context.formatter.display_results(Result::ObjectList.new(rows, fields: %w[name type required description]))
-            end
+            display_schema(exception_info[:e].path)
           end
         end
         # 2- processing of unprocessed arguments (skip when help was displayed: sub-commands are not consumed)
         unless @option_help
           @context.options&.final_errors&.each do |msg|
             Log.log.error { "Argument: #{msg}" }
-            exception_info = {e: Exception.new(msg), t: 'UnusedArg'} if exception_info.nil?
+            exception_info = {e: Exception.new(msg), t: 'UnusedArg', exit: ExitCode::USAGE} if exception_info.nil?
           end
         end
         # 3- exit on error
         unless exception_info.nil?
-          raise exception_info[:e] if Log.log.debug?
-          @context.formatter.display_message(:error, 'Use --log-level=debug to get more details.') if exception_info[:debug]
-          Process.exit(1)
+          if Log.log.debug?
+            # Same display as an uncaught exception, but keeps the exit code
+            $stderr.puts(exception_info[:e].full_message) # rubocop:disable Style/StderrPuts
+          elsif exception_info[:debug]
+            @context.formatter.display_message(:error, 'Use --log-level=debug to get more details.')
+          end
+          exit_code = exception_info[:exit]
+          # Nagios plugins report the failure of the check itself as UNKNOWN
+          exit_code = Nagios::UNKNOWN if !exit_code.eql?(ExitCode::SUCCESS) && @context.formatter&.format_type.eql?(:nagios)
+          Process.exit(exit_code)
         end
         return
       end
@@ -228,6 +238,28 @@ module Aspera
         Result::Text.new(usage_text(plugin: plugin))
       end
 
+      # `on_set` callback of the `ui` option (dot-notation sub-properties): `mode`, `command`
+      # A plain value is the `mode`. Values are validated against schema `UiOptions`.
+      # @param value [Hash] sub-properties to set
+      def option_ui=(value)
+        Aspera.assert_type(value, Hash)
+        value.each do |k, v|
+          case k.to_sym
+          when :mode
+            Environment.instance.url_method =
+              case v.to_s
+              when 'auto' then Environment.instance.default_gui_mode
+              when 'terminal', 'text' then :text
+              when 'browser', 'graphical' then :graphical
+              else Aspera.error_unexpected_value(v, type: BadArgument) { 'ui.mode' }
+              end
+          when :command
+            Environment.instance.browser_command = v.nil? || v.empty? ? nil : v.map(&:to_s)
+          else Aspera.error_unexpected_value(k, type: BadArgument) { 'ui sub-option (mode, command)' }
+          end
+        end
+      end
+
       # `on_set` callback of the `log` option (dot-notation sub-properties): `level`, `type`, `format`, `secrets`
       # @param value [Hash] sub-properties to set
       def option_log=(value)
@@ -243,6 +275,29 @@ module Aspera
         end
       end
 
+      # `on_set` callback of the `temp` option (dot-notation sub-properties): `folder`, `clean`, `expiry`
+      # A plain value is the `folder`. Values are validated against schema `TempOptions`.
+      # @param value [Hash] sub-properties to set
+      def option_temp=(value)
+        Aspera.assert_type(value, Hash)
+        value.each do |k, v|
+          case k.to_sym
+          when :folder then TempFileManager.instance.global_temp = v
+          when :clean  then TempFileManager.instance.cleanup_on_exit = Parser.get_from_list(v.to_s, 'temp clean', BoolValue::ALL)
+          when :expiry
+            TempFileManager.instance.expiry_sec =
+              case v
+              when nil, false then nil
+              when Numeric then v
+              else Duration.to_unit(v, 's')
+              end
+          else Aspera.error_unexpected_value(k, type: BadArgument) { 'temp sub-option (folder, clean, expiry)' }
+          end
+        end
+      rescue ParameterError => e
+        raise BadArgument, "Option temp: #{e.message}"
+      end
+
       private
 
       # Build the usage/help text.
@@ -327,16 +382,36 @@ module Aspera
       # @param arg [ArgumentSpec]
       # @return [Array<String>]
       def schema_help_lines(arg)
-        builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(arg.schema)).build
-        rows = builder.rows.reject { |row| row['type'].eql?('&nbsp;') }.map do |row|
-          builder.columns.map { |column| row[column].to_s }
+        builder = schema_documentation(arg.schema)
+        rows = builder.rows.map do |row|
+          builder.columns.map { |column| Array(row[column]).join("\n") }
         end
         style = {}
         style[:border] = :unicode_round if Environment.terminal_supports_unicode?
-        table = Terminal::Table.new(headings: builder.columns, rows: rows, style: style).to_s
+        table = TableFitter.table(headings: builder.columns, rows: rows, style: style, width: Environment.terminal_columns&.-(4)).to_s
         ["\n    SCHEMA: #{arg.name}", table.lines.map { |line| "    #{line.chomp}" }.join("\n")]
       end
 
+      # Display the documentation of a schema: value `help` given to an option or argument
+      # @param schema_path [String, nil] Path of the schema in the registry, `nil` if none
+      # @return [nil]
+      def display_schema(schema_path)
+        if schema_path.nil?
+          Log.log.warn { 'Sorry, no schema provided yet. Please refer to the manual or API.' }
+          return
+        end
+        builder = schema_documentation(schema_path)
+        @context.formatter.display_results(Result::ObjectList.new(builder.rows, fields: builder.columns))
+        nil
+      end
+
+      # @param schema_path [String] Path of the schema in the registry
+      # @return [Schema::Documentation] Documentation of the schema, for the terminal
+      def schema_documentation(schema_path)
+        options = schema_path.eql?(Schema::Registry::TRANSFER_SPEC) ? Transfer::Spec.doc_options : {}
+        Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(schema_path), **options).build
+      end
+
       # Initialize agents and options
       # This can throw exception if there is a problem with the environment, needs to be caught by execute method
       # @raise [StandardError] if there is a problem with the environment
@@ -413,6 +488,9 @@ module Aspera
 
           ARGS
           #{t}Some commands require mandatory arguments, e.g. a path.
+
+          EXIT STATUS
+          #{ExitCode::DESCRIPTIONS.map { |code, description| "#{t}#{code.to_s.ljust(5)}#{description}" }.join("\n")}
         END_OF_BANNER
       end
 
@@ -427,9 +505,9 @@ module Aspera
         @context.options.declare(:show_config, description: 'Display parameters used for the provided action', allowed: Type::NONE) { @option_show_config = true }
         @context.options.declare(:version, description: 'Display version', allowed: Type::NONE, short: 'v') { @context.formatter.display_message(:data, Cli::VERSION); Process.exit(0) } # rubocop:disable Style/Semicolon
         @context.options.declare(
-          :ui, description: 'Method to start browser',
-          allowed: USER_INTERFACES, default: Environment.instance.url_method,
-          on_set: Environment.instance.method(:url_method=)
+          :ui, description: 'User interface (dot-notation: mode, command)',
+          allowed: [Hash, String], shorthand: 'mode', schema: Schema::Registry::UI_OPTIONS,
+          on_set: method(:option_ui=)
         )
         @context.options.declare(
           :invalid_characters, description: 'Replacement character and invalid filename characters',
@@ -440,11 +518,17 @@ module Aspera
         @context.options.declare(:log_format, description: 'Log formatter', allowed: [Proc, Logger::Formatter, String], on_set: Log.instance.method(:formatter=))
         @context.options.declare(:logger, description: 'Logging method', allowed: Log::LOG_TYPES, on_set: Log.instance.method(:logger_type=))
         @context.options.declare(:log, description: 'Logging options (dot-notation: level, type, format, secrets)', on_set: method(:option_log=), schema: Schema::Registry::LOG_OPTIONS)
+        @context.options.declare(:security, description: 'Security restrictions (dot-notation: level, allowed_paths)', on_set: Security.instance.method(:options=), schema: Schema::Registry::SECURITY_OPTIONS)
         @context.options.declare(:lock_port, description: 'Prevent dual execution of a command, e.g. in cron', allowed: Type::INTEGER)
         @context.options.declare(:once_only, description: 'Process only new items (some commands)', allowed: Type::BOOLEAN, default: false)
         @context.options.declare(:log_secrets, description: 'Show passwords in logs', allowed: Type::BOOLEAN, default: SecretHider.instance.log_secrets, on_set: SecretHider.instance.method(:log_secrets=))
-        @context.options.declare(:clean_temp, description: 'Cleanup temporary files on exit', allowed: Type::BOOLEAN, default: TempFileManager.instance.cleanup_on_exit, on_set: TempFileManager.instance.method(:cleanup_on_exit=))
-        @context.options.declare(:temp_folder, description: 'Temporary folder', default: TempFileManager.instance.global_temp, on_set: TempFileManager.instance.method(:global_temp=))
+        @context.options.declare(
+          :temp, description: 'Temporary files (dot-notation: folder, clean, expiry)',
+          allowed: [Hash, String], shorthand: 'folder', schema: Schema::Registry::TEMP_OPTIONS,
+          on_set: method(:option_temp=)
+        )
+        @context.options.declare(:clean_temp, description: 'Cleanup temporary files on exit', allowed: Type::BOOLEAN, on_set: TempFileManager.instance.method(:cleanup_on_exit=), deprecation: {last: '4.27.5', message: 'use --temp.clean'})
+        @context.options.declare(:temp_folder, description: 'Temporary folder', on_set: TempFileManager.instance.method(:global_temp=), deprecation: {last: '4.27.5', message: 'use --temp.folder'})
         @context.options.declare(:pid_file, description: 'Write process identifier to file, delete on exit')
         @context.options.declare(
           :parser, description: 'Default parser for structured parameters and options',
@@ -471,12 +555,18 @@ module Aspera
       end
       COMMAND_CONFIG = :config
       COMMAND_HELP = :help
+      # Shell completion commands (scripts and words)
+      COMPLETION_COMMAND = %w[config completion].freeze
       # Types that go to result of type = text
       SCALAR_TYPES = [String, Integer, Symbol].freeze
-      USER_INTERFACES = %i[text graphical].freeze
       EXTEND_ARGS = :''
+      # Errors of name resolution, connection and timeout
+      NETWORK_ERRORS = [
+        SocketError, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ETIMEDOUT
+      ].freeze
 
-      private_constant :COMMAND_CONFIG, :COMMAND_HELP, :SCALAR_TYPES, :USER_INTERFACES, :EXTEND_ARGS
+      private_constant :COMMAND_CONFIG, :COMMAND_HELP, :COMPLETION_COMMAND, :SCALAR_TYPES, :EXTEND_ARGS, :NETWORK_ERRORS
     end
   end
 end

data/lib/aspera/cli/security.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'aspera/assert'
+require 'aspera/cli/error'
+
+module Aspera
+  module Cli
+    # Security level: restricts the features that access local resources (files, environment, network) or execute code.
+    # On the command line, the default level is `low`: the user can do anything that the account is allowed to do.
+    # It can be raised, for example in MCP server mode, where commands come from a client.
+    #
+    # @!method self.instance
+    #   Returns the singleton instance of Security
+    #   @return [Security] the singleton instance
+    class Security
+      include Singleton
+
+      # Security levels, from least to most restrictive
+      LEVELS = %i[low medium high].freeze
+      # Extended-value handlers restricted by security level, with the levels that allow them
+      EXTENDED_VALUE_LEVELS = {
+        ruby: %i[low],
+        uri:  %i[low],
+        env:  %i[low],
+        file: %i[low medium]
+      }.freeze
+      # Levels that allow processing a secret (e.g. by an extended value): the result could reveal it, as only declared values are hidden
+      SECRET_PROCESSING_LEVELS = %i[low].freeze
+      private_constant :EXTENDED_VALUE_LEVELS, :SECRET_PROCESSING_LEVELS
+
+      def initialize
+        reset
+      end
+
+      # Back to default: level `low`, no allowed path, not locked
+      # @return [nil]
+      def reset
+        @level = nil
+        @default_level = LEVELS.first
+        @allowed_paths = []
+        @locked = nil
+      end
+
+      # @return [Symbol] Level set by option `security`, else default level
+      def level = @level || @default_level
+
+      # Set by option `security`.
+      # When locked, the value can only be set again to the current one.
+      # @param value [Hash] `level` and `allowed_paths`, see schema `SecurityOptions`
+      # @return [nil]
+      def options=(value)
+        Aspera.assert_type(value, Hash, type: BadArgument) { 'security' }
+        # When locked, each command starts with the empty value of a Hash option: not a change
+        return if @locked && value.empty?
+        value = value.transform_keys(&:to_sym)
+        new_level = value[:level]&.to_sym
+        Aspera.assert_values(new_level, LEVELS, type: BadArgument) { 'security.level' } unless new_level.nil?
+        new_paths = Array(value[:allowed_paths]).map do |path|
+          path = File.expand_path(path)
+          Aspera.assert(File.exist?(path), type: BadArgument) { "security.allowed_paths: no such file or folder: #{path}" }
+          File.realpath(path)
+        end
+        if @locked
+          Aspera.assert((new_level || @default_level).eql?(level) && new_paths.eql?(@allowed_paths), type: BadArgument) do
+            "security cannot be changed #{@locked}"
+          end
+          return
+        end
+        @level = new_level
+        @allowed_paths = new_paths
+        nil
+      end
+
+      # Prevent further changes, e.g. by commands of an MCP client
+      # @param reason [String] For error messages, e.g. `in MCP server mode`
+      # @param default [Symbol, nil] Level if not set by option
+      # @return [nil]
+      def lock(reason, default: nil)
+        Aspera.assert_values(default, LEVELS) unless default.nil?
+        @default_level = default unless default.nil?
+        @locked = reason
+        nil
+      end
+
+      # @param handler [Symbol] Extended-value handler
+      # @raise [BadArgument] If the handler is refused at current level, with the level that allows it and where to set it
+      def check_extended_value(handler)
+        allowed = EXTENDED_VALUE_LEVELS[handler]
+        return if allowed.nil? || allowed.include?(level)
+        # the least permissive level that allows it
+        needed = handler.eql?(:file) ? "level #{allowed.last} with the file in security.allowed_paths" : "level #{allowed.last}"
+        raise BadArgument, "@#{handler}: extended value is disabled by security level #{level}: use #{needed} (#{where_to_set}), or give the value itself"
+      end
+
+      # A secret (e.g. read by `@vault:`, `@secret:`, `@preset:`) is hidden in results only as declared: the result of processing it
+      # could reveal it (e.g. split by `@list:`, in an error message of `@json:`, short value in a text by `@extend:`, converted as name of parameter).
+      # @param what [String] What processes the value, e.g. `@list`
+      # @param hint [String] What to do instead
+      # @yieldreturn [Boolean] `true` if the value contains a secret, evaluated only if the level refuses it
+      # @raise [BadArgument] If the value contains a secret and processing it is refused at current level
+      def check_secret_processing(what, hint: 'give the secret as the whole value')
+        return if SECRET_PROCESSING_LEVELS.include?(level) || !yield
+        raise BadArgument, "#{what}: cannot process a secret at security level #{level}, as the result could reveal it: #{hint}, or use level low (#{where_to_set})"
+      end
+
+      # At level `medium`, the real path is checked, so that neither `..` nor a symbolic link leads outside of allowed paths.
+      # A missing file gets the same error as a file outside allowed paths: no information on other files.
+      # @param path [String] Path of a file to read
+      # @return [String] Path to read
+      # @raise [BadArgument] If reading the file is refused at current level
+      def readable_path(path)
+        path = File.expand_path(path)
+        case level
+        when :low then path
+        when :medium
+          real_path = File.realpath(path) rescue nil
+          Aspera.assert(!real_path.nil? && @allowed_paths.any? { |allowed| real_path.eql?(allowed) || real_path.start_with?(File.join(allowed, '')) }, type: BadArgument) do
+            "no such file in security.allowed_paths: #{path}"
+          end
+          real_path
+        else raise BadArgument, "reading files is disabled by security level #{level}"
+        end
+      end
+
+      private
+
+      # @return [String] Where to set the level, for error messages
+      def where_to_set
+        @locked.nil? ? 'option security' : "option security when starting, as it cannot be changed #{@locked}"
+      end
+    end
+  end
+end

data/lib/aspera/cli/table_fitter.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'terminal-table'
+require 'unicode/display_width'
+
+module Aspera
+  module Cli
+    # Build a terminal table that fits in a given width, by wrapping cells.
+    # Columns with text (containing spaces, e.g. `description`) are wrapped first, the widest first.
+    # If not enough, other columns (names, identifiers) are wrapped too.
+    # If the table cannot fit, columns are narrowed to their minimum width.
+    module TableFitter
+      # Minimum width of a wrapped column with text
+      MIN_TEXT_WIDTH = 20
+      # Minimum width of other wrapped columns
+      MIN_WIDTH = 10
+      # ANSI style (zero width)
+      STYLE = /\e\[[0-9;]*m/
+      # Styles that reset all styles
+      RESETS = ["\e[0m", "\e[m"].freeze
+      # ANSI style or character
+      TOKEN = /#{STYLE}|\X/
+      # Long words are preferably broken after one of these characters
+      BREAK_AFTER = %r{[-_./,=]}
+      private_constant :MIN_TEXT_WIDTH, :MIN_WIDTH, :STYLE, :RESETS, :TOKEN, :BREAK_AFTER
+
+      class << self
+        # @param headings [Array]                 Column names
+        # @param rows     [Array<Array<String>>]  Rows of cells
+        # @param style    [Hash]                  `Terminal::Table` style
+        # @param width    [Integer, nil]          Maximum width of the table, or `nil` for natural width (not a `style` parameter)
+        # @return [Terminal::Table]
+        def table(headings:, rows:, style:, width:)
+          headings, rows = fit(headings, rows, width - overhead(headings.length, style)) unless width.nil?
+          Terminal::Table.new(headings: headings, rows: rows, style: style)
+        end
+
+        private
+
+        # @return [Integer] Width taken by borders and padding for a table with that number of columns
+        def overhead(column_count, style)
+          Terminal::Table.new(headings: [''] * column_count, style: style).to_s.lines.map { |line| display_width(line.chomp) }.max
+        end
+
+        # @param available [Integer] Width available for the content of all columns
+        # @return [Array] Headings and rows, wrapped to fit in available width, or as narrow as possible
+        def fit(headings, rows, available)
+          lines = [headings, *rows].map { |row| row.map(&:to_s) }
+          columns = lines.transpose
+          natural = columns.map { |cells| cells.flat_map { |cell| cell.split("\n") }.map { |line| display_width(line) }.max || 0 }
+          return [headings, rows] if natural.sum <= available
+          text = columns.map { |cells| cells.any? { |cell| cell.match?(/[ \t]/) } }
+          # Minimum width of a column, not narrower than its heading
+          floor = ->(i, min) { min.clamp(display_width(columns[i].first), natural[i]) }
+          # First wrap only columns with text, if not enough wrap all columns
+          text_only = natural.each_index.map { |i| text[i] ? floor.call(i, MIN_TEXT_WIDTH) : natural[i] }
+          all = natural.each_index.map { |i| floor.call(i, text[i] ? MIN_TEXT_WIDTH : MIN_WIDTH) }
+          minimum = text_only.sum <= available ? text_only : all
+          # Columns wider than `limit` are narrowed to it, but not below their minimum (`limit` is `-1` if the table cannot fit)
+          widths_for = ->(limit) { natural.zip(minimum).map { |nat, min| limit.clamp(min, nat) } }
+          limit = (0..natural.max).bsearch { |l| widths_for.call(l).sum > available } - 1
+          widths = widths_for.call(limit)
+          wrapped = lines.map { |row| row.each_with_index.map { |cell, i| wrap(cell, widths[i]) } }
+          [wrapped.first, wrapped.drop(1)]
+        end
+
+        # @return [String] Text with lines longer than width wrapped on spaces, and long words broken
+        def wrap(text, width)
+          text.split("\n").map do |line|
+            next line if display_width(line) <= width
+            wrapped = line.split.flat_map { |word| break_word(word, width) }.each_with_object([]) do |word, result|
+              if !result.empty? && display_width(result.last) + 1 + display_width(word) <= width
+                result[-1] = "#{result.last} #{word}"
+              else
+                result.push(word)
+              end
+            end
+            restyle(wrapped).join("\n")
+          end.join("\n")
+        end
+
+        # @return [Array<String>] Word split in pieces not wider than width, preferably after a punctuation
+        def break_word(word, width)
+          pieces = []
+          while display_width(word) > width
+            piece = +''
+            word.scan(TOKEN) do |token|
+              break if display_width(piece + token) > width && display_width(piece).positive?
+              piece << token
+            end
+            cut = piece.rindex(BREAK_AFTER)
+            piece = piece[0..cut] if cut && display_width(piece[0..cut]) > width / 2
+            pieces.push(piece)
+            word = word[piece.length..]
+          end
+          pieces.push(word)
+        end
+
+        # @return [Array<String>] Lines with ANSI styles closed at end of line, and open again on next line
+        def restyle(lines)
+          active = []
+          lines.map do |line|
+            result = active.join + line
+            line.scan(STYLE) { |style| RESETS.include?(style) ? active.clear : active.push(style) }
+            active.empty? ? result : "#{result}#{RESETS.first}"
+          end
+        end
+
+        # @return [Integer] Number of terminal columns used to display the string, ignoring ANSI escape sequences
+        def display_width(string)
+          Unicode::DisplayWidth.of(Terminal::Table::Util.ansi_escape(string))
+        end
+      end
+    end
+  end
+end

data/lib/aspera/cli/terminal_formatter.rb

@@ -20,52 +20,41 @@ module Aspera
         'HINT:'.bg(:green).white.blink
       end
 
-      # Format boolean with colored symbol (+/- or Y/ )
+      # Format boolean with colored check mark, or Y and space without Unicode
       def tick(yes)
-        result =
-          if Environment.terminal_supports_unicode?
-            yes ? "\u2713" : "\u2717"
-          else
-            yes ? 'Y' : ' '
-          end
+        result = Environment.char(yes ? '✓' : '✗')
         return result.green if yes
-        return result.red
+        result.red
       end
 
       # Format special values with colors (dim for empty, reverse for others)
       def special_format(what)
         result = "<#{what}>"
-        return %w[null empty].any? { |s| what.include?(s) } ? result.faint : result.inverse
-      end
-
-      # Prepare table row for terminal display (word wrap arrays)
-      def check_row(row)
-        row.each_key do |k|
-          row[k] = row[k].map { |i| WordWrap.ww(i.to_s, 120).chomp }.join("\n") if row[k].is_a?(Array)
-        end
+        %w[null empty].any? { |s| what.include?(s) } ? result.faint : result.inverse
       end
 
-      # Convert Markdown to terminal format (**bold** -> blue, `code` -> bold)
-      # @param match [MatchData, String]
-      def markdown_text(match)
-        if match.is_a?(String)
-          match = Markdown::FORMATS.match(match)
-          Aspera.assert(match, 'markdown text does not match any known format')
-        end
-        Aspera.assert_type(match, MatchData)
-        if match[:entity]
-          Aspera.assert_values(match[:entity], %w[bsol])
-          '\\'
-        elsif match[:bold]
-          match[:bold].to_s.blue
-        elsif match[:code]
-          match[:code].to_s.bold
-        else
-          Aspera.error_unexpected_value(match.to_s)
+      # Convert Markdown inline markup to terminal format (**bold** -> blue, `code` -> bold)
+      # @param text [String] text with Markdown inline markup
+      # @return [String] text with terminal formatting
+      def markdown_text(text)
+        text.to_s.gsub(Markdown::INLINE_MARKUP_RE) do
+          match = Regexp.last_match
+          if match[:entity]
+            case match[:entity]
+            when 'bsol' then '\\'
+            else Aspera.error_unexpected_value(match[:entity]) { 'HTML entity' }
+            end
+          elsif match[:bold]
+            match[:bold].to_s.blue
+          elsif match[:code]
+            match[:code].to_s.bold
+          else
+            Aspera.error_unexpected_value(match.to_s)
+          end
         end
       end
 
-      module_function :hint, :tick, :special_format, :check_row, :markdown_text
+      module_function :hint, :tick, :special_format, :markdown_text
     end
   end
 end

data/lib/aspera/cli/transfer_agent.rb

@@ -9,6 +9,7 @@ require 'aspera/cli/info'
 require 'aspera/cli/async_transfer_store'
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/secret_hider'
 require 'securerandom'
 
 module Aspera
@@ -252,11 +253,13 @@ module Aspera
         # updated transfer spec with command line
         transfer_spec.deep_merge!(@user_transfer_spec)
         # resolve pseudo-parameter: target_rate -> target_rate_kbps (overrides target_rate_kbps if both are present)
-        transfer_spec['target_rate_kbps'] = Transfer::Spec.rate_string_to_kbps(transfer_spec.delete('target_rate')) if transfer_spec.key?('target_rate')
+        Transfer::Spec.resolve_target_rate(transfer_spec)
         # recursively remove values that are nil (user wants to delete)
         transfer_spec.deep_do { |hash, key, value, _unused| hash.delete(key) if value.nil? }
         # if TS from app has content_protection (e.g. F5), that means content is protected: ask password if not provided
         transfer_spec['content_protection_password'] = @context.options.prompt_user_input('content protection password', sensitive: true) if transfer_spec['content_protection'].eql?('decrypt') && !transfer_spec.key?('content_protection_password')
+        # Secrets of transfer spec (e.g. `token` from the application) are hidden wherever they appear (logs, results)
+        SecretHider.instance.add_secrets_in(transfer_spec)
         # create transfer agent
         agent_instance.start_transfer(transfer_spec, token_regenerator: rest_token)
         # --- async mode ---