bolt 2.23.0 → 2.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f58ca99a18fca1c109d531c61b55bcee45d73c14e55a074575ffaaf1d9f40aac
-  data.tar.gz: ea55e4c9b9ba4ccd8afed70a6c62c603a119a46f406b573f429bd2cd89983672
+  metadata.gz: 851cd71cf3bbdd91a522f123db238205ca21875c7d1c9bf1eefe4850399ffb5d
+  data.tar.gz: 4ec2ca689f05d37ccbc1cd3962edae53dfcda79c0a58facd9a2f228af5df914c
 SHA512:
-  metadata.gz: dc8845ebe2a171ce79b704c474594a9679e7078feaca324eb7f26b88e9e903de43361a4dbaa357de3cf47be4ae72b4db4690a76e0910c9595f52aab384768fbc
-  data.tar.gz: 60b30a31debf0d031902d8df21372b2524246ee98749eeccfd588c00b3458bcb9c0ed2a1fbdeab266cce86332537bde1005aead37fece867d440d88989c2486d
+  metadata.gz: 3d595d36833a70860c7c997fff4cc55ce682dd3b3b9c4fc5e7b36067cbb73a665e65d473097993963f8409eb5a06a25b5b834de9dff6f42ad8e244972ab0ac4e
+  data.tar.gz: d136cd117711e3a103480b7cae52661e8ad3beef5023552f3bbaa8235e8f795410e13a1955290c7313fb6f7fced1485b275b8430a0d5c81297e11e1ff911f458

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/boltlib/lib/puppet/datatypes/result.rb

@@ -9,11 +9,12 @@ Puppet::DataTypes.create_type('Result') do
     functions => {
       error => Callable[[], Optional[Error]],
       message => Callable[[], Optional[String]],
+      sensitive => Callable[[], Optional[Sensitive[Data]]],
       action => Callable[[], String],
       status => Callable[[], String],
       to_data => Callable[[], Hash],
       ok => Callable[[], Boolean],
-      '[]' => Callable[[String[1]], Data]
+      '[]' => Callable[[String[1]], Variant[Data, Sensitive[Data]]]
     }
   PUPPET
 

data/bolt-modules/boltlib/lib/puppet/functions/download_file.rb

@@ -96,7 +96,7 @@ Puppet::Functions.create_function(:download_file, Puppet::Functions::InternalFun
 
     # Paths expand relative to the default downloads directory for the project
     # e.g. ~/.puppetlabs/bolt/downloads/
-    destination = Puppet.lookup(:bolt_project_data).downloads + destination
+    destination = Puppet.lookup(:bolt_project).downloads + destination
 
     # If the destination directory already exists, delete any existing contents
     if Dir.exist?(destination)

data/bolt-modules/dir/lib/puppet/functions/dir/children.rb

@@ -25,7 +25,7 @@ Puppet::Functions.create_function(:'dir::children', Puppet::Functions::InternalF
     full_mod_path = File.join(mod_path, subpath || '') if mod_path
 
     # Expand relative to the project directory if path is relative
-    project = Puppet.lookup(:bolt_project_data)
+    project = Puppet.lookup(:bolt_project)
     pathname = Pathname.new(dirname)
     full_dir = pathname.absolute? ? dirname : File.expand_path(File.join(project.path, dirname))
 

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

@@ -27,7 +27,7 @@ module Bolt
     }.freeze
 
     def self.build_client
-      logger = Logging.logger[self]
+      logger = Bolt::Logger.logger(self)
       begin
         config_file = config_path(logger)
         config = load_config(config_file, logger)
@@ -93,6 +93,10 @@ module Bolt
     def self.write_config(filename, config)
       FileUtils.mkdir_p(File.dirname(filename))
       File.write(filename, config.to_yaml)
+    rescue StandardError => e
+      Bolt::Logger.warn_once('unwriteable_file', "Could not write analytics configuration to #{filename}.")
+      # This will get caught by build_client and create a NoopClient
+      raise e
     end
 
     class Client
@@ -106,7 +110,7 @@ module Bolt
         require 'httpclient'
         require 'locale'
 
-        @logger = Logging.logger[self]
+        @logger = Bolt::Logger.logger(self)
         @http = HTTPClient.new
         @user_id = user_id
         @executor = Concurrent.global_io_executor
@@ -161,9 +165,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
 
@@ -210,18 +214,18 @@ module Bolt
       attr_accessor :bundled_content
 
       def initialize
-        @logger = Logging.logger[self]
+        @logger = Bolt::Logger.logger(self)
         @bundled_content = []
       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,8 +27,8 @@ module Bolt
       @hiera_config = hiera_config ? validate_hiera_config(hiera_config) : nil
       @apply_settings = apply_settings || {}
 
-      @pool = Concurrent::ThreadPoolExecutor.new(max_threads: max_compiles)
-      @logger = Logging.logger[self]
+      @pool = Concurrent::ThreadPoolExecutor.new(name: 'apply', max_threads: max_compiles)
+      @logger = Bolt::Logger.logger(self)
     end
 
     private def libexec
@@ -75,23 +75,24 @@ module Bolt
       end
     end
 
-    def compile(target, catalog_input)
+    def compile(target, scope)
       # This simplified Puppet node object is what .local uses to determine the
       # certname of the target
       node = Puppet::Node.from_data_hash('name' => target.name,
                                          'parameters' => { 'clientcert' => target.name })
       trusted = Puppet::Context::TrustedInformation.local(node)
-      catalog_input[:target] = {
+      target_data = {
         name: target.name,
         facts: @inventory.facts(target).merge('bolt' => true),
         variables: @inventory.vars(target),
         trusted: trusted.to_h
       }
+      catalog_request = scope.merge(target: target_data)
 
       bolt_catalog_exe = File.join(libexec, 'bolt_catalog')
       old_path = ENV['PATH']
       ENV['PATH'] = "#{RbConfig::CONFIG['bindir']}#{File::PATH_SEPARATOR}#{old_path}"
-      out, err, stat = Open3.capture3('ruby', bolt_catalog_exe, 'compile', stdin_data: catalog_input.to_json)
+      out, err, stat = Open3.capture3('ruby', bolt_catalog_exe, 'compile', stdin_data: catalog_request.to_json)
       ENV['PATH'] = old_path
 
       # If bolt_catalog does not return valid JSON, we should print stderr to
@@ -183,17 +184,16 @@ module Bolt
                                                                        type_by_reference: true,
                                                                        local_reference: true)
 
-      bolt_project = @project if @project&.name
       scope = {
         code_ast: ast,
         modulepath: @modulepath,
-        project: bolt_project.to_h,
+        project: @project.to_h,
         pdb_config: @pdb_client.config.to_hash,
         hiera_config: @hiera_config,
         plan_vars: plan_vars,
         # This data isn't available on the target config hash
         config: @inventory.transport_data_get
-      }
+      }.freeze
       description = options[:description] || 'apply catalog'
 
       required_modules = options[:required_modules].nil? ? nil : Array(options[:required_modules])
@@ -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,6 +61,18 @@ module Bolt
           { flags: OPTIONS[:global],
             banner: GROUP_HELP }
         end
+      when 'guide'
+        { flags: OPTIONS[:global] + %w[format],
+          banner: GUIDE_HELP }
+      when 'module'
+        case action
+        when 'install'
+          { flags: OPTIONS[:global] + %w[configfile force project],
+            banner: MODULE_INSTALL_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: MODULE_HELP }
+        end
       when 'plan'
         case action
         when 'convert'
@@ -85,7 +97,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],
@@ -164,6 +176,7 @@ module Bolt
           command           Run a command remotely
           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, create, show, and run Bolt plans
           project           Create and migrate Bolt projects
@@ -171,6 +184,9 @@ module Bolt
           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
@@ -289,6 +305,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
@@ -314,6 +350,35 @@ module Bolt
           Show the list of targets an action would run on.
     HELP
 
+    MODULE_HELP = <<~HELP
+      NAME
+          module
+      
+      USAGE
+          bolt module <action> [options]
+
+      DESCRIPTION
+          Install the project's modules
+
+      ACTIONS
+          install       Install the project's modules
+    HELP
+
+    MODULE_INSTALL_HELP = <<~HELP
+      NAME
+          install
+      
+      USAGE
+          bolt module install [options]
+
+      DESCRIPTION
+          Install the project's modules.
+
+          Module declarations are loaded from the project's configuration
+          file. Bolt will automatically resolve all module dependencies,
+          generate a Puppetfile, and install the modules.
+    HELP
+
     PLAN_HELP = <<~HELP
       NAME
           plan
@@ -339,11 +404,11 @@ module Bolt
           bolt plan convert <path> [options]
 
       DESCRIPTION
-          Convert a YAML plan to a Bolt plan.
+          Convert a YAML plan to a Puppet language plan and print the converted plan to stdout.
 
           Converting a YAML plan may result in a plan that is syntactically
           correct but has different behavior. Always verify a converted plan's
-          functionality.
+          functionality. Note that the converted plan is not written to a file.
 
       EXAMPLES
           bolt plan convert path/to/plan/myplan.yaml
@@ -394,9 +459,9 @@ module Bolt
           the plan, including a list of available parameters.
 
       EXAMPLES
-          Display a list of available tasks
+          Display a list of available plans
             bolt plan show
-          Display documentation for the canary task
+          Display documentation for the aggregate::count plan
             bolt plan show aggregate::count
     HELP
 
@@ -444,10 +509,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
@@ -804,7 +866,7 @@ module Bolt
              "This option is experimental.") do |exec|
         @options[:'copy-command'] = exec
       end
-      define('--connect-timeout TIMEOUT', Integer, 'Connection timeout (defaults vary)') do |timeout|
+      define('--connect-timeout TIMEOUT', Integer, 'Connection timeout in seconds (defaults vary)') do |timeout|
         @options[:'connect-timeout'] = timeout
       end
       define('--[no-]tty', 'Request a pseudo TTY on targets that support it') do |tty|
@@ -840,9 +902,9 @@ module Bolt
       define('--modules MODULES',
              'A comma-separated list of modules to install from the Puppet Forge',
              'when initializing a project. Resolves and installs all dependencies.') do |modules|
-        @options[:modules] = modules.split(',')
+        @options[:modules] = modules.split(',').map { |mod| { 'name' => mod } }
       end
-      define('--force', 'Overwrite existing key pairs') do |_force|
+      define('--force', 'Force a destructive action') do |_force|
         @options[:force] = true
       end
 
@@ -863,7 +925,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|

data/lib/bolt/catalog.rb

@@ -57,8 +57,10 @@ module Bolt
 
     def compile_catalog(request)
       pdb_client = Bolt::PuppetDB::Client.new(Bolt::PuppetDB::Config.new(request['pdb_config']))
-      project = request['project'] || {}
-      bolt_project = Struct.new(:name, :path).new(project['name'], project['path']) unless project.empty?
+      project = request['project']
+      bolt_project = Struct.new(:name, :path, :load_as_module?).new(project['name'],
+                                                                    project['path'],
+                                                                    project['load_as_module?'])
       inv = Bolt::ApplyInventory.new(request['config'])
       puppet_overrides = {
         bolt_pdb_client: pdb_client,

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,15 @@ module Bolt
                  'inventory' => %w[show],
                  'group' => %w[show],
                  'project' => %w[init migrate],
-                 'apply' => %w[] }.freeze
+                 'apply' => %w[],
+                 'guide' => %w[],
+                 'module' => %w[install] }.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 +80,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 +168,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]) }
 
@@ -211,10 +211,14 @@ module Bolt
     end
 
     def validate(options)
-      unless COMMANDS.include?(options[:subcommand])
+      # Disables the 'module' subcommand unless the module feature flag is set.
+      commands = COMMANDS.dup
+      commands.delete('module') unless ENV['BOLT_MODULE_FEATURE']
+
+      unless commands.include?(options[:subcommand])
         raise Bolt::CLIError,
               "Expected subcommand '#{options[:subcommand]}' to be one of " \
-              "#{COMMANDS.keys.join(', ')}"
+              "#{commands.keys.join(', ')}"
       end
 
       actions = COMMANDS[options[:subcommand]]
@@ -354,7 +358,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[guide module project puppetfile secret].include?(options[:subcommand]) ||
              %w[convert new show].include?(options[:action])
         update_targets(options)
       end
@@ -411,7 +415,7 @@ module Bolt
         list_modules
         return 0
       when 'convert'
-        convert_plan(options[:object])
+        pal.convert_plan(options[:object])
         return 0
       end
 
@@ -422,12 +426,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]
@@ -436,12 +448,17 @@ module Bolt
         when 'run'
           code = run_plan(options[:object], options[:task_options], options[:target_args], options)
         end
+      when 'module'
+        case options[:action]
+        when 'install'
+          code = install_project_modules
+        end
       when 'puppetfile'
         case options[:action]
         when 'generate-types'
           code = generate_types
         when 'install'
-          code = install_puppetfile(config.puppetfile_config, config.puppetfile, config.modulepath)
+          code = install_puppetfile(config.puppetfile_config, config.puppetfile, config.modulepath.first)
         end
       when 'secret'
         code = Bolt::Secret.execute(plugins, outputter, options)
@@ -791,36 +808,38 @@ module Bolt
       old_config = project + 'bolt.yaml'
       config     = project + 'bolt-project.yaml'
       puppetfile = project + 'Puppetfile'
-      modulepath = [project + 'modules']
+      moduledir  = project + 'modules'
 
-      # If modules were specified, first check if there is already a Puppetfile at the project
-      # directory, erroring if there is. If there is no Puppetfile, generate the Puppetfile
-      # content by resolving the specified modules and all their dependencies.
-      # We generate the Puppetfile first so that any errors in resolving modules and their
-      # dependencies are caught early and do not create a project directory.
+      # 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}. Skipping file creation."
+      elsif old_config.exist?
+        @logger.warn "Found existing #{old_config.basename} at #{project}. "\
+                    "#{old_config.basename} is deprecated, please rename to #{config.basename}."
+      end
+
+      # If modules were specified, first check if there is already a Puppetfile
+      # at the project directory, erroring if there is. If there is no
+      # Puppetfile, install the specified modules. The module installer will
+      # resolve dependencies, generate a Puppetfile, and install the modules.
       if options[:modules]
         if puppetfile.exist?
           raise Bolt::CLIError,
-                "Found existing Puppetfile at #{puppetfile}, unable to initialize project with "\
-                "#{options[:modules].join(', ')}"
-        else
-          puppetfile_specs = resolve_puppetfile_specs
+                "Found existing Puppetfile at #{puppetfile}, unable to initialize "\
+                "project with modules."
         end
+
+        install_modules(puppetfile, {}, moduledir, options[:modules])
       end
 
-      # 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}. 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
-      else
+      # If either bolt.yaml or bolt-project.yaml exist, the user has already
+      # been warned and we can just finish project creation. Otherwise, create a
+      # bolt-project.yaml with the project name in it.
+      unless config.exist? || old_config.exist?
         begin
           content = { 'name' => name }
           File.write(config.to_path, content.to_yaml)
@@ -830,152 +849,82 @@ module Bolt
         end
       end
 
-      # Write the generated Puppetfile to the fancy new project
-      if puppetfile_specs
-        File.write(puppetfile, puppetfile_specs.join("\n"))
-        outputter.print_message "Successfully created Puppetfile at #{puppetfile}"
-        # Install the modules from our shiny new Puppetfile
-        if install_puppetfile({}, puppetfile, modulepath)
-          outputter.print_message "Successfully installed #{options[:modules].join(', ')}"
-        else
-          raise Bolt::CLIError, "Could not install #{options[:modules].join(', ')}"
-        end
-      end
-
       0
     end
 
-    # Resolves Puppetfile specs from user-specified modules and dependencies resolved
-    # by the puppetfile-resolver gem.
-    def resolve_puppetfile_specs
-      require 'puppetfile-resolver'
-
-      # Build the document model from the module names, defaulting to the latest version of each module
-      model = PuppetfileResolver::Puppetfile::Document.new('')
-      options[:modules].each do |mod_name|
-        model.add_module(
-          PuppetfileResolver::Puppetfile::ForgeModule.new(mod_name).tap { |mod| mod.version = :latest }
-        )
-      end
-
-      # Make sure the Puppetfile model is valid
-      unless model.valid?
-        raise Bolt::ValidationError,
-              "Unable to resolve dependencies for #{options[:modules].join(', ')}"
+    # Installs modules declared in the project configuration file.
+    #
+    def install_project_modules
+      if config.project.modules.nil?
+        outputter.print_message "Project configuration file '#{config.project.project_file}' "\
+                                "does not specify any module dependencies. Nothing to do."
+        return 0
       end
 
-      # Create the resolver using the Puppetfile model. nil disables Puppet version restrictions.
-      resolver = PuppetfileResolver::Resolver.new(model, nil)
-
-      # Configure and resolve the dependency graph
-      result = resolver.resolve(
-        cache:                 nil,
-        ui:                    nil,
-        module_paths:          [],
-        allow_missing_modules: true
+      install_modules(
+        config.puppetfile,
+        config.puppetfile_config,
+        config.project.path + '.modules',
+        config.project.modules
       )
+    end
 
-      # Validate that the modules exist
-      missing_graph = result.specifications.select do |_name, spec|
-        spec.instance_of? PuppetfileResolver::Models::MissingModuleSpecification
-      end
-
-      if missing_graph.any?
-        titles = model.modules.each_with_object({}) do |mod, acc|
-          acc[mod.name] = mod.title
+    # Installs modules declared in the project configuration file.
+    #
+    def install_modules(puppetfile_path, config, moduledir, modules)
+      require 'bolt/puppetfile'
+      require 'bolt/puppetfile/installer'
+
+      puppetfile = Bolt::Puppetfile.new(modules)
+
+      # If the Puppetfile exists, check if it includes specs for each declared
+      # module, erroring if there are any missing. Otherwise, resolve the
+      # module dependencies and write a new Puppetfile. Users can forcibly
+      # overwrite an existing Puppetfile with the '--force' option.
+      if puppetfile_path.exist? && !options[:force]
+        outputter.print_message "Parsing existing Puppetfile at #{puppetfile_path}"
+        existing = Bolt::Puppetfile.parse(puppetfile_path)
+
+        unless existing.modules.superset? puppetfile.modules
+          missing_modules = puppetfile.modules - existing.modules
+
+          raise Bolt::Error.new(
+            "Puppetfile #{puppetfile_path} is missing specifications for modules: "\
+            "#{missing_modules.map(&:title).join(', ')}. This may not be a Puppetfile "\
+            "managed by Bolt. To forcibly overwrite the Puppetfile, run with the "\
+            "'--force' option.",
+            'bolt/missing-module-specs'
+          )
         end
-
-        names = titles.values_at(*missing_graph.keys)
-        plural = names.count == 1 ? '' : 's'
-
-        raise Bolt::ValidationError,
-              "Unknown module name#{plural} #{names.join(', ')}"
-      end
-
-      # Filter the dependency graph to only include module specifications
-      spec_graph = result.specifications.select do |_name, spec|
-        spec.instance_of? PuppetfileResolver::Models::ModuleSpecification
-      end
-
-      # Map specification models to a Puppetfile specification
-      spec_graph.values.map do |spec|
-        "mod '#{spec.owner}-#{spec.name}', '#{spec.version}'"
+      else
+        outputter.print_message "Resolving module dependencies, this may take a moment"
+        puppetfile.resolve
+        outputter.print_message "Writing Puppetfile at #{puppetfile_path}"
+        puppetfile.write(puppetfile_path, force: true)
       end
-    end
 
-    def migrate_project
-      inventory_file = config.inventoryfile || config.default_inventoryfile
-      data = Bolt::Util.read_yaml_hash(inventory_file, 'inventory')
+      outputter.print_message "Syncing modules from #{puppetfile_path} to #{moduledir}"
+      ok = Bolt::Puppetfile::Installer.new(config).install(puppetfile_path, moduledir)
 
-      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
+      # Automatically generate types after installing modules.
+      pal.generate_types
 
+      outputter.print_puppetfile_result(ok, puppetfile_path, moduledir)
       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'
-
-      if puppetfile.exist?
-        moduledir = modulepath.first.to_s
-        r10k_opts = {
-          root: puppetfile.dirname.to_s,
-          puppetfile: puppetfile.to_s,
-          moduledir: moduledir
-        }
-
-        settings = R10K::Settings.global_settings.evaluate(config)
-        R10K::Initializers::GlobalInitializer.new(settings).call
-        install_action = R10K::Action::Puppetfile::Install.new(r10k_opts, nil)
+    # Loads a Puppetfile and installs its modules.
+    #
+    def install_puppetfile(config, puppetfile, moduledir)
+      require 'bolt/puppetfile/installer'
 
-        # Override the r10k logger with a proxy to our own logger
-        R10K::Logging.instance_variable_set(:@outputter, Bolt::R10KLogProxy.new)
+      ok = Bolt::Puppetfile::Installer.new(config).install(puppetfile, moduledir)
 
-        ok = install_action.call
-        outputter.print_puppetfile_result(ok, puppetfile, moduledir)
-        # Automatically generate types after installing modules
-        pal.generate_types
+      # Automatically generate types after installing modules.
+      pal.generate_types
 
-        ok ? 0 : 1
-      else
-        raise Bolt::FileError.new("Could not find a Puppetfile at #{puppetfile}", puppetfile)
-      end
-    rescue R10K::Error => e
-      raise PuppetfileError, e
+      outputter.print_puppetfile_result(ok, puppetfile, moduledir)
+      ok ? 0 : 1
     end
 
     def pal
@@ -988,8 +937,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)
@@ -1052,13 +1039,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?