@oclif/core 3.0.9 → 3.1.0

package/lib/command.d.ts

@@ -49,6 +49,8 @@ export declare abstract class Command {
     static help: string | undefined;
     /** Hide the command from help */
     static hidden: boolean;
+    /** An array of aliases for this command that are hidden from help. */
+    static hiddenAliases: string[];
     /** A command ID, used mostly in error or verbose reporting. */
     static id: string;
     static plugin: Plugin | undefined;
@@ -155,6 +157,7 @@ export declare namespace Command {
         };
         hasDynamicHelp?: boolean;
         hidden: boolean;
+        hiddenAliases: string[];
         id: string;
         isESM?: boolean;
         permutations?: string[];

package/lib/command.js

@@ -94,6 +94,8 @@ class Command {
     static help;
     /** Hide the command from help */
     static hidden;
+    /** An array of aliases for this command that are hidden from help. */
+    static hiddenAliases = [];
     /** A command ID, used mostly in error or verbose reporting. */
     static id;
     static plugin;

package/lib/config/config.js

@@ -704,14 +704,13 @@ class Config {
             for (const permutation of permutations) {
                 this.commandPermutations.add(permutation, command.id);
             }
-            // set command aliases
-            for (const alias of command.aliases ?? []) {
+            const handleAlias = (alias, hidden = false) => {
                 if (this._commands.has(alias)) {
                     const prioritizedCommand = this.determinePriority([this._commands.get(alias), command]);
                     this._commands.set(alias, { ...prioritizedCommand, id: alias });
                 }
                 else {
-                    this._commands.set(alias, { ...command, id: alias });
+                    this._commands.set(alias, { ...command, hidden, id: alias });
                 }
                 // set every permutation of the aliases
                 // v3 moved command alias permutations to the manifest, but some plugins may not have
@@ -723,6 +722,14 @@ class Config {
                 for (const permutation of aliasPermutations) {
                     this.commandPermutations.add(permutation, command.id);
                 }
+            };
+            // set command aliases
+            for (const alias of command.aliases ?? []) {
+                handleAlias(alias);
+            }
+            // set hidden command aliases
+            for (const alias of command.hiddenAliases ?? []) {
+                handleAlias(alias, true);
             }
         }
         marker?.addDetails({ commandCount: plugin.commands.length });

package/lib/flags.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.option = exports.help = exports.version = exports.string = exports.url = exports.file = exports.directory = exports.integer = exports.boolean = exports.custom = void 0;
-/* eslint-disable valid-jsdoc */
 const node_url_1 = require("node:url");
 const errors_1 = require("./errors");
 const help_1 = require("./help");
@@ -98,7 +97,7 @@ const help = (opts = {}) => boolean({
     ...opts,
     async parse(_, cmd) {
         const Help = await (0, help_1.loadHelpClass)(cmd.config);
-        await new Help(cmd.config, cmd.config.pjson.helpOptions).showHelp(cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv);
+        await new Help(cmd.config, cmd.config.pjson.oclif.helpOptions ?? cmd.config.pjson.helpOptions).showHelp(cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv);
         cmd.exit(0);
     },
 });

package/lib/help/index.js

@@ -82,7 +82,9 @@ class Help extends HelpBase {
     formatCommands(commands) {
         if (commands.length === 0)
             return '';
-        const body = this.renderList(commands.map((c) => {
+        const body = this.renderList(commands
+            .filter((c) => (this.opts.hideAliasesFromRoot ? !c.aliases?.includes(c.id) : true))
+            .map((c) => {
             if (this.config.topicSeparator !== ':')
                 c.id = c.id.replaceAll(':', this.config.topicSeparator);
             return [c.id, this.summary(c)];

package/lib/interfaces/help.d.ts

@@ -4,6 +4,10 @@ export interface HelpOptions {
      * Use docopts as the usage. Defaults to true.
      */
     docopts?: boolean;
+    /**
+     * If true, hide command aliases from the root help output. Defaults to false.
+     */
+    hideAliasesFromRoot?: boolean;
     /**
      * By default, the command summary is show at the top of the help and as the first line in
      * the command description. Repeating the summary in the command description improves readability

package/lib/main.js

@@ -64,7 +64,7 @@ async function run(argv, options) {
     // display help version if applicable
     if ((0, exports.helpAddition)(argv, config)) {
         const Help = await (0, help_1.loadHelpClass)(config);
-        const help = new Help(config, config.pjson.helpOptions);
+        const help = new Help(config, config.pjson.oclif.helpOptions ?? config.pjson.helpOptions);
         await help.showHelp(argv);
         await collectPerf();
         return;

package/lib/util/cache-command.js

@@ -75,15 +75,17 @@ async function cacheCommand(uncachedCmd, plugin, respectNoCacheDefault = false)
     const flags = await cacheFlags((0, aggregate_flags_1.aggregateFlags)(uncachedFlags, uncachedBaseFlags, cmd.enableJsonFlag), respectNoCacheDefault);
     const args = await cacheArgs((0, ensure_arg_object_1.ensureArgObject)(cmd.args), respectNoCacheDefault);
     const stdProperties = {
-        aliases: cmd.aliases || [],
+        aliases: cmd.aliases ?? [],
         args,
         deprecateAliases: cmd.deprecateAliases,
         deprecationOptions: cmd.deprecationOptions,
         description: cmd.description,
-        examples: cmd.examples || cmd.example,
+        // Support both `examples` and `example` for backwards compatibility.
+        examples: cmd.examples ?? cmd.example,
         flags,
         hasDynamicHelp: Object.values(flags).some((f) => f.hasDynamicHelp),
         hidden: cmd.hidden,
+        hiddenAliases: cmd.hiddenAliases ?? [],
         id: cmd.id,
         pluginAlias: plugin && plugin.alias,
         pluginName: plugin && plugin.name,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "3.0.9",
+  "version": "3.1.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {