bolt 3.11.0 → 3.15.0

data/lib/bolt/outputter/human.rb

@@ -78,6 +78,8 @@ module Bolt
           @disable_depth += 1
         when :message
           print_message(event[:message])
+        when :verbose
+          print_message(event[:message]) if @verbose
         end
 
         if enabled?
@@ -339,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"
 
@@ -398,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"
 
@@ -462,13 +464,23 @@ module Bolt
       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.")
+        info = +"#{colorize(:cyan, 'Topics')}\n"
+        info << indent(2, topics.join("\n"))
+        info << "\n\n#{colorize(:cyan, 'Additional information')}\n"
+        info << indent(2, "Use 'bolt guide <TOPIC>' to view a specific guide.")
+        @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)
@@ -476,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?
@@ -496,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
 
-          @stream.write("\n")
+          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
+
+          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)
@@ -661,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
@@ -700,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

@@ -23,6 +23,8 @@ module Bolt
           print_result(event[:result])
         when :message
           print_message(event[:message])
+        when :verbose
+          print_message(event[:message]) if @verbose
         end
       end
 
@@ -45,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']}")
@@ -96,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,6 +24,8 @@ module Bolt
           log_container_start(event)
         when :container_finish
           log_container_finish(event)
+        when :log, :message, :verbose
+          log_message(**event)
         end
       end
 
@@ -65,6 +67,10 @@ module Bolt
           @logger.info("Finished: run container '#{result.object}' failed.")
         end
       end
+
+      def log_message(level:, message:, **_kwargs)
+        @logger.send(level, message)
+      end
     end
   end
 end

data/lib/bolt/pal.rb

@@ -324,7 +324,7 @@ module Bolt
           data['files'].each do |f|
             # If any file has been updated since we last cached, update the
             # cache
-            next if File.mtime(f['path']).to_s == f['mtime']
+            next unless file_modified?(f['path'], f['mtime'])
             data = get_task_info(task_name, with_mtime: true)
             data = Bolt::Util.walk_keys(data, &:to_s)
             # Tell Bolt to write to the cache file once we're done
@@ -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
 
@@ -423,13 +423,10 @@ module Bolt
 
       plan_list = plan_names.each_with_object([]) do |plan_name, list|
         data = plan_cache[plan_name] || get_plan_info(plan_name, with_mtime: true)
-
-        # If the plan is a 'local' plan (in the project itself, or the
-        # modules/ directory) then verify it hasn't been updated since we
-        # cached it. If it has been updated, refresh the cache and use the
-        # new data.
-        if data['file'] &&
-           File.mtime(data.dig('file', 'path')).to_s != data.dig('file', 'mtime')
+        # If the plan is a 'local' plan (in the project itself, or the modules/
+        # directory) then verify it hasn't been updated since we cached it. If
+        # it has been updated, refresh the cache and use the new data.
+        if file_modified?(data.dig('file', 'path'), data.dig('file', 'mtime'))
           data = get_plan_info(plan_name, with_mtime: true)
           updated = true
           plan_cache[plan_name] = data
@@ -438,11 +435,21 @@ 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
 
+    # Returns true if a file has been modified or no longer exists, false
+    # otherwise.
+    #
+    # @param path [String] The path to the file.
+    # @param mtime [String] The last time the file was modified.
+    #
+    private def file_modified?(path, mtime)
+      path && !(File.exist?(path) && File.mtime(path).to_s == mtime.to_s)
+    end
+
     def list_plans(filter_content: false)
       in_bolt_compiler do |compiler|
         errors = []
@@ -505,19 +512,14 @@ module Bolt
           end
         end
 
-        privie = plan.tag(:private)&.text
-        unless privie.nil? || %w[true false].include?(privie.downcase)
-          msg = "Plan #{plan_name} key 'private' must be a boolean, received: #{privie}"
-          raise Bolt::Error.new(msg, 'bolt/invalid-plan')
-        end
-
         pp_info = {
           'name'        => plan_name,
           'description' => description,
           'parameters'  => parameters,
-          'module'      => mod
+          'module'      => mod,
+          'private'     => private_plan?(plan)
         }
-        pp_info.merge!({ 'private' => privie&.downcase == 'true' }) unless privie.nil?
+
         pp_info.merge!(get_plan_mtime(plan.file)) if with_mtime
         pp_info
 
@@ -547,14 +549,39 @@ module Bolt
           'name'        => plan_name,
           'description' => plan.description,
           'parameters'  => parameters,
-          'module'      => mod
+          'module'      => mod,
+          'private'     => !!plan.private
         }
-        yaml_info.merge!({ 'private' => plan.private }) unless plan.private.nil?
+
         yaml_info.merge!(get_plan_mtime(yaml_path)) if with_mtime
         yaml_info
       end
     end
 
+    # Returns true if the plan is private, false otherwise.
+    #
+    # @param plan [PuppetStrings::Yard::CodeObjects::Plan] The puppet-strings plan documentation.
+    # @return [Boolean]
+    #
+    private def private_plan?(plan)
+      if plan.tag(:private)
+        value     = plan.tag(:private).text
+        api_value = value.downcase == 'true' ? 'private' : 'public'
+
+        Bolt::Logger.deprecate(
+          'plan_private_tag',
+          "Tag '@private #{value}' in plan '#{plan.name}' is deprecated, use '@api #{api_value}' instead"
+        )
+
+        unless %w[true false].include?(plan.tag(:private).text.downcase)
+          msg = "Value for '@private' tag in plan '#{plan.name}' must be a boolean, received: #{value}"
+          raise Bolt::Error.new(msg, 'bolt/invalid-plan')
+        end
+      end
+
+      plan.tag(:api).text == 'private' || plan.tag(:private)&.text&.downcase == 'true'
+    end
+
     def get_plan_mtime(path)
       # If the plan is from the project modules/ directory, or is in the
       # project itself, include the last mtime of the file so we can compare
@@ -628,6 +655,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
@@ -676,7 +733,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