aspera-cli 4.27.2 → 4.27.4

data/lib/aspera/cli/preset_manager.rb

@@ -9,6 +9,8 @@ require 'aspera/assert'
 require 'aspera/yaml'
 require 'digest'
 require 'yaml'
+require 'aspera/rainbow'
+using Rainbow
 
 module Aspera
   module Cli
@@ -57,30 +59,38 @@ module Aspera
 
       # Read and validate the YAML config file.
       # Sets @config_presets and @checksum_on_disk.
+      # A file that cannot be read (YAML error, duplicate keys, access) is left untouched: it shall be fixed.
+      # A file with an unexpected structure is renamed for manual conversion, and a new one is created next time.
       def read_config_file
         Log.log.debug { "config file is: #{@config_file}".red }
         if File.exist?(@config_file)
           Log.log.debug { "loading #{@config_file}" }
-          @config_presets   = Yaml.safe_load(File.read(@config_file))
+          begin
+            @config_presets = Yaml.safe_load(File.read(@config_file))
+          rescue Psych::SyntaxError
+            Log.log.error { "YAML error in config file: #{@config_file}" }
+            raise
+          rescue StandardError => e
+            raise Cli::Error, "Config file #{@config_file}: #{e.message}"
+          end
           @checksum_on_disk = checksum
         else
           Log.log.warn { "No config file found. New configuration file: #{@config_file}" }
           @config_presets = {Key::CONFIG => {Key::VERSION => 'new file'}}
           # @checksum_on_disk remains nil: will be saved on first write
         end
-        validate_config_presets!
-      rescue Psych::SyntaxError => e
-        Log.log.error('YAML error in config file')
-        raise e
-      rescue StandardError => e
-        Log.log.debug { "-> #{e.class.name} : #{e}" }
-        if File.exist?(@config_file)
-          new_name = "#{@config_file}.pre#{Cli::VERSION}.manual_conversion_needed"
-          File.rename(@config_file, new_name)
-          Log.log.warn { "Renamed config file to #{new_name}." }
-          Log.log.warn('Manual Conversion is required. Next time, a new empty file will be created.')
+        begin
+          validate_config_presets!
+        rescue StandardError => e
+          Log.log.debug { "-> #{e.class.name} : #{e}" }
+          if File.exist?(@config_file)
+            new_name = "#{@config_file}.pre#{Cli::VERSION}.manual_conversion_needed"
+            File.rename(@config_file, new_name)
+            Log.log.warn { "Renamed config file to #{new_name}." }
+            Log.log.warn('Manual Conversion is required. Next time, a new empty file will be created.')
+          end
+          raise Cli::Error, e.to_s
         end
-        raise Cli::Error, e.to_s
       end
 
       # Save to disk only if content changed since last load/save.
@@ -113,8 +123,8 @@ module Aspera
           Log.log.error do
             "Default config name [#{default_name}] specified for plugin [#{plugin_name_sym}], but it does not exist in config file.\n" \
               "Please fix: either create preset:\n" \
-              "#{Info::CMD_NAME} config id #{default_name} init @json:'{}'\n" \
-              "or remove default:\n#{Info::CMD_NAME} config id default remove #{plugin_name_sym}"
+              "#{Info::CMD_NAME} config preset initialize #{default_name} @json:'{}'\n" \
+              "or remove default:\n#{Info::CMD_NAME} config preset unset #{Key::DEFAULTS} #{plugin_name_sym}"
           end
           raise Cli::Error, "No such preset: #{default_name}"
         end
@@ -130,7 +140,11 @@ module Aspera
         Aspera.assert(!include_path.include?(config_name), type: Cli::Error) { 'loop in include' }
         include_path = include_path.clone
         current = @config_presets
-        config_name.split(PRESET_DIG_SEPARATOR).each do |name|
+        # A preset name may contain a dot (e.g. a host name): the longest name of an existing preset is used
+        parts = config_name.split(PRESET_DIG_SEPARATOR)
+        count = parts.length.downto(1).find { |n| @config_presets.key?(parts.first(n).join(PRESET_DIG_SEPARATOR)) } || 1
+        names = [parts.first(count).join(PRESET_DIG_SEPARATOR)] + parts.drop(count)
+        names.each do |name|
           Aspera.assert_type(current, Hash, type: Cli::Error) { "sub key: #{include_path}" }
           include_path.push(name)
           current = current[name]
@@ -186,16 +200,27 @@ module Aspera
         nil
       end
 
-      # @return [String] name of the global default preset, creating it if needed
-      def global_default_preset
+      # @param create [Boolean] `true`: declare and create the global default preset if needed (to write in it)
+      # @return [String] name of the global default preset
+      def global_default_preset(create: true)
         result = plugin_default_name(CONF_GLOBAL_SYM)
         if result.nil?
           result = Key::GLOBAL
-          set_key(Key::DEFAULTS, CONF_GLOBAL_SYM, result)
+          if create
+            set_key(Key::DEFAULTS, CONF_GLOBAL_SYM, result)
+            # A default declaration requires the preset to exist
+            @config_presets[result] ||= {}
+          end
         end
         result
       end
 
+      # @return [Boolean] true if `preset_name` is declared as the global default preset (does not create it)
+      def global_preset?(preset_name)
+        defaults = @config_presets[Key::DEFAULTS]
+        defaults.is_a?(Hash) && defaults[CONF_GLOBAL_SYM.to_s].eql?(preset_name)
+      end
+
       # Set param in the global defaults preset
       def set_global_default(key, value)
         set_key(global_default_preset, key, value)

data/lib/aspera/cli/prompt.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'io/console'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Console input
+    module Prompt
+      # Prompt user for console input
+      # The prompt is displayed on `stderr`, like for sensitive input, so that `stdout` contains only results.
+      # @param prompt [String]  prompt string to display
+      # @param sensitive [Boolean] whether to hide typed input
+      # @return [String] user input stripped of trailing newline
+      def prompt_user_input(prompt, sensitive: false)
+        return $stdin.getpass("#{prompt}> ") if sensitive
+        $stderr.print("#{prompt}> ")
+        line = $stdin.gets
+        Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
+        line.chomp
+      end
+
+      # Prompt user for input in a list of symbols
+      # @param prompt [String] prompt to display
+      # @param sym_list [Array] list of symbols to select from
+      # @return [Symbol] selected symbol
+      def prompt_user_input_in_list(prompt, sym_list)
+        loop do
+          input = prompt_user_input(prompt).to_sym
+          return input if sym_list.any? { |a| a.eql?(input) }
+          $stderr.puts("No such #{prompt}: #{input}, select one of: #{sym_list.join(', ')}") # rubocop:disable Style/StderrPuts
+        end
+      end
+    end
+  end
+end

data/lib/aspera/cli/result.rb

@@ -20,9 +20,11 @@ module Aspera
     class Result
       attr_reader :data, :fields
 
-      # @param data [Object,nil] The result data
-      # @param fields [Object] Specification of fields to include
+      # @param data [nil, Object] The result data
+      # @param fields [nil, Array<String>, Proc] Specification of fields to include
       def initialize(data: nil, fields: nil)
+        Aspera.assert_type(fields, NilClass, Array, Proc)
+        Aspera.assert_array_all(fields, String) if fields.is_a?(Array)
         @data = data
         @fields = fields
       end
@@ -39,18 +41,9 @@ module Aspera
         # Apply field filtering once for formats that need it
         filtered_data = formatter.filter_list_on_fields(@data)
         case formatter.format_type
-        when :text
-          formatter.display_message(:data, @data.to_s)
-        when :nagios
-          Nagios.process(@data)
-        when :ruby
-          formatter.display_message(:data, PP.pp(filtered_data, +''))
-        when :json
-          formatter.display_message(:data, JSON.generate(filtered_data))
-        when :jsonpp
-          formatter.display_message(:data, JSON.pretty_generate(filtered_data))
-        when :yaml
-          formatter.display_message(:data, YAML.dump(filtered_data))
+        when :nagios then Nagios.process(@data)
+        when :text   then formatter.display_message(:data, @data.to_s)
+        when *STRUCTURED_FORMATS then display_structured(formatter, filtered_data)
         when :image
           if @data.nil?
             formatter.display_message(:data, formatter.special_format('null (no image)'))
@@ -82,10 +75,30 @@ module Aspera
             # here, data is the image blob
             formatter.display_message(:data, Preview::Terminal.build(data, **formatter.image_options))
           end
-        else
-          Aspera.error_unexpected_value(formatter.format_type) { 'format' }
+        else Aspera.error_unexpected_value(formatter.format_type) { 'format' }
         end
       end
+
+      # Formats rendering the data structure itself
+      STRUCTURED_FORMATS = %i[ruby json jsonpp yaml].freeze
+
+      private
+
+      # Display a value in one of STRUCTURED_FORMATS
+      # @param formatter [Formatter] The formatter to use
+      # @param value     [Object]    Value to render
+      # @return [nil]
+      def display_structured(formatter, value)
+        text =
+          case formatter.format_type
+          when :ruby   then PP.pp(value, +'')
+          when :json   then JSON.generate(value)
+          when :jsonpp then JSON.pretty_generate(value)
+          when :yaml   then YAML.dump(value)
+          else Aspera.error_unexpected_value(formatter.format_type) { 'structured format' }
+          end
+        formatter.display_message(:data, text)
+      end
     end
 
     # Special result types - each has its own class
@@ -101,8 +114,11 @@ module Aspera
 
         def format(formatter)
           case formatter.format_type
-          when :text, :nagios, :ruby, :json, :jsonpp, :yaml
+          when :text, :nagios
             formatter.display_message(:data, @data.to_s)
+          when *STRUCTURED_FORMATS
+            # An empty list, or no value
+            display_structured(formatter, @data.eql?(:empty) ? [] : nil)
           when :table, :csv
             if @data.eql?(:nothing)
               Log.log.debug('no result expected')
@@ -137,8 +153,10 @@ module Aspera
         def format(formatter)
           data = formatter.hide_secrets? ? formatter.hide_secrets_in_string(@data) : @data
           case formatter.format_type
-          when :text, :nagios, :ruby, :json, :jsonpp, :yaml
+          when :text, :nagios
             formatter.display_message(:data, data)
+          when *STRUCTURED_FORMATS
+            display_structured(formatter, data)
           when :table, :csv
             formatter.display_message(:info, data)
           else
@@ -166,14 +184,8 @@ module Aspera
           case formatter.format_type
           when :text, :nagios
             formatter.display_message(:data, data.to_s)
-          when :ruby
-            formatter.display_message(:data, PP.pp(data, +''))
-          when :json
-            formatter.display_message(:data, JSON.generate(data))
-          when :jsonpp
-            formatter.display_message(:data, JSON.pretty_generate(data))
-          when :yaml
-            formatter.display_message(:data, YAML.dump(data))
+          when *STRUCTURED_FORMATS
+            display_structured(formatter, data)
           when :table, :csv
             formatter.display_message(:data, data)
           else
@@ -228,7 +240,7 @@ module Aspera
       end
 
       # Object list result (Array of Hash)
-      # @note The +total+ parameter is used to display pagination information (e.g., "Items: 10/100")
+      # @note The `total` parameter is used to display pagination information (e.g., "Items: 10/100")
       class ObjectList < Result
         attr_reader :total
 
@@ -276,14 +288,8 @@ module Aspera
             formatter.display_table(@data.map { |i| {@name => i} }, [@name])
           when :text
             formatter.display_message(:data, @data.join("\n"))
-          when :ruby
-            formatter.display_message(:data, PP.pp(@data, +''))
-          when :json
-            formatter.display_message(:data, JSON.generate(@data))
-          when :jsonpp
-            formatter.display_message(:data, JSON.pretty_generate(@data))
-          when :yaml
-            formatter.display_message(:data, YAML.dump(@data))
+          when *STRUCTURED_FORMATS
+            display_structured(formatter, @data)
           else
             super
           end
@@ -299,7 +305,7 @@ module Aspera
         # @param id_result [String] Key in the result Hash used as item identifier
         # @param fields   [Object] Fields hint passed to the Result constructor (non-bulk only, when not :default)
         # @param bfail    [Boolean] When true, re-raise errors; when false, capture them as a status string
-        # @yieldparam item [Object] Each item in +items+
+        # @yieldparam item [Object] Each item in `items`
         # @yieldreturn [Hash, Array, nil] REST response; a Hash replaces the default id-keyed result
         # @return [Result::ObjectList, Result::SingleObject]
         def bulk(items, is_bulk:, command:, id_result: 'id', fields: :default, bfail: true)

data/lib/aspera/cli/runner.rb

@@ -166,7 +166,7 @@ module Aspera
         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 RestCallError => e;                  exception_info = {e: e, t: 'Rest'}
+        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}
@@ -228,29 +228,19 @@ module Aspera
         Result::Text.new(usage_text(plugin: plugin))
       end
 
-      # Composite option handler for the `log` option (dot-notation sub-properties).
-      # Supported sub-properties: +level+, +type+, +format+
-      # @param _option_sym [Symbol] Option name (unused, always :log)
-      # @param operation   [Symbol] +:set+ or +:get+
-      # @param value       [Hash,nil] Hash of sub-properties to set (only for +:set+)
-      def option_log(_option_sym, operation, value = nil)
-        Aspera.assert_values(operation, %i[set get])
-        case operation
-        when :set
-          Aspera.assert_type(value, Hash)
-          value.each do |k, v|
-            case k.to_sym
-            when :level   then Log.instance.level = v.to_sym
-            when :type    then Log.instance.logger_type = v.to_sym
-            when :format  then Log.instance.formatter = v
-            when :secrets then SecretHider.instance.log_secrets = BoolValue.true?(v)
-            else Aspera.error_unexpected_value(k) { 'log sub-option (level, type, format, secrets)' }
-            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)
+        Aspera.assert_type(value, Hash)
+        value.each do |k, v|
+          case k.to_sym
+          when :level   then Log.instance.level = v.to_sym
+          when :type    then Log.instance.logger_type = v.to_sym
+          when :format  then Log.instance.formatter = v
+          when :secrets then SecretHider.instance.log_secrets = Parser.get_from_list(v.to_s, 'log secrets', BoolValue::ALL)
+          else Aspera.error_unexpected_value(k) { 'log sub-option (level, type, format, secrets)' }
           end
-        when :get
-          return {level: Log.instance.level, type: Log.instance.logger_type, format: Log.instance.formatter, secrets: SecretHider.instance.log_secrets}
         end
-        nil
       end
 
       private
@@ -279,25 +269,11 @@ module Aspera
           registry = plugin.class.command_registry
           cmds     = registry.children_of(path)
           label    = plugin.class.name.split('::').last.downcase
-          # Build label with positional argument slots inserted after each intermediate node
+          # Build label with positional argument slots inserted after each command
           # e.g. [:access_keys, :do, :download] -> "node access_keys do <access_key_id> download"
-          path.each_with_index do |seg, i|
-            label += " #{seg}"
-            seg_path = path[0..i]
-            seg_spec = registry[seg_path]
-            if seg_spec && registry.children_of(seg_path).any? && seg_spec.arguments
-              seg_spec.arguments.each do |arg_spec|
-                label += " <#{arg_spec.name}>"
-              end
-            end
-          end
-          if cmds.none?
-            leaf_spec = registry[path]
-            leaf_spec&.arguments&.each do |arg_spec|
-              argument = arg_spec.mandatory ? "<#{arg_spec.name}>" : "[#{arg_spec.name}]"
-              argument += '...' if arg_spec.multiple
-              label += " #{argument}"
-            end
+          path.each_index do |i|
+            label += " #{path[i]}"
+            registry.arguments_at(path[0..i]).each { |arg_spec| label += " #{arg_spec.syntax}" }
           end
           if cmds.any?
             # Intermediate node: show current command + description, then list subcommands
@@ -314,7 +290,7 @@ module Aspera
             spec = registry[path]
             lines << "\nCOMMAND: #{label}"
             lines << "    #{spec.description}" if spec&.description
-            display_args = spec&.arguments || []
+            display_args = registry.arguments_at(path)
             # transfer_paths commands use --sources for the file list; default is positional args (@args)
             if spec&.transfer_paths
               file_desc = if spec.transfer_paths == :receive
@@ -372,9 +348,7 @@ module Aspera
         # Create command line manager with arguments
         @context.options = Parser.new(Info::CMD_NAME, @argv)
         ExtendedValue.instance.on(EXTEND_ARGS) { |v| @context.options.args_as_extended(v) }
-        # Formatter: declare metadata (class method), then bind to the instance
-        Formatter.declare_options(@context.options)
-        @context.formatter.bind_options(@context.options)
+        @context.formatter.declare_options(@context.options)
         # Compare $0 with expected name
         current_prog_name = File.basename($PROGRAM_NAME)
         Aspera.assert(current_prog_name.eql?(Info::CMD_NAME), type: :warn) { "Please use '#{Info::CMD_NAME}' instead of '#{current_prog_name}'" }
@@ -395,15 +369,13 @@ module Aspera
         @context.config = Plugins::Config.new(context: @context)
         @context.man_header = true
         # Sync cache_tokens from Config into the OAuth persist_mgr (now that option is parsed)
-        OAuth::Factory.instance.persist_mgr = @context.persistency if @context.config.option_cache_tokens
+        OAuth::Factory.instance.persist_mgr = @context.persistency if @context.options.get_option(:cache_tokens)
         # Email service: depends on options declared by Config
         @context.mailer = Mailer.new(@context.options, @context.main_folder)
         # Secret finder: depends on options (:secret) and presets, both set by Bootstrapper
         @context.secret_finder = SecretFinder.new(@context.options, @context.presets)
         # The TransferAgent plugin may use the @preset parser
         @context.transfer = TransferAgent.new(@context)
-        # Add commands for config plugin after all options have been added
-        @context.config.add_manual_header(false)
         @context.validate
         # Set banner when all environment is created so that additional extended value modifiers are known, e.g. @preset
       end
@@ -450,32 +422,33 @@ module Aspera
         Log.log.debug('declare_global_options')
         @context.options.declare(:help, description: 'Show this message', allowed: Type::NONE, short: 'h') do
           @option_help = true
-          @context.options.help_requested = true
+          @context.help_requested = true
         end
         @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,
-          handler: {o: Environment.instance, m: :url_method}
+          allowed: USER_INTERFACES, default: Environment.instance.url_method,
+          on_set: Environment.instance.method(:url_method=)
         )
         @context.options.declare(
           :invalid_characters, description: 'Replacement character and invalid filename characters',
-          handler: {o: Environment.instance, m: :file_illegal_characters}
+          default: Environment.instance.file_illegal_characters,
+          on_set: Environment.instance.method(:file_illegal_characters=)
         )
-        @context.options.declare(:log_level, description: 'Log level', allowed: Log::LEVELS, handler: {o: Log.instance, m: :level})
-        @context.options.declare(:log_format, description: 'Log formatter', allowed: [Proc, Logger::Formatter, String], handler: {o: Log.instance, m: :formatter})
-        @context.options.declare(:logger, description: 'Logging method', allowed: Log::LOG_TYPES, handler: {o: Log.instance, m: :logger_type})
-        @context.options.declare(:log, description: 'Logging options (dot-notation: level, type, format, secrets)', handler: {o: self, m: :option_log}, schema: Schema::Registry::LOG_OPTIONS)
+        @context.options.declare(:log_level, description: 'Log level', allowed: Log::LEVELS, default: Log.instance.level, on_set: Log.instance.method(:level=))
+        @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(: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, handler: {o: SecretHider.instance, m: :log_secrets})
-        @context.options.declare(:clean_temp, description: 'Cleanup temporary files on exit', allowed: Type::BOOLEAN, handler: {o: TempFileManager.instance, m: :cleanup_on_exit})
-        @context.options.declare(:temp_folder, description: 'Temporary folder', handler: {o: TempFileManager.instance, m: :global_temp})
+        @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(:pid_file, description: 'Write process identifier to file, delete on exit')
         @context.options.declare(
           :parser, description: 'Default parser for structured parameters and options',
-          handler: {o: ExtendedValue.instance, m: :default_decoder},
+          on_set: ExtendedValue.instance.method(:default_decoder=),
           allowed: ExtendedValue::DEFAULT_DECODERS,
           default: ExtendedValue::DEFAULT_DECODERS.first
         )

data/lib/aspera/cli/special_values.rb

@@ -5,10 +5,15 @@ module Aspera
     # base class for plugins modules
     module SpecialValues
       # special values
+      # `INIT` to unitialize with all current IDs
       INIT = 'INIT'
+      # `ALL` means "all ids"
       ALL = 'ALL'
+      # `DEF` for the default list
       DEF = 'DEF'
+      # `END` of arguments
       EOA = 'END'
+      # `LATEST`
       LATEST = 'LATEST'
     end
   end

data/lib/aspera/cli/sync_actions.rb

@@ -16,29 +16,63 @@ module Aspera
         %w[Syncd Error Confl Pconf] +
         (23..24).map { |i| "P(#{i})" }).freeze
       # Positional arguments shared by sync transfer commands (push/pull/bidi) and sync admin commands.
-      PATH_AND_INFO_ARGS = [{name: :path, type: String}, {name: :sync_info, type: Hash, mandatory: false, default: {}}].freeze
-      # Names of the leaf commands registered under any `sync admin` node.
-      ADMIN_COMMANDS = %i[find status meta counters file_info overview query].freeze
+      PATH_AND_INFO_ARGS = [{name: :path}, {name: :sync_info, type: Hash, mandatory: false, default: {}}].freeze
       # When a plugin class includes SyncActions, register the :sql option
-      # in that class's DSL registry so Base#initialize auto-declares it.
+      # in that class's DSL registry so Base#initialize auto-declares it,
+      # and add the class-level DSL methods of ClassMethods.
       class << self
         def included(base)
           base.option(:sql, description: 'SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)')
+          base.extend(ClassMethods)
         end
+      end
 
-        # DSL helper: register the 7 `sync admin` leaf commands under the given parent path.
-        # Called at class-load time from any plugin that includes SyncActions.
-        # @param base        [Class]          the plugin class (receiver of DSL methods)
-        # @param admin_path  [Symbol, Array<Symbol>]  path relative to current scope, e.g. :admin
-        def register_sync_admin_commands(base, admin_path)
-          base.commands_under(admin_path) do
-            base.command(:find,      description: 'Find sync database files',     arguments: [{name: :path, type: String}], action: :action_sync_admin_find)
-            base.command(:status,    description: 'Show sync session status',     arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_status)
-            base.command(:meta,      description: 'Show sync session metadata',   arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_meta)
-            base.command(:counters,  description: 'Show sync counters',           arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_counters)
-            base.command(:file_info, description: 'Show per-file sync state',     arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_file_info)
-            base.command(:overview,  description: 'Show sync database overview',  arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_overview)
-            base.command(:query,     description: 'Execute a raw SQL query',      arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_query)
+      # Class-level DSL methods added to the plugin class that includes SyncActions.
+      module ClassMethods
+        # DSL class method: declare the `sync admin` node and its 7 leaf commands.
+        # @param parent [Symbol, Array<Symbol>] path relative to current scope, e.g. :admin
+        def sync_admin_commands(parent)
+          commands_under(parent, description: 'Manage sync database (admin operations)') do
+            command(
+              :find, description: 'Find sync database files', arguments: [{name: :path}],
+              action: lambda do |path:, **|
+                dbs = Sync::Operations.list_db_files(path)
+                Result::ObjectList.new(dbs.keys.map { |n| {name: n, path: dbs[n]} })
+              end
+            )
+            command(
+              :status, description: 'Show sync session status', arguments: PATH_AND_INFO_ARGS,
+              action: ->(path:, sync_info: {}, **) { Result::SingleObject.new(Sync::Operations.admin_status(async_info_from_args(path: path, sync_info: sync_info))) }
+            )
+            command(
+              :meta, description: 'Show sync session metadata', arguments: PATH_AND_INFO_ARGS,
+              action: lambda do |path:, sync_info: {}, **|
+                require 'aspera/sync/database'
+                Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).meta(options.get_option(:sql)))
+              end
+            )
+            command(
+              :counters, description: 'Show sync counters', arguments: PATH_AND_INFO_ARGS,
+              action: lambda do |path:, sync_info: {}, **|
+                require 'aspera/sync/database'
+                Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).counters(options.get_option(:sql)))
+              end
+            )
+            command(:file_info, description: 'Show per-file sync state', arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_file_info)
+            command(
+              :overview, description: 'Show sync database overview', arguments: PATH_AND_INFO_ARGS,
+              action: lambda do |path:, sync_info: {}, **|
+                require 'aspera/sync/database'
+                Result::ObjectList.new(db_from_args(path: path, sync_info: sync_info).overview, fields: %w[table name type])
+              end
+            )
+            command(
+              :query, description: 'Execute a raw SQL query', arguments: PATH_AND_INFO_ARGS,
+              action: lambda do |path:, sync_info: {}, **|
+                require 'aspera/sync/database'
+                Result.auto(db_from_args(path: path, sync_info: sync_info).execute(options.get_option(:sql, mandatory: true)))
+              end
+            )
           end
         end
       end
@@ -119,25 +153,6 @@ module Aspera
         Sync::Database.new(Sync::Operations.session_db_file(sync_info))
       end
 
-      def action_sync_admin_status(path:, sync_info: {}, **)
-        Result::SingleObject.new(Sync::Operations.admin_status(async_info_from_args(path: path, sync_info: sync_info)))
-      end
-
-      def action_sync_admin_find(path:, **)
-        dbs = Sync::Operations.list_db_files(path)
-        Result::ObjectList.new(dbs.keys.map { |n| {name: n, path: dbs[n]} })
-      end
-
-      def action_sync_admin_meta(path:, sync_info: {}, **)
-        require 'aspera/sync/database'
-        Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).meta(options.get_option(:sql)))
-      end
-
-      def action_sync_admin_counters(path:, sync_info: {}, **)
-        require 'aspera/sync/database'
-        Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).counters(options.get_option(:sql)))
-      end
-
       def action_sync_admin_file_info(path:, sync_info: {}, **)
         require 'aspera/sync/database'
         result = db_from_args(path: path, sync_info: sync_info).file_info(options.get_option(:sql))
@@ -147,16 +162,6 @@ module Aspera
         Result::ObjectList.new(result, fields: %w[sstate record_id f_meta_path message])
       end
 
-      def action_sync_admin_overview(path:, sync_info: {}, **)
-        require 'aspera/sync/database'
-        Result::ObjectList.new(db_from_args(path: path, sync_info: sync_info).overview, fields: %w[table name type])
-      end
-
-      def action_sync_admin_query(path:, sync_info: {}, **)
-        require 'aspera/sync/database'
-        Result.auto(db_from_args(path: path, sync_info: sync_info).execute(options.get_option(:sql, mandatory: true)))
-      end
-
       # Execute a sync transfer for a given direction.
       # @param direction [Symbol]    one of Sync::Operations::DIRECTIONS (:push, :pull, :bidi)
       # @param path      [String]    local or remote path (depends on direction)

data/lib/aspera/cli/terminal_formatter.rb

@@ -4,6 +4,8 @@ require 'aspera/environment'
 require 'aspera/formatter_interface'
 require 'aspera/markdown'
 require 'aspera/assert'
+require 'aspera/rainbow'
+using Rainbow
 
 module Aspera
   module Cli
@@ -11,9 +13,13 @@ module Aspera
     # @see FormatterInterface
     # @see MarkdownFormatter (in build/lib/doc_helper.rb)
     module TerminalFormatter
-      HINT = 'HINT:'.bg_green.gray.blink.freeze
       include FormatterInterface
 
+      # Prefix for hint messages (evaluated on each call, as colors can be enabled or disabled by option)
+      def hint
+        'HINT:'.bg(:green).white.blink
+      end
+
       # Format boolean with colored symbol (+/- or Y/ )
       def tick(yes)
         result =
@@ -29,7 +35,7 @@ module Aspera
       # 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
+        return %w[null empty].any? { |s| what.include?(s) } ? result.faint : result.inverse
       end
 
       # Prepare table row for terminal display (word wrap arrays)
@@ -59,7 +65,7 @@ module Aspera
         end
       end
 
-      module_function :tick, :special_format, :check_row, :markdown_text
+      module_function :hint, :tick, :special_format, :check_row, :markdown_text
     end
   end
 end