bolt 3.3.0 → 3.7.0

data/bolt-modules/prompt/lib/puppet/functions/prompt/menu.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Display a menu prompt and wait for a response. Continues to prompt
+# until an option from the menu is selected.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'prompt::menu') do
+  # Select from a list of options.
+  # @param prompt The prompt to display.
+  # @param menu A list of options to choose from.
+  # @param options A hash of additional options.
+  # @option options [String] default The default option to return if the user does not provide
+  #   input or if standard in (stdin) is not a tty. Must be an option present in the menu.
+  # @return The selected option.
+  # @example Prompt the user to select from a list of options
+  #   $selection = prompt::menu('Select a fruit', ['apple', 'banana', 'carrot'])
+  # @example Prompt the user to select from a list of options with a default value
+  #   $selection = prompt::menu('Select environment', ['development', 'production'], 'default' => 'development')
+  dispatch :prompt_menu_array do
+    param 'String', :prompt
+    param 'Array[Variant[Target, Data]]', :menu
+    optional_param 'Hash[String[1], Variant[Target, Data]]', :options
+    return_type 'Variant[Target, Data]'
+  end
+
+  # Select from a list of options with custom inputs.
+  # @param prompt The prompt to display.
+  # @param menu A hash of options to choose from, where keys are the input used to select a value.
+  # @param options A hash of additional options.
+  # @option options [String] default The default option to return if the user does not provide
+  #   input or if standard in (stdin) is not a tty. Must be an option present in the menu.
+  # @return The selected option.
+  # @example Prompt the user to select from a list of options with custom inputs
+  #   $menu = { 'y' => 'yes', 'n' => 'no' }
+  #   $selection = prompt::menu('Install Puppet?', $menu)
+  dispatch :prompt_menu do
+    param 'String', :prompt
+    param 'Hash[String[1], Variant[Target, Data]]', :menu
+    optional_param 'Hash[String[1], Variant[Target, Data]]', :options
+    return_type 'Variant[TargetSpec, Data]'
+  end
+
+  def prompt_menu_array(prompt, menu, options = {})
+    menu_hash = menu.map.with_index { |value, index| [(index + 1).to_s, value] }.to_h
+    prompt_menu(prompt, menu_hash, options)
+  end
+
+  def prompt_menu(prompt, menu, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'prompt::menu')
+    end
+
+    options  = options.transform_keys(&:to_sym)
+    executor = Puppet.lookup(:bolt_executor)
+
+    # Send analytics report
+    executor.report_function_call(self.class.name)
+
+    # Error if there are no options
+    if menu.empty?
+      raise Bolt::ValidationError, "Menu cannot be empty"
+    end
+
+    # Error if the default value is not on the menu
+    if options.key?(:default) && !menu.value?(options[:default])
+      raise Bolt::ValidationError, "Default value '#{options[:default]}' is not one of the provided menu options"
+    end
+
+    # The first prompt should include the menu
+    to_prompt = format_menu(menu) + prompt
+
+    # Request input from the user until they provide a valid option
+    loop do
+      selection = executor.prompt(to_prompt, options)
+
+      return menu[selection] if menu.key?(selection)
+      return selection       if options.key?(:default) && options[:default] == selection
+
+      # Only reprint the prompt, not the menu
+      to_prompt = "Invalid option, try again. #{prompt}"
+    end
+  end
+
+  # Builds the menu string. Aligns all the values by padding input keys.
+  #
+  private def format_menu(menu)
+    # Find the longest input and add 2 for wrapping parenthesis
+    key_length = menu.keys.max_by(&:length).length + 2
+
+    menu_string = +''
+
+    menu.each do |key, value|
+      key = "(#{key})".ljust(key_length)
+      menu_string << "#{key} #{value}\n"
+    end
+
+    menu_string
+  end
+end

data/guides/targets.txt

@@ -0,0 +1,31 @@
+TOPIC
+    targets
+
+DESCRIPTION
+    A target is a device that Bolt connects to and runs actions on. Targets can
+    be physical, such as servers, or virtual, such as containers or virtual
+    machines.
+
+    Several of Bolt's commands connect to targets and run actions on them. When
+    you run these commands, Bolt requires a list of targets to run the action
+    on. For example, the `bolt script run` command and `Invoke-BoltScript`
+    PowerShell cmdlet require you to provide a list of targets to run your
+    script on. You can provide a list of targets to a command using one of the
+    following command-line options:
+
+    Shell commands
+        -t, --targets TARGETS
+        -q, --query   QUERY
+            --rerun   FILTER
+
+    PowerShell cmdlets
+        -T, -Targets TARGETS
+        -Q, -Query   QUERY
+            -Rerun   FILTER
+
+    Typically, targets and their configuration and data are listed in a
+    project's inventory file. For more information about inventory files,
+    see 'bolt guide inventory'.
+
+DOCUMENTATION
+    https://pup.pt/bolt-commands

data/lib/bolt/analytics.rb

@@ -29,7 +29,7 @@ module Bolt
       yaml_plan_count: :cd13
     }.freeze
 
-    def self.build_client
+    def self.build_client(enabled = true)
       logger = Bolt::Logger.logger(self)
       begin
         config_file = config_path
@@ -38,7 +38,7 @@ module Bolt
         config = { 'disabled' => true }
       end
 
-      if config['disabled'] || ENV['BOLT_DISABLE_ANALYTICS']
+      if !enabled || config['disabled'] || ENV['BOLT_DISABLE_ANALYTICS']
         logger.debug "Analytics opt-out is set, analytics will be disabled"
         NoopClient.new
       else
@@ -80,12 +80,8 @@ module Bolt
         unless ENV['BOLT_DISABLE_ANALYTICS']
           msg = <<~ANALYTICS
             Bolt collects data about how you use it. You can opt out of providing this data.
-
-            To disable analytics data collection, add this line to ~/.puppetlabs/etc/bolt/analytics.yaml :
-              disabled: true
-
-            Read more about what data Bolt collects and why here:
-              https://puppet.com/docs/bolt/latest/bolt_installing.html#analytics-data-collection
+            To learn how to disable data collection, or see what data Bolt collects and why,
+            see http://pup.pt/bolt-analytics
           ANALYTICS
           Bolt::Logger.warn_once('analytics_opt_out', msg)
         end

data/lib/bolt/bolt_option_parser.rb

@@ -190,7 +190,8 @@ module Bolt
           apply
 
       USAGE
-          bolt apply [manifest.pp] [options]
+          bolt apply [manifest] {--targets TARGETS | --query QUERY | --rerun FILTER}
+            [options]
 
       DESCRIPTION
           Apply Puppet manifest code on the specified targets.
@@ -219,7 +220,8 @@ module Bolt
           run
 
       USAGE
-          bolt command run <command> [options]
+          bolt command run <command> {--targets TARGETS | --query QUERY | --rerun FILTER}
+            [options]
 
       DESCRIPTION
           Run a command on the specified targets.
@@ -248,7 +250,8 @@ module Bolt
           download
 
       USAGE
-          bolt file download <src> <dest> [options]
+          bolt file download <source> <destination> {--targets TARGETS | --query QUERY | --rerun FILTER}
+            [options]
 
       DESCRIPTION
           Download a file or directory from one or more targets.
@@ -267,7 +270,8 @@ module Bolt
           upload
 
       USAGE
-          bolt file upload <src> <dest> [options]
+          bolt file upload <source> <destination> {--targets TARGETS | --query QUERY | --rerun FILTER}
+            [options]
 
       DESCRIPTION
           Upload a local file or directory.
@@ -343,7 +347,12 @@ module Bolt
           bolt inventory show [options]
 
       DESCRIPTION
-          Show the list of targets an action would run on.
+          Show the list of targets an action would run on. This command will list
+          all targets in the project's inventory by default.
+
+          To filter the targets in the list, use the --targets, --query, or --rerun
+          options. To view detailed configuration and data for targets, use the
+          --detail option.
     HELP
 
     MODULE_HELP = <<~HELP
@@ -432,7 +441,7 @@ module Bolt
           plan
 
       USAGE
-          bolt plan <action> [parameters] [options]
+          bolt plan <action> [options]
 
       DESCRIPTION
           Convert, create, show, and run Bolt plans.
@@ -449,16 +458,18 @@ module Bolt
           convert
 
       USAGE
-          bolt plan convert <path> [options]
+          bolt plan convert <plan name> [options]
 
       DESCRIPTION
-          Convert a YAML plan to a Puppet language plan and print the converted plan to stdout.
+          Convert a YAML plan to a Puppet language plan and print the converted
+          plan to stdout.
 
           Converting a YAML plan might result in a plan that is syntactically
           correct but has different behavior. Always verify a converted plan's
           functionality. Note that the converted plan is not written to a file.
 
       EXAMPLES
+          bolt plan convert myproject::myplan
           bolt plan convert path/to/plan/myplan.yaml
     HELP
 
@@ -467,7 +478,7 @@ module Bolt
           new
       
       USAGE
-          bolt plan new <plan> [options]
+          bolt plan new <plan name> [options]
       
       DESCRIPTION
           Create a new plan in the current project.
@@ -481,7 +492,7 @@ module Bolt
           run
 
       USAGE
-          bolt plan run <plan> [parameters] [options]
+          bolt plan run <plan name> [parameters] [options]
 
       DESCRIPTION
           Run a plan on the specified targets.
@@ -495,7 +506,7 @@ module Bolt
           show
 
       USAGE
-          bolt plan show [plan] [options]
+          bolt plan show [plan name] [options]
 
       DESCRIPTION
           Show available plans and plan documentation.
@@ -557,7 +568,8 @@ module Bolt
           bolt project migrate [options]
 
       DESCRIPTION
-          Migrate a Bolt project to use current best practices and the latest version of configuration files.
+          Migrate a Bolt project to use current best practices and the latest version of
+          configuration files.
     HELP
 
     SCRIPT_HELP = <<~HELP
@@ -579,7 +591,8 @@ module Bolt
           run
 
       USAGE
-          bolt script run <script> [arguments] [options]
+          bolt script run <script> [arguments] {--targets TARGETS | --query QUERY | --rerun FILTER}
+            [options]
 
       DESCRIPTION
           Run a script on the specified targets.
@@ -661,7 +674,8 @@ module Bolt
           run
 
       USAGE
-          bolt task run <task> [parameters] [options]
+          bolt task run <task name> [parameters] {--targets TARGETS | --query QUERY | --rerun FILTER}
+            [options]
 
       DESCRIPTION
           Run a task on the specified targets.
@@ -677,7 +691,7 @@ module Bolt
           show
 
       USAGE
-          bolt task show [task] [options]
+          bolt task show [task name] [options]
 
       DESCRIPTION
           Show available tasks and task documentation.
@@ -710,7 +724,8 @@ module Bolt
              "SSH is the default protocol; can be #{TRANSPORTS.keys.join(', ')}",
              'For Windows targets, specify the winrm:// protocol if it has not be configured',
              'For SSH, port defaults to `22`',
-             'For WinRM, port defaults to `5985` or `5986` based on the --[no-]ssl setting') do |targets|
+             'For WinRM, port defaults to `5985` or `5986` based on the --[no-]ssl setting',
+             "For more information, see 'bolt guide targets'.") do |targets|
         @options[:targets] ||= []
         @options[:targets] << Bolt::Util.get_arg_input(targets)
       end
@@ -888,7 +903,10 @@ module Bolt
       define('-v', '--[no-]verbose', 'Display verbose logging') do |value|
         @options[:verbose] = value
       end
-      define('--stream', 'Stream output from scripts and commands to the console') do |_|
+      define('--stream',
+             'Stream output from scripts and commands to the console.',
+             'Run with --no-verbose to prevent Bolt from displaying output',
+             'a second time after the action is completed.') do |_|
         @options[:stream] = true
       end
       define('--trace', 'Display error stack traces') do |_|

data/lib/bolt/cli.rb

@@ -47,6 +47,8 @@ module Bolt
       'guide' => %w[]
     }.freeze
 
+    TARGETING_OPTIONS = %i[query rerun targets].freeze
+
     attr_reader :config, :options
 
     def initialize(argv)
@@ -96,6 +98,48 @@ module Bolt
       finalize_setup
     end
 
+    # Prints a welcome message when users first install Bolt and run `bolt`, `bolt help` or `bolt --help`
+    def welcome_message
+      bolt = <<~BOLT
+                   `.::-`
+              `.-:///////-.`
+           `-:////:.  `-:///:-  /ooo.                        .ooo/
+       `.-:///::///:-`   `-//:  ymmm-                        :mmmy  .---.
+      :///:-.   `.:////.  -//:  ymmm-                        :mmmy  +mmm+
+      ://.          ///.  -//:  ymmm--/++/-       `-/++/:`   :mmmy-:smmms::-
+      ://.          ://. .://:  ymmmdmmmmmmdo`  .smmmmmmmmh: :mmmysmmmmmmmms
+      ://.          ://:///:-.  ymmmh/--/hmmmy -mmmd/-.:hmmm+:mmmy.-smmms--.
+      ://:.`      .-////:-`     ymmm-     ymmm:hmmm-    `dmmm/mmmy  +mmm+
+      `-:///:-..:///:-.`        ymmm-     ommm/dmmm`     hmmm+mmmy  +mmm+
+         `.-:////:-`            ymmm+    /mmmm.ommms`   /mmmh:mmmy  +mmmo
+             `-.`               ymmmmmhhmmmmd:  ommmmhydmmmy`:mmmy  -mmmmdhd
+                                oyyy+shddhs/`    .+shddhy+-  -yyyo   .ohddhs
+
+
+      BOLT
+      example_cmd = if Bolt::Util.windows?
+                      "Invoke-BoltCommand -Command 'hostname' -Targets localhost"
+                    else
+                      "bolt command run 'hostname' --target localhost"
+                    end
+      prev_cmd = String.new("bolt")
+      prev_cmd << " #{@argv[0]}" unless @argv.empty?
+
+      message = <<~MSG
+      🎉 Welcome to Bolt #{VERSION}
+      😌 We're here to help bring order to the chaos
+      📖 Find our documentation at https://bolt.guide
+      🙋 Ask a question in #bolt on https://slack.puppet.com/
+      🔩 Contribute at https://github.com/puppetlabs/bolt/
+      💡 Not sure where to start? Try "#{example_cmd}"
+
+      We only print this message once. Run "#{prev_cmd}" again for help text.
+      MSG
+
+      $stdout.print "\033[36m#{bolt}\033[0m"
+      $stdout.print message
+    end
+
     # Parses the command and validates options. All errors that are raised here
     # are not handled by the outputter, as it relies on config being loaded.
     def parse_command
@@ -107,6 +151,16 @@ module Bolt
         # help text
         options[:subcommand] = nil unless COMMANDS.include?(options[:subcommand])
 
+        if Bolt::Util.first_run?
+          FileUtils.mkdir_p(Bolt::Util.first_runs_free.dirname)
+          FileUtils.touch(Bolt::Util.first_runs_free)
+
+          if options[:subcommand].nil? && $stdout.isatty
+            welcome_message
+            raise Bolt::CLIExit
+          end
+        end
+
         # Update the parser for the subcommand (or lack thereof)
         parser.update
         puts parser.help
@@ -210,7 +264,7 @@ module Bolt
     end
 
     def update_targets(options)
-      target_opts = options.keys.select { |opt| %i[query rerun targets].include?(opt) }
+      target_opts = options.keys.select { |opt| TARGETING_OPTIONS.include?(opt) }
       target_string = "'--targets', '--rerun', or '--query'"
       if target_opts.length > 1
         raise Bolt::CLIError, "Only one targeting option #{target_string} can be specified"
@@ -489,7 +543,11 @@ module Bolt
         end
         code = apply_manifest(options[:code], options[:targets], options[:object], options[:noop])
       else
-        executor = Bolt::Executor.new(config.concurrency, analytics, options[:noop], config.modified_concurrency)
+        executor = Bolt::Executor.new(config.concurrency,
+                                      analytics,
+                                      options[:noop],
+                                      config.modified_concurrency,
+                                      config.future)
         targets = options[:targets]
 
         results = nil
@@ -578,8 +636,39 @@ module Bolt
     end
 
     def list_targets
-      inventoryfile = config.inventoryfile || config.default_inventoryfile
+      if options.keys.any? { |key| TARGETING_OPTIONS.include?(key) }
+        target_flag = true
+      else
+        options[:targets] = 'all'
+      end
+
+      outputter.print_targets(
+        group_targets_by_source,
+        inventory.source,
+        config.default_inventoryfile,
+        target_flag
+      )
+    end
 
+    def show_targets
+      if options.keys.any? { |key| TARGETING_OPTIONS.include?(key) }
+        target_flag = true
+      else
+        options[:targets] = 'all'
+      end
+
+      outputter.print_target_info(
+        group_targets_by_source,
+        inventory.source,
+        config.default_inventoryfile,
+        target_flag
+      )
+    end
+
+    # Returns a hash of targets sorted by those that are found in the
+    # inventory and those that are provided on the command line.
+    #
+    private def group_targets_by_source
       # Retrieve the known group and target names. This needs to be done before
       # updating targets, as that will add adhoc targets to the inventory.
       known_names = inventory.target_names
@@ -590,22 +679,11 @@ module Bolt
         known_names.include?(target.name)
       end
 
-      target_list = {
-        inventory: inventory_targets,
-        adhoc:     adhoc_targets
-      }
-
-      outputter.print_targets(target_list, inventoryfile)
-    end
-
-    def show_targets
-      update_targets(options)
-      outputter.print_target_info(options[:targets])
+      { inventory: inventory_targets, adhoc: adhoc_targets }
     end
 
     def list_groups
-      groups = inventory.group_names
-      outputter.print_groups(groups)
+      outputter.print_groups(inventory.group_names.sort, inventory.source, config.default_inventoryfile)
     end
 
     def run_plan(plan_name, plan_arguments, nodes, options)
@@ -636,7 +714,11 @@ module Bolt
       plan_context = { plan_name: plan_name,
                        params: plan_arguments }
 
-      executor = Bolt::Executor.new(config.concurrency, analytics, options[:noop], config.modified_concurrency)
+      executor = Bolt::Executor.new(config.concurrency,
+                                    analytics,
+                                    options[:noop],
+                                    config.modified_concurrency,
+                                    config.future)
       if %w[human rainbow].include?(options.fetch(:format, 'human'))
         executor.subscribe(outputter)
       else
@@ -672,7 +754,11 @@ module Bolt
         Bolt::Logger.warn("empty_manifest", message)
       end
 
-      executor = Bolt::Executor.new(config.concurrency, analytics, noop, config.modified_concurrency)
+      executor = Bolt::Executor.new(config.concurrency,
+                                    analytics,
+                                    noop,
+                                    config.modified_concurrency,
+                                    config.future)
       executor.subscribe(outputter) if options.fetch(:format, 'human') == 'human'
       executor.subscribe(log_outputter)
       # apply logging looks like plan logging, so tell the outputter we're in a
@@ -757,15 +843,10 @@ module Bolt
     #
     def assert_project_file(project)
       unless project.project_file?
-        msg = if project.config_file.exist?
-                command = Bolt::Util.powershell? ? 'Update-BoltProject' : 'bolt project migrate'
-                "Detected Bolt configuration file #{project.config_file}, unable to install "\
-                "modules. To update to a project configuration file, run '#{command}'."
-              else
-                command = Bolt::Util.powershell? ? 'New-BoltProject' : 'bolt project init'
-                "Could not find project configuration file #{project.project_file}, unable "\
-                "to install modules. To create a Bolt project, run '#{command}'."
-              end
+        command = Bolt::Util.powershell? ? 'New-BoltProject' : 'bolt project init'
+
+        msg = "Could not find project configuration file #{project.project_file}, unable "\
+              "to install modules. To create a Bolt project, run '#{command}'."
 
         raise Bolt::Error.new(msg, 'bolt/missing-project-config-error')
       end
@@ -883,7 +964,7 @@ module Bolt
 
     def analytics
       @analytics ||= begin
-        client = Bolt::Analytics.build_client
+        client = Bolt::Analytics.build_client(config.analytics)
         client.bundled_content = bundled_content
         client
       end