@gerard2p/mce

Installation

npm i -g @gerard2p/mce

Usage

    mce new <application> [options]
      Creates a new MCE project.
        -f, --force          Overrides target directory                            
        -n, --npm            Install npm dependencies                              
        -s, --style <style>  Define the style of command you will use. If you need
                              more than one command use git.
                              Values: git | *single
    mce add <command>
      Adds a new command to the git project.

This will create project that is ready to work with mce. The project scaffolding look like this:

Project Structure

project_name::
  |--.vscode
  |  |--launch.json
  |  |--settings.json
  |  |--task.json
  |
  |--src
  |  |--index.ts       [single-style]
  |  |--cli.ts
  |  |--commands       [git-style]
  |    |--removeme.ts
  |
  |--.gitignore
  |--package.json
  |--tsconfig.json
  |--project_name

Configuring command

• Single-Style only uses a index.ts in the src folder.
• Git-Style uses [command].ts files inside the commands folder.

In any of both cases a command is defined in the same way.

import { numeric, floating, range, text, list, collect, bool, verbose, enumeration, Parsed} from '@gerard2p/mce';
import { ok, error, warn, info, ask, input } from '@gerard2p/mce/verbose';
import { created, updated, makeDir, cp, printRelativePath, targetPath, cliPath } from '@gerard2p/mce/utils';
import { spin } from '@gerard2p/mce/spinner';
enum Styles { 
    git = 'git',
    single = 'single' 
}
export let description = 'A description for your command';
export let args = '<arg1> [varidac...]';
export let options = {
    enumeration: enumeration('-e <enum>', 'Define the style of command you will use', Styles,Styles.single),
    number: numeric('-n <n>', 'A number'),
    floating: floating('-f <n>', 'A float number'),
    range: range('-r <a>..<b>', 'A Range of two numbers'),
    text: text('-t <n>', 'A string value'),
    list: list('-l <n>', 'comma separed values'),
    collect: collect('-c <n>', 'A repetable value'),
    bool: bool('-b', 'A boolean value'),
    verbose: verbose('Increase system verbosity'),
};
export async function action(arg1:string, varidac:string[], opt:Parsed<typeof options>) {
    // Your Code
}

Option Parsing

You must export a options variable with the options that you want to use. As you can see you can defined a lot of types for your options most of the options cant take a '' as first parameter and mce will generate the tags for you.

The name in the you use to define the property is used as main tag, if you pass '' as the first argument it will fill with a automatic tag_desc and no sort tag will be generated. On the other hand if you pass a string like -e --env <env> mce will use those values as the short tag, tag and tag value.

option	short	tag	tag_desc	desc
enumeration:enumeration('', 'description', ['a','b'])		--enumeration	<e>	description Values a | b
enumeration:enumeration('-l', 'description', ['a','b'])	-l	--enumeration	<e>	description Values a | b
enumeration:enumeration('-l --list', 'description', ['a','b'])	-l	--list	<e>	description Values a | b
enumeration:enumeration('-l --list <l>', 'description', ['a','b'])	-l	--list	<l>	description Values a | b

No mather the case the actual property that is created in the opt is always enumeration for this case.

Coercion

As you can see mce come with some handy functios to coerce and validate the user input.

import { numeric, floating, range, text, list, collect, bool, verbose, enumeration } from '@gerard2p/mce';

Validation

If you need to validate the information of any of your arguments you can pass a RegExp as the third arguments of the option_functions

import { text } from '@gerard2p/mce';

export let options = {
 size: text('-s --size <size>', 'Pizza size', /^(large|medium|small)$/);
}

Defaults

The last argument you pass will always be the default value.

import { text } from '@gerard2p/mce';

export let options = {
 size: text('-s --size <size>', 'Pizza size', /^(large|medium|small)$/, 'medium');
}

Version option

By default mce will trace the --version tag and will respond with the version in your package.json.

Verbose option

By default mce will trace the -v --verbose tag and will respond wwith the version in your package.json.

Only if you define a verbose obtion you will be passed with the actual verbose value but in most of the cases is no needed.

Arguments

You need to export a args:string property with you arguments definition

Required args

<arg> is the convention to make your arg required is no arg detected mce will throw and error.

Optional args

[arg] is the convention to make your arg optional.

Varidac args

[arg ...] is the convention to make the rest of the args be presented as varidad string[]

Coecion

Argument can be coerced by default they are treated as string but if you use:

• <arg:number> will be coerce to number.
• <arg:boolean> will be coerce to boolean.

Help Generation

By default mce will trace the -h --help options and will automatically render help

Add a new command to project

Just run:

mce add <command>

Adds a new command to a git-style project.

Useful Utilities

MCE con with a handy bunch of utilities to help you build your commands easily.

Input

import { confirm, override, question} from '@gerard2p/mce/input'

question(display:string)=>Promise<string>

This is the basic function that allows you to wait for user input. Is compatible with the spinner, so, whenever you call this functions the spinner will stop and display the new message.

When the user enters the input the spinner will continue working as expected.

let answer = await question('Are you ready?')

Will display

Are you ready? _

And will wait for user input.

if inside a spinner:

await spin('demo', async ()=>{
 let answer = await question('Are you ready?')
});

demo - Are you ready? _

confirm (display:string)=>Promise<boolean>

if(await confirm('Are you ready')) {
 // code
}
// Are you ready? [y/n]: _

await spin('demo', async ()=>{
 if(await confirm('Are you ready')) {
  // code
 }
});
// demo - Are you ready? [y/n]: _

override (display:string, testdir:string, state:boolean)=>Promise<boolean>

Returns true if safe to write the directory and content. Removes the directory if is needed.

if(await override('Path already exists do you want to continue')) {
 // code
}
// Path already exists do you want to continue? [y/n]: _

await spin('demo', async ()=>{
 if(await override('Path already exists do you want to continue')) {
  // code
 }
});
// demo - Path already exists do you want to continue? [y/n]: _

tree-maker

import { pathResolver } from '@gerard2p/mce/tree-maker/fs'

This function allows you to intersect the path that resolves to your templates and the target path.

pathResolver(_template:(path:string)=>string, _target?:(path:string)=>string):void

_template will resolve to a template folder located next to your package.json

import { cpy, cmp, dir, root, wrt } from '@gerard2p/mce/tree-maker'
import {   c,   z,   d,    r,   w } from '@gerard2p/mce/tree-maker'

This utility allows to create a directory structure in a really easy and chainable way.

root('proyect')
 .with(
  cpy('LICENSE')
 )
 .dir('subfolder',
 cmp('README.md', {...values}, 'DOC.md'),
  cmp('README.md', {...values}),
  wrt('.gitignore','node_modules\ttemplates')
 )

will produde:

proyect
  |- LICENSE
  |-subfolder
    |-DOC.md
    |-README.md
    |-.gitignore

root(dir:string)=>TreeMaker

Creates the initial directory.

cpy(source:string, target:string)=>chainable

Copies a file from your template directory to the destination folder. Target can be undefined and will use the same name as your source.

cmp(source:string, data:any, target:string)=>chainable

Renders a file from your template directory to the destination folder. Target can be undefined and will use the same name as your source.

wrt(target:string, content:string)=>chainable

Create a file at target location.

dir(folder:string, ...operations:chainable[])=>chainable

Create a new directory and allows to chain new operations

Final Notes

The executable file that is generated only call your ./cli file.

When in git-style cli.ts will look like:

import { MCE } from "@gerard2p/mce";

MCE(__dirname).subcommand(process.argv);

And in single-style:

import { MCE } from "@gerard2p/mce";

MCE(__dirname).command(process.argv);

During local development I use ts-node to call direct the .ts files