bolt 2.31.0 → 2.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b9f29b79c8544029c9a69f6dc76b083857a87e178c9aae0359e49c59ce3cfdb
-  data.tar.gz: 02166a6dda2dc381365b7556f506a419e2717267e88f6015af430f7f725d75d0
+  metadata.gz: 5b010e9146d3269d88005be58db6b788f57ea3046f96f28756641b0c7266eec2
+  data.tar.gz: ce8d15031143acabc664a7025ef004c69211c25316f9691783388ba74e61dec9
 SHA512:
-  metadata.gz: 3a282194ca9ccf988e7282afc3a3a0b57b4edc16bb5bf61790fb0eb0ef234e0c7a76c0ea6cd44915047a99e6d423311be1307f435d8000c568d0552268f6afa6
-  data.tar.gz: 957e6be1a72af03bd448fe070e6f9bb0b78aa1bb65e90a8bda251ef0f6c56e5ffaa8ff64aa0c5852963d9fecb87144b61ffd24494fe0aabcbdff43ecde9947a3
+  metadata.gz: b45657eb2b985f8e97c59ff4603ad049fd17ee6585292463a57bde3b5c7ca55451883b5e88cb0f61e55c05f1d5415cbde3874320ae446124d646a3d3e8ffa812
+  data.tar.gz: 673e3f3310bf4f22602153bf8300851fa3a832db8e73abc9352874bea7c0b1fd50a5baa42d18474885caea7ec9fad4aa50c25f44aa27974097e10ea03b31e07e

data/Puppetfile

@@ -34,7 +34,7 @@ mod 'puppetlabs-stdlib', '6.5.0'
 mod 'puppetlabs-aws_inventory', '0.5.2'
 mod 'puppetlabs-azure_inventory', '0.4.1'
 mod 'puppetlabs-gcloud_inventory', '0.1.3'
-mod 'puppetlabs-http_request', '0.1.0'
+mod 'puppetlabs-http_request', '0.2.0'
 mod 'puppetlabs-pkcs7', '0.1.1'
 mod 'puppetlabs-terraform', '0.5.0'
 mod 'puppetlabs-vault', '0.3.0'

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

@@ -26,8 +26,51 @@ Puppet::Functions.create_function(:'out::message') do
     # Send Analytics Report
     executor.report_function_call(self.class.name)
 
-    executor.publish_event(type: :message, message: message)
+    executor.publish_event(type: :message, message: stringify(message))
 
     nil
   end
+
+  def stringify(message)
+    formatted = format_message(message)
+    if formatted.is_a?(Hash) || formatted.is_a?(Array)
+      ::JSON.pretty_generate(formatted)
+    else
+      formatted
+    end
+  end
+
+  def format_message(message)
+    case message
+    when Array
+      message.map { |item| format_message(item) }
+    when Bolt::ApplyResult
+      format_apply_result(message)
+    when Bolt::Result, Bolt::ResultSet
+      # This is equivalent to to_s, but formattable
+      message.to_data
+    when Bolt::RunFailure
+      formatted_resultset = message.result_set.to_data
+      message.to_h.merge('result_set' => formatted_resultset)
+    when Hash
+      message.each_with_object({}) do |(k, v), h|
+        h[format_message(k)] = format_message(v)
+      end
+    when Integer, Float, NilClass
+      message
+    else
+      message.to_s
+    end
+  end
+
+  def format_apply_result(result)
+    logs = result.resource_logs&.map do |log|
+      # Omit low-level info/debug messages
+      next if %w[info debug].include?(log['level'])
+      indent(2, format_log(log))
+    end
+    hash = result.to_data
+    hash['logs'] = logs unless logs.empty?
+    hash
+  end
 end

data/bolt-modules/prompt/lib/puppet/functions/prompt.rb

@@ -9,11 +9,14 @@ Puppet::Functions.create_function(:prompt) do
   # @param prompt The prompt to display.
   # @param options A hash of additional options.
   # @option options [Boolean] sensitive Disable echo back and mark the response as sensitive.
+  #   The returned value will be wrapped by the `Sensitive` data type. To access the raw
+  #   value, use the `unwrap` function (i.e. `$sensitive_value.unwrap`).
   # @return The response to the prompt.
   # @example Prompt the user if plan execution should continue
   #   $response = prompt('Continue executing plan? [Y\N]')
   # @example Prompt the user for sensitive information
   #   $password = prompt('Enter your password', 'sensitive' => true)
+  #   out::message("Password is: ${password.unwrap}")
   dispatch :prompt do
     param 'String', :prompt
     optional_param 'Hash[String[1], Any]', :options

data/guides/module.txt

@@ -0,0 +1,19 @@
+TOPIC
+    module
+
+DESCRIPTION
+    Modules are shareable, reusable packages of Puppet content. They can include
+    tasks, plans, functions, and other types of content that you can use in your
+    project. You can download and install modules to your project from the
+    Puppet Forge or write your own modules. Bolt also ships with several helpful
+    modules pre-installed that are available to all of your projects.
+
+    Bolt makes it easy to manage the modules that your project depends on. You
+    can use Bolt commands to install a project's modules, add new modules to a
+    project, and view the modules that are available to the project.
+    
+    To learn more about managing modules in a project, see the documentation.
+    To learn how modules are loaded by Bolt, see the 'modulepath' guide.
+
+DOCUMENTATION
+    https://pup.pt/bolt-modules

data/guides/modulepath.txt

@@ -0,0 +1,25 @@
+TOPIC
+    modulepath
+
+DESCRIPTION
+    The modulepath is an ordered list of directories that Bolt loads modules
+    from. When Bolt runs a command, it automatically loads modules from the
+    modulepath.
+    
+    While Bolt has a default modulepath, you can also configure your own
+    modulepath, which can include directories within the project or directories
+    elsewhere on your system. Regardless of whether your project uses a default
+    or configured modulepath, Bolt automatically adds directories to the
+    modulepath. This includes modules containing core Bolt content, which is
+    added to the beginning of the modulepath, and bundled content, which is
+    added to the end of the modulepath.
+
+    Modules loaded from a directory listed earlier in the modulepath take
+    precedence over modules with the same name loaded from a directory later in
+    the modulepath. Bolt will not warn or error when two modules share a name
+    and instead will ignore modules with a lower precedence.
+
+    To learn more about modules, see the 'module' guide.
+
+DOCUMENTATION
+    https://pup.pt/bolt-project-reference#modulepath

data/lib/bolt/config/options.rb

@@ -234,26 +234,44 @@ module Bolt
           type: Array,
           items: {
             type: [Hash, String],
-            required: ["name"],
-            properties: {
-              "name" => {
-                description: "The name of the module.",
-                type: String
+            oneOf: [
+              {
+                required: ["name"],
+                properties: {
+                  "name" => {
+                    description: "The name of the module.",
+                    type: String
+                  },
+                  "version_requirement" => {
+                    description: "The version requirement for the module. Accepts a specific version (1.2.3), version "\
+                                 "shorthand (1.2.x), or a version range (>= 1.2.0).",
+                    type: String
+                  }
+                }
               },
-              "version_requirement" => {
-                description: "The version requirement for the module. Accepts a specific version (1.2.3), version "\
-                             "shorthand (1.2.x), or a version range (>= 1.2.0).",
-                type: String
+              {
+                required: %w[git ref],
+                properties: {
+                  "git" => {
+                    description: "The URL to the public git repository.",
+                    type: String
+                  },
+                  "ref" => {
+                    description: "The git reference to check out. Can be either a branch, tag, or commit SHA.",
+                    type: String
+                  }
+                }
               }
-            }
+            ]
           },
           _plugin: false,
           _example: [
-            { "name" => "puppetlabs-mysql" },
             "puppetlabs-facts",
+            { "name" => "puppetlabs-mysql" },
             { "name" => "puppetlabs-apache", "version_requirement" => "5.5.0" },
             { "name" => "puppetlabs-puppetdb", "version_requirement" => "7.x" },
-            { "name" => "puppetlabs-firewall", "version_requirement" => ">= 1.0.0 < 3.0.0" }
+            { "name" => "puppetlabs-firewall", "version_requirement" => ">= 1.0.0 < 3.0.0" },
+            { "git" => "https://github.com/puppetlabs/puppetlabs-apt", "ref" => "7.6.0" }
           ]
         },
         "name" => {
@@ -329,7 +347,7 @@ module Bolt
             "server_urls" => {
               description: "An array containing the PuppetDB host to connect to. Include the protocol `https` "\
                            "and the port, which is usually `8081`. For example, "\
-                           "`https://my-master.example.com:8081`.",
+                           "`https://my-puppetdb-server.com:8081`.",
               type: Array,
               _example: ["https://puppet.example.com:8081"]
             },

data/lib/bolt/module_installer.rb

@@ -2,6 +2,10 @@
 
 require 'bolt/error'
 require 'bolt/logger'
+require 'bolt/module_installer/installer'
+require 'bolt/module_installer/puppetfile'
+require 'bolt/module_installer/resolver'
+require 'bolt/module_installer/specs'
 
 module Bolt
   class ModuleInstaller
@@ -13,45 +17,53 @@ module Bolt
 
     # Adds a single module to the project.
     #
-    def add(name, modules, puppetfile_path, moduledir, config_path)
-      require 'bolt/puppetfile'
-
-      @outputter.print_message("Adding module #{name} to project\n\n")
-
-      # If the project configuration file already includes this module,
-      # exit early.
-      puppetfile  = Bolt::Puppetfile.new(modules)
-      new_module  = Bolt::Puppetfile::Module.from_hash('name' => name)
-
-      if puppetfile.modules.include?(new_module)
-        @outputter.print_action_step(
-          "Project configuration file #{config_path} already includes module #{new_module}. Nothing to do."
+    def add(name, specs, puppetfile_path, moduledir, config_path)
+      project_specs = Specs.new(specs)
+
+      # Exit early if project config already includes a spec with this name.
+      if project_specs.include?(name)
+        @outputter.print_message(
+          "Project configuration file #{config_path} already includes specification with name "\
+          "#{name}. Nothing to do."
         )
         return true
       end
 
-      # If the Puppetfile exists, make sure it's managed by Bolt.
-      if puppetfile_path.exist?
-        assert_managed_puppetfile(puppetfile, puppetfile_path)
-        existing = Bolt::Puppetfile.parse(puppetfile_path)
-      else
-        existing = Bolt::Puppetfile.new
-      end
+      @outputter.print_message("Adding module #{name} to project\n\n")
 
-      # Create a Puppetfile object that includes the new module and its
-      # dependencies. We error early here so we don't add the new module to the
-      # project config or modify the Puppetfile.
-      puppetfile = add_new_module_to_puppetfile(new_module, modules, puppetfile_path)
+      # Generate the specs to resolve from. If a Puppetfile exists, parse it and
+      # convert the modules to specs. Otherwise, use the project specs.
+      resolve_specs = if puppetfile_path.exist?
+                        existing_puppetfile = Puppetfile.parse(puppetfile_path)
+                        existing_puppetfile.assert_satisfies(project_specs)
+                        Specs.from_puppetfile(existing_puppetfile)
+                      else
+                        project_specs
+                      end
+
+      # Resolve module dependencies. Attempt to first resolve with resolve
+      # specss. If that fails, fall back to resolving from project specs.
+      # This prevents Bolt from modifying installed modules unless there is
+      # a version conflict.
+      @outputter.print_action_step("Resolving module dependencies, this may take a moment")
+
+      begin
+        resolve_specs.add_specs('name' => name)
+        puppetfile = Resolver.new.resolve(resolve_specs)
+      rescue Bolt::Error
+        project_specs.add_specs('name' => name)
+        puppetfile = Resolver.new.resolve(project_specs)
+      end
 
       # Display the diff between the existing Puppetfile and the new Puppetfile.
-      print_puppetfile_diff(existing, puppetfile)
+      print_puppetfile_diff(existing_puppetfile, puppetfile)
 
       # Add the module to the project configuration.
       @outputter.print_action_step("Updating project configuration file at #{config_path}")
 
       data = Bolt::Util.read_yaml_hash(config_path, 'project')
       data['modules'] ||= []
-      data['modules'] <<  { 'name' => new_module.title }
+      data['modules'] << name
 
       begin
         File.write(config_path, data.to_yaml)
@@ -70,130 +82,97 @@ module Bolt
       install_puppetfile(puppetfile_path, moduledir)
     end
 
-    # Creates a new Puppetfile that includes the new module and its dependencies.
-    #
-    private def add_new_module_to_puppetfile(new_module, modules, path)
-      @outputter.print_action_step("Resolving module dependencies, this may take a moment")
-
-      # If there is an existing Puppetfile, add the new module and attempt
-      # to resolve. This will not update the versions of any installed modules.
-      if path.exist?
-        puppetfile = Bolt::Puppetfile.parse(path)
-        puppetfile.add_modules(new_module)
-
-        begin
-          puppetfile.resolve
-          return puppetfile
-        rescue Bolt::Error
-          @logger.debug "Unable to find a version of #{new_module} compatible "\
-                        "with installed modules. Attempting to re-resolve modules "\
-                        "from project configuration; some versions of installed "\
-                        "modules may change."
-        end
-      end
-
-      # If there is not an existing Puppetfile, or resolving with pinned
-      # modules fails, resolve all of the module declarations with the new
-      # module.
-      puppetfile = Bolt::Puppetfile.new(modules)
-      puppetfile.add_modules(new_module)
-      puppetfile.resolve
-      puppetfile
-    end
-
     # Outputs a diff of an old Puppetfile and a new Puppetfile.
     #
     def print_puppetfile_diff(old, new)
-      # Build hashes mapping the module title to the module object. This makes it
+      # Build hashes mapping the module name to the module object. This makes it
       # a little easier to determine which modules have been added, removed, or
       # modified.
-      old = old.modules.each_with_object({}) do |mod, acc|
-        acc[mod.title] = mod
+      old = (old&.modules || []).each_with_object({}) do |mod, acc|
+        next unless mod.type == :forge
+        acc[mod.full_name] = mod
       end
 
       new = new.modules.each_with_object({}) do |mod, acc|
-        acc[mod.title] = mod
+        next unless mod.type == :forge
+        acc[mod.full_name] = mod
       end
 
       # New modules are those present in new but not in old.
-      added = new.reject { |title, _mod| old.include?(title) }.values
+      added = new.reject { |full_name, _mod| old.include?(full_name) }.values
 
       if added.any?
         diff = "Adding the following modules:\n"
-        added.each { |mod| diff += "#{mod.title} #{mod.version}\n" }
+        added.each { |mod| diff += "#{mod.full_name} #{mod.version}\n" }
         @outputter.print_action_step(diff)
       end
 
       # Upgraded modules are those that have a newer version in new than old.
-      upgraded = new.select do |title, mod|
-        if old.include?(title)
-          SemanticPuppet::Version.parse(mod.version) > SemanticPuppet::Version.parse(old[title].version)
+      upgraded = new.select do |full_name, mod|
+        if old.include?(full_name)
+          mod.version > old[full_name].version
         end
       end.keys
 
       if upgraded.any?
         diff = "Upgrading the following modules:\n"
-        upgraded.each { |title| diff += "#{title} #{old[title].version} to #{new[title].version}\n" }
+        upgraded.each { |full_name| diff += "#{full_name} #{old[full_name].version} to #{new[full_name].version}\n" }
         @outputter.print_action_step(diff)
       end
 
       # Downgraded modules are those that have an older version in new than old.
-      downgraded = new.select do |title, mod|
-        if old.include?(title)
-          SemanticPuppet::Version.parse(mod.version) < SemanticPuppet::Version.parse(old[title].version)
+      downgraded = new.select do |full_name, mod|
+        if old.include?(full_name)
+          mod.version < old[full_name].version
         end
       end.keys
 
       if downgraded.any?
         diff = "Downgrading the following modules: \n"
-        downgraded.each { |title| diff += "#{title} #{old[title].version} to #{new[title].version}\n" }
+        downgraded.each { |full_name| diff += "#{full_name} #{old[full_name].version} to #{new[full_name].version}\n" }
         @outputter.print_action_step(diff)
       end
 
       # Removed modules are those present in old but not in new.
-      removed = old.reject { |title, _mod| new.include?(title) }.values
+      removed = old.reject { |full_name, _mod| new.include?(full_name) }.values
 
       if removed.any?
         diff = "Removing the following modules:\n"
-        removed.each { |mod| diff += "#{mod.title} #{mod.version}\n" }
+        removed.each { |mod| diff += "#{mod.full_name} #{mod.version}\n" }
         @outputter.print_action_step(diff)
       end
     end
 
     # Installs a project's module dependencies.
     #
-    def install(modules, path, moduledir, force: false, resolve: true)
-      require 'bolt/puppetfile'
-
+    def install(specs, path, moduledir, force: false, resolve: true)
       @outputter.print_message("Installing project modules\n\n")
 
-      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, or opt to
-      # install the Puppetfile as-is with --no-resolve.
-      #
-      # This is just if resolve is not false (nil should default to true)
       if resolve != false
-        if path.exist? && !force
-          assert_managed_puppetfile(puppetfile, path)
-        else
+        specs = Specs.new(specs)
+
+        # If forcibly installing or if there is no Puppetfile, resolve
+        # and write a Puppetfile.
+        if force || !path.exist?
           @outputter.print_action_step("Resolving module dependencies, this may take a moment")
-          puppetfile.resolve
+          puppetfile = Resolver.new.resolve(specs)
 
-          @outputter.print_action_step("Writing Puppetfile at #{path}")
           # We get here either through 'bolt module install' which uses the
           # managed modulepath (which isn't configurable) or through bolt
           # project init --modules, which uses the default modulepath. This
           # should be safe to assume that if `.modules/` is the moduledir the
           # user is using the new workflow
+          @outputter.print_action_step("Writing Puppetfile at #{path}")
           if moduledir.basename.to_s == '.modules'
             puppetfile.write(path, moduledir)
           else
             puppetfile.write(path)
           end
+        # If not forcibly installing and there is a Puppetfile, assert
+        # that it satisfies the specs.
+        else
+          puppetfile = Puppetfile.parse(path)
+          puppetfile.assert_satisfies(specs)
         end
       end
 
@@ -204,10 +183,8 @@ module Bolt
     # Installs the Puppetfile and generates types.
     #
     def install_puppetfile(path, moduledir, config = {})
-      require 'bolt/puppetfile/installer'
-
       @outputter.print_action_step("Syncing modules from #{path} to #{moduledir}")
-      ok = Bolt::Puppetfile::Installer.new(config).install(path, moduledir)
+      ok = Installer.new(config).install(path, moduledir)
 
       # Automatically generate types after installing modules
       @pal.generate_types
@@ -216,27 +193,5 @@ module Bolt
 
       ok
     end
-
-    # Asserts that an existing Puppetfile is managed by Bolt.
-    #
-    private def assert_managed_puppetfile(puppetfile, path)
-      existing_puppetfile = Bolt::Puppetfile.parse(path)
-
-      unless existing_puppetfile.modules.superset? puppetfile.modules
-        missing_modules = puppetfile.modules - existing_puppetfile.modules
-
-        message = <<~MESSAGE.chomp
-          Puppetfile #{path} is missing specifications for the following
-          module declarations:
-
-          #{missing_modules.map(&:to_hash).to_yaml.lines.drop(1).join.chomp}
-          
-          This may not be a Puppetfile managed by Bolt. To forcibly overwrite the
-          Puppetfile, run 'bolt module install --force'.
-        MESSAGE
-
-        raise Bolt::Error.new(message, 'bolt/missing-module-specs')
-      end
-    end
   end
 end