octocatalog-diff 0.5.1

data/lib/octocatalog-diff/catalog-util/bootstrap.rb

@@ -0,0 +1,145 @@
+require_relative '../bootstrap'
+require_relative '../util/parallel'
+require_relative 'git'
+
+require 'fileutils'
+
+module OctocatalogDiff
+  module CatalogUtil
+    # Methods to bootstrap a directory. Intended to be called from catalog-diff/cli. This handles
+    # parallelization of bootstrap, and formats arguments as expected by the higher level bootstrap
+    # script.
+    class Bootstrap
+      # Exceptions that are anticipated can be caught in the calling class and tested
+      # for explicitly in spec tests.
+      class BootstrapError < RuntimeError; end
+
+      # Bootstrap directories specified by --bootstrapped-from-dir and --bootstrapped-to-dir
+      # command line options. Bootstrapping occurs in parallel. This takes no parameters (options come
+      # from options) and returns nothing (it raises an exception if something fails).
+      def self.bootstrap_directory_parallelizer(options, logger)
+        # What directories do we have to bootstrap?
+        dirs = []
+
+        unless options[:bootstrapped_from_dir].nil?
+          if options[:from_env] == '.'
+            message = 'Must specify a from-branch other than . when using --bootstrapped-from-dir!' \
+                      ' Please use "-f <from_branch>" argument.'
+            logger.error(message)
+            raise BootstrapError, message
+          end
+
+          opts = options.merge(branch: options[:from_env],
+                               path: options[:bootstrapped_from_dir],
+                               tag: 'from_dir',
+                               dir: options[:basedir])
+          dirs << opts
+        end
+
+        unless options[:bootstrapped_to_dir].nil?
+          if options[:to_env] == '.'
+            message = 'Must specify a to-branch other than . when using --bootstrapped-to-dir!' \
+                      ' Please use "-t <to_branch>" argument.'
+            logger.error(message)
+            raise BootstrapError, message
+          end
+
+          opts = options.merge(branch: options[:to_env],
+                               path: options[:bootstrapped_to_dir],
+                               tag: 'to_dir')
+          dirs << opts
+        end
+
+        # If there are no directories given, advise the user to supply the necessary options
+        if dirs.empty?
+          return unless options[:cached_master_dir].nil?
+          message = 'Specify one or more of --bootstrapped-from-dir / --bootstrapped-to-dir / --cached-master-dir' \
+                    ' when using --bootstrap_then_exit'
+          logger.error(message)
+          raise BootstrapError, message
+        end
+
+        # Bootstrap the directories in parallel. Since there are no results here that we
+        # care about, increment the success counter for each run that did not throw an exception.
+        tasks = dirs.map do |x|
+          OctocatalogDiff::Util::Parallel::Task.new(
+            method: method(:bootstrap_directory),
+            description: "bootstrap #{x[:tag]} #{x[:path]} for #{x[:branch]}",
+            args: x
+          )
+        end
+
+        logger.debug("Begin #{dirs.size} bootstrap(s)")
+        parallel_tasks = OctocatalogDiff::Util::Parallel.run_tasks(tasks, logger, options[:parallel])
+        parallel_tasks.each do |result|
+          if result.status
+            logger.debug("Success bootstrap_directory for #{result.args[:tag]}")
+          else
+            errmsg = "Failed bootstrap_directory for #{result.args[:tag]}: #{result.exception.class} #{result.exception.message}"
+            raise BootstrapError, errmsg
+          end
+        end
+      end
+
+      # Performs the actual bootstrap of a directory. Intended to be called by bootstrap_directory_parallelizer
+      # above, or as part of the parallelized catalog build process from catalog-diff/cli/catalogs.
+      # @param logger [Logger] Logger object
+      # @param dir_opts [Hash] Directory options: branch, path, tag
+      def self.bootstrap_directory(options, logger)
+        raise ArgumentError, ':path must be supplied' unless options[:path]
+        FileUtils.mkdir_p(options[:path]) unless Dir.exist?(options[:path])
+        git_checkout(logger, options) if options[:branch]
+        unless options[:bootstrap_script].nil?
+          install_bootstrap_script(logger, options)
+          run_bootstrap(logger, options)
+        end
+      end
+
+      # Perform git checkout
+      # @param logger [Logger] Logger object
+      # @param dir_opts [Hash] Directory options: branch, path, tag
+      def self.git_checkout(logger, dir_opts)
+        logger.debug("Begin git checkout #{dir_opts[:basedir]}:#{dir_opts[:branch]} -> #{dir_opts[:path]}")
+        OctocatalogDiff::CatalogUtil::Git.check_out_git_archive(dir_opts.merge(logger: logger))
+        logger.debug("Success git checkout #{dir_opts[:basedir]}:#{dir_opts[:branch]} -> #{dir_opts[:path]}")
+      rescue OctocatalogDiff::CatalogUtil::Git::GitCheckoutError => exc
+        logger.error("Git checkout error: #{exc}")
+        raise BootstrapError, exc
+      end
+
+      # Install bootstrap script in the target directory. This allows proper bootstrapping from the
+      # latest version of the script, not the script that was in place at the time that directory's branch
+      # was committed.
+      # @param logger [Logger] Logger object
+      # @param opts [Hash] Directory options
+      def self.install_bootstrap_script(logger, opts)
+        # Verify that bootstrap file exists
+        src = File.join(opts[:basedir], opts[:bootstrap_script])
+        raise BootstrapError, "Bootstrap script #{src} does not exist" unless File.file?(src)
+
+        logger.debug('Begin install bootstrap script in target directory')
+
+        # Create destination directory if needed
+        dest = File.join(opts[:path], opts[:bootstrap_script])
+        dest_dir = File.dirname(dest)
+        FileUtils.mkdir_p(dest_dir) unless File.directory?(dest_dir)
+
+        # Copy file and make executable
+        FileUtils.cp src, dest
+        FileUtils.chmod 0o755, dest
+        logger.debug("Success: copied #{src} to #{dest}")
+      end
+
+      # Execute the bootstrap.
+      # @param logger [Logger] Logger object
+      # @param opts [Hash] Directory options
+      def self.run_bootstrap(logger, opts)
+        logger.debug("Begin bootstrap with '#{opts[:bootstrap_script]}' in #{opts[:path]}")
+        result = OctocatalogDiff::Bootstrap.bootstrap(opts)
+        raise BootstrapError, "bootstrap failed for #{opts[:path]}: #{result[:output]}" unless (result[:status_code]).zero?
+        logger.debug("Success bootstrap in #{opts[:path]}")
+        result[:output]
+      end
+    end
+  end
+end

data/lib/octocatalog-diff/catalog-util/builddir.rb

@@ -0,0 +1,289 @@
+require 'yaml'
+
+require_relative '../facts'
+require_relative 'enc'
+
+module OctocatalogDiff
+  module CatalogUtil
+    # Represents a directory that is created such that a catalog can be compiled
+    # in it. This has the following major functions:
+    # - Create the temporary directory that will serve as the puppet configuration directory
+    # - Register a handler to remove the temporary directory upon exit
+    # - Install needed configuration files within the directory (e.g. puppetdb.conf)
+    # - Install the facts into the directory
+    # - Install 'environments/production' which is a symlink to the checkout of the puppet code
+    class BuildDir
+      # Allow the path to the temporary directory to be read
+      attr_reader :tempdir, :enc, :fact_file
+
+      # Constructor
+      # Options for constructor:
+      # :puppetdb_url [String] PuppetDB Server URLs
+      # :puppetdb_server_url_timeout [Fixnum] Timeout (seconds) for puppetdb.conf
+      # :facts [OctocatalogDiff::Facts] Facts object
+      # :fact_file [String] File from which to read facts
+      # :node [String] Node name
+      # :basedir [String] Directory containing puppet code
+      # :enc [String] ENC script file (can be relative or absolute path)
+      # :pe_enc_url [String] ENC URL (for Puppet Enterprise node classification service)
+      # :hiera_config [String] hiera configuration file (relative to base directory)
+      # :hiera_path_strip [String] string to strip off the beginning of :datadir
+      # :puppetdb_ssl_ca [String] Path to SSL CA certificate
+      # :puppetdb_ssl_client_key [String] String representation of SSL client key
+      # :puppetdb_ssl_client_cert [String] String representation of SSL client certificate
+      # :puppetdb_ssl_client_password [String] Password to unlock SSL private key
+      # @param options [Hash] Options for class; see above description
+      def initialize(options = {}, logger = nil)
+        @options = options.dup
+        @tempdir = Dir.mktmpdir
+        at_exit { FileUtils.rm_rf(@tempdir) if File.directory?(@tempdir) }
+
+        @factdir = nil
+        @enc = nil
+        @fact_file = nil
+        @node = options[:node]
+
+        create_structure
+        install_directory_symlink(logger, options[:basedir])
+
+        # These configurations are optional. Don't call the methods if parameters are nil.
+        unless options[:puppetdb_url].nil?
+          install_puppetdb_conf(logger, options[:puppetdb_url], options[:puppetdb_server_url_timeout])
+          install_routes_yaml(logger)
+        end
+        unless options[:hiera_config].nil?
+          install_hiera_config(logger, options[:hiera_config], options[:hiera_path_strip])
+        end
+        @fact_file = install_fact_file(logger, options) unless options.fetch(:facts_terminus, 'yaml') != 'yaml'
+        @enc = install_enc(logger) unless options[:enc].nil? && options[:pe_enc_url].nil?
+        install_ssl(logger, options) if options[:puppetdb_ssl_ca] || options[:puppetdb_ssl_client_cert]
+      end
+
+      # Create common structure
+      def create_structure
+        %w(environments facts var var/ssl var/yaml var/yaml/facts).each do |dir|
+          Dir.mkdir(File.join(@tempdir, dir))
+          FileUtils.chmod 0o755, File.join(@tempdir, dir)
+        end
+      end
+
+      # Install puppetdb.conf file in temporary directory
+      # @param server_urls [String] String for server_urls in puppetdb.conf
+      # @param server_url_timeout [Fixnum] Value for server_url_timeout in puppetdb.conf
+      def install_puppetdb_conf(logger, server_urls, server_url_timeout = 30)
+        unless server_urls.is_a?(String)
+          raise ArgumentError, "server_urls must be a string, got a: #{server_urls.class}"
+        end
+
+        server_url_timeout ||= 30 # If called with nil argument, supply default
+        unless server_url_timeout.is_a?(Fixnum)
+          raise ArgumentError, "server_url_timeout must be a fixnum, got a: #{server_url_timeout.class}"
+        end
+
+        puppetdb_conf = File.join(@tempdir, 'puppetdb.conf')
+        File.open(puppetdb_conf, 'w') do |f|
+          f.write "[main]\n"
+          f.write "server_urls = #{server_urls}\n"
+          f.write "server_url_timeout = #{server_url_timeout}\n"
+        end
+        logger.debug("Installed puppetdb.conf file at #{puppetdb_conf}")
+      end
+
+      # Install routes.yaml file in temporary directory
+      # No parameters or return - thus just writes a file (and notes it to debugging log)
+      # Note: catalog cache => json avoids sending the compiled catalog to PuppetDB
+      # even if storeconfigs is enabled.
+      def install_routes_yaml(logger)
+        routes_yaml = File.join(@tempdir, 'routes.yaml')
+        routes_hash = {
+          'master' => {
+            'facts' => {
+              'terminus' => 'puppetdb',
+              'cache' => 'yaml'
+            },
+            'catalog' => {
+              'cache' => 'json'
+            }
+          }
+        }
+        File.open(routes_yaml, 'w') { |f| f.write(routes_hash.to_yaml) }
+        logger.debug("Installed routes.yaml file at #{routes_yaml}")
+      end
+
+      # Install the fact file in temporary directory
+      # @param options [Hash] Options
+      def install_fact_file(logger, options)
+        unless options[:facts_terminus].nil? || options[:facts_terminus] == 'yaml'
+          raise ArgumentError, "Called install_fact_file but :facts_terminus = #{options[:facts_terminus]}"
+        end
+        unless options[:node].is_a?(String) && !options[:node].empty?
+          raise ArgumentError, 'Called install_fact_file without node, or with an empty node'
+        end
+
+        facts = if options[:fact_file]
+          raise Errno::ENOENT, "Fact file #{options[:fact_file]} does not exist" unless File.file?(options[:fact_file])
+          fact_file_opts = { fact_file_string: File.read(options[:fact_file]) }
+          fact_file_opts[:backend] = Regexp.last_match(1).to_sym if options[:fact_file] =~ /.*\.(\w+)$/
+          OctocatalogDiff::Facts.new(fact_file_opts)
+        elsif options[:facts].is_a?(OctocatalogDiff::Facts)
+          options[:facts].dup
+        else
+          raise ArgumentError, 'No facts passed to "install_fact_file" method'
+        end
+
+        if options[:fact_override].is_a?(Array)
+          options[:fact_override].each do |override|
+            old_value = facts.fact(override.key)
+            facts.override(override.key, override.value)
+            logger.debug("Override #{override.key} from #{old_value.inspect} to #{override.value.inspect}")
+          end
+        end
+
+        fact_file_out = File.join(@tempdir, 'var', 'yaml', 'facts', "#{options[:node]}.yaml")
+        File.open(fact_file_out, 'w') { |f| f.write(facts.facts_to_yaml(options[:node])) }
+        logger.debug("Installed fact file at #{fact_file_out}")
+        fact_file_out
+      end
+
+      # Install symbolic link to puppet environment
+      # @param dir [String] Directory to link to
+      def install_directory_symlink(logger, dir)
+        raise ArgumentError, "Called install_directory_symlink with #{dir.class} argument" unless dir.is_a?(String)
+        raise Errno::ENOENT, "Specified directory #{dir} doesn't exist" unless File.directory?(dir)
+
+        environment_symlink = File.join(@tempdir, 'environments', 'production')
+        FileUtils.rm_f environment_symlink if File.exist?(environment_symlink)
+        FileUtils.symlink dir, environment_symlink
+        logger.debug("Symlinked #{environment_symlink} -> #{dir}")
+      end
+
+      # Install ENC
+      # @param enc [String] Path to ENC script, relative to checkout
+      def install_enc(logger)
+        raise ArgumentError, 'A node must be specified when using an ENC' unless @node.is_a?(String)
+        enc_obj = OctocatalogDiff::CatalogUtil::ENC.new(@options.merge(tempdir: @tempdir))
+        raise "Failed ENC: #{enc_obj.error_message}" if enc_obj.error_message
+
+        enc_path = File.join(@tempdir, 'enc.sh')
+        File.open(enc_path, 'w') do |f|
+          f.write "#!/bin/sh\n"
+          f.write "cat <<-EOF\n"
+          f.write enc_obj.content
+          f.write "\nEOF\n"
+        end
+        FileUtils.chmod 0o755, enc_path
+
+        logger.debug("Installed ENC to echo content, #{enc_obj.content.length} bytes")
+        enc_path
+      end
+
+      # Install hiera config file
+      # @param hiera_config [String] Path to file, relative to checkout
+      # @param hiera_path_strip [String] Prefix to strip off when munging file
+      def install_hiera_config(logger, hiera_config, hiera_path_strip)
+        # Validate hiera config file
+        unless hiera_config.is_a?(String)
+          raise ArgumentError, "Called install_hiera_config with a #{hiera_config.class} argument"
+        end
+        file_src = if hiera_config.start_with? '/'
+          hiera_config
+        elsif hiera_config =~ %r{^environments/production/}
+          File.join(@tempdir, hiera_config)
+        else
+          File.join(@tempdir, 'environments', 'production', hiera_config)
+        end
+        raise Errno::ENOENT, "hiera.yaml (#{file_src}) wasn't found" unless File.file?(file_src)
+
+        # Munge datadir in hiera config file
+        obj = YAML.load_file(file_src)
+        %w(yaml json).each do |key|
+          next unless obj.key?(key.to_sym)
+          next if obj[key.to_sym][:datadir].nil?
+          unless hiera_path_strip.nil?
+            rexp1 = Regexp.new('^' + hiera_path_strip)
+            obj[key.to_sym][:datadir].sub!(rexp1, @tempdir)
+          end
+          rexp2 = Regexp.new('%{(::)?environment}')
+          obj[key.to_sym][:datadir].sub!(rexp2, 'production')
+        end
+
+        # Write properly formatted hiera config file into temporary directory
+        File.open(File.join(@tempdir, 'hiera.yaml'), 'w') { |f| f.write(obj.to_yaml.gsub('!ruby/sym ', ':')) }
+        logger.debug("Installed hiera.yaml from #{file_src} to #{File.join(@tempdir, 'hiera.yaml')}")
+      end
+
+      # Install SSL certificate authority certificate, client key, and client certificate into the
+      # expected locations within Puppet's SSL directory. Note that if the client key has a password,
+      # this will write the key (without password) onto disk, because Puppet doesn't support unlocking
+      # the private key.
+      # @param logger [Logger] Logger object
+      # @param options [Hash] Options hash
+      def install_ssl(logger, options)
+        return unless options[:puppetdb_ssl_client_cert] || options[:puppetdb_ssl_client_key] || options[:puppetdb_ssl_ca]
+
+        # Create directory structure expected by Puppet
+        %w(var/ssl/certs var/ssl/private var/ssl/private_keys).each do |dir|
+          Dir.mkdir(File.join(@tempdir, dir))
+          FileUtils.chmod 0o700, File.join(@tempdir, dir)
+        end
+
+        # SSL client auth requested?
+        if options[:puppetdb_ssl_client_cert] || options[:puppetdb_ssl_client_key]
+          raise ArgumentError, '--puppetdb-ssl-ca must be provided for client auth' unless options[:puppetdb_ssl_ca]
+          raise ArgumentError, '--puppetdb-ssl-client-cert must be provided' unless options[:puppetdb_ssl_client_cert]
+          raise ArgumentError, '--puppetdb-ssl-client-key must be provided' unless options[:puppetdb_ssl_client_key]
+          install_ssl_client(logger, options)
+        end
+
+        # SSL CA provided?
+        install_ssl_ca(logger, options) if options[:puppetdb_ssl_ca]
+      end
+
+      private
+
+      # Install SSL certificate authority certificate
+      # @param logger [Logger] Logger object
+      # @param options [Hash] Options hash
+      def install_ssl_ca(logger, options)
+        ca_file = options[:puppetdb_ssl_ca]
+        raise Errno::ENOENT, 'SSL CA file does not exist' unless File.file?(ca_file)
+        ca_content = File.read(ca_file)
+        ca_outfile = File.join(@tempdir, 'var', 'ssl', 'certs', 'ca.pem')
+        File.open(ca_outfile, 'w') { |f| f.write(ca_content) }
+        logger.debug "Installed CA certificate in #{ca_outfile}"
+      end
+
+      # Install SSL keypair for client certificate authentication
+      # @param logger [Logger] Logger object
+      # @param options [Hash] Options hash
+      def install_ssl_client(logger, options)
+        # Since Puppet always looks for the key and cert in a file named after the hostname, determine the
+        # hostname here for the purposes of naming the files.
+        require 'socket'
+        host = Socket.gethostname
+        install_ssl_client_cert(logger, host, options[:puppetdb_ssl_client_cert])
+        install_ssl_client_key(logger, host, options[:puppetdb_ssl_client_key])
+        install_ssl_client_password(logger, options[:puppetdb_ssl_client_password])
+      end
+
+      def install_ssl_client_cert(logger, host, content)
+        cert_outfile = File.join(@tempdir, 'var', 'ssl', 'certs', "#{host}.pem")
+        File.open(cert_outfile, 'w') { |f| f.write(content) }
+        logger.debug "Installed SSL client certificate in #{cert_outfile}"
+      end
+
+      def install_ssl_client_key(logger, host, content)
+        key_outfile = File.join(@tempdir, 'var', 'ssl', 'private_keys', "#{host}.pem")
+        File.open(key_outfile, 'w') { |f| f.write(content) }
+        logger.debug "Installed SSL client key in #{key_outfile}"
+      end
+
+      def install_ssl_client_password(logger, password)
+        return unless password
+        password_outfile = File.join(@tempdir, 'var', 'ssl', 'private', 'password')
+        File.open(password_outfile, 'w') { |f| f.write(password) }
+        logger.debug "Installed SSL client key password in #{password_outfile}"
+      end
+    end
+  end
+end

data/lib/octocatalog-diff/catalog-util/cached_master_directory.rb

@@ -0,0 +1,169 @@
+require_relative 'bootstrap'
+require_relative 'git'
+require_relative '../catalog-diff/cli/catalogs'
+
+require 'fileutils'
+
+module OctocatalogDiff
+  module CatalogUtil
+    # Handle the bootstrapped and cached checkout of [master branch]. This is an optimization
+    # targeted at local development environments, since a frequent pattern is "run a catalog-diff
+    # between what I have here, and master."
+    #
+    # Please note that there could be a race condition here if this code was run in parallel (i.e.,
+    # the cached master directory is blown away and re-created when a Puppet catalog compile is in
+    # progress). Do not introduce this code to an environment where catalog-diff may be running in
+    # parallel unless you have accounted for this (or are willing to tolerate any errors).
+    class CachedMasterDirectory
+      # Set default branch. Can be overridden by options[:master_cache_branch].
+      DEFAULT_MASTER_BRANCH = 'origin/master'.freeze
+
+      # Get the master branch based on supplied options.
+      # @param options [Hash] Options hash
+      # @return [String] Master branch configured (defaults to DEFAULT_MASTER_BRANCH)
+      def self.master_branch(options = {})
+        options.fetch(:master_cache_branch, DEFAULT_MASTER_BRANCH)
+      end
+
+      # This is the entry point from the CLI (or anywhere else). Takes options hash and logger
+      # as arguments, sets up the cached master directory if required, and adjusts options hash
+      # accordingly. Returns nothing; raises exceptions for failures.
+      # @param options [Hash] Options hash from CLI
+      # @param logger [Logger] Logger object
+      def self.run(options, logger)
+        # If nobody asked for this, don't do anything
+        return if options[:cached_master_dir].nil?
+
+        # Verify that parameters are set up correctly and that at least one of the to-branch and
+        # from-branch is [master branch]. If not, it's not worthwhile to do any of the remaining
+        # tasks in this section.
+        return unless cached_master_applicable_to_this_run?(options)
+
+        # This directory was supposed to be created as part of the option setup. Make sure it exists
+        # as a sanity check.
+        Dir.mkdir options[:cached_master_dir], 0o755 unless Dir.exist?(options[:cached_master_dir])
+
+        # Determine if it's necessary to check out the git repo to the directory in question.
+        git_repo_checkout_bootstrap(options, logger) unless git_repo_checkout_current?(options, logger)
+
+        # Under --bootstrap-then-exit, don't adjust the options. (Otherwise code runs twice.)
+        return if options[:bootstrap_then_exit]
+
+        # Re-point any options to the cached directory.
+        %w(from to).each do |x|
+          next unless options["#{x}_env".to_sym] == master_branch(options)
+          logger.debug "Setting --bootstrapped-#{x}-dir=#{options[:cached_master_dir]}"
+          options["bootstrapped_#{x}_dir".to_sym] = options[:cached_master_dir]
+        end
+
+        # If a catalog was already compiled for the requested node, point to it directly to avoid
+        # re-compiling said catalog.
+        unless options[:node].nil?
+          catalog_path = File.join(options[:cached_master_dir], '.catalogs', options[:node] + '.json')
+          if File.file?(catalog_path)
+            %w(from to).each do |x|
+              next unless options["#{x}_env".to_sym] == master_branch(options)
+              next unless options["#{x}_catalog".to_sym].nil?
+              logger.debug "Setting --#{x}-catalog=#{catalog_path}"
+              options["#{x}_catalog".to_sym] = catalog_path
+              options["#{x}_catalog_compilation_dir".to_sym] = options[:cached_master_dir]
+            end
+          end
+        end
+      end
+
+      # Determine if the cached master directory functionality is needed at all.
+      # @param options [Hash] Options hash from CLI
+      # @return [Boolean] whether to-branch and/or from-branch == [master branch]
+      def self.cached_master_applicable_to_this_run?(options)
+        return false if options[:cached_master_dir].nil?
+        target_branch = master_branch(options)
+        options.fetch(:from_env, '') == target_branch || options.fetch(:to_env, '') == target_branch
+      end
+
+      # Determine whether git repo checkout in the directory is current.
+      # To consider here: (a) is anything at all checked out; (b) is the correct SHA checked out?
+      # @param options [Hash] Options hash from CLI
+      # @param logger [Logger] Logger object
+      # @return [Boolean] whether git repo checkout in the directory is current
+      def self.git_repo_checkout_current?(options, logger)
+        shafile = File.join(options[:cached_master_dir], '.catalog-diff-master.sha')
+        return false unless File.file?(shafile)
+        bootstrapped_sha = File.read(shafile)
+        target_branch = master_branch(options)
+        branch_sha_opts = options.merge(branch: target_branch)
+        current_master_sha = OctocatalogDiff::CatalogUtil::Git.branch_sha(branch_sha_opts)
+        logger.debug "Cached master dir: bootstrapped=#{bootstrapped_sha}; current=#{current_master_sha}"
+        bootstrapped_sha.strip == current_master_sha.strip
+      end
+
+      # Check out [master branch] -> cached directory and bootstrap it
+      # @param options [Hash] Options hash from CLI
+      # @param logger [Logger] Logger object
+      def self.git_repo_checkout_bootstrap(options, logger)
+        # This directory isn't current so kill it
+        # Too dangerous if someone slips up on the command line:
+        # FileUtils.rm_rf options[:cached_master_dir] if Dir.exist?(options[:cached_master_dir])
+        shafile = File.join(options[:cached_master_dir], '.catalog-diff-master.sha')
+        target_branch = master_branch(options)
+        branch_sha_opts = options.merge(branch: target_branch)
+        current_master_sha = OctocatalogDiff::CatalogUtil::Git.branch_sha(branch_sha_opts)
+
+        if Dir.exist?(options[:cached_master_dir]) && File.exist?(shafile)
+          # If :cached_master_dir was set in a known-safe manner, safe_to_delete_cached_master_dir will
+          # allow the cleanup to take place automatically.
+          if options.fetch(:safe_to_delete_cached_master_dir, false) == options[:cached_master_dir]
+            FileUtils.rm_rf options[:cached_master_dir] if Dir.exist?(options[:cached_master_dir])
+          else
+            message = "To proceed, #{options[:cached_master_dir]} needs to be deleted, so it can be re-created."\
+                      " I'm not yet deemed safe enough to do this for you though. Please jump out to a shell and run"\
+                      " 'rm -rf #{options[:cached_master_dir]}' and then come back and try again. (Existing SHA:"\
+                      " #{File.read(shafile).strip}; current master SHA: #{current_master_sha})"
+            raise Errno::EEXIST, message
+          end
+        end
+
+        # This logic is similar to 'bootstrap-then-exit' (without the exit part). The
+        # bootstrap_then_exit handles creating this directory.
+        fake_options = options.dup
+        fake_options[:bootstrap_then_exit] = true
+        fake_options[:bootstrapped_from_dir] = options[:cached_master_dir]
+        fake_options[:bootstrapped_to_dir] = nil
+        fake_options[:from_env] = master_branch(options)
+
+        logger.debug 'Begin bootstrap cached master directory'
+        catalogs_obj = OctocatalogDiff::CatalogDiff::Cli::Catalogs.new(fake_options, logger)
+        catalogs_obj.bootstrap_then_exit
+        logger.debug 'Success bootstrap cached master directory'
+
+        # Write the SHA of [master branch], so git_repo_checkout_current? works next time
+        File.open(shafile, 'w') { |f| f.write(current_master_sha) }
+        logger.debug "Cached master directory bootstrapped to #{current_master_sha}"
+
+        # Create <dir>/.catalogs, to save any catalogs compiled along the way
+        catalog_dir = File.join(options[:cached_master_dir], '.catalogs')
+        Dir.mkdir catalog_dir unless File.directory?(catalog_dir)
+      end
+
+      # Save a compiled catalog in the cached master directory. Does not die fatally if
+      # catalog is invalid or this isn't set up or whatever else.
+      # @param node [String] node name
+      # @param dir [String] cached master directory
+      # @param catalog [OctocatalogDiff::Catalog] Catalog object
+      # @return [Boolean] true if catalog was saved, false if not
+      def self.save_catalog_in_cache_dir(node, dir, catalog)
+        return false if dir.nil? || node.nil?
+        return false if catalog.nil? || !catalog.valid?
+
+        path = File.join(dir, '.catalogs')
+        return false unless Dir.exist?(path)
+
+        filepath = File.join(path, node + '.json')
+        return false if File.file?(filepath)
+
+        File.open(filepath, 'w') { |f| f.write(catalog.catalog_json) }
+        true
+      end
+    end
+  end
+end