[2.x] Improve -help/--help and fix launcher test harness (#8879)

- sbt script: add 'Getting started' section to usage (create project, help commands)
- sbt script: handle -h/--help without starting JVM, exit 0

launcher-package/integration-test/src/test/scala/RunnerScriptTest.scala

@@ -154,6 +154,16 @@ abstract class RunnerScriptTest extends verify.BasicTestSuite with ShellScriptUt
     assertVersionOutput(out)
     ()
 
+  // Test for issue #4189: Improve -help and help commands
+  testOutput(
+    "sbt --help should show getting-started hints",
+    citestVariant = "citest",
+  )("--help"): (out: List[String]) =>
+    val helpText = out.mkString(System.lineSeparator())
+    assert(helpText.contains("Getting started with sbt"))
+    assert(helpText.contains("sbt init"))
+    assert(helpText.contains("help <command>"))
+
   testOutput("--sbt-cache")("--sbt-cache", "./cachePath"): (out: List[String]) =>
     assert(out.contains[String]("-Dsbt.global.localcache=./cachePath"))
 

launcher-package/integration-test/src/test/scala/ShellScriptUtil.scala

@@ -154,16 +154,17 @@ trait ShellScriptUtil extends BasicTestSuite {
             envVars("XDG_CONFIG_HOME") = configHomeDir.getAbsolutePath
           }
 
-          val path = sys.env.getOrElse("PATH", sys.env("Path"))
+          val path = sys.env.getOrElse("PATH", sys.env.getOrElse("Path", ""))
+          val javaHomeEnv = sys.env.getOrElse("JAVA_HOME", System.getProperty("java.home"))
           envVars("JAVA_OPTS") = javaOpts
           envVars("SBT_OPTS") = sbtOpts
           envVars("JAVA_TOOL_OPTIONS") = javaToolOptions
           if isWindows then
             envVars("JAVACMD") = new File(javaBinDir, "java").getAbsolutePath()
-            envVars("JAVA_HOME") = sys.env("JAVA_HOME")
+            envVars("JAVA_HOME") = javaHomeEnv
           else
             envVars("PATH") = javaBinDir + File.pathSeparator + path
-            envVars("JAVA_HOME") = sys.env("JAVA_HOME")
+            envVars("JAVA_HOME") = javaHomeEnv
           val cmd =
             LauncherTestHelper.launcherCommand(testSbtScript.getAbsolutePath, isGitBashTest) ++ args
           val lines = mutable.ListBuffer.empty[String]

launcher-package/src/universal/bin/sbt.bat

@@ -1138,9 +1138,18 @@ echo.
 echo In the case of duplicated or conflicting options, the order above
 echo shows precedence: JAVA_OPTS lowest, command line options highest.
 echo.
+echo Getting started with sbt:
+echo.
+echo   - To create a new project run: sbt init
+echo.
+echo   - Once in the sbt shell, type:
+echo       help
+echo       help ^<command^>
+echo     to see available commands and detailed help.
+echo.
 
 @endlocal
-exit /B 1
+exit /B 0
 
 :set_sbt_version
 set "sbt_version="

sbt

@@ -7,6 +7,7 @@ declare -a java_args
 declare -a scalac_args
 declare -a sbt_commands
 declare -a sbt_options
+declare -a print_help
 declare -a print_version
 declare -a print_sbt_version
 declare -a print_sbt_script_version
@@ -690,6 +691,15 @@ Usage: `basename "$0"` [options]
 
 In the case of duplicated or conflicting options, the order above
 shows precedence: JAVA_OPTS lowest, command line options highest.
+
+Getting started with sbt:
+
+  - To create a new project run: sbt init
+
+  - Once in the sbt shell, type:
+      help
+      help <command>
+    to see available commands and detailed help.
 EOM
 }
 
@@ -782,7 +792,7 @@ parseLineIntoWords() {
 process_args () {
   while [[ $# -gt 0 ]]; do
     case "$1" in
-            -h|-help|--help) usage; exit 1 ;;
+            -h|-help|--help) print_help=1 && shift ;;
       -v|-verbose|--verbose) sbt_verbose=1 && shift ;;
       -V|-version|--version) print_version=1 && shift ;;
           --numeric-version) print_sbt_version=1 && shift ;;
@@ -991,6 +1001,12 @@ args1=( "${cli_options[@]}" "${cli_commands[@]}" "${sbt_additional_commands[@]}"
 process_args "${args1[@]}"
 vlog "[sbt_options] $(declare -p sbt_options)"
 
+# Handle -h/--help/-help at the script level without requiring Java or a project
+if [[ $print_help ]]; then
+  usage
+  exit 0
+fi
+
 # Handle --script-version before native client so it works on sbt 2.x project dirs (#8711)
 if [[ $print_sbt_script_version ]]; then
   echo "$init_sbt_version"