aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/cli/ascp_actions.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'aspera/agent/factory'
+require 'aspera/schema/registry'
+require 'aspera/schema/reader'
+
+module Aspera
+  module Cli
+    # Mixin for Config plugin: ASCP / Transferd related actions
+    module AscpActions
+      TRANSFERD_APP_NAME = 'sdk'
+
+      # Mapping from agent symbol to schema key in options.schema.yaml
+      # Agents without dedicated schema (connect, desktop) are omitted.
+      AGENT_SCHEMA_KEY = {
+        direct:    Schema::Registry::DIRECT_AGENT_OPTIONS,
+        node:      Schema::Registry::NODE_AGENT_OPTIONS,
+        httpgw:    Schema::Registry::HTTPGW_AGENT_OPTIONS,
+        transferd: Schema::Registry::TRANSFERD_AGENT_OPTIONS
+      }.freeze
+      private_constant :AGENT_SCHEMA_KEY
+
+      # Set the SDK directory, checking default and former locations
+      def set_sdk_dir
+        sdk_dir = Products::Transferd.sdk_directory rescue nil
+        if sdk_dir.nil?
+          @sdk_default_location = true
+          Log.log.debug('SDK folder is not set, checking default')
+          sdk_dir = self.class.default_app_main_folder(app_name: TRANSFERD_APP_NAME)
+          Log.log.debug{"Checking: #{sdk_dir}"}
+          if !Dir.exist?(sdk_dir)
+            Log.log.debug{"No such folder: #{sdk_dir}"}
+            former_sdk_folder = File.join(self.class.default_app_main_folder(app_name: Info::CMD_NAME), TRANSFERD_APP_NAME)
+            Log.log.debug{"Checking: #{former_sdk_folder}"}
+            sdk_dir = former_sdk_folder if Dir.exist?(former_sdk_folder)
+          end
+          Log.log.debug{"Using: #{sdk_dir}"}
+          Products::Transferd.sdk_directory = sdk_dir
+        end
+      end
+
+      # Install the transfer SDK (ascp + transferd) from a URL or using the default source.
+      # Version defaults to +Info::SDK_VERSION+; pass +LATEST+ as argument to install the latest available version.
+      # @param version [String, nil] version to install; nil means use the default SDK version
+      # @return [Result::Status] installation result message
+      def install_transfer_sdk(version: nil)
+        asked_version = version.nil? ? Info::SDK_VERSION : version
+        asked_version = nil if asked_version.eql?(SpecialValues::LATEST)
+        sdk_url = options.get_option(:sdk_url, mandatory: true)
+        sdk_url = nil if sdk_url.eql?(SpecialValues::DEF)
+        name, ver, folder = Ascp::Installation.instance.install_sdk(url: sdk_url, version: asked_version)
+        return Result::Status.new("Installed #{name} version #{ver} in #{folder}")
+      end
+
+      def action_ascp_show(**)
+        Result::Text.new(Ascp::Installation.instance.path(:ascp))
+      end
+
+      def action_ascp_info(**)
+        data = Ascp::Installation.instance.ascp_info
+        data['ts'] = transfer.user_transfer_spec
+        DataRepository::ELEMENTS.each_with_object(data){ |i, h| h[i.to_s] = DataRepository.instance.item(i)}
+        SecretHider::ADDITIONAL_KEYS_TO_HIDE.concat(DataRepository::ELEMENTS.map(&:to_s))
+        Result::SingleObject.new(data)
+      end
+
+      def action_ascp_install(version: nil, **)
+        install_transfer_sdk(version: version)
+      end
+
+      def action_ascp_spec(**)
+        builder = Schema::Documentation.new(TerminalFormatter, Transfer::Spec::SCHEMA, include_option: true, agent_columns: true).build
+        Result::ObjectList.new(builder.rows, fields: builder.columns)
+      end
+
+      def action_ascp_schema(agent_name: nil, **)
+        schema = Transfer::Spec::SCHEMA.current.merge({'$comment'=>'DO NOT EDIT, this file was generated from the YAML.'})
+        schema['properties'] = schema['properties'].select{ |_k, v| CommandLineBuilder.supported_by_agent(agent_name, v)} unless agent_name.nil?
+        schema['properties'] = schema['properties'].sort.to_h
+        Result::SingleObject.new(schema)
+      end
+
+      def action_ascp_errors(**)
+        error_data = []
+        Ascp::Management::ERRORS.each_pair do |code, prop|
+          error_data.push(code: code, mnemonic: prop[:c], retry: prop[:r], info: prop[:a])
+        end
+        Result::ObjectList.new(error_data)
+      end
+
+      def action_ascp_products_list(**)
+        Result::ObjectList.new(Ascp::Installation.instance.installed_products, fields: %w[name app_root])
+      end
+
+      def action_agents_list(**)
+        rows = Agent::Factory::ALL.map do |sym, names|
+          schema_key = AGENT_SCHEMA_KEY[sym]
+          param_names =
+            if schema_key
+              Schema::Registry.instance.reader(schema_key).current['properties']&.keys&.sort&.join(', ') || ''
+            else
+              ''
+            end
+          {
+            'name'       => sym.to_s,
+            'short'      => names[:short].to_s,
+            'parameters' => param_names
+          }
+        end.sort_by{ |r| r['name']}
+        Result::ObjectList.new(rows, fields: %w[name short parameters])
+      end
+
+      def action_agents_show(agent_name:, **)
+        names = Agent::Factory::ALL[agent_name]
+        schema_key = AGENT_SCHEMA_KEY[agent_name]
+        agent_info = {
+          'name'        => agent_name.to_s,
+          'short'       => names[:short].to_s,
+          'description' => schema_key ? Schema::Registry.instance.reader(schema_key).current['description'].to_s : '(no configurable parameters)'
+        }
+        if schema_key
+          properties = Schema::Registry.instance.reader(schema_key).current['properties'] || {}
+          rows = properties.map do |pname, pdef|
+            row = {'parameter' => pname, 'type' => pdef['type'].to_s, 'description' => pdef['description'].to_s}
+            row['required'] = (Schema::Registry.instance.reader(schema_key).current['required'] || []).include?(pname) ? 'yes' : 'no'
+            row['default']  = pdef.key?('default') ? pdef['default'].inspect : ''
+            row['enum']     = pdef.key?('enum')    ? pdef['enum'].join(', ') : ''
+            row
+          end
+          return Result::ObjectList.new(rows, fields: %w[parameter required type default enum description])
+        end
+        Result::SingleObject.new(agent_info)
+      end
+
+      def action_agents_parameters(agent_name:, **)
+        schema_key = AGENT_SCHEMA_KEY[agent_name]
+        return Result::Nothing.new if schema_key.nil?
+        properties = Schema::Registry.instance.reader(schema_key).current['properties'] || {}
+        rows = properties.map do |pname, pdef|
+          {'name' => pname, 'type' => pdef['type'].to_s, 'description' => pdef['description'].to_s}
+        end
+        Result::ObjectList.new(rows, fields: %w[name type description])
+      end
+
+      def action_transferd_install(**)
+        install_transfer_sdk
+      end
+
+      def action_transferd_list(**)
+        sdk_list = Ascp::Installation.instance.sdk_locations
+        Result::ObjectList.new(sdk_list, fields: sdk_list.first.keys - ['url'])
+      end
+    end
+  end
+end

data/lib/aspera/cli/async_transfer_store.rb

@@ -0,0 +1,81 @@
+# 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
+
+      # @param persistency [PersistencyFolder]
+      def initialize(persistency)
+        @persistency = persistency
+      end
+
+      # Persist (create or update) an async transfer entry.
+      # @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(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
+    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: Allowed::TYPES_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 || spec.entity_execute # 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