Add env for configuring home directory overriding

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

@@ -19,11 +19,38 @@ import scala.cli.util.ConfigDbUtils
 import scala.util.Properties
 
 object ScalaCli {
-
   // TODO: Remove this part once fix is released in os-lib (Issue #2585)
-  if (scala.util.Try(os.Path(System.getProperty("user.home"))).isFailure) {
-    System.err.println("Warning: user.home property is not set, setting it to user.dir")
-    System.setProperty("user.home", System.getProperty("user.dir"))
+  sys.env.get("SCALA_CLI_HOME_DIR_OVERRIDE")
+    .filter(_.nonEmpty)
+    .filter(homeDir => scala.util.Try(os.Path(homeDir)).isSuccess)
+    .foreach { homeDirOverride =>
+      System.err.println(
+        s"Warning: user.home property overridden with the SCALA_CLI_HOME_DIR_OVERRIDE env var to: $homeDirOverride"
+      )
+      System.setProperty("user.home", homeDirOverride)
+    }
+  private def getInvalidPropMessage(homeDirOpt: Option[String]): String = homeDirOpt match {
+    case Some(value) => s"not valid: $value"
+    case None        => "not set"
+  }
+  sys.props.get("user.home") -> sys.props.get("user.dir") match {
+    case (Some(homeDir), _)
+        if scala.util.Try(os.Path(homeDir)).isSuccess => // all is good, do nothing
+    case (invalidHomeDirOpt, Some(userDir)) if scala.util.Try(os.Path(userDir)).isSuccess =>
+      System.err.println(
+        s"Warning: user.home property is ${getInvalidPropMessage(invalidHomeDirOpt)}, setting it to user.dir value: $userDir"
+      )
+      System.setProperty("user.home", userDir)
+    case (invalidHomeDirOpt, invalidUserDirOpt) =>
+      System.err.println(
+        s"Error: user.home property is ${getInvalidPropMessage(invalidHomeDirOpt)}"
+      )
+      System.err.println(s"Error: user.dir property is ${getInvalidPropMessage(invalidUserDirOpt)}")
+      System.err.println("Scala CLI cannot work correctly without a valid home or user directory.")
+      System.err.println(
+        "Consider overriding it to a valid directory path with the SCALA_CLI_HOME_DIR_OVERRIDE environment variable."
+      )
+      sys.exit(1)
   }
 
   if (Properties.isWin && isGraalvmNativeImage)

modules/integration/src/test/scala/scala/cli/integration/RunTestDefinitions.scala

@@ -2087,4 +2087,62 @@ abstract class RunTestDefinitions(val scalaVersionOpt: Option[String])
       expect(res.err.trim().contains("JVM (11)"))
     }
   }
+
+  // TODO: Remove this part once fix is released in os-lib (Issue #2585)
+  def getCoursierCacheRelPath: os.RelPath =
+    if (Properties.isWin) os.rel / "Coursier" / "Cache"
+    else if (Properties.isMac) os.rel / "Library" / "Caches" / "Coursier"
+    else os.rel / ".cache" / "coursier"
+  if (TestUtil.isJvmCli) // can't reproduce on native image launchers
+    test("user.home is overridden with user.dir") {
+      val customCall =
+        Seq("java", "-Xmx512m", "-Xms128m", "-Duser.home=?", "-jar", TestUtil.cliPath)
+      val msg   = "Hello"
+      val input = "script.sc"
+      TestInputs(os.rel / input -> s"println(\"$msg\")")
+        .fromRoot { root =>
+          expect(!os.isDir(root / getCoursierCacheRelPath))
+          val res = os.proc(customCall, "run", extraOptions, "--server=false", input)
+            .call(
+              cwd = root,
+              stderr = os.Pipe
+            )
+          expect(res.out.trim() == msg)
+          expect(
+            res.err.trim().contains(
+              "user.home property is not valid: ?, setting it to user.dir value"
+            )
+          )
+          if (!Properties.isWin) // coursier cache location on Windows does not depend on home dir
+            expect(os.isDir(root / getCoursierCacheRelPath))
+        }
+    }
+
+  // TODO: Remove this part once fix is released in os-lib (Issue #2585)
+  test("user.home is overridden by SCALA_CLI_HOME_DIR_OVERRIDE") {
+    val msg   = "Hello"
+    val input = "script.sc"
+    TestInputs(os.rel / input -> s"println(\"$msg\")")
+      .fromRoot { root =>
+        val newHomePath = root / "home"
+        os.makeDir(newHomePath)
+        expect(!os.isDir(newHomePath / getCoursierCacheRelPath))
+        val extraEnv = Map("SCALA_CLI_HOME_DIR_OVERRIDE" -> newHomePath.toString())
+
+        val res = os.proc(TestUtil.cli, "run", extraOptions, "--server=false", input)
+          .call(
+            cwd = root,
+            stderr = os.Pipe,
+            env = extraEnv
+          )
+        expect(res.out.trim() == msg)
+        expect(
+          res.err.trim().contains(
+            "user.home property overridden with the SCALA_CLI_HOME_DIR_OVERRIDE"
+          )
+        )
+        if (!Properties.isWin) // coursier cache location on Windows does not depend on home dir
+          expect(os.isDir(newHomePath / getCoursierCacheRelPath))
+      }
+  }
 }