@ziggyqubert/do NPM

@ziggyqubert/do

This provides an extensible cli tool / manager, its based on commander with some updates

usage

From within a project call the cli command node_modules/.bin/zqDo this will run the cli in interactive mode, prompting for the commands and options that should be run, it can also be run completly with command line arguments

Commands

The few commands provided as part of the cli tool, additional commands can be added as part of the module this is run under, or its dependencies

Base commands

help - this provides help for the full cli tool or for the specified command
--env - loads a custom .env file into the environment, see dotenv for details
--version - displays the version information for the cli tool
run - this will run a package.json script in the root package or any workspaces defined

Base options

Options that should apply to all commands or modify the behavior of the cli globally

--env - loads a custom .env file into the environment, see dotenv for details
--interactive - forces interactive mode even if some commands are passed in to the cli
--verbose - turns on verbose logging for the cli. see creating plugins below for details of using this

Plugins

Plugins will automatically loaded from packages within the current working directory, packages above the current working directory, and any direct dependencies (starting with @namespace/) for those packages

Note: only reading

Creating plugins

You can add your own commands to the cli, create a js file in the zqDo folder in your package and it will be loaded automatically as long as it is found as specified above

This file should export a single item either a creation function, or an instance of a commander Command.

Creation function

This will be called, with the commander program, logger, and options as the three arguments, and it can be built off using the commander chaining syntax

You can call .childOf('parentName') to create the command under another command, this allows for extending commands created in other modules

Command instance

If returning a command instance it will be added to the structure, the following updates / changes apply -

if you specify a parent property as a string, it will be added to the base command with that name after other commands have ben loaded
the logger is added to the command object as this.logger so that it can be used within commands

Notes

The cli explicitly exits after calling the specified command, so make sure that async functions use await, or return promises so they dont get terminated before completion

Logging

A logging instance is provided that auto colors output and handles verbose logging, that should be used for outputting messaging, logging.verbose respects the --verbose flag. See creating plugins above for details

Commander changes

This changes the behavior of commander in a couple of ways -

help output - this colorizes, re-formats, and provides more detailed help than commander
default args - you can pass argname: 'defaultValue' as part of the options parameter to .command and that will be used as the default value for missing required arguments (and surfaced in the interactive mode) this can also be done by setting the initOptions property of a Command object
.childOf() - Command method to move the command to be a child command of the specified name
emitters - emitted events will now be thrown on all parent commands as well
parse: - an event will be thrown on parse (before the command runs) with the command name, receives the command as the first paramater, this can be used for init stuff, see the aws plugin for an example