@bemoje/cli 0.0.11 → 0.0.13

package/cjs/arg/ArgumentBuilder.js

@@ -13,11 +13,19 @@ class ArgumentBuilder {
     cmd;
     $;
     index;
+    userConfirmation;
     constructor(cmd, name) {
         this.cmd = cmd;
         this.$ = new extra_typings_1.Argument(name);
         this.index = cmd.meta.argValidators.length;
         cmd.meta.argValidators[this.index] = [];
+        this.cmd.meta.argBuilders.push(this);
+    }
+    get hasValidators() {
+        return this.cmd.meta.argValidators[this.index].length > 0;
+    }
+    get hasParser() {
+        return this.cmd.meta.argParsers[this.index] !== undefined;
     }
     description(string) {
         this.$.description = string;
@@ -40,6 +48,13 @@ class ArgumentBuilder {
     get get() {
         return (0, util_1.realizeLazyProperty)(this, 'get', new ArgumentReader_1.ArgumentReader(this));
     }
+    /**
+     * Only works with async actionHandlers.
+     */
+    userMustConfirmIf(options) {
+        this.userConfirmation = options;
+        return this;
+    }
 }
 exports.ArgumentBuilder = ArgumentBuilder;
 //# sourceMappingURL=ArgumentBuilder.js.map

package/cjs/arg/ArgumentBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"ArgumentBuilder.js","sourceRoot":"","sources":["../../../../../packages/cli/src/arg/ArgumentBuilder.ts"],"names":[],"mappings":";;;AAAA,+DAAsD;AACtD,qEAAiE;AACjE,qDAAiD;AACjD,2EAAuE;AAEvE,uCAAkD;AAElD;;GAEG;AACH,MAAa,eAAe;IAIL;IAHZ,CAAC,CAAU;IACX,KAAK,CAAQ;IAEtB,YAAqB,GAAmB,EAAE,IAAY;QAAjC,QAAG,GAAH,GAAG,CAAgB;QACtC,IAAI,CAAC,CAAC,GAAG,IAAI,wBAAQ,CAAC,IAAI,CAAC,CAAA;QAC3B,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAA;QAC1C,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;IACzC,CAAC;IAED,WAAW,CAAC,MAAc;QACxB,IAAI,CAAC,CAAC,CAAC,WAAW,GAAG,MAAM,CAAA;QAC3B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,CAAC,KAAc,EAAE,WAAoB;QAC1C,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAA;QAClC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,CAAC,MAAyB;QAC/B,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACtB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,+CAAsB,CAAC,IAAI,CAAC,CAAA;IACzC,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,qDAAyB,CAAC,IAAI,CAAC,CAAA;IAC5C,CAAC;IAED,IAAI,GAAG;QACL,OAAO,IAAA,0BAAmB,EAAC,IAAI,EAAE,KAAK,EAAE,IAAI,+BAAc,CAAC,IAAI,CAAC,CAAC,CAAA;IACnE,CAAC;CACF;AApCD,0CAoCC"}
+{"version":3,"file":"ArgumentBuilder.js","sourceRoot":"","sources":["../../../../../packages/cli/src/arg/ArgumentBuilder.ts"],"names":[],"mappings":";;;AAAA,+DAAsD;AACtD,qEAAiE;AACjE,qDAAiD;AACjD,2EAAuE;AAEvE,uCAAkD;AAElD;;GAEG;AACH,MAAa,eAAe;IAKL;IAJZ,CAAC,CAAU;IACX,KAAK,CAAQ;IACtB,gBAAgB,CAA2D;IAE3E,YAAqB,GAAmB,EAAE,IAAY;QAAjC,QAAG,GAAH,GAAG,CAAgB;QACtC,IAAI,CAAC,CAAC,GAAG,IAAI,wBAAQ,CAAC,IAAI,CAAC,CAAA;QAC3B,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAA;QAC1C,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;QACvC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACtC,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;IAC3D,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,SAAS,CAAA;IAC3D,CAAC;IAED,WAAW,CAAC,MAAc;QACxB,IAAI,CAAC,CAAC,CAAC,WAAW,GAAG,MAAM,CAAA;QAC3B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,CAAC,KAAc,EAAE,WAAoB;QAC1C,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAA;QAClC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,CAAC,MAAyB;QAC/B,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACtB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,+CAAsB,CAAC,IAAI,CAAC,CAAA;IACzC,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,qDAAyB,CAAC,IAAI,CAAC,CAAA;IAC5C,CAAC;IAED,IAAI,GAAG;QACL,OAAO,IAAA,0BAAmB,EAAC,IAAI,EAAE,KAAK,EAAE,IAAI,+BAAc,CAAC,IAAI,CAAC,CAAC,CAAA;IACnE,CAAC;IAED;;OAEG;IACH,iBAAiB,CAAC,OAAiE;QACjF,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAA;QAC/B,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAtDD,0CAsDC"}

package/cjs/cmd/CommandBuilder.js

@@ -10,6 +10,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const is_async_function_1 = __importDefault(require("is-async-function"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const prompts_1 = __importDefault(require("prompts"));
 const ArgumentBuilder_1 = require("../arg/ArgumentBuilder");
 const util_1 = require("@bemoje/util");
 const util_2 = require("@bemoje/util");
@@ -49,12 +50,12 @@ class CommandBuilder {
     constructor(name, callback, parent, isNative = false) {
         this.meta.isNative = isNative;
         this.$ = new extra_typings_1.Command(name);
+        exports.commanderBackRefs.set(this.$, this);
         if (parent) {
             this.parent = parent;
             this.parent.meta.subcommands.push(this);
             this.parent.$.addCommand(this.$);
         }
-        exports.commanderBackRefs.set(this.$, this);
         this.initializeHelp();
         if (callback)
             callback.call(this, this);
@@ -91,10 +92,18 @@ class CommandBuilder {
         this.presetsEnabled();
     }
     deleteDataFile() {
-        const filepath = this.dataFilepath;
+        const filepath = this.jsonFilepath;
         if (fs_extra_1.default.existsSync(filepath))
             (0, util_13.removeFile)(filepath);
     }
+    /**
+     * Set the program version to `str`.
+     *
+     * This method auto-registers the "-V, --version" flag
+     * which will print the version number when passed.
+     *
+     * You can optionally supply the  flags and description to override the defaults.
+     */
     version(string) {
         this.$.version(string);
         const opt = this.options.find((o) => o.attributeName() === 'version');
@@ -102,6 +111,11 @@ class CommandBuilder {
             this.meta.globalOptions.push(opt);
         return this;
     }
+    /**
+     * Set the description. If more than one sentence or string is given,
+     * then the first will be used as summary and the whole text as description.
+     * @param lines - description lines
+     */
     description(...lines) {
         const description = lines.join('\n');
         const summary = description.split(/(\. ?|\n|$)/)[0];
@@ -109,16 +123,32 @@ class CommandBuilder {
         this.$.description(description);
         return this;
     }
+    /**
+     * Set an alias for the command.
+     * You may call more than once to add multiple aliases.
+     * Only the first alias is shown in the auto-generated help.
+     */
     alias(alias) {
         this.assertCommandNameNotReserved(alias);
         this.$.alias(alias);
         return this;
     }
+    /**
+     * Set aliases for the command. This overwrites all previously set aliases.
+     * Only the first alias is shown in the auto-generated help.
+     */
     aliases(...aliases) {
         aliases.forEach((alias) => this.assertCommandNameNotReserved(alias));
         this.$.aliases(aliases);
         return this;
     }
+    /**
+     * Set the command usage.
+     */
+    usage(str) {
+        this.$.usage(str);
+        return this;
+    }
     enableBuiltinOptions(options) {
         if (!options || options.debug)
             this.globalOption('-D, --debug', 'Output debugging information.');
@@ -139,6 +169,10 @@ class CommandBuilder {
         else if (typeof cb === 'string') {
             ins.description(cb);
         }
+        if (ins.$.variadic && !ins.hasParser && !ins.hasValidators) {
+            ins.parser.string();
+            ins.validator.isStringArray();
+        }
         return this;
     }
     option(flags, cb) {
@@ -152,6 +186,10 @@ class CommandBuilder {
         else if (typeof cb === 'string') {
             ins.description(cb);
         }
+        if (ins.$.variadic && !ins.hasParser && !ins.hasValidators) {
+            ins.parser.string();
+            ins.validator.isStringArray();
+        }
         return this;
     }
     globalOption(flags, cb) {
@@ -168,14 +206,27 @@ class CommandBuilder {
                 this.meta.hiddenGlobalOptions.add(opt);
         });
     }
+    /**
+     * Create a subcommand.
+     * @param flags - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
+     * @param description - describe the command
+     */
     command(name, cb) {
         new CommandBuilder(name, cb, this);
         return this;
     }
+    /**
+     * Create a native subcommand.
+     * @param flags - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
+     * @param description - describe the command
+     */
     nativeCommand(name, cb) {
         new CommandBuilder(name, cb, this, true);
         return this;
     }
+    /**
+     * Register callback function for the command to execute when invoked.
+     */
     action(fn) {
         const isAsync = (0, is_async_function_1.default)(fn) || /^\(.+\) ?=> ?tslib_1\.__awaiter\(/.test(fn.toString().trim());
         this.meta.isActionAsync = isAsync;
@@ -183,6 +234,16 @@ class CommandBuilder {
         this.initializeActionWrapper(isAsync);
         return this;
     }
+    usageExamples(...examples) {
+        const table = examples.map(({ command, description }) => {
+            if (command.length + (description?.length || 0) > 100) {
+                this.throwCommanderError(`Usage example description too long: ${command}`);
+            }
+            return [command, description ?? ''];
+        });
+        this.description(this.$.description() + '\n\n' + 'Usage Examples:\n' + (0, util_5.formatTableForTerminal)(table));
+        return this;
+    }
     errorHandler(fn) {
         Object.defineProperty(this.meta, 'errorHandler', { value: fn, configurable: true });
         return this;
@@ -220,14 +281,49 @@ class CommandBuilder {
         this.features.autoAssignSubCommandAliases(boolean);
         return this;
     }
+    /**
+     * Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
+     *
+     * @returns `this` command for chaining
+     */
     allowExcessArguments(bool = true) {
         this.$.allowExcessArguments(bool);
         return this;
     }
+    /**
+     * Allow unknown options on the command line.
+     *
+     * @returns `this` command for chaining
+     */
     allowUnknownOption(bool = true) {
         this.$.allowUnknownOption(bool);
         return this;
     }
+    /**
+     * Enable positional options. Positional means global options are specified before subcommands which lets
+     * subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.
+     *
+     * The default behaviour is non-positional and global options may appear anywhere on the command line.
+     *
+     * @returns `this` command for chaining
+     */
+    enablePositionalOptions(positional) {
+        this.$.enablePositionalOptions(positional);
+        return this;
+    }
+    /**
+     * Pass through options that come after command-arguments rather than treat them as command-options,
+     * so actual command-options come before command-arguments. Turning this on for a subcommand requires
+     * positional options to have been enabled on the program (parent commands).
+     *
+     * The default behaviour is non-positional and options may appear before or after command-arguments.
+     *
+     * @returns `this` command for chaining
+     */
+    passThroughOptions(passThrough) {
+        this.$.passThroughOptions(passThrough);
+        return this;
+    }
     /**
      * Register callback to use as replacement for calling process.exit.
      */
@@ -235,13 +331,6 @@ class CommandBuilder {
         this.$.exitOverride(callback);
         return this;
     }
-    throwInsteadOfProcessExit() {
-        const onErr = (err) => {
-            throw err;
-        };
-        this.exitOverride(onErr);
-        this.errorHandler(onErr);
-    }
     /**
      * Add hook for life cycle event.
      */
@@ -271,6 +360,19 @@ class CommandBuilder {
         this.$.showSuggestionAfterError(displaySuggestion);
         return this;
     }
+    /**
+     * Override default decision whether to add implicit help command.
+     * @example ```
+     * addHelpCommand() // force on
+     * addHelpCommand(false); // force off
+     * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+     * ```
+     * @returns `this` command for chaining
+     */
+    addHelpCommand(enableOrNameAndArgs, description) {
+        this.$.addHelpCommand(enableOrNameAndArgs, description);
+        return this;
+    }
     /**
      * Add additional text to be displayed with the built-in help.
      *
@@ -359,7 +461,7 @@ class CommandBuilder {
      * Output help information for this command.
      */
     outputHelp() {
-        console.log(this.getRenderedHelp());
+        console.log(this.getHelpInformation());
     }
     /**
      * Display error message and exit (or call exitOverride).
@@ -373,7 +475,7 @@ class CommandBuilder {
             if (!arg)
                 return arg;
             const parse = this.meta.argParsers[i > last ? last : i];
-            return parse ? (Array.isArray(arg) ? arg.map(parse) : parse(arg)) : arg;
+            return parse ? (Array.isArray(arg) ? arg.map((a) => parse(a)) : parse(arg)) : arg;
         });
     }
     /**
@@ -382,7 +484,7 @@ class CommandBuilder {
     parseOptions(opts) {
         for (const [key, value] of Object.entries(opts)) {
             const parse = this.meta.optParsers[key];
-            opts[key] = parse ? (Array.isArray(value) ? value.map(parse) : parse(value)) : value;
+            opts[key] = parse ? (Array.isArray(value) ? value.map((o) => parse(o)) : parse(value)) : value;
         }
         return opts;
     }
@@ -430,6 +532,13 @@ class CommandBuilder {
         (0, util_4.ensureThat)(options, util_7.isObject);
         this.assertValidOptions(options);
     }
+    throwRatherThanExitProcess() {
+        const throwError = (error) => {
+            throw error;
+        };
+        this.errorHandler(throwError);
+        this.exitOverride(throwError);
+    }
     get name() {
         return this.$.name();
     }
@@ -464,7 +573,7 @@ class CommandBuilder {
             return false;
         return (0, util_2.arrLast)(this.arguments).variadic;
     }
-    get dataFilepath() {
+    get jsonFilepath() {
         return path_1.default.join(CommandBuilder.dataDirectory, this.root.name + '.json');
     }
     /**
@@ -578,19 +687,55 @@ class CommandBuilder {
     getSiblings() {
         return [...this.getSiblingsIterator()];
     }
-    getClosestNonNativeParent() {
-        for (const anc of this.getAncestorsIterator({ includeSelf: true })) {
-            if (!anc.meta.isNative)
-                return anc;
-        }
-        this.throwCommanderError('No non-native parent found');
-    }
-    getRenderedHelp() {
+    /**
+     * Render the help string for the command.
+     */
+    getHelpInformation() {
         return this.$.helpInformation();
     }
-    getOptsWithGlobalsParsed() {
+    getOptsWithGlobals() {
         return this.parseOptions(this.$.optsWithGlobals());
     }
+    /**
+     * Parse `argv`, setting options and invoking commands when defined.
+     *
+     * The default expectation is that the arguments are from node and have the application as argv[0]
+     * and the script being run in argv[1], with user parameters after that.
+     *
+     * @example
+     * ```
+     * program.parse(process.argv);
+     * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+     * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+     * ```
+     *
+     * @returns `this` command for chaining
+     */
+    parse(argv, options) {
+        this.$.parse(argv, options);
+        return this;
+    }
+    /**
+     * Parse `argv`, setting options and invoking commands when defined.
+     *
+     * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
+     *
+     * The default expectation is that the arguments are from node and have the application as argv[0]
+     * and the script being run in argv[1], with user parameters after that.
+     *
+     * @example
+     * ```
+     * program.parseAsync(process.argv);
+     * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+     * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+     * ```
+     *
+     * @returns Promise
+     */
+    async parseAsync(argv, options) {
+        await this.$.parseAsync(argv, options);
+        return this;
+    }
     getParsedValidArgsOptsWithPresets() {
         const [presetArgs, presetOpts, presetOrder] = this.getPresetArgsAndOpts();
         const args = this.getParsedValidArgsWithPresets(presetArgs);
@@ -605,9 +750,9 @@ class CommandBuilder {
         return this.padArgsWithUndefinedUntilExpectedLength(result);
     }
     getParsedValidOptsWithPresets(presetOpts) {
-        const parsed = this.getOptsWithGlobalsParsed();
+        const parsed = this.getOptsWithGlobals();
         const opts = presetOpts.length ? (0, util_11.objAssign)({}, ...presetOpts, parsed) : parsed;
-        this.deleteOptionsWithDefaultOrNoValue(opts);
+        this.hideOptionsWithDefaultOrNoValueOrArePresets(opts);
         this.assertValidOptions(opts);
         return opts;
     }
@@ -643,10 +788,11 @@ class CommandBuilder {
             });
         }
     }
-    deleteOptionsWithDefaultOrNoValue(opts) {
-        const names = new Set(this.getOwnAndGlobalOptions().map((o) => o.attributeName()));
+    hideOptionsWithDefaultOrNoValueOrArePresets(opts) {
+        const allOpts = this.getOwnAndGlobalOptions();
+        const optMap = Object.fromEntries(allOpts.map((o) => [o.attributeName(), o]));
         for (const [key, value] of Object.entries(opts)) {
-            if (!names.has(key) || value === false || value == null) {
+            if (value == null || !optMap[key] || optMap[key].defaultValue === value) {
                 (0, util_14.setNonEnumerable)(opts, key);
             }
         }
@@ -691,7 +837,7 @@ class CommandBuilder {
             return;
         }
         this.nativeCommand('util', (u) => {
-            const cmd = u.getClosestNonNativeParent();
+            const cmd = u.parent;
             u.alias('u');
             u.description('Utility commands.');
             if (cmd.features.isConfigEnabled) {
@@ -709,7 +855,7 @@ class CommandBuilder {
             function createUtilFilepathCommand(f) {
                 f.alias('f');
                 f.description('Print filepath to JSON file containing user data, eg. config and presets.');
-                f.action(async () => console.log(cmd.dataFilepath));
+                f.action(async () => console.log(cmd.jsonFilepath));
             }
             function createUtilListCommand(l) {
                 l.alias('l');
@@ -989,6 +1135,25 @@ class CommandBuilder {
             }
         }
     }
+    async getUserConfirmations(args) {
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            const argb = this.meta.argBuilders[i];
+            if (!argb || !argb.userConfirmation)
+                continue;
+            const { predicate, message } = argb.userConfirmation;
+            if (predicate(arg)) {
+                const result = await (0, prompts_1.default)({
+                    type: 'confirm',
+                    name: 'isConfirmed',
+                    message,
+                    initial: true,
+                });
+                if (!result.isConfirmed)
+                    this.outputError('Aborted.');
+            }
+        }
+    }
     initializeActionWrapper(isAsync = false) {
         if (isAsync) {
             this.$.action(async () => {
@@ -997,7 +1162,8 @@ class CommandBuilder {
                     const [args, opts] = this.getParsedValidArgsOptsWithPresets();
                     if (opts['help'])
                         return this.outputHelp();
-                    const owg = this.$.optsWithGlobals();
+                    await this.getUserConfirmations(args);
+                    const optswg = this.$.optsWithGlobals();
                     await this.meta.actionHandler.call(this, ...args, opts, this);
                 }
                 catch (error) {
@@ -1043,46 +1209,6 @@ class CommandBuilder {
             this.throwCommanderError(`Name '${name}' is reserved and is not available as name or alias.`);
         }
     }
-    /**
-     * Parse `argv`, setting options and invoking commands when defined.
-     *
-     * The default expectation is that the arguments are from node and have the application as argv[0]
-     * and the script being run in argv[1], with user parameters after that.
-     *
-     * @example
-     * ```
-     * program.parse(process.argv);
-     * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
-     * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
-     * ```
-     *
-     * @returns `this` command for chaining
-     */
-    parse(argv, options) {
-        this.$.parse(argv, options);
-        return this;
-    }
-    /**
-     * Parse `argv`, setting options and invoking commands when defined.
-     *
-     * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
-     *
-     * The default expectation is that the arguments are from node and have the application as argv[0]
-     * and the script being run in argv[1], with user parameters after that.
-     *
-     * @example
-     * ```
-     * program.parseAsync(process.argv);
-     * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-     * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
-     * ```
-     *
-     * @returns Promise
-     */
-    async parseAsync(argv, options) {
-        await this.$.parseAsync(argv, options);
-        return this;
-    }
 }
 exports.CommandBuilder = CommandBuilder;
 exports.commanderBackRefs = new WeakMap();