@oclif/core 3.0.0-beta.9 → 3.0.0

package/lib/command.js

@@ -1,18 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Command = void 0;
-const url_1 = require("url");
-const chalk = require("chalk");
-const util_1 = require("util");
-const ux_1 = require("./ux");
+const tslib_1 = require("tslib");
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const node_url_1 = require("node:url");
+const node_util_1 = require("node:util");
+const cli_ux_1 = require("./cli-ux");
+const stream_1 = require("./cli-ux/stream");
 const config_1 = require("./config");
-const Errors = require("./errors");
-const Parser = require("./parser");
-const util_2 = require("./help/util");
-const flags_1 = require("./flags");
-const util_3 = require("./util");
-const stream_1 = require("./ux/stream");
-const pjson = (0, util_3.requireJson)(__dirname, '..', 'package.json');
+const Errors = tslib_1.__importStar(require("./errors"));
+const util_1 = require("./help/util");
+const Parser = tslib_1.__importStar(require("./parser"));
+const aggregate_flags_1 = require("./util/aggregate-flags");
+const fs_1 = require("./util/fs");
+const util_2 = require("./util/util");
+const pjson = (0, fs_1.requireJson)(__dirname, '..', 'package.json');
 /**
  * swallows stdout epipe errors
  * this occurs when stdout closes such as when piping to head
@@ -22,40 +24,86 @@ stream_1.stdout.on('error', (err) => {
         return;
     throw err;
 });
-const jsonFlag = {
-    json: (0, flags_1.boolean)({
-        description: 'Format output as json.',
-        helpGroup: 'GLOBAL',
-    }),
-};
 /**
  * An abstract class which acts as the base for each command
  * in your project.
  */
 class Command {
-    static get enableJsonFlag() {
-        return this._enableJsonFlag;
-    }
-    static set enableJsonFlag(value) {
-        this._enableJsonFlag = value;
-        if (value === true) {
-            this.baseFlags = jsonFlag;
+    argv;
+    config;
+    /** An array of aliases for this command. */
+    static aliases = [];
+    /** An order-dependent object of arguments for the command */
+    static args = {};
+    static baseFlags;
+    /**
+     * Emit deprecation warning when a command alias is used
+     */
+    static deprecateAliases;
+    static deprecationOptions;
+    /**
+     * A full description of how to use the command.
+     *
+     * If no summary, the first line of the description will be used as the summary.
+     */
+    static description;
+    static enableJsonFlag = false;
+    /**
+     * An array of examples to show at the end of the command's help.
+     *
+     * IF only a string is provided, it will try to look for a line that starts
+     * with the cmd.bin as the example command and the rest as the description.
+     * If found, the command will be formatted appropriately.
+     *
+     * ```
+     * EXAMPLES:
+     *   A description of a particular use case.
+     *
+     *     $ <%= config.bin => command flags
+     * ```
+     */
+    static examples;
+    /** A hash of flags for the command */
+    static flags;
+    static hasDynamicHelp = false;
+    static help;
+    /** Hide the command from help */
+    static hidden;
+    /** A command ID, used mostly in error or verbose reporting. */
+    static id;
+    static plugin;
+    static pluginAlias;
+    static pluginName;
+    static pluginType;
+    /** Mark the command as a given state (e.g. beta or deprecated) in help */
+    static state;
+    /** When set to false, allows a variable amount of arguments */
+    static strict = true;
+    /**
+     * The tweet-sized description for your class, used in a parent-commands
+     * sub-command listing and as the header for the command help.
+     */
+    static summary;
+    /**
+     * An override string (or strings) for the default usage documentation.
+     */
+    static usage;
+    static _base = `${pjson.name}@${pjson.version}`;
+    debug;
+    id;
+    constructor(argv, config) {
+        this.argv = argv;
+        this.config = config;
+        this.id = this.ctor.id;
+        try {
+            this.debug = require('debug')(this.id ? `${this.config.bin}:${this.id}` : this.config.bin);
         }
-        else {
-            delete this.baseFlags?.json;
-            this.flags = {}; // force the flags setter to run
-            delete this.flags?.json;
+        catch {
+            this.debug = () => {
+                // noop
+            };
         }
     }
-    static get '--'() {
-        return Command['_--'];
-    }
-    static set '--'(value) {
-        Command['_--'] = value;
-    }
-    get passThroughEnabled() {
-        return Command['_--'];
-    }
     /**
      * instantiate and run the command
      *
@@ -69,7 +117,7 @@ class Command {
             argv = process.argv.slice(2);
         // Handle the case when a file URL string is passed in such as 'import.meta.url'; covert to file path.
         if (typeof opts === 'string' && opts.startsWith('file://')) {
-            opts = (0, url_1.fileURLToPath)(opts);
+            opts = (0, node_url_1.fileURLToPath)(opts);
         }
         const config = await config_1.Config.load(opts || require.main?.filename || __dirname);
         const cmd = new this(argv, config);
@@ -80,33 +128,6 @@ class Command {
         }
         return cmd._run();
     }
-    static get baseFlags() {
-        return this._baseFlags;
-    }
-    static set baseFlags(flags) {
-        this._baseFlags = Object.assign({}, this.baseFlags, flags);
-        this.flags = {}; // force the flags setter to run
-    }
-    static get flags() {
-        return this._flags;
-    }
-    static set flags(flags) {
-        this._flags = Object.assign({}, this._flags ?? {}, this.baseFlags, flags);
-    }
-    constructor(argv, config) {
-        this.argv = argv;
-        this.config = config;
-        this.id = this.ctor.id;
-        try {
-            this.debug = require('debug')(this.id ? `${this.config.bin}:${this.id}` : this.config.bin);
-        }
-        catch {
-            this.debug = () => { };
-        }
-    }
-    get ctor() {
-        return this.constructor;
-    }
     async _run() {
         let err;
         let result;
@@ -127,45 +148,46 @@ class Command {
             this.logJson(this.toSuccessJson(result));
         return result;
     }
-    exit(code = 0) {
-        Errors.exit(code);
+    removeEnvVar(envVar) {
+        const keys = [];
+        try {
+            keys.push(...this.config.scopedEnvVarKeys(envVar));
+        }
+        catch {
+            keys.push(this.config.scopedEnvVarKey(envVar));
+        }
+        keys.map((key) => delete process.env[key]);
     }
-    warn(input) {
-        if (!this.jsonEnabled())
-            Errors.warn(input);
-        return input;
+    async catch(err) {
+        process.exitCode = process.exitCode ?? err.exitCode ?? 1;
+        if (this.jsonEnabled()) {
+            this.logJson(this.toErrorJson(err));
+        }
+        else {
+            if (!err.message)
+                throw err;
+            try {
+                cli_ux_1.ux.action.stop(chalk_1.default.bold.red('!'));
+            }
+            catch { }
+            throw err;
+        }
     }
     error(input, options = {}) {
         return Errors.error(input, options);
     }
-    log(message = '', ...args) {
-        if (!this.jsonEnabled()) {
-            message = typeof message === 'string' ? message : (0, util_1.inspect)(message);
-            stream_1.stdout.write((0, util_1.format)(message, ...args) + '\n');
-        }
+    exit(code = 0) {
+        Errors.exit(code);
     }
-    logToStderr(message = '', ...args) {
-        if (!this.jsonEnabled()) {
-            message = typeof message === 'string' ? message : (0, util_1.inspect)(message);
-            stream_1.stderr.write((0, util_1.format)(message, ...args) + '\n');
+    async finally(_) {
+        try {
+            const { config } = Errors;
+            if (config.errorLogger)
+                await config.errorLogger.flush();
         }
-    }
-    /**
-     * Determine if the command is being run with the --json flag in a command that supports it.
-     *
-     * @returns {boolean} true if the command supports json and the --json flag is present
-     */
-    jsonEnabled() {
-        // if the command doesn't support json, return false
-        if (!this.ctor.enableJsonFlag)
-            return false;
-        // if the command parameter pass through is enabled, return true if the --json flag is before the '--' separator
-        if (this.passThroughEnabled) {
-            const ptIndex = this.argv.indexOf('--');
-            const jsonIndex = this.argv.indexOf('--json');
-            return jsonIndex > -1 && (ptIndex === -1 || jsonIndex < ptIndex);
+        catch (error) {
+            console.error(error);
         }
-        return this.argv.includes('--json') || this.config.scopedEnvVar?.('CONTENT_TYPE')?.toLowerCase() === 'json';
     }
     async init() {
         this.debug('init version: %s argv: %o', this.ctor._base, this.argv);
@@ -178,103 +200,102 @@ class Command {
         g['http-call'].userAgent = this.config.userAgent;
         this.warnIfCommandDeprecated();
     }
-    warnIfFlagDeprecated(flags) {
-        for (const flag of Object.keys(flags)) {
-            const flagDef = this.ctor.flags[flag];
-            const deprecated = flagDef?.deprecated;
-            if (deprecated) {
-                this.warn((0, util_2.formatFlagDeprecationWarning)(flag, deprecated));
-            }
-            const deprecateAliases = flagDef?.deprecateAliases;
-            const aliases = (flagDef?.aliases ?? []).map(a => a.length === 1 ? `-${a}` : `--${a}`);
-            if (deprecateAliases && aliases.length > 0) {
-                const foundAliases = aliases.filter(alias => this.argv.some(a => a.startsWith(alias)));
-                for (const alias of foundAliases) {
-                    let preferredUsage = `--${flagDef?.name}`;
-                    if (flagDef?.char) {
-                        preferredUsage += ` | -${flagDef?.char}`;
-                    }
-                    this.warn((0, util_2.formatFlagDeprecationWarning)(alias, { to: preferredUsage }));
-                }
-            }
-        }
+    /**
+     * Determine if the command is being run with the --json flag in a command that supports it.
+     *
+     * @returns {boolean} true if the command supports json and the --json flag is present
+     */
+    jsonEnabled() {
+        // If the command doesn't support json, return false
+        if (!this.ctor.enableJsonFlag)
+            return false;
+        // If the CONTENT_TYPE env var is set to json, return true
+        if (this.config.scopedEnvVar?.('CONTENT_TYPE')?.toLowerCase() === 'json')
+            return true;
+        const passThroughIndex = this.argv.indexOf('--');
+        const jsonIndex = this.argv.indexOf('--json');
+        return passThroughIndex === -1
+            ? // If '--' is not present, then check for `--json` in this.argv
+                jsonIndex > -1
+            : // If '--' is present, return true only the --json flag exists and is before the '--'
+                jsonIndex > -1 && jsonIndex < passThroughIndex;
     }
-    warnIfCommandDeprecated() {
-        const [id] = (0, util_2.normalizeArgv)(this.config);
-        if (this.ctor.deprecateAliases && this.ctor.aliases.includes(id)) {
-            const cmdName = (0, util_2.toConfiguredId)(this.ctor.id, this.config);
-            const aliasName = (0, util_2.toConfiguredId)(id, this.config);
-            this.warn((0, util_2.formatCommandDeprecationWarning)(aliasName, { to: cmdName }));
+    log(message = '', ...args) {
+        if (!this.jsonEnabled()) {
+            message = typeof message === 'string' ? message : (0, node_util_1.inspect)(message);
+            stream_1.stdout.write((0, node_util_1.format)(message, ...args) + '\n');
         }
-        if (this.ctor.state === 'deprecated') {
-            const cmdName = (0, util_2.toConfiguredId)(this.ctor.id, this.config);
-            this.warn((0, util_2.formatCommandDeprecationWarning)(cmdName, this.ctor.deprecationOptions));
+    }
+    logJson(json) {
+        cli_ux_1.ux.styledJSON(json);
+    }
+    logToStderr(message = '', ...args) {
+        if (!this.jsonEnabled()) {
+            message = typeof message === 'string' ? message : (0, node_util_1.inspect)(message);
+            stream_1.stderr.write((0, node_util_1.format)(message, ...args) + '\n');
         }
     }
     async parse(options, argv = this.argv) {
         if (!options)
             options = this.ctor;
-        const opts = { context: this, ...options };
-        // the spread operator doesn't work with getters so we have to manually add it here
-        opts.flags = options?.flags;
-        opts.args = options?.args;
+        const opts = {
+            context: this,
+            ...options,
+            flags: (0, aggregate_flags_1.aggregateFlags)(options.flags, options.baseFlags, options.enableJsonFlag),
+        };
         const results = await Parser.parse(argv, opts);
         this.warnIfFlagDeprecated(results.flags ?? {});
         return results;
     }
-    async catch(err) {
-        process.exitCode = process.exitCode ?? err.exitCode ?? 1;
-        if (this.jsonEnabled()) {
-            this.logJson(this.toErrorJson(err));
-        }
-        else {
-            if (!err.message)
-                throw err;
-            try {
-                ux_1.default.action.stop(chalk.bold.red('!'));
-            }
-            catch { }
-            throw err;
-        }
-    }
-    async finally(_) {
-        try {
-            const config = Errors.config;
-            if (config.errorLogger)
-                await config.errorLogger.flush();
-        }
-        catch (error) {
-            console.error(error);
-        }
+    toErrorJson(err) {
+        return { error: err };
     }
     toSuccessJson(result) {
         return result;
     }
-    toErrorJson(err) {
-        return { error: err };
-    }
-    logJson(json) {
-        ux_1.default.styledJSON(json);
+    warn(input) {
+        if (!this.jsonEnabled())
+            Errors.warn(input);
+        return input;
     }
-    removeEnvVar(envVar) {
-        const keys = [];
-        try {
-            keys.push(...this.config.scopedEnvVarKeys(envVar));
+    warnIfCommandDeprecated() {
+        const [id] = (0, util_1.normalizeArgv)(this.config);
+        if (this.ctor.deprecateAliases && this.ctor.aliases.includes(id)) {
+            const cmdName = (0, util_1.toConfiguredId)(this.ctor.id, this.config);
+            const aliasName = (0, util_1.toConfiguredId)(id, this.config);
+            this.warn((0, util_1.formatCommandDeprecationWarning)(aliasName, { to: cmdName }));
         }
-        catch {
-            keys.push(this.config.scopedEnvVarKey(envVar));
+        if (this.ctor.state === 'deprecated') {
+            const cmdName = (0, util_1.toConfiguredId)(this.ctor.id, this.config);
+            this.warn((0, util_1.formatCommandDeprecationWarning)(cmdName, this.ctor.deprecationOptions));
+        }
+    }
+    warnIfFlagDeprecated(flags) {
+        const allFlags = (0, aggregate_flags_1.aggregateFlags)(this.ctor.flags, this.ctor.baseFlags, this.ctor.enableJsonFlag);
+        for (const flag of Object.keys(flags)) {
+            const flagDef = allFlags[flag];
+            const deprecated = flagDef?.deprecated;
+            if (deprecated) {
+                this.warn((0, util_1.formatFlagDeprecationWarning)(flag, deprecated));
+            }
+            const deprecateAliases = flagDef?.deprecateAliases;
+            if (deprecateAliases) {
+                const aliases = (0, util_2.uniq)([...(flagDef?.aliases ?? []), ...(flagDef?.charAliases ?? [])]).map((a) => a.length === 1 ? `-${a}` : `--${a}`);
+                if (aliases.length === 0)
+                    return;
+                const foundAliases = aliases.filter((alias) => this.argv.some((a) => a.startsWith(alias)));
+                for (const alias of foundAliases) {
+                    let preferredUsage = `--${flagDef?.name}`;
+                    if (flagDef?.char) {
+                        preferredUsage += ` | -${flagDef?.char}`;
+                    }
+                    this.warn((0, util_1.formatFlagDeprecationWarning)(alias, { to: preferredUsage }));
+                }
+            }
         }
-        keys.map(key => delete process.env[key]);
+    }
+    get ctor() {
+        return this.constructor;
     }
 }
 exports.Command = Command;
-Command._base = `${pjson.name}@${pjson.version}`;
-/** An array of aliases for this command. */
-Command.aliases = [];
-/** When set to false, allows a variable amount of arguments */
-Command.strict = true;
-/** An order-dependent object of arguments for the command */
-Command.args = {};
-Command.hasDynamicHelp = false;
-Command['_--'] = false;
-Command._enableJsonFlag = false;