bolt 2.31.0 → 2.35.0

data/guides/module.txt

@@ -0,0 +1,19 @@
+TOPIC
+    module
+
+DESCRIPTION
+    Modules are shareable, reusable packages of Puppet content. They can include
+    tasks, plans, functions, and other types of content that you can use in your
+    project. You can download and install modules to your project from the
+    Puppet Forge or write your own modules. Bolt also ships with several helpful
+    modules pre-installed that are available to all of your projects.
+
+    Bolt makes it easy to manage the modules that your project depends on. You
+    can use Bolt commands to install a project's modules, add new modules to a
+    project, and view the modules that are available to the project.
+    
+    To learn more about managing modules in a project, see the documentation.
+    To learn how modules are loaded by Bolt, see the 'modulepath' guide.
+
+DOCUMENTATION
+    https://pup.pt/bolt-modules

data/guides/modulepath.txt

@@ -0,0 +1,25 @@
+TOPIC
+    modulepath
+
+DESCRIPTION
+    The modulepath is an ordered list of directories that Bolt loads modules
+    from. When Bolt runs a command, it automatically loads modules from the
+    modulepath.
+    
+    While Bolt has a default modulepath, you can also configure your own
+    modulepath, which can include directories within the project or directories
+    elsewhere on your system. Regardless of whether your project uses a default
+    or configured modulepath, Bolt automatically adds directories to the
+    modulepath. This includes modules containing core Bolt content, which is
+    added to the beginning of the modulepath, and bundled content, which is
+    added to the end of the modulepath.
+
+    Modules loaded from a directory listed earlier in the modulepath take
+    precedence over modules with the same name loaded from a directory later in
+    the modulepath. Bolt will not warn or error when two modules share a name
+    and instead will ignore modules with a lower precedence.
+
+    To learn more about modules, see the 'module' guide.
+
+DOCUMENTATION
+    https://pup.pt/bolt-project-reference#modulepath

data/lib/bolt/bolt_option_parser.rb

@@ -88,7 +88,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] + %w[configfile project pp],
             banner: PLAN_NEW_HELP }
         when 'run'
           { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir hiera-config],
@@ -945,6 +945,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,17 +15,18 @@ 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/pal'
+require 'bolt/plan_creator'
 require 'bolt/plugin'
 require 'bolt/project_migrator'
-require 'bolt/pal'
+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
@@ -196,10 +197,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 +225,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 +282,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' &&
@@ -465,7 +463,16 @@ module Bolt
       when 'plan'
         case options[:action]
         when 'new'
-          code = new_plan(options[:object])
+          command = Bolt::Util.powershell? ? 'New-BoltPlan' : 'bolt plan new'
+          @logger.warn("Command '#{command}' is experimental and subject to changes.")
+          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 +575,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 +592,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 +627,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,10 +718,12 @@ 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
@@ -844,8 +744,9 @@ module Bolt
             "project name must begin with a lowercase letter and can include lowercase "\
             "letters, numbers, and underscores."
         else
+          command = Bolt::Util.powershell? ? 'New-BoltProject -Name <NAME>' : 'bolt project init <NAME>'
           raise Bolt::ValidationError, "The current directory name '#{name}' is an invalid "\
-            "project name. Please specify a name using 'bolt project init <name>'."
+            "project name. Please specify a name using '#{command}'."
         end
       end
 
@@ -902,6 +803,7 @@ module Bolt
     #
     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 +825,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 +843,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 +858,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 +871,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
 

data/lib/bolt/config/options.rb

@@ -234,26 +234,44 @@ module Bolt
           type: Array,
           items: {
             type: [Hash, String],
-            required: ["name"],
-            properties: {
-              "name" => {
-                description: "The name of the module.",
-                type: String
+            oneOf: [
+              {
+                required: ["name"],
+                properties: {
+                  "name" => {
+                    description: "The name of the module.",
+                    type: String
+                  },
+                  "version_requirement" => {
+                    description: "The version requirement for the module. Accepts a specific version (1.2.3), version "\
+                                 "shorthand (1.2.x), or a version range (>= 1.2.0).",
+                    type: String
+                  }
+                }
               },
-              "version_requirement" => {
-                description: "The version requirement for the module. Accepts a specific version (1.2.3), version "\
-                             "shorthand (1.2.x), or a version range (>= 1.2.0).",
-                type: String
+              {
+                required: %w[git ref],
+                properties: {
+                  "git" => {
+                    description: "The URL to the public git repository.",
+                    type: String
+                  },
+                  "ref" => {
+                    description: "The git reference to check out. Can be either a branch, tag, or commit SHA.",
+                    type: String
+                  }
+                }
               }
-            }
+            ]
           },
           _plugin: false,
           _example: [
-            { "name" => "puppetlabs-mysql" },
             "puppetlabs-facts",
+            { "name" => "puppetlabs-mysql" },
             { "name" => "puppetlabs-apache", "version_requirement" => "5.5.0" },
             { "name" => "puppetlabs-puppetdb", "version_requirement" => "7.x" },
-            { "name" => "puppetlabs-firewall", "version_requirement" => ">= 1.0.0 < 3.0.0" }
+            { "name" => "puppetlabs-firewall", "version_requirement" => ">= 1.0.0 < 3.0.0" },
+            { "git" => "https://github.com/puppetlabs/puppetlabs-apt", "ref" => "7.6.0" }
           ]
         },
         "name" => {
@@ -265,7 +283,7 @@ module Bolt
           _example: "myproject"
         },
         "plans" => {
-          description: "A list of plan names to show in `bolt plan show` output, if they exist. This option is used "\
+          description: "A list of plan names and glob patterns to filter the project's plans by. This option is used "\
                        "to limit the visibility of plans for users of the project. For example, project authors "\
                        "might want to limit the visibility of plans that are bundled with Bolt or plans that should "\
                        "only be run as part of another plan. When this option is not configured, all plans are "\
@@ -273,7 +291,7 @@ module Bolt
                        "list.",
           type: Array,
           _plugin: false,
-          _example: ["myproject", "myproject::foo", "myproject::bar"]
+          _example: ["myproject", "myproject::foo", "myproject::bar", "myproject::deploy::*"]
         },
         "plugin_hooks" => {
           description: "A map of [plugin hooks](writing_plugins.md#hooks) and which plugins a hook should use. "\
@@ -329,7 +347,7 @@ module Bolt
             "server_urls" => {
               description: "An array containing the PuppetDB host to connect to. Include the protocol `https` "\
                            "and the port, which is usually `8081`. For example, "\
-                           "`https://my-master.example.com:8081`.",
+                           "`https://my-puppetdb-server.com:8081`.",
               type: Array,
               _example: ["https://puppet.example.com:8081"]
             },
@@ -384,7 +402,7 @@ module Bolt
           _default: true
         },
         "tasks" => {
-          description: "A list of task names to show in `bolt task show` output, if they exist. This option is used "\
+          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 "\
                        "might want to limit the visibility of tasks that are bundled with Bolt or plans that should "\
                        "only be run as part of a larger workflow. When this option is not configured, all tasks "\
@@ -395,7 +413,7 @@ module Bolt
             type: String
           },
           _plugin: false,
-          _example: ["myproject", "myproject::foo", "myproject::bar"]
+          _example: ["myproject", "myproject::foo", "myproject::bar", "myproject::deploy_*"]
         },
         "trusted-external-command" => {
           description: "The path to an executable on the Bolt controller that can produce external trusted facts. "\