bolt 3.13.0 → 3.14.1

data/lib/bolt/outputter/human.rb

@@ -341,7 +341,7 @@ module Bolt
         info << if task.description
                   indent(2, task.description.chomp)
                 else
-                  indent(2, 'No description')
+                  indent(2, 'No description available.')
                 end
         info << "\n\n"
 
@@ -400,7 +400,7 @@ module Bolt
         info << if plan['description']
                   indent(2, plan['description'].chomp)
                 else
-                  indent(2, 'No description')
+                  indent(2, 'No description available.')
                 end
         info << "\n\n"
 
@@ -471,8 +471,16 @@ module Bolt
         @stream.puts info
       end
 
-      def print_guide(guide, _topic)
-        @stream.puts(guide)
+      def print_guide(topic:, guide:, documentation: nil)
+        info = +"#{colorize(:cyan, topic)}\n"
+        info << indent(2, guide)
+
+        if documentation
+          info << "\n#{colorize(:cyan, 'Documentation')}\n"
+          info << indent(2, documentation.join("\n"))
+        end
+
+        @stream.puts info
       end
 
       def print_plan_lookup(value)
@@ -480,15 +488,19 @@ module Bolt
       end
 
       def print_module_list(module_list)
+        info = +''
+
         module_list.each do |path, modules|
-          if (mod = modules.find { |m| m[:internal_module_group] })
-            @stream.puts(colorize(:cyan, mod[:internal_module_group]))
-          else
-            @stream.puts(colorize(:cyan, path))
-          end
+          info << if (mod = modules.find { |m| m[:internal_module_group] })
+                    colorize(:cyan, mod[:internal_module_group])
+                  else
+                    colorize(:cyan, path)
+                  end
+
+          info << "\n"
 
           if modules.empty?
-            @stream.puts('(no modules installed)')
+            info << '(no modules installed)'
           else
             module_info = modules.map do |m|
               version = if m[:version].nil?
@@ -500,11 +512,87 @@ module Bolt
               [m[:name], version]
             end
 
-            @stream.puts format_table(module_info, 2, 1)
+            info << format_table(module_info, 2, 1).to_s
+          end
+
+          info << "\n\n"
+        end
+
+        command = Bolt::Util.powershell? ? 'Get-BoltModule -Name <MODULE>' : 'bolt module show <MODULE>'
+        info << colorize(:cyan, "Additional information\n")
+        info << indent(2, "Use '#{command}' to view details for a specific module.")
+
+        @stream.puts info
+      end
+
+      # Prints detailed module information.
+      #
+      # @param name [String] The module's short name.
+      # @param metadata [Hash] The module's metadata.
+      # @param path [String] The path to the module.
+      # @param plans [Array] The module's plans.
+      # @param tasks [Array] The module's tasks.
+      #
+      def print_module_info(name:, metadata:, path:, plans:, tasks:, **_kwargs)
+        info = +''
+
+        info << colorize(:cyan, name)
+
+        info << colorize(:dim, " [#{metadata['version']}]") if metadata['version']
+        info << "\n"
+
+        info << if metadata['summary']
+                  indent(2, wrap(metadata['summary'].strip, 76))
+                else
+                  indent(2, "No description available.\n")
+                end
+        info << "\n"
+
+        if tasks.any?
+          length = tasks.map(&:first).map(&:length).max
+          data   = tasks.map { |task, desc| [task, truncate(desc, 76 - length)] }
+          info << colorize(:cyan, "Tasks\n")
+          info << format_table(data, 2).to_s
+          info << "\n\n"
+        end
+
+        if plans.any?
+          length = plans.map(&:first).map(&:length).max
+          data   = plans.map { |plan, desc| [plan, truncate(desc, 76 - length)] }
+          info << colorize(:cyan, "Plans\n")
+          info << format_table(data, 2).to_s
+          info << "\n\n"
+        end
+
+        if metadata['operatingsystem_support']&.any?
+          supported = metadata['operatingsystem_support'].map do |os|
+            [os['operatingsystem'], os['operatingsystemrelease']&.join(', ')]
+          end
+
+          info << colorize(:cyan, "Operating system support\n")
+          info << format_table(supported, 2).to_s
+          info << "\n\n"
+        end
+
+        if metadata['dependencies']&.any?
+          dependencies = metadata['dependencies'].map do |dep|
+            [dep['name'], dep['version_requirement']]
           end
 
-          @stream.write("\n")
+          info << colorize(:cyan, "Dependencies\n")
+          info << format_table(dependencies, 2).to_s
+          info << "\n\n"
         end
+
+        info << colorize(:cyan, "Path\n")
+        info << if path.start_with?(Bolt::Config::Modulepath::MODULES_PATH) ||
+                   path.start_with?(Bolt::Config::Modulepath::BOLTLIB_PATH)
+                  indent(2, 'built-in module')
+                else
+                  indent(2, path)
+                end
+
+        @stream.puts info
       end
 
       def print_plugin_list(plugin_list, modulepath)
@@ -665,6 +753,12 @@ module Bolt
           print_container_result(value.result)
         when Bolt::ResultSet
           print_result_set(value)
+        when Bolt::Result
+          print_result(value)
+        when Bolt::ApplyResult
+          print_apply_result(value)
+        when Bolt::Error
+          print_bolt_error(**value.to_h.transform_keys(&:to_sym))
         else
           @stream.puts(::JSON.pretty_generate(plan_result, quirks_mode: true))
         end
@@ -704,6 +798,17 @@ module Bolt
         @stream.puts(colorize(:red, message))
       end
 
+      def print_bolt_error(msg:, details:, **_kwargs)
+        err = msg
+        if (f = details[:file])
+          err += "\n  (file: #{f}"
+          err += ", line: #{details[:line]}" if details[:line]
+          err += ", column: #{details[:column]}" if details[:column]
+          err += ")"
+        end
+        @stream.puts(colorize(:red, err))
+      end
+
       def print_prompt(prompt)
         @stream.print(colorize(:cyan, indent(4, prompt)))
       end

data/lib/bolt/outputter/json.rb

@@ -47,6 +47,7 @@ module Bolt
         @stream.puts results.to_json
       end
       alias print_module_list print_table
+      alias print_module_info print_table
 
       def print_task_info(task)
         path = task.files.first['path'].chomp("/tasks/#{task.files.first['name']}")
@@ -98,11 +99,8 @@ module Bolt
         print_table('topics' => topics)
       end
 
-      def print_guide(guide, topic)
-        @stream.puts({
-          'topic' => topic,
-          'guide' => guide
-        }.to_json)
+      def print_guide(**kwargs)
+        @stream.puts(kwargs.to_json)
       end
 
       def print_plan_lookup(value)

data/lib/bolt/outputter/logger.rb

@@ -24,7 +24,7 @@ module Bolt
           log_container_start(event)
         when :container_finish
           log_container_finish(event)
-        when :log
+        when :log, :message, :verbose
           log_message(**event)
         end
       end

data/lib/bolt/pal.rb

@@ -339,7 +339,7 @@ module Bolt
       end
 
       # Write the cache if any entries were updated
-      File.write(@project.task_cache_file, task_cache.to_json) if updated
+      File.write(@project.task_cache_file, task_cache.to_json) if updated && @project
       filter_content ? filter_content(task_list, @project&.tasks) : task_list
     end
 
@@ -435,7 +435,7 @@ module Bolt
         list << [plan_name, data['description']] unless data['private']
       end
 
-      File.write(@project.plan_cache_file, plan_cache.to_json) if updated
+      File.write(@project.plan_cache_file, plan_cache.to_json) if updated && @project
 
       filter_content ? filter_content(plan_list, @project&.plans) : plan_list
     end
@@ -635,6 +635,36 @@ module Bolt
       end
     end
 
+    # Return information about a module.
+    #
+    # @param name [String] The name of the module.
+    # @return [Hash]
+    #
+    def show_module(name)
+      name = name.tr('-', '/')
+
+      data = in_bolt_compiler do |_compiler|
+        mod = Puppet.lookup(:current_environment).module(name.split(%r{[/-]}, 2).last)
+
+        unless mod && (mod.forge_name == name || mod.name == name)
+          raise Bolt::Error.new("Could not find module '#{name}' on the modulepath.", 'bolt/unknown-module')
+        end
+
+        {
+          name:     mod.forge_name || mod.name,
+          metadata: mod.metadata,
+          path:     mod.path,
+          plans:    mod.plans.map(&:name).sort,
+          tasks:    mod.tasks.map(&:name).sort
+        }
+      end
+
+      data[:plans] = list_plans_with_cache.to_h.slice(*data[:plans]).to_a
+      data[:tasks] = list_tasks_with_cache.to_h.slice(*data[:tasks]).to_a
+
+      data
+    end
+
     def generate_types(cache: false)
       require 'puppet/face/generate'
       in_bolt_compiler do
@@ -683,7 +713,10 @@ module Bolt
         # Create a Fiber for the main plan. This will be run along with any
         # other Fibers created during the plan run in the round_robin, with the
         # main plan always taking precedence in being resumed.
-        future = executor.create_future(name: plan_name) do |_scope|
+        #
+        # Every future except for the main plan needs to have a plan id in
+        # order to be tracked for the `wait()` function with no arguments.
+        future = executor.create_future(name: plan_name, plan_id: 1) do |_scope|
           r = compiler.call_function('run_plan', plan_name, params.merge('_bolt_api_call' => true))
           Bolt::PlanResult.from_pcore(r, 'success')
         rescue Bolt::Error => e

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

@@ -13,6 +13,7 @@ module Bolt
           download
           eval
           message
+          verbose
           plan
           resources
           script
@@ -219,3 +220,4 @@ require 'bolt/pal/yaml_plan/step/task'
 require 'bolt/pal/yaml_plan/step/upload'
 require 'bolt/pal/yaml_plan/step/download'
 require 'bolt/pal/yaml_plan/step/message'
+require 'bolt/pal/yaml_plan/step/verbose'

data/lib/bolt/pal/yaml_plan/step/message.rb

@@ -24,14 +24,6 @@ module Bolt
           private def function
             'out::message'
           end
-
-          # Transpiles the step into the plan language
-          #
-          def transpile
-            code = String.new("  ")
-            code << function_call(function, format_args(body))
-            code << "\n"
-          end
         end
       end
     end

data/lib/bolt/pal/yaml_plan/step/verbose.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Bolt
+  class PAL
+    class YamlPlan
+      class Step
+        class Verbose < Step
+          def self.allowed_keys
+            super + Set['verbose']
+          end
+
+          def self.required_keys
+            Set['verbose']
+          end
+
+          # Returns an array of arguments to pass to the step's function call
+          #
+          private def format_args(body)
+            [body['verbose']]
+          end
+
+          # Returns the function corresponding to the step
+          #
+          private def function
+            'out::verbose'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/plan_future.rb

@@ -5,13 +5,28 @@ require 'fiber'
 module Bolt
   class PlanFuture
     attr_reader :fiber, :id
-    attr_accessor :value
+    attr_accessor :value, :plan_stack
 
-    def initialize(fiber, id, name = nil)
-      @fiber = fiber
-      @id    = id
-      @name  = name
-      @value = nil
+    def initialize(fiber, id, plan_id:, name: nil)
+      @fiber   = fiber
+      @id      = id
+      @name    = name
+      @value   = nil
+      # The plan invocation ID when the Future is created may be
+      # different from the plan ID of the Future when we switch to it if a new
+      # plan was run inside the Future, so keep track of the plans that a
+      # Future is executing in as a stack. When one plan finishes, pop it off
+      # since now we're in the calling plan. These IDs are unique to each plan
+      # invocation, not just plan names.
+      @plan_stack = [plan_id]
+    end
+
+    def original_plan
+      @plan_stack.last
+    end
+
+    def current_plan
+      @plan_stack.first
     end
 
     def name

data/lib/bolt/transport/ssh/exec_connection.rb

@@ -47,7 +47,9 @@ module Bolt
           cmd = []
           # BatchMode is SSH's noninteractive option: if key authentication
           # fails it will error out instead of falling back to password prompt
-          cmd += %w[-o BatchMode=yes]
+          batch_mode = @target.transport_config['batch-mode'] ? 'yes' : 'no'
+          cmd += %W[-o BatchMode=#{batch_mode}]
+
           cmd += %W[-o Port=#{@target.port}] if @target.port
 
           if @target.transport_config.key?('host-key-check')

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '3.13.0'
+  VERSION = '3.14.1'
 end

data/lib/bolt_server/schemas/partials/target-ssh.json

@@ -62,6 +62,10 @@
     "interpreters": {
       "type": "object",
       "description": "Map of file extensions to remote executable"
+    },
+    "plugin_hooks": {
+      "type": "object",
+      "description": "Configuration for plugins to use"
     }
   },
   "oneOf": [

data/lib/bolt_server/schemas/partials/target-winrm.json

@@ -56,6 +56,10 @@
     "smb-port": {
       "type": "integer",
       "description": "Port for SMB protocol"
+    },
+    "plugin_hooks": {
+      "type": "object",
+      "description": "Configuration for plugins to use"
     }
   },
   "required": ["hostname", "user", "password"],

data/lib/bolt_server/transport_app.rb

@@ -389,6 +389,63 @@ module BoltServer
       end
     end
 
+    # The provided block takes a module object and returns the list
+    # of directories to search through. This is similar to
+    # Bolt::Applicator.build_plugin_tarball.
+    def build_project_plugins_tarball(versioned_project, &block)
+      start_time = Time.now
+
+      # Fetch the plugin files
+      plugin_files = in_bolt_project(versioned_project) do |context|
+        files = {}
+
+        # Bolt also sets plugin_modulepath to user modulepath so do it here too for
+        # consistency
+        plugin_modulepath = context[:pal].user_modulepath
+        Puppet.lookup(:current_environment).override_with(modulepath: plugin_modulepath).modules.each do |mod|
+          search_dirs = block.call(mod)
+
+          files[mod] ||= []
+          Find.find(*search_dirs).each do |file|
+            files[mod] << file if File.file?(file)
+          end
+        end
+
+        files
+      end
+
+      # Pack the plugin files
+      sio = StringIO.new
+      begin
+        output = Minitar::Output.new(Zlib::GzipWriter.new(sio))
+
+        plugin_files.each do |mod, files|
+          tar_dir = Pathname.new(mod.name)
+          mod_dir = Pathname.new(mod.path)
+
+          files.each do |file|
+            tar_path = tar_dir + Pathname.new(file).relative_path_from(mod_dir)
+            stat = File.stat(file)
+            content = File.binread(file)
+            output.tar.add_file_simple(
+              tar_path.to_s,
+              data: content,
+              size: content.size,
+              mode: stat.mode & 0o777,
+              mtime: stat.mtime
+            )
+          end
+        end
+
+        duration = Time.now - start_time
+        @logger.trace("Packed plugins in #{duration * 1000} ms")
+      ensure
+        output.close
+      end
+
+      Base64.encode64(sio.string)
+    end
+
     get '/' do
       200
     end
@@ -441,7 +498,7 @@ module BoltServer
         'uri' => target_hash['hostname'],
         'config' => {
           'transport' => 'ssh',
-          'ssh' => opts
+          'ssh' => opts.slice(*Bolt::Config::Transport::SSH.options)
         }
       }
 
@@ -479,7 +536,7 @@ module BoltServer
         'uri' => target_hash['hostname'],
         'config' => {
           'transport' => 'winrm',
-          'winrm' => opts
+          'winrm' => opts.slice(*Bolt::Config::Transport::WinRM.options)
         }
       }
 
@@ -699,60 +756,34 @@ module BoltServer
       raise BoltServer::RequestError, "'versioned_project' is a required argument" if params['versioned_project'].nil?
       content_type :json
 
-      # Inspired by Bolt::Applicator.build_plugin_tarball
-      start_time = Time.now
-
-      # Fetch the plugin files
-      plugin_files = in_bolt_project(params['versioned_project']) do |context|
-        files = {}
-
-        # Bolt also sets plugin_modulepath to user modulepath so do it here too for
-        # consistency
-        plugin_modulepath = context[:pal].user_modulepath
-        Puppet.lookup(:current_environment).override_with(modulepath: plugin_modulepath).modules.each do |mod|
-          search_dirs = []
-          search_dirs << mod.plugins if mod.plugins?
-          search_dirs << mod.pluginfacts if mod.pluginfacts?
-
-          files[mod] ||= []
-          Find.find(*search_dirs).each do |file|
-            files[mod] << file if File.file?(file)
-          end
-        end
-
-        files
+      plugins_tarball = build_project_plugins_tarball(params['versioned_project']) do |mod|
+        search_dirs = []
+        search_dirs << mod.plugins if mod.plugins?
+        search_dirs << mod.pluginfacts if mod.pluginfacts?
+        search_dirs
       end
 
-      # Pack the plugin files
-      sio = StringIO.new
-      begin
-        output = Minitar::Output.new(Zlib::GzipWriter.new(sio))
-
-        plugin_files.each do |mod, files|
-          tar_dir = Pathname.new(mod.name)
-          mod_dir = Pathname.new(mod.path)
+      [200, plugins_tarball.to_json]
+    end
 
-          files.each do |file|
-            tar_path = tar_dir + Pathname.new(file).relative_path_from(mod_dir)
-            stat = File.stat(file)
-            content = File.binread(file)
-            output.tar.add_file_simple(
-              tar_path.to_s,
-              data: content,
-              size: content.size,
-              mode: stat.mode & 0o777,
-              mtime: stat.mtime
-            )
-          end
-        end
+    # Returns the base64 encoded tar archive of _all_ plugin code for a project
+    #
+    # @param versioned_project [String] the versioned_project to build the plugin tarball from
+    get '/project_plugin_tarball' do
+      raise BoltServer::RequestError, "'versioned_project' is a required argument" if params['versioned_project'].nil?
+      content_type :json
 
-        duration = Time.now - start_time
-        @logger.trace("Packed plugins in #{duration * 1000} ms")
-      ensure
-        output.close
+      plugins_tarball = build_project_plugins_tarball(params['versioned_project']) do |mod|
+        search_dirs = []
+        search_dirs << mod.plugins if mod.plugins?
+        search_dirs << mod.pluginfacts if mod.pluginfacts?
+        search_dirs << mod.files if mod.files?
+        type_files = "#{mod.path}/types"
+        search_dirs << type_files if File.exist?(type_files)
+        search_dirs
       end
 
-      [200, Base64.encode64(sio.string).to_json]
+      [200, plugins_tarball.to_json]
     end
 
     error 404 do