bolt 2.30.0 → 2.34.0

data/lib/bolt/pal.rb

@@ -5,28 +5,20 @@ require 'bolt/executor'
 require 'bolt/error'
 require 'bolt/plan_result'
 require 'bolt/util'
+require 'bolt/config/modulepath'
 require 'etc'
 
 module Bolt
   class PAL
-    BOLTLIB_PATH = File.expand_path('../../bolt-modules', __dir__)
-    MODULES_PATH = File.expand_path('../../modules', __dir__)
-
     # PALError is used to convert errors from executing puppet code into
     # 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 = {}
@@ -34,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)
+        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
@@ -45,16 +44,16 @@ module Bolt
       end
     end
 
-    attr_reader :modulepath, :user_modulepath
-
     def initialize(modulepath, hiera_config, resource_types, max_compiles = Etc.nprocessors,
                    trusted_external = nil, apply_settings = {}, project = nil)
+      unless modulepath.is_a?(Bolt::Config::Modulepath)
+        msg = "Type error in PAL: modulepath must be a Bolt::Config::Modulepath"
+        raise Bolt::Error.new(msg, "bolt/execution-error")
+      end
       # Nothing works without initialized this global state. Reinitializing
       # is safe and in practice only happens in tests
       self.class.load_puppet
-
-      @user_modulepath = modulepath
-      @modulepath = [BOLTLIB_PATH, *modulepath, MODULES_PATH]
+      @modulepath = modulepath
       @hiera_config = hiera_config
       @trusted_external = trusted_external
       @apply_settings = apply_settings
@@ -63,13 +62,21 @@ module Bolt
       @project = project
 
       @logger = Bolt::Logger.logger(self)
-      if modulepath && !modulepath.empty?
-        @logger.debug("Loading modules from #{@modulepath.join(File::PATH_SEPARATOR)}")
+      unless user_modulepath.empty?
+        @logger.debug("Loading modules from #{full_modulepath.join(File::PATH_SEPARATOR)}")
       end
 
       @loaded = false
     end
 
+    def full_modulepath
+      @modulepath.full_modulepath
+    end
+
+    def user_modulepath
+      @modulepath.user_modulepath
+    end
+
     # Puppet logging is global so this is class method to avoid confusion
     def self.configure_logging
       Puppet::Util::Log.destinations.clear
@@ -157,7 +164,7 @@ module Bolt
     def in_bolt_compiler
       # TODO: If we always call this inside a bolt_executor we can remove this here
       setup
-      r = Puppet::Pal.in_tmp_environment('bolt', modulepath: @modulepath, facts: {}) do |pal|
+      r = Puppet::Pal.in_tmp_environment('bolt', modulepath: full_modulepath, facts: {}) do |pal|
         # Only load the project if it a) exists, b) has a name it can be loaded with
         Puppet.override(bolt_project: @project,
                         yaml_plan_instantiator: Bolt::PAL::YamlPlan::Loader) do
@@ -212,11 +219,11 @@ module Bolt
         apply_executor: applicator || Applicator.new(
           inventory,
           executor,
-          @modulepath,
+          full_modulepath,
           # Skip syncing built-in plugins, since we vendor some Puppet 6
           # versions of "core" types, which are already present on the agent,
           # but may cause issues on Puppet 5 agents.
-          @user_modulepath,
+          user_modulepath,
           @project,
           pdb_client,
           @hiera_config,
@@ -250,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
@@ -378,7 +390,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
@@ -443,8 +455,8 @@ module Bolt
     #   The information hash provides the name, version, and a string
     #   indicating whether the module belongs to an internal module group.
     def list_modules
-      internal_module_groups = { BOLTLIB_PATH => 'Plan Language Modules',
-                                 MODULES_PATH => 'Packaged Modules',
+      internal_module_groups = { Bolt::Config::Modulepath::BOLTLIB_PATH => 'Plan Language Modules',
+                                 Bolt::Config::Modulepath::MODULES_PATH => 'Packaged Modules',
                                  @project.managed_moduledir.to_s => 'Project Dependencies' }
 
       in_bolt_compiler do

data/lib/bolt/pal/yaml_plan.rb

@@ -98,10 +98,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

data/lib/bolt/plugin.rb

@@ -168,7 +168,7 @@ module Bolt
     end
 
     def modules
-      @modules ||= Bolt::Module.discover(@pal.modulepath)
+      @modules ||= Bolt::Module.discover(@pal.full_modulepath)
     end
 
     def add_plugin(plugin)
@@ -290,7 +290,7 @@ module Bolt
       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)