minestrone 0.0.1

data/lib/minestrone/cli/help.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Minestrone
+  class CLI
+    module Help
+      LINE_PADDING = 7
+      MIN_MAX_LEN  = 30
+      HEADER_LEN   = 60
+
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :execute_requested_actions_without_help, :execute_requested_actions
+        base.send :alias_method, :execute_requested_actions, :execute_requested_actions_with_help
+      end
+
+      def execute_requested_actions_with_help(config)
+        if options[:tasks]
+          task_list(config, options[:tasks])
+        elsif options[:explain]
+          explain_task(config, options[:explain])
+        else
+          execute_requested_actions_without_help(config)
+        end
+      end
+
+      def task_list(config, pattern = true) #:nodoc:
+        tool_output = options[:tool]
+
+        if pattern.is_a?(String)
+          tasks = config.task_list(:all).select {|t| t.fully_qualified_name =~ /#{pattern}/}
+        end
+        if tasks.nil? || tasks.length == 0
+          warn "Pattern '#{pattern}' not found. Listing all tasks.\n\n" if !tool_output && !pattern.is_a?(TrueClass)
+          tasks = config.task_list(:all)
+        end
+
+        if tasks.empty?
+          warn "There are no tasks available. Please specify a recipe file to load." unless tool_output
+        else
+          all_tasks_length = tasks.length
+          if options[:verbose].to_i < 1
+            tasks = tasks.reject { |t| t.description.empty? || t.description =~ /^\[internal\]/ }
+          end
+
+          tasks = tasks.sort_by { |task| task.fully_qualified_name }
+
+          longest = tasks.map { |task| task.fully_qualified_name.length }.max
+          max_length = output_columns - longest - LINE_PADDING
+          max_length = MIN_MAX_LEN if max_length < MIN_MAX_LEN
+
+          tasks.each do |task|
+            if tool_output
+              puts "min #{task.fully_qualified_name}"
+            else
+              puts "min %-#{longest}s # %s" % [task.fully_qualified_name, task.brief_description(max_length)]
+            end
+          end
+
+          unless tool_output
+            if all_tasks_length > tasks.length
+              puts
+              puts "Some tasks were not listed, either because they have no description,"
+              puts "or because they are only used internally by other tasks. To see all"
+              puts "tasks, type `#{File.basename($0)} -vT'."
+            end
+
+            puts
+            puts "Extended help may be available for these tasks."
+            puts "Type `#{File.basename($0)} -e taskname' to view it."
+          end
+        end
+      end
+
+      def explain_task(config, name) #:nodoc:
+        task = config.find_task(name)
+        if task.nil?
+          warn "The task `#{name}' does not exist."
+        else
+          puts "-" * HEADER_LEN
+          puts "min #{name}"
+          puts "-" * HEADER_LEN
+
+          if task.description.empty?
+            puts "There is no description for this task."
+          else
+            puts format_text(task.description)
+          end
+
+          puts
+        end
+      end
+
+      def long_help #:nodoc:
+        help_text = File.read(File.join(__dir__, "help.txt"))
+        self.class.ui.page_at = self.class.ui.output_rows - 2
+        self.class.ui.say format_text(help_text)
+      end
+
+      def format_text(text) #:nodoc:
+        formatted = "".dup
+
+        text.each_line do |line|
+          indentation = line[/^\s+/] || ""
+          indentation_size = indentation.split(//).map { |ch| ch == "\t" ? 8 : 1 }.sum
+          line_length = output_columns - indentation_size
+          line_length = MIN_MAX_LEN if line_length < MIN_MAX_LEN
+
+          lines = line.strip.gsub(/(.{1,#{line_length}})(?:\s+|\Z)/, "\\1\n").split(/\n/)
+
+          if lines.empty?
+            formatted << "\n"
+          else
+            formatted << lines.map { |l| "#{indentation}#{l}\n" }.join
+          end
+        end
+
+        formatted
+      end
+
+      def output_columns #:nodoc:
+        if ( @output_columns.nil? )
+          if ( self.class.ui.output_cols.nil? )
+            @output_columns = 80
+          else
+            @output_columns = self.class.ui.output_cols
+          end
+        end
+        @output_columns
+      end
+    end
+  end
+end

data/lib/minestrone/cli/help.txt

@@ -0,0 +1,72 @@
+-----------------------------
+<%= color('Minestrone', :bold) %>
+-----------------------------
+
+Minestrone is a utility for automating the execution of commands across multiple remote machines. It was originally conceived as an aid to deploy Ruby on Rails web applications, but has since evolved to become a much more general-purpose tool.
+
+The command-line interface to Minestrone is via the `min' command.
+
+  min [ option ] ... action ...
+
+The following options are understood:
+
+  <%= color '-d, --debug', :bold %>
+  Causes Minestrone to pause and prompt before executing any remote command, giving the user the option to either execute the command, skip the command, or abort execution entirely. This makes it a great way to troubleshoot tasks, or test custom tasks, by executing commands one at a time and checking the server to make sure they worked as expected before moving on to the next command. (Compare this to the --dry-run command.)
+
+  <%= color '-e, --explain TASK', :bold %>
+  Displays the extended description of the given task. Not all tasks will have an extended description, but for those that do, this can provide a wealth of additional usage information, such as describing environment variables or settings that can affect the execution of the task.
+
+  <%= color '-F, --default-config', :bold %>
+  By default, min will search for a config file named `Capfile' or `capfile' in the current directory, or in any parent directory, and will automatically load it. However, if you specify the -f flag (see below), min will use that file instead of the default config. If you want to use both the default config, and files loaded via -f, you can specify -F to force min to search for and load the default config, even if additional files were specified via -f.
+
+  <%= color '-f, --file FILE', :bold %>
+  Causes the named file to be loaded. Minestrone will search both its own recipe directory, as well as the current directory, looking for the named file. An ".rb" extension is optional. The -f option may be given any number of times, but if it is given, it will take the place of the normal `Capfile' or `capfile' detection. Use -F if you want the default capfile to be loaded when you use -f.
+
+  <%= color '-H, --long-help', :bold %>
+  Displays this document and exits.
+
+  <%= color '-h, --help', :bold %>
+  Shows a brief summary of these options and exits.
+
+  <%= color '-l, --logger [STDERR|STDOUT|file]', :bold %>
+  Change the file used to print the output. It offers three options: standard error(stderr), standard output and file. Options are not case sensitive. By default Minestrone uses stderr.
+
+  <%= color '-n, --dry-run', :bold %>
+  Causes Minestrone to simply display each remote command, without executing it. In this sense it is similar to --debug, but without the prompt. Note that commands executed locally are still run--only remote commands are skipped.
+
+  <%= color '-p, --password', :bold %>
+  Normally, min will prompt for the sudo password on-demand, the first time it is needed. This can make it hard to walk away from Minestrone, since you might not know if it will prompt for a password down the road. In such cases, you can use the -p option to force min to prompt for the sudo password immediately.
+
+  <%= color '-q, --quiet', :bold %>
+  Display only critical error messages. All other output is suppressed.
+
+  <%= color '-S, --set-before NAME=VALUE', :bold %>
+  Sets the given variable to the given value, before loading any recipe files. This is useful if you have a recipe file that depends on a certain variable being set, at the time it is loaded.
+
+  <%= color '-s, --set NAME=VALUE', :bold %>
+  Sets the given variable to the given value, after loading all recipe files. This is useful when you want to override the value of a variable which is used in a task. Note that this will set the variables too late for them to affect conditions that are executed as the recipes are loaded.
+
+  <%= color '-T, --tasks PATTERN', :bold %>
+  Displays the list of all tasks (matching optional PATTERN) in all loaded recipe files. If a task has no description, or if the description starts with the [internal] tag, the task will not be listed unless you also specify -v.
+
+  <%= color '-t, --tool', :bold %>
+  Abbreviates the output of -T for integration with other tools. Without -t, -T will list tasks with their summaries, and may include additional instructive text at the bottom. When integrating with other tools (e.g., bash auto-expansion and the like) that additional text can get in the way. This switch makes it easier for those tools to parse the list of tasks. (The -t switch has no effect if the -T switch is not specified.)
+
+  <%= color '-V, --version', :bold %>
+  Shows the current Minestrone version number and exits.
+
+  <%= color '-v, --verbose', :bold %>
+  Increase the verbosity. You can specify this option up to three times to further increase verbosity. By default, min will use maximum verbosity, but if you specify an explicit verbosity, that will be used instead. See also -q.
+
+  <%= color '-X, --skip-system-config', :bold %>
+  By default, min will look for and (if it exists) load the global system configuration file located in /etc/minestrone.conf. If you don't want min to load that file, give this option.
+
+  <%= color '-x, --skip-user-config', :bold %>
+  By default, min will look for and (if it exists) load the user-specific configuration file located in $HOME/.caprc. If you don't want min to load that file, give this option.
+
+-----------------------------
+<%= color('Environment Variables', :bold) %>
+-----------------------------
+
+  <%= color 'SERVER', :bold %>
+  Execute the tasks against this server instead of the configured server.

data/lib/minestrone/cli/options.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Minestrone
+  class CLI
+    module Options
+
+      # The hash of (parsed) command-line options
+      attr_reader :options
+
+      # Return an OptionParser instance that defines the acceptable command
+      # line switches for Minestrone, and what their corresponding behaviors
+      # are.
+      def option_parser #:nodoc:
+        @logger = Logger.new
+        @option_parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: #{File.basename($0)} [options] action ..."
+
+          opts.on("-d", "--debug",
+            "Prompts before each remote command execution."
+          ) { |value| options[:debug] = true }
+
+          opts.on("-e", "--explain TASK",
+            "Displays help (if available) for the task."
+          ) { |value| options[:explain] = value }
+
+          opts.on("-F", "--default-config",
+            "Always use default config, even with -f."
+          ) { options[:default_config] = true }
+
+          opts.on("-f", "--file FILE",
+            "A recipe file to load. May be given more than once."
+          ) { |value| options[:recipes] << value }
+
+          opts.on("-H", "--long-help", "Explain these options and environment variables.") do
+            long_help
+            exit
+          end
+
+          opts.on("-h", "--help", "Display this help message.") do
+            puts opts
+            exit
+          end
+
+          opts.on("-l", "--logger [STDERR|STDOUT|file]",
+            "Choose logger method. STDERR used by default."
+          ) do |value|
+            options[:output] = if value.nil? || value.upcase == 'STDERR'
+                                 # Using default logger.
+                                 nil
+                               elsif value.upcase == 'STDOUT'
+                                 $stdout
+                               else
+                                 value
+                               end
+          end
+
+          opts.on("-n", "--dry-run",
+            "Prints out commands without running them."
+          ) { |value| options[:dry_run] = true }
+
+          opts.on("-p", "--password",
+            "Immediately prompt for the sudo password."
+          ) { options[:password] = nil }
+
+          opts.on("-q", "--quiet",
+            "Make the output as quiet as possible."
+          ) { options[:verbose] = 0 }
+
+          opts.on("-S", "--set-before NAME=VALUE",
+            "Set a variable before the recipes are loaded."
+          ) do |pair|
+            name, value = pair.split(/=/, 2)
+            options[:pre_vars][name.to_sym] = value
+          end
+
+          opts.on("-s", "--set NAME=VALUE",
+            "Set a variable after the recipes are loaded."
+          ) do |pair|
+            name, value = pair.split(/=/, 2)
+            options[:vars][name.to_sym] = value
+          end
+
+          opts.on("-T", "--tasks [PATTERN]",
+            "List all tasks (matching optional PATTERN) in the loaded recipe files."
+          ) do |value|
+            options[:tasks] = if value
+              value
+            else
+              true
+            end
+            options[:verbose] ||= 0
+          end
+
+          opts.on("-t", "--tool",
+            "Abbreviates the output of -T for tool integration."
+          ) { options[:tool] = true }
+
+          opts.on("-V", "--version",
+            "Display the Minestrone version, and exit."
+          ) do
+            require 'minestrone/version'
+            puts "Minestrone v#{Minestrone::Version}"
+            exit
+          end
+
+          opts.on("-v", "--verbose",
+            "Be more verbose. May be given more than once."
+          ) do
+            options[:verbose] ||= 0
+            options[:verbose] += 1
+          end
+
+          opts.on("-X", "--skip-system-config",
+            "Don't load the system config file (minestrone.conf)"
+          ) { options.delete(:sysconf) }
+
+          opts.on("-x", "--skip-user-config",
+            "Don't load the user config file (.caprc)"
+          ) { options.delete(:dotfile) }
+        end
+      end
+
+      # If the arguments to the command are empty, this will print the
+      # allowed options and exit. Otherwise, it will parse the command
+      # line and set up any default options.
+
+      def parse_options!
+        @options = {
+          :recipes => [],
+          :actions => [],
+          :vars => {},
+          :pre_vars => {},
+          :sysconf => default_sysconf,
+          :dotfile => default_dotfile
+        }
+
+        if args.empty?
+          warn "Please specify at least one action to execute."
+          warn option_parser
+          exit
+        end
+
+        option_parser.parse!(args)
+
+        coerce_variable_types!
+
+        # if no verbosity has been specified, be verbose
+        options[:verbose] = 3 if !options.has_key?(:verbose)
+
+        look_for_default_recipe_file! if options[:default_config] || options[:recipes].empty?
+        extract_environment_variables!
+
+        options[:actions].concat(args)
+
+        password = options.has_key?(:password)
+        options[:password] = Proc.new { self.class.password_prompt }
+        options[:password] = options[:password].call if password
+      end
+
+      # Extracts name=value pairs from the remaining command-line arguments
+      # and assigns them as environment variables.
+
+      def extract_environment_variables!
+        args.delete_if do |arg|
+          next unless arg.match(/^(\w+)=(.*)$/)
+          ENV[$1] = $2
+        end
+      end
+
+      # Looks for a default recipe file in the current directory.
+
+      def look_for_default_recipe_file!
+        current = Dir.pwd
+
+        loop do
+          %w(Capfile capfile).each do |file|
+            if File.file?(file)
+              options[:recipes] << file
+              @logger.info "Using recipes from #{File.join(current,file)}"
+              return
+            end
+          end
+
+          pwd = Dir.pwd
+          Dir.chdir("..")
+          break if pwd == Dir.pwd # if changing the directory made no difference, then we're at the top
+        end
+
+        Dir.chdir(current)
+      end
+
+      def default_sysconf #:nodoc:
+        File.join(sysconf_directory, "minestrone.conf")
+      end
+
+      def default_dotfile #:nodoc:
+        File.join(home_directory, ".caprc")
+      end
+
+      def sysconf_directory #:nodoc:
+        '/etc'
+      end
+
+      def home_directory #:nodoc:
+        ENV["HOME"] || "/"
+      end
+
+      def coerce_variable_types!
+        [:pre_vars, :vars].each do |collection|
+          options[collection].keys.each do |key|
+            options[collection][key] = coerce_variable(options[collection][key])
+          end
+        end
+      end
+
+      def coerce_variable(value)
+        case value
+        when /^"(.*)"$/ then $1
+        when /^'(.*)'$/ then $1
+        when /^\d+$/ then value.to_i
+        when /^\d+\.\d*$/ then value.to_f
+        when "true" then true
+        when "false" then false
+        when "nil" then nil
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/minestrone/cli.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'minestrone'
+require 'minestrone/cli/help'
+require 'minestrone/cli/options'
+require 'minestrone/configuration'
+require 'highline'
+
+# work around problem where HighLine detects an eof on $stdin and raises an
+# error.
+HighLine.track_eof = false
+
+module Minestrone
+
+  # The CLI class encapsulates the behavior of minestrone when it is invoked
+  # as a command-line utility. This allows other programs to embed Minestrone
+  # and preserve its command-line semantics.
+
+  class CLI
+
+    # The array of (unparsed) command-line options
+    attr_reader :args
+
+    # Return a new CLI instance with the given arguments pre-parsed and
+    # ready for execution.
+    def self.parse(args)
+      self.new(args).tap { |c| c.parse_options! }
+    end
+
+    # Invoke minestrone using the ARGV array as the option parameters. This
+    # is what the command-line minestrone utility does.
+    def self.execute
+      parse(ARGV).execute!
+    end
+
+    # Return the object that provides UI-specific methods, such as prompts
+    # and more.
+    def self.ui
+      @ui ||= HighLine.new
+    end
+
+    # Prompt for a password using echo suppression.
+    def self.password_prompt(prompt = "Password: ")
+      ui.ask(prompt) { |q| q.echo = false }
+    end
+
+    # Debug mode prompt
+    def self.debug_prompt(cmd)
+      ui.say("Preparing to execute command: #{cmd}")
+      prompt = "Execute ([Yes], No, Abort) "
+      ui.ask("#{prompt}?  ") do |q|
+        q.overwrite = false
+        q.default = 'y'
+        q.validate = /(y(es)?)|(no?)|(a(bort)?|\n)/i
+        q.responses[:not_valid] = prompt
+      end
+    end
+
+    # Create a new CLI instance using the given array of command-line parameters
+    # to initialize it. By default, +ARGV+ is used, but you can specify a
+    # different set of parameters (such as when embedded `min` in a program):
+    #
+    #   require 'minestrone/cli'
+    #   Minestrone::CLI.parse(%W(-vvvv -f config/deploy update_code)).execute!
+    #
+    # Note that you can also embed `min` directly by creating a new Configuration
+    # instance and setting it up, The above snippet, redone using the
+    # Configuration class directly, would look like:
+    #
+    #   require 'minestrone'
+    #   require 'minestrone/cli'
+    #   config = Minestrone::Configuration.new
+    #   config.logger.level = Minestrone::Logger::TRACE
+    #   config.set(:password) { Minestrone::CLI.password_prompt } # sudo password
+    #   config.load "config/deploy"
+    #   config.update_code
+    #
+    # There may be times that you want/need the additional control offered by
+    # manipulating the Configuration directly, but generally interfacing with
+    # the CLI class is recommended.
+
+    def initialize(args)
+      @args = args.dup
+      $stdout.sync = true # so that Net::SSH prompts show up
+    end
+
+    # Using the options build when the command-line was parsed, instantiate
+    # a new Minestrone configuration, initialize it, and execute the
+    # requested actions.
+    #
+    # Returns the Configuration instance used, if successful.
+
+    def execute!
+      config = instantiate_configuration(options)
+
+      config.debug = options[:debug]
+      config.dry_run = options[:dry_run]
+      config.logger.level = options[:verbose]
+
+      set_pre_vars(config)
+      load_recipes(config)
+
+      config.trigger(:load)
+      execute_requested_actions(config)
+      config.trigger(:exit)
+
+      config
+    rescue Exception => error
+      handle_error(error)
+    end
+
+    def execute_requested_actions(config)
+      Array(options[:vars]).each { |name, value| config.set(name, value) }
+
+      Array(options[:actions]).each do |action|
+        config.find_and_execute_task(action, :before => :start, :after => :finish)
+      end
+    end
+
+    def set_pre_vars(config) #:nodoc:
+      config.set :password, options[:password]
+      Array(options[:pre_vars]).each { |name, value| config.set(name, value) }
+    end
+
+    def load_recipes(config) #:nodoc:
+      # load the standard recipe definition
+      config.load 'standard'
+
+      # load systemwide config/recipe definition
+      config.load(options[:sysconf]) if options[:sysconf] && File.file?(options[:sysconf])
+
+      # load user config/recipe definition
+      config.load(options[:dotfile]) if options[:dotfile] && File.file?(options[:dotfile])
+
+      Array(options[:recipes]).each { |recipe| config.load(recipe) }
+    end
+
+    # Primarily useful for testing, but subclasses of CLI could conceivably
+    # override this method to return a Configuration subclass or replacement.
+
+    def instantiate_configuration(options = {})
+      Minestrone::Configuration.new(options)
+    end
+
+    def handle_error(error) #:nodoc:
+      case error
+      when Net::SSH::AuthenticationFailed
+        abort "authentication failed for `#{error.message}'"
+      when Minestrone::Error
+        abort(error.message)
+      else
+        raise error
+      end
+    end
+
+    include Options
+    include Help # needs to be included last, because it overrides some methods
+  end
+end