Add environment variable help under --envs-help & refactor environment variable usage

modules/build/src/main/scala/scala/build/ConsoleBloopBuildClient.scala

@@ -8,7 +8,7 @@ import java.nio.file.Paths
 
 import scala.build.errors.Severity
 import scala.build.internal.WrapperParams
-import scala.build.internal.util.ConsoleUtils.ScalaCliConsole
+import scala.build.internals.ConsoleUtils.ScalaCliConsole
 import scala.build.options.Scope
 import scala.build.postprocessing.LineConversion.scalaLineToScLine
 import scala.collection.mutable

modules/build/src/main/scala/scala/build/Directories.scala

@@ -4,6 +4,7 @@ import coursier.cache.shaded.dirs.{GetWinDirs, ProjectDirectories}
 
 import scala.build.errors.ConfigDbException
 import scala.build.internal.JniGetWinDirs
+import scala.build.internals.EnvVar
 import scala.cli.config.ConfigDb
 import scala.util.Properties
 
@@ -19,7 +20,7 @@ trait Directories {
   def cacheDir: os.Path
 
   final def dbPath: os.Path =
-    Option(System.getenv("SCALA_CLI_CONFIG"))
+    EnvVar.ScalaCli.config.valueOpt
       .filter(_.trim.nonEmpty)
       .map(os.Path(_, os.pwd))
       .getOrElse(secretsDir / Directories.defaultDbFileName)
@@ -95,7 +96,7 @@ object Directories {
     SubDir(dir)
 
   lazy val directories: Directories =
-    Option(System.getenv("SCALA_CLI_HOME")).filter(_.trim.nonEmpty) match {
+    EnvVar.ScalaCli.home.valueOpt.filter(_.trim.nonEmpty) match {
       case None =>
         scala.build.Directories.default()
       case Some(homeDir) =>

modules/build/src/main/scala/scala/build/internal/Runner.scala

@@ -12,6 +12,7 @@ import java.nio.file.{Files, Path, Paths}
 import scala.build.EitherCps.{either, value}
 import scala.build.Logger
 import scala.build.errors._
+import scala.build.internals.EnvVar
 import scala.build.testrunner.{AsmTestRunner, TestRunner}
 import scala.util.{Failure, Properties, Success}
 
@@ -191,12 +192,12 @@ object Runner {
     if (Paths.get(app).getNameCount >= 2) Some(asIs)
     else {
       def pathEntries =
-        Option(System.getenv("PATH"))
+        EnvVar.Misc.path.valueOpt
           .iterator
           .flatMap(_.split(File.pathSeparator).iterator)
       def pathSep =
         if (Properties.isWin)
-          Option(System.getenv("PATHEXT"))
+          EnvVar.Misc.pathExt.valueOpt
             .iterator
             .flatMap(_.split(File.pathSeparator).iterator)
         else Iterator("")

modules/build/src/main/scala/scala/build/internal/zip/WrappedZipInputStream.scala

@@ -3,6 +3,8 @@ package scala.build.internal.zip
 import java.io.{Closeable, InputStream}
 import java.util.zip.ZipEntry
 
+import scala.build.internals.EnvVar
+
 /*
  * juz.ZipInputStream is buggy on Arch Linux from native images (CRC32 calculation issues,
  * see oracle/graalvm#4479), so we use a custom ZipInputStream with disabled CRC32 calculation.
@@ -35,7 +37,7 @@ object WrappedZipInputStream {
         case "true" | "1" => true
         case _            => false
       }
-    Option(System.getenv("SCALA_CLI_VENDORED_ZIS")).map(toBoolean)
+    EnvVar.ScalaCli.vendoredZipInputStream.valueOpt.map(toBoolean)
       .orElse(sys.props.get("scala-cli.zis.vendored").map(toBoolean))
       .getOrElse(false)
   }

modules/build/src/test/scala/scala/build/tests/util/BloopServer.scala

@@ -3,6 +3,7 @@ package scala.build.tests.util
 import bloop.rifle.BloopRifleConfig
 import coursier.cache.FileCache
 
+import scala.build.internals.EnvVar
 import scala.build.{Bloop, Logger}
 import scala.util.Properties
 
@@ -30,7 +31,7 @@ object BloopServer {
           // which can have issues with the directory of "java" in the PATH,
           // if it contains '+' or '%' IIRC.
           // So we hardcode the path to "java" here.
-          Option(System.getenv("JAVA_HOME"))
+          EnvVar.Java.javaHome.valueOpt
             .map(os.Path(_, os.pwd))
             .map(_ / "bin" / "java")
             .map(_.toString)

modules/cli/src/main/scala/scala/cli/ScalaCli.scala

@@ -11,6 +11,7 @@ import java.util.Locale
 
 import scala.build.Directories
 import scala.build.internal.Constants
+import scala.build.internals.EnvVar
 import scala.cli.config.{ConfigDb, Keys}
 import scala.cli.internal.Argv0
 import scala.cli.javaLauncher.JavaLauncherCli
@@ -45,7 +46,7 @@ object ScalaCli {
       powerEntry <- configDb.get(Keys.power).toOption
       power      <- powerEntry
     } yield power
-    val isPowerEnv = Option(System.getenv("SCALA_CLI_POWER")).flatMap(_.toBooleanOption)
+    val isPowerEnv = EnvVar.ScalaCli.power.valueOpt.flatMap(_.toBooleanOption)
     val isPower    = isPowerEnv.orElse(isPowerConfigDb).getOrElse(false)
     !isPower
   }
@@ -94,8 +95,8 @@ object ScalaCli {
     baos.toByteArray
   }
 
-  private def isCI = System.getenv("CI") != null
-  private def printStackTraces = Option(System.getenv("SCALA_CLI_PRINT_STACK_TRACES"))
+  private def isCI = EnvVar.Internal.ci.valueOpt.nonEmpty
+  private def printStackTraces = EnvVar.ScalaCli.printStackTraces.valueOpt
     .map(_.toLowerCase(Locale.ROOT))
     .exists {
       case "true" | "1" => true
@@ -157,7 +158,7 @@ object ScalaCli {
             // for https://github.com/VirtusLab/scala-cli/issues/828
             System.err.println(
               s"""Running
-                 |  export SCALA_CLI_VENDORED_ZIS=true
+                 |  export ${EnvVar.ScalaCli.vendoredZipInputStream.name}=true
                  |before running $fullRunnerName might fix the issue.
                  |""".stripMargin
             )
@@ -209,7 +210,8 @@ object ScalaCli {
       }
 
     // load java properties from JAVA_OPTS and JDK_JAVA_OPTIONS environment variables
-    val javaOpts = sys.env.get("JAVA_OPTS").toSeq ++ sys.env.get("JDK_JAVA_OPTIONS").toSeq
+    val javaOpts: Seq[String] =
+      EnvVar.Java.javaOpts.valueOpt.toSeq ++ EnvVar.Java.jdkJavaOpts.valueOpt.toSeq
 
     val ignoredJavaOpts =
       javaOpts
@@ -224,7 +226,8 @@ object ScalaCli {
         }.flatten
     if ignoredJavaOpts.nonEmpty then
       System.err.println(
-        s"Warning: Only java properties are supported in JAVA_OPTS and JDK_JAVA_OPTIONS environment variables. Other options are ignored: ${ignoredJavaOpts.mkString(", ")}"
+        s"Warning: Only java properties are supported in ${EnvVar.Java.javaOpts.name} and ${EnvVar
+            .Java.jdkJavaOpts.name} environment variables. Other options are ignored: ${ignoredJavaOpts.mkString(", ")}"
       )
   }
 

modules/cli/src/main/scala/scala/cli/commands/ScalaCommand.scala

@@ -20,7 +20,7 @@ import scala.build.errors.BuildException
 import scala.build.input.{ScalaCliInvokeData, SubCommand}
 import scala.build.internal.util.WarningMessages
 import scala.build.internal.{Constants, Runner}
-import scala.build.internals.FeatureType
+import scala.build.internals.{EnvVar, FeatureType}
 import scala.build.options.{BuildOptions, ScalacOpt, Scope}
 import scala.build.{Artifacts, Directories, Logger, Positioned, ReplArtifacts}
 import scala.cli.commands.default.LegacyScalaOptions
@@ -284,6 +284,11 @@ abstract class ScalaCommand[T <: HasGlobalOptions](implicit myParser: Parser[T],
       sys.exit(exitCode.orExit(logger))
     }
 
+  private def maybePrintEnvsHelp(options: T): Unit =
+    if sharedOptions(options).exists(_.helpGroups.helpEnvs) then
+      println(EnvVar.helpMessage(isPower = allowRestrictedFeatures))
+      sys.exit(0)
+
   override def helpFormat: HelpFormat = ScalaCliHelp.helpFormat
 
   override val messages: Help[T] =
@@ -378,6 +383,7 @@ abstract class ScalaCommand[T <: HasGlobalOptions](implicit myParser: Parser[T],
       maybePrintSimpleScalacOutput(options, bo)
       maybePrintToolsHelp(options, bo)
     }
+    maybePrintEnvsHelp(options)
     logger.flushExperimentalWarnings
     runCommand(options, remainingArgs, options.global.logging.logger)
   }

modules/cli/src/main/scala/scala/cli/commands/WatchUtil.scala

@@ -2,7 +2,7 @@ package scala.cli.commands
 
 import scala.annotation.tailrec
 import scala.build.internal.StdInConcurrentReader
-import scala.build.internal.util.ConsoleUtils.ScalaCliConsole
+import scala.build.internals.ConsoleUtils.ScalaCliConsole
 
 object WatchUtil {
 

modules/cli/src/main/scala/scala/cli/commands/addpath/AddPath.scala

@@ -6,6 +6,7 @@ import coursier.env.{EnvironmentUpdate, ProfileUpdater}
 import java.io.File
 
 import scala.build.Logger
+import scala.build.internals.EnvVar
 import scala.cli.CurrentParams
 import scala.cli.commands.{CustomWindowsEnvVarUpdater, ScalaCommand}
 import scala.util.Properties
@@ -16,7 +17,10 @@ object AddPath extends ScalaCommand[AddPathOptions] {
   override def runCommand(options: AddPathOptions, args: RemainingArgs, logger: Logger): Unit = {
     if args.all.isEmpty then logger.error("Nothing to do")
     else {
-      val update = EnvironmentUpdate(Nil, Seq("PATH" -> args.all.mkString(File.pathSeparator)))
+      val update = EnvironmentUpdate(
+        Nil,
+        Seq(EnvVar.Misc.path.name -> args.all.mkString(File.pathSeparator))
+      )
       val didUpdate =
         if (Properties.isWin) {
           val updater = CustomWindowsEnvVarUpdater().withUseJni(Some(coursier.paths.Util.useJni()))

modules/cli/src/main/scala/scala/cli/commands/bsp/Bsp.scala

@@ -9,6 +9,7 @@ import scala.build.*
 import scala.build.bsp.{BspReloadableOptions, BspThreads}
 import scala.build.errors.BuildException
 import scala.build.input.Inputs
+import scala.build.internals.EnvVar
 import scala.build.options.{BuildOptions, Scope}
 import scala.cli.commands.ScalaCommand
 import scala.cli.commands.publish.ConfigUtil.*
@@ -63,7 +64,7 @@ object Bsp extends ScalaCommand[BspOptions] {
       .flatMap(_.get(Keys.power).toOption)
       .flatten
       .getOrElse(false)
-    val envPowerMode       = latestEnvs.get("SCALA_CLI_POWER").exists(_.toBoolean)
+    val envPowerMode       = latestEnvs.get(EnvVar.ScalaCli.power.name).exists(_.toBoolean)
     val launcherPowerArg   = latestLauncherOptions.powerOptions.power
     val subCommandPowerArg = latestSharedOptions.powerOptions.power
     val latestPowerMode = configPowerMode || launcherPowerArg || subCommandPowerArg || envPowerMode
@@ -208,7 +209,7 @@ object Bsp extends ScalaCommand[BspOptions] {
           baseOptions.notForBloopOptions.addRunnerDependencyOpt.orElse(Some(false))
       )
     )
-    val withEnvs = envs.get("JAVA_HOME")
+    val withEnvs = envs.get(EnvVar.Java.javaHome.name)
       .filter(_ => withDefaults.javaOptions.javaHomeOpt.isEmpty)
       .map(javaHome =>
         withDefaults.copy(javaOptions =

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

@@ -2,7 +2,7 @@ package scala.cli.commands.config
 
 import caseapp.*
 
-import scala.build.internal.util.ConsoleUtils.ScalaCliConsole
+import scala.build.internals.ConsoleUtils.ScalaCliConsole
 import scala.cli.ScalaCli.{allowRestrictedFeatures, fullRunnerName, progName}
 import scala.cli.commands.pgp.PgpScalaSigningOptions
 import scala.cli.commands.shared.*

modules/cli/src/main/scala/scala/cli/commands/github/LibSodiumJni.scala

@@ -12,7 +12,8 @@ import scala.build.EitherCps.{either, value}
 import scala.build.Logger
 import scala.build.errors.BuildException
 import scala.build.internal.{Constants, FetchExternalBinary}
-import scala.cli.internal.{Constants => CliConstants}
+import scala.build.internals.EnvVar
+import scala.cli.internal.Constants as CliConstants
 import scala.util.Properties
 import scala.util.control.NonFatal
 
@@ -135,7 +136,7 @@ object LibSodiumJni {
         case Some(sodiumLib) =>
           System.load(sodiumLib.toString)
         case None =>
-          val allow = Option(System.getenv("SCALA_CLI_SODIUM_JNI_ALLOW"))
+          val allow = EnvVar.ScalaCli.allowSodiumJni.valueOpt
             .map(_.toLowerCase(Locale.ROOT))
             .forall {
               case "false" | "0" => false

modules/cli/src/main/scala/scala/cli/commands/installcompletions/InstallCompletions.scala

@@ -9,6 +9,7 @@ import java.nio.charset.Charset
 import java.nio.file.Paths
 import java.util
 
+import scala.build.internals.EnvVar
 import scala.build.{Directories, Logger}
 import scala.cli.commands.shared.HelpGroup
 import scala.cli.commands.{ScalaCommand, SpecificationLevel}
@@ -57,7 +58,7 @@ object InstallCompletions extends ScalaCommand[InstallCompletionsOptions] {
         (script, defaultRcFile)
       case Zsh.id | "zsh" =>
         val completionScript = Zsh.script(name)
-        val zDotDir = Option(System.getenv("ZDOTDIR"))
+        val zDotDir = EnvVar.Misc.zDotDir.valueOpt
           .map(os.Path(_, os.pwd))
           .getOrElse(os.home)
         val defaultRcFile        = zDotDir / ".zshrc"
@@ -114,7 +115,7 @@ object InstallCompletions extends ScalaCommand[InstallCompletionsOptions] {
   def getFormat(format: Option[String]): Option[String] =
     format.map(_.trim).filter(_.nonEmpty)
       .orElse {
-        Option(System.getenv("SHELL")).map(_.split("[\\/]+").last).map {
+        EnvVar.Misc.shell.valueOpt.map(_.split("[\\/]+").last).map {
           case "bash" => Bash.id
           case "zsh"  => Zsh.id
           case other  => other

modules/cli/src/main/scala/scala/cli/commands/publish/PublishParamsOptions.scala

@@ -2,6 +2,7 @@ package scala.cli.commands.publish
 
 import caseapp.*
 
+import scala.build.internals.EnvVar
 import scala.cli.commands.shared.{HelpGroup, SharedVersionOptions}
 import scala.cli.commands.tags
 import scala.cli.signing.shared.PasswordOption
@@ -77,10 +78,8 @@ final case class PublishParamsOptions(
 ) {
   // format: on
 
-  def setupCi: Boolean =
-    ci.getOrElse(false)
-  def isCi: Boolean =
-    ci.getOrElse(System.getenv("CI") != null)
+  def setupCi: Boolean = ci.getOrElse(false)
+  def isCi: Boolean    = ci.getOrElse(EnvVar.Internal.ci.valueOpt.nonEmpty)
 }
 
 object PublishParamsOptions {

modules/cli/src/main/scala/scala/cli/commands/run/Run.scala

@@ -13,8 +13,9 @@ import scala.build.EitherCps.{either, value}
 import scala.build.*
 import scala.build.errors.BuildException
 import scala.build.input.{Inputs, ScalaCliInvokeData, SubCommand}
-import scala.build.internal.util.ConsoleUtils.ScalaCliConsole
 import scala.build.internal.{Constants, Runner, ScalaJsLinkerConfig}
+import scala.build.internals.ConsoleUtils.ScalaCliConsole
+import scala.build.internals.EnvVar
 import scala.build.options.{BuildOptions, JavaOpt, PackageType, Platform, ScalacOpt}
 import scala.cli.CurrentParams
 import scala.cli.commands.package0.Package
@@ -498,9 +499,9 @@ object Run extends ScalaCommand[RunOptions] with BuildCommandHelpers {
           if (pythonLibraryPaths.isEmpty) Map.empty
           else {
             val prependTo =
-              if (Properties.isWin) "PATH"
-              else if (Properties.isMac) "DYLD_LIBRARY_PATH"
-              else "LD_LIBRARY_PATH"
+              if (Properties.isWin) EnvVar.Misc.path.name
+              else if (Properties.isMac) EnvVar.Misc.dyldLibraryPath.name
+              else EnvVar.Misc.ldLibraryPath.name
             val currentOpt = Option(System.getenv(prependTo))
             val currentEntries = currentOpt
               .map(_.split(File.pathSeparator).toSet)

modules/cli/src/main/scala/scala/cli/commands/setupide/SetupIde.scala

@@ -14,6 +14,7 @@ import scala.build.bsp.IdeInputs
 import scala.build.errors.{BuildException, WorkspaceError}
 import scala.build.input.{Inputs, OnDisk, Virtual, WorkspaceOrigin}
 import scala.build.internal.Constants
+import scala.build.internals.EnvVar
 import scala.build.options.{BuildOptions, Scope}
 import scala.cli.CurrentParams
 import scala.cli.commands.shared.{SharedBspFileOptions, SharedOptions}
@@ -185,7 +186,8 @@ object SetupIde extends ScalaCommand[SetupIdeOptions] {
     val scalaCliOptionsForBspJson    = writeToArray(options.shared)(SharedOptions.jsonCodec)
     val scalaCliLaunchOptsForBspJson = writeToArray(launcherOptions)(LauncherOptions.jsonCodec)
     val scalaCliBspInputsJson        = writeToArray(ideInputs)
-    val scalaCliBspEnvsJson          = writeToArray(sys.env)
+    val envsForBsp          = sys.env.filter((key, _) => EnvVar.allBsp.map(_.name).contains(key))
+    val scalaCliBspEnvsJson = writeToArray(envsForBsp)
 
     if (inputs.workspaceOrigin.contains(WorkspaceOrigin.HomeDir))
       value(Left(new WorkspaceError(

modules/cli/src/main/scala/scala/cli/commands/shared/CoursierOptions.scala

@@ -5,6 +5,7 @@ import com.github.plokhotnyuk.jsoniter_scala.core.*
 import com.github.plokhotnyuk.jsoniter_scala.macros.*
 import coursier.cache.{CacheLogger, CachePolicy, FileCache}
 
+import scala.build.internals.EnvVar
 import scala.cli.commands.tags
 import scala.concurrent.duration.Duration
 
@@ -54,7 +55,7 @@ final case class CoursierOptions(
   }
 
   def getOffline(): Option[Boolean] = offline
-    .orElse(Option(System.getenv("COURSIER_MODE")).map(_ == "offline"))
+    .orElse(EnvVar.Coursier.coursierMode.valueOpt.map(_ == "offline"))
     .orElse(Option(System.getProperty("coursier.mode")).map(_ == "offline"))
 }
 

modules/cli/src/main/scala/scala/cli/commands/shared/HelpGroupOptions.scala

@@ -10,6 +10,14 @@ import scala.cli.commands.tags
 
 @HelpMessage("Print help message")
 case class HelpGroupOptions(
+  @Group(HelpGroup.Help.toString)
+  @HelpMessage("Show environment variable help")
+  @Tag(tags.implementation)
+  @Tag(tags.inShortHelp)
+  @Name("helpEnv")
+  @Name("envHelp")
+  @Name("envsHelp")
+  helpEnvs: Boolean = false,
   @Group(HelpGroup.Help.toString)
   @HelpMessage("Show options for ScalaJS")
   @Tag(tags.implementation)

modules/cli/src/main/scala/scala/cli/commands/shared/SharedOptions.scala

@@ -26,9 +26,9 @@ import scala.build.errors.{AmbiguousPlatformError, BuildException, ConfigDbExcep
 import scala.build.input.{Element, Inputs, ResourceDirectory, ScalaCliInvokeData}
 import scala.build.interactive.Interactive
 import scala.build.interactive.Interactive.{InteractiveAsk, InteractiveNop}
-import scala.build.internal.util.ConsoleUtils.ScalaCliConsole
 import scala.build.internal.util.WarningMessages
 import scala.build.internal.{Constants, FetchExternalBinary, OsLibc, Util}
+import scala.build.internals.ConsoleUtils.ScalaCliConsole
 import scala.build.options.ScalaVersionUtil.fileWithTtl0
 import scala.build.options.{BuildOptions, ComputeVersion, Platform, ScalacOpt, ShadowingSeq}
 import scala.build.preprocessing.directives.ClasspathUtils.*