bolt 3.0.1 → 3.6.0

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

@@ -11,12 +11,24 @@ Puppet::Functions.create_function(:prompt) do
   # @option options [Boolean] sensitive Disable echo back and mark the response as sensitive.
   #   The returned value will be wrapped by the `Sensitive` data type. To access the raw
   #   value, use the `unwrap` function (i.e. `$sensitive_value.unwrap`).
+  # @option options [String] default The default value to return if the user does not provide
+  #   input or if stdin is not a tty.
   # @return The response to the prompt.
   # @example Prompt the user if plan execution should continue
   #   $response = prompt('Continue executing plan? [Y\N]')
   # @example Prompt the user for sensitive information
   #   $password = prompt('Enter your password', 'sensitive' => true)
   #   out::message("Password is: ${password.unwrap}")
+  # @example Prompt the user and provide a default value
+  #   $user = prompt('Enter your login username', 'default' => 'root')
+  # @example Prompt the user for sensitive information, returning a sensitive default if one is not provided
+  #   $token = prompt('Enter token', 'default' => lookup('default_token'), 'sensitive' => true)
+  #   out::message("Token is: ${token.unwrap}")
+  # @example Prompt the user and fail with a custom message if no input was provided
+  #   $response = prompt('Enter your name', 'default' => '')
+  #   if $response.empty {
+  #     fail_plan('Must provide your name')
+  #   }
   dispatch :prompt do
     param 'String', :prompt
     optional_param 'Hash[String[1], Any]', :options
@@ -30,14 +42,20 @@ Puppet::Functions.create_function(:prompt) do
                               action: 'prompt')
     end
 
-    options = options.transform_keys(&:to_sym)
-
+    options  = options.transform_keys(&:to_sym)
     executor = Puppet.lookup(:bolt_executor)
+
     # Send analytics report
     executor.report_function_call(self.class.name)
 
+    # Require default to be a string value
+    if options.key?(:default) && !options[:default].is_a?(String)
+      raise Bolt::ValidationError, "Option 'default' must be a string"
+    end
+
     response = executor.prompt(prompt, options)
 
+    # If sensitive, wrap it
     if options[:sensitive]
       Puppet::Pops::Types::PSensitiveType::Sensitive.new(response)
     else

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/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/apply_result.rb

@@ -54,7 +54,7 @@ module Bolt
       unless missing_keys.empty?
         if result['_output']
           # rubocop:disable Layout/LineLength
-          msg = "Report result contains an '_output' key. Catalog application may have printed extraneous output to stdout: #{result['_output']}"
+          msg = "Report result contains an '_output' key. Catalog application might have printed extraneous output to stdout: #{result['_output']}"
           # rubocop:enable Layout/LineLength
         else
           msg = "Report did not contain all expected keys missing: #{missing_keys.join(', ')}"

data/lib/bolt/bolt_option_parser.rb

@@ -13,7 +13,7 @@ module Bolt
                 run_context: %w[concurrency inventoryfile save-rerun cleanup],
                 global_config_setters: PROJECT_PATHS + %w[modulepath],
                 transports: %w[transport connect-timeout tty native-ssh ssh-command copy-command],
-                display: %w[format color verbose trace],
+                display: %w[format color verbose trace stream],
                 global: %w[help version log-level clear-cache] }.freeze
 
     ACTION_OPTS = OPTIONS.values.flatten.freeze
@@ -454,7 +454,7 @@ module Bolt
       DESCRIPTION
           Convert a YAML plan to a Puppet language plan and print the converted plan to stdout.
 
-          Converting a YAML plan may result in a plan that is syntactically
+          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.
 
@@ -707,7 +707,7 @@ module Bolt
              "Or read a target list from an input file '@<file>' or stdin '-'.",
              'Example: --targets localhost,target_group,ssh://nix.com:23,winrm://windows.puppet.com',
              'URI format is [protocol://]host[:port]',
-             "SSH is the default protocol; may be #{TRANSPORTS.keys.join(', ')}",
+             "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|
@@ -888,6 +888,9 @@ 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 |_|
+        @options[:stream] = true
+      end
       define('--trace', 'Display error stack traces') do |_|
         @options[:trace] = true
       end

data/lib/bolt/cli.rb

@@ -96,6 +96,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 +149,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
@@ -175,6 +227,7 @@ module Bolt
     # Completes the setup process by configuring Bolt and log messages
     def finalize_setup
       Bolt::Logger.configure(config.log, config.color, config.disable_warnings)
+      Bolt::Logger.stream = config.stream
       Bolt::Logger.analytics = analytics
       Bolt::Logger.flush_queue
 
@@ -212,7 +265,7 @@ module Bolt
       target_opts = options.keys.select { |opt| %i[query rerun targets].include?(opt) }
       target_string = "'--targets', '--rerun', or '--query'"
       if target_opts.length > 1
-        raise Bolt::CLIError, "Only one targeting option #{target_string} may be specified"
+        raise Bolt::CLIError, "Only one targeting option #{target_string} can be specified"
       elsif target_opts.empty? && options[:subcommand] != 'plan'
         raise Bolt::CLIError, "Command requires a targeting option: #{target_string}"
       end
@@ -249,11 +302,14 @@ module Bolt
         end
       end
 
-      if %w[task plan].include?(options[:subcommand]) && options[:action] == 'run'
+      if %w[task plan script].include?(options[:subcommand]) && options[:action] == 'run'
         if options[:object].nil?
           raise Bolt::CLIError, "Must specify a #{options[:subcommand]} to run"
         end
-        # This may mean that we parsed a parameter as the object
+      end
+
+      # This may mean that we parsed a parameter as the object
+      if %w[task plan].include?(options[:subcommand]) && options[:action] == 'run'
         unless options[:object] =~ /\A([a-z][a-z0-9_]*)?(::[a-z][a-z0-9_]*)*\Z/
           raise Bolt::CLIError,
                 "Invalid #{options[:subcommand]} '#{options[:object]}'"
@@ -301,13 +357,13 @@ module Bolt
       if options[:noop] &&
          !(options[:subcommand] == 'task' && options[:action] == 'run') && options[:subcommand] != 'apply'
         raise Bolt::CLIError,
-              "Option '--noop' may only be specified when running a task or applying manifest code"
+              "Option '--noop' can only be specified when running a task or applying manifest code"
       end
 
       if options[:env_vars]
         unless %w[command script].include?(options[:subcommand]) && options[:action] == 'run'
           raise Bolt::CLIError,
-                "Option '--env-var' may only be specified when running a command or script"
+                "Option '--env-var' can only be specified when running a command or script"
         end
       end
     end
@@ -354,7 +410,7 @@ module Bolt
       if inventory_source && conflicting_options.any?
         Bolt::Logger.warn(
           "cli_overrides",
-          "CLI arguments #{conflicting_options.to_a} may be overridden by Inventory: #{inventory_source}"
+          "CLI arguments #{conflicting_options.to_a} might be overridden by Inventory: #{inventory_source}"
         )
       end
     end
@@ -432,7 +488,7 @@ module Bolt
         return 0
       end
 
-      message = 'There may be processes left executing on some nodes.'
+      message = 'There might be processes left executing on some nodes.'
 
       if %w[task plan].include?(options[:subcommand]) && options[:task_options] && !options[:params_parsed] && pal
         options[:task_options] = pal.parse_params(options[:subcommand], options[:object], options[:task_options])
@@ -485,7 +541,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
@@ -501,9 +561,8 @@ module Bolt
             when 'command'
               executor.run_command(targets, options[:object], executor_opts)
             when 'script'
-              script = options[:object]
-              validate_file('script', script)
-              executor.run_script(targets, script, options[:leftovers], executor_opts)
+              script_path = find_file(options[:object])
+              executor.run_script(targets, script_path, options[:leftovers], executor_opts)
             when 'task'
               pal.run_task(options[:object],
                            targets,
@@ -576,7 +635,18 @@ module Bolt
 
     def list_targets
       inventoryfile = config.inventoryfile || config.default_inventoryfile
+      outputter.print_targets(group_targets_by_source, inventoryfile)
+    end
+
+    def show_targets
+      inventoryfile = config.inventoryfile || config.default_inventoryfile
+      outputter.print_target_info(group_targets_by_source, inventoryfile)
+    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
@@ -587,17 +657,7 @@ 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
@@ -610,7 +670,7 @@ module Bolt
         if plan_arguments['nodes'] || plan_arguments['targets']
           key = plan_arguments.include?('nodes') ? 'nodes' : 'targets'
           raise Bolt::CLIError,
-                "A plan's '#{key}' parameter may be specified using the --#{key} option, but in that " \
+                "A plan's '#{key}' parameter can be specified using the --#{key} option, but in that " \
                 "case it must not be specified as a separate #{key}=<value> parameter nor included " \
                 "in the JSON data passed in the --params option"
         end
@@ -633,7 +693,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
@@ -669,7 +733,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
@@ -754,15 +822,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
@@ -840,6 +903,28 @@ module Bolt
       Bolt::Util.validate_file(type, path, allow_dir)
     end
 
+    # Returns the path to a file. If the path is an absolute or relative to
+    # a file, and the file exists, returns the path as-is. Otherwise, checks if
+    # the path is a Puppet file path and looks for the file in a module's files
+    # directory.
+    #
+    def find_file(path)
+      unless File.exist?(path) || Pathname.new(path).absolute?
+        modulepath = Bolt::Config::Modulepath.new(config.modulepath)
+        modules    = Bolt::Module.discover(modulepath.full_modulepath, config.project)
+        mod, file = path.split(File::SEPARATOR, 2)
+
+        if modules[mod]
+          @logger.debug("Did not find file at #{File.expand_path(path)}, checking in module '#{mod}'")
+          path = File.join(modules[mod].path, 'files', file)
+        end
+      end
+
+      Bolt::Util.validate_file('script', path)
+
+      path
+    end
+
     def rerun
       @rerun ||= Bolt::Rerun.new(config.rerunfile, config.save_rerun)
     end
@@ -858,7 +943,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
@@ -868,7 +953,7 @@ module Bolt
       # If the bundled content directory is empty, Bolt is likely installed as a gem.
       if ENV['BOLT_GEM'].nil? && incomplete_install?
         msg = <<~MSG.chomp
-          Bolt may be installed as a gem. To use Bolt reliably and with all of its
+          Bolt might be installed as a gem. To use Bolt reliably and with all of its
           dependencies, uninstall the 'bolt' gem and install Bolt as a package:
           https://puppet.com/docs/bolt/latest/bolt_installing.html
 
@@ -899,7 +984,8 @@ module Bolt
     # Gem installs include the aggregate, canary, and puppetdb_fact modules, while
     # package installs include modules listed in the Bolt repo Puppetfile
     def incomplete_install?
-      (Dir.children(Bolt::Config::Modulepath::MODULES_PATH) - %w[aggregate canary puppetdb_fact secure_env_vars]).empty?
+      builtin_module_list = %w[aggregate canary puppetdb_fact secure_env_vars puppet_connect]
+      (Dir.children(Bolt::Config::Modulepath::MODULES_PATH) - builtin_module_list).empty?
     end
 
     # Mimicks the output from Outputter::Human#fatal_error. This should be used to print