bolt 2.23.0 → 2.27.0

data/lib/bolt/config.rb

@@ -19,7 +19,7 @@ module Bolt
   class Config
     include Bolt::Config::Options
 
-    attr_reader :config_files, :warnings, :data, :transports, :project, :modified_concurrency, :deprecations
+    attr_reader :config_files, :logs, :data, :transports, :project, :modified_concurrency, :deprecations
 
     BOLT_CONFIG_NAME = 'bolt.yaml'
     BOLT_DEFAULTS_NAME = 'bolt-defaults.yaml'
@@ -32,16 +32,19 @@ module Bolt
     end
 
     def self.from_project(project, overrides = {})
+      logs = []
       conf = if project.project_file == project.config_file
                project.data
              else
-               Bolt::Util.read_optional_yaml_hash(project.config_file, 'config')
+               c = Bolt::Util.read_optional_yaml_hash(project.config_file, 'config')
+               logs << { debug: "Loaded configuration from #{project.config_file}" } if File.exist?(project.config_file)
+               c
              end
 
       data = load_defaults(project).push(
         filepath: project.config_file,
         data: conf,
-        warnings: [],
+        logs: logs,
         deprecations: []
       )
 
@@ -50,17 +53,20 @@ module Bolt
 
     def self.from_file(configfile, overrides = {})
       project = Bolt::Project.create_project(Pathname.new(configfile).expand_path.dirname)
+      logs = []
 
       conf = if project.project_file == project.config_file
                project.data
              else
-               Bolt::Util.read_yaml_hash(configfile, 'config')
+               c = Bolt::Util.read_yaml_hash(configfile, 'config')
+               logs << { debug: "Loaded configuration from #{configfile}" }
+               c
              end
 
       data = load_defaults(project).push(
-        filepath: project.config_file,
+        filepath: configfile,
         data: conf,
-        warnings: [],
+        logs: logs,
         deprecations: []
       )
 
@@ -90,13 +96,13 @@ module Bolt
     def self.load_bolt_defaults_yaml(dir)
       filepath = dir + BOLT_DEFAULTS_NAME
       data     = Bolt::Util.read_yaml_hash(filepath, 'config')
-      warnings = []
+      logs     = [{ debug: "Loaded configuration from #{filepath}" }]
 
       # Warn if 'bolt.yaml' detected in same directory.
       if File.exist?(bolt_yaml = dir + BOLT_CONFIG_NAME)
-        warnings.push(
-          msg: "Detected multiple configuration files: ['#{bolt_yaml}', '#{filepath}']. '#{bolt_yaml}' "\
-               "will be ignored."
+        logs.push(
+          warn: "Detected multiple configuration files: ['#{bolt_yaml}', '#{filepath}']. '#{bolt_yaml}' "\
+          "will be ignored."
         )
       end
 
@@ -105,9 +111,9 @@ module Bolt
 
       if project_config.any?
         data.reject! { |key, _| project_config.include?(key) }
-        warnings.push(
-          msg: "Unsupported project configuration detected in '#{filepath}': #{project_config.keys}. "\
-                "Project configuration should be set in 'bolt-project.yaml'."
+        logs.push(
+          warn: "Unsupported project configuration detected in '#{filepath}': #{project_config.keys}. "\
+          "Project configuration should be set in 'bolt-project.yaml'."
         )
       end
 
@@ -116,10 +122,10 @@ module Bolt
 
       if transport_config.any?
         data.reject! { |key, _| transport_config.include?(key) }
-        warnings.push(
-          msg: "Unsupported inventory configuration detected in '#{filepath}': #{transport_config.keys}. "\
-               "Transport configuration should be set under the 'inventory-config' option or "\
-               "in 'inventory.yaml'."
+        logs.push(
+          warn: "Unsupported inventory configuration detected in '#{filepath}': #{transport_config.keys}. "\
+          "Transport configuration should be set under the 'inventory-config' option or "\
+          "in 'inventory.yaml'."
         )
       end
 
@@ -142,7 +148,7 @@ module Bolt
         data = data.merge(data.delete('inventory-config'))
       end
 
-      { filepath: filepath, data: data, warnings: warnings, deprecations: [] }
+      { filepath: filepath, data: data, logs: logs, deprecations: [] }
     end
 
     # Loads a 'bolt.yaml' file, the legacy configuration file. There's no special munging needed
@@ -150,11 +156,12 @@ module Bolt
     def self.load_bolt_yaml(dir)
       filepath = dir + BOLT_CONFIG_NAME
       data     = Bolt::Util.read_yaml_hash(filepath, 'config')
+      logs     = [{ debug: "Loaded configuration from #{filepath}" }]
       deprecations = [{ type: 'Using bolt.yaml for system configuration',
                         msg: "Configuration file #{filepath} is deprecated and will be removed in a future version "\
                         "of Bolt. Use '#{dir + BOLT_DEFAULTS_NAME}' instead." }]
 
-      { filepath: filepath, data: data, warnings: [], deprecations: deprecations }
+      { filepath: filepath, data: data, logs: logs, deprecations: deprecations }
     end
 
     def self.load_defaults(project)
@@ -187,13 +194,13 @@ module Bolt
       unless config_data.is_a?(Array)
         config_data = [{ filepath: project.config_file,
                          data: config_data,
-                         warnings: [],
+                         logs: [],
                          deprecations: [] }]
       end
 
-      @logger       = Logging.logger[self]
+      @logger       = Bolt::Logger.logger(self)
       @project      = project
-      @warnings     = @project.warnings.dup
+      @logs         = @project.logs.dup
       @deprecations = @project.deprecations.dup
       @transports   = {}
       @config_files = []
@@ -213,8 +220,15 @@ module Bolt
         'transport'           => 'ssh'
       }
 
+      if project.path.directory?
+        default_data['log']['bolt-debug.log'] = {
+          'level' => 'debug',
+          'append' => false
+        }
+      end
+
       loaded_data = config_data.each_with_object([]) do |data, acc|
-        @warnings.concat(data[:warnings]) if data[:warnings].any?
+        @logs.concat(data[:logs]) if data[:logs].any?
         @deprecations.concat(data[:deprecations]) if data[:deprecations].any?
 
         if data[:data].any?
@@ -330,10 +344,26 @@ module Bolt
     end
 
     private def update_logs(logs)
+      begin
+        if logs['bolt-debug.log'] && logs['bolt-debug.log'] != 'disable'
+          FileUtils.touch(File.expand_path('bolt-debug.log', @project.path))
+        end
+      rescue StandardError
+        logs.delete('bolt-debug.log')
+      end
+
       logs.each_with_object({}) do |(key, val), acc|
-        next unless val.is_a?(Hash)
+        # Remove any disabled logs
+        next if val == 'disable'
 
         name = normalize_log(key)
+
+        # But otherwise it has to be a Hash
+        unless val.is_a?(Hash)
+          raise Bolt::ValidationError,
+                "config of log #{name} must be a Hash, received #{val.class} #{val.inspect}"
+        end
+
         acc[name] = val.slice('append', 'level')
                        .transform_keys(&:to_sym)
 
@@ -358,7 +388,7 @@ module Bolt
     def validate
       if @data['future']
         msg = "Configuration option 'future' no longer exposes future behavior."
-        @warnings << { option: 'future', msg: msg }
+        @logs << { warn: msg }
       end
 
       keys = OPTIONS.keys - %w[plugins plugin_hooks puppetdb]

data/lib/bolt/config/options.rb

@@ -176,7 +176,9 @@ module Bolt
           description: "A map of configuration for the logfile output. Under `log`, you can configure log options "\
                        "for `console` and add configuration for individual log files, such as "\
                        "`~/.puppetlabs/bolt/debug.log`. Individual log files must be valid filepaths. If the log "\
-                       "file does not exist, then Bolt will create it before logging information.",
+                       "file does not exist, then Bolt will create it before logging information. Set the value to "\
+                       "`disable` to remove a log file defined at an earlier level of the config hierarchy. By "\
+                       "default, Bolt logs to a bolt-debug.log file in the Bolt project directory.",
           type: Hash,
           properties: {
             "console" => {
@@ -186,15 +188,16 @@ module Bolt
                 "level" => {
                   description: "The type of information to log.",
                   type: String,
-                  enum: %w[debug error info notice warn fatal any],
-                  _default: "warn for console, notice for file"
+                  enum: %w[trace debug error info warn fatal any],
+                  _default: "warn"
                 }
               }
             }
           },
           additionalProperties: {
             description: "Configuration for the logfile output.",
-            type: Hash,
+            type: [String, Hash],
+            enum: ['disable'],
             properties: {
               "append" => {
                 description: "Whether to append output to an existing log file.",
@@ -204,8 +207,8 @@ module Bolt
               "level" => {
                 description: "The type of information to log.",
                 type: String,
-                enum: %w[debug error info notice warn fatal any],
-                _default: "warn for console, notice for file"
+                enum: %w[trace debug error info warn fatal any],
+                _default: "warn"
               }
             }
           },
@@ -224,6 +227,24 @@ module Bolt
           _example: ["~/.puppetlabs/bolt/modules", "~/.puppetlabs/bolt/site-modules"],
           _default: ["project/modules", "project/site-modules", "project/site"]
         },
+        "modules" => {
+          description: "A list of module dependencies for the project. Each dependency is a map of data specifying "\
+                       "the module to install. To install the project's module dependencies, run the `bolt module "\
+                       "install` command.",
+          type: Array,
+          items: {
+            type: Hash,
+            required: ["name"],
+            properties: {
+              "name" => {
+                description: "The name of the module.",
+                type: String
+              }
+            }
+          },
+          _plugin: false,
+          _example: [{ "name" => "puppetlabs-mysql" }, { "name" => "puppetlabs-apache" }]
+        },
         "name" => {
           description: "The name of the Bolt project. When this option is configured, the project is considered a "\
                        "[Bolt project](experimental_features.md#bolt-projects), allowing Bolt to load content from "\
@@ -473,6 +494,7 @@ module Bolt
         inventoryfile
         log
         modulepath
+        modules
         name
         plans
         plugin_hooks

data/lib/bolt/executor.rb

@@ -40,7 +40,7 @@ module Bolt
       require 'concurrent'
 
       @analytics = analytics
-      @logger = Logging.logger[self]
+      @logger = Bolt::Logger.logger(self)
 
       @transports = Bolt::TRANSPORTS.each_with_object({}) do |(key, val), coll|
         coll[key.to_s] = if key == :remote
@@ -56,11 +56,12 @@ module Bolt
       @reported_transports = Set.new
       @subscribers = {}
       @publisher = Concurrent::SingleThreadExecutor.new
+      @publisher.post { Thread.current[:name] = 'event-publisher' }
 
       @noop = noop
       @run_as = nil
       @pool = if concurrency > 0
-                Concurrent::ThreadPoolExecutor.new(max_threads: concurrency)
+                Concurrent::ThreadPoolExecutor.new(name: 'exec', max_threads: concurrency)
               else
                 Concurrent.global_immediate_executor
               end
@@ -125,6 +126,7 @@ module Bolt
           # Pass this argument through to avoid retaining a reference to a
           # local variable that will change on the next iteration of the loop.
           @pool.post(batch_promises) do |result_promises|
+            Thread.current[:name] ||= Thread.current.name
             results = yield transport, batch
             Array(results).each do |result|
               result_promises[result.target].set(result)
@@ -241,7 +243,7 @@ module Bolt
 
       @analytics&.event('Plan', 'yaml', plan_steps: steps, return_type: return_type)
     rescue StandardError => e
-      @logger.debug { "Failed to submit analytics event: #{e.message}" }
+      @logger.trace { "Failed to submit analytics event: #{e.message}" }
     end
 
     def with_node_logging(description, batch)

data/lib/bolt/inventory.rb

@@ -46,10 +46,13 @@ module Bolt
     end
 
     def self.from_config(config, plugins)
+      logger = Logging.logger[self]
+
       if ENV.include?(ENVIRONMENT_VAR)
         begin
           data = YAML.safe_load(ENV[ENVIRONMENT_VAR])
           raise Bolt::ParseError, "Could not parse inventory from $#{ENVIRONMENT_VAR}" unless data.is_a?(Hash)
+          logger.debug("Loaded inventory from environment variable #{ENVIRONMENT_VAR}")
         rescue Psych::Exception
           raise Bolt::ParseError, "Could not parse inventory from $#{ENVIRONMENT_VAR}"
         end
@@ -57,8 +60,12 @@ module Bolt
         data = if config.inventoryfile
                  Bolt::Util.read_yaml_hash(config.inventoryfile, 'inventory')
                else
-                 Bolt::Util.read_optional_yaml_hash(config.default_inventoryfile, 'inventory')
+                 i = Bolt::Util.read_optional_yaml_hash(config.default_inventoryfile, 'inventory')
+                 logger.debug("Loaded inventory from #{config.default_inventoryfile}") if i
+                 i
                end
+        # This avoids rubocop complaining about identical conditionals
+        logger.debug("Loaded inventory from #{config.inventoryfile}") if config.inventoryfile
       end
 
       # Resolve plugin references from transport config

data/lib/bolt/inventory/group.rb

@@ -19,7 +19,7 @@ module Bolt
       CONFIG_KEYS = Bolt::Config::INVENTORY_OPTIONS.keys
 
       def initialize(input, plugins)
-        @logger = Logging.logger[self]
+        @logger = Bolt::Logger.logger(self)
         @plugins = plugins
 
         input = @plugins.resolve_top_level_references(input) if @plugins.reference?(input)
@@ -119,7 +119,7 @@ module Bolt
         end
 
         if contains_target?(t_name)
-          @logger.warn("Ignoring duplicate target in #{@name}: #{target}")
+          @logger.debug("Ignoring duplicate target in #{@name}: #{target}")
           return
         end
 
@@ -200,14 +200,14 @@ module Bolt
           # If this is an alias for an existing target, then add it to this group
           elsif (canonical_name = aliases[string_target])
             if contains_target?(canonical_name)
-              @logger.warn("Ignoring duplicate target in #{@name}: #{canonical_name}")
+              @logger.debug("Ignoring duplicate target in #{@name}: #{canonical_name}")
             else
               @unresolved_targets[canonical_name] = { 'name' => canonical_name }
             end
           # If it's not the name or alias of an existing target, then make a
           # new target using the string as the URI
           elsif contains_target?(string_target)
-            @logger.warn("Ignoring duplicate target in #{@name}: #{string_target}")
+            @logger.debug("Ignoring duplicate target in #{@name}: #{string_target}")
           else
             @unresolved_targets[string_target] = { 'uri' => string_target }
           end

data/lib/bolt/inventory/inventory.rb

@@ -16,7 +16,7 @@ module Bolt
 
       # TODO: Pass transport config instead of config object
       def initialize(data, transport, transports, plugins)
-        @logger       = Logging.logger[self]
+        @logger       = Bolt::Logger.logger(self)
         @data         = data || {}
         @transport    = transport
         @config       = transports

data/lib/bolt/inventory/target.rb

@@ -13,7 +13,7 @@ module Bolt
           raise Bolt::Inventory::ValidationError.new("Target must have either a name or uri", nil)
         end
 
-        @logger = Logging.logger[inventory]
+        @logger = Bolt::Logger.logger(inventory)
 
         # If the target isn't mentioned by any groups, it won't have a uri or
         # name and we will use the target_name as both

data/lib/bolt/logger.rb

@@ -14,13 +14,12 @@ module Bolt
       # redefs, so skip it if it's already been initialized
       return if Logging.initialized?
 
-      Logging.init :debug, :info, :notice, :warn, :error, :fatal, :any
+      Logging.init :trace, :debug, :info, :notice, :warn, :error, :fatal, :any
       @mutex = Mutex.new
 
       Logging.color_scheme(
         'bolt',
         lines: {
-          notice: :green,
           warn: :yellow,
           error: :red,
           fatal: %i[white on_red]
@@ -29,7 +28,7 @@ module Bolt
     end
 
     def self.configure(destinations, color)
-      root_logger = Logging.logger[:root]
+      root_logger = Bolt::Logger.logger(:root)
 
       root_logger.add_appenders Logging.appenders.stderr(
         'console',
@@ -67,6 +66,13 @@ module Bolt
       end
     end
 
+    # A helper to ensure the Logging library is always initialized with our
+    # custom log levels before retrieving a Logger instance.
+    def self.logger(name)
+      initialize_logging
+      Logging.logger[name]
+    end
+
     def self.analytics=(analytics)
       @analytics = analytics
     end
@@ -81,7 +87,7 @@ module Bolt
 
     def self.default_layout
       Logging.layouts.pattern(
-        pattern: '%d %-6l %c: %m\n',
+        pattern: '%d %-6l [%T] [%c] %m\n',
         date_pattern: '%Y-%m-%dT%H:%M:%S.%6N'
       )
     end
@@ -91,7 +97,7 @@ module Bolt
     end
 
     def self.default_file_level
-      :notice
+      :warn
     end
 
     # Explicitly check the log level names instead of the log level number, as levels
@@ -111,7 +117,7 @@ module Bolt
     def self.warn_once(type, msg)
       @mutex.synchronize {
         @warnings ||= []
-        @logger ||= Logging.logger[self]
+        @logger ||= Bolt::Logger.logger(self)
         unless @warnings.include?(type)
           @logger.warn(msg)
           @warnings << type

data/lib/bolt/outputter/human.rb

@@ -286,6 +286,16 @@ module Bolt
                         "details and parameters for a specific plan.")
       end
 
+      def print_topics(topics)
+        print_message("Available topics are:")
+        print_message(topics.join("\n"))
+        print_message("\nUse `bolt guide <topic>` to view a specific guide.")
+      end
+
+      def print_guide(guide, _topic)
+        @stream.puts(guide)
+      end
+
       def print_module_list(module_list)
         module_list.each do |path, modules|
           if (mod = modules.find { |m| m[:internal_module_group] })