Merge pull request #41 from Financial-Times/notify-for-package-updates

Notify users about package updates

Author: simonplend

README.md

@@ -6,25 +6,36 @@ Human-friendly command line tool for the GitHub API.
 
 ### Command Line Tool
 
+#### Install globally (recommmended)
+
+```shell
+npm install --global @financial-times/github
+
+github --help
 ```
-$ npx @financial-times/github --help
-github <command>
-
-Commands:
-  github project:add-pull-request  Add a pull request to a project
-  github project:create            Create a new project
-  github pull-request:create       Create a new pull request
-
-Options:
-  --token    GitHub personal access token                              [string]
-  --version  Show version number                                       [boolean]
-  --help     Show help                                                 [boolean]
+
+When you run the tool it will automatically notify you if there is a newer
+version of it available for you to update to. This
+[can be disabled](https://www.npmjs.com/package/update-notifier#user-settings)
+if you'd prefer not to be notified about updates.
+
+Note: If you install this tool globally on your machine and then run
+`npx @financial-times/github`, it will use the globally installed version of the
+tool rather than temporarily installing it from the npm registry.
+
+#### No installation
+
+If you just want to try this tool out without installing it, you can run it with
+[`npx`](https://www.npmjs.com/package/npx) e.g.
+
+```shell
+npx @financial-times/github --help
 ```
 
 ### Library
 
 ```
-npm install --save @financial-times/github
+npm install @financial-times/github
 ```
 
 ```javascript
@@ -35,4 +46,4 @@ const github = require("@financial-times/github")({
 
 See [`examples/examples.js`](https://github.com/Financial-Times/github/blob/master/examples/examples.js) for a full set of usage examples.
 
-See [`src/index.js`](https://github.com/Financial-Times/github/blob/master/src/index.js) for all available methods.
+See [`src/lib/github.js`](https://github.com/Financial-Times/github/blob/master/src/lib/github.js) for all available methods.

bin/github.js

@@ -1,8 +1,66 @@
 #!/usr/bin/env node
 
-require("yargs")
-	.commandDir("../src/commands")
+const updateNotifier = require("update-notifier");
+const yargs = require("yargs");
+
+const options = require('../src/lib/helpers/yargs/options');
+
+const yargsCommandsDirectoryPath = "../src/commands";
+
+/**
+ * Configure yargs.
+ *
+ * @see http://yargs.js.org/docs/
+ */
+yargs
+	/**
+	 * Load our yargs command modules from a directory.
+	 *
+	 * @see https://github.com/yargs/yargs/blob/master/docs/advanced.md#commanddirdirectory-opts
+	 */
+	.commandDir(yargsCommandsDirectoryPath)
+	/**
+	 * Always require a command to be specified.
+	 */
 	.demandCommand()
-	.group(['token', 'json'], 'Global Options:')
+	/**
+	 * Group global options in usage output.
+	 */
+	.group(["token", "json"], "Global Options:")
+	.describe("token", options.descriptions.token)
+	.describe("json", options.descriptions.json)
+	/**
+	 * Report unrecognized commands as errors.
+	 */
 	.strict()
-	.help().argv;
+	/**
+	 * Enable the display of help with the `--help` option.
+	 */
+	.help();
+
+/**
+ * Parse command line arguments and handle them.
+ *
+ * Get yargs to parse Node's `process.argv` array and then handle them
+ * e.g. display usage information, run a command module.
+ *
+ * @see https://nodejs.org/dist/latest/docs/api/process.html#process_process_argv
+ */
+yargs.parse();
+
+/**
+ * Display a notification if a newer version of this package is available to install.
+ *
+ * This check for updates to the `@financial-times/github` package
+ * happens asynchronously in a detached child process that runs
+ * independently from the parent CLI process. This ensures that
+ * the check for updates doesn't interfere with the running of the
+ * CLI itself. If an update is available, the user won't be notified
+ * about it until the next time that they run the CLI.
+ *
+ * Note: `update-notifier` checks for updates once a day by default.
+ *
+ * @see https://www.npmjs.com/package/update-notifier
+ */
+const packageJson = require("../package.json");
+updateNotifier({ pkg: packageJson }).notify();

package.json

@@ -21,6 +21,7 @@
   "dependencies": {
     "@octokit/rest": "^16.16.3",
     "lodash.flow": "^3.5.0",
+    "update-notifier": "^2.5.0",
     "yargs": "^13.2.1"
   },
   "devDependencies": {

src/lib/helpers/yargs/options.js

@@ -1,9 +1,14 @@
 /* eslint-disable no-console */
 
+const descriptions = {
+	token:
+		"GitHub personal access token (uses `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable by default). Generate one at https://github.com/settings/tokens.",
+	json: "Format command output as JSON string"
+};
+
 const withToken = yargs => {
 	return yargs.option("token", {
-		describe:
-			"GitHub personal access token (uses `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable by default). Generate one at https://github.com/settings/tokens.",
+		describe: descriptions.token,
 		type: "string",
 		// IMPORTANT: We use a function here so the token is not output on the command line
 		default: () => process.env.GITHUB_PERSONAL_ACCESS_TOKEN,
@@ -20,9 +25,13 @@ const withToken = yargs => {
 
 const withJson = yargs => {
 	return yargs.option("json", {
-		describe: "Format command output as JSON string",
+		describe: descriptions.json,
 		type: "boolean"
 	});
 };
 
-module.exports = { withToken, withJson };
+module.exports = {
+	descriptions,
+	withToken,
+	withJson
+};