openbolt 5.0.0.rc1

data/bolt-modules/file/lib/puppet/functions/file/readable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Check if a local file is readable using Puppet's
+# `Puppet::Parser::Files.find_file()` function. This will only check files on the
+# machine you run Bolt on.
+Puppet::Functions.create_function(:'file::readable', Puppet::Functions::InternalFunction) do
+  # @param filename Absolute path or Puppet file path.
+  # @return Whether the file is readable.
+  # @example Check a file on disk
+  #   file::readable('/tmp/i_dumped_this_here')
+  # @example check a file from the modulepath
+  #   file::readable('example/VERSION')
+  dispatch :readable do
+    scope_param
+    required_param 'String[1]', :filename
+    return_type 'Boolean'
+  end
+
+  def readable(scope, filename)
+    # Send Analytics Report
+    executor = Puppet.lookup(:bolt_executor) {}
+    executor&.report_function_call(self.class.name)
+
+    # Find the file path if it exists, otherwise return nil
+    found = Bolt::Util.find_file_from_scope(filename, scope)
+    found ? File.readable?(found) : false
+  end
+end

data/bolt-modules/file/lib/puppet/functions/file/write.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Write a string to a file on localhost using ruby's `File.write`. This will
+# only write files to the machine you run Bolt on. Use `write_file()` to write
+# to remote targets.
+Puppet::Functions.create_function(:'file::write') do
+  # @param filename Absolute path.
+  # @param content File content to write.
+  # @example Write a file to disk
+  #   file::write('C:/Users/me/report', $apply_result.first.report)
+  dispatch :write do
+    required_param 'String', :filename
+    required_param 'String', :content
+    return_type 'Undef'
+  end
+
+  def write(filename, content)
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+
+    File.write(filename, content)
+    nil
+  end
+end

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

@@ -0,0 +1,36 @@
+# 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. 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
+  # Output a message.
+  # @param message The message to output.
+  # @example Print a message
+  #   out::message('Something went wrong')
+  dispatch :output_message do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def output_message(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'out::message')
+    end
+
+    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
+
+    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/bolt-modules/prompt/lib/puppet/functions/prompt/menu.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Display a menu prompt and wait for a response. Continues to prompt
+# until an option from the menu is selected.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'prompt::menu') do
+  # Select from a list of options.
+  # @param prompt The prompt to display.
+  # @param menu A list of options to choose from.
+  # @param options A hash of additional options.
+  # @option options [String] default The default option to return if the user does not provide
+  #   input or if standard in (stdin) is not a tty. Must be an option present in the menu.
+  # @return The selected option.
+  # @example Prompt the user to select from a list of options
+  #   $selection = prompt::menu('Select a fruit', ['apple', 'banana', 'carrot'])
+  # @example Prompt the user to select from a list of options with a default value
+  #   $selection = prompt::menu('Select environment', ['development', 'production'], 'default' => 'development')
+  dispatch :prompt_menu_array do
+    param 'String', :prompt
+    param 'Array[Variant[Target, Data]]', :menu
+    optional_param 'Hash[String[1], Variant[Target, Data]]', :options
+    return_type 'Variant[Target, Data]'
+  end
+
+  # Select from a list of options with custom inputs.
+  # @param prompt The prompt to display.
+  # @param menu A hash of options to choose from, where keys are the input used to select a value.
+  # @param options A hash of additional options.
+  # @option options [String] default The default option to return if the user does not provide
+  #   input or if standard in (stdin) is not a tty. Must be an option present in the menu.
+  # @return The selected option.
+  # @example Prompt the user to select from a list of options with custom inputs
+  #   $menu = { 'y' => 'yes', 'n' => 'no' }
+  #   $selection = prompt::menu('Install Puppet?', $menu)
+  dispatch :prompt_menu do
+    param 'String', :prompt
+    param 'Hash[String[1], Variant[Target, Data]]', :menu
+    optional_param 'Hash[String[1], Variant[Target, Data]]', :options
+    return_type 'Variant[TargetSpec, Data]'
+  end
+
+  def prompt_menu_array(prompt, menu, options = {})
+    menu_hash = menu.map.with_index { |value, index| [(index + 1).to_s, value] }.to_h
+    prompt_menu(prompt, menu_hash, options)
+  end
+
+  def prompt_menu(prompt, menu, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'prompt::menu')
+    end
+
+    options  = options.transform_keys(&:to_sym)
+    executor = Puppet.lookup(:bolt_executor)
+
+    # Send analytics report
+    executor.report_function_call(self.class.name)
+
+    # Error if there are no options
+    if menu.empty?
+      raise Bolt::ValidationError, "Menu cannot be empty"
+    end
+
+    # Error if the default value is not on the menu
+    if options.key?(:default) && !menu.value?(options[:default])
+      raise Bolt::ValidationError, "Default value '#{options[:default]}' is not one of the provided menu options"
+    end
+
+    # The first prompt should include the menu
+    to_prompt = format_menu(menu) + prompt
+
+    # Request input from the user until they provide a valid option
+    loop do
+      selection = executor.prompt(to_prompt, options)
+
+      return menu[selection] if menu.key?(selection)
+      return selection       if options.key?(:default) && options[:default] == selection
+
+      # Only reprint the prompt, not the menu
+      to_prompt = "Invalid option, try again. #{prompt}"
+    end
+  end
+
+  # Builds the menu string. Aligns all the values by padding input keys.
+  #
+  private def format_menu(menu)
+    # Find the longest input and add 2 for wrapping parenthesis
+    key_length = menu.keys.max_by(&:length).length + 2
+
+    menu_string = +''
+
+    menu.each do |key, value|
+      key = "(#{key})".ljust(key_length)
+      menu_string << "#{key} #{value}\n"
+    end
+
+    menu_string
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Display a prompt and wait for a response.
+#
+# > **Note:** Not available in apply block
+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`).
+  # @option options [String] default The default value to return if the user does not provide
+  #   input or if stdin is not a tty.
+  # @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}")
+  # @example Prompt the user and provide a default value
+  #   $user = prompt('Enter your login username', 'default' => 'root')
+  # @example Prompt the user for sensitive information, returning a sensitive default if one is not provided
+  #   $token = prompt('Enter token', 'default' => lookup('default_token'), 'sensitive' => true)
+  #   out::message("Token is: ${token.unwrap}")
+  # @example Prompt the user and fail with a custom message if no input was provided
+  #   $response = prompt('Enter your name', 'default' => '')
+  #   if $response.empty {
+  #     fail_plan('Must provide your name')
+  #   }
+  dispatch :prompt do
+    param 'String', :prompt
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'Variant[String, Sensitive]'
+  end
+
+  def prompt(prompt, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'prompt')
+    end
+
+    options  = options.transform_keys(&:to_sym)
+    executor = Puppet.lookup(:bolt_executor)
+
+    # Send analytics report
+    executor.report_function_call(self.class.name)
+
+    # Require default to be a string value
+    if options.key?(:default) && !options[:default].is_a?(String)
+      raise Bolt::ValidationError, "Option 'default' must be a string"
+    end
+
+    response = executor.prompt(prompt, options)
+
+    # If sensitive, wrap it
+    if options[:sensitive]
+      Puppet::Pops::Types::PSensitiveType::Sensitive.new(response)
+    else
+      response
+    end
+  end
+end

data/bolt-modules/system/lib/puppet/functions/system/env.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Get an environment variable.
+Puppet::Functions.create_function(:'system::env') do
+  # @param name Environment variable name.
+  # @return The environment variable's value.
+  # @example Get the USER environment variable
+  #   system::env('USER')
+  dispatch :env do
+    required_param 'String', :name
+    return_type 'Optional[String]'
+  end
+
+  def env(name)
+    # Send analytics report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+
+    ENV[name]
+  end
+end

data/exe/bolt

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bolt'
+require 'bolt/cli'
+
+Thread.current[:name] ||= 'main'
+cli = Bolt::CLI.new(ARGV)
+begin
+  opts = cli.parse
+  exitcode = cli.execute(opts)
+  exit exitcode
+rescue Bolt::CLIExit
+  exit
+rescue Bolt::Error => e
+  exit e.error_code
+end

data/guides/debugging.yaml

@@ -0,0 +1,27 @@
+---
+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
+    run. This log file includes where the Bolt project was loaded from, the
+    location of any configuration or inventory files that were loaded, and the
+    modulepath that modules were loaded from.
+
+    If you're having issues with loading targets or target configuration, you
+    can see the list of resolved Bolt target names by running `bolt inventory
+    show` on *nix systems or `Get-BoltInventory` in PowerShell. To see the
+    resolved configuration for each target, run the command with the `--detail` or
+    `-Detail` options.
+
+    Lastly, if you're having trouble loading Bolt content you can use `bolt
+    module show` on *nix systems or `Get-BoltModule` in PowerShell to see the list
+    of loaded modules, including where they were loaded from. You can also use
+    `bolt task show` or `Get-BoltTask` to list loaded tasks, and `bolt plan show`
+    or `Get-BoltPlan` to list loaded plans.
+
+    Visit the linked documentation for more in-depth troubleshooting help for
+    specific issues.
+
+documentation:
+  - https://pup.pt/bolt-troubleshooting

data/guides/inventory.yaml

@@ -0,0 +1,23 @@
+---
+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
+    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.
+
+    When Bolt loads inventory, it loads the entire inventory, not just the
+    groups and targets specified on the command line. If you've defined a
+    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

data/guides/links.yaml

@@ -0,0 +1,12 @@
+---
+topic: links
+guide: |
+    Bolt documentation          https://bolt.guide
+    Ask a question in #bolt     https://slack.puppet.com/
+    Contribute at               https://github.com/puppetlabs/bolt/
+    Getting Started Guide       https://pup.pt/bolt-getting-started
+    Reference Documentation     https://pup.pt/bolt-reference
+    Troubleshooting Bolt        https://pup.pt/bolt-troubleshooting
+    Bolt Developer Updates      https://pup.pt/bolt-dev-updates
+    Bolt Changelog              https://pup.pt/bolt-changelog
+    Bolt Examples               https://pup.pt/bolt-examples

data/guides/logging.yaml

@@ -0,0 +1,17 @@
+---
+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
+    log-structured output to log files. Both of these message streams are
+    configurable.
+
+    By default, Bolt logs to the console at 'warn' level and writes a log file to
+    '<project>/bolt-debug.log' at 'debug' level. Unless you are running a plan,
+    Bolt runs in verbose mode by default.
+
+    To learn more about projects, see the 'project' guide.
+
+documentation:
+  - https://pup.pt/bolt-logging