@oclif/core 3.0.0-beta.2 → 3.0.0-beta.21

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 cli_ux_1 = require("./cli-ux");
-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 tslib_1 = require("tslib");
+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 stream_1 = require("./cli-ux/stream");
-const pjson = (0, util_3.requireJson)(__dirname, '..', 'package.json');
+const config_1 = require("./config");
+const aggregate_flags_1 = require("./util/aggregate-flags");
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const node_url_1 = require("node:url");
+const fs_1 = require("./util/fs");
+const util_2 = require("./util/util");
+const cli_ux_1 = require("./cli-ux");
+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,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
      *
@@ -69,7 +99,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,19 +110,11 @@ 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);
-    }
+    static baseFlags;
+    /** A hash of flags for the command */
+    static flags;
+    id;
+    debug;
     constructor(argv, config) {
         this.argv = argv;
         this.config = config;
@@ -101,7 +123,9 @@ class Command {
             this.debug = require('debug')(this.id ? `${this.config.bin}:${this.id}` : this.config.bin);
         }
         catch {
-            this.debug = () => { };
+            this.debug = () => {
+                // noop
+            };
         }
     }
     get ctor() {
@@ -140,14 +164,14 @@ class Command {
     }
     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');
+            message = typeof message === 'string' ? message : (0, node_util_1.inspect)(message);
+            stream_1.stdout.write((0, node_util_1.format)(message, ...args) + '\n');
         }
     }
     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');
+            message = typeof message === 'string' ? message : (0, node_util_1.inspect)(message);
+            stream_1.stderr.write((0, node_util_1.format)(message, ...args) + '\n');
         }
     }
     /**
@@ -156,16 +180,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);
@@ -179,45 +206,49 @@ 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_2.formatFlagDeprecationWarning)(flag, deprecated));
+                this.warn((0, util_1.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)));
+            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_2.formatFlagDeprecationWarning)(alias, { to: preferredUsage }));
+                    this.warn((0, util_1.formatFlagDeprecationWarning)(alias, { to: preferredUsage }));
                 }
             }
         }
     }
     warnIfCommandDeprecated() {
-        const [id] = (0, util_2.normalizeArgv)(this.config);
+        const [id] = (0, util_1.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 }));
+            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 }));
         }
         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));
+            const cmdName = (0, util_1.toConfiguredId)(this.ctor.id, this.config);
+            this.warn((0, util_1.formatCommandDeprecationWarning)(cmdName, this.ctor.deprecationOptions));
         }
     }
     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;
@@ -231,7 +262,7 @@ class Command {
             if (!err.message)
                 throw err;
             try {
-                cli_ux_1.ux.action.stop(chalk.bold.red('!'));
+                cli_ux_1.ux.action.stop(chalk_1.default.bold.red('!'));
             }
             catch { }
             throw err;
@@ -239,7 +270,7 @@ class Command {
     }
     async finally(_) {
         try {
-            const config = Errors.config;
+            const { config } = Errors;
             if (config.errorLogger)
                 await config.errorLogger.flush();
         }
@@ -264,17 +295,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

@@ -1,7 +1,6 @@
-import { Options, Plugin as IPlugin } from '../interfaces/plugin';
-import { Config as IConfig, ArchTypes, PlatformTypes, LoadOptions, VersionDetails } from '../interfaces/config';
+import { ArchTypes, Config as IConfig, LoadOptions, PlatformTypes, VersionDetails } from '../interfaces/config';
 import { Hook, Hooks, PJSON, Topic } from '../interfaces';
-import * as Plugin from './plugin';
+import { Plugin as IPlugin, Options } from '../interfaces/plugin';
 import { Command } from '../command';
 export declare class Config implements IConfig {
     options: Options;
@@ -22,7 +21,7 @@ export declare class Config implements IConfig {
     npmRegistry?: string;
     pjson: PJSON.CLI;
     platform: PlatformTypes;
-    plugins: IPlugin[];
+    plugins: Map<string, IPlugin>;
     root: string;
     shell: string;
     topicSeparator: ':' | ' ';
@@ -39,15 +38,15 @@ export declare class Config implements IConfig {
     private _commands;
     private _topics;
     private _commandIDs;
+    private pluginLoader;
     private static _rootPlugin;
     constructor(options: Options);
     static load(opts?: LoadOptions): Promise<Config>;
-    static get rootPlugin(): Plugin.Plugin | undefined;
+    static get rootPlugin(): IPlugin | undefined;
     load(): Promise<void>;
-    loadPluginsAndCommands(): Promise<void>;
-    loadCorePlugins(): Promise<void>;
-    loadDevPlugins(): Promise<void>;
-    loadUserPlugins(): Promise<void>;
+    loadPluginsAndCommands(opts?: {
+        force: boolean;
+    }): Promise<void>;
     runHook<T extends keyof Hooks>(event: T, opts: Hooks[T]['options'], timeout?: number, captureErrors?: boolean): Promise<Hook.Result<Hooks[T]['return']>>;
     runCommand<T = unknown>(id: string, argv?: string[], cachedCommand?: Command.Loadable | null): Promise<T>;
     scopedEnvVar(k: string): string | undefined;
@@ -114,11 +113,6 @@ export declare class Config implements IConfig {
     protected macosCacheDir(): string | undefined;
     protected _shell(): string;
     protected _debug(): number;
-    protected loadPlugins(root: string, type: string, plugins: (string | {
-        root?: string;
-        name?: string;
-        tag?: string;
-    })[], parent?: Plugin.Plugin): Promise<void>;
     protected warn(err: string | Error | {
         name: string;
         detail: string;
@@ -150,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 | undefined, isWritingManifest?: boolean): Promise<Command.Cached>;