shopify-cli 1.3.0 → 1.6.0

data/lib/shopify-cli/project_type.rb

@@ -45,8 +45,11 @@ module ShopifyCli
         File.join(ShopifyCli::PROJECT_TYPES_DIR, project_type.to_s, path)
       end
 
-      def creator(name, command_const)
+      def title(name)
         @project_name = name
+      end
+
+      def creator(command_const)
         @project_creator_command_class = command_const
         ShopifyCli::Commands::Create.subcommand(command_const, @project_type)
       end
@@ -55,6 +58,19 @@ module ShopifyCli
         const_get(@project_creator_command_class)
       end
 
+      def connector(command_const)
+        @project_connector_command_class = command_const
+        ShopifyCli::Commands::Connect.subcommand(command_const, @project_type)
+      end
+
+      def connect_command
+        if @project_connector_command_class.nil?
+          nil
+        else
+          const_get(@project_connector_command_class)
+        end
+      end
+
       def register_command(const, cmd)
         return if project_load_shallow
         Context.new.abort(
@@ -65,7 +81,7 @@ module ShopifyCli
 
       def register_task(task, name)
         return if project_load_shallow
-        ShopifyCli::Task.register(task, name)
+        ShopifyCli::Tasks.register(task, name)
       end
 
       def register_messages(messages)

data/lib/shopify-cli/resolve_constant.rb

@@ -0,0 +1,25 @@
+##
+# `ResolveConstant` implements constant resolution. It is implemented as a
+# `MethodObject` and therefore returns a result object. By default, constants
+# are resolved relative to `Kernal`, but the top-level namespace is
+# configurable:
+#
+#    ShopifyCli::Resolve.call(:object).value # => Object
+#    ShopifyCli::Resolve.call('minitest/test').value # => MiniTest::Test
+#    ShopifyCli::Resolve.call(:test, namespace: MiniTest) # => MiniTest::Test
+#
+module ShopifyCli
+  class ResolveConstant
+    include ShopifyCli::MethodObject
+    property! :namespace, accepts: ->(ns) { ns.respond_to?(:const_get) }, default: Kernel
+
+    def call(name)
+      name
+        .to_s
+        .split(%r{/|:{2}})
+        .map { |const_name| const_name.split(/[_-]/).map(&:capitalize).join("") }
+        .join("::")
+        .yield_self { |const_name| namespace.const_get(const_name) }
+    end
+  end
+end

data/lib/shopify-cli/result.rb

@@ -0,0 +1,432 @@
+module ShopifyCli
+  ##
+  # This module defines two containers for wrapping the result of an action. One
+  # for signifying the successful execution of an action and one for signifying
+  # a failure. Both containers implement the same API, which has been designed
+  # to simplify transforming a result through a series of steps and centralize
+  # the error handling in one place. The implementation is heavily inspired by a
+  # concept known as result monads in other languages. Consider the following
+  # example that uses lambda expressions as stand-ins for more complex method
+  # objects:
+  #
+  #   require 'open-uri'
+  #   Todo = Struct.new(:title, :completed)
+  #
+  #   fetch_data = ->(url) { open(url) }
+  #   parse_data = ->(json) { JSON.parse(json) }
+  #   build_todo = ->(attrs) do
+  #     Todo.new(attrs.fetch(:title), attrs.fetch(:completed))
+  #   end
+  #
+  #   Result.wrap(&fetch_data)
+  #     .call("https://jsonplaceholder.typicode.com/todos/1")
+  #     .then(&parse_data)
+  #     .then(&build_todo)
+  #     .map(&:title)
+  #     .unwrap(nil) # => String | nil
+  #
+  # If everything goes well, this code returns the title of the to do that is
+  # being fetched from `https://jsonplaceholder.typicode.com/todos/1`. However,
+  # there are several possible failure scenarios:
+  #
+  # * fetching the data could fail due to a network error,
+  # * the data returned from the server might not be valid JSON, or
+  # * the data is valid but does not have the right shape.
+  #
+  # If any of these scenarios arises, all subsequent `then` and `map` blocks are
+  # skipped until the result is either unwrapped or we manually recover from the
+  # failure by specifying a `rescue` clause:
+  #
+  #   Result.wrap { raise "Boom!" }
+  #     .rescue { |e| e.message.upcase }
+  #     .unwrap(nil) # => "BOOM!"
+  #
+  # In the event of a failure that hasn't been rescued from,
+  # `unwrap` returns the fallback value specified by the caller:
+  #
+  #   Result.wrap { raise "Boom!" }.unwrap(nil) # => nil
+  #   Result.wrap { raise "Boom!" }.unwrap { |e| e.message } # => "Boom!"
+  #
+  module Result
+    class Error < RuntimeError; end
+    class UnexpectedSuccess < Error; end
+    class UnexpectedFailure < Error; end
+
+    ##
+    # Implements a container for wrapping a success value. The main purpose of
+    # the container is to support further transformations of the result and
+    # centralize error handling should any of the subsequent transformations
+    # fail:
+    #
+    #   result = Result
+    #     .new("{}")
+    #     .then { |json| JSON.parse(json) }
+    #     .tap do |result|
+    #       result.success? # => true
+    #       result.value # => {}
+    #     .then { |data| data.fetch(:firstname) }
+    #     .tap do |result|
+    #       result.failure? # => true
+    #       result.error # => KeyError
+    #     end
+    #
+    # `Success` implements two transformation functions: `then` and `map`. The
+    # former makes no assumption regarding the return value of the
+    # transformation. The latter on the other hand expects the transformation to
+    # be successful. If this assumption is violated, program execution is
+    # interrupted and an error is raised. As the purpose of result objects is to
+    # guard against exactly that. This is generally a flaw and requires the code
+    # to either be hardened or to substitute the call to `map` with a call to
+    # `then`. `map` should only be used for transformations that cannot fail and
+    # when the caller wants to state exactly that fact.
+    #
+    class Success
+      attr_reader :value
+
+      ##
+      # initializes a new `Success` from an arbitrary value.
+      def initialize(value)
+        @value = value
+      end
+
+      ##
+      # always returns true to indicate that this result represents a success.
+      #
+      def success?
+        true
+      end
+
+      ##
+      # always returns false to indicate that this result represents a success.
+      #
+      def failure?
+        false
+      end
+
+      ##
+      # raises an `UnexpectedSuccess` as a `Failure` does not carry an error
+      # value.
+      #
+      def error
+        raise UnexpectedSuccess
+      end
+
+      ##
+      # returns a new `Success` wrapping the result of the given block. The
+      # block is called with the current value. If the block raises an exception
+      # or returns a `Failure`, an exception is raised. `map` assumes any
+      # transformation to succeed. Transformations that are expected to fail under
+      # certain conditions should only be transformed using `then`:
+      #
+      #   Success
+      #     .new(nil)
+      #     .map { |n| n + 1 } # => raises NoMethodError
+      #
+      # Therefore, map should only be used here if the previous success value is
+      # guaranteed to be a number or if the block handles nil cases properly:
+      #
+      #   Success
+      #     .new(nil)
+      #     .map { |n| (n || 0) + 1 }
+      #     .value # => 1
+      #
+      def map(&block)
+        self.then(&block).tap do |result|
+          return result if result.success?
+
+          result.unwrap { |error| error }.tap do |error|
+            case error
+            when Exception
+              raise error
+            else
+              raise UnexpectedFailure, error
+            end
+          end
+        end
+      end
+
+      ##
+      # returns a new result by wrapping the return value of the block. The
+      # block is invoked with the current success value. The result can either
+      # be a `Success` or a `Failure`. The former is the default. The latter
+      # occurs when executing the block either
+      #
+      # - raised an exception,
+      # - returned an instance of a subclass of `Exception`, or
+      # - returned a `Failure`.
+      #
+      # The example below illustrates this behavior:
+      #
+      #   result = Success
+      #     .new(1)
+      #     .then { |n| n + 1 }
+      #     .tap do |result|
+      #       result.success? # => true
+      #       result.value # => 2
+      #     end
+      #
+      #   result.then { |n| n / 0 }.error # => ZeroDivisionError
+      #   result.then { RuntimeError.new }.error # => RuntimeError
+      #   result.then { Failure.new("Boom!") }.error # => "Boom!"
+      #
+      def then(&block)
+        Result.wrap(&block).call(@value)
+      end
+
+      ##
+      # is a no-op and simply returns itself. Only a `Failure` can be
+      # transformed using `rescue`.
+      #
+      def rescue
+        self
+      end
+
+      ##
+      # returns the success value and ignores the fallback value that was either
+      # provided as a method argument or by passing a block. However, the caller
+      # is still required to specify a fallback value to ensure that in the
+      # event of a `Failure` program execution can continue in a controlled
+      # manner:
+      #
+      #    Success.new(1).unwrap(0) => 1
+      #
+      def unwrap(*args, &block)
+        raise ArgumentError, "expected either a fallback value or a block" unless args.one? ^ block
+        @value
+      end
+    end
+
+    ##
+    # Implements a container for wrapping an error value. In many cases, the
+    # error value is going to be an exception but other values are fully
+    # supported:
+    #
+    #   Failure
+    #     .new(RuntimeError.new("Something went wrong"))
+    #     .error # => RuntimeError.new
+    #
+    #   Failure
+    #     .new("Something went wrong")
+    #     .error # => "Something went wrong"
+    #
+    # `Failure` does not support transformations with `then` and `map`. When any
+    # of these two methods is invoked on a `Failure`, the `Failure` itself is
+    # returned unless it is rescued from or unwrapped. This enables the caller to
+    # build optimistic transformation chains and defer error handling:
+    #
+    #   Failure
+    #     .new(nil)
+    #     .then { |json| JSON.parse(json) }                      # Ignored
+    #     .then(&:with_indifferent_access)                       # Ignored
+    #     .then { |data| data.values_at(:firstname, :lastname) } # Ignored
+    #     .unwrap(Person.new("John", "Doe"))                     # => Person
+    #
+    # Alternatively, we could resucue from the error and then proceed with the
+    # remanining transformations:
+    #
+    #   Person = Struct.new(:firstname, :lastname)
+    #   Failure
+    #     .new(nil)
+    #     .then { |json| JSON.parse(json) }                      # Ignored
+    #     .then(&:with_indifferent_access)                       # Ignored
+    #     .rescue { {firstname: "John", lastname: "Doe" }}
+    #     .then { |data| data.values_at(:firstname, :lastname) } # Executed
+    #     .then { |members| Person.new(*members) }               # Executed
+    #     .unwrap(nil)                                           # => Person
+    #
+    class Failure
+      attr_reader :error
+
+      ##
+      # initializes a new `Failure` from an arbitrary value. In many cases, this
+      # value is going to be an instance of a subclass of `Exception` but any
+      # type is supported.
+      #
+      def initialize(error)
+        @error = error
+      end
+
+      ##
+      # always returns `false` to indicate that this result represents a failure.
+      #
+      def success?
+        false
+      end
+
+      ##
+      # Always returns `true` to indicate that this result represents a failure.
+      #
+      def failure?
+        true
+      end
+
+      ##
+      # raises an `ShopifyCli::Result::UnexpectedError` as a
+      # `ShopifyCli::Result::Failure` does not carry a success value.
+      #
+      def value
+        raise UnexpectedFailure
+      end
+
+      ##
+      # is a no-op and simply returns itself. This is essential to skip
+      # transformation steps in a chain once an error has occurred.
+      #
+      def map
+        self
+      end
+
+      ##
+      # is a no-op and simply returns itself. This is essential to skip
+      # transformation steps in a chain once an error has occurred.
+      #
+      def then
+        self
+      end
+
+      ##
+      # can be used to recover from a failure or produce a new failure with a
+      # different error.
+      #
+      #   Failure
+      #     .new("Something went wrong")
+      #     .rescue { |msg| [msg, "but we fixed it!"].join(" "") }
+      #     .tap do |result|
+      #        result.success? # => true
+      #        result.value # => "Something went wrong but we fixed it!"
+      #     end
+      #
+      # `rescue` is opinionated when it comes to the return value of the block.
+      # If the return value is an `Exception` – either one that was raised or an
+      # instance of a subclass of `Exception` – a `Failure` is returned. Any
+      # other value results in a `Success` unless the value has been explicitly
+      # wrapped in a `Failure`:
+      #
+      #   Failure
+      #     .new(RuntimeError.new)
+      #     .resuce { "All good! "}
+      #     .success? # => true
+      #
+      #   Failure
+      #     .new(RuntimeError.new)
+      #     .resuce { Failure.new("Still broken!") }
+      #     .success? # => false
+      #
+      def rescue(&block)
+        Result.wrap(&block).call(@error)
+      end
+
+      ##
+      # returns the fallback value specified by the caller. The fallback value
+      # can be provided as a method argument or as a block. If a block is given,
+      # it receives the error as its first and only argument:
+      #
+      #   failure = Failure.new(RuntimeError.new("Something went wrong!"))
+      #
+      #   failure.unwrap(nil) # => nil
+      #   failure.unwrap { |e| e.message } # => "Something went wrong!"
+      #
+      # #### Parameters
+      #
+      # * `*args` should be an `Array` with zero or one element
+      # * `&block`  should be a Proc that takes zero or one argument
+      #
+      # #### Raises
+      #
+      # * `ArgumentError` if both a fallback argument and a block is provided
+      #
+      def unwrap(*args, &block)
+        raise ArgumentError, "expected either a fallback value or a block" unless args.one? ^ block
+        block ? block.call(@error) : args.pop
+      end
+    end
+
+    ##
+    # wraps the given value into a `ShopifyCli::Result::Success` container
+    #
+    # #### Parameters
+    #
+    # * `value` a value of arbitrary type
+    #
+    def self.success(value)
+      Result::Success.new(value)
+    end
+
+    ##
+    # wraps the given value into a `ShopifyCli::Result::Failure` container
+    #
+    # #### Parameters
+    #
+    # * `error` a value of arbitrary type
+    #
+    def self.failure(error)
+      Result::Failure.new(error)
+    end
+
+    ##
+    # takes either a value or a block and chooses the appropriate result
+    # container based on the type of the value or the type of the block's return
+    # value. If the type is an exception, it is wrapped in a
+    # `ShopifyCli::Result::Failure` and otherwise in a
+    # `ShopifyCli::Result::Success`. If a block was provided instead of value, a
+    # `Proc` is returned and the result wrapping doesn't occur until the block
+    # is invoked.
+    #
+    # #### Parameters
+    #
+    # * `*args` should be an `Array` with zero or one element
+    # * `&block` should be a `Proc` that takes zero or one argument
+    #
+    # #### Returns
+    #
+    # Returns either a `Result::Success`, `Result::Failure` or a `Proc` that
+    # produces one of the former when invoked.
+    #
+    # #### Examples
+    #
+    #   Result.wrap(1) # => ShopifyCli::Result::Success
+    #   Result.wrap(RuntimeError.new) # => ShopifyCli::Result::Failure
+    #
+    #   Result.wrap { 1 } # => Proc
+    #   Result.wrap { 1 }.call # => ShopifyCli::Result::Success
+    #   Result.wrap { raise }.call # => ShopifyCli::Result::Failure
+    #
+    #   Result.wrap { |s| s.upcase }.call("hello").tap do |result|
+    #     result # => Result::Success
+    #     result.value # => "HELLO"
+    #   end
+    #
+    def self.wrap(*values, &block)
+      raise ArgumentError, "expected either a value or a block" unless values.one? ^ block
+
+      if values.one?
+        values.pop.yield_self do |value|
+          case value
+          when Result::Success, Result::Failure
+            value
+          when Exception
+            Result.failure(value)
+          else
+            Result.success(value)
+          end
+        end
+      else
+        ->(*args) do
+          begin
+            wrap(block.call(*args))
+          rescue => error
+            wrap(error)
+          end
+        end
+      end
+    end
+
+    ##
+    # Wraps the given block and invokes it with the passed arguments.
+    #
+    def self.call(*args, &block)
+      raise ArgumentError, "expected a block" unless block
+      wrap(&block).call(*args)
+    end
+  end
+end