feat: add --watch-clear-screen option to clear terminal on rebuild

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

@@ -22,6 +22,16 @@ object WatchUtil {
     s"$gray$message$reset"
   }
 
+  /** Clears the terminal screen using ANSI escape codes. This prints the escape sequence to clear
+    * the entire screen and moves the cursor to the top-left corner.
+    */
+  def clearScreen(): Unit = {
+    // \u001b[2J clears the entire screen
+    // \u001b[H moves the cursor to the top-left corner (home position)
+    System.out.print("\u001b[2J\u001b[H")
+    System.out.flush()
+  }
+
   def printWatchMessage(): Unit =
     System.err.println(waitMessage("Watching sources"))
 

modules/cli/src/main/scala/scala/cli/commands/compile/Compile.scala

@@ -103,6 +103,7 @@ object Compile extends ScalaCommand[CompileOptions] with BuildCommandHelpers {
 
     val shouldBuildTestScope = options.shared.scope.test.getOrElse(false)
     if (options.watch.watchMode) {
+      var isFirstRun = true
       val watcher = Build.watch(
         inputs,
         buildOptions,
@@ -115,6 +116,9 @@ object Compile extends ScalaCommand[CompileOptions] with BuildCommandHelpers {
         actionableDiagnostics = actionableDiagnostics,
         postAction = () => WatchUtil.printWatchMessage()
       ) { res =>
+        if (options.watch.watchClearScreen && !isFirstRun)
+          WatchUtil.clearScreen()
+        isFirstRun = false
         for (builds <- res.orReport(logger))
           postBuild(builds, allowExit = false)
       }

modules/cli/src/main/scala/scala/cli/commands/package0/Package.scala

@@ -89,6 +89,7 @@ object Package extends ScalaCommand[PackageOptions] with BuildCommandHelpers {
     val withTestScope = options.shared.scope.test.getOrElse(false)
     if options.watch.watchMode then {
       var expectedModifyEpochSecondOpt = Option.empty[Long]
+      var isFirstRun                   = true
       val watcher                      = Build.watch(
         inputs,
         initialBuildOptions,
@@ -101,6 +102,9 @@ object Package extends ScalaCommand[PackageOptions] with BuildCommandHelpers {
         actionableDiagnostics = actionableDiagnostics,
         postAction = () => WatchUtil.printWatchMessage()
       ) { res =>
+        if (options.watch.watchClearScreen && !isFirstRun)
+          WatchUtil.clearScreen()
+        isFirstRun = false
         res.orReport(logger).map(_.builds).foreach {
           case b if b.forall(_.success) =>
             val successfulBuilds = b.collect { case s: Build.Successful => s }

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

@@ -255,7 +255,8 @@ object Publish extends ScalaCommand[PublishOptions] with BuildCommandHelpers {
       publishLocal = false,
       forceSigningExternally = options.signingCli.forceSigningExternally.getOrElse(false),
       parallelUpload = options.parallelUpload,
-      options.watch.watch,
+      watch = options.watch.watch,
+      watchClearScreen = options.watch.watchClearScreen,
       isCi = options.publishParams.isCi,
       () => configDb,
       options.mainClass,
@@ -279,6 +280,7 @@ object Publish extends ScalaCommand[PublishOptions] with BuildCommandHelpers {
     forceSigningExternally: Boolean,
     parallelUpload: Option[Boolean],
     watch: Boolean,
+    watchClearScreen: Boolean,
     isCi: Boolean,
     configDb: () => ConfigDb,
     mainClassOptions: MainClassOptions,
@@ -288,6 +290,7 @@ object Publish extends ScalaCommand[PublishOptions] with BuildCommandHelpers {
     val actionableDiagnostics = configDb().get(Keys.actions).getOrElse(None)
 
     if watch then {
+      var isFirstRun = true
       val watcher = Build.watch(
         inputs = inputs,
         options = initialBuildOptions,
@@ -299,8 +302,11 @@ object Publish extends ScalaCommand[PublishOptions] with BuildCommandHelpers {
         partial = None,
         actionableDiagnostics = actionableDiagnostics,
         postAction = () => WatchUtil.printWatchMessage()
-      ) {
-        _.orReport(logger).foreach { builds =>
+      ) { res =>
+        if (watchClearScreen && !isFirstRun)
+          WatchUtil.clearScreen()
+        isFirstRun = false
+        res.orReport(logger).foreach { builds =>
           maybePublish(
             builds = builds,
             workingDir = workingDir,

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

@@ -81,6 +81,7 @@ object PublishLocal extends ScalaCommand[PublishLocalOptions] {
       forceSigningExternally = options.scalaSigning.forceSigningExternally.getOrElse(false),
       parallelUpload = Some(true),
       watch = options.watch.watch,
+      watchClearScreen = options.watch.watchClearScreen,
       isCi = options.publishParams.isCi,
       configDb = () => ConfigDb.empty, // shouldn't be used, no need of repo credentials here
       mainClassOptions = options.mainClass,

modules/cli/src/main/scala/scala/cli/commands/repl/Repl.scala

@@ -208,6 +208,7 @@ object Repl extends ScalaCommand[ReplOptions] with BuildCommandHelpers {
       }
     }
     else if (options.sharedRepl.watch.watchMode) {
+      var isFirstRun = true
       val watcher = Build.watch(
         inputs,
         initialBuildOptions,
@@ -220,6 +221,9 @@ object Repl extends ScalaCommand[ReplOptions] with BuildCommandHelpers {
         actionableDiagnostics = actionableDiagnostics,
         postAction = () => WatchUtil.printWatchMessage()
       ) { res =>
+        if (options.sharedRepl.watch.watchClearScreen && !isFirstRun)
+          WatchUtil.clearScreen()
+        isFirstRun = false
         for (builds <- res.orReport(logger))
           postBuild(builds, allowExit = false) {
             successfulBuilds =>

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

@@ -252,6 +252,7 @@ object Run extends ScalaCommand[RunOptions] with BuildCommandHelpers {
         */
       val mainThreadOpt = AtomicReference(Option.empty[Thread])
 
+      var isFirstRun = true
       val watcher = Build.watch(
         inputs = inputs,
         options = initialBuildOptions,
@@ -266,6 +267,9 @@ object Run extends ScalaCommand[RunOptions] with BuildCommandHelpers {
           if processOpt.get().exists(_._1.isAlive()) then WatchUtil.printWatchWhileRunningMessage()
           else WatchUtil.printWatchMessage()
       ) { res =>
+        if (options.sharedRun.watch.watchClearScreen && !isFirstRun)
+          WatchUtil.clearScreen()
+        isFirstRun = false
         for ((process, onExitProcess) <- processOpt.get()) {
           onExitProcess.cancel(true)
           ProcUtil.interruptProcess(process, logger)

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

@@ -18,7 +18,12 @@ final case class SharedWatchOptions(
   @Tag(tags.should)
   @Tag(tags.inShortHelp)
   @Name("revolver")
-    restart: Boolean = false
+    restart: Boolean = false,
+  @Group(HelpGroup.Watch.toString)
+  @HelpMessage("Clear the screen each time the watch mode detects changes and re-compiles or re-runs")
+  @Tag(tags.implementation)
+  @Name("watch-cls")
+    watchClearScreen: Boolean = false
 ) { // format: on
 
   lazy val watchMode: Boolean = watch || restart

modules/cli/src/main/scala/scala/cli/commands/test/Test.scala

@@ -146,6 +146,7 @@ object Test extends ScalaCommand[TestOptions] {
       }
 
     if (options.watch.watchMode) {
+      var isFirstRun = true
       val watcher = Build.watch(
         inputs,
         initialBuildOptions,
@@ -158,6 +159,9 @@ object Test extends ScalaCommand[TestOptions] {
         actionableDiagnostics = actionableDiagnostics,
         postAction = () => WatchUtil.printWatchMessage()
       ) { res =>
+        if (options.watch.watchClearScreen && !isFirstRun)
+          WatchUtil.clearScreen()
+        isFirstRun = false
         for (builds <- res.orReport(logger))
           maybeTest(builds, allowExit = false)
       }