Include crucial config keys in the config sub-command short --help, while only showing others in --full-help

Author: Gedochao

modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala

@@ -2,6 +2,7 @@ package scala.cli.commands.config
 
 import caseapp.*
 
+import scala.build.internal.util.ConsoleUtils.ScalaCliConsole
 import scala.cli.ScalaCli.{fullRunnerName, progName}
 import scala.cli.commands.pgp.PgpScalaSigningOptions
 import scala.cli.commands.shared.{
@@ -90,18 +91,24 @@ object ConfigOptions {
   private val websiteSuffix      = s"misc/$cmdName"
   val helpMessage: String =
     s"""$helpHeader
+       |
+       |Available keys:
+       |  ${configKeysBulletPoints(includeHidden = false).mkString(s"${System.lineSeparator}  ")}
        |
        |${HelpMessages.commandFullHelpReference(cmdName)}
        |${HelpMessages.commandDocWebsiteReference(websiteSuffix)}""".stripMargin
-  private val configKeysBulletPoints: Seq[String] = {
-    val keys: Seq[Key[_]] = Keys.map.values.toSeq
-    val maxFullNameLength = keys.map(_.fullName.length).max
+  private def configKeysBulletPoints(includeHidden: Boolean): Seq[String] = {
+    val allKeys: Seq[Key[_]] = Keys.map.values.toSeq
+    val keys: Seq[Key[_]]    = if includeHidden then allKeys else allKeys.filterNot(_.hidden)
+    val maxFullNameLength    = keys.map(_.fullName.length).max
     keys.sortBy(_.fullName)
       .map { key =>
         val currentKeyFullNameLength = maxFullNameLength - key.fullName.length
         val extraSpaces =
           if currentKeyFullNameLength > 0 then " " * currentKeyFullNameLength else ""
-        s"- ${Console.YELLOW}${key.fullName}${Console.RESET}$extraSpaces  ${key.description}"
+        val hiddenString =
+          if key.hidden then s"${ScalaCliConsole.GRAY}(hidden)${Console.RESET} " else ""
+        s"- ${Console.YELLOW}${key.fullName}${Console.RESET}$extraSpaces  $hiddenString${key.description}"
       }
   }
   val detailedHelpMessage: String =
@@ -113,7 +120,7 @@ object ConfigOptions {
        |  ${Console.BOLD}$progName $cmdName interactive true${Console.RESET}
        |  
        |Available keys:
-       |  ${configKeysBulletPoints.mkString(s"${System.lineSeparator}  ")}
+       |  ${configKeysBulletPoints(includeHidden = true).mkString(s"${System.lineSeparator}  ")}
        |
        |${HelpMessages.commandDocWebsiteReference(websiteSuffix)}""".stripMargin
 }

modules/config/src/main/scala/scala/cli/config/Key.scala

@@ -41,6 +41,9 @@ abstract class Key[T] {
   /** A short description of a particular key's purpose and syntax for its values. */
   def description: String
 
+  /** A flag indicating whether the key should by default be hidden in help outputs or not. */
+  def hidden: Boolean = false
+
   /** Whether this key corresponds to a password (see [[Key.PasswordEntry]]) */
   def isPasswordOption: Boolean = false
 }
@@ -80,7 +83,8 @@ object Key {
   final class StringEntry(
     val prefix: Seq[String],
     val name: String,
-    val description: String = ""
+    val description: String = "",
+    override val hidden: Boolean = false
   ) extends Key[String] {
     def parse(json: Array[Byte]): Either[EntryError, String] =
       try Right(readFromArray(json)(stringCodec))
@@ -102,7 +106,8 @@ object Key {
   final class BooleanEntry(
     val prefix: Seq[String],
     val name: String,
-    val description: String = ""
+    val description: String = "",
+    override val hidden: Boolean = false
   ) extends Key[Boolean] {
     def parse(json: Array[Byte]): Either[EntryError, Boolean] =
       try Right(readFromArray(json)(booleanCodec))
@@ -124,7 +129,8 @@ object Key {
   final class PasswordEntry(
     val prefix: Seq[String],
     val name: String,
-    val description: String = ""
+    val description: String = "",
+    override val hidden: Boolean = false
   ) extends Key[PasswordOption] {
     def parse(json: Array[Byte]): Either[EntryError, PasswordOption] =
       try {
@@ -157,7 +163,8 @@ object Key {
   final class StringListEntry(
     val prefix: Seq[String],
     val name: String,
-    val description: String = ""
+    val description: String = "",
+    override val hidden: Boolean = false
   ) extends Key[List[String]] {
     def parse(json: Array[Byte]): Either[EntryError, List[String]] =
       try Right(readFromArray(json)(stringListCodec))

modules/config/src/main/scala/scala/cli/config/Keys.scala

@@ -10,39 +10,46 @@ object Keys {
   val userName = new Key.StringEntry(
     prefix = Seq("publish", "user"),
     name = "name",
-    description = "The 'name' user detail, used for publishing."
+    description = "The 'name' user detail, used for publishing.",
+    hidden = true
   )
   val userEmail = new Key.StringEntry(
     prefix = Seq("publish", "user"),
     name = "email",
-    description = "The 'email' user detail, used for publishing."
+    description = "The 'email' user detail, used for publishing.",
+    hidden = true
   )
   val userUrl = new Key.StringEntry(
     prefix = Seq("publish", "user"),
     name = "url",
-    description = "The 'url' user detail, used for publishing."
+    description = "The 'url' user detail, used for publishing.",
+    hidden = true
   )
 
   val ghToken = new Key.PasswordEntry(
     prefix = Seq("github"),
     name = "token",
-    description = "GitHub token."
+    description = "GitHub token.",
+    hidden = true
   )
 
   val pgpSecretKey = new Key.PasswordEntry(
     prefix = Seq("pgp"),
     name = "secret-key",
-    description = "The PGP secret key, used for signing."
+    description = "The PGP secret key, used for signing.",
+    hidden = true
   )
   val pgpSecretKeyPassword = new Key.PasswordEntry(
     prefix = Seq("pgp"),
     name = "secret-key-password",
-    description = "The PGP secret key password, used for signing."
+    description = "The PGP secret key password, used for signing.",
+    hidden = true
   )
   val pgpPublicKey = new Key.PasswordEntry(
     prefix = Seq("pgp"),
     name = "public-key",
-    description = "The PGP public key, used for signing."
+    description = "The PGP public key, used for signing.",
+    hidden = true
   )
 
   val actions = new Key.BooleanEntry(
@@ -78,30 +85,35 @@ object Keys {
   val proxyAddress = new Key.StringEntry(
     prefix = Seq("httpProxy"),
     name = "address",
-    description = "HTTP proxy address."
+    description = "HTTP proxy address.",
+    hidden = true
   )
   val proxyUser = new Key.PasswordEntry(
     prefix = Seq("httpProxy"),
     name = "user",
-    description = "HTTP proxy user (used for authentication)."
+    description = "HTTP proxy user (used for authentication).",
+    hidden = true
   )
   val proxyPassword = new Key.PasswordEntry(
     prefix = Seq("httpProxy"),
     name = "password",
-    description = "HTTP proxy password (used for authentication)."
+    description = "HTTP proxy password (used for authentication).",
+    hidden = true
   )
 
   val repositoryMirrors = new Key.StringListEntry(
     prefix = Seq("repositories"),
     name = "mirrors",
     description =
-      s"Repository mirrors, syntax: repositories.mirrors maven:*=https://repository.company.com/maven"
+      s"Repository mirrors, syntax: repositories.mirrors maven:*=https://repository.company.com/maven",
+    hidden = true
   )
   val defaultRepositories = new Key.StringListEntry(
     prefix = Seq("repositories"),
     name = "default",
     description =
-      "Default repository, syntax: https://first-repo.company.com https://second-repo.company.com"
+      "Default repository, syntax: https://first-repo.company.com https://second-repo.company.com",
+    hidden = true
   )
 
   // Kept for binary compatibility
@@ -111,7 +123,8 @@ object Keys {
   val globalInteractiveWasSuggested = new Key.BooleanEntry(
     prefix = Seq.empty,
     name = "interactive-was-suggested",
-    description = "Setting indicating if the global interactive mode was already suggested."
+    description = "Setting indicating if the global interactive mode was already suggested.",
+    hidden = true
   )
 
   def all: Seq[Key[_]] = Seq[Key[_]](
@@ -196,6 +209,7 @@ object Keys {
   val repositoryCredentials: Key[List[RepositoryCredentials]] =
     new Key[List[RepositoryCredentials]] {
       override val description: String = "Repository credentials, syntax: value:user value:password"
+      override val hidden: Boolean     = true
 
       private def asJson(credentials: RepositoryCredentials): RepositoryCredentialsAsJson =
         RepositoryCredentialsAsJson(
@@ -320,6 +334,7 @@ object Keys {
   val publishCredentials: Key[List[PublishCredentials]] = new Key[List[PublishCredentials]] {
     override val description: String =
       "Publishing credentials, syntax: s1.oss.sonatype.org value:user value:password"
+    override val hidden: Boolean = true
 
     private def asJson(credentials: PublishCredentials): PublishCredentialsAsJson =
       PublishCredentialsAsJson(

modules/generate-reference-doc/src/main/scala/scala/cli/doc/ReferenceDocUtils.scala

@@ -43,14 +43,16 @@ object ReferenceDocUtils {
             consoleToFenceRec(remainingLines.tail, newFenceOpen, newAcc)
       consoleToFenceRec(s.linesIterator.toSeq)
     }
+    def filterOutHiddenStrings: String =
+      s.replace(s"${ScalaCliConsole.GRAY}(hidden)${Console.RESET} ", "")
   }
   extension (helpMessage: HelpMessage) {
-    def referenceDocMessage: String = helpMessage.message.consoleToFence.noConsoleKeys
+    def referenceDocMessage: String = helpMessage.message.filterOutHiddenStrings.consoleToFence
     def referenceDocDetailedMessage: String = {
       val msg =
         if helpMessage.detailedMessage.nonEmpty then helpMessage.detailedMessage
         else helpMessage.message
-      msg.consoleToFence
+      msg.filterOutHiddenStrings.consoleToFence
     }
   }