feat: add state property (#206)

* feat: add state property

* chore: code review

Author: mdonnalley

src/command.ts

@@ -49,6 +49,9 @@ export default abstract class Command {
   /** Hide the command from help? */
   static hidden: boolean
 
+  /** Mark the command as a given state (e.g. beta) in help? */
+  static state?: string;
+
   /**
    * An override string (or strings) for the default usage documentation.
    */
@@ -111,7 +114,7 @@ export default abstract class Command {
 
   private static globalFlags = {
     json: Flags.boolean({
-      description: 'format output as json',
+      description: 'Format output as json.',
       helpGroup: 'GLOBAL',
     }),
   }

src/config/config.ts

@@ -585,6 +585,7 @@ export async function toCached(c: Command.Class, plugin?: IPlugin): Promise<Comm
     pluginAlias: plugin && plugin.alias,
     pluginType: plugin && plugin.type,
     hidden: c.hidden,
+    state: c.state,
     aliases: c.aliases || [],
     examples: c.examples || (c as any).example,
     flags,

src/help/index.ts

@@ -39,14 +39,14 @@ export abstract class HelpBase extends HelpFormatter {
    * Show help, used in multi-command CLIs
    * @param args passed into your command, useful for determining which type of help to display
    */
-  public abstract async showHelp(argv: string[]): Promise<void>;
+  public abstract showHelp(argv: string[]): Promise<void>;
 
   /**
    * Show help for an individual command
    * @param command
    * @param topics
    */
-  public abstract async showCommandHelp(command: Interfaces.Command, topics: Interfaces.Topic[]): Promise<void>;
+  public abstract showCommandHelp(command: Interfaces.Command, topics: Interfaces.Topic[]): Promise<void>;
 }
 
 export class Help extends HelpBase {
@@ -108,7 +108,7 @@ export class Help extends HelpBase {
     }
 
     const topic = this.config.findTopic(subject)
-    if (topic)  {
+    if (topic) {
       await this.showTopicHelp(topic)
       return
     }
@@ -122,6 +122,10 @@ export class Help extends HelpBase {
 
     const subTopics = this.sortedTopics.filter(t => t.name.startsWith(name + ':') && t.name.split(':').length === depth + 1)
     const subCommands = this.sortedCommands.filter(c => c.id.startsWith(name + ':') && c.id.split(':').length === depth + 1)
+    const plugin = this.config.plugins.find(p => p.name === command.pluginName)
+
+    const state = this.config.pjson?.oclif?.state || plugin?.pjson?.oclif?.state || command.state
+    if (state) console.log(`This command is in ${state}.\n`)
 
     const summary = this.summary(command)
     if (summary) console.log(summary + '\n')
@@ -143,6 +147,8 @@ export class Help extends HelpBase {
     let rootTopics = this.sortedTopics
     let rootCommands = this.sortedCommands
 
+    const state = this.config.pjson?.oclif?.state
+    if (state) console.log(`${this.config.bin} is in ${state}.\n`)
     console.log(this.formatRoot())
     console.log('')
 
@@ -170,6 +176,9 @@ export class Help extends HelpBase {
     const subTopics = this.sortedTopics.filter(t => t.name.startsWith(name + ':') && t.name.split(':').length === depth + 1)
     const commands = this.sortedCommands.filter(c => c.id.startsWith(name + ':') && c.id.split(':').length === depth + 1)
 
+    const state = this.config.pjson?.oclif?.state
+    if (state) console.log(`This topic is in ${state}.\n`)
+
     console.log(this.formatTopic(topic))
 
     if (subTopics.length > 0) {

src/interfaces/command.ts

@@ -13,6 +13,9 @@ export interface CommandProps {
   /** Hide the command from help? */
   hidden: boolean;
 
+  /** Mark the command as a given state (e.g. beta) in help? */
+  state?: string;
+
   /** An array of aliases for this command. */
   aliases: string[];
 

src/interfaces/pjson.ts

@@ -45,6 +45,7 @@ export namespace PJSON {
       };
       additionalHelpFlags?: string[];
       additionalVersionFlags?: string[];
+      state?: string;
     };
   }
 

test/help/format-command.test.ts

@@ -81,7 +81,7 @@ FLAGS
                         newliney
 
 GLOBAL FLAGS
-  --json  format output as json
+  --json  Format output as json.
 
 DESCRIPTION
   first line
@@ -139,7 +139,7 @@ FLAGS
                         newliney
 
 GLOBAL FLAGS
-  --json  format output as json
+  --json  Format output as json.
 
 DESCRIPTION
   description of apps:create
@@ -199,7 +199,7 @@ FLAGS
       newliney
 
 GLOBAL FLAGS
-  --json  format output as json
+  --json  Format output as json.
 
 DESCRIPTION
   description of apps:create
@@ -261,7 +261,7 @@ FLAGS
   --force  forces
 
 GLOBAL FLAGS
-  --json  format output as json
+  --json  Format output as json.
 
 DESCRIPTION
   description of apps:create