From 07f9092128f979e3e4e22aeee07bf4d4caa3024c Mon Sep 17 00:00:00 2001
From: Mike Donnalley <mdonnalley@salesforce.com>
Date: Tue, 3 Aug 2021 10:32:12 -0700
Subject: [PATCH] feat: add state property (#206)

* feat: add state property

* chore: code review
---
 src/command.ts                   |  5 ++++-
 src/config/config.ts             |  1 +
 src/help/index.ts                | 15 ++++++++++++---
 src/interfaces/command.ts        |  3 +++
 src/interfaces/pjson.ts          |  1 +
 test/help/format-command.test.ts |  8 ++++----
 6 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/src/command.ts b/src/command.ts
index c2bc62f52..6bffd9b42 100644
--- a/src/command.ts
+++ b/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',
     }),
   }
diff --git a/src/config/config.ts b/src/config/config.ts
index ce8df6650..c8df7d40b 100644
--- a/src/config/config.ts
+++ b/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,
diff --git a/src/help/index.ts b/src/help/index.ts
index 9ba2f3282..ba373de98 100644
--- a/src/help/index.ts
+++ b/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) {
diff --git a/src/interfaces/command.ts b/src/interfaces/command.ts
index 20068c41e..35e4064f0 100644
--- a/src/interfaces/command.ts
+++ b/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[];
 
diff --git a/src/interfaces/pjson.ts b/src/interfaces/pjson.ts
index ca0f53451..11b81db7d 100644
--- a/src/interfaces/pjson.ts
+++ b/src/interfaces/pjson.ts
@@ -45,6 +45,7 @@ export namespace PJSON {
       };
       additionalHelpFlags?: string[];
       additionalVersionFlags?: string[];
+      state?: string;
     };
   }
 
diff --git a/test/help/format-command.test.ts b/test/help/format-command.test.ts
index b6dc28fcd..589bc5311 100644
--- a/test/help/format-command.test.ts
+++ b/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