docs: Add descriptions to --help

Related to #135
PR-URL: #136

commands/config.js

@@ -136,15 +136,24 @@ function printHelp () {
   helpHeader(
     'config',
     chalk`ncm {${COLORS.yellow} config} {${COLORS.teal} <action>}`,
-    'ncm config <action>'
+    'ncm config <action>',
+    `
+Adjust ncm-cli configuration and local storage.
+    `
   )
 
-  L(optionsList())
+  L(extendedOptionsList())
   L()
 }
 
 function optionsList () {
   return chalk`
+{${COLORS.light1} ncm} {${COLORS.yellow} config <action>} {${COLORS.teal} <key> <value>}
+  `.trim()
+}
+
+function extendedOptionsList () {
+  return chalk`
 {${COLORS.light1} ncm} {${COLORS.yellow} config list}
 {${COLORS.light1} ncm} {${COLORS.yellow} config reset}
 {${COLORS.light1} ncm} {${COLORS.yellow} config del} {${COLORS.teal} <key>}

commands/details.js

@@ -164,8 +164,13 @@ async function details (argv, arg1, arg2, arg3) {
 function printHelp () {
   helpHeader(
     'details',
-    chalk`ncm {${COLORS.yellow} details} {${COLORS.teal} <module\{@version\}> [options]}`,
-    'ncm details <module{@version}> [options]'
+    chalk`{${COLORS.light1} ncm} {${COLORS.yellow} details} {${COLORS.teal} <module\{@version\}> [options]}`,
+    'ncm details <module{@version}> [options]',
+    chalk`
+Returns a detailed report about a specific module version.
+
+Defaults to using the {${COLORS.teal} "latest"} version as published to npm if no {${COLORS.teal} "version"} is provided.
+    `
   )
 
   L(optionsList())
@@ -174,8 +179,7 @@ function printHelp () {
 
 function optionsList () {
   return chalk`
-{${COLORS.light1} ncm} {${COLORS.yellow} details} {${COLORS.teal} <module>}
-{${COLORS.light1} ncm} {${COLORS.yellow} details} {${COLORS.teal} <module@version>}
+{${COLORS.light1} ncm} {${COLORS.yellow} details} {${COLORS.teal} <module\{@version\}>}
   {${COLORS.teal} -d, --dir} {white Directory to check for dependency path}
   `.trim()
 }

commands/install.js

@@ -77,8 +77,14 @@ async function install (argv, arg1, arg2, arg3) {
 function printHelp () {
   helpHeader(
     'install',
-    chalk`ncm {${COLORS.yellow} install} {${COLORS.teal} <module\{@version\}> [options] [npm options]}`,
-    'ncm install <module{@version}> [options] [npm options]'
+    chalk`{${COLORS.light1} ncm} {${COLORS.yellow} install} {${COLORS.teal} <module\{@version\}> [options] [npm options]}`,
+    'ncm install <module{@version}> [options] [npm options]',
+    chalk`
+Runs and displays {${COLORS.light1} "ncm details <module\{@version\}>"} with an interactive confirmation prompt.
+If confirmed, attempts to run {${COLORS.light1} "npm install <module\{@version\}>"} with any additional options provided.
+
+{italic The config keys {${COLORS.yellow} installBin} and {${COLORS.yellow} installCmd} can adjust this to work with other package installers if necessary.}
+    `
   )
 
   L(optionsList())
@@ -87,8 +93,7 @@ function printHelp () {
 
 function optionsList () {
   return chalk`
-{${COLORS.light1} ncm} {${COLORS.yellow} install} {${COLORS.teal} <module> [npm options]}
-{${COLORS.light1} ncm} {${COLORS.yellow} install} {${COLORS.teal} <module@version> [npm options]}
+{${COLORS.light1} ncm} {${COLORS.yellow} install} {${COLORS.teal} <module\{@version\}> [npm options]}
 {${COLORS.light1} ncm} {${COLORS.yellow} i} {${COLORS.teal} <module\{@version\}> [npm options]}
   {${COLORS.teal} -d, --dir} {white Directory to check for dependency path}
   `.trim()

commands/orgs.js

@@ -123,8 +123,16 @@ async function orgsCli (details, org) {
 function printHelp () {
   helpHeader(
     'orgs',
-    chalk`ncm {${COLORS.yellow} orgs} {${COLORS.teal} [<orgname>] [options]}`,
-    'ncm orgs [<orgname>] [options]'
+    chalk`{${COLORS.light1} ncm} {${COLORS.yellow} orgs} {${COLORS.teal} [<orgname>] [options]}`,
+    'ncm orgs [<orgname>] [options]',
+    chalk`
+Change your active NodeSource organization, which impacts the whitelist.
+Defaults to an interactive prompt.
+
+By passing an {${COLORS.teal} <orgname>}, the interactive part may be skipped.
+
+Input is {italic case sensitive}.
+    `
   )
 
   L(optionsList())

commands/report.js

@@ -154,8 +154,17 @@ async function report (argv, _dir) {
 function printHelp () {
   helpHeader(
     'report',
-    chalk`ncm {${COLORS.yellow} report} {${COLORS.teal} [<directory>] [options]}`,
-    'ncm report [<directory>] [options]'
+    chalk`{${COLORS.light1} ncm} {${COLORS.yellow} report} {${COLORS.teal} [<directory>] [options]}`,
+    'ncm report [<directory>] [options]',
+    chalk`
+Generates a project-wide report of directory risk and quality of installed or specified packages.
+The top five riskiest modules detected will be displayed alongside a concise project report.
+
+A report with a list of all modules can be generated by passing {${COLORS.teal} --long}.
+
+Reports may be filtered based on any of the following flags:
+  {${COLORS.teal} --compliance}, {${COLORS.teal} --security}
+    `
   )
 
   L(optionsList())
@@ -167,10 +176,8 @@ function optionsList () {
 {${COLORS.light1} ncm} {${COLORS.yellow} report}
 {${COLORS.light1} ncm} {${COLORS.yellow} report} {${COLORS.teal} <directory>}
   {${COLORS.teal} -d, --dir}               {white Another way to specify <directory>}
-  {${COLORS.teal} -l, --long}              {white Expanded output with module list}
-  {${COLORS.teal} -c --compliance}         {white Expanded output with compliance failures}
-  {${COLORS.teal} -s --security}           {white Expanded output with security failures}
-  {${COLORS.teal} --filter=<value>}        {white Expanded output with filtered module list}
-                            {white filters can be "critical", "high", "medium" or "low"}
+  {${COLORS.teal} -l, --long}              {white Full module list output}
+  {${COLORS.teal} -c --compliance}         {white Compliance failures only output}
+  {${COLORS.teal} -s --security}           {white Security failures only output}
   `.trim()
 }

commands/signin.js

@@ -141,8 +141,15 @@ async function signin (argv, email, password) {
 function printHelp () {
   helpHeader(
     'signin',
-    chalk`ncm {${COLORS.yellow} signin} {${COLORS.teal} [options]}`,
-    'ncm signin [options]'
+    chalk`{${COLORS.light1} ncm} {${COLORS.yellow} signin} {${COLORS.teal} [options]}`,
+    'ncm signin [options]',
+    chalk`
+Sign-in interactively using your NodeSource account email and password.
+Alternatively, sign-in via single-sign-on by specifiying an option.
+
+For more information on organization selection, see {${COLORS.light1} "ncm orgs --help"}.
+See the readme for information on authentication via CI tokens.
+    `
   )
 
   L(optionsList())

commands/signout.js

@@ -21,8 +21,12 @@ async function signout (argv) {
 function printHelp () {
   helpHeader(
     'signout',
-    chalk`ncm {${COLORS.yellow} signout}`,
-    'ncm signout'
+    chalk`{${COLORS.light1} ncm} {${COLORS.yellow} signout}`,
+    'ncm signout',
+    `
+Sign out.
+Has no impact on CI token usage.
+    `
   )
 
   L(optionsList())

commands/whitelist.js

@@ -312,8 +312,13 @@ const queries = {
 function printHelp () {
   helpHeader(
     'whitelist',
-    chalk`ncm {${COLORS.yellow} whitelist} {${COLORS.teal} <option>}`,
-    'ncm whitelist [option]'
+    chalk`{${COLORS.light1} ncm} {${COLORS.yellow} whitelist} {${COLORS.teal} <option>}`,
+    'ncm whitelist [option]',
+    `
+Display or modify your NodeSource organization’s module whitelist.
+
+Public modules are listed alongside their risk score, license compliance, and security summary.
+    `
   )
 
   L(optionsList())

lib/help.js

@@ -10,10 +10,10 @@ module.exports = {
   helpHeader
 }
 
-function helpHeader (cmd, usage, usageRaw) {
+function helpHeader (cmd, usage, usageRaw, description) {
   L()
   L(header(`NCM CLI Help: ncm ${cmd}`))
-  L()
+  description ? L(description) : L()
   L('Usage:')
   L(rawBox(usage, usageRaw.length || usage.length))
   L()