runbook 0.12.1

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/TODO.md

@@ -0,0 +1,38 @@
+## Desired feature list
+* [X] Revise README.md
+* [] capistrano-runbook gem that integrates runbook into capistrano tasks
+* [] Create a generator for a runbook? Allow for custom generators?
+  * Generate runbook templates
+  * Generate runbook projects with Runbookfile, Gemfile, etc.
+  * Generate plugins
+* [] Add Appraisal to test against multiple versions of Ruby
+* [] Update output to be more log friendly, including timestamps for operations
+* [] Allow for preventing echo when prompting for input
+* [] Add an ability for skipping mutation commands that will have an affect on the system
+* [] Add a revert section that does not get executed, but can be executed by passing a revert flag
+* [] Specify version in runbook to allow for supporting backwards incompatible runbook DSL format changes
+* [] Add support for sudo interaction handler for raw commands
+* [] Replace Thor with a solution that is more easily extendable (adding new flags, etc.)
+* [] Add goto statements for repeating steps (functionality exists in paranoid mode)
+* [] Add test statement
+* [] Feedback on completion of tmux commands (when they complete, return values, outputs)
+* [] Add shorter aliases for tmux layout keys
+* [] Add host aliases for ssh_config setters
+* [] Allow for step dependencies that get executed before the step
+* [] Add periodic flush for sshkit output
+* Add a way to execute a series of commands in groups
+* Docker testing story for more full-stack integration tests
+  * Test integration with sshkit
+  * Test sshkit-sudo functionality
+* logging solution for alternate output
+* Pattern for conditionally enabling plugins? Conditional plugins should be implemented as separate gems.
+  * Requiring a plugin is the same as enabling it
+  * Configuration can be added to toggle aspects of the plugin
+* Add a setup step that always executes even if start_at is defined
+* Yaml specification format (subset of Ruby)
+  * Will not contain as much flexibility as Ruby format
+  * Can convert from Ruby format to yaml (depending on compatibility) and yaml to Ruby
+* Guard for view updates (How to handle arguments?)
+* Be able to serve up markdown docs (web server) for easy viewing
+* Could provide a rake task for compiling and nooping runbooks?
+* Can specify input-format, output-format, input (file), and output (file)

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "runbook"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start
+
+# require "irb"
+# IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/runbook

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'runbook/cli'
+
+Runbook::CLI.start

data/lib/hacks/ssh_kit.rb

@@ -0,0 +1,58 @@
+::SSHKit::Backend::Abstract.class_eval do
+  # Code taken from https://github.com/capistrano/sshkit/blob/v1.16.0/lib/sshkit/backends/abstract.rb#L98-L116
+  # Copyright (c) 2008- Lee Hambley & Contributors
+  # License link: https://github.com/capistrano/sshkit/blob/v1.16.0/LICENSE.md
+  #
+  # Full copyright notice and license:
+  #
+  # Copyright (c) 2008- Lee Hambley & Contributors
+  #
+  # Permission is hereby granted, free of charge, to any person obtaining a
+  # copy of this software and associated documentation files (the "Software"),
+  # to deal in the Software without restriction, including without limitation
+  # the rights to use, copy, modify, merge, publish, distribute, sublicense,
+  # and/or sell copies of the Software, and to permit persons to whom the
+  # Software is furnished to do so, subject to the following conditions:
+  #
+  # The above copyright notice and this permission notice shall be included
+  # in all copies or substantial portions of the Software.
+  #
+  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+  # DEALINGS IN THE SOFTWARE.
+
+  def as(who, &_block)
+    if who.is_a? Hash
+      @user  = who[:user]  || who["user"]
+      @group = who[:group] || who["group"]
+    else
+      @user  = who
+      @group = nil
+    end
+
+    execute_args = {verbosity: Logger::DEBUG}
+    old_pty = ::SSHKit::Backend::Netssh.config.pty
+    begin
+      if Runbook.configuration.enable_sudo_prompt
+        execute_args[:interaction_handler] ||= ::SSHKit::Sudo::InteractionHandler.new
+        ::SSHKit::Backend::Netssh.config.pty = true
+      end
+      execute <<-EOTEST, execute_args
+        if ! sudo -u #{@user} whoami > /dev/null
+          then echo "You cannot switch to user '#{@user}' using sudo, please check the sudoers file" 1>&2
+          false
+        fi
+      EOTEST
+      yield
+    ensure
+      ::SSHKit::Backend::Netssh.config.pty = old_pty
+    end
+  ensure
+    remove_instance_variable(:@user)
+    remove_instance_variable(:@group)
+  end
+end

data/lib/runbook/cli.rb

@@ -0,0 +1,90 @@
+require "thor"
+require "runbook"
+
+module Runbook
+  class CLI < Thor
+    map "--version" => :__print_version
+    class_option :config, aliases: :c, type: :string
+
+    def initialize(args = [], local_options = {}, config = {})
+      super(args, local_options, config)
+
+      cmd_name = config[:current_command].name
+      _set_cli_config(options[:config], cmd_name) if options[:config]
+    end
+
+    desc "view RUNBOOK", "Prints a formatted version of the runbook"
+    long_desc <<-LONGDESC
+      Prints the runbook.
+
+      With --view (-v), Prints the view using the specified view type
+    LONGDESC
+    option :view, aliases: :v, type: :string, default: :markdown
+    def view(runbook)
+      runbook = _retrieve_runbook(runbook, :view)
+      puts Runbook::Viewer.new(runbook).generate(
+        view: options[:view],
+      )
+    end
+
+    desc "exec RUNBOOK", "Executes the runbook"
+    long_desc <<-LONGDESC
+      Executes the runbook.
+
+      With --noop (-n),        Runs the runbook in no-op mode, preventing
+                               commands from executing.
+
+      With --auto (-a),        Runs the runbook in auto mode. This
+                               will prevent the execution from asking
+                               for any user input (such as confirmations).
+                               Not all runbooks are compatible with auto
+                               mode (if they use the ask statement without
+                               defaults for example).
+
+      With --run (-r),         Runs the runbook with the specified run type
+
+      With --no-paranoid (-P), Runs the runbook without prompting to
+                               continue at every step
+
+      With --start-at (-s),    Runs the runbook starting at the specified
+                               section or step.
+    LONGDESC
+    option :run, aliases: :r, type: :string, default: :ssh_kit
+    option :noop, aliases: :n, type: :boolean
+    option :auto, aliases: :a, type: :boolean
+    option :"no-paranoid", aliases: :P, type: :boolean
+    option :start_at, aliases: :s, type: :string, default: "0"
+    def exec(runbook)
+      runbook = _retrieve_runbook(runbook, :exec)
+      Runbook::Runner.new(runbook).run(
+        run: options[:run],
+        noop: options[:noop],
+        auto: options[:auto],
+        paranoid: options[:"no-paranoid"] == nil,
+        start_at: options[:start_at],
+      )
+    end
+
+    desc "--version", "Print runbook's version"
+    def __print_version
+      puts "Runbook v#{Runbook::VERSION}"
+    end
+
+    private
+
+    def _set_cli_config(config, cmd)
+      unless File.exist?(config)
+        raise Thor::InvocationError, "#{cmd}: cannot access #{config}: No such file or directory"
+      end
+      Runbook::Configuration.cli_config_file = config
+    end
+
+    def _retrieve_runbook(runbook, cmd)
+      unless File.exist?(runbook)
+        raise Thor::InvocationError, "#{cmd}: cannot access #{runbook}: No such file or directory"
+      end
+      load(runbook)
+      Runbook.books.last || eval(File.read(runbook))
+    end
+  end
+end

data/lib/runbook/configuration.rb

@@ -0,0 +1,110 @@
+module Runbook
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    Configuration.load_config
+    self.configuration ||= Configuration.new
+    yield(configuration) if block_given?
+  end
+
+  def self.reset_configuration
+    self.configuration = Configuration.new
+    Configuration.loaded = false
+  end
+
+  class Configuration
+    attr_accessor :ssh_kit
+    attr_accessor :enable_sudo_prompt
+    attr_reader :use_same_sudo_password
+
+    GlobalConfigFile = "/etc/runbook.conf"
+    ProjectConfigFile = "Runbookfile"
+    UserConfigFile = ".runbook.conf"
+
+    def self.cli_config_file
+      @cli_config_file
+    end
+
+    def self.cli_config_file=(cli_config_file)
+      @cli_config_file = cli_config_file
+    end
+
+    def self.loaded
+      @loaded
+    end
+
+    def self.loaded=(loaded)
+      @loaded = loaded
+    end
+
+    def self.load_config
+      return if @loaded
+      @loaded = true
+      _load_global_config
+      _load_project_config
+      _load_user_config
+      _load_cli_config
+      # Set defaults
+      Runbook.configure
+    end
+
+    def self.reconfigure
+      @loaded = false
+      load_config
+    end
+
+    def self._load_global_config
+      load(GlobalConfigFile) if File.exist?(GlobalConfigFile)
+    end
+
+    def self._load_project_config
+      dir = Dir.pwd
+      loop do
+        config_path = File.join(dir, ProjectConfigFile)
+        if File.exist?(config_path)
+          load(config_path)
+          return
+        end
+        break if File.identical?(dir, "/")
+        dir = File.join(dir, "..")
+      end
+    end
+
+    def self._load_user_config
+      user_config_file = File.join(ENV["HOME"], UserConfigFile)
+      load(user_config_file) if File.exist?(user_config_file)
+    end
+
+    def self._load_cli_config
+      if cli_config_file && File.exist?(cli_config_file)
+        load(cli_config_file)
+      end
+    end
+
+    def initialize
+      self.ssh_kit = SSHKit.config
+      ssh_kit.output = Airbrussh::Formatter.new(
+        $stdout,
+        banner: nil,
+        command_output: true,
+      )
+      self.enable_sudo_prompt = true
+      self.use_same_sudo_password = true
+    end
+
+    def use_same_sudo_password=(use_same_pwd)
+      @use_same_sudo_password = use_same_pwd
+      SSHKit::Sudo::InteractionHandler.class_eval do
+        if use_same_pwd
+          use_same_password!
+        else
+          def password_cache_key(host)
+            "#{host.user}@#{host.hostname}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/runbook/dsl.rb

@@ -0,0 +1,21 @@
+module Runbook
+  module DSL
+    def self.class(*modules)
+      Class.new do
+        attr_reader :parent
+
+        def initialize(parent)
+          @parent = parent
+        end
+
+        modules.each do |mod|
+          prepend mod
+        end
+      end
+    end
+
+    def self.dsl_ivars
+      [:@parent]
+    end
+  end
+end

data/lib/runbook/entities/book.rb

@@ -0,0 +1,17 @@
+module Runbook::Entities
+  class Book < Runbook::Entity
+    def initialize(title)
+      super(title)
+    end
+
+    # Seed data for 'render' tree traversal method
+    def self.initial_render_metadata
+      {depth: 1, index: 0}
+    end
+
+    # Seed data for 'run' tree traversal method
+    def self.initial_run_metadata
+      {depth: 1, index: 0, position: ""}
+    end
+  end
+end

data/lib/runbook/entities/section.rb

@@ -0,0 +1,7 @@
+module Runbook::Entities
+  class Section < Runbook::Entity
+    def initialize(title)
+      super(title)
+    end
+  end
+end

data/lib/runbook/entities/step.rb

@@ -0,0 +1,7 @@
+module Runbook::Entities
+  class Step < Runbook::Entity
+    def initialize(title=nil)
+      super(title)
+    end
+  end
+end

data/lib/runbook/entity.rb

@@ -0,0 +1,127 @@
+module Runbook
+  class Entity < Node
+    include Runbook::Hooks::Invoker
+    const_set(:DSL, Runbook::DSL.class)
+
+    def self.inherited(child_class)
+      child_class.const_set(:DSL, Runbook::DSL.class)
+    end
+
+    attr_accessor :parent
+    attr_reader :title, :dsl
+
+    def initialize(title, parent: nil)
+      @title = title
+      @parent = parent
+      @dsl = "#{self.class}::DSL".constantize.new(self)
+    end
+
+    def add(item)
+      items << item
+      item.parent = self
+    end
+
+    def items
+      @items ||= []
+    end
+
+    def method_missing(method, *args, &block)
+      if dsl.respond_to?(method)
+        dsl.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to?(name, include_private = false)
+      !!(dsl.respond_to?(name) || super)
+    end
+
+    def render(view, output, metadata)
+      invoke_with_hooks(view, self, output, metadata) do
+        view.render(self, output, metadata)
+        items.each_with_index do |item, index|
+          new_metadata = _render_metadata(items, item, metadata, index)
+          item.render(view, output, new_metadata)
+        end
+      end
+    end
+
+    def run(run, metadata)
+      return if _should_reverse?(run, metadata)
+      return if dynamic? && visited?
+
+      invoke_with_hooks(run, self, metadata) do
+        run.execute(self, metadata)
+        next if _should_reverse?(run, metadata)
+        loop do
+          items.each_with_index do |item, index|
+            new_metadata = _run_metadata(items, item, metadata, index)
+            # Optimization
+            break if _should_reverse?(run, new_metadata)
+            item.run(run, new_metadata)
+          end
+
+          if _should_retraverse?(run, metadata)
+            metadata[:reverse] = false
+          else
+            break
+          end
+        end
+      end
+      self.visited!
+    end
+
+    def dynamic!
+      items.each(&:dynamic!)
+      @dynamic = true
+    end
+
+    def _render_metadata(items, item, metadata, index)
+      index = items.select do |item|
+        item.is_a?(Entity)
+      end.index(item)
+
+      metadata.merge(
+        {
+          depth: metadata[:depth] + 1,
+          index: index,
+        }
+      )
+    end
+
+    def _run_metadata(items, item, metadata, index)
+      pos_index = items.select do |item|
+        item.is_a?(Entity)
+      end.index(item)
+
+      if pos_index
+        if metadata[:position].empty?
+          pos = "#{pos_index + 1}"
+        else
+          pos = "#{metadata[:position]}.#{pos_index + 1}"
+        end
+      else
+        pos = metadata[:position]
+      end
+
+      metadata.merge(
+        {
+          depth: metadata[:depth] + 1,
+          index: index,
+          position: pos,
+        }
+      )
+    end
+
+    def _should_reverse?(run, metadata)
+      return false unless metadata[:reverse]
+      run.past_position?(metadata[:position], metadata[:start_at])
+    end
+
+    def _should_retraverse?(run, metadata)
+      return false unless metadata[:reverse]
+      run.start_at_is_substep?(self, metadata)
+    end
+  end
+end

data/lib/runbook/errors.rb

@@ -0,0 +1,7 @@
+module Runbook
+  StandardError = Class.new(::StandardError)
+
+  class Runner
+    ExecutionError = Class.new(Runbook::StandardError)
+  end
+end

data/lib/runbook/extensions/add.rb

@@ -0,0 +1,13 @@
+module Runbook::Extensions
+  module Add
+    module DSL
+      def add(entity)
+        parent.add(entity)
+      end
+    end
+  end
+
+  Runbook::Entities::Book::DSL.prepend(Add::DSL)
+  Runbook::Entities::Section::DSL.prepend(Add::DSL)
+  Runbook::Entities::Step::DSL.prepend(Add::DSL)
+end

data/lib/runbook/extensions/description.rb

@@ -0,0 +1,14 @@
+module Runbook::Extensions
+  module Description
+    module DSL
+      def description(msg)
+        Runbook::Statements::Description.new(msg).tap do |desc|
+          parent.add(desc)
+        end
+      end
+    end
+  end
+
+  Runbook::Entities::Book::DSL.prepend(Description::DSL)
+  Runbook::Entities::Section::DSL.prepend(Description::DSL)
+end

data/lib/runbook/extensions/sections.rb

@@ -0,0 +1,15 @@
+module Runbook::Extensions
+  module Sections
+    module DSL
+      def section(title, &block)
+        Runbook::Entities::Section.new(title).tap do |section|
+          parent.add(section)
+          section.dsl.instance_eval(&block)
+        end
+      end
+    end
+  end
+
+  Runbook::Entities::Book::DSL.prepend(Sections::DSL)
+  Runbook::Entities::Section::DSL.prepend(Sections::DSL)
+end

data/lib/runbook/extensions/shared_variables.rb

@@ -0,0 +1,51 @@
+module Runbook::Extensions
+  module SharedVariables
+    module RunHooks
+      def self.register_shared_variables_hooks(base)
+        base.register_hook(
+          :set_ivars_hook,
+          :before,
+          Runbook::Statement,
+        ) do |object, metadata|
+          target = SharedVariables::RunHooks._target(object)
+          metadata[:repo].each do |key, value|
+            target.singleton_class.class_eval { attr_accessor key }
+            target.send(SharedVariables::RunHooks._eqls_method(key), value)
+          end
+        end
+
+        base.register_hook(
+          :copy_ivars_to_repo_hook,
+          :after,
+          Runbook::Statement,
+          before: :save_repo_hook
+        ) do |object, metadata|
+          SharedVariables::RunHooks._copy_ivars_to_repo(object, metadata)
+        end
+      end
+
+      def self._copy_ivars_to_repo(object, metadata)
+        target = _target(object)
+        ivars = target.instance_variables - Runbook::DSL.dsl_ivars
+
+        ivars.each do |ivar|
+          repo_key = ivar.to_s[1..-1].to_sym
+          val = target.instance_variable_get(ivar)
+          metadata[:repo][repo_key] = val
+        end
+      end
+
+      def self._target(object)
+        object.parent.dsl
+      end
+
+      def self._eqls_method(key)
+        "#{key}=".to_sym
+      end
+    end
+  end
+
+  Runbook.runs.each do |run|
+    SharedVariables::RunHooks.register_shared_variables_hooks(run)
+  end
+end