bolt 3.14.1 → 3.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9dbc0b26225fd929d594a6719b55491bad8647650d257b0bbd1bf0eb2424f7c
-  data.tar.gz: ff0df82a3a02edfbf05bdbfe39814d2d5535719dbb6b80659bfff5d28651da3a
+  metadata.gz: 53659858c8aae545c73cd8ef74ce2fda41c024d0040cf2c1dc935985d28d53e3
+  data.tar.gz: 59909ae1b57566430f66f472e453ab16341ca530b2ac3b1036a4deefd269564e
 SHA512:
-  metadata.gz: 61a484916431f7da5b3fa8992641bdf382f0d34eaf2f054e41638e27dc48b7118c07f7729a54246a0d6e19e2a74cedc549fdcc513ba26651f84b470f2c7b187e
-  data.tar.gz: d5bf6f496c13253e83dd7d9625058846000a5b339a13fd8d6d922b61ed57b61618125c5de76377f1e01d946e16bd220313659cc066ec793527a2c03013264bc0
+  metadata.gz: 6e76fe56e10409ce22d1a849adf3bbbce19c838dfbb6cb3bb8461f7a642c150a9a17beac13a08f4273ebcbf781ee0d63dd3db6b7a034a2f15d9f300a94a8a16d
+  data.tar.gz: c109c02ee6fb38a0ffae8abc57709d60952c8a158edb45774344ae44df3a3d6689385924eddaefea40ed437ab7d73455d8aebf2a59c81ff7c7bce5651abdde68

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

@@ -8,16 +8,18 @@ require 'bolt/task'
 # installed using either the configured plugin or the `task` plugin with the
 # `puppet_agent::install` task.
 #
-# Agent installation will be skipped if the target includes the `puppet-agent` feature, either as a
-# property of its transport (PCP) or by explicitly setting it as a feature in Bolt's inventory.
+# Agent installation will be skipped if the target includes the `puppet-agent`
+# feature, either as a property of its transport (PCP) or by explicitly setting
+# it as a feature in Bolt's inventory.
 #
 # > **Note:** Not available in apply block
 Puppet::Functions.create_function(:apply_prep) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param options Options hash.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [Array] _required_modules An array of modules to sync to the target.
   # @option options [String] _run_as User to run as using privilege escalation.
-  # @return [nil]
+  # @return [Bolt::ResultSet]
   # @example Prepare targets by name.
   #   apply_prep('target1,target2')
   dispatch :apply_prep do
@@ -25,138 +27,169 @@ Puppet::Functions.create_function(:apply_prep) do
     optional_param 'Hash[String, Data]', :options
   end
 
-  def script_compiler
-    @script_compiler ||= Puppet::Pal::ScriptCompiler.new(closure_scope.compiler)
-  end
+  def apply_prep(target_spec, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'apply_prep')
+    end
 
-  def inventory
-    @inventory ||= Puppet.lookup(:bolt_inventory)
-  end
+    options = options.slice(*%w[_catch_errors _required_modules _run_as])
+    targets = inventory.get_targets(target_spec)
 
-  def get_task(name, params = {})
-    tasksig = script_compiler.task_signature(name)
-    raise Bolt::Error.new("Task '#{name}' could not be found", 'bolt/apply-prep') unless tasksig
+    executor.report_function_call(self.class.name)
 
-    errors = []
-    unless tasksig.runnable_with?(params) { |msg| errors << msg }
-      # This relies on runnable with printing a partial message before the first real error
-      raise Bolt::ValidationError, "Invalid parameters for #{errors.join("\n")}"
+    executor.log_action('install puppet and gather facts', targets) do
+      executor.without_default_logging do
+        install_results = install_agents(targets, options)
+        facts_results   = get_facts(install_results.ok_set.targets, options)
+
+        Bolt::ResultSet.new(install_results.error_set.results + facts_results.results)
+      end
     end
+  end
 
-    Bolt::Task.from_task_signature(tasksig)
+  def applicator
+    @applicator ||= Puppet.lookup(:apply_executor)
   end
 
-  # rubocop:disable Naming/AccessorMethodName
-  def set_agent_feature(target)
-    inventory.set_feature(target, 'puppet-agent')
+  def executor
+    @executor ||= Puppet.lookup(:bolt_executor)
   end
-  # rubocop:enable Naming/AccessorMethodName
 
+  def inventory
+    @inventory ||= Puppet.lookup(:bolt_inventory)
+  end
+
+  # Runs a task. This method is called by the puppet_library hook.
+  #
   def run_task(targets, task, args = {}, options = {})
     executor.run_task(targets, task, args, options)
   end
 
-  # Returns true if the target has the puppet-agent feature defined, either from inventory or transport.
-  def agent?(target, executor, inventory)
+  # Returns true if the target has the puppet-agent feature defined, either from
+  # inventory or transport.
+  #
+  private def agent?(target)
     inventory.features(target).include?('puppet-agent') ||
-      executor.transport(target.transport).provided_features.include?('puppet-agent') || target.remote?
+    executor.transport(target.transport).provided_features.include?('puppet-agent') ||
+    target.remote?
   end
 
-  def executor
-    @executor ||= Puppet.lookup(:bolt_executor)
+  # Generate the plugin tarball.
+  #
+  private def build_plugin_tarball(required_modules)
+    if required_modules.any?
+      Puppet.debug("Syncing only required modules: #{required_modules.join(',')}.")
+    end
+
+    tarball = applicator.build_plugin_tarball do |mod|
+      next unless required_modules.empty? || required_modules.include?(mod.name)
+      search_dirs = []
+      search_dirs << mod.plugins if mod.plugins?
+      search_dirs << mod.pluginfacts if mod.pluginfacts?
+      search_dirs
+    end
+
+    Puppet::Pops::Types::PSensitiveType::Sensitive.new(tarball)
   end
 
-  def apply_prep(target_spec, options = {})
-    unless Puppet[:tasks]
-      raise Puppet::ParseErrorWithIssue
-        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'apply_prep')
+  # Install the puppet-agent package on targets that need it.
+  #
+  private def install_agents(targets, options)
+    results = []
+
+    agent_targets, agentless_targets = targets.partition { |target| agent?(target) }
+
+    agent_targets.each do |target|
+      Puppet.debug("Puppet Agent feature declared for #{target}")
+      results << Bolt::Result.new(target)
     end
 
-    # Unfreeze this
-    options = options.slice(*%w[_run_as _required_modules])
+    unless agentless_targets.empty?
+      hooks, errors = get_hooks(agentless_targets, options)
+      hook_results  = run_hooks(hooks)
 
-    applicator = Puppet.lookup(:apply_executor)
+      hook_results.each do |result|
+        next unless result.ok?
+        inventory.set_feature(result.target, 'puppet-agent')
+      end
 
-    executor.report_function_call(self.class.name)
+      results.concat(hook_results).concat(errors)
+    end
 
-    targets = inventory.get_targets(target_spec)
+    Bolt::ResultSet.new(results).tap do |resultset|
+      unless resultset.ok? || options['_catch_errors']
+        raise Bolt::RunFailure.new(resultset.error_set, 'apply_prep')
+      end
+    end
+  end
 
-    required_modules = options.delete('_required_modules').to_a
-    if required_modules.any?
-      Puppet.debug("Syncing only required modules: #{required_modules.join(',')}.")
+  # Retrieve facts from each target and add them to inventory.
+  #
+  private def get_facts(targets, options)
+    return Bolt::ResultSet.new([]) unless targets.any?
+
+    task    = applicator.custom_facts_task
+    args    = { 'plugins' => build_plugin_tarball(options.delete('_required_modules').to_a) }
+    results = run_task(targets, task, args, options)
+
+    unless results.ok? || options['_catch_errors']
+      raise Bolt::RunFailure.new(results, 'run_task', task.name)
     end
 
-    # Gather facts, including custom facts
-    plugins = applicator.build_plugin_tarball do |mod|
-      next unless required_modules.empty? || required_modules.include?(mod.name)
-      search_dirs = []
-      search_dirs << mod.plugins if mod.plugins?
-      search_dirs << mod.pluginfacts if mod.pluginfacts?
-      search_dirs
+    results.each do |result|
+      next unless result.ok?
+
+      if unsupported_puppet?(result['clientversion'])
+        Bolt::Logger.deprecate(
+          "unsupported_puppet",
+          "Detected unsupported Puppet agent version #{result['clientversion']} on target "\
+          "#{result.target}. Bolt supports Puppet agent 6.0.0 and higher."
+        )
+      end
+
+      inventory.add_facts(result.target, result.value)
     end
 
-    executor.log_action('install puppet and gather facts', targets) do
-      executor.without_default_logging do
-        # Skip targets that include the puppet-agent feature, as we know an agent will be available.
-        agent_targets, need_install_targets = targets.partition { |target| agent?(target, executor, inventory) }
-        agent_targets.each { |target| Puppet.debug "Puppet Agent feature declared for #{target.name}" }
-        unless need_install_targets.empty?
-          # lazy-load expensive gem code
-          require 'concurrent'
-          pool = Concurrent::ThreadPoolExecutor.new
-
-          hooks = need_install_targets.map do |t|
-            opts = t.plugin_hooks&.fetch('puppet_library').dup
-            plugin_name = opts.delete('plugin')
-            hook = inventory.plugins.get_hook(plugin_name, :puppet_library)
-            # Give plan function options precedence over inventory options
-            { 'target' => t,
-              'hook_proc' => hook.call(opts.merge(options), t, self) }
-          rescue StandardError => e
-            Bolt::Result.from_exception(t, e)
-          end
-
-          hook_errors, ok_hooks = hooks.partition { |h| h.is_a?(Bolt::Result) }
-
-          futures = ok_hooks.map do |hash|
-            Concurrent::Future.execute(executor: pool) do
-              hash['hook_proc'].call
-            end
-          end
-
-          results = futures.zip(ok_hooks).map do |f, hash|
-            f.value || Bolt::Result.from_exception(hash['target'], f.reason)
-          end
-          set = Bolt::ResultSet.new(results + hook_errors)
-          raise Bolt::RunFailure.new(set.error_set, 'apply_prep') unless set.ok
-
-          need_install_targets.each { |target| set_agent_feature(target) }
-        end
-
-        task = applicator.custom_facts_task
-        arguments = { 'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins) }
-        results = run_task(targets, task, arguments, options)
-
-        # TODO: Standardize RunFailure type with error above
-        raise Bolt::RunFailure.new(results, 'run_task', task.name) unless results.ok?
-
-        results.each do |result|
-          # Log a warning if the client version is < 6
-          if unsupported_puppet?(result['clientversion'])
-            Bolt::Logger.deprecate(
-              "unsupported_puppet",
-              "Detected unsupported Puppet agent version #{result['clientversion']} on target "\
-              "#{result.target}. Bolt supports Puppet agent 6.0.0 and higher."
-            )
-          end
-
-          inventory.add_facts(result.target, result.value)
-        end
+    results
+  end
+
+  # Return a list of targets and their puppet_library hooks.
+  #
+  private def get_hooks(targets, options)
+    hooks  = []
+    errors = []
+
+    targets.each do |target|
+      plugin_opts = target.plugin_hooks.fetch('puppet_library').dup
+      plugin_name = plugin_opts.delete('plugin')
+      hook        = inventory.plugins.get_hook(plugin_name, :puppet_library)
+
+      hooks << { 'target' => target,
+                 'proc'   => hook.call(plugin_opts.merge(options), target, self) }
+    rescue StandardError => e
+      errors << Bolt::Result.from_exception(target, e)
+    end
+
+    [hooks, errors]
+  end
+
+  # Runs the puppet_library hook for each target, returning the result
+  # of each.
+  #
+  private def run_hooks(hooks)
+    require 'concurrent'
+    pool = Concurrent::ThreadPoolExecutor.new
+
+    futures = hooks.map do |hook|
+      Concurrent::Future.execute(executor: pool) do
+        hook['proc'].call
       end
     end
 
-    # Return nothing
-    nil
+    futures.zip(hooks).map do |future, hook|
+      future.value || Bolt::Result.from_exception(hook['target'], future.reason)
+    end
   end
 
   # Returns true if the client's major version is < 6.

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

data/guides/module.yaml

@@ -0,0 +1,18 @@
+---
+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
+    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.yaml

@@ -0,0 +1,24 @@
+---
+topic: modulepath
+guide: |
+    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/guides/project.yaml

@@ -0,0 +1,21 @@
+---
+topic: project
+guide: |
+    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/guides/targets.yaml

@@ -0,0 +1,28 @@
+---
+topic: targets
+guide: |
+    A target is a device that Bolt connects to and runs actions on. Targets can
+    be physical, such as servers, or virtual, such as containers or virtual
+    machines.
+
+    Several of Bolt's commands connect to targets and run actions on them.
+    These commands require a target or targets to run on. You can specify
+    targets to a command using one of the following command-line options:
+
+    *nix options                Powershell options
+     -t, --targets TARGETS      -T, -Targets  TARGETS
+     -q, --query   QUERY        -Q, -Query    QUERY
+         --rerun   FILTER       -Rerun        FILTER
+
+    The 'targets' option accepts a comma-separated list of target URIs or group
+    names, or can read a target list from an input file '@<file>' or stdin '-'.
+    URIs can be specified with the format [protocol://][user@]host[:port]. To
+    learn more about available protocols and their defaults, run 'bolt guide
+    transports'.
+
+    Typically, targets and their configuration and data are listed in a
+    project's inventory file. For more information about inventory files,
+    see 'bolt guide inventory'.
+
+documentation:
+  - https://pup.pt/bolt-commands

data/guides/transports.yaml

@@ -0,0 +1,22 @@
+---
+topic: transports
+guide: |
+    Bolt uses transports (also known as protocols) to establish a connection
+    with a target in order to run actions on the target. The default transport is
+    SSH, and you can see available transports along with their configuration
+    options and defaults at http://pup.pt/bolt-reference.
+
+    You can specify a transport for a target by prepending '<transport>://' to
+    the target's URI. For example, to connect to a target with hostname
+    'example.com' as user 'Administrator' using the WinRM transport, you would
+    pass the following to the target flag:
+        winrm://Administrator@example.com
+
+    You can also specify a default transport for all targets by passing the
+    '--transport' flag on *nix systems and the '-Transport' flag in Powershell.
+    Finally, you can set the transport for a target in the inventory. For more
+    information about the Bolt inventory, run 'bolt guide inventory'.
+
+documentation:
+  - https://pup.pt/bolt-commands#specify-a-transport
+  - http://pup.pt/bolt-inventory#transport-configuration

data/lib/bolt/bolt_option_parser.rb

@@ -1095,7 +1095,7 @@ module Bolt
         @options[:log] = { 'console' => { 'level' => level } }
       end
       define('--clear-cache',
-             "Clear plugin cache before executing.") do |_|
+             "Clear plugin, plan, and task caches before executing.") do |_|
         @options[:clear_cache] = true
       end
       define('--plugin PLUGIN', 'Select the plugin to use.') do |plug|

data/lib/bolt/cli.rb

@@ -238,8 +238,10 @@ module Bolt
       config.check_path_case('modulepath', config.modulepath)
       config.project.check_deprecated_file
 
-      if options[:clear_cache] && File.exist?(config.project.plugin_cache_file)
-        FileUtils.rm(config.project.plugin_cache_file)
+      if options[:clear_cache]
+        FileUtils.rm(config.project.plugin_cache_file) if File.exist?(config.project.plugin_cache_file)
+        FileUtils.rm(config.project.task_cache_file) if File.exist?(config.project.task_cache_file)
+        FileUtils.rm(config.project.plan_cache_file) if File.exist?(config.project.plan_cache_file)
       end
 
       warn_inventory_overrides_cli(options)
@@ -836,13 +838,16 @@ module Bolt
 
       results = nil
       elapsed_time = Benchmark.realtime do
-        pal.in_plan_compiler(executor, inventory, puppetdb_client) do |compiler|
-          compiler.call_function('apply_prep', targets)
+        apply_prep_results = pal.in_plan_compiler(executor, inventory, puppetdb_client) do |compiler|
+          compiler.call_function('apply_prep', targets, '_catch_errors' => true)
         end
 
-        results = pal.with_bolt_executor(executor, inventory, puppetdb_client) do
-          Puppet.lookup(:apply_executor).apply_ast(ast, targets, catch_errors: true, noop: noop)
+        apply_results = pal.with_bolt_executor(executor, inventory, puppetdb_client) do
+          Puppet.lookup(:apply_executor)
+                .apply_ast(ast, apply_prep_results.ok_set.targets, catch_errors: true, noop: noop)
         end
+
+        results = Bolt::ResultSet.new(apply_prep_results.error_set.results + apply_results.results)
       end
 
       executor.shutdown

data/lib/bolt/pal.rb

@@ -447,7 +447,7 @@ module Bolt
     # @param mtime [String] The last time the file was modified.
     #
     private def file_modified?(path, mtime)
-      path && !(File.exist?(path) && File.mtime(path).to_s == mtime)
+      path && !(File.exist?(path) && File.mtime(path).to_s == mtime.to_s)
     end
 
     def list_plans(filter_content: false)
@@ -512,19 +512,14 @@ module Bolt
           end
         end
 
-        privie = plan.tag(:private)&.text
-        unless privie.nil? || %w[true false].include?(privie.downcase)
-          msg = "Plan #{plan_name} key 'private' must be a boolean, received: #{privie}"
-          raise Bolt::Error.new(msg, 'bolt/invalid-plan')
-        end
-
         pp_info = {
           'name'        => plan_name,
           'description' => description,
           'parameters'  => parameters,
-          'module'      => mod
+          'module'      => mod,
+          'private'     => private_plan?(plan)
         }
-        pp_info.merge!({ 'private' => privie&.downcase == 'true' }) unless privie.nil?
+
         pp_info.merge!(get_plan_mtime(plan.file)) if with_mtime
         pp_info
 
@@ -554,14 +549,39 @@ module Bolt
           'name'        => plan_name,
           'description' => plan.description,
           'parameters'  => parameters,
-          'module'      => mod
+          'module'      => mod,
+          'private'     => !!plan.private
         }
-        yaml_info.merge!({ 'private' => plan.private }) unless plan.private.nil?
+
         yaml_info.merge!(get_plan_mtime(yaml_path)) if with_mtime
         yaml_info
       end
     end
 
+    # Returns true if the plan is private, false otherwise.
+    #
+    # @param plan [PuppetStrings::Yard::CodeObjects::Plan] The puppet-strings plan documentation.
+    # @return [Boolean]
+    #
+    private def private_plan?(plan)
+      if plan.tag(:private)
+        value     = plan.tag(:private).text
+        api_value = value.downcase == 'true' ? 'private' : 'public'
+
+        Bolt::Logger.deprecate(
+          'plan_private_tag',
+          "Tag '@private #{value}' in plan '#{plan.name}' is deprecated, use '@api #{api_value}' instead"
+        )
+
+        unless %w[true false].include?(plan.tag(:private).text.downcase)
+          msg = "Value for '@private' tag in plan '#{plan.name}' must be a boolean, received: #{value}"
+          raise Bolt::Error.new(msg, 'bolt/invalid-plan')
+        end
+      end
+
+      plan.tag(:api).text == 'private' || plan.tag(:private)&.text&.downcase == 'true'
+    end
+
     def get_plan_mtime(path)
       # If the plan is from the project modules/ directory, or is in the
       # project itself, include the last mtime of the file so we can compare

data/lib/bolt/pal/yaml_plan/transpiler.rb

@@ -30,7 +30,7 @@ module Bolt
           plan_string = String.new('')
           plan_string << "# #{plan_object.description}\n" if plan_object.description
           plan_string << "# WARNING: This is an autogenerated plan. It might not behave as expected.\n"
-          plan_string << "# @private #{plan_object.private}\n" unless plan_object.private.nil?
+          plan_string << "# @api #{plan_object.private ? 'private' : 'public'}\n" unless plan_object.private.nil?
           plan_string << "#{param_descriptions}\n" unless param_descriptions.empty?
 
           plan_string << "plan #{plan_object.name}("

data/lib/bolt/plugin/task.rb

@@ -59,7 +59,7 @@ module Bolt
         run_opts = {}
         run_opts[:run_as] = opts['_run_as'] if opts['_run_as']
         begin
-          task = apply_prep.get_task(opts['task'], params)
+          task = @context.get_validated_task(opts['task'], params)
         rescue Bolt::Error => e
           raise Bolt::Plugin::PluginError::ExecutionError.new(e.message, name, 'puppet_library')
         end

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '3.14.1'
+  VERSION = '3.15.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 3.14.1
+  version: 3.15.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-07-26 00:00:00.000000000 Z
+date: 2021-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -466,6 +466,15 @@ files:
 - bolt-modules/prompt/lib/puppet/functions/prompt/menu.rb
 - bolt-modules/system/lib/puppet/functions/system/env.rb
 - exe/bolt
+- guides/debugging.yaml
+- guides/inventory.yaml
+- guides/links.yaml
+- guides/logging.yaml
+- guides/module.yaml
+- guides/modulepath.yaml
+- guides/project.yaml
+- guides/targets.yaml
+- guides/transports.yaml
 - lib/bolt.rb
 - lib/bolt/analytics.rb
 - lib/bolt/applicator.rb