cuprum-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0569f2b0f6fd69ffae0141d299421c0a42d91182e8d795151ab0d8994838cf5
+  data.tar.gz: d585735c4712bd25a0729c09fb8547e46b0e4a2222d3cf1476c178ea17d54bc1
+SHA512:
+  metadata.gz: b65e0e51ef3d04c4adb58998dc62e3a153e9e8cb2c44f21fd540798993bf13633e7079c07df56a03e30d0d0d5300f31b3eeacf3b2575ae4c88f513ecd60f5e1f
+  data.tar.gz: d0b99e59cc83645160bad0fec52432cee1d10b1f7efaf4f5771dff0c7a1df747dd2e9364ac27994ba73b17aaa6c74070711ff048e4185512a085a2d85346d6ee

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.0
+
+Initial version.
+
+## Commands
+
+Implemented `Cuprum::Cli::Command`
+
+- Added support for positional arguments
+- Added support for keyword options and flags
+
+### Built-In Commands
+
+- Implemented `Cuprum::Cli::Ci::RSpecCommand`
+- Implemented `Cuprum::Cli::Ci::RSpecEachCommand`
+- Implemented `Cuprum::Cli::File::NewCommand`
+
+### Dependencies
+
+- Implemented `Cuprum::Cli::Dependencies::FileSystem`
+- Implemented `Cuprum::Cli::Dependencies::StandardIo`
+- Implemented `Cuprum::Cli::Dependencies::SystemCommand`
+
+### Registries
+
+- Implemented `Cuprum::Cli::Registry`
+
+## Integrations
+
+Added `Thor` integration
+
+- Implemented `Cuprum::Cli::Integrations::Thor::Registry`

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"cuprum-cli" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["sleepingkingstudios@gmail.com"](mailto:"sleepingkingstudios@gmail.com").

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rob Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,163 @@
+# Cuprum::Cli
+
+A command-line utility powered by [Cuprum](https://www.sleepingkingstudios.com/cuprum/) that provides tools and utilities for defining command-line tools.
+
+<blockquote>
+  Read The
+  <a href="https://www.sleepingkingstudios.com/cuprum-cli" target="_blank">
+    Documentation
+  </a>
+</blockquote>
+
+## About
+
+### Documentation
+
+Documentation is generated using [YARD](https://yardoc.org/), and can be generated locally using the `yard` gem.
+
+### License
+
+Copyright (c) 2026 Rob Smith
+
+`Cuprum::Cli` is released under the [MIT License](https://opensource.org/licenses/MIT).
+
+### Contribute
+
+The canonical repository for this gem is located at https://github.com/sleepingkingstudios/cuprum-cli.
+
+To report a bug or submit a feature request, please use the [Issue Tracker](https://github.com/sleepingkingstudios/cuprum-cli/issues).
+
+To contribute code, please fork the repository, make the desired updates, and then provide a [Pull Request](https://github.com/sleepingkingstudios/cuprum-cli/pulls). Pull requests must include appropriate tests for consideration, and all code must be properly formatted.
+
+### Code of Conduct
+
+Please note that the `Cuprum::Cli` project is released with a [Contributor Code of Conduct](https://github.com/sleepingkingstudios/cuprum-cli/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
+
+### Local Development
+
+The test suite for `Cuprum::Cli` is written using [RSpec](https://rspec.info/), with optional integration dependencies managed using [Appraisal](https://github.com/thoughtbot/appraisal).
+
+To run the general test suite:
+
+```bash
+bundle exec rspec
+```
+
+To run the test suite including the `Thor` integration:
+
+```bash
+BUNDLER_GEMFILE=gemfiles/integrations_thor.gemfile INTEGRATION=thor bundle exec rspec
+```
+
+To run the [RuboCop](https://rubocop.org/) linter:
+
+```bash
+bundle exec rubocop
+```
+
+## Getting Started
+
+Add the gem to your Gemfile or gemspec:
+
+```ruby
+group :development, :test do
+  gem 'cuprum-cli'
+end
+```
+
+To ensure that dependent libraries are loaded, call the `Cuprum::Cli` initializer:
+
+- In the initializer for your project:
+
+  ```ruby
+  module Space
+    @initializer = SleepingKingStudios::Tools::Toolbox::Initializer.new do
+      Cuprum::Cli.initializer.call
+    end
+  end
+  ```
+
+- Or, in the entry points of your application (such as a `bin` script or `spec_helper.rb`).
+
+Set up a <a href="https://www.sleepingkingstudios.com/cuprum-cli/integrations" target="_blank">CLI integration</a> and register your commands:
+
+```ruby
+# In tasks.thor:
+require 'cuprum/cli/integrations/thor/registry'
+
+Cuprum::Cli.initializer.call
+
+registry = Cuprum::Cli::Integrations::Thor::Registry.new
+
+registry.register Cuprum::Cli::Commands::Ci::RSpecCommand
+registry.register Cuprum::Cli::Commands::Ci::RSpecCommand,
+  full_name:   'ci:rspec:sinatra4',
+  description: 'Runs the RSpec tests against Sinatra 4.X',
+  options:     { gemfile: 'gemfiles/sinatra_4.gemfile' }
+```
+
+Finally, you can call the commands from your CLI tool:
+
+```
+% bundle exec thor list
+ci
+--
+thor ci:rspec ...FILE_PATTERNS       # Runs an RSpec command.
+thor ci:rspec:sinatra4 ...FILE_PATTERNS  # Runs the RSpec tests against Sinatra 4.X
+```
+
+### Defining Commands
+
+You can also define custom CLI commands using the `Cuprum::Cli::Command` class. `Cuprum::Cli` defines a powerful DSL for quickly defining and configuring commands.
+
+```ruby
+class PingCommand < Cuprum::Cli::Command
+  dependency :system_command
+
+  argument :service_url,
+    default:     'www.example.com',
+    description: 'The URL of the remote service',
+    type:        String
+
+  option :interval,
+    aliases:     'i',
+    default:     0.1,
+    description: 'The interval between pings',
+    type:        Float
+
+  option :max_count,
+    aliases:     %w[c],
+    default:     5,
+    description: 'The total number of pings sent to the server',
+    type:        Integer
+
+  private
+
+  def format_options
+    # The ping command uses a non-standard options format.
+    options = +''
+
+    options << "-c#{max_count}"
+    options << "-i#{interval}"
+    options << '-q' # Only display the summary line.
+  end
+
+  def process
+    system_command.capture(
+      'ping',
+      arguments: [format_options, service_url]
+    )
+  end
+end
+```
+
+Now that we've defined a custom command, we can register it in our CLI integration:
+
+```ruby
+registry.register PingCommand
+registry.register PingCommand,
+  full_name: 'ping:github',
+  options:   { service_url: 'github.com' }
+```
+
+For more information on defining commands, see the <a href="https://www.sleepingkingstudios.com/cuprum-cli/commands" target="_blank">commands documentation</a>.

data/lib/cuprum/cli/argument.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+require 'cuprum/cli/arguments'
+
+module Cuprum::Cli # rubocop:disable Metrics/ModuleLength
+  # Data object representing a positional command argument.
+  Argument = Data.define(
+    :default,
+    :description,
+    :name,
+    :parameter_name,
+    :required,
+    :type,
+    :variadic
+  ) do
+    # @param name [String, Symbol] the name of the argument.
+    # @param default [Object, Proc] the default value for the argument. If given
+    #   and the value of the argument is nil, sets the argument value to the
+    #   default value.
+    # @param description [String] a short, human-readable description of the
+    #   argument.
+    # @param parameter_name [String] a representation of the possible values for
+    #   the argument.
+    # @param required [true, false] if true, raises an exception if the argument
+    #   is not provided to the command.
+    # @param type [Class, String, Symbol] the expected type of the argument
+    #   value as a Class or class name. If given, raises an exception if the
+    #   argument value is not an instance of the type. Defaults to :string.
+    # @param variadic [true, false] if true, the argument is variadic and
+    #   represents an array of arguments provided to the command. Defaults to
+    #   false.
+    def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      name:,
+      default:        nil,
+      description:    nil,
+      parameter_name: nil,
+      required:       false,
+      type:           :string,
+      variadic:       false
+    )
+      name     = name.to_sym
+      required = required ? true : false
+      type     = type.to_sym if type.is_a?(String)
+      variadic = variadic ? true : false
+
+      super(
+        default:,
+        description:,
+        name:,
+        parameter_name:,
+        required:,
+        type:,
+        variadic:
+      )
+    end
+
+    alias_method :required?, :required
+
+    alias_method :variadic?, :variadic
+
+    # @overload def resolve(value)
+    #   Validates the value for the current argument.
+    #
+    #   If the value is nil, applies the argument default (if any).
+    #
+    #   @param value [Object] the value to validate.
+    #
+    #   @return [Object] the validated argument value.
+    #
+    #   @raise [Cuprum::Cli::Arguments::InvalidArgumentError] if the value is
+    #     missing (for a required argument) or invalid.
+    def resolve(original_value) # rubocop:disable Metrics/CyclomaticComplexity
+      return resolve_variadic(original_value) if variadic?
+
+      value = original_value
+      value = default_value if blank?(value)
+      value = value.to_s    if value.is_a?(Symbol)
+
+      return (type == :boolean ? false : nil) if value.nil? && !required?
+
+      return value if valid_argument?(value)
+
+      raise Cuprum::Cli::Arguments::InvalidArgumentError,
+        invalid_argument_message(original_value)
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def default_value
+      default.is_a?(Proc) ? default.call : default
+    end
+
+    def expected_array_type # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      message = required? ? 'a non-empty Array of' : 'an Array of'
+
+      case type
+      when :boolean
+        "#{message} true or false"
+      when Class
+        name = tools.string_tools.pluralize(type.name)
+
+        "#{message} #{tools.string_tools.camelize(name)}"
+      else
+        name = tools.string_tools.pluralize(type.to_s)
+
+        "#{message} #{tools.string_tools.camelize(name)}"
+      end
+    end
+
+    def expected_type
+      case type
+      when :boolean
+        'true or false'
+      when Class
+        "an instance of #{type.name}"
+      else
+        "an instance of #{tools.string_tools.camelize(type.to_s)}"
+      end
+    end
+
+    def invalid_argument_message(value)
+      "invalid value for argument :#{name} - expected #{expected_type}, " \
+        "received #{value.inspect}"
+    end
+
+    def invalid_variadic_argument_message(value)
+      "invalid value for variadic argument :#{name} - expected " \
+        "#{expected_array_type}, received #{value.inspect}"
+    end
+
+    def resolve_variadic(original_value)
+      value = original_value
+      value = default_value if blank?(value)
+
+      return [] if value.nil? && !required?
+
+      return value if valid_arguments?(value)
+
+      raise Cuprum::Cli::Arguments::InvalidArgumentError,
+        invalid_variadic_argument_message(original_value)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def valid_argument?(value)
+      case type
+      when :boolean
+        value == true || value == false # rubocop:disable Style/MultipleComparison
+      when Class
+        value.is_a?(type)
+      else
+        expected = tools.string_tools.camelize(type.to_s)
+        expected = Object.const_get(expected)
+
+        value.is_a?(expected)
+      end
+    end
+
+    def valid_arguments?(value)
+      return false unless value.is_a?(Array)
+
+      value.all? { |item| valid_argument?(item) }
+    end
+  end
+end

data/lib/cuprum/cli/arguments/class_methods.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require 'weakref'
+
+require 'cuprum/cli/arguments'
+
+module Cuprum::Cli::Arguments
+  # Methods used to extend command class functionality for defining arguments.
+  module ClassMethods
+    # Helper class for defining command arguments.
+    class Builder
+      # @param command_class [Class] the command class.
+      # @param defined_arguments [Array<Cuprum::Cli::Argument>] the arguments
+      #   defined for the command.
+      def initialize(command_class:, defined_arguments:)
+        @command_class     = command_class
+        @defined_arguments = defined_arguments
+      end
+
+      # @return [Class] the command class.
+      attr_reader :command_class
+
+      # @return [Array<Cuprum::Cli::Argument>] the arguments defined for the
+      #   command.
+      attr_reader :defined_arguments
+
+      # (see Cuprum::Cli::Arguments::ClassMethods#argument)
+      def call(name, define_method: nil, define_predicate: nil, **options)
+        argument = Cuprum::Cli::Argument.new(name:, **options)
+
+        defined_arguments << argument
+
+        define_method    = (options[:type] != :boolean) if define_method.nil?
+        define_predicate = (options[:type] == :boolean) if define_predicate.nil?
+
+        define_method_for(argument)    if define_method
+        define_predicate_for(argument) if define_predicate
+
+        argument.name
+      end
+
+      private
+
+      def define_method_for(argument)
+        command_class.define_method(argument.name) { @arguments[argument.name] }
+      end
+
+      def define_predicate_for(argument)
+        command_class.define_method(:"#{argument.name}?") do
+          value = @arguments[argument.name]
+
+          return false if value.nil? || value == false
+
+          !(value.respond_to?(:empty?) && value.empty?)
+        end
+      end
+    end
+
+    # @private
+    class VariadicArgumentsResolver
+      def initialize(defined_arguments)
+        @defined_arguments = defined_arguments
+        @variadic_index    = defined_arguments.index(&:variadic?)
+        @variadic_argument = defined_arguments[variadic_index]
+        @before_arguments  = defined_arguments[...variadic_index]
+        @after_arguments   = defined_arguments[(1 + variadic_index)..]
+        @resolved          = {}
+      end
+
+      # @private
+      def call(*values)
+        values = resolve_before(values)
+        values = resolve_after(values)
+
+        resolved[variadic_argument.name] = values
+
+        resolved
+      end
+
+      private
+
+      attr_reader :after_arguments
+
+      attr_reader :before_arguments
+
+      attr_reader :resolved
+
+      attr_reader :variadic_argument
+
+      attr_reader :variadic_index
+
+      def resolve_after(values) # rubocop:disable Metrics/AbcSize
+        extra_count = values.count - after_arguments.count
+
+        if extra_count.negative?
+          values.concat(Array.new(-extra_count))
+
+          extra_count = 0
+        end
+
+        after_arguments&.each&.with_index(extra_count) do |argument, index|
+          resolved[argument.name] = argument.resolve(values[index])
+        end
+
+        values[...extra_count]
+      end
+
+      def resolve_before(values)
+        before_arguments&.each&.with_index do |argument, index|
+          resolved[argument.name] = argument.resolve(values[index])
+        end
+
+        values[before_arguments.count...] || []
+      end
+    end
+    private_constant :VariadicArgumentsResolver
+
+    # @overload argument(name, default: nil, description: nil, required: false, type: :string, variadic: false, **options)
+    #   Defines an argument for the command class.
+    #
+    #   @param name [String, Symbol] the name of the argument.
+    #   @param default [Object, Proc] the default value for the argument. If
+    #     given and the value of the argument is nil, sets the argument value to
+    #     the default value.
+    #   @param description [String] a short, human-readable description of the
+    #     argument.
+    #   @param required [true, false] if true, raises an exception if the
+    #     argument is not provided to the command. Defaults to false.
+    #   @param type [Class, String, Symbol] the expected type of the argument
+    #     value as a Class or class name. If given, raises an exception if the
+    #     argument value is not an instance of the type. Defaults to :string.
+    #   @param variadic [true, false] if true, the argument is variadic and
+    #     represents an array of arguments provided to the command. Defaults to
+    #     false.
+    #   @param options [Hash] additional options for defining the argument.
+    #
+    #   @option options define_method [true, false] if true, defines a reader
+    #     method for the argument. Defaults to false for boolean arguments and
+    #     true for all other arguments.
+    #   @option options define_predicate [true, false] if true, defines a
+    #     predicate method for the argument, which returns true if the argument
+    #     is not nil and not empty. Defaults to true for boolean arguments and
+    #     false for all other arguments.
+    #
+    #   @raise [ArgumentError] if variadic is true and the command already
+    #     defines a variadic argument.
+    def argument(name, define_method: nil, define_predicate: nil, **)
+      handle_multiple_variadic_arguments(**)
+
+      arguments_builder.call(name, define_method:, define_predicate:, **)
+    end
+
+    # Appends a predefined argument value for the command.
+    #
+    # @param value [Object] the argument value to append.
+    #
+    # @return [void]
+    def argument_value(value)
+      defined_argument_values << value
+
+      nil
+    end
+
+    # @return [Array<Object>] predefined argument values for the command.
+    def argument_values = defined_argument_values
+
+    # @overload arguments()
+    #   The defined arguments for the command class.
+    #
+    #   @return [Array<Cuprum::Cli::Argument>] the defined arguments.
+    #
+    # @overload arguments(name, default: nil, description: nil, required: false, type: :string, **options)
+    #   Defines a variadic argument for the command class.
+    #
+    #   @param name [String, Symbol] the name of the argument.
+    #   @param default [Object, Proc] the default value for the argument. If
+    #     given and the value of the argument is nil, sets the argument value to
+    #     the default value.
+    #   @param description [String] a short, human-readable description of the
+    #     argument.
+    #   @param required [true, false] if true, raises an exception if the
+    #     argument is not provided to the command.
+    #   @param type [Class, String, Symbol] the expected type of the argument
+    #     value as a Class or class name. If given, raises an exception if the
+    #     argument value is not an instance of the type. Defaults to :string.
+    #   @param options [Hash] additional options for defining the argument.
+    #
+    #   @option options define_method [true, false] if true, defines a reader
+    #     method for the argument. Defaults to false for boolean arguments and
+    #     true for all other arguments.
+    #   @option options define_predicate [true, false] if true, defines a
+    #     predicate method for the argument, which returns true if the argument
+    #     is not nil and not empty. Defaults to true for boolean arguments and
+    #     false for all other arguments.
+    def arguments(name = nil, **)
+      if name.nil?
+        return defined_arguments unless defined_arguments.empty?
+
+        return superclass.arguments if superclass.respond_to?(:arguments)
+
+        return []
+      end
+
+      argument(name, **, variadic: true)
+    end
+
+    # Validates the given argument values against the defined class arguments.
+    #
+    # Also applies any default values from the defined arguments.
+    #
+    # @param values [Array] the arguments values to resolve.
+    #
+    # @return [Array] the arguments values with applied defaults.
+    #
+    # @raise [Cuprum::Cli::Arguments::ExtraArgumentsError] if provided more
+    #   arguments than the command class defines arguments.
+    # @raise [Cuprum::Cli::Arguments::InvalidArgumentError] if any value does
+    #   not match the expected argument type, or any required value is missing.
+    def resolve_arguments(*values) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      values            = argument_values + values
+      defined_arguments = arguments
+
+      if defined_arguments.any?(&:variadic?)
+        return VariadicArgumentsResolver.new(defined_arguments).call(*values)
+      end
+
+      if values.size > defined_arguments.size
+        raise Cuprum::Cli::Arguments::ExtraArgumentsError,
+          extra_arguments_message(values.size)
+      end
+
+      defined_arguments.each.with_index.to_h do |argument, index|
+        [argument.name, argument.resolve(values[index])]
+      end
+    end
+
+    private
+
+    def arguments_builder
+      (
+        @arguments_builder ||= WeakRef.new(
+          Builder.new(command_class: self, defined_arguments:)
+        )
+      ).__getobj__
+    rescue RefError
+      # :nocov:
+      @arguments_builder = WeakRef.new(
+        Builder.new(command_class: self, defined_arguments:)
+      )
+      @arguments_builder.__getobj__
+      # :nocov:
+    end
+
+    def defined_argument_values
+      @defined_argument_values ||= []
+    end
+
+    def defined_arguments
+      @defined_arguments ||= []
+    end
+
+    def extra_arguments_message(count)
+      total_count   = defined_arguments.size
+      last_required = (arguments.rindex(&:required?) || -1) + 1
+      expected      =
+        last_required == total_count ? total_count : last_required..total_count
+
+      "wrong number of arguments (given #{count}, expected #{expected})"
+    end
+
+    def handle_multiple_variadic_arguments(variadic: false, **)
+      return unless variadic
+
+      matching = defined_arguments.find(&:variadic?)
+
+      return unless matching
+
+      message = "command already defines variadic argument :#{matching.name}"
+
+      raise ArgumentError, message
+    end
+  end
+end