bolt 3.12.0 → 3.16.0

data/lib/bolt/outputter/json.rb

@@ -23,6 +23,8 @@ module Bolt
           print_result(event[:result])
         when :message
           print_message(event[:message])
+        when :verbose
+          print_message(event[:message]) if @verbose
         end
       end
 
@@ -45,8 +47,13 @@ module Bolt
         @stream.puts results.to_json
       end
       alias print_module_list print_table
+      alias print_module_info print_table
 
-      def print_task_info(task)
+      # Print information about a task.
+      #
+      # @param task [Bolt::Task] The task information.
+      #
+      def print_task_info(task:)
         path = task.files.first['path'].chomp("/tasks/#{task.files.first['name']}")
         module_dir = if path.start_with?(Bolt::Config::Modulepath::MODULES_PATH)
                        "built-in module"
@@ -56,11 +63,16 @@ module Bolt
         @stream.puts task.to_h.merge(module_dir: module_dir).to_json
       end
 
-      def print_tasks(tasks, modulepath)
-        print_table('tasks' => tasks, 'modulepath' => modulepath)
+      # List available tasks.
+      #
+      # @param tasks [Array] A list of task names and descriptions.
+      # @param modulepath [Array] The modulepath.
+      #
+      def print_tasks(**kwargs)
+        print_table(**kwargs)
       end
 
-      def print_plugin_list(plugins, modulepath)
+      def print_plugin_list(plugins:, modulepath:)
         plugins.delete(:validate_resolve_reference)
         print_table('plugins' => plugins, 'modulepath' => modulepath)
       end
@@ -75,11 +87,15 @@ module Bolt
         @stream.puts plan.to_json
       end
 
-      def print_plans(plans, modulepath)
-        print_table('plans' => plans, 'modulepath' => modulepath)
+      def print_plans(**kwargs)
+        print_table(**kwargs)
       end
 
-      def print_apply_result(apply_result, _elapsed_time)
+      def print_new_plan(**kwargs)
+        print_table(**kwargs)
+      end
+
+      def print_apply_result(apply_result)
         @stream.puts apply_result.to_json
       end
 
@@ -92,15 +108,21 @@ module Bolt
         @stream.puts result_set.to_json
       end
 
-      def print_topics(topics)
-        print_table('topics' => topics)
+      # Print available guide topics.
+      #
+      # @param topics [Array] The available topics.
+      #
+      def print_topics(**kwargs)
+        print_table(kwargs)
       end
 
-      def print_guide(guide, topic)
-        @stream.puts({
-          'topic' => topic,
-          'guide' => guide
-        }.to_json)
+      # Print the guide for the specified topic.
+      #
+      # @param guide [String] The guide.
+      # @param topic [String] The topic.
+      #
+      def print_guide(**kwargs)
+        @stream.puts(kwargs.to_json)
       end
 
       def print_plan_lookup(value)
@@ -113,35 +135,38 @@ module Bolt
                        moduledir: moduledir.to_s }.to_json)
       end
 
-      def print_targets(target_list, inventory_source, default_inventory, _target_flag)
-        @stream.puts ::JSON.pretty_generate(
-          inventory: {
-            targets: target_list[:inventory].map(&:name),
-            count: target_list[:inventory].count,
-            file: (inventory_source || default_inventory).to_s
-          },
-          adhoc: {
-            targets: target_list[:adhoc].map(&:name),
-            count: target_list[:adhoc].count
-          },
-          targets: target_list.values.flatten.map(&:name),
-          count: target_list.values.flatten.count
-        )
-      end
-
-      def print_target_info(target_list, _inventory_source, _default_inventory, _target_flag)
-        targets = target_list.values.flatten
-
-        @stream.puts ::JSON.pretty_generate(
-          targets: targets.map(&:detail),
-          count: targets.count
-        )
-      end
-
-      def print_groups(groups, _inventory_source, _default_inventory)
-        count = groups.count
-        @stream.puts({ groups: groups,
-                       count: count }.to_json)
+      # Print target names and where they came from.
+      #
+      # @param adhoc [Hash] Adhoc targets provided on the command line.
+      # @param inventory [Hash] Targets provided from the inventory.
+      # @param targets [Array] All targets.
+      # @param count [Integer] Number of targets.
+      #
+      def print_targets(adhoc:, inventory:, targets:, count:, **_kwargs)
+        adhoc[:targets]     = adhoc[:targets].map { |t| t['name'] }
+        inventory[:targets] = inventory[:targets].map { |t| t['name'] }
+        targets             = targets.map { |t| t['name'] }
+        @stream.puts({ adhoc: adhoc, inventory: inventory, targets: targets, count: count }.to_json)
+      end
+
+      # Print target names and where they came from.
+      #
+      # @param adhoc [Hash] Adhoc targets provided on the command line.
+      # @param inventory [Hash] Targets provided from the inventory.
+      # @param targets [Array] All targets.
+      # @param count [Integer] Number of targets.
+      #
+      def print_target_info(adhoc:, inventory:, targets:, count:, **_kwargs)
+        @stream.puts({ adhoc: adhoc, inventory: inventory, targets: targets, count: count }.to_json)
+      end
+
+      # Print inventory group information.
+      #
+      # @param count [Integer] Number of groups in the inventory.
+      # @param groups [Array] Names of groups in the inventory.
+      #
+      def print_groups(count:, groups:, **_kwargs)
+        @stream.puts({ count: count, groups: groups }.to_json)
       end
 
       def fatal_error(err)

data/lib/bolt/outputter/logger.rb

@@ -24,6 +24,8 @@ module Bolt
           log_container_start(event)
         when :container_finish
           log_container_finish(event)
+        when :log, :message, :verbose
+          log_message(**event)
         end
       end
 
@@ -65,6 +67,10 @@ module Bolt
           @logger.info("Finished: run container '#{result.object}' failed.")
         end
       end
+
+      def log_message(level:, message:, **_kwargs)
+        @logger.send(level, message)
+      end
     end
   end
 end

data/lib/bolt/pal.rb

@@ -339,7 +339,7 @@ module Bolt
       end
 
       # Write the cache if any entries were updated
-      File.write(@project.task_cache_file, task_cache.to_json) if updated
+      File.write(@project.task_cache_file, task_cache.to_json) if updated && @project
       filter_content ? filter_content(task_list, @project&.tasks) : task_list
     end
 
@@ -435,7 +435,7 @@ module Bolt
         list << [plan_name, data['description']] unless data['private']
       end
 
-      File.write(@project.plan_cache_file, plan_cache.to_json) if updated
+      File.write(@project.plan_cache_file, plan_cache.to_json) if updated && @project
 
       filter_content ? filter_content(plan_list, @project&.plans) : plan_list
     end
@@ -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
@@ -635,6 +655,36 @@ module Bolt
       end
     end
 
+    # Return information about a module.
+    #
+    # @param name [String] The name of the module.
+    # @return [Hash]
+    #
+    def show_module(name)
+      name = name.tr('-', '/')
+
+      data = in_bolt_compiler do |_compiler|
+        mod = Puppet.lookup(:current_environment).module(name.split(%r{[/-]}, 2).last)
+
+        unless mod && (mod.forge_name == name || mod.name == name)
+          raise Bolt::Error.new("Could not find module '#{name}' on the modulepath.", 'bolt/unknown-module')
+        end
+
+        {
+          name:     mod.forge_name || mod.name,
+          metadata: mod.metadata,
+          path:     mod.path,
+          plans:    mod.plans.map(&:name).sort,
+          tasks:    mod.tasks.map(&:name).sort
+        }
+      end
+
+      data[:plans] = list_plans_with_cache.to_h.slice(*data[:plans]).to_a
+      data[:tasks] = list_tasks_with_cache.to_h.slice(*data[:tasks]).to_a
+
+      data
+    end
+
     def generate_types(cache: false)
       require 'puppet/face/generate'
       in_bolt_compiler do
@@ -683,7 +733,10 @@ module Bolt
         # Create a Fiber for the main plan. This will be run along with any
         # other Fibers created during the plan run in the round_robin, with the
         # main plan always taking precedence in being resumed.
-        future = executor.create_future(name: plan_name) do |_scope|
+        #
+        # Every future except for the main plan needs to have a plan id in
+        # order to be tracked for the `wait()` function with no arguments.
+        future = executor.create_future(name: plan_name, plan_id: 1) do |_scope|
           r = compiler.call_function('run_plan', plan_name, params.merge('_bolt_api_call' => true))
           Bolt::PlanResult.from_pcore(r, 'success')
         rescue Bolt::Error => e

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

@@ -13,6 +13,7 @@ module Bolt
           download
           eval
           message
+          verbose
           plan
           resources
           script
@@ -219,3 +220,4 @@ require 'bolt/pal/yaml_plan/step/task'
 require 'bolt/pal/yaml_plan/step/upload'
 require 'bolt/pal/yaml_plan/step/download'
 require 'bolt/pal/yaml_plan/step/message'
+require 'bolt/pal/yaml_plan/step/verbose'

data/lib/bolt/pal/yaml_plan/step/message.rb

@@ -24,14 +24,6 @@ module Bolt
           private def function
             'out::message'
           end
-
-          # Transpiles the step into the plan language
-          #
-          def transpile
-            code = String.new("  ")
-            code << function_call(function, format_args(body))
-            code << "\n"
-          end
         end
       end
     end

data/lib/bolt/pal/yaml_plan/step/verbose.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Bolt
+  class PAL
+    class YamlPlan
+      class Step
+        class Verbose < Step
+          def self.allowed_keys
+            super + Set['verbose']
+          end
+
+          def self.required_keys
+            Set['verbose']
+          end
+
+          # Returns an array of arguments to pass to the step's function call
+          #
+          private def format_args(body)
+            [body['verbose']]
+          end
+
+          # Returns the function corresponding to the step
+          #
+          private def function
+            'out::verbose'
+          end
+        end
+      end
+    end
+  end
+end

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/plan_creator.rb

@@ -51,7 +51,7 @@ module Bolt
       end
     end
 
-    def self.create_plan(plans_path, plan_name, outputter, is_puppet)
+    def self.create_plan(plans_path, plan_name, is_puppet)
       _, name_segments, basename = segment_plan_name(plan_name)
       dir_path = plans_path.join(*name_segments)
 
@@ -77,25 +77,7 @@ module Bolt
         )
       end
 
-      if Bolt::Util.powershell?
-        show_command = 'Get-BoltPlan -Name '
-        run_command  = 'Invoke-BoltPlan -Name '
-      else
-        show_command = 'bolt plan show'
-        run_command  = 'bolt plan run'
-      end
-
-      output = <<~OUTPUT
-        Created plan '#{plan_name}' at '#{plan_path}'
-
-        Show this plan with:
-            #{show_command} #{plan_name}
-        Run this plan with:
-            #{run_command} #{plan_name}
-      OUTPUT
-
-      outputter.print_message(output)
-      0
+      { name: plan_name, path: plan_path }
     end
 
     def self.segment_plan_name(plan_name)

data/lib/bolt/plan_future.rb

@@ -4,14 +4,34 @@ require 'fiber'
 
 module Bolt
   class PlanFuture
-    attr_reader :fiber, :id
-    attr_accessor :value
+    attr_reader :fiber, :id, :scope
+    attr_accessor :value, :plan_stack
 
-    def initialize(fiber, id, name = nil)
+    def initialize(fiber, id, plan_id:, name: nil, scope: nil)
       @fiber = fiber
       @id    = id
       @name  = name
       @value = nil
+
+      # Default to Puppet's current global_scope, otherwise things will
+      # blow up when the Fiber Executor tries to override the global_scope.
+      @scope = scope || Puppet.lookup(:global_scope) { nil }
+
+      # The plan invocation ID when the Future is created may be
+      # different from the plan ID of the Future when we switch to it if a new
+      # plan was run inside the Future, so keep track of the plans that a
+      # Future is executing in as a stack. When one plan finishes, pop it off
+      # since now we're in the calling plan. These IDs are unique to each plan
+      # invocation, not just plan names.
+      @plan_stack = [plan_id]
+    end
+
+    def original_plan
+      @plan_stack.last
+    end
+
+    def current_plan
+      @plan_stack.first
     end
 
     def name