bolt 2.33.1 → 2.37.0

data/lib/bolt/inventory/group.rb

@@ -241,10 +241,11 @@ module Bolt
         end
 
         if input.key?('nodes')
+          command = Bolt::Util.powershell? ? 'Update-BoltProject' : 'bolt project migrate'
           msg = <<~MSG.chomp
                 Found 'nodes' key in group #{@name}. This looks like a v1 inventory file, which is
                 no longer supported by Bolt. Migrate to a v2 inventory file automatically using
-                'bolt project migrate'.
+                '#{command}'.
                 MSG
           raise ValidationError.new(msg, nil)
         end

data/lib/bolt/module_installer.rb

@@ -63,7 +63,7 @@ module Bolt
 
       data = Bolt::Util.read_yaml_hash(config_path, 'project')
       data['modules'] ||= []
-      data['modules'] << name
+      data['modules'] << name.tr('-', '/')
 
       begin
         File.write(config_path, data.to_yaml)

data/lib/bolt/module_installer/specs/forge_spec.rb

@@ -11,7 +11,7 @@ module Bolt
   class ModuleInstaller
     class Specs
       class ForgeSpec
-        NAME_REGEX    = %r{\A[a-z][a-z0-9_]*[-/](?<name>[a-z][a-z0-9_]*)\z}.freeze
+        NAME_REGEX    = %r{\A[a-zA-Z0-9]+[-/](?<name>[a-z][a-z0-9_]*)\z}.freeze
         REQUIRED_KEYS = Set.new(%w[name]).freeze
         KNOWN_KEYS    = Set.new(%w[name version_requirement]).freeze
 
@@ -33,8 +33,9 @@ module Bolt
           unless (match = name.match(NAME_REGEX))
             raise Bolt::ValidationError,
                   "Invalid name for Forge module specification: #{name}. Name must match "\
-                  "'owner/name', must start with a lowercase letter, and may only include "\
-                  "lowercase letters, digits, and underscores."
+                  "'owner/name'. Owner segment may only include letters or digits. Name "\
+                  "segment must start with a lowercase letter and may only include lowercase "\
+                  "letters, digits, and underscores."
           end
 
           [name.tr('-', '/'), match[:name]]
@@ -54,7 +55,7 @@ module Bolt
         #
         def satisfied_by?(mod)
           @type == mod.type &&
-            @full_name == mod.full_name &&
+            @full_name.downcase == mod.full_name.downcase &&
             !mod.version.nil? &&
             @semantic_version.cover?(mod.version)
         end

data/lib/bolt/module_installer/specs/git_spec.rb

@@ -11,7 +11,7 @@ module Bolt
   class ModuleInstaller
     class Specs
       class GitSpec
-        NAME_REGEX    = %r{\A(?:[a-z][a-z0-9_]*[-/])?(?<name>[a-z][a-z0-9_]*)\z}.freeze
+        NAME_REGEX    = %r{\A(?:[a-zA-Z0-9]+[-/])?(?<name>[a-z][a-z0-9_]*)\z}.freeze
         REQUIRED_KEYS = Set.new(%w[git ref]).freeze
 
         attr_reader :git, :ref, :type
@@ -36,8 +36,9 @@ module Bolt
           unless (match = name.match(NAME_REGEX))
             raise Bolt::ValidationError,
                   "Invalid name for Git module specification: #{name}. Name must match "\
-                  "'name' or 'owner/name', must start with a lowercase letter, and may "\
-                  "only include lowercase letters, digits, and underscores."
+                  "'name' or 'owner/name'. Owner segment may only include letters or digits. "\
+                  "Name segment must start with a lowercase letter and may only include "\
+                  "lowercase letters, digits, and underscores."
           end
 
           match[:name]

data/lib/bolt/outputter/human.rb

@@ -214,9 +214,10 @@ module Bolt
       end
 
       def print_tasks(tasks, modulepath)
-        print_table(tasks)
+        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 `bolt task show <task-name>` to view "\
+                        "\nUse '#{command}' to view "\
                         "details and parameters for a specific task.")
       end
 
@@ -225,20 +226,26 @@ module Bolt
         # Building lots of strings...
         pretty_params = +""
         task_info = +""
-        usage = +"bolt task run --targets <node-name> #{task.name}"
+        usage = if Bolt::Util.powershell?
+                  +"Invoke-BoltTask -Name #{task.name} -Targets <targets>"
+                else
+                  +"bolt task run #{task.name} --targets <targets>"
+                end
 
         task.parameters&.each do |k, v|
           pretty_params << "- #{k}: #{v['type'] || 'Any'}\n"
           pretty_params << "    Default: #{v['default'].inspect}\n" if v.key?('default')
           pretty_params << "    #{v['description']}\n" if v['description']
-          usage << if v['type'].is_a?(Puppet::Pops::Types::POptionalType)
+          usage << if v['type'].start_with?("Optional")
                      " [#{k}=<value>]"
                    else
                      " #{k}=<value>"
                    end
         end
 
-        usage << " [--noop]" if task.supports_noop
+        if task.supports_noop
+          usage << Bolt::Util.powershell? ? '[-Noop]' : '[--noop]'
+        end
 
         task_info << "\n#{task.name}"
         task_info << " - #{task.description}" if task.description
@@ -261,7 +268,11 @@ module Bolt
         # Building lots of strings...
         pretty_params = +""
         plan_info = +""
-        usage = +"bolt plan run #{plan['name']}"
+        usage = if Bolt::Util.powershell?
+                  +"Invoke-BoltPlan -Name #{plan['name']}"
+                else
+                  +"bolt plan run #{plan['name']}"
+                end
 
         plan['parameters'].each do |name, p|
           pretty_params << "- #{name}: #{p['type']}\n"
@@ -287,16 +298,17 @@ module Bolt
       end
 
       def print_plans(plans, modulepath)
-        print_table(plans)
+        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 `bolt plan show <plan-name>` to view "\
+                        "\nUse '#{command}' to view "\
                         "details and parameters for a specific plan.")
       end
 
       def print_topics(topics)
         print_message("Available topics are:")
         print_message(topics.join("\n"))
-        print_message("\nUse `bolt guide <topic>` to view a specific guide.")
+        print_message("\nUse 'bolt guide <TOPIC>' to view a specific guide.")
       end
 
       def print_guide(guide, _topic)

data/lib/bolt/outputter/rainbow.rb

@@ -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

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')