bolt 3.1.0 → 3.6.1

data/lib/bolt/inventory/options.rb

@@ -11,8 +11,10 @@ module Bolt
         facts
         features
         groups
+        plugin_hooks
         targets
         vars
+        version
       ].freeze
 
       # Definitions used to validate the data.
@@ -123,6 +125,13 @@ module Bolt
           description: "A map of variables for the group or target.",
           type: Hash,
           _plugin: true
+        },
+        "version" => {
+          description: "The version of the inventory file.",
+          type: Integer,
+          _plugin: false,
+          _example: 2,
+          _default: 2
         }
       }.freeze
     end

data/lib/bolt/inventory/target.rb

@@ -92,6 +92,7 @@ module Bolt
       end
 
       def add_facts(new_facts = {})
+        validate_fact_names(new_facts)
         @facts = Bolt::Util.deep_merge(@facts, new_facts)
       end
 
@@ -153,9 +154,24 @@ module Bolt
           raise Bolt::UnknownTransportError.new(transport, uri)
         end
 
+        validate_fact_names(facts)
+
         transport_config
       end
 
+      # Validate fact names and issue a deprecation warning if any fact names have a dot.
+      #
+      private def validate_fact_names(facts)
+        if (dotted = facts.keys.select { |name| name.include?('.') }).any?
+          Bolt::Logger.deprecate(
+            'dotted_fact_name',
+            "Target '#{safe_name}' includes dotted fact names: '#{dotted.join("', '")}'. Dotted fact "\
+            "names are deprecated and Bolt does not automatically convert facts with dotted names to "\
+            "structured facts. For more information, see https://pup.pt/bolt-dotted-facts"
+          )
+        end
+      end
+
       def host
         @uri_obj.hostname || transport_config['host']
       end

data/lib/bolt/logger.rb

@@ -91,6 +91,14 @@ module Bolt
       Logging.logger[:root].appenders.any?
     end
 
+    def self.stream
+      @stream
+    end
+
+    def self.stream=(stream)
+      @stream = stream
+    end
+
     # A helper to ensure the Logging library is always initialized with our
     # custom log levels before retrieving a Logger instance.
     def self.logger(name)

data/lib/bolt/module_installer.rb

@@ -45,7 +45,7 @@ module Bolt
       # specss. If that fails, fall back to resolving from project specs.
       # This prevents Bolt from modifying installed modules unless there is
       # a version conflict.
-      @outputter.print_action_step("Resolving module dependencies, this may take a moment")
+      @outputter.print_action_step("Resolving module dependencies, this might take a moment")
 
       @outputter.start_spin
       begin
@@ -156,7 +156,7 @@ module Bolt
         # If forcibly installing or if there is no Puppetfile, resolve
         # and write a Puppetfile.
         if force || !path.exist?
-          @outputter.print_action_step("Resolving module dependencies, this may take a moment")
+          @outputter.print_action_step("Resolving module dependencies, this might take a moment")
 
           # This doesn't use the block as it's more testable to just mock *_spin
           @outputter.start_spin

data/lib/bolt/module_installer/puppetfile.rb

@@ -36,7 +36,7 @@ module Bolt
           raise Bolt::ValidationError, <<~MSG
             Unable to parse Puppetfile #{path}:
             #{parsed.validation_errors.join("\n\n")}.
-            This may not be a Puppetfile managed by Bolt.
+            This Puppetfile might not be managed by Bolt.
           MSG
         end
 
@@ -106,7 +106,7 @@ module Bolt
 
           #{unsatisfied_specs.map(&:to_hash).to_yaml.lines.drop(1).join.chomp}
           
-          This may not be a Puppetfile managed by Bolt. To forcibly overwrite the
+          This Puppetfile might not be managed by Bolt. To forcibly overwrite the
           Puppetfile, run '#{command}'.
         MESSAGE
 

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

@@ -39,8 +39,8 @@ module Bolt
           unless (match = name.match(NAME_REGEX))
             raise Bolt::ValidationError,
                   "Invalid name for Forge module specification: #{name}. Name must match "\
-                  "'owner/name'. Owner segment may only include letters or digits. Name "\
-                  "segment must start with a lowercase letter and may only include lowercase "\
+                  "'owner/name'. Owner segment can only include letters or digits. Name "\
+                  "segment must start with a lowercase letter and can only include lowercase "\
                   "letters, digits, and underscores."
           end
 

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

@@ -49,8 +49,8 @@ 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'. Owner segment may only include letters or digits. "\
-                  "Name segment must start with a lowercase letter and may only include "\
+                  "'name' or 'owner/name'. Owner segment can only include letters or digits. "\
+                  "Name segment must start with a lowercase letter and can only include "\
                   "lowercase letters, digits, and underscores."
           end
 

data/lib/bolt/node/output.rb

@@ -6,13 +6,23 @@ require 'bolt/result'
 module Bolt
   class Node
     class Output
-      attr_reader :stdout, :stderr
+      attr_reader :stderr, :stdout, :merged_output
       attr_accessor :exit_code
 
       def initialize
-        @stdout = StringIO.new
-        @stderr = StringIO.new
-        @exit_code = 'unknown'
+        @stdout        = StringIO.new
+        @stderr        = StringIO.new
+        @merged_output = StringIO.new
+        @exit_code     = 'unknown'
+      end
+
+      def to_h
+        {
+          'stdout'        => @stdout.string,
+          'stderr'        => @stderr.string,
+          'merged_output' => @merged_output.string,
+          'exit_code'     => @exit_code
+        }
       end
     end
   end

data/lib/bolt/outputter/human.rb

@@ -6,6 +6,7 @@ module Bolt
   class Outputter
     class Human < Bolt::Outputter
       COLORS = {
+        dim:    "2", # Dim, the other color of the rainbow
         red:    "31",
         green:  "32",
         yellow: "33",
@@ -53,10 +54,21 @@ module Bolt
         string.sub(/\s\z/, '')
       end
 
+      # Wraps a string to the specified width. Lines only wrap
+      # at whitespace.
+      #
       def wrap(string, width = 80)
+        return string unless string.is_a?(String)
         string.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n")
       end
 
+      # Trims a string to a specified width, adding an ellipsis if it's longer.
+      #
+      def truncate(string, width = 80)
+        return string unless string.is_a?(String) && string.length > width
+        string.lines.first[0...width].gsub(/\s\w+\s*$/, '...')
+      end
+
       def handle_event(event)
         case event[:type]
         when :enable_default_output
@@ -81,6 +93,10 @@ module Bolt
             print_plan_start(event)
           when :plan_finish
             print_plan_finish(event)
+          when :container_start
+            print_container_start(event) if plan_logging?
+          when :container_finish
+            print_container_finish(event) if plan_logging?
           when :start_spin
             start_spin
           when :stop_spin
@@ -101,6 +117,34 @@ module Bolt
         @stream.puts(colorize(:green, "Started on #{target.safe_name}..."))
       end
 
+      def print_container_result(result)
+        if result.success?
+          @stream.puts(colorize(:green, "Finished running container #{result.object}:"))
+        else
+          @stream.puts(colorize(:red, "Failed running container #{result.object}:"))
+        end
+
+        if result.error_hash
+          @stream.puts(colorize(:red, remove_trail(indent(2, result.error_hash['msg']))))
+          return 0
+        end
+
+        # Only print results if there's something other than empty string and hash
+        safe_value = result.safe_value
+        if safe_value['stdout'].strip.empty? && safe_value['stderr'].strip.empty?
+          @stream.puts(indent(2, "Running container #{result.object} completed successfully with no result"))
+        else
+          unless safe_value['stdout'].strip && safe_value['stdout'].strip.empty?
+            @stream.puts(indent(2, "STDOUT:"))
+            @stream.puts(indent(4, safe_value['stdout']))
+          end
+          unless safe_value['stderr'].strip.empty?
+            @stream.puts(indent(2, "STDERR:"))
+            @stream.puts(indent(4, safe_value['stderr']))
+          end
+        end
+      end
+
       def print_result(result)
         if result.success?
           @stream.puts(colorize(:green, "Finished on #{result.target.safe_name}:"))
@@ -131,16 +175,9 @@ module Bolt
           end
 
           # Use special handling if the result looks like a command or script result
-          if result.generic_value.keys == %w[stdout stderr exit_code]
+          if result.generic_value.keys == %w[stdout stderr merged_output exit_code]
             safe_value = result.safe_value
-            unless safe_value['stdout'].strip.empty?
-              @stream.puts(indent(2, "STDOUT:"))
-              @stream.puts(indent(4, safe_value['stdout']))
-            end
-            unless safe_value['stderr'].strip.empty?
-              @stream.puts(indent(2, "STDERR:"))
-              @stream.puts(indent(4, safe_value['stderr']))
-            end
+            @stream.puts(indent(2, safe_value['merged_output'])) unless safe_value['merged_output'].strip.empty?
           elsif result.generic_value.any?
             @stream.puts(indent(2, ::JSON.pretty_generate(result.generic_value)))
           end
@@ -176,6 +213,25 @@ module Bolt
         @stream.puts(colorize(:green, message))
       end
 
+      def print_container_start(image:, **_kwargs)
+        @stream.puts(colorize(:green, "Starting: run container '#{image}'"))
+      end
+
+      def print_container_finish(event)
+        result = if event[:result].is_a?(Bolt::ContainerFailure)
+                   event[:result].result
+                 else
+                   event[:result]
+                 end
+
+        if result.success?
+          @stream.puts(colorize(:green, "Finished: run container '#{result.object}' succeeded."))
+        else
+          @stream.puts(colorize(:red, "Finished: run container '#{result.object}' failed."))
+        end
+        print_container_result(result) if @verbose
+      end
+
       def print_plan_start(event)
         @plan_depth += 1
         # We use this event to both mark the start of a plan _and_ to enable
@@ -218,11 +274,11 @@ module Bolt
         @stream.puts total_msg
       end
 
-      def print_table(results, padding_left = 0, padding_right = 3)
+      def format_table(results, padding_left = 0, padding_right = 3)
         # lazy-load expensive gem code
         require 'terminal-table'
 
-        @stream.puts Terminal::Table.new(
+        Terminal::Table.new(
           rows: results,
           style: {
             border_x: '',
@@ -238,94 +294,155 @@ module Bolt
 
       def print_tasks(tasks, modulepath)
         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 '#{command}' to view "\
-                        "details and parameters for a specific task.")
+
+        tasks = tasks.map do |name, description|
+          description = truncate(description, 72)
+          [name, description]
+        end
+
+        @stream.puts colorize(:cyan, 'Tasks')
+        @stream.puts tasks.any? ? format_table(tasks, 2) : indent(2, 'No available tasks')
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Modulepath')
+        @stream.puts indent(2, modulepath.join(File::PATH_SEPARATOR))
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Additional information')
+        @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific task.")
       end
 
       # @param [Hash] task A hash representing the task
       def print_task_info(task)
-        # Building lots of strings...
-        pretty_params = +""
-        task_info = +""
-        usage = if Bolt::Util.powershell?
-                  +"Invoke-BoltTask -Name #{task.name} -Targets <targets>"
+        params = (task.parameters || []).sort
+
+        info = +''
+
+        # Add task name and description
+        info << colorize(:cyan, "#{task.name}\n")
+        info << if task.description
+                  indent(2, task.description.chomp)
                 else
-                  +"bolt task run #{task.name} --targets <targets>"
+                  indent(2, 'No description')
                 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'].start_with?("Optional")
-                     " [#{k}=<value>]"
+        info << "\n\n"
+
+        # Build usage string
+        usage = +''
+        usage << if Bolt::Util.powershell?
+                   "Invoke-BoltTask -Name #{task.name} -Targets <targets>"
+                 else
+                   "bolt task run #{task.name} --targets <targets>"
+                 end
+        usage << (Bolt::Util.powershell? ? ' [-Noop]' : ' [--noop]') if task.supports_noop
+        params.each do |name, data|
+          usage << if data['type']&.start_with?('Optional')
+                     " [#{name}=<value>]"
                    else
-                     " #{k}=<value>"
+                     " #{name}=<value>"
                    end
         end
 
-        if task.supports_noop
-          usage << Bolt::Util.powershell? ? '[-Noop]' : '[--noop]'
+        # Add usage
+        info << colorize(:cyan, "Usage\n")
+        info << indent(2, wrap(usage))
+        info << "\n"
+
+        # Add parameters, if any
+        if params.any?
+          info << colorize(:cyan, "Parameters\n")
+          params.each do |name, data|
+            info << indent(2, "#{colorize(:yellow, name)}  #{colorize(:dim, data['type'] || 'Any')}\n")
+            info << indent(4, "#{wrap(data['description']).chomp}\n") if data['description']
+            info << indent(4, "Default: #{data['default'].inspect}\n") if data.key?('default')
+            info << "\n"
+          end
         end
 
-        task_info << "\n#{task.name}"
-        task_info << " - #{task.description}" if task.description
-        task_info << "\n\n"
-        task_info << "USAGE:\n#{usage}\n\n"
-        task_info << "PARAMETERS:\n#{pretty_params}\n" unless pretty_params.empty?
-        task_info << "MODULE:\n"
-
+        # Add module location
         path = task.files.first['path'].chomp("/tasks/#{task.files.first['name']}")
-        task_info << if path.start_with?(Bolt::Config::Modulepath::MODULES_PATH)
-                       "built-in module"
-                     else
-                       path
-                     end
-        @stream.puts(task_info)
+        info << colorize(:cyan, "Module\n")
+        info << if path.start_with?(Bolt::Config::Modulepath::MODULES_PATH)
+                  indent(2, 'built-in module')
+                else
+                  indent(2, path)
+                end
+
+        @stream.puts info
       end
 
       # @param [Hash] plan A hash representing the plan
       def print_plan_info(plan)
-        # Building lots of strings...
-        pretty_params = +""
-        plan_info = +""
-        usage = if Bolt::Util.powershell?
-                  +"Invoke-BoltPlan -Name #{plan['name']}"
+        params = plan['parameters'].sort
+
+        info = +''
+
+        # Add plan name and description
+        info << colorize(:cyan, "#{plan['name']}\n")
+        info << if plan['description']
+                  indent(2, plan['description'].chomp)
                 else
-                  +"bolt plan run #{plan['name']}"
+                  indent(2, 'No description')
                 end
+        info << "\n\n"
+
+        # Build the usage string
+        usage = +''
+        usage << if Bolt::Util.powershell?
+                   "Invoke-BoltPlan -Name #{plan['name']}"
+                 else
+                   "bolt plan run #{plan['name']}"
+                 end
+        params.each do |name, data|
+          usage << (data.include?('default_value') ? " [#{name}=<value>]" : " #{name}=<value>")
+        end
 
-        plan['parameters'].each do |name, p|
-          pretty_params << "- #{name}: #{p['type']}\n"
-          pretty_params << "    Default: #{p['default_value']}\n" unless p['default_value'].nil?
-          pretty_params << "    #{p['description']}\n" if p['description']
-          usage << (p.include?('default_value') ? " [#{name}=<value>]" : " #{name}=<value>")
+        # Add usage
+        info << colorize(:cyan, "Usage\n")
+        info << indent(2, wrap(usage))
+        info << "\n"
+
+        # Add parameters, if any
+        if params.any?
+          info << colorize(:cyan, "Parameters\n")
+
+          params.each do |name, data|
+            info << indent(2, "#{colorize(:yellow, name)}  #{colorize(:dim, data['type'])}\n")
+            info << indent(4, "#{wrap(data['description']).chomp}\n") if data['description']
+            info << indent(4, "Default: #{data['default_value']}\n") unless data['default_value'].nil?
+            info << "\n"
+          end
         end
 
-        plan_info << "\n#{plan['name']}"
-        plan_info << " - #{plan['description']}" if plan['description']
-        plan_info << "\n\n"
-        plan_info << "USAGE:\n#{usage}\n\n"
-        plan_info << "PARAMETERS:\n#{pretty_params}\n" unless plan['parameters'].empty?
-        plan_info << "MODULE:\n"
+        # Add module location
+        info << colorize(:cyan, "Module\n")
+        info << if plan['module'].start_with?(Bolt::Config::Modulepath::MODULES_PATH)
+                  indent(2, 'built-in module')
+                else
+                  indent(2, plan['module'])
+                end
 
-        path = plan['module']
-        plan_info << if path.start_with?(Bolt::Config::Modulepath::MODULES_PATH)
-                       "built-in module"
-                     else
-                       path
-                     end
-        @stream.puts(plan_info)
+        @stream.puts info
       end
 
       def print_plans(plans, modulepath)
         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 '#{command}' to view "\
-                        "details and parameters for a specific plan.")
+
+        plans = plans.map do |name, description|
+          description = truncate(description, 72)
+          [name, description]
+        end
+
+        @stream.puts colorize(:cyan, 'Plans')
+        @stream.puts plans.any? ? format_table(plans, 2) : indent(2, 'No available plans')
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Modulepath')
+        @stream.puts indent(2, modulepath.join(File::PATH_SEPARATOR))
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Additional information')
+        @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific plan.")
       end
 
       def print_topics(topics)
@@ -359,7 +476,7 @@ module Bolt
               [m[:name], version]
             end
 
-            print_table(module_info, 2, 1)
+            @stream.puts format_table(module_info, 2, 1)
           end
 
           @stream.write("\n")
@@ -373,29 +490,77 @@ module Bolt
         targets += target_list[:inventory].map { |target| [target.name, nil] }
         targets += target_list[:adhoc].map { |target| [target.name, adhoc] }
 
-        if targets.any?
-          print_table(targets, 0, 2)
-          @stream.puts
-        end
+        info = +''
 
-        @stream.puts "INVENTORY FILE:"
-        if File.exist?(inventoryfile)
-          @stream.puts inventoryfile
+        # Add target list
+        info << colorize(:cyan, "Targets\n")
+        info << if targets.any?
+                  format_table(targets, 2, 2).to_s
+                else
+                  indent(2, 'No targets')
+                end
+        info << "\n\n"
+
+        @stream.puts info
+
+        print_inventory_summary(
+          target_list[:inventory].count,
+          target_list[:adhoc].count,
+          inventoryfile
+        )
+      end
+
+      def print_target_info(target_list, inventoryfile)
+        adhoc_targets     = target_list[:adhoc].map(&:name).to_set
+        inventory_targets = target_list[:inventory].map(&:name).to_set
+        targets           = target_list.values.flatten.sort_by(&:name)
+
+        info = +''
+
+        if targets.any?
+          adhoc = colorize(:yellow, " (Not found in inventory file)")
+
+          targets.each do |target|
+            info << colorize(:cyan, target.name)
+            info << adhoc if adhoc_targets.include?(target.name)
+            info << "\n"
+            info << indent(2, target.detail.to_yaml.lines.drop(1).join)
+            info << "\n"
+          end
         else
-          @stream.puts wrap("Tried to load inventory from #{inventoryfile}, but the file does not exist")
+          info << colorize(:cyan, "Targets\n")
+          info << indent(2, "No targets\n\n")
         end
 
-        @stream.puts "\nTARGET COUNT:"
-        @stream.puts "#{targets.count} total, #{target_list[:inventory].count} from inventory, "\
-                     "#{target_list[:adhoc].count} adhoc"
-      end
+        @stream.puts info
 
-      def print_target_info(targets)
-        @stream.puts ::JSON.pretty_generate(
-          targets: targets.map(&:detail)
+        print_inventory_summary(
+          inventory_targets.count,
+          adhoc_targets.count,
+          inventoryfile
         )
-        count = "#{targets.count} target#{'s' unless targets.count == 1}"
-        @stream.puts colorize(:green, count)
+      end
+
+      private def print_inventory_summary(inventory_count, adhoc_count, inventoryfile)
+        info = +''
+
+        # Add inventory file source
+        info << colorize(:cyan, "Inventory file\n")
+        info << if File.exist?(inventoryfile)
+                  indent(2, "#{inventoryfile}\n")
+                else
+                  indent(2, wrap("Tried to load inventory from #{inventoryfile}, but the file does not exist\n"))
+                end
+        info << "\n"
+
+        # Add target count summary
+        count = "#{inventory_count + adhoc_count} total, "\
+                "#{inventory_count} from inventory, "\
+                "#{adhoc_count} adhoc"
+        info << colorize(:cyan, "Target count\n")
+        info << indent(2, count)
+
+        @stream.puts info
       end
 
       def print_groups(groups)
@@ -417,6 +582,10 @@ module Bolt
           @stream.puts("Plan completed successfully with no result")
         when Bolt::ApplyFailure, Bolt::RunFailure
           print_result_set(value.result_set)
+        when Bolt::ContainerResult
+          print_container_result(value)
+        when Bolt::ContainerFailure
+          print_container_result(value.result)
         when Bolt::ResultSet
           print_result_set(value)
         else