bolt 2.32.0 → 2.36.0

data/lib/bolt/apply_result.rb

@@ -96,9 +96,9 @@ module Bolt
       @target = target
       @value = {}
       @action = 'apply'
-      value['report'] = report if report
-      value['_error'] = error if error
-      value['_output'] = metrics_message if metrics_message
+      @value['report'] = report if report
+      @value['_error'] = error if error
+      @value['_output'] = metrics_message if metrics_message
     end
 
     def event_metrics

data/lib/bolt/bolt_option_parser.rb

@@ -6,11 +6,12 @@ require 'optparse'
 
 module Bolt
   class BoltOptionParser < OptionParser
+    PROJECT_PATHS = %w[project configfile boltdir].freeze
     OPTIONS = { inventory: %w[targets query rerun description],
                 authentication: %w[user password password-prompt private-key host-key-check ssl ssl-verify],
                 escalation: %w[run-as sudo-password sudo-password-prompt sudo-executable],
                 run_context: %w[concurrency inventoryfile save-rerun cleanup],
-                global_config_setters: %w[modulepath project configfile],
+                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],
                 global: %w[help version debug log-level] }.freeze
@@ -46,7 +47,8 @@ module Bolt
       when 'inventory'
         case action
         when 'show'
-          { flags: OPTIONS[:inventory] + OPTIONS[:global] + %w[format inventoryfile boltdir configfile detail],
+          { flags: OPTIONS[:inventory] + OPTIONS[:global] +
+            PROJECT_PATHS + %w[format inventoryfile detail],
             banner: INVENTORY_SHOW_HELP }
         else
           { flags: OPTIONS[:global],
@@ -55,7 +57,7 @@ module Bolt
       when 'group'
         case action
         when 'show'
-          { flags: OPTIONS[:global] + %w[format inventoryfile boltdir configfile],
+          { flags: OPTIONS[:global] + PROJECT_PATHS + %w[format inventoryfile],
             banner: GROUP_SHOW_HELP }
         else
           { flags: OPTIONS[:global],
@@ -67,13 +69,13 @@ module Bolt
       when 'module'
         case action
         when 'add'
-          { flags: OPTIONS[:global] + %w[configfile project],
+          { flags: OPTIONS[:global] + PROJECT_PATHS,
             banner: MODULE_ADD_HELP }
         when 'generate-types'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
             banner: MODULE_GENERATETYPES_HELP }
         when 'install'
-          { flags: OPTIONS[:global] + %w[configfile force project resolve],
+          { flags: OPTIONS[:global] + PROJECT_PATHS + %w[force resolve],
             banner: MODULE_INSTALL_HELP }
         when 'show'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
@@ -88,7 +90,7 @@ module Bolt
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
             banner: PLAN_CONVERT_HELP }
         when 'new'
-          { flags: OPTIONS[:global] + %w[configfile project],
+          { flags: OPTIONS[:global] + PROJECT_PATHS + %w[pp],
             banner: PLAN_NEW_HELP }
         when 'run'
           { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir hiera-config],
@@ -106,7 +108,7 @@ module Bolt
           { flags: OPTIONS[:global] + %w[modules],
             banner: PROJECT_INIT_HELP }
         when 'migrate'
-          { flags: OPTIONS[:global] + %w[inventoryfile project configfile],
+          { flags: OPTIONS[:global] + PROJECT_PATHS + %w[inventoryfile],
             banner: PROJECT_MIGRATE_HELP }
         else
           { flags: OPTIONS[:global],
@@ -793,7 +795,10 @@ module Bolt
         @options[:noop] = true
       end
       define('--description DESCRIPTION',
-             'Description to use for the job') do |description|
+             'Deprecated. Description to use for the job') do |description|
+        msg = "Command line option '--description' is deprecated, and will be "\
+          "removed in Bolt 3.0."
+        @deprecations << { type: 'Using --description', msg: msg }
         @options[:description] = description
       end
       define('--params PARAMETERS',
@@ -873,13 +878,25 @@ module Bolt
           File.expand_path(moduledir)
         end
       end
-      define('--project PATH', '--boltdir PATH',
-             'Specify what project to load config from (default: autodiscovered from current working dir)') do |path|
+      define('--boltdir PATH',
+             'Deprecated. Specify what project to load config from (default:',
+             'autodiscovered from current working dir)') do |path|
+        msg = "Command line option '--boltdir' is deprecated, use '--project' instead."
+        @deprecations << { type: 'Using --boltdir', msg: msg }
         @options[:boltdir] = path
       end
+      define('--project PATH',
+             'Path to load the Bolt project from (default: autodiscovered from current dir)') do |path|
+        @options[:project] = path
+      end
       define('--configfile PATH',
-             'Specify where to load config from (default: ~/.puppetlabs/bolt/bolt.yaml).',
-             'Directory containing bolt.yaml will be used as the project directory.') do |path|
+             'Deprecated. Specify where to load config from (default:',
+             '~/.puppetlabs/bolt/bolt.yaml). Directory containing bolt.yaml will be',
+             'used as the project directory.') do |path|
+        msg = "Command line option '--configfile' is deprecated, and " \
+          "will be removed in Bolt 3.0. Use '--project' and provide the "\
+          "directory path instead."
+        @deprecations << { type: 'Using --configfile', msg: msg }
         @options[:configfile] = path
       end
       define('--hiera-config PATH',
@@ -891,12 +908,18 @@ module Bolt
         if ENV.include?(Bolt::Inventory::ENVIRONMENT_VAR)
           raise Bolt::CLIError, "Cannot pass inventory file when #{Bolt::Inventory::ENVIRONMENT_VAR} is set"
         end
-        @options[:inventoryfile] = Pathname.new(File.expand_path(path))
+        @options[:inventoryfile] = File.expand_path(path)
       end
       define('--puppetfile PATH',
-             'Specify a Puppetfile to use when installing modules. (default: ~/.puppetlabs/bolt/Puppetfile)',
+             'Deprecated. Specify a Puppetfile to use when installing modules.',
+             ' (default: ~/.puppetlabs/bolt/Puppetfile)',
              'Modules are installed in the current project.') do |path|
-        @options[:puppetfile_path] = Pathname.new(File.expand_path(path))
+        command = Bolt::Util.powershell? ? 'Update-BoltProject' : 'bolt project migrate'
+        msg = "Command line option '--puppetfile' is deprecated, and will be removed "\
+          "in Bolt 3.0. You can migrate to using the new module management "\
+          "workflow using '#{command}'."
+        @deprecations << { type: 'Using --puppetfile', msg: msg }
+        @options[:puppetfile_path] = File.expand_path(path)
       end
       define('--[no-]save-rerun', 'Whether to update the rerun file after this command.') do |save|
         @options[:'save-rerun'] = save
@@ -945,6 +968,11 @@ module Bolt
         @options[:resolve] = resolve
       end
 
+      separator "\nPLAN OPTIONS"
+      define('--pp', 'Create a new Puppet language plan.') do |pp|
+        @options[:puppet] = pp
+      end
+
       separator "\nDISPLAY OPTIONS"
       define('--filter FILTER', 'Filter tasks and plans by a matching substring') do |filter|
         unless /^[a-z0-9_:]+$/.match(filter)

data/lib/bolt/cli.rb

@@ -15,20 +15,22 @@ require 'bolt/config'
 require 'bolt/error'
 require 'bolt/executor'
 require 'bolt/inventory'
-require 'bolt/rerun'
 require 'bolt/logger'
+require 'bolt/module_installer'
 require 'bolt/outputter'
-require 'bolt/puppetdb'
-require 'bolt/plugin'
-require 'bolt/project_migrator'
 require 'bolt/pal'
+require 'bolt/plan_creator'
+require 'bolt/plugin'
+require 'bolt/project_manager'
+require 'bolt/puppetdb'
+require 'bolt/rerun'
+require 'bolt/secret'
 require 'bolt/target'
 require 'bolt/version'
-require 'bolt/secret'
-require 'bolt/module_installer'
 
 module Bolt
   class CLIExit < StandardError; end
+
   class CLI
     COMMANDS = {
       'command'    => %w[run],
@@ -163,8 +165,9 @@ module Bolt
                 elsif options[:configfile]
                   Bolt::Config.from_file(options[:configfile], options)
                 else
-                  project = if options[:boltdir]
-                              dir = Pathname.new(options[:boltdir])
+                  cli_flag = options[:project] || options[:boltdir]
+                  project = if cli_flag
+                              dir = Pathname.new(cli_flag)
                               if (dir + Bolt::Project::BOLTDIR_NAME).directory?
                                 Bolt::Project.create_project(dir + Bolt::Project::BOLTDIR_NAME)
                               else
@@ -196,10 +199,6 @@ module Bolt
 
       warn_inventory_overrides_cli(options)
 
-      # Assert whether the puppetfile/module commands are available depending
-      # on whether 'modules' is configured.
-      assert_puppetfile_or_module_command(config.project.modules)
-
       options
     rescue Bolt::Error => e
       outputter.fatal_error(e)
@@ -228,9 +227,9 @@ module Bolt
 
     def validate(options)
       unless COMMANDS.include?(options[:subcommand])
+        command = Bolt::Util.powershell? ? 'Get-Command -Module PuppetBolt' : 'bolt help'
         raise Bolt::CLIError,
-              "Expected subcommand '#{options[:subcommand]}' to be one of " \
-              "#{COMMANDS.keys.join(', ')}"
+              "'#{options[:subcommand]}' is not a Bolt command. See '#{command}'."
       end
 
       actions = COMMANDS[options[:subcommand]]
@@ -285,8 +284,9 @@ module Bolt
       end
 
       if options[:subcommand] == 'module' && options[:action] == 'install' && options[:object]
+        command = Bolt::Util.powershell? ? 'Add-BoltModule -Module' : 'bolt module add'
         raise Bolt::CLIError, "Invalid argument '#{options[:object]}'. To add a new module to "\
-                              "the project, run 'bolt module add #{options[:object]}'."
+                              "the project, run '#{command} #{options[:object]}'."
       end
 
       if options[:subcommand] != 'file' && options[:subcommand] != 'script' &&
@@ -295,7 +295,7 @@ module Bolt
               "Unknown argument(s) #{options[:leftovers].join(', ')}"
       end
 
-      if options[:boltdir] && options[:configfile]
+      if options.slice(:boltdir, :configfile, :project).length > 1
         raise Bolt::CLIError, "Only one of '--boltdir', '--project', or '--configfile' may be specified"
       end
 
@@ -342,15 +342,10 @@ module Bolt
     def warn_inventory_overrides_cli(opts)
       inventory_source = if ENV[Bolt::Inventory::ENVIRONMENT_VAR]
                            Bolt::Inventory::ENVIRONMENT_VAR
-                         elsif config.inventoryfile && Bolt::Util.file_stat(config.inventoryfile)
+                         elsif config.inventoryfile
                            config.inventoryfile
-                         else
-                           begin
-                             Bolt::Util.file_stat(config.default_inventoryfile)
-                             config.default_inventoryfile
-                           rescue Errno::ENOENT
-                             nil
-                           end
+                         elsif File.exist?(config.default_inventoryfile)
+                           config.default_inventoryfile
                          end
 
       inventory_cli_opts = %i[authentication escalation transports].each_with_object([]) do |key, acc|
@@ -394,7 +389,7 @@ module Bolt
         output_format: config.format,
         # For continuity
         boltdir_type: config.project.type
-      }
+      }.merge!(analytics.plan_counts(config.project.plans_path))
 
       # Only include target and inventory info for commands that take a targets
       # list. This avoids loading inventory for commands that don't need it.
@@ -458,14 +453,22 @@ module Bolt
       when 'project'
         case options[:action]
         when 'init'
-          code = initialize_project
+          code = Bolt::ProjectManager.new(config, outputter, pal)
+                                     .create(Dir.pwd, options[:object], options[:modules])
         when 'migrate'
-          code = Bolt::ProjectMigrator.new(config, outputter).migrate
+          code = Bolt::ProjectManager.new(config, outputter, pal).migrate
         end
       when 'plan'
         case options[:action]
         when 'new'
-          code = new_plan(options[:object])
+          plan_name = options[:object]
+
+          # If this passes validation, it will return the path to the plan to create
+          Bolt::PlanCreator.validate_input(config.project, plan_name)
+          code = Bolt::PlanCreator.create_plan(config.project.plans_path,
+                                               plan_name,
+                                               outputter,
+                                               options[:puppet])
         when 'run'
           code = run_plan(options[:object], options[:task_options], options[:target_args], options)
         end
@@ -568,10 +571,15 @@ module Bolt
       outputter.print_task_info(pal.get_task(task_name))
     end
 
+    # Filters a list of content by matching substring.
+    #
+    private def filter_content(content, filter)
+      return content unless content && filter
+      content.select { |name,| name.include?(filter) }
+    end
+
     def list_tasks
-      tasks = pal.list_tasks
-      tasks.select! { |task| task.first.include?(options[:filter]) } if options[:filter]
-      tasks.select! { |task| config.project.tasks.include?(task.first) } unless config.project.tasks.nil?
+      tasks = filter_content(pal.list_tasks(filter_content: true), options[:filter])
       outputter.print_tasks(tasks, pal.user_modulepath)
     end
 
@@ -580,9 +588,7 @@ module Bolt
     end
 
     def list_plans
-      plans = pal.list_plans
-      plans.select! { |plan| plan.first.include?(options[:filter]) } if options[:filter]
-      plans.select! { |plan| config.project.plans.include?(plan.first) } unless config.project.plans.nil?
+      plans = filter_content(pal.list_plans(filter_content: true), options[:filter])
       outputter.print_plans(plans, pal.user_modulepath)
     end
 
@@ -617,118 +623,6 @@ module Bolt
       outputter.print_groups(groups)
     end
 
-    def new_plan(plan_name)
-      @logger.warn("Command 'bolt plan new' is experimental and subject to changes.")
-
-      if config.project.name.nil?
-        raise Bolt::Error.new(
-          "Project directory '#{config.project.path}' is not a named project. Unable to create "\
-          "a project-level plan. To name a project, set the 'name' key in the 'bolt-project.yaml' "\
-          "configuration file.",
-          "bolt/unnamed-project-error"
-        )
-      end
-
-      if plan_name !~ Bolt::Module::CONTENT_NAME_REGEX
-        message = <<~MESSAGE.chomp
-          Invalid plan name '#{plan_name}'. Plan names are composed of one or more name segments
-          separated by double colons '::'.
-
-          Each name segment must begin with a lowercase letter, and may only include lowercase
-          letters, digits, and underscores.
-
-          Examples of valid plan names:
-              - #{config.project.name}
-              - #{config.project.name}::my_plan
-        MESSAGE
-
-        raise Bolt::ValidationError, message
-      end
-
-      prefix, *name_segments, basename = plan_name.split('::')
-
-      # If the plan name is just the project name, then create an 'init' plan.
-      # Otherwise, use the last name segment for the plan's filename.
-      basename ||= 'init'
-
-      unless prefix == config.project.name
-        message = "First segment of plan name '#{plan_name}' must match project name '#{config.project.name}'. "\
-                  "Did you mean '#{config.project.name}::#{plan_name}'?"
-
-        raise Bolt::ValidationError, message
-      end
-
-      dir_path = config.project.plans_path.join(*name_segments)
-
-      %w[pp yaml].each do |ext|
-        next unless (path = config.project.plans_path + "#{basename}.#{ext}").exist?
-        raise Bolt::Error.new(
-          "A plan with the name '#{plan_name}' already exists at '#{path}', nothing to do.",
-          'bolt/existing-plan-error'
-        )
-      end
-
-      begin
-        FileUtils.mkdir_p(dir_path)
-      rescue Errno::EEXIST => e
-        raise Bolt::Error.new(
-          "#{e.message}; unable to create plan directory '#{dir_path}'",
-          'bolt/existing-file-error'
-        )
-      end
-
-      plan_path = dir_path + "#{basename}.yaml"
-
-      plan_template = <<~PLAN
-        # This is the structure of a simple plan. To learn more about writing
-        # YAML plans, see the documentation: http://pup.pt/bolt-yaml-plans
-
-        # The description sets the description of the plan that will appear
-        # in 'bolt plan show' output.
-        description: A plan created with bolt plan new
-
-        # The parameters key defines the parameters that can be passed to
-        # the plan.
-        parameters:
-          targets:
-            type: TargetSpec
-            description: A list of targets to run actions on
-            default: localhost
-
-        # The steps key defines the actions the plan will take in order.
-        steps:
-          - message: Hello from #{plan_name}
-          - name: command_step
-            command: whoami
-            targets: $targets
-
-        # The return key sets the return value of the plan.
-        return: $command_step
-      PLAN
-
-      begin
-        File.write(plan_path, plan_template)
-      rescue Errno::EACCES => e
-        raise Bolt::FileError.new(
-          "#{e.message}; unable to create plan",
-          plan_path
-        )
-      end
-
-      output = <<~OUTPUT
-        Created plan '#{plan_name}' at '#{plan_path}'
-
-        Show this plan with:
-            bolt plan show #{plan_name}
-        Run this plan with:
-            bolt plan run #{plan_name}
-      OUTPUT
-
-      outputter.print_message(output)
-
-      0
-    end
-
     def run_plan(plan_name, plan_arguments, nodes, options)
       unless nodes.empty?
         if plan_arguments['nodes'] || plan_arguments['targets']
@@ -820,88 +714,22 @@ module Bolt
     end
 
     def list_modules
+      assert_puppetfile_or_module_command(config.project.modules)
       outputter.print_module_list(pal.list_modules)
     end
 
     def generate_types
+      assert_puppetfile_or_module_command(config.project.modules)
       # generate_types will surface a nice error with helpful message if it fails
       pal.generate_types
       0
     end
 
-    # Initializes a specified directory as a Bolt project and installs any modules
-    # specified by the user, along with their dependencies
-    def initialize_project
-      # Dir.pwd will return backslashes on Windows, but Pathname always uses
-      # forward slashes to concatenate paths. This results in paths like
-      # C:\User\Administrator/modules, which fail module install. This ensure
-      # forward slashes in the cwd path.
-      dir = File.expand_path(Dir.pwd)
-      name = options[:object] || File.basename(dir)
-      if name !~ Bolt::Module::MODULE_NAME_REGEX
-        if options[:object]
-          raise Bolt::ValidationError, "The provided project name '#{name}' is invalid; "\
-            "project name must begin with a lowercase letter and can include lowercase "\
-            "letters, numbers, and underscores."
-        else
-          raise Bolt::ValidationError, "The current directory name '#{name}' is an invalid "\
-            "project name. Please specify a name using 'bolt project init <name>'."
-        end
-      end
-
-      project    = Pathname.new(dir)
-      old_config = project + 'bolt.yaml'
-      config     = project + 'bolt-project.yaml'
-      puppetfile = project + 'Puppetfile'
-      moduledir  = project + 'modules'
-
-      # Warn the user if the project directory already exists. We don't error
-      # here since users might not have installed any modules yet. If both
-      # bolt.yaml and bolt-project.yaml exist, this will just warn about
-      # bolt-project.yaml and subsequent Bolt actions will warn about both files
-      # existing.
-      if config.exist?
-        @logger.warn "Found existing project directory at #{project}. Skipping file creation."
-      elsif old_config.exist?
-        @logger.warn "Found existing #{old_config.basename} at #{project}. "\
-                    "#{old_config.basename} is deprecated, please rename to #{config.basename}."
-      end
-
-      # If modules were specified, first check if there is already a Puppetfile
-      # at the project directory, erroring if there is. If there is no
-      # Puppetfile, install the specified modules. The module installer will
-      # resolve dependencies, generate a Puppetfile, and install the modules.
-      if options[:modules]
-        if puppetfile.exist?
-          raise Bolt::CLIError,
-                "Found existing Puppetfile at #{puppetfile}, unable to initialize "\
-                "project with modules."
-        end
-
-        installer = Bolt::ModuleInstaller.new(outputter, pal)
-        installer.install(options[:modules], puppetfile, moduledir)
-      end
-
-      # If either bolt.yaml or bolt-project.yaml exist, the user has already
-      # been warned and we can just finish project creation. Otherwise, create a
-      # bolt-project.yaml with the project name in it.
-      unless config.exist? || old_config.exist?
-        begin
-          content = { 'name' => name }
-          File.write(config.to_path, content.to_yaml)
-          outputter.print_message "Successfully created Bolt project at #{project}"
-        rescue StandardError => e
-          raise Bolt::FileError.new("Could not create bolt-project.yaml at #{project}: #{e.message}", nil)
-        end
-      end
-
-      0
-    end
-
     # Installs modules declared in the project configuration file.
     #
     def install_project_modules(project, force, resolve)
       assert_project_file(project)
+      assert_puppetfile_or_module_command(project.modules)
 
       unless project.modules
         outputter.print_message "Project configuration file #{project.project_file} does not "\
@@ -923,6 +751,7 @@ module Bolt
     #
     def add_project_module(name, project)
       assert_project_file(project)
+      assert_puppetfile_or_module_command(project.modules)
 
       modules   = project.modules || []
       installer = Bolt::ModuleInstaller.new(outputter, pal)
@@ -940,11 +769,13 @@ 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 'bolt project migrate'."
+                "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 'bolt project init'."
+                "to install modules. To create a Bolt project, run '#{command}'."
               end
 
         raise Bolt::Error.new(msg, 'bolt/missing-project-config-error')
@@ -953,10 +784,12 @@ module Bolt
 
     # Loads a Puppetfile and installs its modules.
     #
-    def install_puppetfile(config, puppetfile, moduledir)
+    def install_puppetfile(puppetfile_config, puppetfile, moduledir)
+      assert_puppetfile_or_module_command(config.project.modules)
+
       outputter.print_message("Installing modules from Puppetfile")
       installer = Bolt::ModuleInstaller.new(outputter, pal)
-      ok = installer.install_puppetfile(puppetfile, moduledir, config)
+      ok = installer.install_puppetfile(puppetfile, moduledir, puppetfile_config)
       ok ? 0 : 1
     end
 
@@ -964,17 +797,36 @@ module Bolt
     # modules being configured.
     #
     def assert_puppetfile_or_module_command(modules)
+      if Bolt::Util.powershell?
+        case options[:action]
+        when 'generate-types'
+          old_command = 'Register-BoltPuppetfileTypes'
+          new_command = 'Register-BoltModuleTypes'
+        when 'install'
+          old_command = 'Install-BoltPuppetfile'
+          new_command = 'Install-BoltModule'
+        when 'show', 'show-modules'
+          old_command = 'Get-BoltPuppetfileModules'
+          new_command = 'Get-BoltModule'
+        end
+      else
+        old_command = "bolt puppetfile #{options[:action]}"
+        new_command = if options[:action] == 'show-modules'
+                        'bolt module show'
+                      else
+                        "bolt module #{options[:action]}"
+                      end
+      end
+
       if modules && options[:subcommand] == 'puppetfile'
         raise Bolt::CLIError,
-              "Unable to use command 'bolt puppetfile #{options[:action]}' when "\
-              "'modules' is configured in bolt-project.yaml. Use the 'module' command "\
-              "instead. For a list of available actions for the 'module' command, run "\
-              "'bolt module --help'."
+              "Unable to use command '#{old_command}' when 'modules' is configured in "\
+              "bolt-project.yaml. Use '#{new_command}' instead."
       elsif modules.nil? && options[:subcommand] == 'module'
-        raise Bolt::CLIError,
-              "Unable to use command 'bolt module #{options[:action]}'. To use "\
-              "this command, update your project configuration to manage module "\
-              "dependencies."
+        msg  = "Unable to use command '#{new_command}' when 'modules' is not configured in "\
+               "bolt-project.yaml. "
+        msg += "Use '#{old_command}' instead." if options[:action] != 'add'
+        raise Bolt::CLIError, msg
       end
     end