bolt 1.41.0 → 1.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc1e64c9534b1225ee0b2e7d33082fc5c811a01b530910ca1885920d1ead4af3
-  data.tar.gz: fc120c02dd62a691fc7acac412750329cbbf5e10a78c90402877463cf9f42d99
+  metadata.gz: d70e65622c7ae119fafb6212eda5fa66e517bf190f404d00f150d98efa616ce8
+  data.tar.gz: 9fdfbbf45efc6b1a3ec4f0364dfaf2d2682de8a30c3ab17b7893db9091da3e9f
 SHA512:
-  metadata.gz: 378be37bc8b7ef4c0fc77ca2f3030a45da1d6f0cd3e3733ce8cb2ae0aeb26e34f5542e467397c9dfb56aa7e54765d983939fe7491c684af11b64dc195c8fc632
-  data.tar.gz: 666ea5b5111b85f41243c1aefe495ff5b1b87e4dcf4e4dcd6b202397ade6dad252e202eaf3e3549558f669b0e0563e04ce2537b58f363cfea32ac6952eb3d234
+  metadata.gz: 3ba016ff367bf902b3a512ec7a6f3c46bac6fed6a16ef207400af12a741821a5aa5baa18b38e8dbbed201d555e71f88eafb38912e4acdb3e715362bb27ec8f51
+  data.tar.gz: a37fa6e6f3a703d3d2b7b00c578884a617578800c190105bfbc6398a5febdca5475fa96737f82fd0677b22f174932bf20fb30271964a65f959ebc6cea4dfce6f

data/bolt-modules/boltlib/lib/puppet/functions/remove_from_group.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Removes a target from the specified inventory group.
+#
+# The target is removed from all child groups and all parent groups where the target has
+# not been explicitly defined. A target cannot be removed from the 'all' group.
+#
+# **NOTE:** Not available in apply block
+Puppet::Functions.create_function(:remove_from_group) do
+  # @param target A pattern identifying a single target.
+  # @param group The name of the group to remove the target from.
+  # @example Remove Target from group.
+  #   remove_from_group('foo@example.com', 'group1')
+  # @example Remove failing Targets from the rest of a plan
+  #   $result = run_command(uptime, my_group, '_catch_errors' => true)
+  #   $result.error_set.targets.each |$t| { remove_from_group($t, my_group) }
+  #   run_command(next_command, my_group) # does not target the failing nodes.
+  dispatch :remove_from_group do
+    param 'Boltlib::TargetSpec', :target
+    param 'String[1]', :group
+  end
+
+  def remove_from_group(target, group)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'remove_from_group')
+    end
+
+    inventory = Puppet.lookup(:bolt_inventory)
+    executor = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    inventory.remove_from_group(inventory.get_targets(target), group)
+  end
+end

data/lib/bolt/bolt_option_parser.rb

@@ -23,30 +23,54 @@ module Bolt
         { flags: ACTION_OPTS + %w[noop execute compile-concurrency],
           banner: APPLY_HELP }
       when 'command'
-        { flags: ACTION_OPTS,
-          banner: COMMAND_HELP }
+        case action
+        when 'run'
+          { flags: ACTION_OPTS,
+            banner: COMMAND_RUN_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: COMMAND_HELP }
+        end
       when 'file'
-        { flags: ACTION_OPTS + %w[tmpdir],
-          banner: FILE_HELP }
+        case action
+        when 'upload'
+          { flags: ACTION_OPTS + %w[tmpdir],
+            banner: FILE_UPLOAD_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: FILE_HELP }
+        end
       when 'inventory'
-        { flags: OPTIONS[:inventory] + OPTIONS[:global] + %w[format inventoryfile boltdir configfile detail],
-          banner: INVENTORY_HELP }
+        case action
+        when 'show'
+          { flags: OPTIONS[:inventory] + OPTIONS[:global] + %w[format inventoryfile boltdir configfile detail],
+            banner: INVENTORY_SHOW_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: INVENTORY_HELP }
+        end
       when 'group'
-        { flags: OPTIONS[:global] + %w[format inventoryfile boltdir configfile],
-          banner: GROUP_HELP }
+        case action
+        when 'show'
+          { flags: OPTIONS[:global] + %w[format inventoryfile boltdir configfile],
+            banner: GROUP_SHOW_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: GROUP_HELP }
+        end
       when 'plan'
         case action
         when 'convert'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
             banner: PLAN_CONVERT_HELP }
-        when 'show'
-          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
-            banner: PLAN_SHOW_HELP }
         when 'run'
           { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir],
             banner: PLAN_RUN_HELP }
+        when 'show'
+          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
+            banner: PLAN_SHOW_HELP }
         else
-          { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir],
+          { flags: OPTIONS[:global],
             banner: PLAN_HELP }
         end
       when 'project'
@@ -73,25 +97,43 @@ module Bolt
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
             banner: PUPPETFILE_GENERATETYPES_HELP }
         else
-          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
+          { flags: OPTIONS[:global],
             banner: PUPPETFILE_HELP }
         end
       when 'script'
-        { flags: ACTION_OPTS + %w[tmpdir],
-          banner: SCRIPT_HELP }
+        case action
+        when 'run'
+          { flags: ACTION_OPTS + %w[tmpdir],
+            banner: SCRIPT_RUN_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: SCRIPT_HELP }
+        end
       when 'secret'
-        { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[plugin],
-          banner: SECRET_HELP }
+        case action
+        when 'createkeys'
+          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[plugin],
+            banner: SECRET_CREATEKEYS_HELP }
+        when 'decrypt'
+          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[plugin],
+            banner: SECRET_DECRYPT_HELP }
+        when 'encrypt'
+          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[plugin],
+            banner: SECRET_ENCRYPT_HELP }
+        else
+          { flags: OPTIONS[:global],
+            banner: SECRET_HELP }
+        end
       when 'task'
         case action
-        when 'show'
-          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
-            banner: TASK_SHOW_HELP }
         when 'run'
           { flags: ACTION_OPTS + %w[params tmpdir],
             banner: TASK_RUN_HELP }
+        when 'show'
+          { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
+            banner: TASK_SHOW_HELP }
         else
-          { flags: ACTION_OPTS + %w[params tmpdir],
+          { flags: OPTIONS[:global],
             banner: TASK_HELP }
         end
       else
@@ -100,258 +142,454 @@ module Bolt
       end
     end
 
-    def self.examples(cmd, desc)
-      <<~EXAMP
-      #{desc} a Windows host via WinRM, providing for the password
-        bolt #{cmd} -n winrm://winhost -u Administrator -p
-      #{desc} the local machine, a Linux host via SSH, and hosts from a group specified in an inventory file
-        bolt #{cmd} -n localhost,nixhost,node_group
-      #{desc} Windows hosts queried from PuppetDB via WinRM as a domain user, prompting for the password
-        bolt #{cmd} -q 'inventory[certname] { facts.os.family = "windows" }' --transport winrm -u 'domain\\Administrator' -p
-      EXAMP
-    end
-
     BANNER = <<~HELP
-      Usage: bolt <subcommand> <action>
-
-      Available subcommands:
-        bolt command run <command>       Run a command remotely
-        bolt file upload <src> <dest>    Upload a local file or directory
-        bolt script run <script>         Upload a local script and run it remotely
-        bolt task show                   Show list of available tasks
-        bolt task show <task>            Show documentation for task
-        bolt task run <task> [params]    Run a Puppet task
-        bolt plan convert <plan_path>    Convert a YAML plan to a Puppet plan
-        bolt plan show                   Show list of available plans
-        bolt plan show <plan>            Show details for plan
-        bolt plan run <plan> [params]    Run a Puppet task plan
-        bolt apply <manifest>            Apply Puppet manifest code
-        bolt puppetfile install          Install modules from a Puppetfile into a Boltdir
-        bolt puppetfile show-modules     List modules available to Bolt
-        bolt secret createkeys           Create new encryption keys
-        bolt secret encrypt <plaintext>  Encrypt a value
-        bolt secret decrypt <encrypted>  Decrypt a value
-        bolt inventory show              Show the list of targets an action would run on
-        bolt group show                  Show the list of groups in the inventory
-        bolt project init                Create a new Bolt project
-        bolt project migrate             Migrate a Bolt project to the latest version
-
-      Run `bolt <subcommand> --help` to view specific examples.
-
-      Available options are:
+      NAME
+          bolt
+
+      USAGE
+          bolt <subcommand> [action] [options]
+
+      DESCRIPTION
+          Bolt is an orchestration tool that automates the manual work it takes to
+          maintain your infrastructure.
+
+      SUBCOMMANDS
+          apply             Apply Puppet manifest code
+          command           Run a command remotely
+          file              Upload a local file or directory
+          group             Show the list of groups in the inventory
+          inventory         Show the list of targets an action would run on
+          plan              Convert, show, and run Bolt plans
+          project           Create and migrate Bolt projects
+          puppetfile        Install and list modules and generate type references
+          script            Upload a local script and run it remotely
+          secret            Create encryption keys and encrypt and decrypt values
+          task              Show and run Bolt tasks
     HELP
 
-    TASK_HELP = <<~HELP
-      Usage: bolt task <action> <task> [parameters]
+    APPLY_HELP = <<~HELP
+      NAME
+          apply
 
-      Available actions are:
-        show                             Show list of available tasks
-        show <task>                      Show documentation for task
-        run <task>                       Run a Puppet task
+      USAGE
+          bolt apply <manifest.pp> [options]
 
-      Parameters are of the form <parameter>=<value>.
+      DESCRIPTION
+          Apply Puppet manifest code on the specified targets.
 
-      #{examples('task run facts', 'run facter on')}
-      Available options are:
+      EXAMPLES
+          bolt apply manifest.pp --targets target1,target2
     HELP
 
-    TASK_SHOW_HELP = <<~HELP
-      Usage: bolt task show <task>
+    COMMAND_HELP = <<~HELP
+      NAME
+          command
 
-      Available actions are:
-        show                             Show list of available tasks
-        show <task>                      Show documentation for task
+      USAGE
+          bolt command <action> [options]
 
-      Available options are:
+      DESCRIPTION
+          Run a command on the specified targets.
+
+      ACTIONS
+          run         Run a command on the specified targets.
     HELP
 
-    TASK_RUN_HELP = <<~HELP
-      Usage: bolt task run <task> [parameters]
+    COMMAND_RUN_HELP = <<~HELP
+      NAME
+          run
 
-      Parameters are of the form <parameter>=<value>.
+      USAGE
+          bolt command run <command> [options]
 
-      #{examples('task run facts', 'run facter on')}
-      Available options are:
+      DESCRIPTION
+          Run a command on the specified targets.
+
+      EXAMPLES
+          bolt command run 'uptime' -t target1,target2
     HELP
 
-    COMMAND_HELP = <<~HELP
-      Usage: bolt command <action> <command>
+    FILE_HELP = <<~HELP
+      NAME
+          file
+
+      USAGE
+          bolt file <action> [options]
 
-      Available actions are:
-        run                              Run a command remotely
+      DESCRIPTION
+          Upload a local file or directory
 
-      #{examples('command run hostname', 'run hostname on')}
-      Available options are:
+      ACTIONS
+          upload        Upload a local file or directory
     HELP
 
-    SCRIPT_HELP = <<~HELP
-      Usage: bolt script <action> <script> [[arg1] ... [argN]]
+    FILE_UPLOAD_HELP = <<~HELP
+      NAME
+          upload
+
+      USAGE
+          bolt file upload <src> <dest> [options]
+
+      DESCRIPTION
+          Upload a local file or directory.
+
+      EXAMPLES
+          bolt file upload /tmp/source /etc/profile.d/login.sh -t target1
+    HELP
+
+    GROUP_HELP = <<~HELP
+      NAME
+          group
 
-      Available actions are:
-        run                              Upload a local script and run it remotely
+      USAGE
+          bolt group <action> [options]
 
-      #{examples('script run my_script.ps1 some args', 'run a script on')}
-      Available options are:
+      DESCRIPTION
+          Show the list of groups in the inventory.
+
+      ACTIONS
+          show          Show the list of groups in the inventory
+    HELP
+
+    GROUP_SHOW_HELP = <<~HELP
+      NAME
+          show
+
+      USAGE
+          bolt group show [options]
+
+      DESCRIPTION
+          Show the list of groups in the inventory.
+    HELP
+
+    INVENTORY_HELP = <<~HELP
+      NAME
+          inventory
+
+      USAGE
+          bolt inventory <action> [options]
+
+      DESCRIPTION
+          Show the list of targets an action would run on.
+
+      ACTIONS
+          show          Show the list of targets an action would run on
+    HELP
+
+    INVENTORY_SHOW_HELP = <<~HELP
+      NAME
+          show
+
+      USAGE
+          bolt inventory show [options]
+
+      DESCRIPTION
+          Show the list of targets an action would run on.
     HELP
 
     PLAN_HELP = <<~HELP
-      Usage: bolt plan <action> <plan> [parameters]
+      NAME
+          plan
 
-      Available actions are:
-        convert <plan_path>              Convert a YAML plan to a Puppet plan
-        show                             Show list of available plans
-        show <plan>                      Show details for plan
-        run                              Run a Puppet task plan
+      USAGE
+          bolt plan <action> [parameters] [options]
 
-      Parameters are of the form <parameter>=<value>.
+      DESCRIPTION
+          Convert, show, and run Bolt plans.
 
-      #{examples('plan run canary command=hostname', 'run the canary plan on')}
-      Available options are:
+      ACTIONS
+          convert       Convert a YAML plan to a Bolt plan
+          run           Run a plan on the specified targets
+          show          Show available plans and plan documentation
     HELP
 
     PLAN_CONVERT_HELP = <<~HELP
-      Usage: bolt plan convert <plan_path>
+      NAME
+          convert
+
+      USAGE
+          bolt plan convert <path> [options]
 
-      Available options are:
+      DESCRIPTION
+          Convert a YAML plan to a Bolt plan.
+
+          Converting a YAML plan may result in a plan that is syntactically
+          correct but has different behavior. Always verify a converted plan's
+          functionality.
+
+      EXAMPLES
+          bolt plan convert path/to/plan/myplan.yaml
+    HELP
+
+    PLAN_RUN_HELP = <<~HELP
+      NAME
+          run
+
+      USAGE
+          bolt plan run <plan> [parameters] [options]
+
+      DESCRIPTION
+          Run a plan on the specified targets.
+
+      EXAMPLES
+          bolt plan run canary --targets target1,target2 command=hostname
     HELP
 
     PLAN_SHOW_HELP = <<~HELP
-      Usage: bolt plan show <plan>
+      NAME
+          show
 
-      Available actions are:
-        show                             Show list of available plans
-        show <plan>                      Show details for plan
+      USAGE
+          bolt plan show [plan] [options]
 
-      Available options are:
+      DESCRIPTION
+          Show available plans and plan documentation.
+
+          Omitting the name of a plan will display a list of plans available
+          in the Bolt project.
+
+          Providing the name of a plan will display detailed documentation for
+          the plan, including a list of available parameters.
+
+      EXAMPLES
+          Display a list of available tasks
+            bolt plan show
+          Display documentation for the canary task
+            bolt plan show aggregate::count
     HELP
 
-    PLAN_RUN_HELP = <<~HELP
-      Usage: bolt plan run <plan> [parameters]
+    PROJECT_HELP = <<~HELP
+      NAME
+          project
 
-      Parameters are of the form <parameter>=<value>.
+      USAGE
+          bolt project <action> [options]
 
-      #{examples('plan run canary command=hostname', 'run the canary plan on')}
-      Available options are:
+      DESCRIPTION
+          Create and migrate Bolt projects
+
+      ACTIONS
+          init              Create a new Bolt project
+          migrate           Migrate a Bolt project to the latest version
     HELP
 
-    FILE_HELP = <<~HELP
-      Usage: bolt file <action>
+    PROJECT_INIT_HELP = <<~HELP
+      NAME
+          init
+
+      USAGE
+          bolt project init [directory] [options]
+
+      DESCRIPTION
+          Create a new Bolt project.
 
-      Available actions are:
-        upload <src> <dest>              Upload local file or directory <src> to <dest> on each node
+          Specify a directory to create a Bolt project in. Defaults to the
+          curent working directory.
 
-      #{examples('file upload /tmp/source /etc/profile.d/login.sh', 'upload a file to')}
-      Available options are:
+      EXAMPLES
+          Create a new Bolt project in the current working directory.
+            bolt project init
+          Create a new Bolt project at a specified path.
+            bolt project init ~/path/to/project
+    HELP
+
+    PROJECT_MIGRATE_HELP = <<~HELP
+      NAME
+          migrate
+
+      USAGE
+          bolt project migrate [options]
+
+      DESCRIPTION
+          Migrate a Bolt project to the latest version.
+
+          Loads a Bolt project's inventory file and migrates it to the latest version. The
+          inventory file is modified in place and will not preserve comments or formatting.
     HELP
 
     PUPPETFILE_HELP = <<~HELP
-      Usage: bolt puppetfile <action>
+      NAME
+          puppetfile
+
+      USAGE
+          bolt puppetfile <action> [options]
+
+      DESCRIPTION
+          Install and list modules and generate type references
+
+      ACTIONS
+          generate-types        Generate type references to register in plans
+          install               Install modules from a Puppetfile into a Boltdir
+          show-modules          List modules available to the Bolt project
+    HELP
 
-      Available actions are:
-        install                          Install modules from a Puppetfile into a Boltdir
-        show-modules                     List modules available to Bolt
-        generate-types                   Generate type references to register in Plans
+    PUPPETFILE_GENERATETYPES_HELP = <<~HELP
+      NAME
+          generate-types
 
-      Install modules into the local Boltdir
-        bolt puppetfile install
+      USAGE
+          bolt puppetfile generate-types [options]
 
-      Available options are:
+      DESCRIPTION
+          Generate type references to register in plans.
     HELP
 
     PUPPETFILE_INSTALL_HELP = <<~HELP
-      Usage: bolt puppetfile install
+      NAME
+          install
 
-      Install modules into the local Boltdir
-        bolt puppetfile install
+      USAGE
+          bolt puppetfile install [options]
 
-      Available options are:
+      DESCRIPTION
+          Install modules from a Puppetfile into a Boltdir
     HELP
 
     PUPPETFILE_SHOWMODULES_HELP = <<~HELP
-      Usage: bolt puppetfile show-modules
+      NAME
+          show-modules
 
-      List modules available to Bolt
-        bolt puppetfile show-modules
+      USAGE
+          bolt puppetfile show-modules [options]
 
-      Available options are:
+      DESCRIPTION
+          List modules available to the Bolt project.
     HELP
 
-    PUPPETFILE_GENERATETYPES_HELP = <<~HELP
-      Usage: bolt puppetfile generate-types
+    SCRIPT_HELP = <<~HELP
+      NAME
+          script
 
-      Generate type references to register in Plans
-        bolt puppetfile generate-types
+      USAGE
+          bolt script <action> [options]
 
-      Available options are:
+      DESCRIPTION
+          Run a script on the specified targets.
+
+      ACTIONS
+          run         Run a script on the specified targets.
     HELP
 
-    APPLY_HELP = <<~HELP
-      Usage: bolt apply <manifest.pp>
+    SCRIPT_RUN_HELP = <<~HELP
+      NAME
+          run
+
+      USAGE
+          bolt script run <script> [arguments] [options]
+
+      DESCRIPTION
+          Run a script on the specified targets.
+
+          Arguments passed to a script are passed literally and are not interpolated
+          by the shell. Any arguments containing spaces or special characters should
+          be quoted.
+
+      EXAMPLES
+          bolt script run myscript.sh 'echo hello' --targets target1,target2
+    HELP
+
+    SECRET_HELP = <<~HELP
+      NAME
+          secret
 
-      #{examples('apply site.pp', 'apply a manifest on')}
-        bolt apply site.pp --nodes foo.example.com,bar.example.com
+      USAGE
+          bolt secret <action> [options]
 
-      Available options are:
+      DESCRIPTION
+          Create encryption keys and encrypt and decrypt values.
+
+      ACTIONS
+          createkeys           Create new encryption keys
+          encrypt              Encrypt a value
+          decrypt              Decrypt a value
+    HELP
+
+    SECRET_CREATEKEYS_HELP = <<~HELP
+      NAME
+          createkeys
+
+      USAGE
+          bolt secret createkeys [options]
+
+      DESCRIPTION
+          Create new encryption keys.
+    HELP
+
+    SECRET_DECRYPT_HELP = <<~HELP
+      NAME
+          decrypt
+
+      USAGE
+          bolt secret decrypt <ciphertext> [options]
+
+      DESCRIPTION
+          Decrypt a value.
     HELP
 
-    SECRET_HELP = <<~SECRET_HELP
-      Usage: bolt secret <action> <value>
-      Manage secrets for inventory and hiera data.
+    SECRET_ENCRYPT_HELP = <<~HELP
+      NAME
+          encrypt
 
-      Available actions are:
-        createkeys               Create new encryption keys
-        encrypt                  Encrypt a value
-        decrypt                  Decrypt a value
+      USAGE
+        bolt secret encrypt <plaintext> [options]
 
-      Available options are:
-    SECRET_HELP
+      DESCRIPTION
+          Encrypt a value.
+    HELP
 
-    INVENTORY_HELP = <<~INVENTORY_HELP
-      Usage: bolt inventory <action>
+    TASK_HELP = <<~HELP
+      NAME
+          task
 
-      Available actions are:
-        show                     Show the list of targets an action would run on
+      USAGE
+          bolt task <action> [options]
 
-      Available options are:
-    INVENTORY_HELP
+      DESCRIPTION
+          Show and run Bolt tasks.
 
-    GROUP_HELP = <<~GROUP_HELP
-      Usage: bolt group <action>
+      ACTIONS
+          run          Run a Bolt task
+          show         Show available tasks and task documentation
+    HELP
 
-      Available actions are:
-        show                     Show the list of groups in the inventory
+    TASK_RUN_HELP = <<~HELP
+      NAME
+          run
 
-      Available options are:
-    GROUP_HELP
+      USAGE
+          bolt task run <task> [parameters] [options]
 
-    PROJECT_HELP = <<~PROJECT_HELP
-      Usage: bolt project <action>
+      DESCRIPTION
+          Run a task on the specified targets.
 
-      Available actions are:
-        init                     Create a new Bolt project
-        migrate                  Migrate a Bolt project to the latest version
+          Parameters take the form <parameter>=<value>.
 
-      Available options are:
-    PROJECT_HELP
+      EXAMPLES
+          bolt task run package --targets target1,target2 action=status name=bash
+    HELP
 
-    PROJECT_INIT_HELP = <<~PROJECT_INIT_HELP
-      Usage: bolt project init [directory]
+    TASK_SHOW_HELP = <<~HELP
+      NAME
+          show
 
-      Create a new Bolt project.
-      Specify a directory to create the Bolt project in. Defaults to the current working directory.
+      USAGE
+          bolt task show [task] [options]
 
-      Available options are:
-    PROJECT_INIT_HELP
+      DESCRIPTION
+          Show available tasks and task documentation.
 
-    PROJECT_MIGRATE_HELP = <<~PROJECT_MIGRATE_HELP
-      Usage: bolt project migrate
+          Omitting the name of a task will display a list of tasks available
+          in the Bolt project.
 
-      Migrate a Bolt project to the latest version.
-      Loads a Bolt project's inventory file and migrates it to the latest version. The
-      inventory file is modified in place and will not preserve comments or formatting.
+          Providing the name of a task will display detailed documentation for
+          the task, including a list of available parameters.
 
-      Available options are:
-    PROJECT_MIGRATE_HELP
+      EXAMPLES
+          Display a list of available tasks
+            bolt task show
+          Display documentation for the canary task
+            bolt task show canary
+    HELP
 
     attr_reader :warnings
     def initialize(options)
@@ -360,6 +598,7 @@ module Bolt
       @options = options
       @warnings = []
 
+      separator "\nINVENTORY OPTIONS"
       define('-n', '--nodes NODES',
              'Alias for --targets',
              'Deprecated in favor of --targets') do |nodes|
@@ -407,7 +646,7 @@ module Bolt
         @options[:detail] = detail
       end
 
-      separator "\nAuthentication:"
+      separator "\nAUTHENTICATION OPTIONS"
       define('-u', '--user USER', 'User to authenticate as') do |user|
         @options[:user] = user
       end
@@ -442,7 +681,7 @@ module Bolt
         @options[:'ssl-verify'] = ssl_verify
       end
 
-      separator "\nEscalation:"
+      separator "\nESCALATION OPTIONS"
       define('--run-as USER', 'User to run as using privilege escalation') do |user|
         @options[:'run-as'] = user
       end
@@ -465,7 +704,7 @@ module Bolt
         STDERR.puts
       end
 
-      separator "\nRun context:"
+      separator "\nRUN CONTEXT OPTIONS"
       define('-c', '--concurrency CONCURRENCY', Integer,
              'Maximum number of simultaneous connections (default: 100)') do |concurrency|
         @options[:concurrency] = concurrency
@@ -502,7 +741,7 @@ module Bolt
         @options[:'save-rerun'] = save
       end
 
-      separator "\nTransports:"
+      separator "\nTRANSPORT OPTIONS"
       define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s),
              "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t|
         @options[:transport] = t
@@ -517,7 +756,7 @@ module Bolt
         @options[:tmpdir] = tmpdir
       end
 
-      separator "\nDisplay:"
+      separator "\nDISPLAY OPTIONS"
       define('--format FORMAT', 'Output format to use: human or json') do |format|
         @options[:format] = format
       end
@@ -531,7 +770,7 @@ module Bolt
         @options[:trace] = true
       end
 
-      separator "\nGlobal:"
+      separator "\nGLOBAL OPTIONS"
       define('-h', '--help', 'Display help') do |_|
         @options[:help] = true
       end

data/lib/bolt/inventory.rb

@@ -140,6 +140,23 @@ module Bolt
       end
     end
 
+    def remove_from_group(target, desired_group)
+      unless target.length == 1
+        raise ValidationError.new("'remove_from_group' expects a single Target, got #{target.length}", nil)
+      end
+
+      if desired_group == 'all'
+        raise ValidationError.new("Cannot remove Target from Group 'all'", nil)
+      end
+
+      if group_names.include?(desired_group)
+        invalidate_group_cache!(target.first)
+        remove_node(@groups, target.first, desired_group)
+      else
+        raise ValidationError.new("Group #{desired_group} does not exist in inventory", nil)
+      end
+    end
+
     def set_var(target, var_hash)
       set_vars_from_hash(target.name, var_hash)
     end
@@ -329,30 +346,30 @@ module Bolt
     end
     private :set_plugin_hooks
 
+    def remove_node(current_group, target, desired_group, track = { 'all' => nil })
+      # Remove the target from the group
+      if current_group.name == desired_group
+        current_group.nodes.delete(target.name)
+      # If the target remains in the group, add the group data to the cache
+      elsif current_group.node_names.include?(target.name)
+        add_group_data_to_cache(current_group, target, track)
+      end
+      current_group.groups.each do |child_group|
+        # If target was in current group, remove it from all child groups
+        desired_group = child_group.name if current_group.name == desired_group
+        track[child_group.name] = current_group
+        remove_node(child_group, target, desired_group)
+      end
+    end
+    private :remove_node
+
     def add_node(current_group, target, desired_group, track = { 'all' => nil })
       if current_group.name == desired_group
         # Group to add to is found
         t_name = target.name
         # Add target to nodes hash
         current_group.nodes[t_name] = { 'name' => t_name }.merge(target.options)
-        # Inherit facts, vars, and features from hierarchy
-        current_group_data = { facts: current_group.facts,
-                               vars: current_group.vars,
-                               features: current_group.features,
-                               plugin_hooks: current_group.plugin_hooks }
-        data = inherit_data(track, current_group.name, current_group_data)
-        set_facts(t_name, @target_facts[t_name] ? data[:facts].merge(@target_facts[t_name]) : data[:facts])
-        set_vars_from_hash(t_name, @target_vars[t_name] ? data[:vars].merge(@target_vars[t_name]) : data[:vars])
-        data[:features].each do |feature|
-          set_feature(target, feature)
-        end
-        hook_data = @config.plugin_hooks.merge(data[:plugin_hooks])
-        hash = if @target_plugin_hooks[t_name]
-                 hook_data.merge(@target_plugin_hooks[t_name])
-               else
-                 hook_data
-               end
-        set_plugin_hooks(t_name, hash)
+        add_group_data_to_cache(current_group, target, track)
         return true
       end
       # Recurse on children Groups if not desired_group
@@ -363,6 +380,28 @@ module Bolt
     end
     private :add_node
 
+    def add_group_data_to_cache(current_group, target, track)
+      t_name = target.name
+      current_group_data = { facts: current_group.facts,
+                             vars: current_group.vars,
+                             features: current_group.features,
+                             plugin_hooks: current_group.plugin_hooks }
+      data = inherit_data(track, current_group.name, current_group_data)
+      set_facts(t_name, @target_facts[t_name] ? data[:facts].merge(@target_facts[t_name]) : data[:facts])
+      set_vars_from_hash(t_name, @target_vars[t_name] ? data[:vars].merge(@target_vars[t_name]) : data[:vars])
+      data[:features].each do |feature|
+        set_feature(target, feature)
+      end
+      hook_data = @config.plugin_hooks.merge(data[:plugin_hooks])
+      hash = if @target_plugin_hooks[t_name]
+               hook_data.merge(@target_plugin_hooks[t_name])
+             else
+               hook_data
+             end
+      set_plugin_hooks(t_name, hash)
+    end
+    private :add_group_data_to_cache
+
     def inherit_data(track, name, data)
       unless track[name].nil?
         data[:facts] = track[name].facts.merge(data[:facts])
@@ -374,5 +413,13 @@ module Bolt
       data
     end
     private :inherit_data
+
+    def invalidate_group_cache!(target)
+      @target_facts.delete(target.name)
+      @target_features.delete(target.name)
+      @target_vars.delete(target.name)
+      @target_plugin_hooks.delete(target.name)
+    end
+    private :invalidate_group_cache!
   end
 end

data/lib/bolt/inventory/group2.rb

@@ -142,6 +142,11 @@ module Bolt
         @unresolved_targets[t_name] = target
       end
 
+      def remove_target(target)
+        @resolved_targets.delete(target.name)
+        @unresolved_targets.delete(target.name)
+      end
+
       def add_target(target)
         @resolved_targets[target.name] = { 'name' => target.name }
       end

data/lib/bolt/inventory/inventory2.rb

@@ -136,6 +136,22 @@ module Bolt
       end
       private :expand_targets
 
+      def remove_target(current_group, target, desired_group)
+        if current_group.name == desired_group
+          current_group.remove_target(target)
+          target.invalidate_group_cache!
+        end
+        current_group.groups.each do |child_group|
+          # If target was in current group, remove it from all child groups
+          if current_group.name == desired_group
+            remove_target(child_group, target, child_group.name)
+          else
+            remove_target(child_group, target, desired_group)
+          end
+        end
+      end
+      private :remove_target
+
       def add_target(current_group, target, desired_group)
         if current_group.name == desired_group
           current_group.add_target(target)
@@ -201,6 +217,22 @@ module Bolt
         end
       end
 
+      def remove_from_group(target, desired_group)
+        unless target.length == 1
+          raise ValidationError.new("'remove_from_group' expects a single Target, got #{target.length}", nil)
+        end
+
+        if desired_group == 'all'
+          raise ValidationError.new("Cannot remove Target from Group 'all'", nil)
+        end
+
+        if group_names.include?(desired_group)
+          remove_target(@groups, @targets[target.first.name], desired_group)
+        else
+          raise ValidationError.new("Group #{desired_group} does not exist in inventory", nil)
+        end
+      end
+
       def add_to_group(targets, desired_group)
         if group_names.include?(desired_group)
           targets.each do |target|

data/lib/bolt/pal.rb

@@ -312,8 +312,10 @@ module Bolt
 
       # If it's a Puppet language plan, use strings to extract data. The only
       # way to tell is to check which filename exists in the module.
-      plan_file = plan_name.split('::', 2)[1] || 'init'
-      pp_path = File.join(mod, 'plans', "#{plan_file}.pp")
+      plan_subpath = File.join(plan_name.split('::').drop(1))
+      plan_subpath = 'init' if plan_subpath.empty?
+
+      pp_path = File.join(mod, 'plans', "#{plan_subpath}.pp")
       if File.exist?(pp_path)
         require 'puppet-strings'
         require 'puppet-strings/yard'
@@ -346,7 +348,7 @@ module Bolt
 
       # If it's a YAML plan, fall back to limited data
       else
-        yaml_path = File.join(mod, 'plans', "#{plan_file}.yaml")
+        yaml_path = File.join(mod, 'plans', "#{plan_subpath}.yaml")
         plan_content = File.read(yaml_path)
         plan = Bolt::PAL::YamlPlan::Loader.from_string(plan_name, plan_content, yaml_path)
 

data/lib/bolt/puppetdb/config.rb

@@ -9,19 +9,22 @@ module Bolt
       if !ENV['HOME'].nil?
         DEFAULT_TOKEN = File.expand_path('~/.puppetlabs/token')
         DEFAULT_CONFIG = { user: File.expand_path('~/.puppetlabs/client-tools/puppetdb.conf'),
-                           global: '/etc/puppetlabs/client-tools/puppetdb.conf',
-                           win_global: 'C:/ProgramData/PuppetLabs/client-tools/puppetdb.conf' }.freeze
+                           global: '/etc/puppetlabs/client-tools/puppetdb.conf' }.freeze
       else
         DEFAULT_TOKEN = Bolt::Util.windows? ? 'nul' : '/dev/null'
         DEFAULT_CONFIG = { user: '/etc/puppetlabs/puppet/puppetdb.conf',
-                           global: '/etc/puppetlabs/puppet/puppetdb.conf',
-                           win_global: 'C:/ProgramData/PuppetLabs/client-tools/puppetdb.conf' }.freeze
+                           global: '/etc/puppetlabs/puppet/puppetdb.conf' }.freeze
 
       end
 
+      def self.default_windows_config
+        require 'win32/dir'
+        File.expand_path(File.join(Dir::COMMON_APPDATA, 'PuppetLabs/client-tools/puppetdb.conf'))
+      end
+
       def self.load_config(filename, options, boltdir_path = nil)
         config = {}
-        global_path = Bolt::Util.windows? ? DEFAULT_CONFIG[:win_global] : DEFAULT_CONFIG[:global]
+        global_path = Bolt::Util.windows? ? default_windows_config : DEFAULT_CONFIG[:global]
         if filename
           if File.exist?(filename)
             config = JSON.parse(File.read(filename))

data/lib/bolt/result.rb

@@ -8,9 +8,8 @@ module Bolt
     attr_reader :target, :value, :action, :object
 
     def self.from_exception(target, exception)
-      @exception = exception
-      if @exception.is_a?(Bolt::Error)
-        error = @exception.to_h
+      if exception.is_a?(Bolt::Error)
+        error = exception.to_h
       else
         error = {
           'kind' => 'puppetlabs.tasks/exception-error',

data/lib/bolt/transport/ssh/connection.rb

@@ -34,6 +34,11 @@ module Bolt
           @transport_logger = transport_logger
           @logger.debug("Initializing ssh connection to #{@target.safe_name}")
 
+          @sudo_password = @target.options['sudo-password']
+          # rubocop:disable Style/GlobalVars
+          @sudo_password ||= @target.options['password'] if $future
+          # rubocop:enable Style/GlobalVars
+
           if target.options['private-key']&.instance_of?(String)
             begin
               Bolt::Util.validate_file('ssh key', target.options['private-key'])
@@ -148,8 +153,8 @@ module Bolt
 
         def handled_sudo(channel, data, stdin)
           if data.lines.include?(Sudoable.sudo_prompt)
-            if target.options['sudo-password']
-              channel.send_data("#{target.options['sudo-password']}\n")
+            if @sudo_password
+              channel.send_data("#{@sudo_password}\n")
               channel.wait
               return true
             else

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '1.41.0'
+  VERSION = '1.42.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 1.41.0
+  version: 1.42.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-03 00:00:00.000000000 Z
+date: 2019-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -349,6 +349,7 @@ files:
 - bolt-modules/boltlib/lib/puppet/functions/get_targets.rb
 - bolt-modules/boltlib/lib/puppet/functions/puppetdb_fact.rb
 - bolt-modules/boltlib/lib/puppet/functions/puppetdb_query.rb
+- bolt-modules/boltlib/lib/puppet/functions/remove_from_group.rb
 - bolt-modules/boltlib/lib/puppet/functions/resolve_references.rb
 - bolt-modules/boltlib/lib/puppet/functions/run_command.rb
 - bolt-modules/boltlib/lib/puppet/functions/run_plan.rb