bolt 3.11.0 → 3.15.0

data/bolt-modules/log/lib/puppet/functions/log/debug.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a debugging message.
+#
+# Messages logged at this level typically include detailed information about
+# what a plan is doing. For example, you might log a message at the `debug`
+# level that shows what value is returned from a function invocation.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::debug') do
+  # Log a debugging message.
+  # @param message The message to log.
+  # @example Log a debugging message
+  #   log::debug("Function frogsay returned: ${result}")
+  dispatch :log_debug do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_debug(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::debug'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :debug, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log an error message.
+#
+# Messages logged at this level typically indicate that the plan encountered an
+# error that can be recovered from. For example, you might log a message at the
+# `error` level if you want to inform the user an action running on a target
+# failed but that the plan will continue running.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::error') do
+  # Log an error message.
+  # @param message The message to log.
+  # @example Log an error message
+  #   log::error("The HTTP request returned an error, continuing the plan: ${result}")
+  dispatch :log_error do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_error(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::error'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :error, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/fatal.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a fatal message.
+#
+# Messages logged at this level indicate that the plan encountered an error that
+# could not be recovered from. For example, you might log a message at the
+# `fatal` level if a service is unavailable and the plan cannot continue running
+# without it.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::fatal') do
+  # Log a fatal message.
+  # @param message The message to log.
+  # @example Log a fatal message
+  #   log::fatal("The service is unavailable, unable to continue running: ${result}")
+  dispatch :log_fatal do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_fatal(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::fatal'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :fatal, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/info.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log an info message.
+#
+# Messages logged at this level typically include high-level information about
+# what a plan is doing. For example, you might log a message at the `info` level
+# that informs users that the plan is reading a file on disk.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::info') do
+  # Log an info message.
+  # @param message The message to log.
+  # @example Log an info message
+  #   log::info("Reading network device command file ${file}.")
+  dispatch :log_info do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_info(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::info'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :info, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/trace.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a trace message.
+#
+# Messages logged at this level typically include the most detailed information
+# about what a plan is doing. For example, you might log a message at the `trace`
+# level that describes how a plan is manipulating data.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::trace') do
+  # Log a trace message.
+  # @param message The message to log.
+  # @example Log a trace message
+  #   log::trace("Creating Target object with data ${data} from file ${file}")
+  dispatch :log_trace do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_trace(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::trace'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :trace, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/warn.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a warning message.
+#
+# Messages logged at this level typically include messages about deprecated
+# behavior or potentially harmful situations that might affect the plan run.
+# For example, you might log a message at the `warn` level if you are
+# planning to make a breaking change to your plan in a future release and
+# want to notify users.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::warn') do
+  # Log a warning message.
+  # @param message The message to log.
+  # @example Log a warning message
+  #   log::warn('This plan will no longer install the package in a future release.')
+  dispatch :log_warn do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_warn(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::warn'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :warn, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

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

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require 'bolt/util/format'
+
 # Output a message for the user.
 #
 # This will print a message to stdout when using the human output format,
-# and print to stderr when using the json output format
+# and print to stderr when using the json output format. Messages are
+# also logged at the `info` level. For more information about logs, see
+# [Logs](logs.md).
 #
 # > **Note:** Not available in apply block
 Puppet::Functions.create_function(:'out::message') do
@@ -22,55 +26,11 @@ Puppet::Functions.create_function(:'out::message') do
         .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'out::message')
     end
 
-    executor = Puppet.lookup(:bolt_executor)
-    # Send Analytics Report
-    executor.report_function_call(self.class.name)
-
-    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
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :message, message: Bolt::Util::Format.stringify(message), level: :info)
     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
+    nil
   end
 end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Output a message for the user when running in verbose mode.
+#
+# This will print a message to stdout when using the human output format,
+# and print to stderr when using the json output format. Messages are
+# also logged at the `debug` level. For more information about logs, see
+# [Logs](logs.md).
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'out::verbose') do
+  # @param message The message to output.
+  # @example Print a message
+  #   out::verbose('Something went wrong')
+  dispatch :output_verbose do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def output_verbose(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'out::verbose')
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :verbose, message: Bolt::Util::Format.stringify(message), level: :debug)
+    end
+
+    nil
+  end
+end

data/guides/{debugging.txt → debugging.yaml}

@@ -1,7 +1,6 @@
-TOPIC
-    debugging
-
-DESCRIPTION
+---
+topic: debugging
+guide: |
     When Bolt isn't behaving as expected, there are a few helpful commands and
     logs that can help identify common issues. The first place to look is in
     `<PROJECT>/bolt-debug.log`, which contains debug-level logs from the last Bolt
@@ -24,5 +23,5 @@ DESCRIPTION
     Visit the linked documentation for more in-depth troubleshooting help for
     specific issues.
 
-DOCUMENTATION
-    https://pup.pt/bolt-troubleshooting
+documentation:
+  - https://pup.pt/bolt-troubleshooting

data/guides/{inventory.txt → inventory.yaml}

@@ -1,7 +1,6 @@
-TOPIC
-    inventory
-
-DESCRIPTION
+---
+topic: inventory
+guide: |
     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
@@ -19,6 +18,6 @@ DESCRIPTION
     target in multiple groups, this might result in target configuration that
     is different than expected.
 
-DOCUMENTATION
-    https://pup.pt/bolt-inventory
-    https://pup.pt/bolt-inventory-reference
+documentation:
+  - https://pup.pt/bolt-inventory
+  - https://pup.pt/bolt-inventory-reference

data/guides/{links.txt → links.yaml}

@@ -1,7 +1,6 @@
-TOPIC
-    links
-
-DESCRIPTION
+---
+topic: links
+guide: |
     Bolt documentation          https://bolt.guide
     Ask a question in #bolt     https://slack.puppet.com/
     Contribute at               https://github.com/puppetlabs/bolt/

data/guides/{logging.txt → logging.yaml}

@@ -1,7 +1,6 @@
-TOPIC
-    logging
-
-DESCRIPTION
+---
+topic: logging
+guide: |
     Bolt prints messages both to the console and to log files. Messages can
     either come from Bolt's 'outputter', which logs user-facing messages like
     progress and results, or from the 'logger', which logs warnings, errors, and
@@ -14,5 +13,5 @@ DESCRIPTION
 
     To learn more about projects, see the 'project' guide.
 
-DOCUMENTATION
-    https://pup.pt/bolt-logging
+documentation:
+  - https://pup.pt/bolt-logging

data/guides/{module.txt → module.yaml}

@@ -1,7 +1,6 @@
-TOPIC
-    module
-
-DESCRIPTION
+---
+topic: module
+guide: |
     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
@@ -15,5 +14,5 @@ DESCRIPTION
     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
+documentation:
+  - https://pup.pt/bolt-modules