bolt 2.23.0 → 2.27.0

data/lib/bolt/outputter/json.rb

@@ -83,6 +83,17 @@ module Bolt
         @stream.puts result.to_json
       end
 
+      def print_topics(topics)
+        print_table('topics' => topics)
+      end
+
+      def print_guide(guide, topic)
+        @stream.puts({
+          'topic' => topic,
+          'guide' => guide
+        }.to_json)
+      end
+
       def print_puppetfile_result(success, puppetfile, moduledir)
         @stream.puts({ "success": success,
                        "puppetfile": puppetfile,

data/lib/bolt/outputter/logger.rb

@@ -7,7 +7,7 @@ module Bolt
     class Logger < Bolt::Outputter
       def initialize(verbose, trace)
         super(false, verbose, trace)
-        @logger = Logging.logger[self]
+        @logger = Bolt::Logger.logger(self)
       end
 
       def handle_event(event)
@@ -40,13 +40,13 @@ module Bolt
 
       def log_plan_start(event)
         plan = event[:plan]
-        @logger.notice("Starting: plan #{plan}")
+        @logger.info("Starting: plan #{plan}")
       end
 
       def log_plan_finish(event)
         plan = event[:plan]
         duration = event[:duration]
-        @logger.notice("Finished: plan #{plan} in #{duration.round(2)} sec")
+        @logger.info("Finished: plan #{plan} in #{duration.round(2)} sec")
       end
     end
   end

data/lib/bolt/outputter/rainbow.rb

@@ -86,6 +86,21 @@ module Bolt
         total_msg << " in #{duration_to_string(elapsed_time)}" unless elapsed_time.nil?
         @stream.puts colorize(:rainbow, total_msg)
       end
+
+      def print_guide(guide, _topic)
+        @stream.puts colorize(:rainbow, guide)
+      end
+
+      def print_topics(topics)
+        content  = String.new("Available topics are:\n")
+        content += topics.join("\n")
+        content += "\n\nUse `bolt guide <topic>` to view a specific guide."
+        @stream.puts colorize(:rainbow, content)
+      end
+
+      def print_message(message)
+        @stream.puts colorize(:rainbow, message)
+      end
     end
   end
 end

data/lib/bolt/pal.rb

@@ -65,9 +65,9 @@ module Bolt
       @resource_types = resource_types
       @project = project
 
-      @logger = Logging.logger[self]
+      @logger = Bolt::Logger.logger(self)
       if modulepath && !modulepath.empty?
-        @logger.info("Loading modules from #{@modulepath.join(File::PATH_SEPARATOR)}")
+        @logger.debug("Loading modules from #{@modulepath.join(File::PATH_SEPARATOR)}")
       end
 
       @loaded = false
@@ -76,7 +76,7 @@ module Bolt
     # Puppet logging is global so this is class method to avoid confusion
     def self.configure_logging
       Puppet::Util::Log.destinations.clear
-      Puppet::Util::Log.newdestination(Logging.logger['Puppet'])
+      Puppet::Util::Log.newdestination(Bolt::Logger.logger('Puppet'))
       # Defer all log level decisions to the Logging library by telling Puppet
       # to log everything
       Puppet.settings[:log_level] = 'debug'
@@ -141,6 +141,19 @@ module Bolt
       end
     end
 
+    def detect_project_conflict(project, environment)
+      return unless project && project.load_as_module?
+      # The environment modulepath has stripped out non-existent directories,
+      # so we don't need to check for them
+      modules = environment.modulepath.flat_map do |path|
+        Dir.children(path).select { |name| Puppet::Module.is_module_directory?(name, path) }
+      end
+      if modules.include?(project.name)
+        Bolt::Logger.warn_once("project shadows module",
+                               "The project '#{project.name}' shadows an existing module of the same name")
+      end
+    end
+
     # Runs a block in a PAL script compiler configured for Bolt.  Catches
     # exceptions thrown by the block and re-raises them ensuring they are
     # Bolt::Errors since the script compiler block will squash all exceptions.
@@ -149,15 +162,13 @@ module Bolt
       setup
       r = Puppet::Pal.in_tmp_environment('bolt', modulepath: @modulepath, facts: {}) do |pal|
         # Only load the project if it a) exists, b) has a name it can be loaded with
-        bolt_project = @project if @project&.name
-        # Puppet currently won't receive the project unless it is a named project. Since
-        # the download_file plan function needs access to the project path, add it to the
-        # context.
-        bolt_project_data = @project
-        Puppet.override(bolt_project: bolt_project,
-                        bolt_project_data: bolt_project_data,
+        Puppet.override(bolt_project: @project,
                         yaml_plan_instantiator: Bolt::PAL::YamlPlan::Loader) do
-          pal.with_script_compiler do |compiler|
+          # Because this has the side effect of loading and caching the list
+          # of modules, it must happen *after* we have overridden
+          # bolt_project or the project will be ignored
+          detect_project_conflict(@project, Puppet.lookup(:environments).get('bolt'))
+          pal.with_script_compiler(set_local_facts: false) do |compiler|
             alias_types(compiler)
             register_resource_types(Puppet.lookup(:loaders)) if @resource_types
             begin
@@ -409,7 +420,7 @@ module Bolt
                      end
           params[name] = { 'type' => type_str }
           params[name]['sensitive'] = param.type_expr.instance_of?(Puppet::Pops::Types::PSensitiveType)
-          params[name]['default_value'] = param.value
+          params[name]['default_value'] = param.value unless param.value.nil?
           params[name]['description'] = param.description if param.description
         end
         {

data/lib/bolt/pal/yaml_plan/evaluator.rb

@@ -7,7 +7,7 @@ module Bolt
     class YamlPlan
       class Evaluator
         def initialize(analytics = Bolt::Analytics::NoopClient.new)
-          @logger = Logging.logger[self]
+          @logger = Bolt::Logger.logger(self)
           @analytics = analytics
           @evaluator = Puppet::Pops::Parser::EvaluatingParser.new
         end

data/lib/bolt/pal/yaml_plan/transpiler.rb

@@ -21,10 +21,18 @@ module Bolt
           validate_path
 
           plan_object = parse_plan
+          param_descriptions = plan_object.parameters.map do |param|
+            str = String.new("# @param #{param.name}")
+            str << " #{param.description}" if param.description
+            str
+          end.join("\n")
 
-          plan_string = String.new("# WARNING: This is an autogenerated plan. " \
-                                   "It may not behave as expected.\n" \
-                                   "plan #{plan_object.name}(")
+          plan_string = String.new('')
+          plan_string << "# #{plan_object.description}\n" if plan_object.description
+          plan_string << "# WARNING: This is an autogenerated plan. It may not behave as expected.\n"
+          plan_string << "#{param_descriptions}\n" unless param_descriptions.empty?
+
+          plan_string << "plan #{plan_object.name}("
           # Parameters are Bolt::PAL::YamlPlan::Parameter
           plan_object.parameters&.each_with_index do |param, i|
             plan_string << param.transpile

data/lib/bolt/plugin/puppetdb.rb

@@ -19,7 +19,7 @@ module Bolt
       def initialize(config:, context:)
         pdb_config = Bolt::PuppetDB::Config.load_config(config, context.boltdir)
         @puppetdb_client = Bolt::PuppetDB::Client.new(pdb_config)
-        @logger = Logging.logger[self]
+        @logger = Bolt::Logger.logger(self)
       end
 
       def name

data/lib/bolt/project.rb

@@ -17,37 +17,53 @@ module Bolt
     }.freeze
 
     attr_reader :path, :data, :config_file, :inventory_file, :modulepath, :hiera_config,
-                :puppetfile, :rerunfile, :type, :resource_types, :warnings, :project_file,
+                :puppetfile, :rerunfile, :type, :resource_types, :logs, :project_file,
                 :deprecations, :downloads, :plans_path
 
-    def self.default_project
-      create_project(File.expand_path(File.join('~', '.puppetlabs', 'bolt')), 'user')
+    def self.default_project(logs = [])
+      create_project(File.expand_path(File.join('~', '.puppetlabs', 'bolt')), 'user', logs)
     # If homedir isn't defined use the system config path
     rescue ArgumentError
-      create_project(Bolt::Config.system_path, 'system')
+      create_project(Bolt::Config.system_path, 'system', logs)
     end
 
     # Search recursively up the directory hierarchy for the Project. Look for a
     # directory called Boltdir or a file called bolt.yaml (for a control repo
     # type Project). Otherwise, repeat the check on each directory up the
     # hierarchy, falling back to the default if we reach the root.
-    def self.find_boltdir(dir)
+    def self.find_boltdir(dir, logs = [])
       dir = Pathname.new(dir)
 
       if (dir + BOLTDIR_NAME).directory?
-        create_project(dir + BOLTDIR_NAME, 'embedded')
+        create_project(dir + BOLTDIR_NAME, 'embedded', logs)
       elsif (dir + 'bolt.yaml').file? || (dir + 'bolt-project.yaml').file?
-        create_project(dir, 'local')
+        create_project(dir, 'local', logs)
       elsif dir.root?
-        default_project
+        default_project(logs)
       else
-        find_boltdir(dir.parent)
+        logs << { debug: "Did not detect Boltdir, bolt.yaml, or bolt-project.yaml at '#{dir}'. "\
+                  "This directory won't be loaded as a project." }
+        find_boltdir(dir.parent, logs)
       end
     end
 
-    def self.create_project(path, type = 'option')
+    def self.create_project(path, type = 'option', logs = [])
       fullpath = Pathname.new(path).expand_path
 
+      if type == 'user'
+        begin
+          # This is already expanded if the type is user
+          FileUtils.mkdir_p(path)
+        rescue StandardError
+          logs << { warn: "Could not create default project at #{path}. Continuing without a writeable project. "\
+                    "Log and rerun files will not be written." }
+        end
+      end
+
+      if type == 'option' && !File.directory?(path)
+        raise Bolt::Error.new("Could not find project at #{path}", "bolt/project-error")
+      end
+
       if !Bolt::Util.windows? && type != 'environment' && fullpath.world_writable?
         raise Bolt::Error.new(
           "Project directory '#{fullpath}' is world-writable which poses a security risk. Set "\
@@ -58,15 +74,18 @@ module Bolt
 
       project_file = File.join(fullpath, 'bolt-project.yaml')
       data = Bolt::Util.read_optional_yaml_hash(File.expand_path(project_file), 'project')
-      new(data, path, type)
+      default = type =~ /user|system/ ? 'default ' : ''
+      exist = File.exist?(File.expand_path(project_file))
+      logs << { info: "Loaded #{default}project from '#{fullpath}'" } if exist
+      new(data, path, type, logs)
     end
 
-    def initialize(raw_data, path, type = 'option')
+    def initialize(raw_data, path, type = 'option', logs = [])
       @path = Pathname.new(path).expand_path
 
       @project_file = @path + 'bolt-project.yaml'
 
-      @warnings = []
+      @logs = logs
       @deprecations = []
       if (@path + 'bolt.yaml').file? && project_file?
         msg = "Project-level configuration in bolt.yaml is deprecated if using bolt-project.yaml. "\
@@ -88,7 +107,7 @@ module Bolt
       tc = Bolt::Config::INVENTORY_OPTIONS.keys & raw_data.keys
       if tc.any?
         msg = "Transport configuration isn't supported in bolt-project.yaml. Ignoring keys #{tc}"
-        @warnings << { msg: msg }
+        @logs << { warn: msg }
       end
 
       @data = raw_data.reject { |k, _| Bolt::Config::INVENTORY_OPTIONS.include?(k) }
@@ -98,7 +117,7 @@ module Bolt
       @config_file = if (Bolt::Config::BOLT_OPTIONS & @data.keys).any?
                        if (@path + 'bolt.yaml').file?
                          msg = "bolt-project.yaml contains valid config keys, bolt.yaml will be ignored"
-                         @warnings << { msg: msg }
+                         @logs << { warn: msg }
                        end
                        @project_file
                      else
@@ -114,7 +133,9 @@ module Bolt
     # This API is used to prepend the project as a module to Puppet's internal
     # module_references list. CHANGE AT YOUR OWN RISK
     def to_h
-      { path: @path.to_s, name: name }
+      { path: @path.to_s,
+        name: name,
+        load_as_module?: load_as_module? }
     end
 
     def eql?(other)
@@ -126,6 +147,10 @@ module Bolt
       @project_file.file?
     end
 
+    def load_as_module?
+      !name.nil?
+    end
+
     def name
       @data['name']
     end
@@ -138,6 +163,10 @@ module Bolt
       @data['plans']
     end
 
+    def modules
+      @data['modules']
+    end
+
     def validate
       if name
         if name !~ Bolt::Module::MODULE_NAME_REGEX
@@ -151,7 +180,7 @@ module Bolt
         end
       else
         message = "No project name is specified in bolt-project.yaml. Project-level content will not be available."
-        @warnings << { msg: message }
+        @logs << { warn: message }
       end
 
       %w[tasks plans].each do |conf|
@@ -159,6 +188,23 @@ module Bolt
           raise Bolt::ValidationError, "'#{conf}' in bolt-project.yaml must be an array"
         end
       end
+
+      if @data['modules']
+        unless @data['modules'].is_a?(Array)
+          raise Bolt::ValidationError, "'modules' in bolt-project.yaml must be an array"
+        end
+
+        @data['modules'].each do |mod|
+          next if mod.is_a?(Hash)
+          raise Bolt::ValidationError, "Module declaration #{mod.inspect} must be a hash"
+        end
+
+        unknown_keys = data['modules'].flat_map(&:keys).uniq - ['name']
+        if unknown_keys.any?
+          @logs << { warn: "Module declarations in bolt-project.yaml only support a name key. Ignoring "\
+                           "unsupported keys: #{unknown_keys.join(', ')}." }
+        end
+      end
     end
 
     def check_deprecated_file

data/lib/bolt/project_migrate.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Bolt
+  class ProjectMigrate
+    attr_reader :path, :project_file, :backup_dir, :outputter, :inventory_file, :config_file
+
+    # This init mostly makes testing easier
+    def initialize(path, outputter, configured_inventory = nil)
+      @path = Pathname.new(path).expand_path
+      @project_file = @path + 'bolt-project.yaml'
+      @config_file = @path + 'bolt.yaml'
+      @backup_dir = @path + '.bolt-bak'
+      @inventory_file = configured_inventory || @path + 'inventory.yaml'
+      @outputter = outputter
+    end
+
+    def migrate_project
+      inv_ok = inventory_1_to_2(inventory_file, outputter) if inventory_file.file?
+      config_ok = bolt_yaml_to_bolt_project(inventory_file, outputter)
+      inv_ok && config_ok ? 0 : 1
+    end
+
+    # This could be made public and used elsewhere if the need arises
+    private def backup_file(origin_path)
+      unless File.exist?(origin_path)
+        outputter.print_message "Could not find file #{origin_path}, skipping backup."
+        return
+      end
+
+      date = Time.new.strftime("%Y%m%d_%H%M%S%L")
+      FileUtils.mkdir_p(backup_dir)
+
+      filename = File.basename(origin_path)
+      backup_path = File.join(backup_dir, "#{filename}.#{date}.bak")
+
+      outputter.print_message "Backing up #{filename} from #{origin_path} to #{backup_path}"
+
+      begin
+        FileUtils.cp(origin_path, backup_path)
+      rescue StandardError => e
+        raise Bolt::FileError.new("#{e.message}; unable to create backup of #{filename}.", origin_path)
+      end
+    end
+
+    private def bolt_yaml_to_bolt_project(inventory_file, outputter)
+      # If bolt-project.yaml already exists
+      if project_file.file?
+        outputter.print_message "bolt-project.yaml already exists in Bolt "\
+          "project at #{path}. Skipping project file update."
+
+      # If bolt.yaml doesn't exist
+      elsif !config_file.file?
+        outputter.print_message "Could not find bolt.yaml in project at "\
+          "#{path}. Skipping project file update."
+
+      else
+        config_data = Bolt::Util.read_optional_yaml_hash(config_file, 'config')
+        transport_data, project_data = config_data.partition do |k, _|
+          Bolt::Config::INVENTORY_OPTIONS.keys.include?(k)
+        end.map(&:to_h)
+
+        if transport_data.any?
+          if File.exist?(inventory_file)
+            inventory_data = Bolt::Util.read_yaml_hash(inventory_file, 'inventory')
+            merged = Bolt::Util.deep_merge(transport_data, inventory_data['config'] || {})
+            inventory_data['config'] = merged
+            backup_file(inventory_file)
+          else
+            FileUtils.touch(inventory_file)
+            inventory_data = { 'config' => transport_data }
+          end
+
+          backup_file(config_file)
+
+          begin
+            outputter.print_message "Moving transportation configuration options "\
+              "'#{transport_data.keys.join(', ')}' from bolt.yaml to inventory.yaml"
+            File.write(inventory_file, inventory_data.to_yaml)
+            File.write(config_file, project_data.to_yaml)
+          rescue StandardError => e
+            raise Bolt::FileError.new("#{e.message}; unable to write inventory.", inventory_file)
+          end
+        end
+
+        outputter.print_message "Renaming bolt.yaml to bolt-project.yaml"
+        FileUtils.mv(config_file, project_file)
+        outputter.print_message "Successfully updated project. Please add a "\
+          "'name' key to bolt-project.yaml to use project-level tasks and plans. "\
+          "Learn more about projects by running 'bolt guide project'."
+        # If nothing errored, this succeeded
+        true
+      end
+    end
+
+    private def inventory_1_to_2(inventory_file, outputter)
+      data = Bolt::Util.read_yaml_hash(inventory_file, 'inventory')
+      data.delete('version') if data['version'] != 2
+      migrated = migrate_group(data)
+
+      ok = if migrated
+             backup_file(inventory_file)
+             File.write(inventory_file, data.to_yaml)
+           end
+
+      result = if migrated && ok
+                 "Successfully migrated Bolt inventory to the latest version."
+               elsif !migrated
+                 "Bolt inventory is already on the latest version. Skipping inventory update."
+               else
+                 "Could not migrate Bolt inventory to the latest version. See "\
+                 "https://puppet.com/docs/bolt/latest/inventory_file_v2.html to manually update."
+               end
+      outputter.print_message(result)
+      ok
+    end
+
+    # Walks an inventory hash and replaces all 'nodes' keys with 'targets' keys
+    # and all 'name' keys nested in a 'targets' hash with 'uri' keys. Data is
+    # modified in place.
+    private def migrate_group(group)
+      migrated = false
+      if group.key?('nodes')
+        migrated = true
+        targets = group['nodes'].map do |target|
+          target['uri'] = target.delete('name') if target.is_a?(Hash)
+          target
+        end
+        group.delete('nodes')
+        group['targets'] = targets
+      end
+      (group['groups'] || []).each do |subgroup|
+        migrated_group = migrate_group(subgroup)
+        migrated ||= migrated_group
+      end
+      migrated
+    end
+  end
+end