@oclif/core 3.0.0-beta.17 → 3.0.0-beta.19

package/lib/command.js

@@ -6,14 +6,14 @@ const Errors = tslib_1.__importStar(require("./errors"));
 const Parser = tslib_1.__importStar(require("./parser"));
 const node_util_1 = require("node:util");
 const util_1 = require("./help/util");
-const util_2 = require("./util");
+const index_1 = require("./util/index");
 const stream_1 = require("./cli-ux/stream");
 const config_1 = require("./config");
-const flags_1 = require("./flags");
+const aggregate_flags_1 = require("./util/aggregate-flags");
 const chalk_1 = tslib_1.__importDefault(require("chalk"));
 const node_url_1 = require("node:url");
 const cli_ux_1 = require("./cli-ux");
-const pjson = (0, util_2.requireJson)(__dirname, '..', 'package.json');
+const pjson = (0, index_1.requireJson)(__dirname, '..', 'package.json');
 /**
  * swallows stdout epipe errors
  * this occurs when stdout closes such as when piping to head
@@ -23,40 +23,68 @@ 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;
-        }
-        else {
-            delete this.baseFlags?.json;
-            this.flags = {}; // force the flags setter to run
-            delete this.flags?.json;
-        }
-    }
-    static get '--'() {
-        return Command['_--'];
-    }
-    static set '--'(value) {
-        Command['_--'] = value;
-    }
-    get passThroughEnabled() {
-        return Command['_--'];
-    }
+    argv;
+    config;
+    static _base = `${pjson.name}@${pjson.version}`;
+    /** A command ID, used mostly in error or verbose reporting. */
+    static id;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Hide the command from help */
+    static hidden;
+    /** Mark the command as a given state (e.g. beta or deprecated) in help */
+    static state;
+    static deprecationOptions;
+    /**
+     * Emit deprecation warning when a command alias is used
+     */
+    static deprecateAliases;
+    /**
+     * An override string (or strings) for the default usage documentation.
+     */
+    static usage;
+    static help;
+    /** An array of aliases for this command. */
+    static aliases = [];
+    /** When set to false, allows a variable amount of arguments */
+    static strict = true;
+    /** An order-dependent object of arguments for the command */
+    static args = {};
+    static plugin;
+    static pluginName;
+    static pluginType;
+    static pluginAlias;
+    /**
+     * 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;
+    static hasDynamicHelp = false;
+    static enableJsonFlag = false;
     /**
      * instantiate and run the command
      *
@@ -81,21 +109,11 @@ class Command {
         }
         return cmd._run();
     }
-    static get baseFlags() {
-        return this._baseFlags;
-    }
-    static set baseFlags(flags) {
-        // eslint-disable-next-line prefer-object-spread
-        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) {
-        // eslint-disable-next-line prefer-object-spread
-        this._flags = Object.assign({}, this._flags ?? {}, this.baseFlags, flags);
-    }
+    static baseFlags;
+    /** A hash of flags for the command */
+    static flags;
+    id;
+    debug;
     constructor(argv, config) {
         this.argv = argv;
         this.config = config;
@@ -161,16 +179,19 @@ class Command {
      * @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 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);
-        }
-        return this.argv.includes('--json') || this.config.scopedEnvVar?.('CONTENT_TYPE')?.toLowerCase() === 'json';
+        // 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;
     }
     async init() {
         this.debug('init version: %s argv: %o', this.ctor._base, this.argv);
@@ -184,18 +205,19 @@ class Command {
         this.warnIfCommandDeprecated();
     }
     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 = this.ctor.flags[flag];
+            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}`);
+                const aliases = (0, index_1.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)));
+                const foundAliases = aliases.filter((alias) => this.argv.some((a) => a.startsWith(alias)));
                 for (const alias of foundAliases) {
                     let preferredUsage = `--${flagDef?.name}`;
                     if (flagDef?.char) {
@@ -221,10 +243,11 @@ class Command {
     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;
@@ -271,17 +294,7 @@ class Command {
         catch {
             keys.push(this.config.scopedEnvVarKey(envVar));
         }
-        keys.map(key => delete process.env[key]);
+        keys.map((key) => delete process.env[key]);
     }
 }
 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;

package/lib/config/config.d.ts

@@ -144,14 +144,13 @@ export declare class Config implements IConfig {
      */
     private determinePriority;
     /**
-      * Insert legacy plugins
-      *
-      * Replace invalid CLI plugins (cli-engine plugins, mostly Heroku) loaded via `this.loadPlugins`
-      * with oclif-compatible ones returned by @oclif/plugin-legacy init hook.
-      *
-      * @param plugins array of oclif-compatible plugins
-      * @returns void
-      */
+     * Insert legacy plugins
+     *
+     * Replace invalid CLI plugins (cli-engine plugins, mostly Heroku) loaded via `this.loadPlugins`
+     * with oclif-compatible ones returned by @oclif/plugin-legacy init hook.
+     *
+     * @param plugins array of oclif-compatible plugins
+     * @returns void
+     */
     private insertLegacyPlugins;
 }
-export declare function toCached(c: Command.Class, plugin?: IPlugin, respectNoCacheDefault?: boolean): Promise<Command.Cached>;