aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/cli/command_spec.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Aspera
+  module Cli
+    # Declares a positional argument consumed by a command.
+    # Declaration order in a command's `arguments:` array defines parsing order.
+    # Mandatory arguments must come before optional ones.
+    #
+    # @!attribute name        [Symbol]                    Name used in help and error messages
+    # @!attribute description [String]                    User-facing description
+    # @!attribute type        [Class, Array<Class>, :identifier] Validated type; :identifier triggers instance_identifier
+    # @!attribute mandatory   [Boolean]                   Default true; optional args must come after all mandatory ones
+    # @!attribute multiple    [Boolean, String]           true: consume all remaining; String: consume until named marker
+    # @!attribute default     [Object, nil]               Default value when mandatory: false and no argument provided
+    # @!attribute schema      [String, nil]               JSON schema name for validation and --help introspection
+    # @!attribute bulk        [Boolean]                   When true, wraps read+loop for bulk mode (Array if --bulk yes)
+    # @!attribute lookup      [Symbol, nil]               Instance method name for percent-selector resolution (only used when type: :identifier)
+    # @!attribute allowed     [Array<Symbol>, nil]        Allowed Symbol values; when set, type is forced to Symbol and accept_list is applied
+    # @!attribute interactive [Boolean]                   When true, sets ask_missing_mandatory before resolving so interactive prompting is triggered when no CLI args are provided
+    ArgumentSpec = Struct.new(
+      :name,
+      :description,
+      :type,
+      :mandatory,
+      :multiple,
+      :default,
+      :schema,
+      :bulk,
+      :lookup,
+      :allowed,
+      :interactive,
+      keyword_init: true
+    ) do
+      def initialize(**kwargs)
+        kwargs[:mandatory]    = true  if kwargs[:mandatory].nil?
+        kwargs[:multiple]     = false if kwargs[:multiple].nil?
+        kwargs[:bulk]         = false if kwargs[:bulk].nil?
+        kwargs[:interactive]  = false if kwargs[:interactive].nil?
+        super
+      end
+    end
+
+    # Declares an option referenced by name from command declarations.
+    # Mirrors the existing `options.declare` call but associates the option with
+    # the command(s) that use it.
+    #
+    # @!attribute name        [Symbol]               Option name (same symbol used in options.declare)
+    # @!attribute description [String, nil]          User-facing description; nil derives it from schema:
+    # @!attribute allowed     [Array, nil]           Allowed values (forwarded to options.declare)
+    # @!attribute default     [Object, nil]          Default value
+    # @!attribute short       [String, nil]          Single-character short form (e.g. 'x')
+    # @!attribute handler     [Symbol, Hash, nil]
+    #   - Symbol: resolved to {o: <plugin instance>, m: <symbol>} at runtime (Category B)
+    #   - Hash:   {o: <object>, m: <method>} used as-is (Category A: singletons / class constants)
+    #   - nil:    option stores its value locally (no delegation)
+    # @!attribute deprecation [String, nil]          Forwarded to options.declare as deprecation:
+    # @!attribute schema      [String, nil]          JSON schema name; also derives description when nil
+    OptionSpec = Struct.new(
+      :name,
+      :description,
+      :allowed,
+      :default,
+      :short,
+      :handler, # kept as-is: this is the option accessor delegation, not a command action
+      :deprecation,
+      :schema,
+      keyword_init: true
+    )
+
+    # Declares a single command node in the flat registry.
+    #
+    # @!attribute id               [Symbol]                      Unique identifier within its parent's namespace
+    # @!attribute parent           [Symbol, Array<Symbol>, nil]  Full path to parent; nil for root commands
+    # @!attribute description      [String]                      User-facing help text
+    # @!attribute options          [Array<Symbol>]               Option names consumed by this command
+    # @!attribute arguments        [Array<ArgumentSpec>]         Positional arguments, in order.
+    #                                                            The first ArgumentSpec with type: :identifier is treated as the instance
+    #                                                            identifier for intermediate nodes (consumed in Phase A) and leaf nodes.
+    # @!attribute action           [Symbol, Proc, nil]           Instance method (Symbol) or inline block (Proc) called when this is a leaf command
+    # @!attribute setup            [Symbol, nil]                 Instance method called before dispatching to children; returns Hash merged into ctx
+    # @!attribute delegates_to     [Symbol, Array<Symbol>, nil]  Re-enter the command tree at this path
+    # @!attribute delegate_instance [Symbol, nil]                Instance method returning a different plugin object
+    # @!attribute aliases          [Array<Symbol>, nil] Alternative names accepted for this command (each resolves to this command's id)
+    # @!attribute entity_execute   [Hash, nil]                   Shorthand: expand to Base#entity_execute with these parameters
+    # @!attribute transfer_paths   [:send, :receive, nil]        File-list resolution delegated to TransferAgent; mutually exclusive with arguments
+    # @!attribute condition        [Symbol, nil]                 Instance method returning Boolean; if false command is hidden from dispatch
+    # @!attribute query_schema     [String, nil]                 Schema path for --query help; when set, the runner hints `--query=help`
+    CommandSpec = Struct.new(
+      :id,
+      :parent,
+      :description,
+      :options,
+      :arguments,
+      :action,
+      :setup,
+      :delegates_to,
+      :delegate_instance,
+      :aliases,
+      :entity_execute,
+      :transfer_paths,
+      :condition,
+      :query_schema,
+      keyword_init: true
+    ) do
+      def initialize(**kwargs)
+        # Coerce each element of arguments: from Hash to ArgumentSpec if needed
+        if kwargs[:arguments]
+          kwargs[:arguments] = kwargs[:arguments].map do |a|
+            a.is_a?(Hash) ? ArgumentSpec.new(**a) : a
+          end
+        end
+        super
+      end
+
+      class << self
+        # Derive the implicit action method name from a path array.
+        # e.g. [:admin, :user, :list] -> :action_admin_user_list
+        # @param path [Array<Symbol>]
+        # @return [Symbol]
+        def action_method(path)
+          :"action_#{path.join('_')}"
+        end
+      end
+
+      # Compute the full path as Array<Symbol> from parent + id.
+      # @return [Array<Symbol>]
+      def full_path
+        Array(parent) + [id]
+      end
+
+      # Derive the implicit action method name from the full path.
+      # @return [Symbol]
+      def action_method_name
+        self.class.action_method(full_path)
+      end
+    end
+  end
+end

data/lib/aspera/cli/context.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'aspera/assert'
+require 'aspera/cli/mailer'
+require 'aspera/cli/secret_finder'
+
+module Aspera
+  module Cli
+    # Global objects shared with plugins
+    class Context
+      # @type [Array<Symbol>]
+      # Members that must be non-nil after bootstrap (validated in #validate)
+      MEMBERS = %i[options transfer config formatter persistency man_header presets http_config main_folder mailer secret_finder].freeze
+      # @!attribute [rw] options
+      #   @return [Parser] the command line options manager
+      # @!attribute [rw] transfer
+      #   @return [TransferAgent] the transfer agent, used by transfer plugins
+      # @!attribute [rw] config
+      #   @return [Plugins::Config] the configuration plugin, used by plugins to get configuration values and presets
+      # @!attribute [rw] formatter
+      #   @return [Formatter] the formatter, used by plugins to display results and messages
+      # @!attribute [rw] persistency
+      #   @return [Object] # whatever the type is
+      # @!attribute [rw] man_header
+      #   @return [Boolean] whether to display the manual header in plugin help
+      # @!attribute [rw] presets
+      #   @return [PresetManager] manages the YAML config file and preset resolution
+      # @!attribute [rw] http_config
+      #   @return [Http] manages HTTP/S and TLS runtime options
+      # @!attribute [rw] mailer
+      #   @return [Mailer] sends emails (SMTP) via ERB templates
+      # @!attribute [rw] secret_finder
+      #   @return [SecretFinder] resolves secrets for url+username pairs
+      attr_accessor(*MEMBERS)
+      # Optional: nil when progress bar is disabled
+      attr_accessor :progress_bar
+      # Optional: nil when no PAC script is configured
+      attr_accessor :pac_executor
+
+      # Initialize all members to nil, so that they are defined and can be validated later
+      # @return [nil]
+      def initialize
+        MEMBERS.each{ |i| instance_variable_set(:"@#{i}", nil)}
+        @progress_bar = nil
+        @pac_executor = nil
+      end
+
+      # Validate that all mandatory members are non-nil (detect bootstrap bugs)
+      # @raise [Aspera::AssertionError] if any member is not set
+      # @return [nil]
+      def validate
+        MEMBERS.each do |i|
+          Aspera.assert(instance_variable_defined?(:"@#{i}")){"context member @#{i} is not defined"}
+          Aspera.assert(!instance_variable_get(:"@#{i}").nil?){"context member @#{i} is nil"}
+        end
+      end
+
+      # Check if the context is in manual-only mode
+      # @return [Boolean] true if in manual-only mode
+      def only_manual?
+        transfer.eql?(:only_manual)
+      end
+
+      # Set the context to manual-only mode
+      # @return [Symbol] :only_manual
+      def only_manual!
+        @transfer = :only_manual
+      end
+    end
+  end
+end

data/lib/aspera/cli/error.rb

@@ -4,9 +4,25 @@ module Aspera
   module Cli
     # CLI base exception
     class Error < StandardError; end
+
+    # Raised by dispatch_from_registry when --help is encountered mid-dispatch.
+    # Carries the plugin instance (with #help_path set) so the runner can display
+    # context-sensitive help without unwinding through a full rescue chain.
+    class HelpRequest < StandardError
+      # @return [Plugins::Base]
+      attr_reader :plugin
+
+      def initialize(plugin)
+        super('help requested')
+        @plugin = plugin
+      end
+    end
+
     # Raised when an unexpected argument is provided.
     class BadArgument < Error; end
+
     class MissingArgument < Error; end
+
     class NoSuchElement < Error; end
 
     # Raised when a lookup for a specific entity fails to return exactly one result.

data/lib/aspera/cli/extended_value.rb

@@ -3,6 +3,7 @@
 # cspell:ignore csvt jsonpp stdbin
 require 'aspera/uri_reader'
 require 'aspera/environment'
+require 'aspera/yaml'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/cli/error'
@@ -86,6 +87,7 @@ module Aspera
         # Base handlers
         # Other handlers can be set using `on`
         # e.g. `preset` is reader in config plugin
+        # @type [Hash{Symbol => Proc}]
         @handlers = {
           val:    lambda{ |i| i},
           base64: lambda{ |i| Base64.decode64(i)},
@@ -100,10 +102,10 @@ module Aspera
           path:   lambda{ |i| File.expand_path(i)},
           re:     lambda{ |i| Regexp.new(i, Regexp::MULTILINE)},
           ruby:   lambda{ |i| Environment.secure_eval(i, __FILE__, __LINE__)},
-          s:      lambda{ |i| i.to_s},
+          s:      lambda(&:to_s),
           secret: lambda{ |i| prompt = i.empty? ? 'secret' : i; $stdin.getpass("#{prompt}> ")}, # rubocop:disable Style/Semicolon
           stdin:  lambda{ |i| ExtendedValue.read_stdin(i)},
-          yaml:   lambda{ |i| YAML.load(i)},
+          yaml:   lambda{ |i| YAML.safe_load(i)},
           zlib:   lambda{ |i| Zlib::Inflate.inflate(i)},
           extend: lambda{ |i| ExtendedValue.instance.evaluate_extend(i)}
         }
@@ -137,7 +139,7 @@ module Aspera
       # Add a new handler
       def on(name, &block)
         Aspera.assert_type(name, Symbol){'name'}
-        Aspera.assert(block)
+        Aspera.assert(block){"block required when registering handler for #{name}"}
         Log.log.debug{"Setting handler for #{name}"}
         @handlers[name] = block
         update_regex