toys-core 0.10.1 → 0.11.0

data/lib/toys/standard_mixins/bundler.rb

@@ -7,32 +7,55 @@ module Toys
     #
     # The following parameters can be passed when including this mixin:
     #
-    #  *  `:groups` (Array<String>) The groups to include in setup
+    #  *  `:static` (Boolean) If `true`, installs the bundle immediately, when
+    #     defining the tool. If `false` (the default), installs the bundle just
+    #     before the tool runs.
     #
-    #  *  `:search_dirs` (Array<String,Symbol>) Directories to search for a
-    #     Gemfile.
+    #  *  `:groups` (Array\<String\>) The groups to include in setup.
+    #
+    #  *  `:gemfile_path` (String) The path to the Gemfile to use. If `nil` or
+    #     not given, the `:search_dirs` will be searched for a Gemfile.
+    #
+    #  *  `:search_dirs` (String,Symbol,Array\<String,Symbol\>) Directories to
+    #     search for a Gemfile.
     #
     #     You can pass full directory paths, and/or any of the following:
-    #      *  `:context` - the current context directory
-    #      *  `:current` - the current working directory
-    #      *  `:toys` - the Toys directory containing the tool definition
+    #      *  `:context` - the current context directory.
+    #      *  `:current` - the current working directory.
+    #      *  `:toys` - the Toys directory containing the tool definition, and
+    #         any of its parents within the Toys directory hierarchy.
     #
     #     The default is to search `[:toys, :context, :current]` in that order.
+    #     See {DEFAULT_SEARCH_DIRS}.
+    #
+    #     For most directories, the bundler mixin will look for the files
+    #     ".gems.rb", "gems.rb", and "Gemfile", in that order. In `:toys`
+    #     directories, it will look only for ".gems.rb" and "Gemfile", in that
+    #     order. These can be overridden by setting the `:gemfile_names` and/or
+    #     `:toys_gemfile_names` arguments.
+    #
+    #  *  `:gemfile_names` (Array\<String\>) File names that are recognized as
+    #     Gemfiles when searching in directories other than Toys directories.
+    #     Defaults to {Toys::Utils::Gems::DEFAULT_GEMFILE_NAMES}.
+    #
+    #  *  `:toys_gemfile_names` (Array\<String\>) File names that are
+    #     recognized as Gemfiles when wearching in Toys directories.
+    #     Defaults to {DEFAULT_TOYS_GEMFILE_NAMES}.
     #
     #  *  `:on_missing` (Symbol) What to do if a needed gem is not installed.
     #
     #     Supported values:
-    #      *  `:confirm` - prompt the user on whether to install (default)
-    #      *  `:error` - raise an exception
-    #      *  `:install` - just install the gem
+    #      *  `:confirm` - prompt the user on whether to install (default).
+    #      *  `:error` - raise an exception.
+    #      *  `:install` - just install the gem.
     #
     #  *  `:on_conflict` (Symbol) What to do if bundler has already been run
     #     with a different Gemfile.
     #
     #     Supported values:
-    #      *  `:error` - raise an exception (default)
-    #      *  `:ignore` - just silently proceed without bundling again
-    #      *  `:warn` - print a warning and proceed without bundling again
+    #      *  `:error` - raise an exception (default).
+    #      *  `:ignore` - just silently proceed without bundling again.
+    #      *  `:warn` - print a warning and proceed without bundling again.
     #
     #  *  `:terminal` (Toys::Utils::Terminal) Terminal to use (optional)
     #  *  `:input` (IO) Input IO (optional, defaults to STDIN)
@@ -41,48 +64,106 @@ module Toys
     module Bundler
       include Mixin
 
-      on_initialize do
-        |groups: nil,
-         search_dirs: nil,
-         on_missing: nil,
-         on_conflict: nil,
-         terminal: nil,
-         input: nil,
-         output: nil|
+      on_initialize do |static: false, **kwargs|
+        unless static
+          context_directory = self[::Toys::Context::Key::CONTEXT_DIRECTORY]
+          source_info = self[::Toys::Context::Key::TOOL_SOURCE]
+          ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
+        end
+      end
+
+      on_include do |static: false, **kwargs|
+        if static
+          ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
+        end
+      end
+
+      ##
+      # Default search directories for Gemfiles.
+      # @return [Array<String,Symbol>]
+      #
+      DEFAULT_SEARCH_DIRS = [:toys, :context, :current].freeze
+
+      ##
+      # The gemfile names that are searched by default in Toys directories.
+      # @return [Array<String>]
+      #
+      DEFAULT_TOYS_GEMFILE_NAMES = [".gems.rb", "Gemfile"].freeze
+
+      # @private
+      def self.setup_bundle(context_directory,
+                            source_info,
+                            gemfile_path: nil,
+                            search_dirs: nil,
+                            gemfile_names: nil,
+                            toys_gemfile_names: nil,
+                            groups: nil,
+                            on_missing: nil,
+                            on_conflict: nil,
+                            terminal: nil,
+                            input: nil,
+                            output: nil)
         require "toys/utils/gems"
-        search_dirs = ::Toys::StandardMixins::Bundler.resolve_search_dirs(search_dirs, self)
+        gemfile_path ||= begin
+          gemfile_finder = GemfileFinder.new(context_directory, source_info,
+                                             gemfile_names, toys_gemfile_names)
+          gemfile_finder.search(search_dirs || DEFAULT_SEARCH_DIRS)
+        end
         gems = ::Toys::Utils::Gems.new(on_missing: on_missing, on_conflict: on_conflict,
                                        terminal: terminal, input: input, output: output)
-        gems.bundle(groups: groups, search_dirs: search_dirs)
+        gems.bundle(groups: groups, gemfile_path: gemfile_path)
       end
 
-      ## @private
-      def self.resolve_search_dirs(search_dirs, context)
-        search_dirs ||= [:toys, :context, :current]
-        Array(search_dirs).flat_map do |dir|
-          case dir
+      # @private
+      class GemfileFinder
+        # @private
+        def initialize(context_directory, source_info, gemfile_names, toys_gemfile_names)
+          @context_directory = context_directory
+          @source_info = source_info
+          @gemfile_names = gemfile_names
+          @toys_gemfile_names = toys_gemfile_names || DEFAULT_TOYS_GEMFILE_NAMES
+        end
+
+        # @private
+        def search(search_dir)
+          case search_dir
+          when ::Array
+            search_array(search_dir)
+          when ::String
+            ::Toys::Utils::Gems.find_gemfile(search_dir, gemfile_names: @gemfile_names)
           when :context
-            context[::Toys::Context::Key::CONTEXT_DIRECTORY]
+            search(@context_directory)
           when :current
-            ::Dir.getwd
+            search(::Dir.getwd)
           when :toys
-            toys_dir_stack(context[::Toys::Context::Key::TOOL_SOURCE])
-          when ::String
-            dir
+            search_toys
           else
             raise ::ArgumentError, "Unrecognized search_dir: #{dir.inspect}"
           end
         end
-      end
 
-      ## @private
-      def self.toys_dir_stack(source_info)
-        dirs = []
-        while source_info
-          dirs << source_info.source_path if source_info.source_type == :directory
-          source_info = source_info.parent
+        private
+
+        def search_array(search_dirs)
+          search_dirs.each do |search_dir|
+            result = search(search_dir)
+            return result if result
+          end
+          nil
+        end
+
+        def search_toys
+          source_info = @source_info
+          while source_info
+            if source_info.source_type == :directory
+              result = ::Toys::Utils::Gems.find_gemfile(source_info.source_path,
+                                                        gemfile_names: @toys_gemfile_names)
+              return result if result
+            end
+            source_info = source_info.parent
+          end
+          nil
         end
-        dirs
       end
     end
   end

data/lib/toys/standard_mixins/exec.rb

@@ -728,7 +728,7 @@ module Toys
       def self._setup_clean_process(cmd)
         raise ::ArgumentError, "Toys process is unknown" unless ::Toys.executable_path
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
-        cmd = Array(::Toys.executable_path) + cmd
+        cmd = [::RbConfig.ruby, "--disable=gems", ::Toys.executable_path] + cmd
         if defined?(::Bundler)
           if ::Bundler.respond_to?(:with_unbundled_env)
             ::Bundler.with_unbundled_env { yield(cmd) }

data/lib/toys/utils/exec.rb

@@ -547,7 +547,7 @@ module Toys
         ##
         # The process ID.
         #
-        # Exactly one of `exception` and `pid` will be non-nil.
+        # Exactly one of {#exception} and {#pid} will be non-nil.
         #
         # @return [Integer] if the process start was successful
         # @return [nil] if the process could not be started.
@@ -557,7 +557,7 @@ module Toys
         ##
         # The exception raised when the process failed to start.
         #
-        # Exactly one of `exception` and `pid` will be non-nil.
+        # Exactly one of {#exception} and {#pid} will be non-nil.
         #
         # @return [Exception] if the process failed to start.
         # @return [nil] if the process start was successful.
@@ -722,15 +722,20 @@ module Toys
         ##
         # Wait for the subcommand to complete, and return a result object.
         #
+        # Closes the control streams if present. The stdin stream is always
+        # closed, even if the call times out. The stdout and stderr streams are
+        # closed only after the command terminates.
+        #
         # @param timeout [Numeric,nil] The timeout in seconds, or `nil` to
         #     wait indefinitely.
         # @return [Toys::Utils::Exec::Result] The result object
         # @return [nil] if a timeout occurred.
         #
         def result(timeout: nil)
+          close_streams(:in)
           return nil if @wait_thread && !@wait_thread.join(timeout)
           @result ||= begin
-            close_streams
+            close_streams(:out)
             @join_threads.each(&:join)
             Result.new(name, @captures[:out], @captures[:err], @wait_thread&.value, @exception)
                   .tap { |result| @result_callback&.call(result) }
@@ -738,13 +743,13 @@ module Toys
         end
 
         ##
-        # Close all the controller's streams.
+        # Close the controller's streams.
         # @private
         #
-        def close_streams
-          @in.close if @in && !@in.closed?
-          @out.close if @out && !@out.closed?
-          @err.close if @err && !@err.closed?
+        def close_streams(which)
+          @in.close if which != :out && @in && !@in.closed?
+          @out.close if which != :in && @out && !@out.closed?
+          @err.close if which != :in && @err && !@err.closed?
           self
         end
 
@@ -773,7 +778,21 @@ module Toys
       end
 
       ##
-      # The result returned from a subcommand execution.
+      # The result returned from a subcommand execution. This includes the
+      # identifying name of the execution (if any), the result status of the
+      # execution, and any captured stream output.
+      #
+      # Possible result statuses are:
+      #
+      #  *  The process failed to start. {Result#failed?} will return true, and
+      #     {Result#exception} will return an exception describing the failure
+      #     (often an errno).
+      #  *  The process executed and exited with a normal exit code. Either
+      #     {Result#success?} or {Result#error?} will return true, and
+      #     {Result.exit_code} will return the numeric exit code.
+      #  *  The process executed but was terminated by an uncaught signal.
+      #     {Result#signaled?} will return true, and {Result#term_signal} will
+      #     return the numeric signal code.
       #
       class Result
         ## @private
@@ -809,11 +828,13 @@ module Toys
         attr_reader :captured_err
 
         ##
-        # The status code object.
+        # The Ruby process status object, providing various information about
+        # the ending state of the process.
         #
-        # Exactly one of `exception` and `status` will be non-nil.
+        # Exactly one of {#exception} and {#status} will be non-nil.
         #
-        # @return [Process::Status] The status code.
+        # @return [Process::Status] The status, if the process was successfully
+        #     spanwed and terminated.
         # @return [nil] if the process could not be started.
         #
         attr_reader :status
@@ -821,7 +842,7 @@ module Toys
         ##
         # The exception raised if a process couldn't be started.
         #
-        # Exactly one of `exception` and `status` will be non-nil.
+        # Exactly one of {#exception} and {#status} will be non-nil.
         #
         # @return [Exception] The exception raised from process start.
         # @return [nil] if the process started successfully.
@@ -829,33 +850,76 @@ module Toys
         attr_reader :exception
 
         ##
-        # The numeric status code.
+        # The numeric status code for a process that exited normally,
         #
-        # This will be a nonzero integer if the process failed to start. That
-        # is, `exit_code` will never be `nil`, even if `status` is `nil`.
+        # Exactly one of {#exception}, {#exit_code}, and {#term_signal} will be
+        # non-nil.
         #
-        # @return [Integer]
+        # @return [Integer] the numeric status code, if the process started
+        #     successfully and exited normally.
+        # @return [nil] if the process did not start successfully, or was
+        #     terminated by an uncaught signal.
         #
         def exit_code
-          status ? status.exitstatus : 127
+          status&.exitstatus
+        end
+
+        ##
+        # The numeric signal code that caused process termination.
+        #
+        # Exactly one of {#exception}, {#exit_code}, and {#term_signal} will be
+        # non-nil.
+        #
+        # @return [Integer] The signal that caused the process to terminate.
+        # @return [nil] if the process did not start successfully, or executed
+        #     and exited with a normal exit code.
+        #
+        def term_signal
+          status&.termsig
+        end
+
+        ##
+        # Returns true if the subprocess failed to start, or false if the
+        # process was able to execute.
+        #
+        # @return [Boolean]
+        #
+        def failed?
+          status.nil?
+        end
+
+        ##
+        # Returns true if the subprocess terminated due to an unhandled signal,
+        # or false if the process failed to start or exited normally.
+        #
+        # @return [Boolean]
+        #
+        def signaled?
+          !term_signal.nil?
         end
 
         ##
-        # Returns true if the subprocess terminated with a zero status.
+        # Returns true if the subprocess terminated with a zero status, or
+        # false if the process failed to start, terminated due to a signal, or
+        # returned a nonzero status.
         #
         # @return [Boolean]
         #
         def success?
-          exit_code.zero?
+          code = exit_code
+          !code.nil? && code.zero?
         end
 
         ##
-        # Returns true if the subprocess terminated with a nonzero status.
+        # Returns true if the subprocess terminated with a nonzero status, or
+        # false if the process failed to start, terminated due to a signal, or
+        # returned a zero status.
         #
         # @return [Boolean]
         #
         def error?
-          !exit_code.zero?
+          code = exit_code
+          !code.nil? && !code.zero?
         end
       end
 
@@ -887,10 +951,10 @@ module Toys
           return controller if @config_opts[:background]
           begin
             @block&.call(controller)
+            controller.result
           ensure
-            controller.close_streams
+            controller.close_streams(:both)
           end
-          controller.result
         end
 
         private

data/lib/toys/utils/gems.rb

@@ -64,6 +64,19 @@ module Toys
       class AlreadyBundledError < BundlerFailedError
       end
 
+      ##
+      # The bundle contained a toys or toys-core dependency that is
+      # incompatible with the currently running version.
+      #
+      class IncompatibleToysError < BundlerFailedError
+      end
+
+      ##
+      # The gemfile names that are searched by default.
+      # @return [Array<String>]
+      #
+      DEFAULT_GEMFILE_NAMES = [".gems.rb", "gems.rb", "Gemfile"].freeze
+
       ##
       # Activate the given gem. If it is not present, attempt to install it (or
       # inform the user to update the bundle).
@@ -81,16 +94,22 @@ module Toys
       #
       # @param on_missing [:confirm,:error,:install] What to do if a needed gem
       #     is not installed. Possible values:
+      #
       #      *  `:confirm` - prompt the user on whether to install
       #      *  `:error` - raise an exception
       #      *  `:install` - just install the gem
+      #
       #     The default is `:confirm`.
+      #
       # @param on_conflict [:error,:warn,:ignore] What to do if bundler has
       #     already been run with a different Gemfile. Possible values:
+      #
       #      *  `:error` - raise an exception
       #      *  `:ignore` - just silently proceed without bundling again
       #      *  `:warn` - print a warning and proceed without bundling again
+      #
       #     The default is `:error`.
+      #
       # @param terminal [Toys::Utils::Terminal] Terminal to use (optional)
       # @param input [IO] Input IO (optional, defaults to STDIN)
       # @param output [IO] Output IO (optional, defaults to STDOUT)
@@ -136,26 +155,54 @@ module Toys
       end
 
       ##
-      # Set up the bundle.
+      # Search for an appropriate Gemfile, and set up the bundle.
+      #
+      # @param groups [Array<String>] The groups to include in setup.
+      #
+      # @param gemfile_path [String] The path to the Gemfile to use. If `nil`
+      #     or not given, the `:search_dirs` will be searched for a Gemfile.
+      #
+      # @param search_dirs [String,Array<String>] Directories in which to
+      #     search for a Gemfile, if gemfile_path is not given. You can provide
+      #     a single directory or an array of directories.
+      #
+      # @param gemfile_names [String,Array<String>] File names that are
+      #     recognized as Gemfiles, when searching because gemfile_path is not
+      #     given. Defaults to {DEFAULT_GEMFILE_NAMES}.
       #
-      # @param groups [Array<String>] The groups to include in setup
-      # @param search_dirs [Array<String>] Directories to search for a Gemfile
       # @return [void]
       #
       def bundle(groups: nil,
-                 search_dirs: nil)
+                 gemfile_path: nil,
+                 search_dirs: nil,
+                 gemfile_names: nil)
+        Array(search_dirs).each do |dir|
+          break if gemfile_path
+          gemfile_path = Gems.find_gemfile(dir, gemfile_names: gemfile_names)
+        end
+        raise GemfileNotFoundError, "Gemfile not found" unless gemfile_path
         Gems.synchronize do
-          gemfile_path = find_gemfile(Array(search_dirs))
-          activate("bundler", "~> 2.1")
           if configure_gemfile(gemfile_path)
+            activate("bundler", "~> 2.1")
+            require "bundler"
             setup_bundle(gemfile_path, groups || [])
           end
         end
       end
 
+      # @private
+      def self.find_gemfile(search_dir, gemfile_names: nil)
+        gemfile_names ||= DEFAULT_GEMFILE_NAMES
+        Array(gemfile_names).each do |file|
+          gemfile_path = ::File.join(search_dir, file)
+          return gemfile_path if ::File.readable?(gemfile_path)
+        end
+        nil
+      end
+
       @global_mutex = ::Monitor.new
 
-      ## @private
+      # @private
       def self.synchronize(&block)
         @global_mutex.synchronize(&block)
       end
@@ -184,14 +231,14 @@ module Toys
             error.message.include?("Could not find")
           end
         if !is_missing_spec || @on_missing == :error
-          report_error(name, requirements, error)
+          report_activation_error(name, requirements, error)
           return
         end
         confirm_and_install_gem(name, requirements)
         begin
           gem(name, *requirements)
         rescue ::Gem::LoadError => e
-          report_error(name, requirements, e)
+          report_activation_error(name, requirements, e)
         end
       end
 
@@ -215,7 +262,7 @@ module Toys
         ::Gem::Specification.reset
       end
 
-      def report_error(name, requirements, err)
+      def report_activation_error(name, requirements, err)
         if ::ENV["BUNDLE_GEMFILE"]
           raise GemfileUpdateNeededError.new(gem_requirements_text(name, requirements),
                                              ::ENV["BUNDLE_GEMFILE"])
@@ -223,22 +270,16 @@ module Toys
         raise ActivationFailedError, err.message
       end
 
-      def find_gemfile(search_dirs)
-        search_dirs.each do |dir|
-          gemfile_path = ::File.join(dir, "Gemfile")
-          return gemfile_path if ::File.readable?(gemfile_path)
-        end
-        raise GemfileNotFoundError, "Gemfile not found"
-      end
-
       def configure_gemfile(gemfile_path)
         old_path = ::ENV["BUNDLE_GEMFILE"]
-        if old_path && gemfile_path != old_path
-          case @on_conflict
-          when :warn
-            terminal.puts("Warning: could not set up bundler because it is already set up.", :red)
-          when :error
-            raise AlreadyBundledError, "Could not set up bundler because it is already set up"
+        if old_path
+          if gemfile_path != old_path
+            case @on_conflict
+            when :warn
+              terminal.puts("Warning: could not set up bundler because it is already set up.", :red)
+            when :error
+              raise AlreadyBundledError, "Could not set up bundler because it is already set up"
+            end
           end
           return false
         end
@@ -247,13 +288,60 @@ module Toys
       end
 
       def setup_bundle(gemfile_path, groups)
-        require "bundler"
         begin
-          ::Bundler.setup(*groups)
-        rescue ::Bundler::GemNotFound
+          modify_bundle_definition(gemfile_path)
+          ::Bundler.ui.silence { ::Bundler.setup(*groups) }
+        rescue ::Bundler::GemNotFound, ::Bundler::VersionConflict
+          restore_toys_libs
           install_bundle(gemfile_path)
           ::Bundler.reset!
-          ::Bundler.setup(*groups)
+          modify_bundle_definition(gemfile_path)
+          ::Bundler.ui.silence { ::Bundler.setup(*groups) }
+        end
+        restore_toys_libs
+      end
+
+      def modify_bundle_definition(gemfile_path)
+        builder = ::Bundler::Dsl.new
+        builder.eval_gemfile(gemfile_path)
+        toys_gems = ["toys-core"]
+        remove_gem_from_definition(builder, "toys-core")
+        removed_toys = remove_gem_from_definition(builder, "toys")
+        add_gem_to_definition(builder, "toys-core")
+        if removed_toys || ::Toys.const_defined?(:VERSION)
+          add_gem_to_definition(builder, "toys")
+          toys_gems << "toys"
+        end
+        definition = builder.to_definition(gemfile_path + ".lock", { gems: toys_gems })
+        ::Bundler.instance_variable_set(:@definition, definition)
+      end
+
+      def remove_gem_from_definition(builder, name)
+        existing_dep = builder.dependencies.find { |dep| dep.name == name }
+        return false unless existing_dep
+        unless existing_dep.requirement.satisfied_by?(::Gem::Version.new(::Toys::Core::VERSION))
+          raise IncompatibleToysError,
+                "The bundle lists #{name} #{existing_dep.requirement} as a dependency, which is" \
+                " incompatible with the current version #{::Toys::Core::VERSION}."
+        end
+        builder.dependencies.delete(existing_dep)
+        true
+      end
+
+      def add_gem_to_definition(builder, name)
+        if ::ENV["TOYS_DEV"] == "true"
+          path = ::File.join(::File.dirname(::File.dirname(::Toys::CORE_LIB_PATH)), name)
+        end
+        command = "gem #{name.inspect}, #{::Toys::Core::VERSION.inspect}, path: #{path.inspect}\n"
+        builder.eval_gemfile("current #{name}", command)
+      end
+
+      def restore_toys_libs
+        $LOAD_PATH.delete(::Toys::CORE_LIB_PATH)
+        $LOAD_PATH.unshift(::Toys::CORE_LIB_PATH)
+        if ::Toys.const_defined?(:LIB_PATH)
+          $LOAD_PATH.delete(::Toys::LIB_PATH)
+          $LOAD_PATH.unshift(::Toys::LIB_PATH)
         end
       end
 
@@ -264,7 +352,8 @@ module Toys
         when :error
           false
         else
-          terminal.confirm("Your bundle is not complete. Install? ", default: @default_confirm)
+          terminal.confirm("Your bundle requires additional gems. Install? ",
+                           default: @default_confirm)
         end
       end
 
@@ -276,7 +365,12 @@ module Toys
                   " `cd #{gemfile_dir} && bundle install`"
         end
         require "bundler/cli"
-        ::Bundler::CLI.start(["install"])
+        begin
+          ::Bundler::CLI.start(["install"])
+        rescue ::Bundler::GemNotFound, ::Bundler::InstallError
+          terminal.puts("Failed to install. Trying update...")
+          ::Bundler::CLI.start(["update"])
+        end
       end
     end
   end