helpful-cli - npm Package Compare versions

Comparing version 1.0.8 to 2.0.0-alpha

package.json

 {
   "name": "helpful-cli",
-  "version": "1.0.8",
-  "description": "Command line utility for the Helpful Human team.",
-  "main": "index.js",
+  "version": "2.0.0-alpha",
+  "description": "Command line utility for custom project scaffolding.",
+  "main": "./dist/index.js",
   "scripts": {
-    "test": "mocha"
+    "preversion": "npm test",
+    "version": "npm run build",
+    "postversion": "git push origin master && git push origin master --tags",
+    "clean": "rimraf dist",
+    "build": "rollup -c",
+    "watch": "npm run build -- --watch",
+    "test": "mocha",
+    "tdd": "npm run test -- --watch",
+    "prepublish": "npm run clean && npm run build"
   },
   "bin": {
-    "helpful": "./index.js"
+    "helpme": "./bin/index.js"
   },
@@ -20,5 +28,6 @@ "repository": {
     "tool",
-    "cli"
+    "cli",
+    "scaffolding"
   ],
-  "author": "Nick Glenn <[e-mail]>",
+  "author": "Helpful Human <[e-mail]>",
   "license": "MIT",
@@ -33,5 +42,7 @@ "bugs": {
     "commander": "^2.9.0",
+    "figures": "^2.0.0",
     "fs-extra": "^0.30.0",
-    "glob": "^7.1.0",
+    "glob": "^7.1.1",
     "inquirer": "^1.2.1",
+    "is-glob": "^3.1.0",
     "lodash": "^4.16.3",
@@ -41,4 +52,18 @@ "minimatch": "^3.0.3",
     "ramda": "^0.22.1",
-    "shelljs": "^0.7.4"
+    "request": "^2.79.0",
+    "shelljs": "^0.7.4",
+    "shortid": "^2.2.6",
+    "unzip": "^0.1.11",
+    "yamljs": "^0.2.8"
+  },
+  "devDependencies": {
+    "chai": "^3.5.0",
+    "mocha": "^3.2.0",
+    "rimraf": "^2.5.4",
+    "rollup": "^0.41.4",
+    "rollup-plugin-buble": "^0.15.0",
+    "rollup-plugin-commonjs": "^7.0.0",
+    "rollup-watch": "^3.2.2",
+    "sinon": "^1.17.7"
   }
 }

README.md

 # Helpful CLI
 
-Command line utility belt for Helpful Human employees.  This project is a work in progress and currently only supports a single command for scaffolding projects.
+**tl; dr** "Templatize Anything"
 
+> This tool is currently undergoing a massive rewrite.  You can still use the original version of this tool by installing it via `npm`, or review its source on the `v1` branch.
+
+Helpful CLI is a command line utility for quickly scaffolding new projects, or add files to existing projects, using remote templates.  It's kind of like a `Makefile`, but on steroids. Templates must contain a `helpful` manifest file in JSON, CommonJS or YAML format.
+
+## Installation
+
+Helpful CLI is written using [NodeJS](https://www.nodejs.org/) and is currently only available via `npm`.  Run the following `npm` command to install.  Once installed, you can access Helpful CLI using the `helpme` command in your terminal of choice.
+
+```
+npm install -g helpful-cli
+```
+
 ## Usage
 
-Install the tool with `npm install -g helpful-cli`, then run the `helpful init` command in the folder where you wish to house your project.  Then just walk through the wizard to create your new project.
+1. Find a repository that contains a `helpful.json`, `helpful.js` or `helpful.yml` manifest file.
+1. Change to a local directory that you would like to unpack the template into.
+1. Run `helpme install <template_url>` to start the installer.
+1. Follow the instructions in the prompt.
+
+**Or...**
+
+```
+mkdir Example
+cd Example
+helpme install helpfulhuman/cli-example
+```
+
+## Creating Templates
+
+Helpful CLI can be used with just about any codebase, existing or otherwise.  There are 2 requirements for creating a Helpful CLI compliant package.
+
+1. A properly constructed and formatted [manifest file](#the-helpful-manifest-file).
+1. Your template must be hosted by a [supported remote type](#supported-remotes).
+
+## The `helpful` Manifest File
+
+The `helpful` manifest file is a JSON, CommonJS or YAML file that provides a list of instructions to the Helpful CLI tool.  The format of this file can be summed up as **"ask, copy, run"**.  The basic template for a manifest file looks like this...
+
+#### JSON
+
+```json
+{
+  "ask": [],
+  "copy": [],
+  "run": []
+}
+```
+
+#### CommonJS
+
+> This format allows you to use all the NodeJS runtime has to offer and can be useful for greater control when handling conditionals based on user input.
+
+```js
+module.exports = {
+  ask: [],
+  copy: [],
+  run: []
+};
+```
+
+#### YAML
+
+```yml
+ask:
+copy:
+run:
+```
+
+### Ask
+
+The `ask` portion of your manifest file contains a list of "question" objects.  These objects are used to create terminal prompts that will collect configuration choices from your template's user.  This input will allow you to alter Helpful CLI's behaviour when copying files and running scripts.
+
+Helpful CLI currently uses [inquirer](https://github.com/SBoudrias/Inquirer.js/) under the hood and fully supports its question object API.  We're only covering the basics here, so feel free to look at their documentation for more info.
+
+#### Question Object (Basics)
+
+Name | Type | Description
+-----|------|------------
+**type** | `String` | Defaults to `input`. The type of question prompt presented to the user.  Possible options include `input`, `confirm`, `list`, and `checkbox`.
+**name** | `String` | Required.  The variable name that will store the captured user input.
+**message** | `String` | Required.  The message that will be displayed to the user.
+**default** | `Mixed` | Default value(s) to use if nothing is entered.
+**choices** | `Array` | Required with `list` and `checkbox`.  Values can be simple strings, or objects containing a `name` (to display in list), a `value` (to save in the answers hash) and a `short` (to display after selection) properties.
+
+#### Example
+
+```json
+{
+  "ask": [
+    {
+      "name": "projectName",
+      "message": "What is the name of your project?"
+    },
+    {
+      "type": "list",
+      "name": "deployTarget",
+      "message": "What is your project's target deployment environment?",
+      "choices": [ "AWS", "Docker", "Heroku" ]
+    }
+  ]
+}
+```
+
+### Copy
+
+The `copy` property is an array containing "copy operation" objects.  This tells Helpful CLI what to copy from the template to the target directory.  All file locations are relative to where the manifest file is.
+
+It's worth noting that every file that is copied is also run through the [Nunjucks](https://mozilla.github.io/nunjucks/) templating engine.  This allows you to customize templates with the user input you collected in the `ask` step.  For more information, check out the [Nunjucks templating docs](https://mozilla.github.io/nunjucks/templating.html).
+
+#### Copy Operation Object
+
+Name | Type | Description
+-----|------|------------
+**path** | `String` | Required. Can be a path to a file, folder or a [glob](https://github.com/isaacs/node-glob).
+**exclude** | `String|Array` | An optional pattern or an array of glob patterns to exclude matches.
+**overwrite** | `Boolean` | Defaults to `false`.  When true, the copy operation will replace any existing folders at the file's destination with the new one.  _Use this wisely!_
+**renameFile** | `String` | Allows you to rename a file to the set string.  Useful for copying over files like `_gitignore` as `.gitgnore`.  _Do not use with glob patterns or directories!_
+**renameDir** | `String` | Optionally change the directory that the file(s) will be copied to, relative to the target directory's root.
+**when** | `String|Function` | Will only copy the file(s) when the result is `true`.  See [Using `when` Strings](#using-when-strings) for more information on `String` usage.
+
+#### Example
+
+```json
+{
+  "copy": [
+    {
+      "path": "package.json"
+    },
+    {
+      "path": "_gitignore",
+      "renameFile": ".gitignore"
+    },
+    {
+      "path": "src/**/*.js",
+      "overwrite": true
+    }
+  ]
+}
+```
+
+### Run
+
+Finally, the `run` field is an array of "command objects".  These objects represent shell commands that can be run in the target directory.  Like the template files in the `copy` step, each command is run through the [Nunjucks](https://mozilla.github.io/nunjucks/) templating engine.  This allows you to customize your commands with the input collected in the `ask` step.
+
+#### Command Object
+
+Name | Type | Description
+-----|------|------------
+**cmd** | `String` | Required. The shell command to run.  Will be parsed by Nunjucks.
+**when** | `String|Function` | Will only run the command when the result is `true`.  See [Using `when` Strings](#using-when-strings) for more information on `String` usage.
+
+#### Example
+
+```json
+{
+  "ask": [
+    {
+      "type": "checkbox",
+      "name": "libs",
+      "message": "Would you like to install any of these libraries?",
+      "choices": ["lodash", "jquery", "rx"]
+    }
+  ],
+  "run": [
+    {
+      "cmd": "npm install -S {{ libs | join(' ') }}",
+      "when": "libs.length > 0"
+    }
+  ]
+}
+```
+
+### Final Message on Success
+
+It's not unlikely that you'll want to include a closing message upon successful installation of your template.  You can do this using an object for a `done` property.  The done property contains only a "Done object", which is outlined below.
+
+#### Done Object
+
+Name | Type | Description
+-----|------|------------
+**message** | `String` | Required. The message will be output as the final statement upon successful installation of a template.  Will be parsed by Nunjucks.
+**when** | `String|Function` | Will only run the command when the result is `true`.  See [Using `when` Strings](#using-when-strings) for more information on `String` usage.
+
+#### Example
+
+```json
+{
+  "done": {
+    "message": "Run `npm start` to see your application"
+  }
+}
+```
+
+### Using `when` Strings
+
+Doing any kind of circumstancial or dynamic checking with static files like JSON or YAML is difficult.  To circumvent this limitation, we've implemented the `when` property for `copy` and `run` objects.  This property can take a string as an alternative that will be treated as a JS expression that only has access to user input (from the `ask` step).
+
+Here's a quick sample of how it can be used.
+
+```json
+{
+  "ask": [
+    {
+      "type": "confirm",
+      "name": "createReadme",
+      "message": "Would you like to add a README file?"
+    }
+  ],
+  "copy": [
+    {
+      "path": "README.md",
+      "overwrite": true,
+      "when": "createReadme == true"
+    }
+  ]
+}
+```
+
+## Supported Remotes
+
+These are the remotes _currently_ supported by Helpful CLI.
+
+#### Public GitHub repositories
+
+GitHub is probably the easiest way to host your template.  You can download a GitHub hosted template using either of of the following methods.
+
+```
+helpme install username/repository
+helpme install github.com/username/repository
+```
+
+#### Publicly accessible `.zip` files
+
+You can host a `.zip` template anywhere you like, but you need to make sure that the full URL (with a `.zip` extensions) is provided in order to download.
+
+```
+helpme install http://mydomain.com/files/my-template.zip
+```
+
+#### Planned Remote Support
+
+* GitHub (private)
+* BitBucket (public and private)
+* GitLab (public and private)
+* `.zip` files (authenticated)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Debug access

Supply chain risk

Uses debug, reflection and dynamic code execution features.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 4 instances in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

37092

increased by5.03%

Number of lines in readme file

249

increased by3457.14%

Number of low supply chain risk alerts

3

decreased by-72.73%

Worsened metrics

Dependency count

17

increased by54.55%

Dev dependency count

8

increased byInfinity%

Number of package files

9

decreased by-85%

Lines of code

849

decreased by-16.27%

Number of low quality alerts

1

increased byInfinity%

Dependency changes

• + Addedfigures@^2.0.0

• + Addedis-glob@^3.1.0

• + Addedrequest@^2.79.0

• + Addedshortid@^2.2.6

• + Addedunzip@^0.1.11

• + Addedyamljs@^0.2.8

• + Addedajv@6.12.6(transitive)

• + Addedargparse@1.0.10(transitive)

• + Addedasn1@0.2.6(transitive)

• + Addedassert-plus@1.0.0(transitive)

• + Addedasynckit@0.4.0(transitive)

• + Addedaws-sign2@0.7.0(transitive)

• + Addedaws4@1.13.2(transitive)

• + Addedbcrypt-pbkdf@1.0.2(transitive)

• + Addedbinary@0.3.0(transitive)

• + Addedbuffers@0.1.1(transitive)

• + Addedcaseless@0.12.0(transitive)

• + Addedchainsaw@0.1.0(transitive)

• + Addedcombined-stream@1.0.8(transitive)

• + Addedcore-util-is@1.0.2(transitive)

• + Addeddashdash@1.14.1(transitive)

• + Addeddelayed-stream@1.0.0(transitive)

• + Addedecc-jsbn@0.1.2(transitive)

• + Addedextsprintf@1.3.0(transitive)

• + Addedfast-deep-equal@3.1.3(transitive)

• + Addedfast-json-stable-stringify@2.1.0(transitive)

• + Addedfigures@2.0.0(transitive)

• + Addedforever-agent@0.6.1(transitive)

• + Addedform-data@2.3.3(transitive)

• + Addedfstream@0.1.31(transitive)

• + Addedgetpass@0.1.7(transitive)

• + Addedgraceful-fs@3.0.12(transitive)

• + Addedhar-schema@2.0.0(transitive)

• + Addedhar-validator@5.1.5(transitive)

• + Addedhttp-signature@1.2.0(transitive)

• + Addedis-extglob@2.1.1(transitive)

• + Addedis-glob@3.1.0(transitive)

• + Addedis-typedarray@1.0.0(transitive)

• + Addedisarray@0.0.1(transitive)

• + Addedisstream@0.1.2(transitive)

• + Addedjsbn@0.1.1(transitive)

• + Addedjson-schema@0.4.0(transitive)

• + Addedjson-schema-traverse@0.4.1(transitive)

• + Addedjson-stringify-safe@5.0.1(transitive)

• + Addedjsprim@1.4.2(transitive)

• + Addedmatch-stream@0.0.2(transitive)

• + Addedmime-db@1.52.0(transitive)

• + Addedmime-types@2.1.35(transitive)

• + Addedminimist@1.2.8(transitive)

• + Addedmkdirp@0.5.6(transitive)

• + Addednanoid@2.1.11(transitive)

• + Addednatives@1.1.6(transitive)

• + Addedoauth-sign@0.9.0(transitive)

• + Addedover@0.0.5(transitive)

• + Addedperformance-now@2.1.0(transitive)

• + Addedpsl@1.13.0(transitive)

• + Addedpullstream@0.4.1(transitive)

• + Addedpunycode@2.3.1(transitive)

• + Addedqs@6.5.3(transitive)

• + Addedreadable-stream@1.0.34(transitive)

• + Addedrequest@2.88.2(transitive)

• + Addedsafer-buffer@2.1.2(transitive)

• + Addedsetimmediate@1.0.5(transitive)

• + Addedshortid@2.2.16(transitive)

• + Addedslice-stream@1.0.0(transitive)

• + Addedsprintf-js@1.0.3(transitive)

• + Addedsshpk@1.18.0(transitive)

• + Addedstring_decoder@0.10.31(transitive)

• + Addedtough-cookie@2.5.0(transitive)

• + Addedtraverse@0.3.9(transitive)

• + Addedtunnel-agent@0.6.0(transitive)

• + Addedtweetnacl@0.14.5(transitive)

• + Addedunzip@0.1.11(transitive)

• + Addeduri-js@4.4.1(transitive)

• + Addeduuid@3.4.0(transitive)

• + Addedverror@1.10.0(transitive)

• + Addedyamljs@0.2.10(transitive)

• Updatedglob@^7.1.1