capistrano 3.4.0 → 3.17.1

data/lib/capistrano/doctor/environment_doctor.rb

@@ -0,0 +1,19 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    class EnvironmentDoctor
+      include Capistrano::Doctor::OutputHelpers
+
+      def call
+        title("Environment")
+        puts <<-OUT.gsub(/^\s+/, "")
+          Ruby     #{RUBY_DESCRIPTION}
+          Rubygems #{Gem::VERSION}
+          Bundler  #{defined?(Bundler::VERSION) ? Bundler::VERSION : 'N/A'}
+          Command  #{$PROGRAM_NAME} #{ARGV.join(' ')}
+        OUT
+      end
+    end
+  end
+end

data/lib/capistrano/doctor/gems_doctor.rb

@@ -0,0 +1,45 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    # Prints table of all Capistrano-related gems and their version numbers. If
+    # there is a newer version of a gem available, call attention to it.
+    class GemsDoctor
+      include Capistrano::Doctor::OutputHelpers
+
+      def call
+        title("Gems")
+        table(all_gem_names) do |gem, row|
+          row.yellow if update_available?(gem)
+          row << gem
+          row << installed_gem_version(gem)
+          row << "(update available)" if update_available?(gem)
+        end
+      end
+
+      private
+
+      def installed_gem_version(gem_name)
+        Gem.loaded_specs[gem_name].version
+      end
+
+      def update_available?(gem_name)
+        latest = Gem.latest_version_for(gem_name)
+        return false if latest.nil?
+        latest > installed_gem_version(gem_name)
+      end
+
+      def all_gem_names
+        core_gem_names + plugin_gem_names
+      end
+
+      def core_gem_names
+        %w(capistrano airbrussh rake sshkit net-ssh) & Gem.loaded_specs.keys
+      end
+
+      def plugin_gem_names
+        (Gem.loaded_specs.keys - ["capistrano"]).grep(/capistrano/).sort
+      end
+    end
+  end
+end

data/lib/capistrano/doctor/output_helpers.rb

@@ -0,0 +1,79 @@
+module Capistrano
+  module Doctor
+    # Helper methods for pretty-printing doctor output to stdout. All output
+    # (other than `title`) is indented by four spaces to facilitate copying and
+    # pasting this output into e.g. GitHub or Stack Overflow to achieve code
+    # formatting.
+    module OutputHelpers
+      class Row
+        attr_reader :color
+        attr_reader :values
+
+        def initialize
+          @values = []
+        end
+
+        def <<(value)
+          values << value
+        end
+
+        def yellow
+          @color = :yellow
+        end
+      end
+
+      # Prints a table for a given array of records. For each record, the block
+      # is yielded two arguments: the record and a Row object. To print values
+      # for that record, add values using `row << "some value"`. A row can
+      # optionally be highlighted in yellow using `row.yellow`.
+      def table(records, &block)
+        return if records.empty?
+        rows = collect_rows(records, &block)
+        col_widths = calculate_column_widths(rows)
+
+        rows.each do |row|
+          line = row.values.each_with_index.map do |value, col|
+            value.to_s.ljust(col_widths[col])
+          end.join(" ").rstrip
+          line = color.colorize(line, row.color) if row.color
+          puts line
+        end
+      end
+
+      # Prints a title in blue with surrounding newlines.
+      def title(text)
+        # Use $stdout directly to bypass the indentation that our `puts` does.
+        $stdout.puts(color.colorize("\n#{text}\n", :blue))
+      end
+
+      # Prints text in yellow.
+      def warning(text)
+        puts color.colorize(text, :yellow)
+      end
+
+      # Override `Kernel#puts` to prepend four spaces to each line.
+      def puts(string=nil)
+        $stdout.puts(string.to_s.gsub(/^/, "    "))
+      end
+
+      private
+
+      def collect_rows(records)
+        records.map do |rec|
+          Row.new.tap { |row| yield(rec, row) }
+        end
+      end
+
+      def calculate_column_widths(rows)
+        num_columns = rows.map { |row| row.values.length }.max
+        Array.new(num_columns) do |col|
+          rows.map { |row| row.values[col].to_s.length }.max
+        end
+      end
+
+      def color
+        @color ||= SSHKit::Color.new($stdout)
+      end
+    end
+  end
+end

data/lib/capistrano/doctor/servers_doctor.rb

@@ -0,0 +1,105 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    class ServersDoctor
+      include Capistrano::Doctor::OutputHelpers
+
+      def initialize(env=Capistrano::Configuration.env)
+        @servers = env.servers.to_a
+      end
+
+      def call
+        title("Servers (#{servers.size})")
+        rwc = RoleWhitespaceChecker.new(servers)
+
+        table(servers) do |server, row|
+          sd = ServerDecorator.new(server)
+
+          row << sd.uri_form
+          row << sd.roles
+          row << sd.properties
+          row.yellow if rwc.any_has_whitespace?(server.roles)
+        end
+
+        if rwc.whitespace_roles.any?
+          warning "\nWhitespace detected in role(s) #{rwc.whitespace_roles_decorated}. " \
+            "This might be a result of a mistyped \"%w()\" array literal."
+        end
+        puts
+      end
+
+      private
+
+      attr_reader :servers
+
+      class RoleWhitespaceChecker
+        attr_reader :whitespace_roles, :servers
+
+        def initialize(servers)
+          @servers = servers
+          @whitespace_roles = find_whitespace_roles
+        end
+
+        def any_has_whitespace?(roles)
+          roles.any? { |role| include_whitespace?(role) }
+        end
+
+        def include_whitespace?(role)
+          role =~ /\s/
+        end
+
+        def whitespace_roles_decorated
+          whitespace_roles.map(&:inspect).join(", ")
+        end
+
+        private
+
+        def find_whitespace_roles
+          servers.map(&:roles).flat_map(&:to_a).uniq
+                 .select { |role| include_whitespace?(role) }
+        end
+      end
+
+      class ServerDecorator
+        def initialize(server)
+          @server = server
+        end
+
+        def uri_form
+          [
+            server.user,
+            server.user && "@",
+            server.hostname,
+            server.port && ":",
+            server.port
+          ].compact.join
+        end
+
+        def roles
+          server.roles.to_a.inspect
+        end
+
+        def properties
+          return "" unless server.properties.keys.any?
+          pretty_inspect(server.properties.to_h)
+        end
+
+        private
+
+        attr_reader :server
+
+        # Hashes with proper padding
+        def pretty_inspect(element)
+          return element.inspect unless element.is_a?(Hash)
+
+          pairs_string = element.keys.map do |key|
+            [pretty_inspect(key), pretty_inspect(element.fetch(key))].join(" => ")
+          end.join(", ")
+
+          "{ #{pairs_string} }"
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/doctor/variables_doctor.rb

@@ -0,0 +1,74 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    # Prints a table of all Capistrano variables and their current values. If
+    # there are unrecognized variables, print warnings for them.
+    class VariablesDoctor
+      # These are keys that are recognized by Capistrano, but do not have values
+      # set by default.
+      WHITELIST = %i(
+        application
+        current_directory
+        linked_dirs
+        linked_files
+        releases_directory
+        repo_url
+        repo_tree
+        shared_directory
+      ).freeze
+      private_constant :WHITELIST
+
+      include Capistrano::Doctor::OutputHelpers
+
+      def initialize(env=Capistrano::Configuration.env)
+        @env = env
+      end
+
+      def call
+        title("Variables")
+        values = inspect_all_values
+
+        table(variables.keys.sort_by(&:to_s)) do |key, row|
+          row.yellow if suspicious_keys.include?(key)
+          row << key.inspect
+          row << values[key]
+        end
+
+        puts if suspicious_keys.any?
+
+        suspicious_keys.sort_by(&:to_s).each do |key|
+          warning("#{key.inspect} is not a recognized Capistrano setting "\
+                  "(#{location(key)})")
+        end
+      end
+
+      private
+
+      attr_reader :env
+
+      def variables
+        env.variables
+      end
+
+      def inspect_all_values
+        variables.keys.each_with_object({}) do |key, inspected|
+          inspected[key] = if env.is_question?(key)
+                             "<ask>"
+                           else
+                             variables.peek(key).inspect
+                           end
+        end
+      end
+
+      def suspicious_keys
+        (variables.untrusted_keys & variables.unused_keys) - WHITELIST
+      end
+
+      def location(key)
+        loc = variables.source_locations(key).first
+        loc && loc.sub(/^#{Regexp.quote(Dir.pwd)}/, "").sub(/:in.*/, "")
+      end
+    end
+  end
+end

data/lib/capistrano/doctor.rb

@@ -0,0 +1,6 @@
+require "capistrano/doctor/environment_doctor"
+require "capistrano/doctor/gems_doctor"
+require "capistrano/doctor/variables_doctor"
+require "capistrano/doctor/servers_doctor"
+
+load File.expand_path("../tasks/doctor.rake", __FILE__)

data/lib/capistrano/dotfile.rb

@@ -1,3 +1,2 @@
-dotfile = Pathname.new(File.join(Dir.home, '.capfile'))
+dotfile = Pathname.new(File.join(Dir.home, ".capfile"))
 load dotfile if dotfile.file?
-

data/lib/capistrano/dsl/env.rb

@@ -1,47 +1,14 @@
+require "forwardable"
+
 module Capistrano
   module DSL
     module Env
-
-      def configure_backend
-        env.configure_backend
-      end
-
-      def fetch(key, default=nil, &block)
-        env.fetch(key, default, &block)
-      end
-
-      def any?(key)
-        value = fetch(key)
-        if value && value.respond_to?(:any?)
-          value.any?
-        else
-          !fetch(key).nil?
-        end
-      end
-
-      def set(key, value)
-        env.set(key, value)
-      end
-
-      def set_if_empty(key, value)
-        env.set_if_empty(key, value)
-      end
-
-      def delete(key)
-        env.delete(key)
-      end
-
-      def ask(key, value, options={})
-        env.ask(key, value, options)
-      end
-
-      def role(name, servers, options={})
-        env.role(name, servers, options)
-      end
-
-      def server(name, properties={})
-        env.server(name, properties)
-      end
+      extend Forwardable
+      def_delegators :env,
+                     :configure_backend, :fetch, :set, :set_if_empty, :delete,
+                     :ask, :role, :server, :primary, :validate, :append,
+                     :remove, :dry_run?, :install_plugin, :any?, :is_question?,
+                     :configure_scm, :scm_plugin_installed?
 
       def roles(*names)
         env.roles_for(names.flatten)
@@ -53,17 +20,13 @@ module Capistrano
 
       def release_roles(*names)
         if names.last.is_a? Hash
-          names.last.merge!({ :exclude => :no_release })
+          names.last[:exclude] = :no_release
         else
           names << { exclude: :no_release }
         end
         roles(*names)
       end
 
-      def primary(role)
-        env.primary(role)
-      end
-
       def env
         Configuration.env
       end
@@ -75,7 +38,6 @@ module Capistrano
       def asset_timestamp
         env.timestamp.strftime("%Y%m%d%H%M.%S")
       end
-
     end
   end
 end

data/lib/capistrano/dsl/paths.rb

@@ -1,8 +1,7 @@
-require 'pathname'
+require "pathname"
 module Capistrano
   module DSL
     module Paths
-
       def deploy_to
         fetch(:deploy_to)
       end
@@ -12,15 +11,15 @@ module Capistrano
       end
 
       def current_path
-        deploy_path.join('current')
+        deploy_path.join(fetch(:current_directory, "current"))
       end
 
       def releases_path
-        deploy_path.join('releases')
+        deploy_path.join(fetch(:releases_directory, "releases"))
       end
 
       def release_path
-        fetch(:release_path, current_path)
+        fetch(:release_path) { current_path }
       end
 
       def set_release_path(timestamp=now)
@@ -29,40 +28,27 @@ module Capistrano
       end
 
       def stage_config_path
-        Pathname.new fetch(:stage_config_path, 'config/deploy')
+        Pathname.new fetch(:stage_config_path, "config/deploy")
       end
 
       def deploy_config_path
-        Pathname.new fetch(:deploy_config_path, 'config/deploy.rb')
+        Pathname.new fetch(:deploy_config_path, "config/deploy.rb")
       end
 
       def repo_url
-        require 'cgi'
-        require 'uri'
-        if fetch(:git_http_username) and fetch(:git_http_password)
-          URI.parse(fetch(:repo_url)).tap do |repo_uri|
-            repo_uri.user     = fetch(:git_http_username)
-            repo_uri.password = CGI.escape(fetch(:git_http_password))
-          end.to_s
-        elsif fetch(:git_http_username)
-          URI.parse(fetch(:repo_url)).tap do |repo_uri|
-            repo_uri.user = fetch(:git_http_username)
-          end.to_s
-        else
-          fetch(:repo_url)
-        end
+        fetch(:repo_url)
       end
 
       def repo_path
-        Pathname.new(fetch(:repo_path, ->(){deploy_path.join('repo')}))
+        Pathname.new(fetch(:repo_path, ->() { deploy_path.join("repo") }))
       end
 
       def shared_path
-        deploy_path.join('shared')
+        deploy_path.join(fetch(:shared_directory, "shared"))
       end
 
       def revision_log
-        deploy_path.join('revisions.log')
+        deploy_path.join("revisions.log")
       end
 
       def now
@@ -96,7 +82,7 @@ module Capistrano
       end
 
       def map_dirnames(paths)
-        paths.map { |path| path.dirname }
+        paths.map(&:dirname).uniq
       end
     end
   end

data/lib/capistrano/dsl/stages.rb

@@ -1,19 +1,31 @@
 module Capistrano
   module DSL
     module Stages
+      RESERVED_NAMES = %w(deploy doctor install).freeze
+      private_constant :RESERVED_NAMES
 
       def stages
-        Dir[stage_definitions].map { |f| File.basename(f, '.rb') }
+        names = Dir[stage_definitions].map { |f| File.basename(f, ".rb") }
+        assert_valid_stage_names(names)
+        names
       end
 
       def stage_definitions
-        stage_config_path.join('*.rb')
+        stage_config_path.join("*.rb")
       end
 
       def stage_set?
         !!fetch(:stage, false)
       end
 
+      private
+
+      def assert_valid_stage_names(names)
+        invalid = names.find { |n| RESERVED_NAMES.include?(n) }
+        return if invalid.nil?
+
+        raise t("error.invalid_stage_name", name: invalid, path: stage_config_path.join("#{invalid}.rb"))
+      end
     end
   end
 end

data/lib/capistrano/dsl/task_enhancements.rb

@@ -1,4 +1,4 @@
-require 'capistrano/upload_task'
+require "capistrano/upload_task"
 
 module Capistrano
   module TaskEnhancements
@@ -9,17 +9,14 @@ module Capistrano
 
     def after(task, post_task, *args, &block)
       Rake::Task.define_task(post_task, *args, &block) if block_given?
-      post_task = Rake::Task[post_task]
-      Rake::Task[task].enhance do
-        post_task.invoke
+      task = Rake::Task[task]
+      task.enhance do
+        post = Rake.application.lookup(post_task, task.scope)
+        raise ArgumentError, "Task #{post_task.inspect} not found" unless post
+        post.invoke
       end
     end
 
-    def remote_file(task)
-      target_roles = task.delete(:roles) { :all }
-      define_remote_file_task(task, target_roles)
-    end
-
     def define_remote_file_task(task, target_roles)
       Capistrano::UploadTask.define_task(task) do |t|
         prerequisite_file = t.prerequisites.first
@@ -31,7 +28,6 @@ module Capistrano
             upload! File.open(prerequisite_file), file
           end
         end
-
       end
     end
 
@@ -54,13 +50,12 @@ module Capistrano
 
     def exit_deploy_because_of_exception(ex)
       warn t(:deploy_failed, ex: ex.message)
-      invoke 'deploy:failed'
+      invoke "deploy:failed"
       exit(false)
     end
 
     def deploying?
       fetch(:deploying, false)
     end
-
   end
 end

data/lib/capistrano/dsl.rb

@@ -1,9 +1,8 @@
-require 'etc'
-require 'capistrano/dsl/task_enhancements'
-require 'capistrano/dsl/paths'
-require 'capistrano/dsl/stages'
-require 'capistrano/dsl/env'
-require 'capistrano/configuration/filter'
+require "capistrano/dsl/task_enhancements"
+require "capistrano/dsl/paths"
+require "capistrano/dsl/stages"
+require "capistrano/dsl/env"
+require "capistrano/configuration/filter"
 
 module Capistrano
   module DSL
@@ -12,12 +11,29 @@ module Capistrano
     include Paths
     include Stages
 
-    def invoke(task, *args)
-      Rake::Task[task].invoke(*args)
+    def invoke(task_name, *args)
+      task = Rake::Task[task_name]
+      # NOTE: We access instance variable since the accessor was only added recently. Once Capistrano depends on rake 11+, we can revert the following line
+      if task && task.instance_variable_get(:@already_invoked)
+        file, line, = caller.first.split(":")
+        colors = SSHKit::Color.new($stderr)
+        $stderr.puts colors.colorize("Skipping task `#{task_name}'.", :yellow)
+        $stderr.puts "Capistrano tasks may only be invoked once. Since task `#{task}' was previously invoked, invoke(\"#{task_name}\") at #{file}:#{line} will be skipped."
+        $stderr.puts "If you really meant to run this task again, use invoke!(\"#{task_name}\")"
+        $stderr.puts colors.colorize("THIS BEHAVIOR MAY CHANGE IN A FUTURE VERSION OF CAPISTRANO. Please join the conversation here if this affects you.", :red)
+        $stderr.puts colors.colorize("https://github.com/capistrano/capistrano/issues/1686", :red)
+      end
+      task.invoke(*args)
+    end
+
+    def invoke!(task_name, *args)
+      task = Rake::Task[task_name]
+      task.reenable
+      task.invoke(*args)
     end
 
     def t(key, options={})
-      I18n.t(key, options.merge(scope: :capistrano))
+      I18n.t(key, **options.merge(scope: :capistrano))
     end
 
     def scm
@@ -30,12 +46,11 @@ module Capistrano
 
     def revision_log_message
       fetch(:revision_log_message,
-        t(:revision_log_message,
-          branch: fetch(:branch),
-          user: local_user,
-          sha: fetch(:current_revision),
-          release: fetch(:release_timestamp))
-       )
+            t(:revision_log_message,
+              branch: fetch(:branch),
+              user: local_user,
+              sha: fetch(:current_revision),
+              release: fetch(:release_timestamp)))
     end
 
     def rollback_log_message
@@ -50,15 +65,31 @@ module Capistrano
       VersionValidator.new(locked_version).verify
     end
 
+    # rubocop:disable Security/MarshalLoad
     def on(hosts, options={}, &block)
       subset_copy = Marshal.dump(Configuration.env.filter(hosts))
       SSHKit::Coordinator.new(Marshal.load(subset_copy)).each(options, &block)
     end
+    # rubocop:enable Security/MarshalLoad
 
     def run_locally(&block)
       SSHKit::Backend::Local.new(&block).run
     end
 
+    # Catch common beginner mistake and give a helpful error message on stderr
+    def execute(*)
+      file, line, = caller.first.split(":")
+      colors = SSHKit::Color.new($stderr)
+      $stderr.puts colors.colorize("Warning: `execute' should be wrapped in an `on' scope in #{file}:#{line}.", :red)
+      $stderr.puts
+      $stderr.puts "  task :example do"
+      $stderr.puts colors.colorize("    on roles(:app) do", :yellow)
+      $stderr.puts "      execute 'whoami'"
+      $stderr.puts colors.colorize("    end", :yellow)
+      $stderr.puts "  end"
+      $stderr.puts
+      raise NoMethodError, "undefined method `execute' for main:Object"
+    end
   end
 end
-self.extend Capistrano::DSL
+extend Capistrano::DSL

data/lib/capistrano/framework.rb

@@ -1,2 +1,2 @@
 load File.expand_path("../tasks/framework.rake", __FILE__)
-require 'capistrano/install'
+require "capistrano/install"