bolt 2.33.2 → 2.38.0

data/lib/bolt/outputter/json.rb

@@ -3,7 +3,7 @@
 module Bolt
   class Outputter
     class JSON < Bolt::Outputter
-      def initialize(color, verbose, trace, stream = $stdout)
+      def initialize(color, verbose, trace, spin, stream = $stdout)
         super
         @items_open = false
         @object_open = false

data/lib/bolt/outputter/logger.rb

@@ -6,7 +6,7 @@ module Bolt
   class Outputter
     class Logger < Bolt::Outputter
       def initialize(verbose, trace)
-        super(false, verbose, trace)
+        super(false, verbose, trace, false)
         @logger = Bolt::Logger.logger(self)
       end
 

data/lib/bolt/outputter/rainbow.rb

@@ -5,7 +5,7 @@ require 'bolt/pal'
 module Bolt
   class Outputter
     class Rainbow < Bolt::Outputter::Human
-      def initialize(color, verbose, trace, stream = $stdout)
+      def initialize(color, verbose, trace, spin, stream = $stdout)
         begin
           require 'paint'
           if Bolt::Util.windows?
@@ -53,7 +53,7 @@ module Bolt
                 @state = :normal if c == 'm'
               end
             end
-            a.join('')
+            a.join
           else
             "\033[#{COLORS[color]}m#{string}\033[0m"
           end
@@ -62,6 +62,17 @@ module Bolt
         end
       end
 
+      def start_spin
+        return unless @spin
+        @spin = true
+        @spin_thread = Thread.new do
+          loop do
+            @stream.print(colorize(:rainbow, @pinwheel.rotate!.first + "\b"))
+            sleep(0.1)
+          end
+        end
+      end
+
       def print_summary(results, elapsed_time = nil)
         ok_set = results.ok_set
         unless ok_set.empty?

data/lib/bolt/pal.rb

@@ -26,7 +26,7 @@ module Bolt
         details[:line]   = err.line if defined?(err.line)
         details[:column] = err.pos if defined?(err.pos)
 
-        error.add_filelineno(details)
+        error.add_filelineno(details.compact)
         error
       end
 
@@ -286,15 +286,26 @@ module Bolt
       raise Bolt::PAL::PALError, "Failed to parse manifest: #{e}"
     end
 
-    def list_tasks
+    # Filters content by a list of names and glob patterns specified in project
+    # configuration.
+    def filter_content(content, patterns)
+      return content unless content && patterns
+
+      content.select do |name,|
+        patterns.any? { |pattern| File.fnmatch?(pattern, name, File::FNM_EXTGLOB) }
+      end
+    end
+
+    def list_tasks(filter_content: false)
       in_bolt_compiler do |compiler|
-        tasks = compiler.list_tasks
-        tasks.map(&:name).sort.each_with_object([]) do |task_name, data|
+        tasks = compiler.list_tasks.map(&:name).sort.each_with_object([]) do |task_name, data|
           task_sig = compiler.task_signature(task_name)
           unless task_sig.task_hash['metadata']['private']
             data << [task_name, task_sig.task_hash['metadata']['description']]
           end
         end
+
+        filter_content ? filter_content(tasks, @project&.tasks) : tasks
       end
     end
 
@@ -346,14 +357,15 @@ module Bolt
       Bolt::Task.from_task_signature(task)
     end
 
-    def list_plans
+    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'])
         end
-        plans
+
+        filter_content ? filter_content(plans, @project&.plans) : plans
       end
     end
 
@@ -390,7 +402,7 @@ module Bolt
                         plan.docstring
                       end
 
-        defaults = plan.parameters.reject { |_, value| value.nil? }.to_h
+        defaults = plan.parameters.to_h.compact
         signature_params = Set.new(plan.parameters.map(&:first))
         parameters = plan.tags(:param).each_with_object({}) do |param, params|
           name = param.name

data/lib/bolt/pal/yaml_plan.rb

@@ -45,6 +45,13 @@ module Bolt
         used_names = Set.new(@parameters.map(&:name))
 
         @steps = plan['steps'].each_with_index.map do |step, index|
+          unless step.is_a?(Hash)
+            raise Bolt::Error.new(
+              "Parse error in step number #{index + 1}: Plan step must be an object with valid step keys.",
+              'bolt/invalid-plan'
+            )
+          end
+
           # Step keys also aren't allowed to be code and neither is the value of "name"
           stringified_step = Bolt::Util.walk_keys(step) { |key| stringify(key) }
           stringified_step['name'] = stringify(stringified_step['name']) if stringified_step.key?('name')

data/lib/bolt/plan_creator.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/logger'
+require 'bolt/module'
+require 'bolt/util'
+
+module Bolt
+  module PlanCreator
+    def self.validate_input(project, plan_name)
+      if project.name.nil?
+        raise Bolt::Error.new(
+          "Project directory '#{project.path}' is not a named project. Unable to create "\
+          "a project-level plan. To name a project, set the 'name' key in the 'bolt-project.yaml' "\
+          "configuration file.",
+          "bolt/unnamed-project-error"
+        )
+      end
+
+      if plan_name !~ Bolt::Module::CONTENT_NAME_REGEX
+        message = <<~MESSAGE.chomp
+          Invalid plan name '#{plan_name}'. Plan names are composed of one or more name segments
+          separated by double colons '::'.
+
+          Each name segment must begin with a lowercase letter, and may only include lowercase
+          letters, digits, and underscores.
+
+          Examples of valid plan names:
+              - #{project.name}
+              - #{project.name}::my_plan
+        MESSAGE
+
+        raise Bolt::ValidationError, message
+      end
+
+      prefix, _, basename = segment_plan_name(plan_name)
+
+      unless prefix == project.name
+        message = "First segment of plan name '#{plan_name}' must match project name '#{project.name}'. "\
+                  "Did you mean '#{project.name}::#{plan_name}'?"
+
+        raise Bolt::ValidationError, message
+      end
+
+      %w[pp yaml].each do |ext|
+        next unless (path = project.plans_path + "#{basename}.#{ext}").exist?
+        raise Bolt::Error.new(
+          "A plan with the name '#{plan_name}' already exists at '#{path}', nothing to do.",
+          'bolt/existing-plan-error'
+        )
+      end
+    end
+
+    def self.create_plan(plans_path, plan_name, outputter, is_puppet)
+      _, name_segments, basename = segment_plan_name(plan_name)
+      dir_path = plans_path.join(*name_segments)
+
+      begin
+        FileUtils.mkdir_p(dir_path)
+      rescue Errno::EEXIST => e
+        raise Bolt::Error.new(
+          "#{e.message}; unable to create plan directory '#{dir_path}'",
+          'bolt/existing-file-error'
+        )
+      end
+
+      type = is_puppet ? 'pp' : 'yaml'
+      plan_path = dir_path + "#{basename}.#{type}"
+      plan_template = is_puppet ? puppet_plan(plan_name) : yaml_plan(plan_name)
+
+      begin
+        File.write(plan_path, plan_template)
+      rescue Errno::EACCES => e
+        raise Bolt::FileError.new(
+          "#{e.message}; unable to create plan",
+          plan_path
+        )
+      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
+    end
+
+    def self.segment_plan_name(plan_name)
+      prefix, *name_segments, basename = plan_name.split('::')
+
+      # If the plan name is just the project name, then create an 'init' plan.
+      # Otherwise, use the last name segment for the plan's filename.
+      basename ||= 'init'
+
+      [prefix, name_segments, basename]
+    end
+
+    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
+
+        # 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
+            default: localhost
+
+        # The steps key defines the actions the plan will take in order.
+        steps:
+          - message: Hello from #{plan_name}
+          - name: command_step
+            command: whoami
+            targets: $targets
+
+        # The return key sets the return value of the plan.
+        return: $command_step
+      YAML
+    end
+
+    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
+
+        # 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 = "localhost"
+        ) {
+          out::message("Hello from #{plan_name}")
+          $command_result = run_command('whoami', $targets)
+          return $command_result
+        }
+      PUPPET
+    end
+  end
+end

data/lib/bolt/plugin.rb

@@ -4,6 +4,7 @@ require 'bolt/inventory'
 require 'bolt/executor'
 require 'bolt/module'
 require 'bolt/pal'
+require 'bolt/plugin/cache'
 require 'bolt/plugin/puppetdb'
 
 module Bolt
@@ -36,6 +37,13 @@ module Bolt
           super("Plugin #{plugin_name} does not support #{hook}", 'bolt/unsupported-hook')
         end
       end
+
+      class LoadingDisabled < PluginError
+        def initialize(plugin_name)
+          msg = "Cannot load plugin #{plugin_name}: plugin loading is disabled"
+          super(msg, 'bolt/plugin-loading-disabled', { 'plugin_name' => plugin_name })
+        end
+      end
     end
 
     class PluginContext
@@ -119,15 +127,8 @@ module Bolt
       end
     end
 
-    def self.setup(config, pal, analytics = Bolt::Analytics::NoopClient.new)
-      plugins = new(config, pal, analytics)
-
-      # Initialize any plugins referenced in plugin config. This will also indirectly
-      # initialize any plugins they depend on.
-      if plugins.reference?(config.plugins)
-        msg = "The 'plugins' setting cannot be set by a plugin reference"
-        raise PluginError.new(msg, 'bolt/plugin-error')
-      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)
@@ -148,12 +149,13 @@ module Bolt
 
     private_class_method :new
 
-    def initialize(config, pal, analytics)
+    def initialize(config, pal, analytics, load_plugins: true)
       @config = config
       @analytics = analytics
       @plugin_context = PluginContext.new(config, pal, self)
       @plugins = {}
       @pal = pal
+      @load_plugins = load_plugins
       @unknown = Set.new
       @resolution_stack = []
       @unresolved_plugin_configs = config.plugins.dup
@@ -176,6 +178,8 @@ module Bolt
     end
 
     def add_ruby_plugin(plugin_name)
+      raise PluginError::LoadingDisabled, plugin_name unless @load_plugins
+
       cls_name = Bolt::Util.snake_name_to_class_name(plugin_name)
       filename = "bolt/plugin/#{plugin_name}"
       require filename
@@ -192,10 +196,17 @@ module Bolt
     def add_module_plugin(plugin_name)
       opts = {
         context: @plugin_context,
+        # Make sure that the plugin's config is validated _before_ the unknown-plugin
+        # and loading-disabled checks. This way, we can fail early on invalid plugin
+        # config instead of _after_ loading the modulepath (which can be expensive).
         config: config_for_plugin(plugin_name)
       }
 
-      plugin = Bolt::Plugin::Module.load(plugin_name, modules, opts)
+      mod = modules[plugin_name]
+      raise PluginError::Unknown, plugin_name unless mod&.plugin?
+      raise PluginError::LoadingDisabled, plugin_name unless @load_plugins
+
+      plugin = Bolt::Plugin::Module.load(mod, opts)
       add_plugin(plugin)
     end
 
@@ -284,27 +295,45 @@ module Bolt
     # Evaluates a single reference. The value returned may be another
     # reference.
     def resolve_single_reference(reference)
+      plugin_cache = if cache?(reference)
+                       cache = Bolt::Plugin::Cache.new(reference,
+                                                       @config.project.cache_file,
+                                                       @config.plugin_cache)
+                       entry = cache.read_and_clean_cache
+                       return entry unless entry.nil?
+
+                       cache
+                     end
+
       plugin_name = reference['_plugin']
       hook = get_hook(plugin_name, :resolve_reference)
 
       begin
         validate_proc = get_hook(plugin_name, :validate_resolve_reference)
       rescue PluginError
-        validate_proc = proc { |*args| }
+        validate_proc = proc { |*args| } # Nothing to do
       end
 
       validate_proc.call(reference)
 
-      begin
+      result = begin
         # Evaluate the plugin and then recursively evaluate any plugin returned by it.
         hook.call(reference)
       rescue StandardError => e
         loc = "resolve_reference in #{plugin_name}"
         raise PluginError::ExecutionError.new(e.message, plugin_name, loc)
       end
+
+      plugin_cache.write_cache(result) if cache?(reference)
+
+      result
     end
     private :resolve_single_reference
 
+    private def cache?(reference)
+      reference.key?('_cache') || @config.plugin_cache.key?('ttl')
+    end
+
     # Checks whether a given value is a _plugin reference
     def reference?(input)
       input.is_a?(Hash) && input.key?('_plugin')

data/lib/bolt/plugin/cache.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'bolt/error'
+require 'bolt/util'
+
+module Bolt
+  class Plugin
+    class Cache
+      attr_reader :reference, :cache_file, :default_config, :id
+
+      def initialize(reference, cache_file, default_config)
+        @reference = reference
+        @cache_file = cache_file
+        @default_config = default_config
+      end
+
+      def read_and_clean_cache
+        return if ttl == 0
+        validate
+
+        # Luckily we don't need to use a serious hash algorithm
+        require 'digest/bubblebabble'
+        r = reference.select { |k, _| k == '_cache' }.sort.to_s
+        @id = Digest::SHA2.bubblebabble(r)[0..20]
+
+        unmodified = true
+        # First remove any cache entries past their ttl
+        # This prevents removing plugins from leaving orphaned cache entries
+        cache.delete_if do |_, entry|
+          expired = Time.now - Time.parse(entry['mtime']) >= entry['ttl']
+          unmodified = false if expired
+          expired
+        end
+        File.write(cache_file, cache.to_json) unless cache.empty? || unmodified
+
+        cache.dig(id, 'result')
+      end
+
+      private def cache
+        @cache ||= Bolt::Util.read_optional_json_file(@cache_file, 'cache')
+      end
+
+      def write_cache(result)
+        cache.merge!({ id => { 'result' => result,
+                               'mtime' => Time.now,
+                               'ttl' => ttl } })
+        FileUtils.touch(cache_file)
+        File.write(cache_file, cache.to_json)
+      end
+
+      def validate
+        # The default cache `plugin-cache` will be validated by the config
+        # validator
+        return if reference['_cache'].nil?
+        r = reference['_cache']
+        unless r.is_a?(Hash)
+          raise Bolt::ValidationError,
+                "_cache must be a Hash, received #{r.class}: #{r.inspect}"
+        end
+
+        unless r.key?('ttl')
+          raise Bolt::ValidationError, "_cache must set 'ttl' key."
+        end
+
+        unless r['ttl'] >= 0
+          raise Bolt::ValidationError, "'ttl' key under '_cache' must be a minimum of 0."
+        end
+      end
+
+      private def ttl
+        @ttl ||= reference.dig('_cache', 'ttl') || default_config['ttl']
+      end
+    end
+  end
+end