cuprum-cli 0.1.0

data/lib/cuprum/cli/errors/system_command_failure.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/cli/errors'
+
+module Cuprum::Cli::Errors
+  # Error returned when a system command returns a non-success status.
+  class SystemCommandFailure < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.cli.errors.system_command_failure'
+
+    # @param command [String] the failed command.
+    # @param details [String] the error output from the process, if any.
+    # @param exit_status [Integer] the exit code returned by the process.
+    def initialize(command:, details: nil, exit_status: nil)
+      @command     = command
+      @details     = details
+      @exit_status = exit_status
+
+      super(message: default_message)
+    end
+
+    attr_reader :command
+
+    attr_reader :details
+
+    attr_reader :exit_status
+
+    private
+
+    def as_json_data
+      {
+        'command'     => command,
+        'details'     => details,
+        'exit_status' => exit_status
+      }
+    end
+
+    def default_message
+      %(system command failed with exit status #{exit_status} - "#{command}")
+    end
+  end
+end

data/lib/cuprum/cli/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Namespace for errors, which represent failure states of commands.
+  module Errors
+    autoload :Files,                'cuprum/cli/errors/files'
+    autoload :SystemCommandFailure, 'cuprum/cli/errors/system_command_failure'
+  end
+end

data/lib/cuprum/cli/integrations/thor/arguments_parser.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/integrations/thor'
+
+module Cuprum::Cli::Integrations::Thor
+  # Utility for parsing command-line arguments captured by Thor tasks.
+  #
+  # Any unrecognized command line flags or options are appended as-is to the
+  # arguments array by Thor. Therefore, to handle cases such as variadic options
+  # where flags or options cannot be pre-parsed by Thor, we need an additional
+  # parsing step to pull any remaining flags or options out of the arguments.
+  #
+  # This parser supports the following formats:
+  #
+  # - `-a`, `--all`: Sets the `a` or `all` flag to `true`.
+  # - `-abc`: Sets the `a`, `b`, and `c` flags to `true`.
+  # - `--skip-all`, `--no-all`: Sets the `a` flag to `false`.
+  # - `-a=value`, `--a=value`: Sets the `a` option to `"value"`.
+  #
+  # The following formats are specifically *not* supported:
+  #
+  # - `--foo bar`: `--foo` is assumed to be a flag, `bar` is assumed to be a
+  #   positional argument.
+  # - `--str[]=foo --str[]=bar`: Array arguments are not supported.
+  # - `--str[foo]=foo --str[bar]=bar`: Hash arguments are not supported.
+  #
+  # In addition, parsed option values are coerced into their most likely
+  # intended types.
+  class ArgumentsParser
+    # Parses the given argument inputs into arguments and options.
+    #
+    # @param inputs [Array<String>] the arguments captured by Thor.
+    #
+    # @return [Array<Array<String>, Hash{Symbol=>Object}>] the parsed arguments
+    #   and options.
+    def call(*inputs)
+      raw_options, arguments = inputs.partition { |str| str.start_with?('-') }
+
+      [arguments, parse_options(raw_options)]
+    end
+
+    private
+
+    def coerce_value(raw_value)
+      Cuprum::Cli::Coercion.coerce(raw_value)
+    end
+
+    def grouped_flags?(raw_key)
+      return false if raw_key.start_with?('--')
+
+      raw_key.length > 2
+    end
+
+    def normalize_flag_key(raw_key)
+      return raw_key[5..] if raw_key.start_with?('--no-')
+      return raw_key[7..] if raw_key.start_with?('--skip-')
+      return raw_key[2..] if raw_key.start_with?('--')
+
+      raw_key[1..]
+    end
+
+    def normalize_option_key(raw_key)
+      return raw_key[2..] if raw_key.start_with?('--')
+
+      raw_key[1..]
+    end
+
+    def parse_flag_value(raw_key) # rubocop:disable Naming/PredicateMethod
+      return false if raw_key.start_with?('--no-')
+      return false if raw_key.start_with?('--skip-')
+
+      true
+    end
+
+    def parse_option(raw_key, raw_value) # rubocop:disable Metrics/MethodLength
+      if raw_value.nil? && grouped_flags?(raw_key)
+        raw_key[1..].chars.to_h { |char| [char.to_sym, true] }
+      elsif raw_value.nil?
+        key   = normalize_flag_key(raw_key)
+        value = parse_flag_value(raw_key)
+
+        { key.to_sym => value }
+      else
+        key   = normalize_option_key(raw_key)
+        value = coerce_value(raw_value)
+
+        { key.to_sym => value }
+      end
+    end
+
+    def parse_options(raw_options)
+      raw_options.reduce({}) do |options, input|
+        raw_key, raw_value = input.split('=')
+
+        options.merge(parse_option(raw_key, raw_value))
+      end
+    end
+  end
+end

data/lib/cuprum/cli/integrations/thor/registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/integrations/thor'
+require 'cuprum/cli/integrations/thor/task'
+require 'cuprum/cli/registry'
+
+module Cuprum::Cli::Integrations::Thor
+  # Registers CLI commands by name and adds as Thor tasks.
+  class Registry < Cuprum::Cli::Registry
+    # Registers the command with the registry.
+    #
+    # Also registers a Thor task with compatible parameters and metadata.
+    #
+    # @param command [Class] the command class to register.
+    # @param config [Hash] options for configuring the command.
+    #
+    # @option config arguments [Array] arguments to pass to the command on
+    #   initialization.
+    # @option config description [String] the description for the command.
+    # @option config full_description [String] the full description for the
+    #   command.
+    # @option config full_name [String] the name under which to register the
+    #   command. Defaults to the value of command.full_name.
+    # @option config options [Hash] options to pass to the command on
+    #   initialization.
+    #
+    # @raise [NameError] if a command is already registered with that name.
+    #
+    # @return [self]
+    def register(command, **config)
+      super.tap do
+        name    = config.fetch(:full_name, command.full_name)
+        command = commands[name]
+
+        Cuprum::Cli::Integrations::Thor::Task::Builder
+          .new(command)
+          .build(full_name: name)
+      end
+    end
+    alias add register
+  end
+end

data/lib/cuprum/cli/integrations/thor/task.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'sleeping_king_studios/tools/toolbelt'
+require 'sleeping_king_studios/tools/toolbox/subclass'
+require 'thor'
+
+require 'cuprum/cli/integrations/thor'
+require 'cuprum/cli/integrations/thor/arguments_parser'
+
+module Cuprum::Cli::Integrations::Thor
+  # Thor task wrapping a Cuprum::Cli command.
+  class Task < ::Thor
+    extend SleepingKingStudios::Tools::Toolbox::Subclass
+
+    # Generates a Thor::Task wrapping a Cuprum::Cli command class.
+    class Builder
+      extend Forwardable
+
+      NUMERIC_TYPES = Set.new(%w[big_decimal integer float]).freeze
+      private_constant :NUMERIC_TYPES
+
+      # @param command_class [Class] the command to execute.
+      def initialize(command_class)
+        validate_command_class(command_class)
+
+        @command_class = command_class
+        @full_name     = nil
+      end
+
+      # @return [Class] the command to execute.
+      attr_reader :command_class
+
+      def_delegators :@command_class,
+        :arguments,
+        :description,
+        :full_description,
+        :full_description?
+
+      # Generates a Thor::Task wrapping the command class.
+      #
+      # The generated task will be assigned Thor metadata automatically, based
+      # on the configuration of the command class.
+      #
+      # @return [Class] the generated Task class.
+      def build(full_name: nil)
+        @full_name = full_name || command_class.full_name
+
+        tools.assertions.validate_name(@full_name, as: 'full_name')
+
+        Cuprum::Cli::Integrations::Thor::Task
+          .subclass(command_class)
+          .tap do |task|
+            apply_metadata(task)
+
+            task.alias_method short_name, :call_command
+          end
+      end
+
+      private
+
+      attr_reader :full_name
+
+      def apply_options(task)
+        command_class.options.each_value do |option|
+          params = {
+            aliases:  option.aliases,
+            banner:   option.parameter_name || option.name.to_s.upcase,
+            desc:     option.description,
+            required: option.required?,
+            type:     parameter_type(option)
+          }
+
+          task.option(option.name, **params)
+        end
+      end
+
+      def apply_metadata(task)
+        task.namespace(namespace)
+        task.desc(signature, description)
+
+        task.long_desc(full_description) if full_description?
+
+        apply_options(task)
+
+        task
+      end
+
+      def argument_signature(argument)
+        signature = argument.parameter_name || argument.name.to_s.upcase
+
+        argument.variadic ? " ...#{signature}" : " #{signature}"
+      end
+
+      def arguments_signature
+        arguments.map { |argument| argument_signature(argument) }.join
+      end
+
+      def namespace
+        return 'default' if full_name.nil? || !full_name.include?(':')
+
+        full_name&.sub(/:[\w_]+\z/, '')
+      end
+
+      def parameter_type(parameter)
+        type = parameter.type
+        type = type.name if type.is_a?(Class)
+        type = tools.string_tools.underscore(type)
+
+        return :numeric if NUMERIC_TYPES.include?(type)
+
+        type.to_sym
+      end
+
+      def short_name
+        full_name&.split(':')&.last
+      end
+
+      def signature
+        "#{short_name}#{arguments_signature}"
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+
+      def validate_command_class(command_class, as: 'command_class')
+        tools.assertions.validate_class(command_class, as:)
+        tools.assertions.validate_inherits_from(
+          command_class,
+          as:,
+          expected: Cuprum::Cli::Command
+        )
+
+        validate_command_description(command_class, as:)
+      end
+
+      def validate_command_description(command_class, as:)
+        description = command_class.description
+
+        return unless description.nil? || description.empty?
+
+        raise ArgumentError, "#{as} does not have a description"
+      end
+    end
+
+    # Ensures that the task exists with a non-zero status code on a failure.
+    #
+    # @return [true]
+    def self.exit_on_failure? = true
+
+    # @overload initialize(command_class, arguments = [], options = {}, config = {})
+    #   @param command_class [Class] the command to execute.
+    #   @param arguments [Array] the arguments passed by the Thor runtime.
+    #   @param options [Hash] the options passed by the Thor runtime.
+    #   @param config [Hash] additional configuration passed by the Thor
+    #     runtime.
+    def initialize(
+      command_class,
+      arguments = [],
+      options   = {},
+      config    = {},
+      command_dependencies: {}
+    )
+      super(arguments, options, config)
+
+      @command_class = command_class
+      @command_dependencies = command_dependencies
+    end
+
+    # @return [Class] the command to execute.
+    attr_reader :command_class
+
+    no_commands do
+      # Calls the wrapped Cuprum::Cli command with the parsed parameters.
+      def call_command(*args)
+        args, opts =
+          Cuprum::Cli::Integrations::Thor::ArgumentsParser.new.call(*args)
+        opts       = opts.merge(options)
+        opts       = tools.hash_tools.convert_keys_to_symbols(opts)
+        result     =
+          command_class.new(**command_dependencies).call(*args, **opts)
+
+        handle_failure(result) if result.failure?
+      rescue Cuprum::Cli::Options::UnknownOptionError,
+             Cuprum::Cli::Arguments::ExtraArgumentsError => exception
+        abort(exception.message)
+      end
+    end
+
+    private
+
+    attr_reader :command_dependencies
+
+    def abort(*) = Kernel.abort(*)
+
+    def handle_failure(result)
+      message =
+        result
+        .error
+        &.then { |err| "#{err.class.name}: #{err.message}" } || false
+
+      abort(message)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/cli/integrations/thor.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/integrations'
+
+module Cuprum::Cli::Integrations
+  # Integration with the Thor CLI toolkit.
+  #
+  # @see http://whatisthor.com/
+  module Thor
+    autoload :ArgumentsParser, 'cuprum/cli/integrations/thor/arguments_parser'
+    autoload :Registry,        'cuprum/cli/integrations/thor/registry'
+    autoload :Task,            'cuprum/cli/integrations/thor/task'
+  end
+end

data/lib/cuprum/cli/integrations.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Namespace for integrations with other command-line tools.
+  module Integrations; end
+end

data/lib/cuprum/cli/metadata.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Class methods for describing commands.
+  module Metadata
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Format used to validate command names.
+    FULL_NAME_FORMAT = /\A[a-z_]+(:[a-z_]+)*\z/
+
+    UNDEFINED = SleepingKingStudios::Tools::UNDEFINED
+    private_constant :UNDEFINED
+
+    # Raised when performing a protected operation on an abstract Command.
+    class AbstractCommandError < StandardError; end
+
+    # Class methods to extend when including Metadata.
+    module ClassMethods
+      # Marks the command as abstract.
+      def abstract = @abstract = true
+
+      # @return [true, false] true if the command is abstract and should not be
+      #   instantiated directly or assigned metadata; otherwise false.
+      def abstract? = @abstract.nil? ? false : @abstract
+
+      # @overload description
+      #   @return [String] the description for the command.
+      #
+      # @overload description(value)
+      #   Sets the description for the command.
+      #
+      #   @param value [String] the description to set.
+      #
+      #   @return [String] the set description.
+      def description(value = UNDEFINED)
+        return defined_description if value == UNDEFINED
+
+        if abstract?
+          raise AbstractCommandError,
+            abstract_command_message('set description')
+        end
+
+        tools.assertions.validate_name(value, as: 'description')
+
+        @description = value
+      end
+
+      # @return [true, false] true if the command defines a description;
+      #   otherwise false.
+      def description? = !defined_description.nil?
+
+      # @overload full_description
+      #   @return [String] the full description for the command.
+      #
+      # @overload full_description(value)
+      #   Sets the full description for the command.
+      #
+      #   @param value [String] the full description to set.
+      #
+      #   @return [String] the set full description.
+      def full_description(value = UNDEFINED)
+        if value == UNDEFINED
+          return defined_full_description || defined_description
+        end
+
+        if abstract?
+          raise AbstractCommandError,
+            abstract_command_message('set full_description')
+        end
+
+        tools.assertions.validate_name(value, as: 'full_description')
+
+        @full_description = value
+      end
+
+      # @return [true, false] true if the command defines a full description;
+      #   otherwise false.
+      def full_description? = !defined_full_description.nil?
+
+      # @overload full_name
+      #   Returns the name of the command, used when calling from a CLI.
+      #
+      #   Unless another value is set, defaults to the class name of the command
+      #   with the following format:
+      #
+      #   - Removes the "Commands" namespace and any prior namespace, if any.
+      #   - Removes a "Command" suffix, if any.
+      #   - Converts each remaining segment to snake_case and joins with ":".
+      #
+      #   @return [String] the scoped name for the command.
+      #
+      # @overload full_name(value)
+      #   Sets the full name for the command.
+      #
+      #   The full name must be in snake_case format joined by ":".
+      #
+      #   @param value [String] the full name to set.
+      #
+      #   @return [String] the set full name.
+      def full_name(value = UNDEFINED) # rubocop:disable Metrics/MethodLength
+        return defined_full_name if value == UNDEFINED
+
+        if abstract?
+          raise AbstractCommandError, abstract_command_message('set full_name')
+        end
+
+        tools.assertions.validate_name(value, as: 'full_name')
+        tools.assertions.validate_matches(
+          value,
+          as:       'full_name',
+          expected: FULL_NAME_FORMAT,
+          message:  invalid_full_name_format_message
+        )
+
+        @full_name = value
+      end
+
+      # The namespace for the command.
+      #
+      # A command's namespace is defined as the part of the full name prior to
+      # the last segment.
+      #
+      # - For a command with full name "custom", the namespace will be nil.
+      # - For a command with full name "category:sub_category:do_something", the
+      #   namespace will be "category:sub_category".
+      #
+      # @return [String, nil] the namespace for the command, or nil if the
+      #   command's full name is unscoped.
+      #
+      # @see #short_name.
+      def namespace
+        return if full_name.nil? || !full_name.include?(':')
+
+        full_name&.sub(/:[\w_]+\z/, '')
+      end
+
+      # @return [true, false] true if the command defines a namespace; otherwise
+      #   false.
+      def namespace? = !namespace.nil?
+
+      # The short name for the command.
+      #
+      # A command's short_name is the last segment of the full name.
+      #
+      # - For a command with full name "custom", the short_name will be
+      #   "custom".
+      # - For a command with full name "category:sub_category:do_something", the
+      #   short_name will be "do_something".
+      #
+      # @return [String] the short name for the command.
+      def short_name = full_name&.split(':')&.last
+
+      protected
+
+      def abstract_command_message(short_message)
+        class_name =
+          ancestors
+          .find { |ancestor| ancestor.is_a?(Class) && ancestor.name }
+          .name
+
+        "unable to #{short_message} - #{class_name} is an abstract class"
+      end
+
+      def defined_description
+        return @description if @description
+
+        return unless superclass.respond_to?(:defined_description, true)
+
+        superclass.defined_description
+      end
+
+      def defined_full_description
+        return @full_description if @full_description
+
+        return unless superclass.respond_to?(:defined_full_description, true)
+
+        superclass.defined_full_description
+      end
+
+      def defined_full_name
+        return @full_name if @full_name ||= default_name
+
+        return unless superclass.respond_to?(:defined_full_name, true)
+
+        return if superclass.name == 'Cuprum::Cli::Command'
+
+        superclass.defined_full_name
+      end
+
+      private
+
+      def default_name
+        return if name.nil?
+
+        name
+          .split('Commands::')
+          .last
+          .sub(/Command\z/, '')
+          .split('::')
+          .map { |str| tools.string_tools.underscore(str) }
+          .join(':')
+      end
+
+      def invalid_full_name_format_message
+        'full_name does not match format category:sub_category:do_something'
+      end
+
+      def tools = SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end