bolt 3.0.0 → 3.5.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/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])
@@ -501,9 +557,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,
@@ -610,7 +665,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
@@ -709,9 +764,11 @@ module Bolt
     def install_project_modules(project, config, force, resolve)
       assert_project_file(project)
 
-      unless project.modules.any?
-        outputter.print_message "Project configuration file #{project.project_file} does not "\
-                                "specify any module dependencies. Nothing to do."
+      if project.modules.empty? && resolve != false
+        outputter.print_message(
+          "Project configuration file #{project.project_file} does not "\
+          "specify any module dependencies. Nothing to do."
+        )
         return 0
       end
 
@@ -838,6 +895,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
@@ -866,7 +945,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
 
@@ -897,7 +976,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

data/lib/bolt/config.rb

@@ -419,6 +419,10 @@ module Bolt
       @data['spinner']
     end
 
+    def stream
+      @data['stream']
+    end
+
     def inventoryfile
       @data['inventoryfile']
     end

data/lib/bolt/config/options.rb

@@ -4,6 +4,7 @@ require 'bolt/config/transport/ssh'
 require 'bolt/config/transport/winrm'
 require 'bolt/config/transport/orch'
 require 'bolt/config/transport/local'
+require 'bolt/config/transport/lxd'
 require 'bolt/config/transport/docker'
 require 'bolt/config/transport/remote'
 
@@ -17,6 +18,7 @@ module Bolt
         'winrm'  => Bolt::Config::Transport::WinRM,
         'pcp'    => Bolt::Config::Transport::Orch,
         'local'  => Bolt::Config::Transport::Local,
+        'lxd'    => Bolt::Config::Transport::LXD,
         'docker' => Bolt::Config::Transport::Docker,
         'remote' => Bolt::Config::Transport::Remote
       }.freeze
@@ -423,7 +425,14 @@ module Bolt
           _example: false,
           _default: true
         },
-
+        "stream" => {
+          description: "Whether to stream output from scripts and commands to the console. "\
+                       "**This option is experimental**.",
+          type: [TrueClass, FalseClass],
+          _plugin: false,
+          _default: false,
+          _example: true
+        },
         "tasks" => {
           description: "A list of task names and glob patterns to filter the project's tasks by. This option is used "\
                        "to limit the visibility of tasks for users of the project. For example, project authors "\
@@ -440,8 +449,8 @@ module Bolt
         },
         "trusted-external-command" => {
           description: "The path to an executable on the Bolt controller that can produce external trusted facts. "\
-                       "**External trusted facts are experimental in both Puppet and Bolt and this API may change or "\
-                       "be removed.**",
+                       "**External trusted facts are experimental in both Puppet and Bolt and this API might "\
+                       "change or be removed.**",
           type: String,
           _plugin: false,
           _example: "/etc/puppetlabs/facts/trusted_external.sh"
@@ -475,6 +484,13 @@ module Bolt
           _plugin: true,
           _example: { "cleanup" => false, "tmpdir" => "/tmp/bolt" }
         },
+        "lxd" => {
+          description: "A map of configuration options for the LXD transport. The LXD transport is "\
+                       "experimental and might include breaking changes between minor versions.",
+          type: Hash,
+          _plugin: true,
+          _example: { cleanup: false }
+        },
         "pcp" => {
           description: "A map of configuration options for the pcp transport.",
           type: Hash,
@@ -530,6 +546,7 @@ module Bolt
         puppetdb
         save-rerun
         spinner
+        stream
       ].freeze
 
       # Options that are available in a bolt-project.yaml file
@@ -553,6 +570,7 @@ module Bolt
         puppetdb
         save-rerun
         spinner
+        stream
         tasks
         trusted-external-command
       ].freeze