bagofcli

Parse command line arguments and execute actions based on the specified commands. Uses commander to provide `-V` / `--version` flags to display the version number, and `-h` / `--help` flags to display the help info. Commands, their positional arguments, and the global and command options are declared in the command file, while `actions` provides the action handler of each command. A command without declared args accepts any positional arguments by default, a command declared with `allowExcessArguments: false` rejects unexpected ones while parsing, before the action handler is called, and the process exits with status code 1. An option declared with `choices` only accepts one of the listed values, commander rejects any other value while parsing, before the action handler is called, and the process exits with status code 1. Likewise, an option declared with `min`, `max`, or `integer` only accepts a number (or an integer when `integer` is true) within the inclusive range. Arguments and options are validated against the rules declared in the command file before the action handler is called, the process exits with status code 1 without calling the action handler when any of them is invalid.

// conf/commands.json
// {
//   "options": [
//     { "arg": "-f, --file <file>", "desc": "A global option" }
//   ],
//   "commands": {
//     "greet": {
//       "desc": "Greet someone",
//       "args": [{ "name": "name", "rules": ["required"] }],
//       "options": [{ "arg": "-s, --shout", "desc": "A command option" }]
//     }
//   }
// }
bag.command(import.meta.dirname, {
  commands: {
    greet: {
      action: function (command) {
        // command.args[0] is the name positional argument
        // command.shout is the command option
        // command.file is the global option
      },
    },
  },
});

Execute a one-liner command. The output emitted on stderr and stdout of the child process will be written to process.stdout and process.stderr of this process. Fallthrough is handy in situation where there are multiple execs running in sequence/parallel, and they all have to be executed regardless of success/error on either one of them.

Execute a one-liner command and collect the output. The output emitted on stderr and stdout of the child process will be collected and passed on to the given callback. Fallthrough is handy in situation where there are multiple execs running in sequence/parallel, and they all have to be executed regardless of success/error on either one of them.

Handle process exit based on the existence of error. This is handy for command-line tools to use as the final callback. Exit status code 1 indicates an error, exit status code 0 indicates a success. Error message will be logged to the console. This function can be used as a standard `cb(err, result)` callback, the result is not declared in the signature because it is not used, the process simply exits with status code 0 when there is no error.

A higher order function that returns a process exit callback, with error and success callbacks to handle error and result accordingly. Exit status code 1 indicates an error, exit status code 0 indicates a success.

Get an array of files contained in specified items. When a directory is specified, all files contained within that directory and its sub-directories will be included.

Display log step heading message on the console.

Display log step item error message on the console error.

Display log step item success message on the console.

Display log step item warning message on the console.

Lookup config values for the specified keys in the following order: - environment variable - if optional file is specified, then check for the value inside the file, the file type is determined by the file extension (.json, .yaml, or .yml) - if optional prompt is set to true, then prompt the user for the config values that are not found in the environment variable and the file the value typed in by the user is masked when the key contains the word password (case insensitive) The file is located using module:bagofcli.lookupFile.

Synchronously read file based on these rules: - if path is absolute, then check file at absolute path first - if path is relative, then check file at current working directory - if none of the above exists, check file at user home directory - if none exists, throw an error This allows simple file lookup which allows various locations.

Execute a command with an array of arguments. The output emitted on stdout and stderr of the child process will be written to process.stdout and process.stderr of this process, without any additional newline.

// will be executed as: make -f somemakefile target1 target2 target3
bag.spawn("make", ["-f", "somemakefile", "target1", "target2", "target3"], cb);