Show help in a consistent manner

Ensure help works consistently.

If help is visible anywhere in the command as --help, -h, or help
this will treat it as the 'help' flag and ensure that the lowest
level subcommand (before the 'help' word was encountered) is the one
that renders help.

Version has been moved to its own command, but we have retained a '-v'
flag for easy-of-use.

components/chef-workstation/i18n/en.yml

@@ -1,61 +1,88 @@
 # Shared and top-level CLI output text.
 cli:
   # CLI option, banner, and usage text
-  banner: |
-    Congratulations! You are using chef: your gateway
-    to managing everything from a single node to an entire Chef
-    infrastructure.
-
-    USAGE:
-      chef [SUBCOMMAND]
   aborted: Canceling request due to interrupt.
-  alias_for: "Alias for: "
-  aliases: "ALIASES:"
   config: Location of config file. Defaults to %1
   creating_config: "Creating config file in %1."
-  help: "Show usage information"
-  print_version: "Chef Workstation Version: %1\n\n"
-  short_banner: "Usage:  chef COMMAND [options...]"
   subcommands: "SUBCOMMANDS:"
   target: ""
-  version: "Show the current version of this tool"
-  version_msg: "Version %1"
 
 # Text specific to each command
 commands:
+  base:
+    version: "Show the current version of this tool"
+    version_for_help: "Chef Workstation Version: %1\n\n"
+    description: |
+      Congratulations! You are using chef: your gateway
+      to managing everything from a single node to an entire Chef
+      infrastructure.
+
+    usage: chef COMMAND [options...]
+
+    usage_full: |
+      chef COMMAND [options...]
+
+    status:
+      connecting: "Connecting..."
+      connected: "Connected."
+      connection_failed: "Connection failed: %1"
+
+    help: "Show usage information"
+    alias_for: "Alias for: "
+    aliases: "ALIASES:"
+    usage_msg: "USAGE: "
+
+  help:
+    description: Show help and usage for 'chef' or a given subcommand.
+    usage: cheff <help|-h|--help> [COMMAND_OR_ALIAS]
+    usage_full: |
+      chef <help|-h|--help>
+      chef <help|-h|--help> [COMMAND_OR_ALIAS]
+      chef <COMMAND_OR_ALIAS> <help|-h|--help>
+
+  version:
+    description: Show the current version of Chef Workstation.
+    usage: chef <version|-v|--version>
+    usage_full: chef <version|-v|--version>
+
   config:
     description: Manage Chef Workstation configuration
-    usage: |
-      USAGE:
-        chef config [SUBCOMMAND]
+    usage: chef config [SUBCOMMAND] [FLAGS]
+    usage_full: chef config [SUBCOMMAND] [FLAGS]
     show:
       description: Echo out Chef Workstation configuration to stdout
-      usage: |
-        USAGE:
-          chef config show [FLAGS]
+      usage: chef config show [FLAGS]
+      usage_full: chef config show [FLAGS]
       source: "Config loaded from %1path %2."
+
   target:
-    description: Manage a target
-    usage: |
-      USAGE:
-        chef target [SUBCOMMAND]
+    description: Manage a target node or device.
+    usage: chef target [SUBCOMMAND] [FLAGS]
+    usage_full: chef target [SUBCOMMAND] [FLAGS]
+
     converge:
-      description: Converge a target
+      description: Apply a change to a target node.
+
       usage: |
-        USAGE:
-          chef target converge <TARGET> <RESOURCE> <RESOURCE_NAME> [PROPERTIES] [FLAGS]
-            Converge the specified <TARGET> with the single <RESOURCE>. [PROPERTIES]
-            should be specified as key=value. EG:
+        chef target converge <TARGET> <RESOURCE> <RESOURCE_NAME> [PROPERTIES] [FLAGS]
+
+      usage_full: |
+        chef target converge <TARGET> <RESOURCE> <RESOURCE_NAME> [PROPERTIES] [FLAGS]
 
-            chef target converge myec2node directory /tmp/test mode="0777" action=create
+          Converge the specified <TARGET> with the single <RESOURCE>.
+          [PROPERTIES] should be specified as key=value. For example:
 
-          chef target converge <TARGET> <RECIPE> [FLAGS]
-            Converge the specified <TARGET> with the single recipe located at
-            <RECIPE>.
+            chef target converge myec2node directory \
+                                 /tmp/test mode="0777" action=create
+
+        chef target converge <TARGET> <RECIPE> [FLAGS]
+
+          Converge the specified <TARGET> with the single recipe located at
+          <RECIPE>. For example:
 
             chef target converge myec2node path/to/cookbook/recipe.rb
 
-        ARGS:
+        ARGUMENTS:
           <TARGET>          The host or IP address to converge. Can also be an SSH or WinRM URL
                             in the form:
 
@@ -66,6 +93,7 @@ commands:
                             the name of the user you wanted to create.
           <RECIPE>          The recipe to converge. This can be provided as one of:
                             1. Full path to a recipe file
+
       root_description: "Whether to use root permissions on the target. Defaults to true."
       identity_file: "SSH identity file to use when connecting."
       ssl:
@@ -75,15 +103,11 @@ commands:
           Use --ssl-no-verify when using SSL for WinRM and
           the remote host is using a self-signed certificate.
           Current default: %1
-  base:
-    status:
-      connecting: "Connecting..."
-      connected: "Connected."
-      connection_failed: "Connection failed: %1"
+
 
 # Status updates shared across commands.
 status:
-  install:
+  install_chef:
     installing: Installing Chef client.
     downloading: Downloading Chef client installer.
     uploading: Uploading Chef client installer.

components/chef-workstation/lib/chef-workstation/builtin_commands.rb

@@ -1,4 +1,3 @@
-#
 # Copyright:: Copyright (c) 2018 Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
@@ -13,7 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-#
+
 require "chef-workstation/commands_map"
 require "chef-workstation/text"
 
@@ -28,4 +27,25 @@
   c.top_level("config", :Config, text.config, "chef-workstation/command/config", subcommands: [
     c.create("show", [:Config, :Show], text.config.show, "chef-workstation/command/config/show"),
   ])
+  # TODO - Can we implement this allow us to specify
+  #        relative ordering? 'help' and 'version' should
+  #        always be last.
+
+  # This exists so that 'help' shows as a subcommand.
+  # Help is a function of a command, so we convert the subcommand 'help' to the appropriate
+  # flag when we encounter it and pass it into the actual command that the
+  # customer wants to execute. It is never instantiated.
+  c.top_level("help", nil, text.base, nil)
+
+  # Version works inversely - if someone specifies '-v' we will swap that out
+  # to use the Version command.
+  c.top_level("version", :Version, text.base, "chef-workstation/command/version")
+
+  # This is our root command 'chef'. Giving it all top-level subcommands (which will
+  # exclude this hidden one at time of evaluation) means that 'chef help' will be able to show
+  # the subcommands.
+  #
+  # TODO: In another pass, let's get rid of 'hidden-root' and make CommandMap support a root node.
+  c.top_level("hidden-root", :Base, text.base, "chef-workstation/command/base",
+              hidden: true, subcommands: c.command_specs.values)
 end