@magic/cli 0.0.43 → 0.0.45

package/README.md

@@ -11,6 +11,7 @@ provides autogenerated --help output (that can be customized)
 handles commands and environment.
 
 ### v0.0.11+:
+
 ecmascript modules only. no commonjs support.
 
 [html-docs](https://magic.github.io/cli/)
@@ -35,49 +36,57 @@ ecmascript modules only. no commonjs support.
 [snyk-image]: https://snyk.io/test/github/magic/cli/badge.svg
 [snyk-url]: https://snyk.io/test/github/magic/cli
 
-* [dependencies](#dependencies)
-* [install](#install)
-* [caveats](#caveats)
-* [usage](#usage)
-* [argv](#argv)
-* [commands](#commands)
-* [help](#help)
-* [config](#configuration)
-* [pure](#config-pure)
-* [append / prepend](#prepend-append)
-* [default](#default)
+- [dependencies](#dependencies)
+- [install](#install)
+- [caveats](#caveats)
+- [usage](#usage)
+- [argv](#argv)
+- [commands](#commands)
+- [help](#help)
+- [config](#configuration)
+- [pure](#config-pure)
+- [append / prepend](#prepend-append)
+- [default](#default)
 
 ### <a name="dependencies"></a>dependencies:
-* [@magic/log](https://github.com/magic/log): console.log wrapper with loglevels
-* [@magic/types](https://github.com/magic/types): type checking library
-* [@magic/types](https://github.com/magic/cases): case checking library (CamelCase, snake_case, kebab-case)
+
+- [@magic/log](https://github.com/magic/log): console.log wrapper with loglevels
+- [@magic/types](https://github.com/magic/types): type checking library
+- [@magic/types](https://github.com/magic/cases): case checking library (CamelCase, snake_case, kebab-case)
 
 @magic/log, @magic/cases and @magic/types have no dependencies.
 
 ### <a name="install"></a>install
+
 be in a node ecmascript module project.
+
 ```bash
 npm i --save-dev --save-exact @magic/cli
 ```
 
 ### <a name="caveats"></a>caveats
+
 there are some quirks that need some careful consideration when designing a cli api
 depending on your requirements, these caveats should seldomly apply.
 
 ##### last argument
+
 if your last argument does not have a corresponding flag,
 it will still be assigned to the last flag prior to it.
 
 ##### command name overload
+
 if one of your options gets an argument that is equal to a command,
 this command will be executed
 
 ##### flag name overload
+
 cli arguments that start with a - will always be treated as flags, not values.
 
-*those issues might get addressed in the future.*
+_those issues might get addressed in the future._
 
 ### <a name="usage"></a>Usage
+
 first, define the cli file
 
 ```javascript
@@ -85,10 +94,7 @@ first, define the cli file
 import { cli } from '@magic/cli'
 
 const res = cli({
-  commands: [
-    ['cmd1', 'cmd1alias'],
-    'cmd2',
-  ],
+  commands: [['cmd1', 'cmd1alias'], 'cmd2'],
   options: [
     ['--flag1', '-f1'],
     ['--flag2', '-f2'],
@@ -96,12 +102,8 @@ const res = cli({
   default: {
     '--default-key': 'default-value',
   },
-  required: [
-    '--default-key',
-  ],
-  single: [
-    '--default-key',
-  ],
+  required: ['--default-key'],
+  single: ['--default-key'],
   env: [[['--production', '--prod', '--p', '-p'], 'NODE_ENV', 'production']],
   pure: true, // do neither change process.argv nor process.env
   pureArgv: true, // do not change process.argv
@@ -112,6 +114,7 @@ console.log(res)
 ```
 
 ### <a name="argv"></a>options / argv
+
 argv mappings handle options and option aliases
 
 using the cli file above
@@ -121,6 +124,7 @@ using the cli file above
 ```
 
 resulting process.argv:
+
 ```javascript
 process.argv = [
   '/path/to/bin/node',
@@ -134,6 +138,7 @@ process.argv = [
 ```
 
 logged javascript object
+
 ```javascript
 {
   argv: { '--flag1': ['arg1', arg2], '--flag2': [] },
@@ -143,7 +148,9 @@ logged javascript object
 ```
 
 ### <a name="commands"><a>commands
+
 cli commands will be handled too.
+
 ```javascript
 // call
 ./bin.js cmd1
@@ -156,9 +163,11 @@ cli commands will be handled too.
 ```
 
 ### <a name="help"></a>help output
+
 @magic/cli will parse your configuration and create a help text based on it.
 
 #### <a name="help-simple"></a>simple help message
+
 ```javascript
 // ./bin.mjs
 
@@ -172,7 +181,6 @@ const args = {
 }
 
 const argv = cli(args)
-
 ```
 
 then run ./bin.mjs without arguments
@@ -199,7 +207,9 @@ dev: set NODE_ENV to development - aliases ["development"]
 ```
 
 #### <a name="help-detailed"></a>detailed help message
+
 the help property will accept an object which maps to the args object
+
 ```javascript
 import cli from '@magic/cli'
 
@@ -246,9 +256,11 @@ dev: set process.NODE_ENV to development - aliases ["development"]
 ```
 
 ### <a name="clean"></a>clean
+
 some cli arguments will be expected to return a string instead of a list of arguments.
 
 this can be achieved using the single array
+
 ```javascript
 const args = {
   options: [['--single', '-s']],
@@ -260,13 +272,14 @@ const res = cli(args)
 console.log(res)
 ```
 
-
 ### <a name="required"></a>required
+
 some cli arguments will be required.
 
 this can be achieved using the required array.
 
 if a required field is missing, a error message and the help will be shown.
+
 ```javascript
 const args = {
   options: [['--required', '-r']],
@@ -279,12 +292,14 @@ console.log(res)
 ```
 
 ### <a name="config"></a>configuration
+
 there are some configuration parameters that can be passed to the cli function
 
 #### <a name="config-pure"></a>pure
+
 ```javascript
 const args = {
-  pure: false,    // set to true to prevent changes to process.argv and process.env
+  pure: false, // set to true to prevent changes to process.argv and process.env
   pureEnv: false, // set to true to prevent changes to process.env
   pureArgv: false, // set to true to prevent changes to process.argv
 }
@@ -293,7 +308,9 @@ cli(args)
 ```
 
 ### <a name="prepend-append"></a>prepend/append
+
 process.argv values can be prepended and appended
+
 ```javascript
 import cli from '@magic/cli'
 
@@ -306,7 +323,9 @@ cli(args)
 ```
 
 #### <a name="default"></a>default
+
 use this to set default process.argv key: value pairs that should be set if they are not
+
 ```javascript
 import cli from '@magic/cli'
 
@@ -332,148 +351,202 @@ const argv = cli(args)
 ### Changelog
 
 ##### 0.0.1
+
 first release
 
 ##### 0.0.3
+
 cli's should now correctly process.exit(1) on error of the spawned process.
 
 ##### 0.0.4
+
 console help output now aligns nicely
 
 ##### 0.0.5
+
 node 12.4.0 does not have --experimental-node-modules fladg.
 
 ##### 0.0.6
+
 readd --experimental-node-modules flag for 13.1.0+
 
 ##### 0.0.7
+
 update dependencies
 bump node version
 
 ##### 0.0.8
+
 help is shown if cli has commands but none are given
 
 ##### 0.0.9
+
 update dependencies
 
 ##### 0.0.10
+
 update dependencies
 
 ##### 0.0.11
-* parsed.args added. is copy of argv, but using camelCased keys without leading --.
-* no commonjs fallback, ecmascript modules all the way
-* parsed does not return aliases. env, argv, args, commands. thats it.
+
+- parsed.args added. is copy of argv, but using camelCased keys without leading --.
+- no commonjs fallback, ecmascript modules all the way
+- parsed does not return aliases. env, argv, args, commands. thats it.
 
 ##### 0.0.12
+
 add @magic/cases dependency
 
 ##### 0.0.13
+
 update deps
 
 ##### 0.0.14
+
 --help works for cli scripts without commands too
 
 ##### 0.0.15
+
 cli will always provide --help and -h flags to show help
 
 ##### 0.0.16
-* args can be set to be single now, making them return a .join(' ')ed string instead of an array
-* args can be set to be required now, making the cli error and show the help if they are not.
+
+- args can be set to be single now, making them return a .join(' ')ed string instead of an array
+- args can be set to be required now, making the cli error and show the help if they are not.
 
 ##### 0.0.17
+
 required args can now be an array. this allows '--a' or '--b' to be required.
 errors if both are given.
 
 ##### 0.0.18
-* the command `cli-name all` now automagically sets all available commands to true.
-* command keys will always be set to a boolean, return false if task is supposed to not be active.
+
+- the command `cli-name all` now automagically sets all available commands to true.
+- command keys will always be set to a boolean, return false if task is supposed to not be active.
 
 ##### 0.0.19
+
 regression: calling cli that has commands without commands will show help again.
 
 ##### 0.0.20
+
 regression: make commands only have keys for active commands again
 
 ##### 0.0.21
+
 finally get rid of the command regressions
 
 ##### 0.0.22
-* add cli.prompt to get user input.
-* do not error if args.options is empty
-* exec and spawn now are separate functions corresponding to node builtins
+
+- add cli.prompt to get user input.
+- do not error if args.options is empty
+- exec and spawn now are separate functions corresponding to node builtins
 
 ##### 0.0.23
-* cli.prompt: change call signature, remove PasswordStream
+
+- cli.prompt: change call signature, remove PasswordStream
 
 ##### 0.0.24
-* fix required node version
-* update dependencies
+
+- fix required node version
+- update dependencies
 
 ##### 0.0.25
-* prompt now has a yesDefault option
-* prompt will add y/N or Y/n to the prompt message if it is missing
+
+- prompt now has a yesDefault option
+- prompt will add y/N or Y/n to the prompt message if it is missing
 
 ##### 0.0.26
-* default help arguments are now output by default.
+
+- default help arguments are now output by default.
 
 ##### 0.0.27
+
 nicer output for prompt messages
 
 ##### 0.0.28
+
 bump required node version to 14.2.0
 
 ##### 0.0.29
+
 update dependencies
 
 ##### 0.0.30
-* update dependencies
+
+- update dependencies
 
 ##### 0.0.31
-* bump required node version to 14.15.4
-* update dependencies
+
+- bump required node version to 14.15.4
+- update dependencies
 
 ##### 0.0.32
+
 update dependencies
 
 ##### 0.0.33
+
 update dependencies
 
 ##### 0.0.34
+
 update dependencies
 
 ##### 0.0.35
-* parse now can get an opts object as third argument to overwrite child_process.exec options
-* help.argToHelp now errors if the first argument is not an array, before errors only got triggered by falsy arg.
-* exec now uses @magic/error for errors.
-* exec does not trim() the result.
-* findLongestString sorts by length and then alphabetically
-* export execFile
-* update dependencies
+
+- parse now can get an opts object as third argument to overwrite child_process.exec options
+- help.argToHelp now errors if the first argument is not an array, before errors only got triggered by falsy arg.
+- exec now uses @magic/error for errors.
+- exec does not trim() the result.
+- findLongestString sorts by length and then alphabetically
+- export execFile
+- update dependencies
 
 ##### 0.0.36
+
 update dependencies
 
 ##### 0.0.37
+
 update dependencies
 
 ##### 0.0.38
+
 update dependencies
 
 ##### 0.0.39
-* update devdependencies
-* parse.argv does not error if args do not have a length
+
+- update devdependencies
+- parse.argv does not error if args do not have a length
 
 ##### 0.0.40
+
 update dependencies
 
 ##### 0.0.41
+
 update dependencies
 
 ##### 0.0.42
+
 update dependencies
 
 ##### 0.0.43
+
 update dependencies
 
-##### 0.0.44 - unreleased
-...
+##### 0.0.44
+
+- update dependencies
+- add colors to default arg output
+
+##### 0.0.45
+
+- help.example can be an array
+- update dependencies
+- cli.prompt - msg can be an array
+
+##### 0.0.46 - unreleased
+
+- ...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magic/cli",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "homepage": "https://magic.github.io/cli",
   "description": "declarative command line interfaces with aliasing, commands and environment sanitization",
   "scripts": {
@@ -32,21 +32,21 @@
     "declarative"
   ],
   "dependencies": {
-    "@magic/cases": "0.0.8",
-    "@magic/deep": "0.1.15",
-    "@magic/error": "0.0.16",
-    "@magic/log": "0.1.17",
-    "@magic/types": "0.1.22"
+    "@magic/cases": "0.0.9",
+    "@magic/deep": "0.1.16",
+    "@magic/error": "0.0.17",
+    "@magic/log": "0.1.18",
+    "@magic/types": "0.1.23"
   },
   "devDependencies": {
     "@magic-modules/git-badges": "0.0.12",
-    "@magic-modules/light-switch": "0.0.11",
-    "@magic-modules/no-spy": "0.0.7",
-    "@magic-modules/pre": "0.0.11",
-    "@magic-themes/docs": "0.0.14",
-    "@magic/core": "0.0.142",
-    "@magic/format": "0.0.41",
-    "@magic/test": "0.2.12"
+    "@magic-modules/light-switch": "0.0.12",
+    "@magic-modules/no-spy": "0.0.9",
+    "@magic-modules/pre": "0.0.12",
+    "@magic-themes/docs": "0.0.15",
+    "@magic/core": "0.0.150",
+    "@magic/format": "0.0.51",
+    "@magic/test": "0.2.17"
   },
   "author": "Wizards & Witches",
   "license": "AGPL-3.0",

package/src/help/argToHelp.mjs

@@ -39,7 +39,12 @@ export const argToHelp = (arr, help = {}, defaults = {}) => {
       }
 
       if (defaults[name]) {
-        res += ` - default: ${defaults[name]}`
+        let val = defaults[name]
+        if (is.string(val)) {
+          val = `'${val.replace(/'/gim, "'")}'`
+        }
+
+        res += ` - default: ${log.paint('green', val)}`
       }
 
       if (aliases.length) {

package/src/help/index.mjs

@@ -27,6 +27,18 @@ export const maybeHelp = args => {
   const name = help.name || '@magic/cli wrapped cli.'
   const header = is.string(help) ? help : help.text
 
+  const exampleArray = is.string(help.example) ? help.example.split('\n') : help.example
+
+  const exampleText = exampleArray
+    .map(a => {
+      if (a.trim().startsWith('#')) {
+        return log.color('green', a)
+      } else {
+        return a.trim()
+      }
+    })
+    .join('\n')
+
   const helpArray = [
     log.paint('green', name),
     '\n',
@@ -35,7 +47,7 @@ export const maybeHelp = args => {
     options.length && `${log.paint('grey', 'flags')}:\n${optionHelp}\n\n`,
     env.length && `${log.paint('grey', 'environment switches')}:\n${envHelp}\n\n`,
     'examples:\n',
-    help.example,
+    exampleText,
   ]
 
   const errors = parsed.errors

package/src/prompt.mjs

@@ -1,11 +1,13 @@
-import fs from 'fs'
+import is from '@magic/types'
 import readline from 'readline'
 
-import log from '@magic/log'
-
 export const prompt = (msg = '', options = {}) =>
   new Promise((resolve, reject) => {
-    const { yesNo = false, pass = false, std = process, yesDefault = false } = options
+    const { yesNo = false, std = process, yesDefault = false } = options
+
+    if (is.array(msg)) {
+      msg = msg.join(' ')
+    }
 
     if (yesNo) {
       let flag = 'y/N'