aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/cli/formatter.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 # cspell:ignore jsonpp
+require 'aspera/schema/registry'
 require 'aspera/cli/special_values'
+require 'aspera/cli/terminal_formatter'
 require 'aspera/preview/terminal'
 require 'aspera/secret_hider'
 require 'aspera/environment'
@@ -9,7 +11,6 @@ require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/markdown'
 require 'aspera/dot_container'
-require 'aspera/formatter_interface'
 require 'terminal-table'
 require 'tty-spinner'
 require 'yaml'
@@ -19,75 +20,8 @@ require 'word_wrap'
 
 module Aspera
   module Cli
-    # Terminal formatter with ANSI colors and Unicode support
-    # @see FormatterInterface
-    # @see MarkdownFormatter (in build/lib/doc_helper.rb)
-    module TerminalFormatter
-      include FormatterInterface
-
-      # Format boolean with colored symbol (✓/✗ or Y/ )
-      def tick(yes)
-        result =
-          if Environment.terminal_supports_unicode?
-            yes ? "\u2713" : "\u2717"
-          else
-            yes ? 'Y' : ' '
-          end
-        return result.green if yes
-        return 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.dim : result.reverse_color
-      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
-      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)
-        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)
-        end
-      end
-
-      module_function :tick, :special_format, :check_row, :markdown_text
-    end
-
     # Take care of CLI output on terminal
     class Formatter
-      # 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
-
       class << self
         # Replace special values with a readable version on terminal
         def replace_specific_for_terminal(input_hash, string_list_separator)
@@ -134,6 +68,17 @@ module Aspera
         @spinner = nil
       end
 
+      # Display item count if total is provided
+      def display_item_count(count, total)
+        return if total.nil?
+        count = count.to_i
+        total = total.to_i
+        return if total.eql?(0) && count.eql?(0)
+        count_msg = "Items: #{count}/#{total}"
+        count_msg = count_msg.bg_red unless count.eql?(total)
+        display_status(count_msg)
+      end
+
       def long_operation(title = nil, action: :spin)
         return unless Environment.terminal?
         return if %i[error data].include?(@options[:display])
@@ -164,28 +109,41 @@ module Aspera
         end
       end
 
-      def declare_options(options)
-        options.declare(:display, 'Output only some information', allowed: DISPLAY_LEVELS, handler: {o: self, m: :option_handler}, default: :data)
-        options.declare(:format, 'Output format', allowed: DISPLAY_FORMATS, handler: {o: self, m: :option_handler}, default: :table)
-        options.declare(:output, 'Destination for results', handler: {o: self, m: :option_handler})
-        options.declare(
-          :fields, "Comma separated list of: fields, or #{SpecialValues::ALL}, or #{SpecialValues::DEF}", handler: {o: self, m: :option_handler},
-          allowed: [String, Array, Regexp, Proc],
-          default: SpecialValues::DEF
-        )
-        options.declare(:select, 'Select only some items in lists: column, value', allowed: [Hash, Proc], handler: {o: self, m: :option_handler})
-        options.declare(:table_style, '(Table) Display style', allowed: [Hash], handler: {o: self, m: :option_handler}, default: {})
-        options.declare(:flat_hash, '(Table) Display deep values as additional keys', allowed: Allowed::TYPES_BOOLEAN, handler: {o: self, m: :option_handler}, default: true)
-        options.declare(
-          :multi_single, '(Table) Control how object list is displayed as single table, or multiple objects', allowed: %i[no yes single],
-          handler: {o: self, m: :option_handler}, default: :no
-        )
-        options.declare(:show_secrets, 'Show secrets on command output', allowed: Allowed::TYPES_BOOLEAN, handler: {o: self, m: :option_handler}, default: false)
-        options.declare(:image, 'Options for image display', allowed: Hash, handler: {o: self, m: :option_handler}, default: {})
+      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|
+          options.set_handler(opt, object: self, method: :option_handler)
+        end
+        nil
       end
 
-      # method accessed by option manager
-      # options are: format, output, display, fields, select, table_style, flat_hash, multi_single
+      # 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 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
       def option_handler(option_symbol, operation, value = nil)
         Aspera.assert_values(operation, %i[set get])
         case operation
@@ -206,7 +164,7 @@ module Aspera
             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
-            raise "Invalid parameter(s) for option image: #{unknown_options.join(', ')}, use #{allowed_options.join(', ')}" unless unknown_options.empty?
+            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]
         else Aspera.error_unreachable_line
@@ -214,10 +172,16 @@ module Aspera
         nil
       end
 
-      # Main output method
-      # data: for requested data, not displayed if level==error
-      # info: additional info, displayed if level==info
-      # error: always displayed on stderr
+      # Main output method for displaying messages to the user
+      # This method is used by Result classes to output formatted data
+      # @param message_level [Symbol] The level of the message - must be one of: :data, :info, :error
+      # @param message [String] The message to display
+      # @param hide_secrets [Boolean] Whether to hide secrets in the message (default: true)
+      # @return [nil]
+      # @note Message display behavior depends on the message_level:
+      #   - +:data+ messages are displayed unless display level is +:error+
+      #   - +:info+ messages are only displayed when display level is +:info+
+      #   - +:error+ messages are always displayed on stderr
       def display_message(message_level, message, hide_secrets: true)
         message = SecretHider.instance.hide_secrets_in_string(message) if hide_secrets && message.is_a?(String) && hide_secrets?
         case message_level
@@ -232,15 +196,7 @@ module Aspera
         display_message(:info, status, **kwargs)
       end
 
-      def display_item_count(number, total)
-        number = number.to_i
-        total = total.to_i
-        return if total.eql?(0) && number.eql?(0)
-        count_msg = "Items: #{number}/#{total}"
-        count_msg = count_msg.bg_red unless number.eql?(total)
-        display_status(count_msg)
-      end
-
+      # Check if secrets should be hidden
       def hide_secrets?
         !@options[:show_secrets] && !@options[:display].eql?(:data)
       end
@@ -250,118 +206,62 @@ module Aspera
         SecretHider.instance.deep_remove_secret(data) if hide_secrets?
       end
 
-      # Display results, especially the table format
-      # @param type [Symbol] Type of data
-      # @param data [Object] Data to display
-      # @param fields [Array<String>] List of fields to display
-      # @param total [Integer] Total number of items
-      # @param name [String] Name of the column to display
-      def display_results(type:, data: nil, fields: nil, total: nil, name: nil)
-        Log.log.debug{"display_results: type=#{type}"}
-        Log.dump(:data, data, level: :trace1)
-        Log.dump(:fields, fields, level: :trace1)
-        Aspera.assert_type(type, Symbol){'result must have type'}
-        Aspera.assert(!data.nil? || %i[empty nothing].include?(type)){'result must have data'}
-        display_item_count(data.length, total) unless total.nil?
-        hide_secrets(data)
-        data = SecretHider.instance.hide_secrets_in_string(data) if data.is_a?(String) && hide_secrets?
-        @options[:format] = :image if type.eql?(:image)
-        case @options[:format]
-        when :text
-          display_message(:data, data.to_s)
-        when :nagios
-          Nagios.process(data)
-        when :ruby
-          display_message(:data, PP.pp(filter_list_on_fields(data), +''))
-        when :json
-          display_message(:data, JSON.generate(filter_list_on_fields(data)))
-        when :jsonpp
-          display_message(:data, JSON.pretty_generate(filter_list_on_fields(data)))
-        when :yaml
-          display_message(:data, YAML.dump(filter_list_on_fields(data)))
-        when :image
-          # if object or list, then must be a single
-          case type
-          when :single_object, :object_list
-            data = [data] if type.eql?(:single_object)
-            raise BadArgument, 'image display requires a single result' unless data.length == 1
-            fields = compute_fields(data, fields)
-            raise BadArgument, 'select a single field to display' unless fields.length == 1
-            data = data.first
-            raise BadArgument, 'no such field' unless data.key?(fields.first)
-            data = data[fields.first]
-          end
-          Aspera.assert_type(data, String){'URL or blob for image'}
-          # Check if URL
-          data =
-            begin
-              # just validate
-              URI.parse(data)
-              if Environment.instance.url_method.eql?(:text)
-                UriReader.read(data)
-              else
-                Environment.instance.open_uri(data)
-                display_message(:info, "Opened URL in browser: #{data}")
-                :done
-              end
-            rescue URI::InvalidURIError
-              data
-            end
-          # try base64
-          data = begin
-            Base64.strict_decode64(data)
-          rescue
-            data
-          end
-          # here, data is the image blob
-          display_message(:data, Preview::Terminal.build(data, **@options[:image].symbolize_keys)) unless data.eql?(:done)
-        when :table, :csv
-          case type
-          when :single_object
-            # :single_object is a Hash, where key=column name
-            Aspera.assert_type(data, Hash){'result'}
-            if data.empty?
-              display_message(:data, TerminalFormatter.special_format('empty dict'))
-            else
-              data = DotContainer.new(data).to_dotted if @options[:flat_hash]
-              display_table([data], compute_fields([data], fields), single: true)
-            end
-          when :object_list
-            # :object_list is an Array of Hash, where key=column name
-            Aspera.assert_array_all(data, Hash){'result'}
-            data = data.map{ |obj| DotContainer.new(obj).to_dotted} if @options[:flat_hash]
-            display_table(data, compute_fields(data, fields), single: type.eql?(:single_object))
-          when :value_list
-            # :value_list is a simple array of values, name of column provided in `name`
-            display_table(data.map{ |i| {name => i}}, [name])
-          when :special # no table
-            if data.eql?(:nothing)
-              Log.log.debug('no result expected')
-              return
-            end
-            display_message(:info, TerminalFormatter.special_format(data.to_s))
-            return
-          when :status # no table
-            # :status displays a simple message
-            display_message(:info, data)
-          when :text # no table
-            # :status displays a simple message
-            display_message(:data, data)
-          else Aspera.error_unexpected_value(type){'data type'}
-          end
-        else Aspera.error_unexpected_value(@options[:format]){'format'}
-        end
+      # Display results using the Visitor pattern
+      # Each Result subclass knows how to format itself by calling the appropriate
+      # formatter method, eliminating the need for type checking in the formatter.
+      # @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'}
+
+        Log.log.debug{"display_results: result class=#{result.class.name}"}
+        Log.dump(:data, result.data, level: :trace1)
+        Log.dump(:fields, result.fields, level: :trace1)
+
+        # Hide secrets in data
+        hide_secrets(result.data)
+
+        # Use the Visitor pattern: delegate formatting to the result object
+        result.format(self)
       end
-      #==========================================================================================
+      # Public methods exposed to Result classes for formatting
 
-      private
+      # Get the current format type
+      def format_type
+        @options[:format]
+      end
 
-      # @return all fields of all objects in list of objects
+      # Set the format type (used by Image result)
+      def format_type=(format)
+        @options[:format] = format
+      end
+
+      # Hide secrets in a string
+      def hide_secrets_in_string(string)
+        SecretHider.instance.hide_secrets_in_string(string)
+      end
+
+      # Get special format string
+      def special_format(text)
+        TerminalFormatter.special_format(text)
+      end
+
+      # Check if flat_hash option is enabled
+      def flat_hash?
+        @options[:flat_hash]
+      end
+
+      # Get image options
+      def image_options
+        @options[:image].symbolize_keys
+      end
+
+      # @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
       end
 
-      # @return the list of fields to display
+      # @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)
@@ -427,7 +327,7 @@ module Aspera
         when Proc
           begin
             data.select!{ |i| @options[:select].call(i)}
-          rescue Exception => e # rubocop:disable Lint/RescueException
+          rescue StandardError => e
             raise Cli::BadArgument, "Error in user-provided ruby lambda code during select: #{e.message}"
           end
         when Hash
@@ -470,7 +370,7 @@ module Aspera
         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?)}
-        # here : fields : list of column names
+        # fields: list of column names to display
         case @options[:format]
         when :table
           format_style[:border] = :unicode_round if Environment.terminal_supports_unicode?
@@ -506,6 +406,19 @@ 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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/version'
+require 'aspera/cli/info'
+require 'aspera/environment'
+require 'aspera/persistency_action_once'
+require 'aspera/rest'
+require 'aspera/log'
+require 'date'
+
+module Aspera
+  module Cli
+    # Mixin providing gem version-check functionality to Plugin::Config.
+    # Depends on `options` and `persistency` being available in the including class.
+    module GemChecker
+      GEM_CHECK_DATE_FMT = '%Y/%m/%d'
+
+      # @return [Hash] current vs latest gem version info
+      def check_gem_version
+        latest_version =
+          begin
+            Rest.new(base_url: 'https://rubygems.org/api/v1').read("versions/#{Info::GEM_NAME}/latest.json")['version']
+          rescue StandardError
+            Log.log.warn('Could not retrieve latest gem version on rubygems.')
+            '0'
+          end
+        if Gem::Version.new(Environment.ruby_version) < Gem::Version.new(Info::RUBY_FUTURE_MINIMUM_VERSION)
+          Log.log.warn do
+            "Note that a future version will require Ruby version #{Info::RUBY_FUTURE_MINIMUM_VERSION} at minimum, " \
+              "you are using #{Environment.ruby_version}"
+          end
+        end
+        return {
+          name:        Info::GEM_NAME,
+          current:     Cli::VERSION,
+          latest:      latest_version,
+          need_update: Gem::Version.new(Cli::VERSION) < Gem::Version.new(latest_version)
+        }
+      end
+
+      # Check periodically if a newer gem version is available; log a warning if so.
+      # Called once per run by Runner, before command execution.
+      def periodic_check_newer_gem_version
+        delay_days = options.get_option(:version_check_days, mandatory: true).to_i
+        return if delay_days.eql?(0)
+        last_check_array = []
+        check_date_persist = PersistencyActionOnce.new(
+          manager: persistency,
+          data:    last_check_array,
+          id:      'version_last_check'
+        )
+        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}"}
+        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
+        check_data = check_gem_version
+        Log.log.warn do
+          "A new version is available: #{check_data[:latest]}. You have #{check_data[:current]}. Upgrade with: gem update #{check_data[:name]}"
+        end if check_data[:need_update]
+      end
+    end
+  end
+end

data/lib/aspera/cli/hints.rb

@@ -129,6 +129,7 @@ module Aspera
       class << self
         # @param error [Exception] exception object
         def hint_for(error, formatter)
+          # Loop on known error hints
           ERROR_HINTS.each do |hint|
             next unless error.is_a?(hint[:exception])
             message = error.message
@@ -141,12 +142,11 @@ module Aspera
                 next unless message.eql?(m)
               when Regexp
                 next unless message.match?(m)
-              else Aspera.error_unexpected_value(m)
+              else Aspera.error_unexpected_value(m){'hint match'}
               end
               hint[:remediation].each do |r|
                 Log.log.info{"#{'HINT:'.bg_green.gray.blink.freeze} #{r}"}
               end
-              break
             end
           end
         end