bolt 3.14.1 → 3.17.0

data/lib/bolt/outputter/json.rb

@@ -49,7 +49,11 @@ module Bolt
       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"
@@ -59,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
@@ -78,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
 
@@ -95,10 +108,19 @@ 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
 
+      # 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
@@ -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/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/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/plan_creator.rb

@@ -7,7 +7,7 @@ require 'bolt/util'
 
 module Bolt
   module PlanCreator
-    def self.validate_input(project, plan_name)
+    def self.validate_plan_name(project, plan_name)
       if project.name.nil?
         raise Bolt::Error.new(
           "Project directory '#{project.path}' is not a named project. Unable to create "\
@@ -51,7 +51,15 @@ module Bolt
       end
     end
 
-    def self.create_plan(plans_path, plan_name, outputter, is_puppet)
+    # Create a new plan from the plan templates based on which language the
+    # user configured, and whether the plan wraps a script.
+    #
+    # @param plans_path [string] The path to the new plan
+    # @param plan_name [string] The name of the new plan
+    # @param is_puppet [boolean] Whether to create a Puppet language plan
+    # @param script [string] A reference to a script for the new plan to run
+    #
+    def self.create_plan(plans_path, plan_name, is_puppet: false, script: nil)
       _, name_segments, basename = segment_plan_name(plan_name)
       dir_path = plans_path.join(*name_segments)
 
@@ -66,8 +74,15 @@ module Bolt
 
       type = is_puppet ? 'pp' : 'yaml'
       plan_path = dir_path + "#{basename}.#{type}"
-      plan_template = is_puppet ? puppet_plan(plan_name) : yaml_plan(plan_name)
-
+      plan_template = if is_puppet && script
+                        puppet_script_plan(plan_name, script)
+                      elsif is_puppet
+                        puppet_plan(plan_name)
+                      elsif script
+                        yaml_script_plan(script)
+                      else
+                        yaml_plan(plan_name)
+                      end
       begin
         File.write(plan_path, plan_template)
       rescue Errno::EACCES => e
@@ -77,25 +92,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)
@@ -108,7 +105,11 @@ module Bolt
       [prefix, name_segments, basename]
     end
 
-    def self.yaml_plan(plan_name)
+    # Template for a new simple YAML plan.
+    #
+    # @param plan_name [string] The name of the new plan
+    #
+    private_class_method def self.yaml_plan(plan_name)
       <<~YAML
         # This is the structure of a simple plan. To learn more about writing
         # YAML plans, see the documentation: http://pup.pt/bolt-yaml-plans
@@ -137,7 +138,42 @@ module Bolt
       YAML
     end
 
-    def self.puppet_plan(plan_name)
+    # Template for a new YAML plan that runs a script.
+    #
+    # @param script [string] A reference to the script to run.
+    #
+    private_class_method def self.yaml_script_plan(script)
+      <<~YAML
+        # This is the structure of a simple plan. To learn more about writing
+        # YAML plans, see the documentation: http://pup.pt/bolt-yaml-plans
+        
+        # The description sets the description of the plan that will appear
+        # in 'bolt plan show' output.
+        description: A plan created with bolt plan new
+
+        # The parameters key defines the parameters that can be passed to
+        # the plan.
+        parameters:
+          targets:
+            type: TargetSpec
+            description: A list of targets to run actions on
+
+        # The steps key defines the actions the plan will take in order.
+        steps:
+          - name: run_script
+            script: #{script}
+            targets: $targets
+
+        # The return key sets the return value of the plan.
+        return: $run_script
+      YAML
+    end
+
+    # Template for a new simple Puppet plan.
+    #
+    # @param plan_name [string] The name of the new plan
+    #
+    private_class_method def self.puppet_plan(plan_name)
       <<~PUPPET
         # This is the structure of a simple plan. To learn more about writing
         # Puppet plans, see the documentation: http://pup.pt/bolt-puppet-plans
@@ -156,5 +192,28 @@ module Bolt
         }
       PUPPET
     end
+
+    # Template for a new Puppet plan that only runs a script.
+    #
+    # @param plan_name [string] The name of the new plan
+    # @param script [string] A reference to the script to run
+    #
+    private_class_method def self.puppet_script_plan(plan_name, script)
+      <<~PUPPET
+        # This is the structure of a simple plan. To learn more about writing
+        # Puppet plans, see the documentation: http://pup.pt/bolt-puppet-plans
+
+        # The summary sets the description of the plan that will appear
+        # in 'bolt plan show' output. Bolt uses puppet-strings to parse the
+        # summary and parameters from the plan.
+        # @summary A plan created with bolt plan new.
+        # @param targets The targets to run on.
+        plan #{plan_name} (
+          TargetSpec $targets
+        ) {
+          return run_script('#{script}', $targets)
+        }
+      PUPPET
+    end
   end
 end

data/lib/bolt/plan_future.rb

@@ -4,14 +4,19 @@ require 'fiber'
 
 module Bolt
   class PlanFuture
-    attr_reader :fiber, :id
+    attr_reader :fiber, :id, :scope
     attr_accessor :value, :plan_stack
 
-    def initialize(fiber, id, plan_id:, name: nil)
-      @fiber   = fiber
-      @id      = id
-      @name    = name
-      @value   = 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

data/lib/bolt/plan_result.rb

@@ -6,7 +6,7 @@ require 'bolt/util'
 
 module Bolt
   class PlanResult
-    attr_accessor :value, :status
+    attr_accessor :status, :value
 
     # This must be called from inside a compiler
     def self.from_pcore(result, status)

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

@@ -127,29 +127,15 @@ module Bolt
       end
     end
 
-    def self.setup(config, pal, analytics = Bolt::Analytics::NoopClient.new, **opts)
-      plugins = new(config, pal, analytics, **opts)
-
-      config.plugins.each_key do |plugin|
-        plugins.by_name(plugin)
-      end
-
-      plugins.plugin_hooks.merge!(plugins.resolve_references(config.plugin_hooks))
-
-      plugins
-    end
-
     RUBY_PLUGINS = %w[task prompt env_var puppetdb puppet_connect_data].freeze
     BUILTIN_PLUGINS = %w[task terraform pkcs7 prompt vault aws_inventory puppetdb azure_inventory
                          yaml env_var gcloud_inventory].freeze
     DEFAULT_PLUGIN_HOOKS = { 'puppet_library' => { 'plugin' => 'puppet_agent', 'stop_service' => true } }.freeze
 
     attr_reader :pal, :plugin_context
-    attr_accessor :plugin_hooks
+    attr_writer :plugin_hooks
 
-    private_class_method :new
-
-    def initialize(config, pal, analytics, load_plugins: true)
+    def initialize(config, pal, analytics = Bolt::Analytics::NoopClient.new, load_plugins: true)
       @config = config
       @analytics = analytics
       @plugin_context = PluginContext.new(config, pal, self)
@@ -166,7 +152,15 @@ module Bolt
         raise Bolt::Error.new(msg, 'bolt/plugin-error')
       end
       @unresolved_plugin_configs['puppetdb'] = config.puppetdb if config.puppetdb
-      @plugin_hooks = DEFAULT_PLUGIN_HOOKS.dup
+    end
+
+    # Returns a map of configured plugin hooks. Any unresolved plugin references
+    # are resolved.
+    #
+    # @return [Hash[String, Hash]]
+    #
+    def plugin_hooks
+      @plugin_hooks ||= DEFAULT_PLUGIN_HOOKS.merge(resolve_references(@config.plugin_hooks))
     end
 
     def modules