bolt 2.42.0 → 3.3.0

data/lib/bolt/outputter/human.rb

@@ -32,8 +32,8 @@ module Bolt
       end
 
       def start_spin
-        return unless @spin && @stream.isatty
-        @spin = true
+        return unless @spin && @stream.isatty && !@spinning
+        @spinning = true
         @spin_thread = Thread.new do
           loop do
             sleep(0.1)
@@ -43,9 +43,9 @@ module Bolt
       end
 
       def stop_spin
-        return unless @spin && @stream.isatty
+        return unless @spin && @stream.isatty && @spinning
+        @spinning = false
         @spin_thread.terminate
-        @spin = false
         @stream.print("\b")
       end
 
@@ -53,10 +53,21 @@ module Bolt
         string.sub(/\s\z/, '')
       end
 
+      # Wraps a string to the specified width. Lines only wrap
+      # at whitespace.
+      #
       def wrap(string, width = 80)
+        return string unless string.is_a?(String)
         string.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n")
       end
 
+      # Trims a string to a specified width, adding an ellipsis if it's longer.
+      #
+      def truncate(string, width = 80)
+        return string unless string.is_a?(String) && string.length > width
+        string.lines.first[0...width].gsub(/\s\w+\s*$/, '...')
+      end
+
       def handle_event(event)
         case event[:type]
         when :enable_default_output
@@ -81,6 +92,10 @@ module Bolt
             print_plan_start(event)
           when :plan_finish
             print_plan_finish(event)
+          when :start_spin
+            start_spin
+          when :stop_spin
+            stop_spin
           end
         end
       end
@@ -214,11 +229,11 @@ module Bolt
         @stream.puts total_msg
       end
 
-      def print_table(results, padding_left = 0, padding_right = 3)
+      def format_table(results, padding_left = 0, padding_right = 3)
         # lazy-load expensive gem code
         require 'terminal-table'
 
-        @stream.puts Terminal::Table.new(
+        Terminal::Table.new(
           rows: results,
           style: {
             border_x: '',
@@ -234,10 +249,22 @@ module Bolt
 
       def print_tasks(tasks, modulepath)
         command = Bolt::Util.powershell? ? 'Get-BoltTask -Task <TASK NAME>' : 'bolt task show <TASK NAME>'
-        tasks.any? ? print_table(tasks) : print_message('No available tasks')
-        print_message("\nMODULEPATH:\n#{modulepath.join(File::PATH_SEPARATOR)}\n"\
-                        "\nUse '#{command}' to view "\
-                        "details and parameters for a specific task.")
+
+        tasks = tasks.map do |name, description|
+          description = truncate(description, 72)
+          [name, description]
+        end
+
+        @stream.puts colorize(:cyan, 'Tasks')
+        @stream.puts tasks.any? ? format_table(tasks, 2) : indent(2, 'No available tasks')
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Modulepath')
+        @stream.puts indent(2, modulepath.join(File::PATH_SEPARATOR))
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Additional information')
+        @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific task.")
       end
 
       # @param [Hash] task A hash representing the task
@@ -318,10 +345,22 @@ module Bolt
 
       def print_plans(plans, modulepath)
         command = Bolt::Util.powershell? ? 'Get-BoltPlan -Name <PLAN NAME>' : 'bolt plan show <PLAN NAME>'
-        plans.any? ? print_table(plans) : print_message('No available plans')
-        print_message("\nMODULEPATH:\n#{modulepath.join(File::PATH_SEPARATOR)}\n"\
-                        "\nUse '#{command}' to view "\
-                        "details and parameters for a specific plan.")
+
+        plans = plans.map do |name, description|
+          description = truncate(description, 72)
+          [name, description]
+        end
+
+        @stream.puts colorize(:cyan, 'Plans')
+        @stream.puts plans.any? ? format_table(plans, 2) : indent(2, 'No available plans')
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Modulepath')
+        @stream.puts indent(2, modulepath.join(File::PATH_SEPARATOR))
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Additional information')
+        @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific plan.")
       end
 
       def print_topics(topics)
@@ -355,7 +394,7 @@ module Bolt
               [m[:name], version]
             end
 
-            print_table(module_info, 2, 1)
+            @stream.puts format_table(module_info, 2, 1)
           end
 
           @stream.write("\n")
@@ -370,7 +409,7 @@ module Bolt
         targets += target_list[:adhoc].map { |target| [target.name, adhoc] }
 
         if targets.any?
-          print_table(targets, 0, 2)
+          @stream.puts format_table(targets, 0, 2)
           @stream.puts
         end
 
@@ -388,7 +427,7 @@ module Bolt
 
       def print_target_info(targets)
         @stream.puts ::JSON.pretty_generate(
-          "targets": targets.map(&:detail)
+          targets: targets.map(&:detail)
         )
         count = "#{targets.count} target#{'s' unless targets.count == 1}"
         @stream.puts colorize(:green, count)

data/lib/bolt/outputter/json.rb

@@ -95,38 +95,38 @@ module Bolt
       end
 
       def print_puppetfile_result(success, puppetfile, moduledir)
-        @stream.puts({ "success": success,
-                       "puppetfile": puppetfile,
-                       "moduledir": moduledir.to_s }.to_json)
+        @stream.puts({ success: success,
+                       puppetfile: puppetfile,
+                       moduledir: moduledir.to_s }.to_json)
       end
 
       def print_targets(target_list, inventoryfile)
         @stream.puts ::JSON.pretty_generate(
-          "inventory": {
-            "targets": target_list[:inventory].map(&:name),
-            "count": target_list[:inventory].count,
-            "file": inventoryfile.to_s
+          inventory: {
+            targets: target_list[:inventory].map(&:name),
+            count: target_list[:inventory].count,
+            file: inventoryfile.to_s
           },
-          "adhoc": {
-            "targets": target_list[:adhoc].map(&:name),
-            "count": target_list[:adhoc].count
+          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
+          targets: target_list.values.flatten.map(&:name),
+          count: target_list.values.flatten.count
         )
       end
 
       def print_target_info(targets)
         @stream.puts ::JSON.pretty_generate(
-          "targets": targets.map(&:detail),
-          "count": targets.count
+          targets: targets.map(&:detail),
+          count: targets.count
         )
       end
 
       def print_groups(groups)
         count = groups.count
-        @stream.puts({ "groups": groups,
-                       "count": count }.to_json)
+        @stream.puts({ groups: groups,
+                       count: count }.to_json)
       end
 
       def fatal_error(err)

data/lib/bolt/outputter/rainbow.rb

@@ -63,12 +63,12 @@ module Bolt
       end
 
       def start_spin
-        return unless @spin && @stream.isatty
-        @spin = true
+        return unless @spin && @stream.isatty && !@spinning
+        @spinning = true
         @spin_thread = Thread.new do
           loop do
-            @stream.print(colorize(:rainbow, @pinwheel.rotate!.first + "\b"))
             sleep(0.1)
+            @stream.print(colorize(:rainbow, @pinwheel.rotate!.first + "\b"))
           end
         end
       end

data/lib/bolt/pal.rb

@@ -153,8 +153,10 @@ module Bolt
         Dir.children(path).select { |name| Puppet::Module.is_module_directory?(name, path) }
       end
       if modules.include?(project.name)
-        Bolt::Logger.warn_once("project shadows module",
-                               "The project '#{project.name}' shadows an existing module of the same name")
+        Bolt::Logger.warn_once(
+          "project_shadows_module",
+          "The project '#{project.name}' shadows an existing module of the same name"
+        )
       end
     end
 
@@ -213,6 +215,7 @@ module Bolt
     def with_bolt_executor(executor, inventory, pdb_client = nil, applicator = nil, &block)
       setup
       opts = {
+        bolt_project: @project,
         bolt_executor: executor,
         bolt_inventory: inventory,
         bolt_pdb_client: pdb_client,
@@ -357,19 +360,52 @@ module Bolt
       Bolt::Task.from_task_signature(task)
     end
 
+    def list_plans_with_cache(filter_content: false)
+      # Don't filter content yet, so that if users update their plan filters
+      # we don't need to refresh the cache
+      plan_names = list_plans(filter_content: false).map(&:first)
+      plan_cache = if @project
+                     Bolt::Util.read_optional_json_file(@project.plan_cache_file, 'Plan cache file')
+                   else
+                     {}
+                   end
+      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)
+
+        # 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)
+          updated = true
+          plan_cache[plan_name] = info
+        end
+
+        list << [plan_name, info['description']] unless info['private']
+      end
+
+      File.write(@project.plan_cache_file, plan_cache.to_json) if updated
+
+      filter_content ? filter_content(plan_list, @project&.plans) : plan_list
+    end
+
     def list_plans(filter_content: false)
       in_bolt_compiler do |compiler|
         errors = []
         plans = compiler.list_plans(nil, errors).map { |plan| [plan.name] }.sort
         errors.each do |error|
-          @logger.warn(error.details['original_error'])
+          Bolt::Logger.warn("plan_load_error", error.details['original_error'])
         end
 
         filter_content ? filter_content(plans, @project&.plans) : plans
       end
     end
 
-    def get_plan_info(plan_name)
+    def get_plan_info(plan_name, with_mtime: false)
       plan_sig = in_bolt_compiler do |compiler|
         compiler.plan_signature(plan_name)
       end
@@ -410,18 +446,30 @@ module Bolt
             params[name] = { 'type' => param.types.first }
             params[name]['sensitive'] = param.types.first =~ /\ASensitive(\[.*\])?\z/ ? true : false
             params[name]['default_value'] = defaults[name] if defaults.key?(name)
-            params[name]['description'] = param.text unless param.text.empty?
+            params[name]['description'] = param.text if param.text && !param.text.empty?
           else
-            @logger.warn("The documented parameter '#{name}' does not exist in plan signature")
+            Bolt::Logger.warn(
+              "missing_plan_parameter",
+              "The documented parameter '#{name}' does not exist in signature for plan '#{plan.name}'"
+            )
           end
         end
 
-        {
-          'name' => plan_name,
+        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
+          'parameters'  => parameters,
+          'module'      => mod
         }
+        pp_info.merge!({ 'private' => privie&.downcase == 'true' }) unless privie.nil?
+        pp_info.merge!(get_plan_mtime(plan.file)) if with_mtime
+        pp_info
 
       # If it's a YAML plan, fall back to limited data
       else
@@ -444,12 +492,32 @@ module Bolt
           params[name]['default_value'] = param.value unless param.value.nil?
           params[name]['description'] = param.description if param.description
         end
-        {
-          'name' => plan_name,
+
+        yaml_info = {
+          'name'        => plan_name,
           'description' => plan.description,
-          'parameters' => parameters,
-          'module' => mod
+          'parameters'  => parameters,
+          'module'      => mod
         }
+        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
+
+    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
+      # if the plan has been updated since it was cached.
+      if @project &&
+         File.exist?(path) &&
+         (path.include?(File.join(@project.path, 'modules')) ||
+          path.include?(@project.plans_path.to_s))
+
+        { 'file' => { 'mtime' => File.mtime(path),
+                      'path' => path } }
+      else
+        {}
       end
     end
 
@@ -490,16 +558,28 @@ module Bolt
       end
     end
 
-    def generate_types
+    def generate_types(cache: false)
       require 'puppet/face/generate'
       in_bolt_compiler do
         generator = Puppet::Generate::Type
         inputs = generator.find_inputs(:pcore)
         FileUtils.mkdir_p(@resource_types)
+        cache_plan_info if @project && cache
         generator.generate(inputs, @resource_types, true)
       end
     end
 
+    def cache_plan_info
+      # plan_name is an array here
+      plans_info = list_plans(filter_content: false).map do |plan_name,|
+        data = get_plan_info(plan_name, with_mtime: true)
+        { plan_name => data }
+      end.reduce({}, :merge)
+
+      FileUtils.touch(@project.plan_cache_file)
+      File.write(@project.plan_cache_file, plans_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)

data/lib/bolt/pal/yaml_plan.rb

@@ -6,10 +6,10 @@ require 'bolt/pal/yaml_plan/step'
 module Bolt
   class PAL
     class YamlPlan
-      PLAN_KEYS = Set['parameters', 'steps', 'return', 'version', 'description']
+      PLAN_KEYS = Set['parameters', 'private', 'steps', 'return', 'version', 'description']
       VAR_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/.freeze
 
-      attr_reader :name, :parameters, :steps, :return, :description
+      attr_reader :name, :parameters, :private, :steps, :return, :description
 
       def initialize(name, plan)
         # Top-level plan keys aren't allowed to be Puppet code, so force them
@@ -30,6 +30,12 @@ module Bolt
           Parameter.new(param, definition)
         end.freeze
 
+        @private = plan['private']
+        unless @private.nil? || @private.is_a?(TrueClass) || @private.is_a?(FalseClass)
+          msg = "Plan #{@name} key 'private' must be a boolean, received: #{@private.inspect}"
+          raise Bolt::Error.new(msg, "bolt/invalid-plan")
+        end
+
         # Validate top level plan keys
         top_level_keys = plan.keys.to_set
         unless PLAN_KEYS.superset?(top_level_keys)
@@ -67,8 +73,7 @@ module Bolt
       def duplicate_check(used_names, name, step_number)
         if used_names.include?(name)
           error_message = "Duplicate step name or parameter detected: #{name.inspect}"
-          err = Step.step_error(error_message, name, step_number)
-          raise Bolt::Error.new(err, "bolt/invalid-plan")
+          raise Step::StepError.new(error_message, name, step_number)
         end
       end
 

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

@@ -12,165 +12,15 @@ module Bolt
           @evaluator = Puppet::Pops::Parser::EvaluatingParser.new
         end
 
-        def dispatch_step(scope, step)
-          step_body = evaluate_code_blocks(scope, step.body)
-
-          # Dispatch based on the step class name
-          step_type = step.class.name.split('::').last.downcase
-          method = "#{step_type}_step"
-
-          send(method, scope, step_body)
-        end
-
-        def task_step(scope, step)
-          task = step['task']
-          targets = step['targets'] || step['target']
-          description = step['description']
-          params = step['parameters'] || {}
-
-          args = if description
-                   [task, targets, description, params]
-                 else
-                   [task, targets, params]
-                 end
-
-          scope.call_function('run_task', args)
-        end
-
-        def plan_step(scope, step)
-          plan = step['plan']
-          parameters = step['parameters'] || {}
-
-          args = [plan, parameters]
-
-          scope.call_function('run_plan', args)
-        end
-
-        def script_step(scope, step)
-          script = step['script']
-          targets = step['targets'] || step['target']
-          description = step['description']
-          arguments = step['arguments'] || []
-
-          options = { 'arguments' => arguments }
-          args = if description
-                   [script, targets, description, options]
-                 else
-                   [script, targets, options]
-                 end
-
-          scope.call_function('run_script', args)
-        end
-
-        def command_step(scope, step)
-          command = step['command']
-          targets = step['targets'] || step['target']
-          description = step['description']
-
-          args = [command, targets]
-          args << description if description
-          scope.call_function('run_command', args)
-        end
-
-        def upload_step(scope, step)
-          source = step['upload'] || step['source']
-          destination = step['destination']
-          targets = step['targets'] || step['target']
-          description = step['description']
-
-          args = [source, destination, targets]
-          args << description if description
-          scope.call_function('upload_file', args)
-        end
-
-        def download_step(scope, step)
-          source = step['download']
-          destination = step['destination']
-          targets = step['targets'] || step['target']
-          description = step['description']
-
-          args = [source, destination, targets]
-          args << description if description
-          scope.call_function('download_file', args)
-        end
-
-        def eval_step(_scope, step)
-          step['eval']
-        end
-
-        def resources_step(scope, step)
-          targets = step['targets'] || step['target']
-
-          # TODO: Only call apply_prep when needed
-          scope.call_function('apply_prep', targets)
-          manifest = generate_manifest(step['resources'])
-
-          apply_manifest(scope, targets, manifest)
-        end
-
-        def message_step(scope, step)
-          scope.call_function('out::message', [step['message']])
-        end
-
-        def generate_manifest(resources)
-          # inspect returns the Ruby representation of the resource hashes,
-          # which happens to be the same as the Puppet representation
-          puppet_resources = resources.inspect
-
-          # Because the :tasks setting globally controls which mode the parser
-          # is in, we need to make this snippet of non-tasks manifest code
-          # parseable in tasks mode. The way to do that is by putting it in an
-          # apply statement and taking the body.
-          <<~MANIFEST
-          apply('placeholder') {
-            $resources = #{puppet_resources}
-            $resources.each |$res| {
-              Resource[$res['type']] { $res['title']:
-                * => $res['parameters'],
-              }
-            }
-
-            # Add relationships if there is more than one resource
-            if $resources.length > 1 {
-              ($resources.length - 1).each |$index| {
-                $lhs = $resources[$index]
-                $rhs = $resources[$index+1]
-                $lhs_resource = Resource[$lhs['type'] , $lhs['title']]
-                $rhs_resource = Resource[$rhs['type'] , $rhs['title']]
-                $lhs_resource -> $rhs_resource
-              }
-            }
-          }
-          MANIFEST
-        end
-
-        def apply_manifest(scope, targets, manifest)
-          ast = @evaluator.parse_string(manifest)
-          apply_block = ast.body.body
-          applicator = Puppet.lookup(:apply_executor)
-          applicator.apply([targets], apply_block, scope)
-        end
-
         # This is the method that Puppet calls to evaluate the plan. The name
         # makes more sense for .pp plans.
+        #
         def evaluate_block_with_bindings(closure_scope, args_hash, plan)
-          if plan.steps.any? { |step| step.body.key?('target') }
-            msg = "The 'target' parameter for YAML plan steps is deprecated and will be removed "\
-                  "in a future version of Bolt. Use the 'targets' parameter instead."
-            Bolt::Logger.deprecation_warning("Using 'target' parameter for YAML plan steps, not 'targets'", msg)
-          end
-
-          if plan.steps.any? { |step| step.body.key?('source') }
-            msg = "The 'source' parameter for YAML plan upload steps is deprecated and will be removed "\
-                  "in a future version of Bolt. Use the 'upload' parameter instead."
-            Bolt::Logger.deprecation_warning("Using 'source' parameter for YAML upload steps, not 'upload'", msg)
-          end
-
           plan_result = closure_scope.with_local_scope(args_hash) do |scope|
             plan.steps.each do |step|
-              step_result = dispatch_step(scope, step)
+              step_result = step.evaluate(scope, self)
 
-              scope.setvar(step.name, step_result) if step.name
+              scope.setvar(step.body['name'], step_result) if step.body['name']
             end
 
             evaluate_code_blocks(scope, plan.return)
@@ -180,6 +30,7 @@ module Bolt
         end
 
         # Recursively evaluate any EvaluableString instances in the object.
+        #
         def evaluate_code_blocks(scope, value)
           # XXX We should establish a local scope here probably
           case value
@@ -204,6 +55,7 @@ module Bolt
         # Occasionally the Closure will ask us to evaluate what it assumes are
         # AST objects. Because we've sidestepped the AST, they aren't, so just
         # return the values as already evaluated.
+        #
         def evaluate(value, _scope)
           value
         end