cuprum-cli 0.1.0

data/lib/cuprum/cli/dependencies/standard_io/mock.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+require 'cuprum/cli/dependencies/standard_io'
+
+module Cuprum::Cli::Dependencies
+  # Mock implementation of StandardIo for testing purposes.
+  class StandardIo::Mock < Cuprum::Cli::Dependencies::StandardIo
+    # @overload append_for_read(*messages, io:)
+    #   Utility method for appending readable data to a StringIO stream.
+    #
+    #   @param messages [Array<String>] the messages to append. Will be appended
+    #     to the stream in the provided order.
+    #   @param io [IO] the io stream to append.
+    #
+    #   @return [IO] the io stream.
+    def self.append_for_read(*messages, io:)
+      total_length = 0
+
+      messages.each do |message|
+        message += "\n" unless message.end_with?("\n")
+
+        io.print(message)
+
+        total_length += message.length
+      end
+
+      io.pos -= total_length
+
+      io
+    end
+
+    # @param error_stream [IO] the error stream. Defaults to an instance of
+    #   StringIO.
+    # @param input_stream [IO] the input stream. Defaults to an instance of
+    #   StringIO.
+    # @param output_stream [IO] the output stream. Defaulst to an instance of
+    #   StringIO.
+    def initialize(
+      error_stream:  StringIO.new,
+      input_stream:  StringIO.new,
+      output_stream: StringIO.new
+    )
+      super
+
+      @combined_stream = StringIO.new
+    end
+
+    # @return [IO] a combined input/output stream representing all IO activity.
+    attr_reader :combined_stream
+
+    # @return [IO] the error stream
+    def error_stream = super # rubocop:disable Lint/UselessMethodDefinition
+
+    # @return [IO] the input stream.
+    def input_stream = super # rubocop:disable Lint/UselessMethodDefinition
+
+    # @return [IO] the output stream.
+    def output_stream = super # rubocop:disable Lint/UselessMethodDefinition
+
+    # (see Cuprum::Cli::Dependencies::StandardIo#read_input)
+    def read_input
+      message = super
+
+      combined_stream.print(message) if message
+
+      message
+    end
+
+    # (see Cuprum::Cli::Dependencies::StandardIo#write_output)
+    def write_output(message = nil, newline: true)
+      super
+
+      newline ? combined_stream.puts(message) : combined_stream.print(message)
+    end
+
+    # (see Cuprum::Cli::Dependencies::StandardIo#write_error)
+    def write_error(message = nil, newline: true)
+      super
+
+      newline ? combined_stream.puts(message) : combined_stream.print(message)
+    end
+  end
+end

data/lib/cuprum/cli/dependencies/standard_io.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/dependencies'
+
+module Cuprum::Cli::Dependencies
+  # Utility wrapping standard input, output, and error IO streams.
+  class StandardIo
+    autoload :Helpers, 'cuprum/cli/dependencies/standard_io/helpers'
+    autoload :Mock,    'cuprum/cli/dependencies/standard_io/mock'
+
+    ANSI_COLORS = {
+      'black'  => 0,
+      'blue'   => 34,
+      'green'  => 32,
+      'purple' => 35,
+      'red'    => 31,
+      'yellow' => 33
+    }.freeze
+    private_constant :ANSI_COLORS
+
+    # @param error_stream [IO] the error stream. Defaults to $stderr.
+    # @param input_stream [IO] the input stream. Defaults to $stdin.
+    # @param output_stream [IO] the output stream. Defaulst to $stdout.
+    def initialize(
+      error_stream:  -> { $stderr },
+      input_stream:  -> { $stdin },
+      output_stream: -> { $stdout }
+    )
+      @lazy_error_stream  = error_stream
+      @lazy_input_stream  = input_stream
+      @lazy_output_stream = output_stream
+    end
+
+    # Wraps the text in an ANSI color escape code.
+    #
+    # @param text [String] the text to colorize.
+    # @param color [String] the color to apply.
+    #
+    # @return [String] the colorized string.
+    #
+    # @raise [KeyError] if the requested color does not have an escape code.
+    def color(text, color)
+      color_code = ANSI_COLORS.fetch(color.to_s)
+
+      "\e[#{color_code}m#{text}\e[0m"
+    end
+
+    # Requests a newline-terminated string from the input stream.
+    #
+    # @return [String] the returned input string.
+    def read_input
+      input_stream.gets
+    end
+
+    # Writes the given message to the error stream.
+    #
+    # If no error message is given, prints a newline only.
+    #
+    # @param message [String, nil] the message to write.
+    # @param newline [true, false] if true, appends a newline to the message if
+    #   it does not have a newline. Defaults to true.
+    #
+    # @return [nil]
+    def write_error(message = nil, newline: true)
+      newline ? error_stream.puts(message) : error_stream.print(message)
+    end
+
+    # Writes the given message to the output stream.
+    #
+    # If no message is given, prints a newline only.
+    #
+    # @param message [String, nil] the message to write.
+    # @param newline [true, false] if true, appends a newline to the message if
+    #   it does not have a newline. Defaults to true.
+    #
+    # @return [nil]
+    def write_output(message = nil, newline: true)
+      newline ? output_stream.puts(message) : output_stream.print(message)
+    end
+
+    private
+
+    def error_stream
+      @error_stream ||=
+        if @lazy_error_stream.is_a?(Proc)
+          @lazy_error_stream.call
+        else
+          @lazy_error_stream
+        end
+    end
+
+    def input_stream
+      @input_stream ||=
+        if @lazy_input_stream.is_a?(Proc)
+          @lazy_input_stream.call
+        else
+          @lazy_input_stream
+        end
+    end
+
+    def output_stream
+      @output_stream ||=
+        if @lazy_output_stream.is_a?(Proc)
+          @lazy_output_stream.call
+        else
+          @lazy_output_stream
+        end
+    end
+  end
+end

data/lib/cuprum/cli/dependencies/system_command/mock.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/dependencies/system_command'
+
+module Cuprum::Cli::Dependencies
+  # Mock implementation of SystemCommand for testing purposes.
+  class SystemCommand::Mock < Cuprum::Cli::Dependencies::SystemCommand
+    # Data class providing a mock implementation of Process::Status.
+    MockStatus = Data.define(:exitstatus) do
+      # @return [true, false] true if the exit status is zero, otherwise false.
+      def success? = exitstatus.zero?
+    end
+
+    # @param captures [Hash{String => Proc, Array[String, String, Integer]}]
+    #   the captured values to return. If the captures Hash has a key matching
+    #   the command, that value will be used to generate the result.
+    def initialize(captures: {})
+      super()
+
+      @captures          = captures
+      @recorded_commands = []
+    end
+
+    # @return [Array<String>] the commands recorded by the mock service.
+    attr_reader :recorded_commands
+
+    private
+
+    attr_reader :captures
+
+    def capture_command(command, **rest)
+      recorded_commands << build_command(command, **rest)
+
+      output, error, exitstatus =
+        captures
+        .fetch(command, ['', '', 0])
+        .then { |capture| capture.is_a?(Proc) ? capture.call(**rest) : capture }
+
+      CapturedOutput.new(
+        output:,
+        error:,
+        status: MockStatus.new(exitstatus:)
+      )
+    end
+
+    def spawn_command(command, **rest)
+      recorded_commands << build_command(command, **rest)
+
+      _, _, exitstatus =
+        captures
+        .fetch(command, ['', '', 0])
+        .then { |capture| capture.is_a?(Proc) ? capture.call(**rest) : capture }
+
+      MockStatus.new(exitstatus:)
+    end
+  end
+end

data/lib/cuprum/cli/dependencies/system_command.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+require 'cuprum/cli/dependencies'
+require 'cuprum/cli/errors/system_command_failure'
+
+module Cuprum::Cli::Dependencies
+  # Utility wrapper for running system command and capturing output.
+  class SystemCommand
+    autoload :Mock, 'cuprum/cli/dependencies/system_command/mock'
+
+    # Data object representing the captured output and status of a process.
+    CapturedOutput = Data.define(:error, :output, :status) do
+      # @return [true, false] true if the process was successful, otherwise
+      #   false.
+      def success? = status.success?
+    end
+
+    # @overload capture(command,.arguments: [], environment: {}, options: {})
+    #   Executes the system command and returns the captured output.
+    #
+    #   @param command [String] the command to run.
+    #   @param arguments [Array<String>] command-line flags or arguments to pass
+    #     to the command.
+    #   @param enviroment [Hash<String, Object>] environment variables to set
+    #     for the command.
+    #   @param options [Hash<String, Object>] command line options and values to
+    #     pass to the command.
+    #
+    #   @return [Cuprum::Result<Cuprum::Cli::Dependencies::SystemCommand::CapturedOutput>]
+    #     a Result wrapping the process status and captured output. The Result
+    #     will have a status of :success if the process ran successfully;
+    #     otherwise, the Result will have a status of :failure
+    def capture(command, **)
+      value = capture_command(command, **)
+
+      return Cuprum::Result.new(value:) if value.success?
+
+      error = Cuprum::Cli::Errors::SystemCommandFailure.new(
+        command:,
+        details:     value.error,
+        exit_status: value.status.exitstatus
+      )
+
+      Cuprum::Result.new(error:, value:)
+    end
+
+    # @overload spawn(command, arguments: [], enviroment:, options: {})
+    #   Spawns a process to run the system command.
+    #
+    #   @param command [String] the command to run.
+    #   @param arguments [Array<String>] command-line flags or arguments to pass
+    #     to the command.
+    #   @param enviroment [Hash<String, Object>] environment variables to set
+    #     for the command.
+    #   @param options [Hash<String, Object>] command line options and values to
+    #     pass to the command.
+    #
+    #   @return [Cuprum::Result<nil>] a result with status :success if the
+    #     process ran successfully; otherwise, a result with status :failure and
+    #     an Error.
+    def spawn(command, **)
+      status = spawn_command(command, **)
+
+      return Cuprum::Result.new if status.success?
+
+      error = Cuprum::Cli::Errors::SystemCommandFailure.new(
+        command:,
+        exit_status: status.exitstatus
+      )
+
+      Cuprum::Result.new(error:)
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def build_command(command, arguments: nil, environment: nil, options: nil)
+      # @todo [RUBY_VERSION <= '3.3'] remove || {} fallbacks.
+      [
+        format_environment(**(environment || {})),
+        command,
+        format_arguments(*arguments),
+        format_options(**(options || {}))
+      ]
+        .reject { |value| value.nil? || value.empty? }
+        .join(' ')
+    end
+
+    def capture_command(command, **)
+      command = build_command(command, **)
+
+      output, error, status = Open3.capture3(command)
+
+      CapturedOutput.new(output:, error:, status:)
+    end
+
+    def format_arguments(*arguments)
+      arguments.join(' ')
+    end
+
+    def format_environment(**environment)
+      environment
+        .reject { |_, value| blank?(value) }
+        .map do |key, value|
+          key = tools.string_tools.underscore(key.to_s).upcase
+
+          "#{key}=#{value.inspect}"
+        end
+        .join(' ')
+    end
+
+    def format_options(**options) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      options
+        .reject { |_, value| blank?(value) }
+        .map do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          key   = key.to_s
+          value = value.inspect
+
+          next "#{key}=#{value}" if key.start_with?('-')
+
+          key = tools.string_tools.underscore(key).tr('_', '-')
+
+          "#{key.length == 1 ? '-' : '--'}#{key}=#{value}"
+        end
+        .join(' ')
+    end
+
+    def spawn_command(command, **)
+      command   = build_command(command, **)
+      pid       = Process.spawn(command)
+      _, status = Process.wait2(pid)
+
+      status
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/cli/dependencies.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Dependencies provide standard functionality to commands.
+  module Dependencies
+    autoload :FileSystem,    'cuprum/cli/dependencies/file_system'
+    autoload :StandardIo,    'cuprum/cli/dependencies/standard_io'
+    autoload :SystemCommand, 'cuprum/cli/dependencies/system_command'
+
+    # @return [Plumbum::Provider] the provider for the standard dependencies.
+    def self.provider
+      @provider ||= Plumbum::ManyProvider.new(
+        values: {
+          file_system:    FileSystem.new,
+          standard_io:    StandardIo.new,
+          system_command: SystemCommand.new
+        }
+      )
+    end
+  end
+end

data/lib/cuprum/cli/errors/files/file_not_writeable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/cli/errors/files'
+
+module Cuprum::Cli::Errors::Files
+  # Error returned when attempting to generate a file in an invalid location.
+  class FileNotWriteable < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.cli.errors.files.file_not_writeable'
+
+    # @param file_path [String] the path to the expected file.
+    # @param message [String] message describing the nature of the error.
+    # @param reason [String] additional details on the error.
+    def initialize(file_path:, message: nil, reason: nil)
+      @file_path = file_path
+      @reason    = reason
+      message    = default_message(file_path:, message:, reason:)
+
+      super
+    end
+
+    # @return [String] the path to the expected file.
+    attr_reader :file_path
+
+    # @return [String] additional details on the error.
+    attr_reader :reason
+
+    private
+
+    def as_json_data = { 'file_path' => file_path, 'reason' => reason }.compact
+
+    def default_message(file_path:, message:, reason:)
+      message ||= "unable to write file #{file_path}"
+
+      return message unless reason
+
+      "#{message} - #{reason}"
+    end
+  end
+end

data/lib/cuprum/cli/errors/files/missing_parameter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/errors/files'
+require 'cuprum/cli/errors/files/template_error'
+
+module Cuprum::Cli::Errors::Files
+  # Error returned when a required parameter is missing when rendering content.
+  class MissingParameter < Cuprum::Cli::Errors::Files::TemplateError
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.cli.errors.files.missing_parameter'
+
+    # @param parameter_name [String, Symbol] the name of the missing parameter.
+    # @param details [String] additional information about the error.
+    # @param format [String] the content format.
+    # @param message [String] an optional message to display.
+    # @param template_name [String] the name of the rendered content, if any,
+    def initialize(
+      parameter_name:,
+      details: nil,
+      format: nil,
+      message: nil,
+      template_name: nil
+    )
+      @parameter_name = parameter_name
+      @format         = format
+      @template_name  = template_name
+
+      super(
+        details:,
+        format:,
+        message:        default_message(message),
+        parameter_name:,
+        template_name:
+      )
+    end
+
+    # @return [String] the content format.
+    attr_reader :format
+
+    # @return [String, Symbol] the name of the missing parameter.
+    attr_reader :parameter_name
+
+    private
+
+    def as_json_data
+      super.merge(
+        'format'         => format,
+        'parameter_name' => parameter_name.to_s
+      ).compact
+    end
+
+    def default_message(message)
+      str = "missing parameter #{parameter_name.inspect}"
+
+      if template_name?
+        str = "#{str} for template #{template_name}"
+        str = "#{str} with format #{format}" if format?
+      elsif format?
+        str = "#{str} for #{format} template"
+      end
+
+      return str unless message && !message.empty?
+
+      "#{message} - #{str}"
+    end
+
+    def format? = format && !format.empty?
+
+    def template_name? = template_name && !template_name.empty?
+  end
+end

data/lib/cuprum/cli/errors/files/missing_template.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/cli/errors/files'
+
+module Cuprum::Cli::Errors::Files
+  # Error returned when unable to load a template.
+  class MissingTemplate < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.cli.errors.files.missing_template'
+
+    # @param template_path [String] the expected template path.
+    # @param message [String] an optional message to display.
+    def initialize(template_path:, message: nil)
+      @template_path = template_path
+
+      super(message: default_message(message), template_path:)
+    end
+
+    # @return [String] the expected template path.
+    attr_reader :template_path
+
+    private
+
+    def as_json_data = { 'template_path' => template_path }
+
+    def default_message(message)
+      str = "unable to load template #{template_path}"
+
+      return str unless message && !message.empty?
+
+      "#{message} - #{str}"
+    end
+  end
+end

data/lib/cuprum/cli/errors/files/template_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/cli/errors/files'
+
+module Cuprum::Cli::Errors::Files
+  # Error returned when an error occurs when generating templated content.
+  class TemplateError < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.cli.errors.files.template_error'
+
+    # @param message [String] message describing the nature of the error.
+    # @param details [String] additional information about the error.
+    # @param template_name [String] the name of the rendered content, if any,
+    def initialize(message:, details: nil, template_name: nil, **)
+      @details       = details
+      @template_name = template_name
+
+      super
+    end
+
+    # @return [String] additional information about the error.
+    attr_reader :details
+
+    # @return [String] the name of the rendered content, if any,
+    attr_reader :template_name
+
+    private
+
+    def as_json_data
+      super
+        .merge('details' => details, 'template_name' => template_name)
+        .compact
+    end
+  end
+end

data/lib/cuprum/cli/errors/files/template_not_resolved.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/errors/files'
+require 'cuprum/cli/errors/files/template_error'
+
+module Cuprum::Cli::Errors::Files
+  # Error returned when unable to resolve a template for a templated file.
+  class TemplateNotResolved < Cuprum::Cli::Errors::Files::TemplateError
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.cli.errors.files.template_not_resolved'
+
+    # @param file_path [String] the file path for the templated file.
+    # @param details [String] additional information about the error.
+    # @param message [String] an optional message to display.
+    # @param options [Hash] options used when attempting to resolve the
+    #   template.
+    def initialize(file_path:, details: nil, message: nil, options: {})
+      @file_path = file_path
+      @options   = options
+
+      super(details:, file_path:, message: default_message(message), options:)
+    end
+
+    # @return [String] the file path for the templated file.
+    attr_reader :file_path
+
+    # @return [Hash] options used when attempting to resolve the template.
+    attr_reader :options
+
+    private
+
+    def as_json_data
+      hsh = super
+
+      hsh['file_path'] = file_path
+      hsh['options']   = options.transform_keys(&:to_s) unless options.empty?
+
+      hsh
+    end
+
+    def default_message(message)
+      str = "unable to resolve template for file #{file_path}"
+      str = "#{str} with options" unless options.empty?
+
+      options.each.with_index do |(key, value), index|
+        str += "#{',' unless index.zero?} #{key}: #{value.inspect}"
+      end
+
+      return str unless message && !message.empty?
+
+      "#{str} - #{message}"
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/errors'
+
+module Cuprum::Cli::Errors
+  # Namespace for errors returned when creating or managing files.
+  module Files
+    autoload :FileNotWriteable,
+      'cuprum/cli/errors/files/file_not_writeable'
+    autoload :MissingParameter,
+      'cuprum/cli/errors/files/missing_parameter'
+    autoload :MissingTemplate,
+      'cuprum/cli/errors/files/missing_template'
+    autoload :TemplateError,
+      'cuprum/cli/errors/files/template_error'
+    autoload :TemplateNotResolved,
+      'cuprum/cli/errors/files/template_not_resolved'
+  end
+end