bolt 2.32.0 → 2.36.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)
@@ -187,6 +187,7 @@ module Bolt
       ok = Installer.new(config).install(path, moduledir)
 
       # Automatically generate types after installing modules
+      @outputter.print_action_step("Generating type references")
       @pal.generate_types
 
       @outputter.print_puppetfile_result(ok, path, moduledir)

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

@@ -14,17 +14,11 @@ module Bolt
     # Bolt::Errors
     class PALError < Bolt::Error
       def self.from_preformatted_error(err)
-        if err.cause.is_a? Bolt::Error
-          err.cause
-        else
-          from_error(err)
-        end
-      end
-
-      # Generate a Bolt::Pal::PALError for non-bolt errors
-      def self.from_error(err)
-        # Use the original error message if available
-        message = err.cause ? err.cause.message : err.message
+        error = if err.cause.is_a? Bolt::Error
+                  err.cause
+                else
+                  from_error(err)
+                end
 
         # Provide the location of an error if it came from a plan
         details = {}
@@ -32,8 +26,15 @@ module Bolt
         details[:line]   = err.line if defined?(err.line)
         details[:column] = err.pos if defined?(err.pos)
 
-        e = new(message, details.compact)
+        error.add_filelineno(details.compact)
+        error
+      end
 
+      # Generate a Bolt::Pal::PALError for non-bolt errors
+      def self.from_error(err)
+        # Use the original error message if available
+        message = err.cause ? err.cause.message : err.message
+        e = new(message)
         e.set_backtrace(err.backtrace)
         e
       end
@@ -256,19 +257,24 @@ module Bolt
 
     # TODO: PUP-8553 should replace this
     def with_puppet_settings
-      Dir.mktmpdir('bolt') do |dir|
-        cli = []
-        Puppet::Settings::REQUIRED_APP_SETTINGS.each do |setting|
-          cli << "--#{setting}" << dir
-        end
-        Puppet.settings.send(:clear_everything_for_tests)
-        Puppet.initialize_settings(cli)
-        Puppet::GettextConfig.create_default_text_domain
-        Puppet[:trusted_external_command] = @trusted_external
-        Puppet.settings[:hiera_config] = @hiera_config
-        self.class.configure_logging
-        yield
+      dir = Dir.mktmpdir('bolt')
+
+      cli = []
+      Puppet::Settings::REQUIRED_APP_SETTINGS.each do |setting|
+        cli << "--#{setting}" << dir
       end
+      Puppet.settings.send(:clear_everything_for_tests)
+      Puppet.initialize_settings(cli)
+      Puppet::GettextConfig.create_default_text_domain
+      Puppet[:trusted_external_command] = @trusted_external
+      Puppet.settings[:hiera_config] = @hiera_config
+      self.class.configure_logging
+      yield
+    ensure
+      # Delete the tmpdir if it still exists. This check is needed to
+      # prevent Bolt from erroring if the tmpdir is somehow deleted
+      # before reaching this point.
+      FileUtils.remove_entry_secure(dir) if File.exist?(dir)
     end
 
     # Parses a snippet of Puppet manifest code and returns the AST represented
@@ -280,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
 
@@ -340,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
 
@@ -384,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')
@@ -98,10 +105,12 @@ module Bolt
       # subclasses this parent class in order to implement its own evaluation
       # logic.
       class EvaluableString
-        attr_reader :value
+        attr_reader :file, :line, :value
 
-        def initialize(value)
+        def initialize(value, file = nil, line = nil)
           @value = value
+          @file  = file
+          @line  = line
         end
 
         def ==(other)

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

@@ -191,7 +191,11 @@ module Bolt
               o[key] = evaluate_code_blocks(scope, v)
             end
           when EvaluableString
-            value.evaluate(scope, @evaluator)
+            begin
+              value.evaluate(scope, @evaluator)
+            rescue StandardError => e
+              raise format_evaluate_error(e, value)
+            end
           else
             value
           end
@@ -203,6 +207,24 @@ module Bolt
         def evaluate(value, _scope)
           value
         end
+
+        def format_evaluate_error(error, value)
+          # The Puppet::PreformattedError includes the line number of the
+          # evaluable string that caused the error, while the value includes the
+          # line number of the YAML plan that the string began on. To get the
+          # actual line number of the error, add these two numbers together.
+          line = error.line + value.line
+
+          # If the evaluable string is not a scalar literal, correct for it
+          # being on the same line as the step key.
+          line -= 1 if value.is_a?(BareString)
+
+          Bolt::PlanFailure.new(
+            error.basic_message,
+            'bolt/evaluation-error',
+            { file: value.file, line: line }
+          )
+        end
       end
     end
   end

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

@@ -9,10 +9,15 @@ module Bolt
     class YamlPlan
       class Loader
         class PuppetVisitor < Psych::Visitors::NoAliasRuby
-          def self.create_visitor
+          def initialize(scanner, class_loader, file)
+            super(scanner, class_loader)
+            @file = file
+          end
+
+          def self.create_visitor(source_ref)
             class_loader = Psych::ClassLoader::Restricted.new([], [])
             scanner = Psych::ScalarScanner.new(class_loader)
-            new(scanner, class_loader)
+            new(scanner, class_loader, source_ref)
           end
 
           def deserialize(node)
@@ -23,18 +28,18 @@ module Bolt
                 # @ss is a ScalarScanner, from the base ToRuby visitor class
                 node.value
               when Psych::Nodes::Scalar::DOUBLE_QUOTED
-                DoubleQuotedString.new(node.value)
-              # | style string or > style string
-              when Psych::Nodes::Scalar::LITERAL, Psych::Nodes::Scalar::FOLDED
-                CodeLiteral.new(node.value)
-              # This one shouldn't be possible
+                DoubleQuotedString.new(node.value, @file, node.start_line + 1)
+              # | style string
+              when Psych::Nodes::Scalar::LITERAL
+                CodeLiteral.new(node.value, @file, node.start_line + 1)
+              # > style string
               else
                 @ss.tokenize(node.value)
               end
             else
               value = @ss.tokenize(node.value)
               if value.is_a?(String)
-                BareString.new(value)
+                BareString.new(value, @file, node.start_line + 1)
               else
                 value
               end
@@ -50,7 +55,7 @@ module Bolt
                        else
                          Psych.parse(yaml_string, source_ref)
                        end
-          PuppetVisitor.create_visitor.accept(parse_tree)
+          PuppetVisitor.create_visitor(source_ref).accept(parse_tree)
         end
 
         def self.from_string(name, yaml_string, source_ref)

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