bolt 3.9.2 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b54ca78ebd584ad7e8bd223f086ac1dfc86f6f8bca3e7a7a2aab93a466eebc44
-  data.tar.gz: f68a3dfe2dad3a15bd9d970860ad629de9fac40882291d6cd7b677bf0da5814e
+  metadata.gz: fa1075046a81e0596ff3f0483dc7b7a5913a073dd6e998f66c70687049531e74
+  data.tar.gz: 9cdb2d3503e1bd2d84fa7c0fc846e3f4d2293780f648d9d07d549fd50d2b1a51
 SHA512:
-  metadata.gz: 879279d0db3506639ed99118623e90435e4f3ee70239aebd43e50d0fb8527eebf1ecfcf4298b6b110fcd34b560f4037cfc44439b2ad9858f67d9dfa1e5ad27e6
-  data.tar.gz: 36f05f2209c085c607200a857c380114eac7c631a6dd2b98550d27ece0488f3d0c3883693f83c74c3e87387a81e63d446727931084e40d27e6443a9c05eb1c4a
+  metadata.gz: 4b2f636ec7f5f038b69cd5c4f82e9fd93e59521035e15fa678cef67501a4e00287e29f40ce1672d2f5db0fa4972cbc26d9763f62480612e30ebcfae404d12a1f
+  data.tar.gz: f87b3966ea10cf5a5fe46937e9a47b73d4553924bff00ee578f6c659a70fe82864e2cc78b76a685dfb9e3d4a4e5a3fb7bea136730bf6b5160454e665f4f02ea8

data/guides/debugging.txt

@@ -0,0 +1,28 @@
+TOPIC
+    debugging
+
+DESCRIPTION
+    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/lib/bolt/bolt_option_parser.rb

@@ -67,7 +67,7 @@ module Bolt
         { flags: OPTIONS[:global] + %w[format],
           banner: GUIDE_HELP }
       when 'lookup'
-        { flags: ACTION_OPTS + %w[hiera-config],
+        { flags: ACTION_OPTS + %w[hiera-config plan-hierarchy],
           banner: LOOKUP_HELP }
       when 'module'
         case action
@@ -105,6 +105,15 @@ module Bolt
           { flags: OPTIONS[:global],
             banner: PLAN_HELP }
         end
+      when 'plugin'
+        case action
+        when 'show'
+          { flags: OPTIONS[:global] + %w[color format modulepath project],
+            banner: PLUGIN_SHOW_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: PLUGIN_HELP }
+        end
       when 'project'
         case action
         when 'init'
@@ -192,6 +201,7 @@ module Bolt
           module            Manage Bolt project modules
           lookup            Look up a value with Hiera
           plan              Convert, create, show, and run Bolt plans
+          plugin            Show available plugins
           project           Create and migrate Bolt projects
           script            Upload a local script and run it remotely
           secret            Create encryption keys and encrypt and decrypt values
@@ -407,7 +417,7 @@ module Bolt
           lookup
 
       #{colorize(:cyan, 'Usage')}
-          bolt lookup <key> {--targets TARGETS | --query QUERY | --rerun FILTER}
+          bolt lookup <key> {--targets TARGETS | --query QUERY | --rerun FILTER | --plan-hierarchy}
             [options]
 
       #{colorize(:cyan, 'Description')}
@@ -418,6 +428,7 @@ module Bolt
 
       #{colorize(:cyan, 'Examples')}
           bolt lookup password --targets servers
+          bolt lookup password --plan-hierarchy variable=value
     HELP
 
     MODULE_HELP = <<~HELP
@@ -608,6 +619,37 @@ module Bolt
             bolt plan show aggregate::count
     HELP
 
+    PLUGIN_HELP = <<~HELP
+      #{colorize(:cyan, 'Name')}
+          plugin
+
+      #{colorize(:cyan, 'Usage')}
+          bolt plugin <action> [options]
+
+      #{colorize(:cyan, 'Description')}
+          Show available plugins.
+
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt plugins at https://pup.pt/bolt-plugins.
+
+      #{colorize(:cyan, 'Actions')}
+          show          Show available plugins
+    HELP
+
+    PLUGIN_SHOW_HELP = <<~HELP
+      #{colorize(:cyan, 'Name')}
+          show
+
+      #{colorize(:cyan, 'Usage')}
+          bolt plugin show [options]
+
+      #{colorize(:cyan, 'Description')}
+          Show available plugins.
+
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt plugins at https://pup.pt/bolt-plugins.
+    HELP
+
     PROJECT_HELP = <<~HELP
       #{colorize(:cyan, 'Name')}
           project
@@ -988,6 +1030,11 @@ module Bolt
         @options[:resolve] = resolve
       end
 
+      separator "\n#{self.class.colorize(:cyan, 'Lookup options')}"
+      define('--plan-hierarchy', 'Look up a value with Hiera in the context of a specific plan.') do |_|
+        @options[:plan_hierarchy] = true
+      end
+
       separator "\n#{self.class.colorize(:cyan, 'Plan options')}"
       define('--pp', 'Create a new Puppet language plan.') do |_|
         @options[:puppet] = true

data/lib/bolt/cli.rb

@@ -42,6 +42,7 @@ module Bolt
       'lookup'    => %w[],
       'module'    => %w[add generate-types install show],
       'plan'      => %w[show run convert new],
+      'plugin'    => %w[show],
       'project'   => %w[init migrate],
       'script'    => %w[run],
       'secret'    => %w[encrypt decrypt createkeys],
@@ -354,12 +355,18 @@ module Bolt
                               "the project, run '#{command} #{options[:object]}'."
       end
 
-      if options[:subcommand] != 'file' && options[:subcommand] != 'script' &&
+      if !%w[file script lookup].include?(options[:subcommand]) &&
          !options[:leftovers].empty?
         raise Bolt::CLIError,
               "Unknown argument(s) #{options[:leftovers].join(', ')}"
       end
 
+      target_opts = options.keys.select { |opt| TARGETING_OPTIONS.include?(opt) }
+      if options[:subcommand] == 'lookup' &&
+         target_opts.any? && options[:plan_hierarchy]
+        raise Bolt::CLIError, "The 'lookup' command accepts either targeting option OR --plan-hierarchy."
+      end
+
       if options[:noop] &&
          !(options[:subcommand] == 'task' && options[:action] == 'run') && options[:subcommand] != 'apply'
         raise Bolt::CLIError,
@@ -432,10 +439,11 @@ module Bolt
       end
 
       # 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[:target_args] will contain a string/array version of the targeting options this is passed to plans
       # options[:targets] will contain a resolved set of Target objects
       unless %w[guide module project secret].include?(options[:subcommand]) ||
-             %w[convert new show].include?(options[:action])
+             %w[convert new show].include?(options[:action]) ||
+             options[:plan_hierarchy]
         update_targets(options)
       end
 
@@ -487,6 +495,8 @@ module Bolt
           list_groups
         when 'module'
           list_modules
+        when 'plugin'
+          list_plugins
         end
         return 0
       when 'convert'
@@ -516,7 +526,13 @@ module Bolt
           code = Bolt::ProjectManager.new(config, outputter, pal).migrate
         end
       when 'lookup'
-        code = lookup(options[:object], options[:targets])
+        plan_vars = Hash[options[:leftovers].map { |a| a.split('=', 2) }]
+        # Validate functions verifies one of these was passed
+        if options[:targets]
+          code = lookup(options[:object], options[:targets], plan_vars: plan_vars)
+        elsif options[:plan_hierarchy]
+          code = plan_lookup(options[:object], plan_vars: plan_vars)
+        end
       when 'plan'
         case options[:action]
         when 'new'
@@ -630,7 +646,7 @@ module Bolt
     end
 
     def list_tasks
-      tasks = filter_content(pal.list_tasks(filter_content: true), options[:filter])
+      tasks = filter_content(pal.list_tasks_with_cache(filter_content: true), options[:filter])
       outputter.print_tasks(tasks, pal.user_modulepath)
     end
 
@@ -694,10 +710,19 @@ module Bolt
       outputter.print_groups(inventory.group_names.sort, inventory.source, config.default_inventoryfile)
     end
 
+    # Looks up a value with Hiera as if in a plan outside an apply block, using
+    # provided variable values for interpolations
+    #
+    def plan_lookup(key, plan_vars: {})
+      result = pal.plan_hierarchy_lookup(key, plan_vars: plan_vars)
+      outputter.print_plan_lookup(result)
+      0
+    end
+
     # Looks up a value with Hiera, using targets as the contexts to perform the
-    # look ups in.
+    # look ups in. This should return the same value as a lookup in an apply block.
     #
-    def lookup(key, targets)
+    def lookup(key, targets, plan_vars: {})
       executor = Bolt::Executor.new(
         config.concurrency,
         analytics,
@@ -706,7 +731,7 @@ module Bolt
         config.future
       )
 
-      executor.subscribe(outputter) if options.fetch(:format, 'human') == 'human'
+      executor.subscribe(outputter) if config.format == 'human'
       executor.subscribe(log_outputter)
       executor.publish_event(type: :plan_start, plan: nil)
 
@@ -716,7 +741,7 @@ module Bolt
           targets,
           inventory,
           executor,
-          config.concurrency
+          plan_vars: plan_vars
         )
       end
 
@@ -827,6 +852,10 @@ module Bolt
       outputter.print_module_list(pal.list_modules)
     end
 
+    def list_plugins
+      outputter.print_plugin_list(plugins.list_plugins, pal.user_modulepath)
+    end
+
     def generate_types
       # generate_types will surface a nice error with helpful message if it fails
       pal.generate_types(cache: true)

data/lib/bolt/outputter/human.rb

@@ -460,6 +460,10 @@ module Bolt
         @stream.puts(guide)
       end
 
+      def print_plan_lookup(value)
+        @stream.puts(value)
+      end
+
       def print_module_list(module_list)
         module_list.each do |path, modules|
           if (mod = modules.find { |m| m[:internal_module_group] })
@@ -488,6 +492,34 @@ module Bolt
         end
       end
 
+      def print_plugin_list(plugin_list, modulepath)
+        info   = +''
+        length = plugin_list.values.map(&:keys).flatten.map(&:length).max + 4
+
+        plugin_list.each do |hook, plugins|
+          next if plugins.empty?
+          next if hook == :validate_resolve_reference
+
+          info << colorize(:cyan, "#{hook}\n")
+
+          plugins.each do |name, description|
+            info << indent(2, name.ljust(length))
+            info << truncate(description, 80 - length) if description
+            info << "\n"
+          end
+
+          info << "\n"
+        end
+
+        info << colorize(:cyan, "Modulepath\n")
+        info << indent(2, "#{modulepath.join(File::PATH_SEPARATOR)}\n\n")
+
+        info << colorize(:cyan, "Additional information\n")
+        info << indent(2, "For more information about using plugins see https://pup.pt/bolt-plugins")
+
+        @stream.puts info.chomp
+      end
+
       def print_targets(target_list, inventory_source, default_inventory, target_flag)
         adhoc = colorize(:yellow, "(Not found in inventory file)")
 

data/lib/bolt/outputter/json.rb

@@ -60,6 +60,11 @@ module Bolt
         print_table('tasks' => tasks, 'modulepath' => modulepath)
       end
 
+      def print_plugin_list(plugins, modulepath)
+        plugins.delete(:validate_resolve_reference)
+        print_table('plugins' => plugins, 'modulepath' => modulepath)
+      end
+
       def print_plan_info(plan)
         path = plan.delete('module')
         plan['module_dir'] = if path.start_with?(Bolt::Config::Modulepath::MODULES_PATH)
@@ -98,6 +103,10 @@ module Bolt
         }.to_json)
       end
 
+      def print_plan_lookup(value)
+        @stream.puts(value.to_json)
+      end
+
       def print_puppetfile_result(success, puppetfile, moduledir)
         @stream.puts({ success: success,
                        puppetfile: puppetfile,

data/lib/bolt/pal.rb

@@ -163,9 +163,10 @@ module Bolt
     # Runs a block in a PAL script compiler configured for Bolt.  Catches
     # exceptions thrown by the block and re-raises them ensuring they are
     # Bolt::Errors since the script compiler block will squash all exceptions.
-    def in_bolt_compiler
+    def in_bolt_compiler(compiler_params: {})
       # TODO: If we always call this inside a bolt_executor we can remove this here
       setup
+      compiler_params = compiler_params.merge(set_local_facts: false)
       r = Puppet::Pal.in_tmp_environment('bolt', modulepath: full_modulepath, facts: {}) do |pal|
         # Only load the project if it a) exists, b) has a name it can be loaded with
         Puppet.override(bolt_project: @project,
@@ -174,7 +175,7 @@ module Bolt
           # of modules, it must happen *after* we have overridden
           # bolt_project or the project will be ignored
           detect_project_conflict(@project, Puppet.lookup(:environments).get('bolt'))
-          pal.with_script_compiler(set_local_facts: false) do |compiler|
+          pal.with_script_compiler(**compiler_params) do |compiler|
             alias_types(compiler)
             register_resource_types(Puppet.lookup(:loaders)) if @resource_types
             begin
@@ -299,6 +300,49 @@ module Bolt
       end
     end
 
+    def list_tasks_with_cache(filter_content: false)
+      # Don't filter content yet, so that if users update their task filters
+      # we don't need to refresh the cache
+      task_names = list_tasks(filter_content: false).map(&:first)
+      task_cache = if @project
+                     Bolt::Util.read_optional_json_file(@project.task_cache_file, 'Task cache file')
+                   else
+                     {}
+                   end
+      updated = false
+
+      task_list = task_names.each_with_object([]) do |task_name, list|
+        data = task_cache[task_name] || get_task_info(task_name, with_mtime: true)
+
+        # Make sure all the keys are strings - if we get data from
+        # get_task_info they will be symbols
+        data = Bolt::Util.walk_keys(data, &:to_s)
+
+        # If any files in the task were updated, refresh the cache
+        if data['files']&.any?
+          # For all the files that are part of the task
+          data['files'].each do |f|
+            # If any file has been updated since we last cached, update the
+            # cache
+            next if File.mtime(f['path']).to_s == f['mtime']
+            data = get_task_info(task_name, with_mtime: true)
+            data = Bolt::Util.walk_keys(data, &:to_s)
+            # Tell Bolt to write to the cache file once we're done
+            updated = true
+            # Update the cache data
+            task_cache[task_name] = data
+          end
+        end
+        metadata = data['metadata'] || {}
+        # Don't add tasks to the list to return if they are private
+        list << [task_name, metadata['description']] unless metadata['private']
+      end
+
+      # Write the cache if any entries were updated
+      File.write(@project.task_cache_file, task_cache.to_json) if updated
+      filter_content ? filter_content(task_list, @project&.tasks) : task_list
+    end
+
     def list_tasks(filter_content: false)
       in_bolt_compiler do |compiler|
         tasks = compiler.list_tasks.map(&:name).sort.each_with_object([]) do |task_name, data|
@@ -350,14 +394,20 @@ module Bolt
       end
     end
 
-    def get_task(task_name)
+    def get_task(task_name, with_mtime: false)
       task = task_signature(task_name)
 
       if task.nil?
         raise Bolt::Error.unknown_task(task_name)
       end
 
-      Bolt::Task.from_task_signature(task)
+      task = Bolt::Task.from_task_signature(task)
+      task.add_mtimes if with_mtime
+      task
+    end
+
+    def get_task_info(task_name, with_mtime: false)
+      get_task(task_name, with_mtime: with_mtime).to_h
     end
 
     def list_plans_with_cache(filter_content: false)
@@ -372,20 +422,20 @@ module Bolt
       updated = false
 
       plan_list = plan_names.each_with_object([]) do |plan_name, list|
-        info = plan_cache[plan_name] || get_plan_info(plan_name, with_mtime: true)
+        data = plan_cache[plan_name] || get_plan_info(plan_name, with_mtime: true)
 
         # If the plan is a 'local' plan (in the project itself, or the
         # modules/ directory) then verify it hasn't been updated since we
         # cached it. If it has been updated, refresh the cache and use the
         # new data.
-        if info['file'] &&
-           (File.mtime(info.dig('file', 'path')) <=> info.dig('file', 'mtime')) != 0
-          info = get_plan_info(plan_name, with_mtime: true)
+        if data['file'] &&
+           File.mtime(data.dig('file', 'path')).to_s != data.dig('file', 'mtime')
+          data = get_plan_info(plan_name, with_mtime: true)
           updated = true
-          plan_cache[plan_name] = info
+          plan_cache[plan_name] = data
         end
 
-        list << [plan_name, info['description']] unless info['private']
+        list << [plan_name, data['description']] unless data['private']
       end
 
       File.write(@project.plan_cache_file, plan_cache.to_json) if updated
@@ -585,6 +635,7 @@ module Bolt
         inputs = generator.find_inputs(:pcore)
         FileUtils.mkdir_p(@resource_types)
         cache_plan_info if @project && cache
+        cache_task_info if @project && cache
         generator.generate(inputs, @resource_types, true)
       end
     end
@@ -600,6 +651,17 @@ module Bolt
       File.write(@project.plan_cache_file, plans_info.to_json)
     end
 
+    def cache_task_info
+      # task_name is an array here
+      tasks_info = list_tasks(filter_content: false).map do |task_name,|
+        data = get_task_info(task_name, with_mtime: true)
+        { task_name => data }
+      end.reduce({}, :merge)
+
+      FileUtils.touch(@project.task_cache_file)
+      File.write(@project.task_cache_file, tasks_info.to_json)
+    end
+
     def run_task(task_name, targets, params, executor, inventory, description = nil)
       in_task_compiler(executor, inventory) do |compiler|
         params = params.merge('_bolt_api_call' => true, '_catch_errors' => true)
@@ -632,7 +694,21 @@ module Bolt
       Bolt::PlanResult.new(e, 'failure')
     end
 
-    def lookup(key, targets, inventory, executor, _concurrency)
+    def plan_hierarchy_lookup(key, plan_vars: {})
+      # Do a lookup with a script compiler, which uses the 'plan_hierarchy' key in
+      # Hiera config.
+      with_puppet_settings do
+        # We want all of the setup and teardown that `in_bolt_compiler` does,
+        # but also want to pass keys to the script compiler.
+        in_bolt_compiler(compiler_params: { variables: plan_vars }) do |compiler|
+          compiler.call_function('lookup', key)
+        end
+      rescue Puppet::Error => e
+        raise PALError.from_error(e)
+      end
+    end
+
+    def lookup(key, targets, inventory, executor, plan_vars: {})
       # Install the puppet-agent package and collect facts. Facts are
       # automatically added to the targets.
       in_plan_compiler(executor, inventory, nil) do |compiler|
@@ -654,21 +730,29 @@ module Bolt
 
         trusted = Puppet::Context::TrustedInformation.local(node).to_h
 
+        # Separate environment configuration from interpolation data the same
+        # way we do when compiling Puppet catalogs.
         env_conf = {
           modulepath: @modulepath.full_modulepath,
-          facts:      target.facts,
-          variables:  target.vars
+          facts:      target.facts
+        }
+
+        interpolations = {
+          variables:        plan_vars,
+          target_variables: target.vars
         }
 
         with_puppet_settings do
           Puppet::Pal.in_tmp_environment(target.name, **env_conf) do |pal|
             Puppet.override(overrides) do
               Puppet.lookup(:pal_current_node).trusted_data = trusted
-              pal.with_catalog_compiler do |compiler|
+              pal.with_catalog_compiler(**interpolations) do |compiler|
                 Bolt::Result.for_lookup(target, key, compiler.call_function('lookup', key))
               rescue StandardError => e
                 Bolt::Result.from_exception(target, e)
               end
+            rescue Puppet::Error => e
+              raise PALError.from_error(e)
             end
           end
         end

data/lib/bolt/plugin.rb

@@ -250,6 +250,44 @@ module Bolt
       end
     end
 
+    # Loads all plugins and returns a map of plugin names to hooks.
+    #
+    def list_plugins
+      load_all_plugins
+
+      hooks = KNOWN_HOOKS.map { |hook| [hook, {}] }.to_h
+
+      @plugins.sort.each do |name, plugin|
+        # Don't show the Puppet Connect plugin for now.
+        next if name == 'puppet_connect_data'
+
+        case plugin
+        when Bolt::Plugin::Module
+          plugin.hook_map.each do |hook, spec|
+            next unless hooks.include?(hook)
+            hooks[hook][name] = spec['task'].description
+          end
+        else
+          plugin.hook_descriptions.each do |hook, description|
+            hooks[hook][name] = description
+          end
+        end
+      end
+
+      hooks
+    end
+
+    # Loads all plugins available to the project.
+    #
+    private def load_all_plugins
+      modules.each do |name, mod|
+        next unless mod.plugin?
+        by_name(name)
+      end
+
+      RUBY_PLUGINS.each { |name| by_name(name) }
+    end
+
     def puppetdb_client
       by_name('puppetdb').puppetdb_client
     end

data/lib/bolt/plugin/env_var.rb

@@ -10,7 +10,14 @@ module Bolt
       end
 
       def hooks
-        %i[resolve_reference validate_resolve_reference]
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          resolve_reference: 'Read values stored in environment variables.',
+          validate_resolve_reference: nil
+        }
       end
 
       def validate_resolve_reference(opts)

data/lib/bolt/plugin/module.rb

@@ -24,7 +24,7 @@ module Bolt
         end
       end
 
-      attr_reader :config
+      attr_reader :config, :hook_map
 
       def initialize(mod:, context:, config:, **_opts)
         @module = mod

data/lib/bolt/plugin/prompt.rb

@@ -10,7 +10,14 @@ module Bolt
       end
 
       def hooks
-        %i[resolve_reference validate_resolve_reference]
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          resolve_reference: 'Prompt the user for a sensitive value.',
+          validate_resolve_reference: nil
+        }
       end
 
       def validate_resolve_reference(opts)

data/lib/bolt/plugin/puppet_connect_data.rb

@@ -49,7 +49,14 @@ module Bolt
       end
 
       def hooks
-        %i[resolve_reference validate_resolve_reference]
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          resolve_reference: nil,
+          validate_resolve_reference: nil
+        }
       end
 
       def resolve_reference(opts)

data/lib/bolt/plugin/puppetdb.rb

@@ -27,7 +27,13 @@ module Bolt
       end
 
       def hooks
-        [:resolve_reference]
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          resolve_reference: 'Query PuppetDB for a group of targets.'
+        }
       end
 
       def warn_missing_fact(certname, fact)

data/lib/bolt/plugin/task.rb

@@ -4,7 +4,15 @@ module Bolt
   class Plugin
     class Task
       def hooks
-        %i[validate_resolve_reference puppet_library resolve_reference]
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          puppet_library: 'Run a task to install the Puppet agent package.',
+          resolve_reference: 'Run a task as a plugin.',
+          validate_resolve_reference: nil
+        }
       end
 
       def name

data/lib/bolt/project.rb

@@ -14,7 +14,7 @@ module Bolt
     attr_reader :path, :data, :inventory_file, :hiera_config,
                 :puppetfile, :rerunfile, :type, :resource_types, :project_file,
                 :downloads, :plans_path, :modulepath, :managed_moduledir,
-                :backup_dir, :plugin_cache_file, :plan_cache_file
+                :backup_dir, :plugin_cache_file, :plan_cache_file, :task_cache_file
 
     def self.default_project
       create_project(File.expand_path(File.join('~', '.puppetlabs', 'bolt')), 'user')
@@ -114,6 +114,7 @@ module Bolt
       @backup_dir        = @path + '.bolt-bak'
       @plugin_cache_file = @path + '.plugin_cache.json'
       @plan_cache_file   = @path + '.plan_cache.json'
+      @task_cache_file   = @path + '.task_cache.json'
       @modulepath        = [(@path + 'modules').to_s]
 
       if (tc = Bolt::Config::INVENTORY_OPTIONS.keys & data.keys).any?

data/lib/bolt/task.rb

@@ -17,6 +17,7 @@ module Bolt
                        remote supports_noop].freeze
 
     attr_reader :name, :files, :metadata, :remote
+    attr_accessor :mtime
 
     # name [String] name of the task
     # files [Array<Hash>] where each entry includes `name` and `path`
@@ -77,6 +78,12 @@ module Bolt
       file_map[file_name]['path']
     end
 
+    def add_mtimes
+      @files.each do |f|
+        f['mtime'] = File.mtime(f['path']) if File.exist?(f['path'])
+      end
+    end
+
     def implementations
       metadata['implementations']
     end

data/lib/bolt/version.rb

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

data/lib/bolt_spec/plans/mock_executor.rb

@@ -286,7 +286,7 @@ module BoltSpec
         future
       end
 
-      def wait(results, _timeout, **_kwargs)
+      def wait(results, **_kwargs)
         results
       end
 

data/resources/bolt_bash_completion.sh

@@ -0,0 +1,214 @@
+#####################################################################
+###
+### Bash autocompletion for bolt
+### include this file in your .bash_profile or .bashrc to use completion
+### "source bolt_bash_completion.sh"
+###
+### Marc Schoechlin ms-github@256bit.org
+
+get_json_keys() {
+/opt/puppetlabs/bolt/bin/ruby <<-EOF
+  require 'json'
+  data = JSON.parse(File.read("${1}"))
+  puts data.keys.uniq.sort.join(' ')
+EOF
+}
+
+_bolt_complete() {
+  local prev
+  local cur
+  # Get the current word and previous word without colons
+  _get_comp_words_by_ref -n : cur
+  _get_comp_words_by_ref -n : prev
+
+  local next=""
+  local subcommand=${COMP_WORDS[1]}
+  [[ ${#COMP_WORDS[@]} -gt 2 ]] && local action=${COMP_WORDS[2]}
+  local context_opts="-m --modulepath --project"
+  local global_opts="--clear-cache -h --help --log-level --version"
+  local inventory_opts="-q --query --rerun -t --targets"
+  local authentication_opts="-u --user -p --password --password-prompt --private-key --host-key-check --no-host-key-check --ssl --no-ssl --ssl-verify --no-ssl-verify"
+  local escalation_opts="--run-as --sudo-password --sudo-password-prompt --sudo-executable"
+  local run_context_opts="-c --concurrency -i --inventoryfile --save-rerun --no-save-rerun --cleanup --no-cleanup"
+  local transport_opts="--transport --connect-timeout --tty --no-tty --native-ssh --no-native-ssh --ssh-command --copy-command"
+  local display_opts="--format --color --no-color -v --verbose --no-verbose --trace --stream"
+  local action_opts="${inventory_opts} ${context_opts} ${authentication_opts} ${escalation_opts} ${run_context_opts} ${transport_opts} ${display_opts}"
+  local apply_opts="--compile-concurrency --hiera-config"
+  local file_opts=" -m --modulepath --project --private-key -i --inventoryfile --hiera-config "
+
+  # If there's only one word and it's "bolt", tab complete the subcommand
+  if [ $COMP_CWORD -eq 1 ]; then
+    next="apply command file group guide inventory lookup module plan plugin project script secret task"
+  fi
+
+  # Tab complete files for options that accept files. The spaces are important!
+  # They make it so `bolt inventory` isn't confused with `--inventoryfile`.
+  if [[ $file_opts =~ " ${prev} " ]]; then
+    next=$(compgen -f -d "" -- $cur)
+  # Handle tab completing enumerable CLI options
+  elif [ "$prev" == "--log-level" ]; then
+    next="trace debug info warn error fatal any"
+  elif [ "$prev" == "--transport" ]; then
+    next="docker local lxd pcp podman remote ssh winrm"
+  elif [ "$prev" == "--format" ]; then
+    next="human json rainbow"
+  else
+    # Once we have subcommands, tab complete actions
+    case $subcommand in
+      apply)
+        next="${action_opts} ${apply_opts} -e --execute"
+        ;;
+      command)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="run"
+        elif [ $action = "run" ]; then
+          next="${action_opts} --env-var"
+        fi
+        ;;
+      file)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="download upload"
+        else
+          case $action in
+            download) next="${action_opts} --tmpdir";;
+            upload) next=$action_opts;;
+          esac
+        fi
+        ;;
+      group)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="show"
+        elif [ $action == 'show' ]; then
+          next="--project --format --inventoryfile"
+        fi
+        ;;
+      guide)
+        next="--format"
+        ;;
+      inventory)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="show"
+        elif [ $action == 'show' ]; then
+          next="${inventory_opts} --project --format --inventoryfile --detail"
+        fi
+        ;;
+      lookup)
+        next="${action_opts} --hiera-config --plan-hierarchy"
+        ;;
+      module)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="add generate-types install show"
+        else
+          case $action in
+            add | install) next="--project";;
+            generate-types) next="${context_opts}";;
+            show) next="${context_opts} --filter --format";;
+          esac
+        fi
+        ;;
+      plan)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="convert new run show"
+        elif [[ ($COMP_CWORD -eq 3 || \
+          ( $COMP_CWORD -eq 4 && "$cur" == *"::" ) || \
+          ( $COMP_CWORD -eq 5 && "$cur" == *"::"* )) &&
+          $action != "new" ]]; then
+
+          if [ -f "${PWD}/.plan_cache.json" ]; then
+            # Use Puppet's ruby instead of jq since we know it will be there.
+            next=$(get_json_keys "${PWD}/.plan_cache.json")
+          elif [ -f "${HOME}/.puppetlabs/bolt/.plan_cache.json" ]; then
+            next=$(get_json_keys "${HOME}/.puppetlabs/bolt/.plan_cache.json")
+          else
+            case $action in
+              convert) next="${context_opts}";;
+              new) next="--project --pp";;
+              run) next="${action_opts} ${apply_opts} --params --tmpdir";;
+              show) next="${context_opts} --filter --format";;
+            esac
+          fi
+        else
+          case $action in
+            convert) next="${context_opts}";;
+            new) next="--project --pp";;
+            run) next="${action_opts} ${apply_opts} --params --tmpdir";;
+            show) next="${context_opts} --filter --format";;
+          esac
+        fi
+        ;;
+      plugin)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="show"
+        else
+          next="${context_opts} --format --color --no-color"
+        fi
+        ;;
+      project)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="init migrate"
+        else
+          case $action in
+            init) next="--modules";;
+            migrate) next="--project --inventoryfile";;
+          esac
+        fi
+        ;;
+      script)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="run"
+        elif [[ $COMP_CWORD -eq 3 && $action == 'run' ]]; then
+          # List files and directories
+          next=$(compgen -f -d "" -- $cur)
+        elif [ $action == 'run' ]; then
+          next="${action_opts} --env-var --tmpdir"
+        fi
+        ;;
+      secret)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="createkeys encrypt decrypt"
+        else
+          case $action in
+            createkeys) next="${context_opts} --plugin --force";;
+            encrypt | decrypt) next="${context_opts} --plugin";;
+          esac
+        fi
+        ;;
+      task)
+        if [ $COMP_CWORD -eq 2 ]; then
+          next="run show"
+        elif [[ $COMP_CWORD -eq 3 || \
+          ( $COMP_CWORD -eq 4 && "$cur" == *"::" ) || \
+          ( $COMP_CWORD -eq 5 && "$cur" == *"::"* ) ]]; then
+          if [ -f "${PWD}/.task_cache.json" ]; then
+            # Use Puppet's ruby instead of jq since we know it will be there.
+            next=$(get_json_keys "${PWD}/.task_cache.json")
+          elif [ -f "${HOME}/.puppetlabs/bolt/.task_cache.json" ]; then
+            next=$(get_json_keys "${HOME}/.puppetlabs/bolt/.task_cache.json")
+          else
+            case $action in
+              run) next="${action_opts} --env-var --tmpdir";;
+              show) next="${context_opts} --filter --format";;
+            esac
+          fi
+        else
+          case $action in
+            run) next="${action_opts} --env-var --tmpdir";;
+            show) next="${context_opts} --filter --format";;
+          esac
+        fi
+        ;;
+    esac
+  fi
+
+  # If any of the next options are flags, we've reached the end of the
+  # building-a-Bolt-command part and can re-enable file and directory name
+  # completion and include Bolt's global flags.
+  if [[ "$next" =~ "--" ]]; then
+    next+=" ${global_opts}"
+  fi
+
+  COMPREPLY=($(compgen -W "$next" -- $cur))
+  __ltrim_colon_completions $cur
+}
+
+complete -F _bolt_complete bolt

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 3.9.2
+  version: 3.10.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-06-08 00:00:00.000000000 Z
+date: 2021-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -453,6 +453,7 @@ files:
 - bolt-modules/prompt/lib/puppet/functions/prompt/menu.rb
 - bolt-modules/system/lib/puppet/functions/system/env.rb
 - exe/bolt
+- guides/debugging.txt
 - guides/guide.txt
 - guides/inventory.txt
 - guides/links.txt
@@ -636,6 +637,7 @@ files:
 - modules/canary/plans/init.pp
 - modules/puppet_connect/plans/test_input_data.pp
 - modules/puppetdb_fact/plans/init.pp
+- resources/bolt_bash_completion.sh
 homepage: https://github.com/puppetlabs/bolt
 licenses:
 - Apache-2.0