bolt 2.22.0 → 2.26.0

data/lib/bolt/cli.rb

@@ -20,6 +20,7 @@ require 'bolt/logger'
 require 'bolt/outputter'
 require 'bolt/puppetdb'
 require 'bolt/plugin'
+require 'bolt/project_migrate'
 require 'bolt/pal'
 require 'bolt/target'
 require 'bolt/version'
@@ -38,13 +39,14 @@ module Bolt
                  'inventory' => %w[show],
                  'group' => %w[show],
                  'project' => %w[init migrate],
-                 'apply' => %w[] }.freeze
+                 'apply' => %w[],
+                 'guide' => %w[] }.freeze
 
     attr_reader :config, :options
 
     def initialize(argv)
       Bolt::Logger.initialize_logging
-      @logger = Logging.logger[self]
+      @logger = Bolt::Logger.logger(self)
       @argv = argv
       @options = {}
     end
@@ -77,7 +79,7 @@ module Bolt
 
     # Wrapper method that is called by the Bolt executable. Parses the command and
     # then loads the project and config. Once config is loaded, it completes the
-    # setup process by configuring Bolt and issuing warnings.
+    # setup process by configuring Bolt and logging messages.
     #
     # This separation is needed since the Bolt::Outputter class that normally handles
     # printing errors relies on config being loaded. All setup that happens before
@@ -165,20 +167,17 @@ module Bolt
       raise e
     end
 
-    # Completes the setup process by configuring Bolt and issuing warnings
+    # Completes the setup process by configuring Bolt and log messages
     def finalize_setup
       Bolt::Logger.configure(config.log, config.color)
       Bolt::Logger.analytics = analytics
 
-      # Logger must be configured before checking path case and project file, otherwise warnings will not display
+      # Logger must be configured before checking path case and project file, otherwise logs will not display
       config.check_path_case('modulepath', config.modulepath)
       config.project.check_deprecated_file
 
-      # Log the file paths for loaded config files
-      config_loaded
-
-      # Display warnings created during parser and config initialization
-      config.warnings.each { |warning| @logger.warn(warning[:msg]) }
+      # Log messages created during parser and config initialization
+      config.logs.each { |log| @logger.send(log.keys[0], log.values[0]) }
       @parser_deprecations.each { |dep| Bolt::Logger.deprecation_warning(dep[:type], dep[:msg]) }
       config.deprecations.each { |dep| Bolt::Logger.deprecation_warning(dep[:type], dep[:msg]) }
 
@@ -354,7 +353,7 @@ module Bolt
       # Initialize inventory and targets. Errors here are better to catch early.
       # options[:target_args] will contain a string/array version of the targetting options this is passed to plans
       # options[:targets] will contain a resolved set of Target objects
-      unless %w[project puppetfile secret].include?(options[:subcommand]) ||
+      unless %w[project puppetfile secret guide].include?(options[:subcommand]) ||
              %w[convert new show].include?(options[:action])
         update_targets(options)
       end
@@ -411,7 +410,7 @@ module Bolt
         list_modules
         return 0
       when 'convert'
-        convert_plan(options[:object])
+        pal.convert_plan(options[:object])
         return 0
       end
 
@@ -422,12 +421,20 @@ module Bolt
       end
 
       case options[:subcommand]
+      when 'guide'
+        code = if options[:object]
+                 show_guide(options[:object])
+               else
+                 list_topics
+               end
       when 'project'
         case options[:action]
         when 'init'
           code = initialize_project
         when 'migrate'
-          code = migrate_project
+          inv = config.inventoryfile
+          path = config.project.path
+          code = Bolt::ProjectMigrate.new(path, outputter, inv).migrate_project
         end
       when 'plan'
         case options[:action]
@@ -526,7 +533,7 @@ module Bolt
       tasks = pal.list_tasks
       tasks.select! { |task| task.first.include?(options[:filter]) } if options[:filter]
       tasks.select! { |task| config.project.tasks.include?(task.first) } unless config.project.tasks.nil?
-      outputter.print_tasks(tasks, pal.list_modulepath)
+      outputter.print_tasks(tasks, pal.user_modulepath)
     end
 
     def show_plan(plan_name)
@@ -537,7 +544,7 @@ module Bolt
       plans = pal.list_plans
       plans.select! { |plan| plan.first.include?(options[:filter]) } if options[:filter]
       plans.select! { |plan| config.project.plans.include?(plan.first) } unless config.project.plans.nil?
-      outputter.print_plans(plans, pal.list_modulepath)
+      outputter.print_plans(plans, pal.user_modulepath)
     end
 
     def list_targets
@@ -770,8 +777,26 @@ module Bolt
     # Initializes a specified directory as a Bolt project and installs any modules
     # specified by the user, along with their dependencies
     def initialize_project
-      project    = Pathname.new(File.expand_path(options[:object] || Dir.pwd))
-      config     = project + 'bolt.yaml'
+      # Dir.pwd will return backslashes on Windows, but Pathname always uses
+      # forward slashes to concatenate paths. This results in paths like
+      # C:\User\Administrator/modules, which fail module install. This ensure
+      # forward slashes in the cwd path.
+      dir = File.expand_path(Dir.pwd)
+      name = options[:object] || File.basename(dir)
+      if name !~ Bolt::Module::MODULE_NAME_REGEX
+        if options[:object]
+          raise Bolt::ValidationError, "The provided project name '#{name}' is invalid; "\
+            "project name must begin with a lowercase letter and can include lowercase "\
+            "letters, numbers, and underscores."
+        else
+          raise Bolt::ValidationError, "The current directory name '#{name}' is an invalid "\
+            "project name. Please specify a name using 'bolt project init <name>'."
+        end
+      end
+
+      project    = Pathname.new(dir)
+      old_config = project + 'bolt.yaml'
+      config     = project + 'bolt-project.yaml'
       puppetfile = project + 'Puppetfile'
       modulepath = [project + 'modules']
 
@@ -792,18 +817,24 @@ module Bolt
 
       # Warn the user if the project directory already exists. We don't error here since users
       # might not have installed any modules yet.
+      # If both bolt.yaml and bolt-project.yaml exist, this will just warn
+      # about bolt-project.yaml and subsequent Bolt actions will warn about
+      # both files existing
       if config.exist?
-        @logger.warn "Found existing project directory at #{project}"
-      end
-
-      # Create the project directory
-      FileUtils.mkdir_p(project)
-
+        @logger.warn "Found existing project directory at #{project}. Skipping file creation."
+      # This won't get called if bolt-project.yaml exists
+      elsif old_config.exist?
+        @logger.warn "Found existing #{old_config.basename} at #{project}. "\
+          "#{old_config.basename} is deprecated, please rename to #{config.basename}."
       # Bless the project directory as a...wait for it...project
-      if FileUtils.touch(config)
-        outputter.print_message "Successfully created Bolt project at #{project}"
       else
-        raise Bolt::FileError.new("Could not create Bolt project directory at #{project}", nil)
+        begin
+          content = { 'name' => name }
+          File.write(config.to_path, content.to_yaml)
+          outputter.print_message "Successfully created Bolt project at #{project}"
+        rescue StandardError => e
+          raise Bolt::FileError.new("Could not create bolt-project.yaml at #{project}: #{e.message}", nil)
+        end
       end
 
       # Write the generated Puppetfile to the fancy new project
@@ -879,49 +910,6 @@ module Bolt
       end
     end
 
-    def migrate_project
-      inventory_file = config.inventoryfile || config.default_inventoryfile
-      data = Bolt::Util.read_yaml_hash(inventory_file, 'inventory')
-
-      data.delete('version') if data['version'] != 2
-
-      migrated = migrate_group(data)
-
-      ok = File.write(inventory_file, data.to_yaml) if migrated
-
-      result = if migrated && ok
-                 "Successfully migrated Bolt project to latest version."
-               elsif !migrated
-                 "Bolt project already on latest version. Nothing to do."
-               else
-                 "Could not migrate Bolt project to latest version."
-               end
-      outputter.print_message result
-
-      ok ? 0 : 1
-    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.
-    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
-
     def install_puppetfile(config, puppetfile, modulepath)
       require 'r10k/cli'
       require 'bolt/r10k_log_proxy'
@@ -964,8 +952,46 @@ module Bolt
                              config.project)
     end
 
-    def convert_plan(plan)
-      pal.convert_plan(plan)
+    # Collects the list of Bolt guides and maps them to their topics.
+    def guides
+      @guides ||= begin
+                    root_path = File.expand_path(File.join(__dir__, '..', '..', 'guides'))
+                    files     = Dir.children(root_path).sort
+
+                    files.each_with_object({}) do |file, guides|
+                      next if file !~ /\.txt\z/
+                      topic = File.basename(file, '.txt')
+                      guides[topic] = File.join(root_path, file)
+                    end
+                  rescue SystemCallError => e
+                    raise Bolt::FileError.new("#{e.message}: unable to load guides directory", root_path)
+                  end
+    end
+
+    # Display the list of available Bolt guides.
+    def list_topics
+      outputter.print_topics(guides.keys)
+      0
+    end
+
+    # Display a specific Bolt guide.
+    def show_guide(topic)
+      if guides[topic]
+        analytics.event('Guide', 'known_topic', label: topic)
+
+        begin
+          guide = File.read(guides[topic])
+        rescue SystemCallError => e
+          raise Bolt::FileError("#{e.message}: unable to load guide page", filepath)
+        end
+
+        outputter.print_guide(guide, topic)
+      else
+        analytics.event('Guide', 'unknown_topic', label: topic)
+        outputter.print_message("Did not find guide for topic '#{topic}'.\n\n")
+        list_topics
+      end
+      0
     end
 
     def validate_file(type, path, allow_dir = false)
@@ -1028,13 +1054,6 @@ module Bolt
       content
     end
 
-    def config_loaded
-      msg = <<~MSG.chomp
-        Loaded configuration from: '#{config.config_files.join("', '")}'
-      MSG
-      @logger.debug(msg)
-    end
-
     # Gem installs include the aggregate, canary, and puppetdb_fact modules, while
     # package installs include modules listed in the Bolt repo Puppetfile
     def incomplete_install?

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,
         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?
@@ -331,9 +345,17 @@ module Bolt
 
     private def update_logs(logs)
       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 +380,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]