aspera-cli 4.26.2 → 4.27.1

data/lib/aspera/cli/async_transfer_store.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'aspera/log'
+require 'json'
+require 'securerandom'
+
+module Aspera
+  module Cli
+    # Persist the state of asynchronous transfers on the local file system.
+    #
+    # Each entry is a JSON document identified by a `job_id` (UUID generated by ascli).
+    # The underlying storage uses PersistencyFolder with the category prefix
+    # +CATEGORY+ so all async-transfer files are grouped together and can be
+    # garbage-collected independently.
+    #
+    # Schema of a stored entry:
+    #   job_id            [String]  UUID generated by ascli (= the store key)
+    #   agent_type        [String]  'desktop' | 'node' | 'connect' | 'transferd' | 'direct'
+    #   transfer_id       [String]  Opaque ID returned by the agent's start_transfer
+    #   agent_params      [Hash]    Agent-specific connection parameters for re-querying
+    #   status            [String]  'running' | 'completed' | 'failed' | 'cancelled'
+    #   bytes_transferred [Integer] Last known bytes transferred (0 if unknown)
+    #   started_at        [String]  ISO-8601 timestamp
+    #   ended_at          [String, nil] ISO-8601 timestamp once finished
+    #   error             [String, nil] Error message when status == 'failed'
+    class AsyncTransferStore
+      CATEGORY = 'async_transfer_'
+      private_constant :CATEGORY
+
+      # Class-level registry of in-process agent references, keyed by job_id.
+      # Shared across all AsyncTransferStore instances within the same Ruby process,
+      # so that a reference registered in one Runner call is visible in the next
+      # (e.g. MCP server mode where each tool call creates a fresh Runner/Context).
+      # Never persisted to disk.
+      @agent_refs = {}
+      class << self
+        attr_reader :agent_refs
+      end
+
+      # @param persistency [PersistencyFolder]
+      def initialize(persistency)
+        @persistency = persistency
+      end
+
+      # Register an in-process agent reference for a job.
+      # Called by TransferAgent immediately after start_transfer (async mode).
+      # The reference is only available while the same Ruby process is alive.
+      # @param job_id    [String] the ascli-generated UUID
+      # @param agent_ref [Object] live agent instance (responds to sessions_by_job)
+      def register_agent_ref(job_id, agent_ref)
+        self.class.agent_refs[job_id] = agent_ref
+      end
+
+      # Retrieve a previously registered in-process agent reference.
+      # @param job_id [String]
+      # @return [Object, nil] the live agent instance, or nil if not registered / process restarted
+      def agent_ref(job_id)
+        self.class.agent_refs[job_id]
+      end
+
+      # Persist (create or update) an async transfer entry.
+      # Keys whose name starts with '_' are in-process references (e.g. '_agent_ref')
+      # and are intentionally excluded from the JSON serialization — at every nesting level.
+      # @param job_id [String] the ascli-generated UUID
+      # @param data   [Hash]   fields to store (will be JSON-serialised)
+      def write(job_id, data)
+        Aspera.assert_type(job_id, String) { 'job_id' }
+        Aspera.assert_type(data, Hash) { 'data' }
+        @persistency.put(store_key(job_id), JSON.generate(strip_internal_keys(data)))
+        nil
+      end
+
+      # Read one entry.
+      # @param job_id [String]
+      # @return [Hash, nil] the stored data, or nil if not found
+      def read(job_id)
+        Aspera.assert_type(job_id, String) { 'job_id' }
+        raw = @persistency.get(store_key(job_id))
+        return if raw.nil?
+        JSON.parse(raw)
+      end
+
+      # List all async transfer entries.
+      # @return [Array<Hash>] each entry includes the +job_id+ field
+      def list
+        @persistency.current_items(CATEGORY).map do |key, raw|
+          data = JSON.parse(raw)
+          data['job_id'] ||= key.sub(CATEGORY, '')
+          data
+        end
+      end
+
+      # Delete one entry.
+      # @param job_id [String]
+      def delete(job_id)
+        Aspera.assert_type(job_id, String) { 'job_id' }
+        @persistency.delete(store_key(job_id))
+        nil
+      end
+
+      private
+
+      # Map a job_id to the PersistencyFolder key (includes category prefix).
+      def store_key(job_id)
+        "#{CATEGORY}#{job_id}"
+      end
+
+      # Recursively remove keys whose name starts with '_' from a Hash.
+      # Such keys hold in-process Ruby object references (e.g. '_agent_ref') that
+      # cannot be serialized to JSON and must never reach the file system.
+      def strip_internal_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), h|
+            h[k] = strip_internal_keys(v) unless k.to_s.start_with?('_')
+          end
+        when Array
+          value.map { |v| strip_internal_keys(v) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/aspera/cli/bootstrapper.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/plugins/factory'
+require 'aspera/cli/extended_value'
+require 'aspera/cli/special_values'
+require 'aspera/cli/info'
+require 'aspera/cli/transfer_progress'
+require 'aspera/cli/preset_manager'
+require 'aspera/cli/http'
+require 'aspera/ascp/installation'
+require 'aspera/products/transferd'
+require 'aspera/transfer/parameters'
+require 'aspera/proxy_auto_config'
+require 'aspera/environment'
+require 'aspera/persistency_folder'
+require 'aspera/rest'
+require 'aspera/log'
+require 'aspera/assert'
+require 'aspera/oauth'
+require 'aspera/ssl'
+require 'aspera/schema/registry'
+
+module Aspera
+  module Cli
+    # Performs one-time bootstrap of all shared services into Context.
+    # Called by Runner before instantiating Plugins::Config, so that Config
+    # acts only as a CLI plugin (option declaration + command handlers).
+    #
+    # Responsibilities:
+    #   - resolve context.main_folder (option :home)
+    #   - populate context.persistency, context.presets, context.http_config, context.progress_bar
+    #   - register plugin lookup folders
+    #   - register @preset / @vault extended-value handlers
+    #   - configure global singletons: RestParameters, OAuth::Factory, SSL, Transfer::Parameters,
+    #     RestErrorAnalyzer
+    #   - set up the PAC proxy executor (option :fpac)
+    class Bootstrapper
+      # Folder name inside $HOME for all Aspera tool data (~/.aspera)
+      ASPERA_HOME_FOLDER_NAME  = '.aspera'
+      # Default name for the YAML config file
+      DEFAULT_CONFIG_FILENAME  = 'config.yaml'
+      # Sub-folder for user-installed plugins
+      ASPERA_PLUGINS_FOLDERNAME = 'plugins'
+      # Sub-folder for persistency data
+      PERSISTENCY_FOLDER       = 'persist_store'
+      # Sub-folder for file lists used by transfers
+      FILE_LIST_FOLDER_NAME    = 'filelists'
+      # Log file for REST call exceptions
+      REST_EXCEPTIONS_LOG_FILENAME = 'rest_exceptions.log'
+      # Extended-value prefix that resolves a named preset
+      EXTEND_PRESET = :preset
+      # Extended-value prefix that resolves a vault secret
+      EXTEND_VAULT  = :vault
+      # Default preset name for the global config section
+      CONF_GLOBAL_SYM = :config
+
+      private_constant :ASPERA_HOME_FOLDER_NAME,
+        :DEFAULT_CONFIG_FILENAME,
+        :ASPERA_PLUGINS_FOLDERNAME,
+        :PERSISTENCY_FOLDER,
+        :FILE_LIST_FOLDER_NAME,
+        :REST_EXCEPTIONS_LOG_FILENAME,
+        :EXTEND_PRESET,
+        :EXTEND_VAULT,
+        :CONF_GLOBAL_SYM
+
+      # @param context [Context] the shared context to populate
+      def initialize(context)
+        Aspera.assert_type(context, Context) { 'context' }
+        @context = context
+        @pac_exec = nil
+      end
+
+      # Run the full bootstrap sequence.
+      # Must be called after context.options and context.formatter are set.
+      # On return, context.persistency, context.presets, context.http_config and
+      # context.progress_bar are populated and all global singletons are configured.
+      #
+      # @param gem_plugins_folder [String]  folder of built-in plugins (from Plugins::Config)
+      # @param vault_value_cb     [Proc]    block(name): secret value (from VaultManager)
+      def run(gem_plugins_folder:, vault_value_cb:)
+        setup_main_folder
+        setup_persistency_and_plugin_folders(gem_plugins_folder)
+        setup_config_file
+        setup_extended_value_handlers(vault_value_cb)
+        setup_progress_bar
+        setup_pac_executor
+        setup_rest_and_transfer_runtime
+      end
+
+      # Public accessor used as option handler for :config_file
+      attr_accessor :config_file_option
+
+      private
+
+      # Declare + parse :home option: sets context.main_folder
+      def setup_main_folder
+        @context.options.declare(
+          :home, description: 'Home folder for tool',
+          handler: {o: @context, m: :main_folder},
+          default: default_app_main_folder(app_name: Info::CMD_NAME)
+        )
+        @context.options.parse_options!
+        Log.log.debug { "#{Info::CMD_NAME} folder: #{@context.main_folder}" }
+      end
+
+      # context.persistency + plugin lookup folders
+      def setup_persistency_and_plugin_folders(gem_plugins_folder)
+        @context.persistency = PersistencyFolder.new(File.join(@context.main_folder, PERSISTENCY_FOLDER))
+        Plugins::Factory.instance.add_lookup_folder(gem_plugins_folder)
+        Plugins::Factory.instance.add_lookup_folder(File.join(@context.main_folder, ASPERA_PLUGINS_FOLDERNAME))
+      end
+
+      # Declare + parse :config_file option: sets context.presets + context.http_config
+      def setup_config_file
+        @context.options.declare(
+          :config_file, description: 'Path to YAML file with preset configuration',
+          handler: {o: self, m: :config_file_option},
+          default: File.join(@context.main_folder, DEFAULT_CONFIG_FILENAME)
+        )
+        @context.options.parse_options!
+        @context.presets = PresetManager.new(config_file: @config_file_option)
+        @context.http_config = Http.new
+      end
+
+      # Register @preset and @vault extended-value handlers + global config default preset
+      def setup_extended_value_handlers(vault_value_cb)
+        @context.options.declare(:secret, description: 'Secret for access keys')
+        @context.options.declare(:vault, schema: Schema::Registry::VAULT_OPTIONS)
+        @context.options.declare(:vault_password, description: 'Vault password')
+        # Register @preset and @vault handlers BEFORE parse_options! so that
+        # values like --secret=@preset:name are correctly evaluated at parse time.
+        ExtendedValue.instance.on(EXTEND_PRESET) { |v| @context.presets.by_name(v) }
+        ExtendedValue.instance.on(EXTEND_VAULT, &vault_value_cb)
+        @context.options.parse_options!
+        # Load global config default preset (equivalent of add_plugin_default_preset(:config))
+        default_config_name = @context.presets.plugin_default_name(CONF_GLOBAL_SYM)
+        unless default_config_name.nil?
+          Log.log.debug { "add_plugin_default_preset:#{CONF_GLOBAL_SYM}:#{default_config_name}" }
+          @context.options.add_option_preset(@context.presets.by_name(default_config_name), 'default_plugin', override: false)
+        end
+      end
+
+      # Declare + parse :progress_bar: sets context.progress_bar
+      def setup_progress_bar
+        @context.options.declare(:progress_bar, description: 'Display progress bar', allowed: Type::BOOLEAN, default: Environment.terminal?)
+        @context.options.parse_options!
+        @context.progress_bar = TransferProgress.new if @context.options.get_option(:progress_bar)
+      end
+
+      # Declare + parse :fpac / :proxy_credentials: sets up PAC executor
+      def setup_pac_executor
+        @context.options.declare(:fpac, description: 'Proxy auto configuration script')
+        @context.options.declare(:proxy_credentials, description: 'HTTP proxy credentials for fpac: user, password', allowed: [Array, NilClass])
+        @context.options.parse_options!
+        pac_script = @context.options.get_option(:fpac)
+        return unless pac_script
+
+        @context.pac_executor = ProxyAutoConfig.new(pac_script).register_uri_generic
+        proxy_user_pass = @context.options.get_option(:proxy_credentials)
+        if proxy_user_pass
+          Aspera.assert(proxy_user_pass.length.eql?(2), type: Cli::BadArgument) { "proxy_credentials shall have two elements (#{proxy_user_pass.length})" }
+          @context.pac_executor.proxy_user = proxy_user_pass[0]
+          @context.pac_executor.proxy_pass = proxy_user_pass[1]
+        end
+      end
+
+      # Configure global singletons: RestParameters, SSL, Transfer, RestErrorAnalyzer.
+      # OAuth persist_mgr is NOT set here: it depends on :cache_tokens which is parsed later
+      # by Config#initialize. Runner sets it after Config.new.
+      def setup_rest_and_transfer_runtime
+        RestParameters.instance.user_agent    = Info::CMD_NAME
+        RestParameters.instance.progress_bar  = @context.progress_bar
+        RestParameters.instance.session_cb    = ->(http_session) { @context.http_config.update_session(http_session) }
+        RestParameters.instance.spinner_cb    = ->(title = nil, action: :spin) { @context.formatter.long_operation(title, action: action) }
+        OAuth::Web.additional_info = "#{Info::CMD_NAME} v#{Cli::VERSION}"
+        Transfer::Parameters.file_list_folder = File.join(@context.main_folder, FILE_LIST_FOLDER_NAME)
+        RestErrorAnalyzer.instance.log_file   = File.join(@context.main_folder, REST_EXCEPTIONS_LOG_FILENAME)
+        RestErrorsAspera.register_handlers
+      end
+
+      # @return [String] ~/.aspera
+      def module_family_folder
+        user_home_folder = Dir.home
+        Aspera.assert(Dir.exist?(user_home_folder), type: Cli::Error) { "Home folder does not exist: #{user_home_folder}. Check your user environment." }
+        File.join(user_home_folder, ASPERA_HOME_FOLDER_NAME)
+      end
+
+      # @return [String] ~/.aspera/<app_name>
+      def default_app_main_folder(app_name:)
+        Aspera.assert_type(app_name, String)
+        Aspera.assert(!app_name.empty?, 'app_name must not be empty')
+        File.join(module_family_folder, app_name)
+      end
+    end
+  end
+end

data/lib/aspera/cli/command_registry.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/command_spec'
+
+module Aspera
+  module Cli
+    # Stores CommandSpec objects indexed by their full path (Array<Symbol>).
+    # Each plugin class gets its own instance (not shared across the inheritance chain).
+    #
+    # Public API:
+    #   register(spec)          - store a CommandSpec; raises on duplicate full_path
+    #   register_option(spec)   - store an OptionSpec by name
+    #   option_specs            - Hash{Symbol => OptionSpec} of all registered options
+    #   [](path)                - retrieve a CommandSpec by full path
+    #   children_of(path)       - Hash{Symbol => CommandSpec} of direct children (O(1))
+    #   all_paths               - Array of all registered full paths
+    #   any?                    - true if at least one spec has been registered
+    #   validate!               - cross-spec consistency checks; raises on violation
+    class CommandRegistry
+      # @param path [Array<Symbol>] full path to look up
+      # @return [CommandSpec, nil]
+      def [](path)
+        @specs[Array(path)]
+      end
+
+      # Register a CommandSpec. Raises if the full_path is already registered.
+      # Also updates the children index so children_of remains O(1).
+      # @param spec [CommandSpec]
+      # @raise [ArgumentError] on duplicate full path
+      # @return [CommandSpec] the registered spec
+      def register(spec)
+        path = spec.full_path
+        raise ArgumentError, "Duplicate command path: #{path.inspect}" if @specs.key?(path)
+        @specs[path] = spec
+        # Index: parent_path -> { child_id -> spec }
+        parent = path[0..-2] # [] for root-level commands
+        (@children_index[parent] ||= {})[spec.id] = spec
+        spec
+      end
+
+      # Returns a Hash mapping each child id to its CommandSpec for all direct
+      # children of `path`. Empty hash if no children are registered.
+      # O(1) lookup via the children index built in register().
+      # @param path [Array<Symbol>] parent path ([] for root-level commands)
+      # @return [Hash{Symbol => CommandSpec}]
+      def children_of(path)
+        @children_index[Array(path)] || {}
+      end
+
+      # @return [Array<Array<Symbol>>] all registered full paths
+      def all_paths
+        @specs.keys
+      end
+
+      # Register an OptionSpec. Raises if the option name is already registered.
+      # @param spec [OptionSpec]
+      # @raise [ArgumentError] on duplicate option name
+      # @return [OptionSpec] the registered spec
+      def register_option(spec)
+        raise ArgumentError, "Duplicate option: #{spec.name.inspect}" if @option_specs.key?(spec.name)
+        @option_specs[spec.name] = spec
+      end
+
+      # @return [Hash{Symbol => OptionSpec}] all registered option specs
+      def option_specs
+        @option_specs.dup
+      end
+
+      # @return [Boolean] true if at least one spec is registered
+      def any?
+        !@specs.empty?
+      end
+
+      # @return [Boolean] true if no specs have been registered
+      def none?
+        @specs.empty?
+      end
+
+      # Cross-spec consistency checks.
+      # @param plugin_class [Class, nil] when given, also verify that implicit action methods exist
+      # @raise [ArgumentError] on any violation
+      # @return [self]
+      def validate!(plugin_class: nil)
+        # Rule: every non-root parent path that appears in the children index must have
+        # a registered CommandSpec. A missing parent means commands_under(:x) was used
+        # without a matching command :x declaration.
+        @children_index.each_key do |parent_path|
+          next if parent_path.empty? # root is never a CommandSpec
+          unless @specs.key?(parent_path)
+            raise ArgumentError,
+              "commands_under(#{parent_path.map(&:inspect).join(', ')}) used but #{parent_path.last.inspect} has no command declaration"
+          end
+        end
+
+        @specs.each_value do |spec|
+          path = spec.full_path
+
+          # Rule: delegates_to must point to a known path when present (non-empty array or symbol)
+          if spec.delegates_to
+            dt_path =
+              case spec.delegates_to
+              when Symbol then [spec.delegates_to]
+              when Array  then spec.delegates_to
+              end
+            # An empty array [] means re-enter the root - always valid
+            unless dt_path.empty? || @specs.key?(dt_path)
+              raise ArgumentError,
+                "#{path.inspect}: delegates_to #{dt_path.inspect} points to unknown path"
+            end
+          end
+
+          # Rule: delegate_instance requires delegates_to
+          if spec.delegate_instance && spec.delegates_to.nil?
+            raise ArgumentError,
+              "#{path.inspect}: delegate_instance requires delegates_to to be set"
+          end
+
+          # Rule: leaf commands with no explicit action must have a matching instance method
+          next if spec.action # explicit action: skip
+          next if @children_index[path]&.any? # intermediate node: skip
+          next if spec.delegates_to # delegated: skip
+          next unless plugin_class
+          implicit_method = CommandSpec.action_method(path)
+          unless plugin_class.method_defined?(implicit_method) || plugin_class.private_method_defined?(implicit_method)
+            raise ArgumentError,
+              "#{path.inspect}: no action: and no method #{implicit_method} on #{plugin_class}"
+          end
+        end
+        self
+      end
+
+      private
+
+      def initialize
+        # Keyed by Array<Symbol> full path
+        @specs = {}
+        # Keyed by Symbol option name
+        @option_specs = {}
+        # Children index: parent Array<Symbol> -> Hash{child_id Symbol => CommandSpec}
+        # Built incrementally in register(); enables O(1) children_of lookups.
+        @children_index = {}
+      end
+    end
+  end
+end

data/lib/aspera/cli/command_spec.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'aspera/schema/registry'
+
+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, Proc, nil]         Percent-selector resolver (only used when type: :identifier).
+    #                                                     Symbol → resolved via send(lookup, field, value, **ctx).
+    #                                                     Proc/lambda → called via instance_exec(field, value, **ctx, &lookup).
+    #                                                     Style: use Symbol for named methods; ->(){} for 1-liners; lambda do…end for 2–3 statements.
+    # @!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 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,
+      :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

@@ -1,15 +1,18 @@
 # 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 = %i[options transfer config formatter persistency man_header presets http_config].freeze
+      # 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 [Manager] the command line options manager
+      #   @return [Parser] the command line options manager
       # @!attribute [rw] transfer
       #   @return [TransferAgent] the transfer agent, used by transfer plugins
       # @!attribute [rw] config
@@ -24,21 +27,31 @@ module Aspera
       #   @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)}
+        MEMBERS.each { |i| instance_variable_set(:"@#{i}", nil) }
+        @progress_bar = nil
+        @pac_executor = nil
       end
 
-      # Validate that all members are set, raise exception if not
+      # 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"}
+          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