bolt 2.21.0 → 2.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef2991c1d3979e03b9070dc168be0e8c44c309914fd7eb02badc60e5b5d907bf
-  data.tar.gz: 9508d434488486b8b16d062f910f6d3bcf8d7b3e89121ccb8033dd393a7a21db
+  metadata.gz: 8bfb8de382e2a2ab6931f43ffce1eb97187fda6e2e56036b20637afb8ae8da2d
+  data.tar.gz: 56cf9c3fda7f29434413feb8b7f2eb3b358c1ed4316f2d5f4e1e47875a6919c5
 SHA512:
-  metadata.gz: 351084ca010d6f3d051a588e0d216f07d32473026703378dd7003c9f71f411fa2499926d4e1c6272df55cffc8eeb360fbc6fff4c5a0930c14cba006dfbf3874c
-  data.tar.gz: eef7d1b6b0dfe5584bd216bb5ebe421b61b9e25a4131509cf310f33fc75f7a3afa072e919215eefadb43ac7415cdd51546e6b634daf53d8a7a568366bb31ee68
+  metadata.gz: ec5bf195ad19bac051942f2689e58a325982a8c47b12d8970e1ed6a6758e714d8f22ce5275dc3fb7160ea6d06e7ee63bf528b2f18d67ee754b9ae41c3e92a7c5
+  data.tar.gz: cc6a87ed720484d04c7bb2275cd6812ac211733e2efce265b69cfb5ee5614fa743122ce50369079697ad08374eccea6e9797e8398176d7669846887b0f0832aa

data/Puppetfile

@@ -6,7 +6,7 @@ moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
 mod 'puppetlabs-service', '1.3.0'
-mod 'puppetlabs-puppet_agent', '3.2.0'
+mod 'puppetlabs-puppet_agent', '4.1.1'
 mod 'puppetlabs-facts', '1.0.0'
 
 # Core types and providers for Puppet 6

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/do_until.rb

@@ -4,30 +4,36 @@
 Puppet::Functions.create_function(:'ctrl::do_until') do
   # @param options A hash of additional options.
   # @option options [Numeric] limit The number of times to repeat the block.
+  # @option options [Numeric] interval The number of seconds to wait before repeating the block.
   # @example Run a task until it succeeds
   #   ctrl::do_until() || {
-  #     run_task('test', $target, _catch_errors => true).ok()
+  #     run_task('test', $target, '_catch_errors' => true).ok()
   #   }
-  #
   # @example Run a task until it succeeds or fails 10 times
   #   ctrl::do_until('limit' => 10) || {
-  #     run_task('test', $target, _catch_errors => true).ok()
+  #     run_task('test', $target, '_catch_errors' => true).ok()
+  #   }
+  # @example Run a task and wait 10 seconds before running it again
+  #   ctrl::do_until('interval' => 10) || {
+  #     run_task('test', $target, '_catch_errors' => true).ok()
   #   }
-  #
   dispatch :do_until do
     optional_param 'Hash[String[1], Any]', :options
     block_param
   end
 
-  def do_until(options = { 'limit' => 0 })
+  def do_until(options = {})
     # Send Analytics Report
     Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
 
-    limit = options['limit']
+    limit = options['limit'] || 0
+    interval = options['interval']
+
     i = 0
     until (x = yield)
       i += 1
       break if limit != 0 && i >= limit
+      Kernel.sleep(interval) if interval
     end
     x
   end

data/bolt-modules/out/lib/puppet/functions/out/message.rb

@@ -12,7 +12,7 @@ Puppet::Functions.create_function(:'out::message') do
   # @example Print a message
   #   out::message('Something went wrong')
   dispatch :output_message do
-    param 'String', :message
+    param 'Any', :message
     return_type 'Undef'
   end
 

data/exe/bolt

@@ -4,6 +4,7 @@
 require 'bolt'
 require 'bolt/cli'
 
+Thread.current[:name] ||= 'main'
 cli = Bolt::CLI.new(ARGV)
 begin
   opts = cli.parse

data/guides/inventory.txt

@@ -0,0 +1,19 @@
+TOPIC
+    inventory
+
+DESCRIPTION
+    The inventory describes the targets that you run Bolt commands on, along
+    with any data and configuration for the targets. Targets in an inventory can
+    belong to one or more groups, allowing you to share data and configuration
+    across multiple targets and to specify multiple targets for your Bolt
+    commands without the need to list each target individually.
+
+    In most cases, Bolt loads the inventory from an inventory file in your Bolt
+    project. The inventory file is a YAML file named 'inventory.yaml'. Because
+    Bolt loads the inventory file from a Bolt project, you must have an existing
+    project configuration file named 'bolt-project.yaml' alongside the inventory
+    file.
+
+DOCUMENTATION
+    https://pup.pt/bolt-inventory
+    https://pup.pt/bolt-inventory-reference

data/guides/project.txt

@@ -0,0 +1,22 @@
+TOPIC
+    project
+
+DESCRIPTION
+    A Bolt project is a directory that serves as the launching point for Bolt
+    and allows you to create a shareable orchestration application. Projects
+    typically include a project configuration file, an inventory file, and any
+    content you use in your project workflow, such as tasks and plans.
+
+    When you run Bolt, it runs in the context of a project. If the directory you
+    run Bolt from is not a project, Bolt attempts to find a project by
+    traversing the parent directories. If Bolt is unable to find a project, it
+    runs from the default project, located at '~/.puppetlabs/bolt'.
+
+    A directory is only considered a Bolt project when it has a project
+    configuration file named 'bolt-project.yaml'. Bolt doesn't load project data
+    and content, including inventory files, unless the data and content are part
+    of a project.
+
+DOCUMENTATION
+    https://pup.pt/bolt-projects
+    https://pup.pt/bolt-project-reference

data/lib/bolt/analytics.rb

@@ -72,7 +72,7 @@ module Bolt
 
     def self.load_config(filename, logger)
       if File.exist?(filename)
-        YAML.load_file(filename)
+        Bolt::Util.read_optional_yaml_hash(filename, 'analytics')
       else
         unless ENV['BOLT_DISABLE_ANALYTICS']
           logger.warn <<~ANALYTICS
@@ -161,9 +161,9 @@ module Bolt
         # Handle analytics submission in the background to avoid blocking the
         # app or polluting the log with errors
         Concurrent::Future.execute(executor: @executor) do
-          @logger.debug "Submitting analytics: #{JSON.pretty_generate(params)}"
+          @logger.trace "Submitting analytics: #{JSON.pretty_generate(params)}"
           @http.post(TRACKING_URL, params)
-          @logger.debug "Completed analytics submission"
+          @logger.trace "Completed analytics submission"
         end
       end
 
@@ -215,13 +215,13 @@ module Bolt
       end
 
       def screen_view(screen, **_kwargs)
-        @logger.debug "Skipping submission of '#{screen}' screenview because analytics is disabled"
+        @logger.trace "Skipping submission of '#{screen}' screenview because analytics is disabled"
       end
 
       def report_bundled_content(mode, name); end
 
       def event(category, action, **_kwargs)
-        @logger.debug "Skipping submission of '#{category} #{action}' event because analytics is disabled"
+        @logger.trace "Skipping submission of '#{category} #{action}' event because analytics is disabled"
       end
 
       def finish; end

data/lib/bolt/applicator.rb

@@ -27,7 +27,7 @@ module Bolt
       @hiera_config = hiera_config ? validate_hiera_config(hiera_config) : nil
       @apply_settings = apply_settings || {}
 
-      @pool = Concurrent::ThreadPoolExecutor.new(max_threads: max_compiles)
+      @pool = Concurrent::ThreadPoolExecutor.new(name: 'apply', max_threads: max_compiles)
       @logger = Logging.logger[self]
     end
 
@@ -217,6 +217,7 @@ module Bolt
       r = @executor.log_action(description, targets) do
         futures = targets.map do |target|
           Concurrent::Future.execute(executor: @pool) do
+            Thread.current[:name] ||= Thread.current.name
             @executor.with_node_logging("Compiling manifest block", [target]) do
               compile(target, scope)
             end
@@ -300,7 +301,7 @@ module Bolt
 
         files.each do |file|
           tar_path = Pathname.new(file).relative_path_from(parent)
-          @logger.debug("Packing plugin #{file} to #{tar_path}")
+          @logger.trace("Packing plugin #{file} to #{tar_path}")
           stat = File.stat(file)
           content = File.binread(file)
           output.tar.add_file_simple(
@@ -314,7 +315,7 @@ module Bolt
       end
 
       duration = Time.now - start_time
-      @logger.debug("Packed plugins in #{duration * 1000} ms")
+      @logger.trace("Packed plugins in #{duration * 1000} ms")
 
       output.close
       Base64.encode64(sio.string)

data/lib/bolt/bolt_option_parser.rb

@@ -61,11 +61,17 @@ module Bolt
           { flags: OPTIONS[:global],
             banner: GROUP_HELP }
         end
+      when 'guide'
+        { flags: OPTIONS[:global] + %w[format],
+          banner: GUIDE_HELP }
       when 'plan'
         case action
         when 'convert'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
             banner: PLAN_CONVERT_HELP }
+        when 'new'
+          { flags: OPTIONS[:global] + %w[configfile project],
+            banner: PLAN_NEW_HELP }
         when 'run'
           { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir hiera-config],
             banner: PLAN_RUN_HELP }
@@ -82,7 +88,7 @@ module Bolt
           { flags: OPTIONS[:global] + %w[modules],
             banner: PROJECT_INIT_HELP }
         when 'migrate'
-          { flags: OPTIONS[:global] + %w[inventoryfile boltdir configfile],
+          { flags: OPTIONS[:global] + %w[inventoryfile project configfile],
             banner: PROJECT_MIGRATE_HELP }
         else
           { flags: OPTIONS[:global],
@@ -159,15 +165,19 @@ module Bolt
       SUBCOMMANDS
           apply             Apply Puppet manifest code
           command           Run a command remotely
-          file              Upload a local file or directory
+          file              Copy files between the controller and targets
           group             Show the list of groups in the inventory
+          guide             View guides for Bolt concepts and features
           inventory         Show the list of targets an action would run on
-          plan              Convert, show, and run Bolt plans
+          plan              Convert, create, show, and run Bolt plans
           project           Create and migrate Bolt projects
           puppetfile        Install and list modules and generate type references
           script            Upload a local script and run it remotely
           secret            Create encryption keys and encrypt and decrypt values
           task              Show and run Bolt tasks
+
+      GUIDES
+          For a list of guides on Bolt's concepts and features, run 'bolt guide'.
     HELP
 
     APPLY_HELP = <<~HELP
@@ -286,6 +296,26 @@ module Bolt
           Show the list of groups in the inventory.
     HELP
 
+    GUIDE_HELP = <<~HELP
+      NAME
+          guide
+
+      USAGE
+          bolt guide [topic] [options]
+
+      DESCRIPTION
+          View guides for Bolt's concepts and features.
+
+          Omitting a topic will display a list of available guides,
+          while providing a topic will display the relevant guide.
+
+      EXAMPLES
+          View a list of available guides
+            bolt guide
+          View the 'project' guide page
+            bolt guide project
+    HELP
+
     INVENTORY_HELP = <<~HELP
       NAME
           inventory
@@ -319,10 +349,11 @@ module Bolt
           bolt plan <action> [parameters] [options]
 
       DESCRIPTION
-          Convert, show, and run Bolt plans.
+          Convert, create, show, and run Bolt plans.
 
       ACTIONS
           convert       Convert a YAML plan to a Bolt plan
+          new           Create a new plan in the current project
           run           Run a plan on the specified targets
           show          Show available plans and plan documentation
     HELP
@@ -345,6 +376,20 @@ module Bolt
           bolt plan convert path/to/plan/myplan.yaml
     HELP
 
+    PLAN_NEW_HELP = <<~HELP
+      NAME
+          new
+      
+      USAGE
+          bolt plan new <plan> [options]
+      
+      DESCRIPTION
+          Create a new plan in the current project.
+
+      EXAMPLES
+          bolt plan new myproject::myplan
+    HELP
+
     PLAN_RUN_HELP = <<~HELP
       NAME
           run
@@ -402,19 +447,18 @@ module Bolt
           init
 
       USAGE
-          bolt project init [directory] [options]
+          bolt project init [name] [options]
 
       DESCRIPTION
-          Create a new Bolt project.
+          Create a new Bolt project in the current working directory.
 
-          Specify a directory to create a Bolt project in. Defaults to the
-          curent working directory.
+          Specify a name for the Bolt project. Defaults to the basename of the current working directory.
 
       EXAMPLES
-          Create a new Bolt project in the current working directory.
+          Create a new Bolt project using the directory as the project name.
             bolt project init
-          Create a new Bolt project at a specified path.
-            bolt project init ~/path/to/project
+          Create a new Bolt project with a specified name.
+            bolt project init myproject
           Create a new Bolt project with existing modules.
             bolt project init --modules puppetlabs-apt,puppetlabs-ntp
     HELP
@@ -427,10 +471,7 @@ module Bolt
           bolt project migrate [options]
 
       DESCRIPTION
-          Migrate a Bolt project to the latest version.
-
-          Loads a Bolt project's inventory file and migrates it to the latest version. The
-          inventory file is modified in place and will not preserve comments or formatting.
+          Migrate a Bolt project to use current best practices and the latest version of configuration files.
     HELP
 
     PUPPETFILE_HELP = <<~HELP
@@ -676,9 +717,9 @@ module Bolt
         @options[:password] = password
       end
       define('--password-prompt', 'Prompt for user to input password') do |_password|
-        STDERR.print "Please enter your password: "
-        @options[:password] = STDIN.noecho(&:gets).chomp
-        STDERR.puts
+        $stderr.print "Please enter your password: "
+        @options[:password] = $stdin.noecho(&:gets).chomp
+        $stderr.puts
       end
       define('--private-key KEY', 'Path to private ssh key to authenticate with') do |key|
         @options[:'private-key'] = File.expand_path(key)
@@ -702,9 +743,9 @@ module Bolt
         @options[:'sudo-password'] = password
       end
       define('--sudo-password-prompt', 'Prompt for user to input escalation password') do |_password|
-        STDERR.print "Please enter your privilege escalation password: "
-        @options[:'sudo-password'] = STDIN.noecho(&:gets).chomp
-        STDERR.puts
+        $stderr.print "Please enter your privilege escalation password: "
+        @options[:'sudo-password'] = $stdin.noecho(&:gets).chomp
+        $stderr.puts
       end
       define('--sudo-executable EXEC', "Specify an executable for running as another user.",
              "This option is experimental.") do |exec|
@@ -846,7 +887,7 @@ module Bolt
       end
       define('--log-level LEVEL',
              "Set the log level for the console. Available options are",
-             "debug, info, notice, warn, error, fatal, any.") do |level|
+             "trace, debug, info, warn, error, fatal, any.") do |level|
         @options[:log] = { 'console' => { 'level' => level } }
       end
       define('--plugin PLUGIN', 'Select the plugin to use') do |plug|
@@ -887,7 +928,7 @@ module Bolt
         file = value.sub(/^@/, '')
         read_arg_file(file)
       elsif value == '-'
-        STDIN.read
+        $stdin.read
       else
         value
       end

data/lib/bolt/catalog.rb

@@ -76,7 +76,15 @@ module Bolt
       target = request['target']
       plan_vars = shadow_vars('plan', request['plan_vars'], target['facts'])
       target_vars = shadow_vars('target', target['variables'], target['facts'])
-      topscope_vars = target_vars.merge(plan_vars)
+
+      # Merge plan vars with target vars, while maintaining the order of the plan
+      # vars. It's critical that the order of plan vars is not changed, as Puppet
+      # will deserialize the variables in the order they appear. Variables may
+      # contain local references to variables that appear earlier in a plan. If
+      # these variables are moved before the variable they reference, Puppet will
+      # be unable to deserialize the data and raise an error.
+      topscope_vars = target_vars.reject { |k, _v| plan_vars.key?(k) }.merge(plan_vars)
+
       env_conf = { modulepath: request['modulepath'],
                    facts: target['facts'],
                    variables: topscope_vars }

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'
@@ -31,14 +32,15 @@ module Bolt
     COMMANDS = { 'command' => %w[run],
                  'script' => %w[run],
                  'task' => %w[show run],
-                 'plan' => %w[show run convert],
+                 'plan' => %w[show run convert new],
                  'file' => %w[download upload],
                  'puppetfile' => %w[install show-modules generate-types],
                  'secret' => %w[encrypt decrypt createkeys],
                  'inventory' => %w[show],
                  'group' => %w[show],
                  'project' => %w[init migrate],
-                 'apply' => %w[] }.freeze
+                 'apply' => %w[],
+                 'guide' => %w[] }.freeze
 
     attr_reader :config, :options
 
@@ -283,6 +285,10 @@ module Bolt
         raise Bolt::CLIError, "Must specify a value to #{options[:action]}"
       end
 
+      if options[:subcommand] == 'plan' && options[:action] == 'new' && !options[:object]
+        raise Bolt::CLIError, "Must specify a plan name."
+      end
+
       if options.key?(:debug) && options.key?(:log)
         raise Bolt::CLIError, "Only one of '--debug' or '--log-level' may be specified"
       end
@@ -350,19 +356,11 @@ 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 options[:subcommand] == 'puppetfile' ||
-             options[:subcommand] == 'secret' ||
-             options[:subcommand] == 'project' ||
-             options[:action] == 'show' ||
-             options[:action] == 'convert'
+      unless %w[project puppetfile secret guide].include?(options[:subcommand]) ||
+             %w[convert new show].include?(options[:action])
         update_targets(options)
       end
 
-      if options[:action] == 'convert'
-        convert_plan(options[:object])
-        return 0
-      end
-
       screen = "#{options[:subcommand]}_#{options[:action]}"
       # submit a different screen for `bolt task show` and `bolt task show foo`
       if options[:action] == 'show' && options[:object]
@@ -414,6 +412,9 @@ module Bolt
       when 'show-modules'
         list_modules
         return 0
+      when 'convert'
+        pal.convert_plan(options[:object])
+        return 0
       end
 
       message = 'There may be processes left executing on some nodes.'
@@ -423,15 +424,28 @@ 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'
-        code = run_plan(options[:object], options[:task_options], options[:target_args], options)
+        case options[:action]
+        when 'new'
+          code = new_plan(options[:object])
+        when 'run'
+          code = run_plan(options[:object], options[:task_options], options[:target_args], options)
+        end
       when 'puppetfile'
         case options[:action]
         when 'generate-types'
@@ -522,7 +536,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)
@@ -533,7 +547,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
@@ -551,6 +565,118 @@ module Bolt
       outputter.print_groups(groups)
     end
 
+    def new_plan(plan_name)
+      @logger.warn("Command 'bolt plan new' is experimental and subject to changes.")
+
+      if config.project.name.nil?
+        raise Bolt::Error.new(
+          "Project directory '#{config.project.path}' is not a named project. Unable to create "\
+          "a project-level plan. To name a project, set the 'name' key in the 'bolt-project.yaml' "\
+          "configuration file.",
+          "bolt/unnamed-project-error"
+        )
+      end
+
+      if plan_name !~ Bolt::Module::CONTENT_NAME_REGEX
+        message = <<~MESSAGE.chomp
+          Invalid plan name '#{plan_name}'. Plan names are composed of one or more name segments
+          separated by double colons '::'.
+          
+          Each name segment must begin with a lowercase letter, and may only include lowercase
+          letters, digits, and underscores.
+          
+          Examples of valid plan names:
+              - #{config.project.name}
+              - #{config.project.name}::my_plan
+        MESSAGE
+
+        raise Bolt::ValidationError, message
+      end
+
+      prefix, *name_segments, basename = plan_name.split('::')
+
+      # If the plan name is just the project name, then create an 'init' plan.
+      # Otherwise, use the last name segment for the plan's filename.
+      basename ||= 'init'
+
+      unless prefix == config.project.name
+        message = "First segment of plan name '#{plan_name}' must match project name '#{config.project.name}'. "\
+                  "Did you mean '#{config.project.name}::#{plan_name}'?"
+
+        raise Bolt::ValidationError, message
+      end
+
+      dir_path = config.project.plans_path.join(*name_segments)
+
+      %w[pp yaml].each do |ext|
+        next unless (path = config.project.plans_path + "#{basename}.#{ext}").exist?
+        raise Bolt::Error.new(
+          "A plan with the name '#{plan_name}' already exists at '#{path}', nothing to do.",
+          'bolt/existing-plan-error'
+        )
+      end
+
+      begin
+        FileUtils.mkdir_p(dir_path)
+      rescue Errno::EEXIST => e
+        raise Bolt::Error.new(
+          "#{e.message}; unable to create plan directory '#{dir_path}'",
+          'bolt/existing-file-error'
+        )
+      end
+
+      plan_path = dir_path + "#{basename}.yaml"
+
+      plan_template = <<~PLAN
+        # This is the structure of a simple plan. To learn more about writing
+        # YAML plans, see the documentation: http://pup.pt/bolt-yaml-plans
+
+        # The description sets the description of the plan that will appear
+        # in 'bolt plan show' output.
+        description: A plan created with bolt plan new
+
+        # The parameters key defines the parameters that can be passed to
+        # the plan.
+        parameters:
+          targets:
+            type: TargetSpec
+            description: A list of targets to run actions on
+            default: localhost
+
+        # The steps key defines the actions the plan will take in order.
+        steps:
+          - message: Hello from #{plan_name}
+          - name: command_step
+            command: whoami
+            targets: $targets
+
+        # The return key sets the return value of the plan.
+        return: $command_step
+      PLAN
+
+      begin
+        File.write(plan_path, plan_template)
+      rescue Errno::EACCES => e
+        raise Bolt::FileError.new(
+          "#{e.message}; unable to create plan",
+          plan_path
+        )
+      end
+
+      output = <<~OUTPUT
+        Created plan '#{plan_name}' at '#{plan_path}'
+
+        Show this plan with:
+            bolt plan show #{plan_name}
+        Run this plan with:
+            bolt plan run #{plan_name}
+      OUTPUT
+
+      outputter.print_message(output)
+
+      0
+    end
+
     def run_plan(plan_name, plan_arguments, nodes, options)
       unless nodes.empty?
         if plan_arguments['nodes'] || plan_arguments['targets']
@@ -654,8 +780,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']
 
@@ -676,18 +820,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
@@ -763,49 +913,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'
@@ -848,8 +955,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)
@@ -916,7 +1061,7 @@ module Bolt
       msg = <<~MSG.chomp
         Loaded configuration from: '#{config.config_files.join("', '")}'
       MSG
-      @logger.debug(msg)
+      @logger.info(msg)
     end
 
     # Gem installs include the aggregate, canary, and puppetdb_fact modules, while