careacademy-runbook 1.2.0

data/lib/runbook/generators/project/templates/README.md.tt

@@ -0,0 +1,29 @@
+# <%= name.titleize %>
+
+## Deployment
+
+This code is best deployed by cloning this project using git.
+
+## Usage
+
+Set up this repository by running `bin/setup`. This will install all necessary dependencies for your runbooks.
+
+Execute your runbooks using `bundle exec runbook exec <PATH_TO_YOUR_RUNBOOK>`
+
+Get runbook help executing `bundle exec runbook help` or visiting https://github.com/braintree/runbook
+
+## This Repository
+
+Runbook code should live in the following locations:
+
+`runbooks` - Place your runbooks in this directory
+
+`<%= @shared_lib_dir %>` - Place code shared across your runbooks in this directory
+
+`lib/runbook/extensions` - Place code that extends Runbook's functionality here. For example, adding a new statement to Runbook's DSL would live in this directory. Require these files in your `Runbookfile` so Runbook can load them when it is launched. See https://github.com/braintree/runbook#extending-runbook for more details on extending Runbook.
+
+`lib/runbook/generators` - Place Runbook generators in this directory. Require these files in your `Runbookfile` to expose the generators via Runbook's command line interface.
+
+## Development
+
+Run `bin/setup` to install any necessary dependencies for this project. Run `bin/console` to use your code via an interactive prompt.

data/lib/runbook/generators/project/templates/Runbookfile.tt

@@ -0,0 +1,11 @@
+# Your Runbookfile serves two purposes. Use your Runbookfile to
+# (1) require any runbook plugins, extensions, or generators that
+# you want available to your runbooks and (2) configure Runbook
+# using a `Runbook.configure` block.
+
+# Use this block to configure Runbook. See
+# https://github.com/braintree/runbook#configuration for more
+# details.
+#
+# Runbook.configure do |config|
+# end

data/lib/runbook/generators/project/templates/base_file.rb.tt

@@ -0,0 +1,8 @@
+# Require your runbook shared code here so it can easily be
+# included in your runbooks and accessed from the interactive
+# console using `bin/console`.
+
+require "runbook"
+
+module <%= name.camelize %>
+end

data/lib/runbook/generators/runbook/runbook.rb

@@ -0,0 +1,22 @@
+module Runbook::Generators
+  class Runbook < Thor::Group
+    include ::Runbook::Generators::Base
+
+    source_root File.dirname(__FILE__)
+
+    def self.usage
+      "runbook NAME [options]"
+    end
+
+    def self.description
+      "Generate a runbook named NAME, e.x. deploy_nginx"
+    end
+
+    argument :name, desc: "The name of your runbook, e.x. deploy_nginx"
+
+    def create_runbook
+      target = File.join(options[:root], "#{name.underscore}.rb")
+      template('templates/runbook.tt', target)
+    end
+  end
+end

data/lib/runbook/generators/runbook/templates/runbook.tt

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require "runbook"
+
+runbook = Runbook.book "<%= name.titleize %>" do
+  description <<-DESC
+This is a runbook that...
+  DESC
+
+  section "SECTION" do
+    step "STEP" do
+      # Add statements here
+    end
+  end
+end
+
+if __FILE__ == $0
+  Runbook::Runner.new(runbook).run
+else
+  runbook
+end

data/lib/runbook/generators/statement/statement.rb

@@ -0,0 +1,18 @@
+module Runbook::Generators
+  class Statement < Thor::Group
+    include ::Runbook::Generators::Base
+
+    source_root File.dirname(__FILE__)
+
+    def self.description
+      "Generate a statement named NAME (e.x. ruby_command) that can be used in your runbooks"
+    end
+
+    argument :name, desc: "The name of your statement, e.x. ruby_command"
+
+    def create_statement
+      target = File.join(parent_options[:root], "#{name.underscore}.rb")
+      template('templates/statement.tt', target)
+    end
+  end
+end

data/lib/runbook/generators/statement/templates/statement.tt

@@ -0,0 +1,34 @@
+# Remember to require this file in a runbook config file
+# or in your project so it is available in your runbooks
+module Runbook::Statements
+  class <%= name.classify %> < Runbook::Statement
+    # Add all attributes for your statement
+    attr_reader :attr1, :attr2
+
+    # Define the initialize method signature to
+    # match the method signature of your dsl statement
+    def initialize(attr1, attr2)
+      @attr1 = attr1
+      @attr2 = attr2
+    end
+  end
+end
+
+# scope this module using your project's namespace
+module MyProject::RunbookExtensions
+  module <%= "#{name.underscore}_markdown".classify %>
+    def runbook__statements__<%= name.underscore %>(object, output, metadata)
+      # Format how your statement will be displayed when rendered with markdown
+      output << "#{object.attr1}#{object.attr2}"
+    end
+  end
+  Runbook::Views::Markdown.singleton_class.prepend(<%= "#{name.underscore}_markdown".classify %>)
+
+  module <%= "#{name.underscore}_sshkit".classify %>
+    def runbook__statements__<%= name.underscore %>(object, metadata)
+      # Execute your behavior using object which is your instantiated statement
+      # and the current metadata for this step of the execution
+    end
+  end
+  Runbook::Runs::SSHKit.singleton_class.prepend(<%= "#{name.underscore}_sshkit".classify %>)
+end

data/lib/runbook/helpers/format_helper.rb

@@ -0,0 +1,11 @@
+module Runbook::Helpers
+  module FormatHelper
+    def deindent(str, padding: 0)
+      lines = str.split("\n")
+      indentations = lines.map { |l| l.size - l.gsub(/^\s+/, "").size }
+      min_indentation = indentations.min
+      lines.map! { |line| " " * padding + line[min_indentation..-1] }
+      lines.join("\n")
+    end
+  end
+end

data/lib/runbook/helpers/ssh_kit_helper.rb

@@ -0,0 +1,143 @@
+module Runbook::Helpers
+  module SSHKitHelper
+    def ssh_kit_command(cmd, raw: false)
+      return [cmd] if raw
+      cmd, args = cmd.split(" ", 2)
+      [cmd.to_sym, args]
+    end
+
+    def ssh_kit_command_options(ssh_config)
+      {}.tap do |options|
+        if ssh_config[:user] && Runbook.configuration.enable_sudo_prompt
+          options[:interaction_handler] ||= ::SSHKit::Sudo::InteractionHandler.new
+        end
+      end
+    end
+
+    def find_ssh_config(object, ssh_config_method=:ssh_config)
+      blank_config = Runbook::Extensions::SSHConfig.blank_ssh_config
+      nil_or_blank = ->(config) { config.nil? || config == blank_config }
+      ssh_config = object.send(ssh_config_method)
+      return ssh_config unless nil_or_blank.call(ssh_config)
+      object = object.parent
+
+      while object
+        ssh_config = object.ssh_config
+        return ssh_config unless nil_or_blank.call(ssh_config)
+        object = object.parent
+      end
+
+      return blank_config
+    end
+
+    def render_ssh_config_output(ssh_config)
+      "".tap do |output|
+        if (servers = ssh_config[:servers]).any?
+          server_str = servers.join(", ")
+          if server_str.size > 80
+            server_str = "#{server_str[0..38]}...#{server_str[-38..-1]}"
+          end
+          output << "   on: #{server_str}\n"
+        end
+
+        if (strategy = ssh_config[:parallelization][:strategy])
+          limit = ssh_config[:parallelization][:limit]
+          wait = ssh_config[:parallelization][:wait]
+          in_str = "   in: #{strategy}"
+          in_str << ", limit: #{limit}" if strategy == :groups
+          in_str << ", wait: #{wait}" if [:sequence, :groups].include?(strategy)
+          output << "#{in_str}\n"
+        end
+
+        if ssh_config[:user] || ssh_config[:group]
+          user = ssh_config[:user]
+          group = ssh_config[:group]
+          as_str = "   as:"
+          as_str << " user: #{user}" if user
+          as_str << " group: #{group}" if group
+          output << "#{as_str}\n"
+        end
+
+        if (path = ssh_config[:path])
+          output << "   within: #{path}\n"
+        end
+
+        if (env = ssh_config[:env])
+          env_str = env.map do |k, v|
+            "#{k.to_s.upcase}=#{v}"
+          end.join(" ")
+          output << "   with: #{env_str}\n"
+        end
+
+        if (umask = ssh_config[:umask])
+          output << "   umask: #{umask}\n"
+        end
+      end
+    end
+
+    def with_ssh_config(ssh_config, &exec_block)
+      user = ssh_config[:user]
+      group = ssh_config[:group]
+      as_block =  _as_block(user, group, &exec_block)
+      within_block = _within_block(ssh_config[:path], &as_block)
+      with_block = _with_block(ssh_config[:env], &within_block)
+
+      _with_umask(ssh_config[:umask]) do
+        servers = _servers(ssh_config[:servers])
+        parallelization = ssh_config[:parallelization]
+        coordinator_options = _coordinator_options(parallelization)
+        SSHKit::Coordinator.new(servers).each(coordinator_options) do
+          instance_exec(&with_block)
+        end
+      end
+    end
+
+    def _servers(ssh_config_servers)
+      return :local if ssh_config_servers.empty?
+      return :local if ssh_config_servers == [:local]
+      ssh_config_servers
+    end
+
+    def _coordinator_options(ssh_config_parallelization)
+      ssh_config_parallelization.clone.tap do |options|
+        if options[:strategy]
+          options[:in] = options.delete(:strategy)
+        end
+      end
+    end
+
+    def _as_block(user, group, &block)
+      if user || group
+        -> { as({user: user, group: group}) { instance_exec(&block) } }
+      else
+        -> { instance_exec(&block) }
+      end
+    end
+
+    def _with_block(env, &block)
+      if env
+        -> { with(env) { instance_exec(&block) } }
+      else
+        -> { instance_exec(&block) }
+      end
+    end
+
+    def _within_block(path, &block)
+      if path
+        -> { within(path) { instance_exec(&block) } }
+      else
+        -> { instance_exec(&block) }
+      end
+    end
+
+    def _with_umask(umask, &block)
+      old_umask = SSHKit.config.umask
+      begin
+        SSHKit.config.umask = umask if umask
+        instance_exec(&block)
+      ensure
+        SSHKit.config.umask = old_umask
+      end
+    end
+  end
+end

data/lib/runbook/helpers/tmux_helper.rb

@@ -0,0 +1,176 @@
+module Runbook::Helpers
+  module TmuxHelper
+    FILE_PERMISSIONS = 0600
+
+    def setup_layout(structure, runbook_title:)
+      _remove_stale_layouts
+      layout_file = _layout_file(_slug(runbook_title))
+      if File.exist?(layout_file)
+        stored_layout = ::YAML::load_file(layout_file)
+        if _all_panes_exist?(stored_layout)
+          return stored_layout
+        end
+      end
+
+      _setup_layout(structure).tap do |layout_panes|
+        File.open(layout_file, 'w', FILE_PERMISSIONS) do |f|
+          f.write(layout_panes.to_yaml)
+        end
+      end
+    end
+
+    def send_keys(command, target)
+      `tmux send-keys -t #{target} #{_pager_escape_sequence} #{Shellwords.escape(command)} C-m`
+    end
+
+    def kill_all_panes(layout_panes)
+      runbook_pane = _runbook_pane
+      layout_panes.values.each do |pane_id|
+        _kill_pane(pane_id) unless pane_id == runbook_pane
+      end
+    end
+
+    def _pager_escape_sequence
+      "q C-u"
+    end
+
+    def _kill_pane(pane_id)
+      `tmux kill-pane -t #{pane_id}`
+    end
+
+    def _layout_file(runbook_title)
+      `tmux display-message -p -t $TMUX_PANE "#{Dir.tmpdir}/runbook_layout_\#{pid}_\#{session_name}_\#{pane_pid}_\#{pane_id}_#{runbook_title}.yml"`.strip
+    end
+
+    def _slug(title)
+      title.titleize.gsub(/[\/\s]+/, "").underscore.dasherize
+    end
+
+    def _all_panes_exist?(stored_layout)
+      (stored_layout.values - _session_panes).empty?
+    end
+
+    def _remove_stale_layouts
+      session_panes = _session_panes
+      session_layout_files = _session_layout_files
+      session_layout_files.each do |file|
+        File.delete(file) unless session_panes.any? { |pane| /_#{pane}_/ =~ file }
+      end
+    end
+
+    def _session_panes
+      `tmux list-panes -s -F '#D'`.split("\n")
+    end
+
+    def _session_layout_files
+      session_layout_glob = `tmux display-message -p "#{Dir.tmpdir}/runbook_layout_\#{pid}_\#{session_name}_*.yml"`.strip
+      Dir[session_layout_glob]
+    end
+
+    def _setup_layout(structure)
+      current_pane = _runbook_pane
+      panes_to_init = []
+      {}.tap do |layout_panes|
+        if structure.is_a?(Hash)
+          first_window = true
+          structure.each do |name, window|
+            if first_window
+              _rename_window(name)
+              first_window = false
+            else
+              current_pane = _new_window(name)
+            end
+            _setup_panes(layout_panes, panes_to_init, current_pane, window)
+          end
+        else
+          _setup_panes(layout_panes, panes_to_init, current_pane, structure)
+        end
+        _swap_runbook_pane(panes_to_init, layout_panes)
+        _initialize_panes(panes_to_init, layout_panes)
+      end
+    end
+
+    def _setup_panes(layout_panes, panes_to_init, current_pane, structure, depth=0)
+      return if structure.empty?
+      case structure
+      when Array
+        case structure.size
+        when 1
+          _setup_panes(layout_panes, panes_to_init, current_pane, structure.shift, depth+1)
+        else
+          size = 100 - 100 / structure.size
+          new_pane = _split(current_pane, depth, size)
+          _setup_panes(layout_panes, panes_to_init, current_pane, structure.shift, depth+1)
+          _setup_panes(layout_panes, panes_to_init, new_pane, structure, depth)
+        end
+      when Hash
+        if structure.values.all? { |v| v.is_a?(Numeric) }
+          total_size = structure.values.reduce(:+)
+          case structure.size
+          when 1
+            _setup_panes(layout_panes, panes_to_init, current_pane, structure.keys[0], depth+1)
+          else
+            size = (total_size - structure.values[0]) * 100 / total_size
+            new_pane = _split(current_pane, depth, size)
+            first_struct = structure.keys[0]
+            structure.delete(first_struct)
+            _setup_panes(layout_panes, panes_to_init, current_pane, first_struct, depth+1)
+            _setup_panes(layout_panes, panes_to_init, new_pane, structure, depth)
+          end
+        else
+          layout_panes[structure[:name]] = current_pane
+          panes_to_init << structure
+        end
+      when Symbol
+        layout_panes[structure] = current_pane
+      end
+    end
+
+    def _swap_runbook_pane(panes_to_init, layout_panes)
+      if (runbook_pane = panes_to_init.find { |pane| pane[:runbook_pane] })
+        current_runbook_pane_name = layout_panes.keys.find do |k|
+          layout_panes[k] == _runbook_pane
+        end
+        target_pane_id = layout_panes[runbook_pane[:name]]
+        layout_panes[runbook_pane[:name]] = _runbook_pane
+        layout_panes[current_runbook_pane_name] = target_pane_id
+        _swap_panes(target_pane_id, _runbook_pane)
+      end
+    end
+
+    def _initialize_panes(panes_to_init, layout_panes)
+      panes_to_init.each do |pane|
+        target = layout_panes[pane[:name]]
+        _set_directory(pane[:directory], target) if pane[:directory]
+        send_keys(pane[:command], target) if pane[:command]
+      end
+    end
+
+    def _runbook_pane
+      @runbook_pane ||= `tmux display-message -p '#D'`.strip
+    end
+
+    def _rename_window(name)
+      `tmux rename-window "#{name}"`
+    end
+
+    def _new_window(name)
+      `tmux new-window -n "#{name}" -P -F '#D' -d`.strip
+    end
+
+    def _split(current_pane, depth, size)
+      direction = depth.even? ? "h" : "v"
+      command = "tmux split-window"
+      args = "-#{direction} -t #{current_pane} -p #{size} -P -F '#D' -d"
+      `#{command} #{args}`.strip
+    end
+
+    def _swap_panes(target_pane, source_pane)
+      `tmux swap-pane -d -t #{target_pane} -s #{source_pane}`
+    end
+
+    def _set_directory(directory, target)
+      send_keys("cd #{directory}; clear", target)
+    end
+  end
+end

data/lib/runbook/hooks.rb

@@ -0,0 +1,88 @@
+module Runbook
+  module Hooks
+    def hooks
+      @hooks ||= []
+    end
+
+    def register_hook(name, type, klass, before: nil, &block)
+      hook = {
+        name: name,
+        type: type,
+        klass: klass,
+        block: block,
+      }
+
+      if before
+        hooks.insert(_hook_index(before), hook)
+      else
+        hooks << hook
+      end
+    end
+
+    def hooks_for(type, klass)
+      hooks.select do |hook|
+        hook[:type] == type && klass <= hook[:klass]
+      end
+    end
+
+    def _hook_index(hook_name)
+      hooks.index { |hook| hook[:name] == hook_name } || -1
+    end
+
+    module Invoker
+      def invoke_with_hooks(executor, object, *args, &block)
+        skip_before = skip_around = skip_after = false
+        if executor <= Runbook::Run
+          if executor.should_skip?(args[0])
+            if executor.start_at_is_substep?(object, args[0])
+              skip_before = skip_around = true
+            else
+              skip_before = skip_around = skip_after = true
+            end
+          end
+        end
+
+        unless skip_before
+          _execute_before_hooks(executor, object, *args)
+        end
+
+        if skip_around
+          block.call
+        else
+          _execute_around_hooks(executor, object, *args, &block)
+        end
+
+        unless skip_after
+          _execute_after_hooks(executor, object, *args)
+        end
+      end
+
+      def _execute_before_hooks(executor, object, *args)
+        executor.hooks_for(:before, object.class).each do |hook|
+          executor.instance_exec(object, *args, &hook[:block])
+        end
+      end
+
+      def _execute_around_hooks(executor, object, *args)
+        executor.hooks_for(:around, object.class).reverse.reduce(
+          -> (object, *args) {
+            yield
+          }
+        ) do |inner_method, hook|
+          -> (object, *args) {
+            inner_block = Proc.new do |object, *args|
+              inner_method.call(object, *args)
+            end
+            executor.instance_exec(object, *args, inner_block, &hook[:block])
+          }
+        end.call(object, *args)
+      end
+
+      def _execute_after_hooks(executor, object, *args)
+        executor.hooks_for(:after, object.class).each do |hook|
+          executor.instance_exec(object, *args, &hook[:block])
+        end
+      end
+    end
+  end
+end

data/lib/runbook/initializer.rb

@@ -0,0 +1,85 @@
+module Runbook
+  class Initializer < Thor::Group
+    include Thor::Actions
+
+    source_root File.join(
+      File.dirname(__FILE__),
+      "generators",
+      "project",
+    )
+
+    add_runtime_options!
+    check_unknown_options!
+
+    def create_runbookfile
+      template(
+        "templates/Runbookfile.tt",
+        "Runbookfile",
+      )
+    end
+
+    def create_runbooks_directory
+      target = "runbooks"
+      empty_directory(target)
+      _keep_dir(target)
+    end
+
+    def create_lib_directory
+      dirs = [
+        "lib",
+        "runbook",
+      ]
+      target = File.join(*dirs)
+
+      empty_directory(target)
+      _keep_dir(target)
+    end
+
+    def create_extensions_directory
+      dirs = [
+        "lib",
+        "runbook",
+        "extensions",
+      ]
+      target = File.join(*dirs)
+
+      empty_directory(target)
+      _keep_dir(target)
+    end
+
+    def create_generators_directory
+      dirs = [
+        "lib",
+        "runbook",
+        "generators",
+      ]
+      target = File.join(*dirs)
+
+      empty_directory(target)
+      _keep_dir(target)
+    end
+
+    def runbook_initialization_overview
+      msg = [
+        "",
+        "Runbook was successfully initialized.",
+        "Add runbooks to the `runbooks` directory.",
+        "Add shared code to `lib/runbook`.",
+        "Execute runbooks using `bundle exec runbook exec <RUNBOOK_PATH>`",
+        "from your project root.",
+        "\n",
+      ]
+
+      say(msg.join("\n"))
+    end
+
+    private
+
+    def _keep_dir(dir)
+      create_file(
+        File.join(dir, ".keep"),
+        verbose: false,
+      )
+    end
+  end
+end

data/lib/runbook/node.rb

@@ -0,0 +1,33 @@
+module Runbook
+  class Node
+    attr_accessor :parent
+
+    def initialize
+      raise "Should not be initialized"
+    end
+
+    def dynamic!
+      @dynamic = true
+    end
+
+    def visited!
+      @visited = true
+    end
+
+    def dynamic?
+      @dynamic
+    end
+
+    def visited?
+      @visited
+    end
+
+    def parent_entity
+      node = self
+      while(node && !node.is_a?(Runbook::Entity))
+        node = node.parent
+      end
+      node
+    end
+  end
+end