feat(xt-sync): change command to prompt with options; update relevant docs

Author: nkrusch

cli/xt-sync.js

@@ -8,7 +8,7 @@
  * @description
  *
  * ```text
- * xt-sync [--gitignore] [--eslint] [--gitlab] [--travis] [--all]
+ * xt-sync
  * ```
  *
  * The purpose of this command is to upgrade configuration files of
@@ -19,42 +19,53 @@
  */
 
 const path = require('path');
+const prompts = require('prompts');
 const program = require('commander');
 const pkg = require('../package.json');
 const texts = require('../config/texts').xtSync;
 const Utilities = require('./utilities').Utilities;
 
+// list available options
 const files = {
-    gitlab: {path: '../config/gitlab.yml', out: '.gitlab-ci.yml'},
-    travis: {path: '../config/travis.yml', out: '.travis.yml'},
-    eslint: {path: '../config/eslint.json', out: '.eslintrc'},
-    gitignore: {path: '../config/ignore', out: '.gitignore'}
+    gitlab: {title: texts.argLint, path: '../config/gitlab.yml', out: '.gitlab-ci.yml'},
+    travis: {title: texts.argGitlab, path: '../config/travis.yml', out: '.travis.yml'},
+    eslint: {title: texts.argTravis, path: '../config/eslint.json', out: '.eslintrc'},
+    gitignore: {title: texts.gitignore, path: '../config/ignore', out: '.gitignore'}
 };
 
+// generate the options to display to user
+const options = [{
+    type: 'multiselect',
+    name: 'options',
+    message: texts.instructions,
+    choices: Object.entries(files).map(
+        ([key, value]) => (
+            {title: value.title, value: key}
+        ))
+}];
+
 program
+    .name('xt-sync')
+    .option('-a --all', 'deprecated: call xt-sync without flags')
     .version(pkg.version)
-    .option('-l --gitlab', texts.argGitlab)
-    .option('-t --travis', texts.argTravis)
-    .option('-e --eslint', texts.argLint)
-    .option('-g --gitignore', texts.argGitIgnore)
-    .option('-a --all', texts.argAll)
     .parse(process.argv);
 
-let counter = 0;
+(async () => {
 
-const options = program.opts();
+    const onCancel = () => process.exit(0)
+    // noinspection JSUnresolvedVariable
+    const response = (await prompts(options, {onCancel})).options;
 
-Object.keys(files).map(opt => {
-    if (options[opt] !== undefined || options.all) {
-        const relativePath = path.resolve(__dirname, files[opt].path);
-        const outputFileName = files[opt].out;
-        const content = Utilities.readFile(relativePath, 'utf8');
-        const outPath = path.join(process.cwd(), outputFileName);
+    // copy selected options from config -> project
+    Object.entries(files).map(([key, value]) => {
 
-        Utilities.writeFile(outPath, content);
-        console.log(texts.updateSuccess(outputFileName));
-        counter++;
-    }
-});
+        if (response.indexOf(key) > -1) {
+            const relativePath = path.resolve(__dirname, value.path);
+            const content = Utilities.readFile(relativePath);
+            const outPath = path.join(process.cwd(), value.out);
 
-if (!counter) console.log(texts.onError);
+            Utilities.writeFile(outPath, content);
+            console.log(texts.updateSuccess(value.out));
+        }
+    });
+})();

config/init/package.json

@@ -16,7 +16,7 @@
     "clean": "xt-clean",
     "docs": "xt-docs",
     "test": "xt-test",
-    "sync": "xt-sync --all"
+    "sync": "xt-sync"
   },
   "babel": {
     "presets": [

config/texts.js

@@ -55,20 +55,15 @@ exports.xtCreate = {
  */
 exports.xtSync = {
 
-    argGitlab: 'sync gitlab-ci.yml',
+    argGitlab: 'gitlab CI config',
 
-    argTravis: 'sync travis.yml',
+    argTravis: 'travis CI config',
 
-    argLint: 'sync eslint',
+    argLint: 'eslint config',
 
-    argGitIgnore: 'sync gitignore',
+    argGitIgnore: 'gitignore',
 
-    argAll: 'sync everything',
-
-    onError: (
-        chalk.red('Specify which files to sync using flags.\n' +
-            'See --help for more details.')
-    ),
+    instructions: 'choose the files you want to sync:',
 
     updateSuccess: (what) => (
         chalk.bold.green(`✓ updated ${what}`)

guide/06-xt-sync.md

@@ -3,76 +3,53 @@
 
 * * *
 
-<p class='page-intro'><code>xt-sync</code> command is intended for upgrading configuration files of
-a stale project to the latest versions</p>
+<p class='page-intro'><code>xt-sync</code> is intended for copying and updating 
+configuration files.</p>
 
 * * *
 
-When a project has not been worked on recently, it may need updates of 
-various files, such as CI configuration files. 
+When adding more features to an extension project, it may be helpful
+to not start from scratch. `xt-sync` command enables extension projects
+to pull in starter configuration files for the purposes of linting, 
+setting up automated CI builds, and for setting up git VCS.
 
-The purpose of this command is to make that update process simple by
-allowing each project to choose which configuration files to update.
-The CLI will then supply the project with the most recent configuration
-files.
+The configuration files are intended as a starting point. If you
+end up modifying them heavily at a project level, you should continue
+to maintain them manually instead of using this command.
 
-**Note:** If the configuration files have been modified heavily for 
-an individual project, it is not advisable to upgrade them in this manner. 
-Instead you should upgrade such configuration files manually.
+If you do not modify these configuration files, you can sync the 
+latest version periodically, to update to the latest version supplied
+by this CLI.
 
 ## Commands
 
-Braces `{ }` indicate that the user must choose one (and only one) of the items inside the braces.
+**Sync configuration files**
 
-You must pass at least one flag with this command.
-
-
-**Synchronize all configuration files**
+This command will guide you through the available options. 
 
 ```bash
-xt-sync {-a|--all}
+xt-sync
 ```
 
-**Synchronize ESLint configuration file**
-
-```bash
-xt-sync {-e|--eslint}
-```
 
-**Synchronize Gitlab CI configuration file**
+## Package.json scripts
 
+After installing extension-cli, you can run these commands from a terminal by calling
+ 
 ```bash
-xt-sync {-l|--gitlab}
+npx xt-sync
 ```
 
-**Synchronize Travis CI configuration file**
-
-```bash
-xt-sync {-t|--travis}
-``` 
-
-**Synchronize .gitignore file**
-
-```bash
-xt-sync {-g|--gitignore}
-``` 
-
-**Get help using this command**
-
-```bash
-xt-sync --help
-``` 
-
-## Package.json scripts
-
-After installing extension-cli, you can run these commands from a terminal using `npx xt-sync --all`.
- 
-Or you can add an option to `packages.json` scripts section and then execute the command as `npm run sync`.
-See example below.
+Alternatively you can add an option to `packages.json` scripts section as shown below
 
 ```json
-"scripts":{
-  "sync": "xt-sync --all"
+"scripts" : {
+  "sync": "xt-sync"
 }
 ```
 
+and then execute the command by running 
+
+```bash
+npm run sync
+```