Add toolkit using directive and cli options

build.sc

@@ -394,6 +394,9 @@ trait Core extends ScalaCliSbtModule with ScalaCliPublishModule with HasTests
          |  def scalafmtName = "${Deps.scalafmtCli.dep.module.name.value}"
          |  def defaultScalafmtVersion = "${Deps.scalafmtCli.dep.version}"
          |
+         |  def toolkitOrganization = "${Deps.toolkit.dep.module.organization.value}"
+         |  def toolkitName = "${Deps.toolkit.dep.module.name.value}"
+         |
          |  def defaultScalaVersion = "${Scala.defaultUser}"
          |  def defaultScala212Version = "${Scala.scala212}"
          |  def defaultScala213Version = "${Scala.scala213}"

modules/build/src/main/scala/scala/build/preprocessing/ScalaPreprocessor.scala

@@ -70,7 +70,8 @@ case object ScalaPreprocessor extends Preprocessor {
       directives.ScalaNative.handler,
       directives.ScalaVersion.handler,
       directives.Sources.handler,
-      directives.Tests.handler
+      directives.Tests.handler,
+      directives.Toolkit.handler
     ).map(_.mapE(_.buildOptions))
 
   val requireDirectiveHandlers: Seq[DirectiveHandler[BuildRequirements]] =

modules/build/src/test/scala/scala/build/tests/DirectiveTests.scala

@@ -3,11 +3,12 @@ package scala.build.tests
 import com.eed3si9n.expecty.Expecty.expect
 
 import java.io.IOException
-import scala.build.{BuildThreads, Directories, LocalRepo}
+import scala.build.{BuildThreads, Directories, LocalRepo, Position, Positioned}
 import scala.build.options.{BuildOptions, InternalOptions, MaybeScalaVersion}
 import scala.build.tests.util.BloopServer
 import build.Ops.EitherThrowOps
 import scala.build.Position
+import dependency.AnyDependency
 
 class DirectiveTests extends munit.FunSuite {
 
@@ -87,4 +88,23 @@ class DirectiveTests extends munit.FunSuite {
     }
   }
 
+  test("resolve toolkit dependency") {
+    val testInputs = TestInputs(
+      os.rel / "simple.sc" ->
+        """//> using toolkit "latest"
+          |""".stripMargin
+    )
+    testInputs.withBuild(baseOptions, buildThreads, bloopConfigOpt) {
+      (_, _, maybeBuild) =>
+        val build = maybeBuild.orThrow
+        val dep   = build.options.classPathOptions.extraDependencies.toSeq.headOption
+        assert(dep.nonEmpty)
+
+        val toolkitDep = dep.get.value
+        expect(toolkitDep.organization == "org.virtuslab")
+        expect(toolkitDep.name == "toolkit")
+        expect(toolkitDep.version == "latest.release")
+    }
+  }
+
 }

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

@@ -16,6 +16,7 @@ import scala.build.EitherCps.{either, value}
 import scala.build.*
 import scala.build.blooprifle.BloopRifleConfig
 import scala.build.compiler.{BloopCompilerMaker, ScalaCompilerMaker, SimpleScalaCompilerMaker}
+import scala.build.directives.DirectiveDescription
 import scala.build.errors.{AmbiguousPlatformError, BuildException}
 import scala.build.input.{Element, Inputs, ResourceDirectory}
 import scala.build.interactive.Interactive
@@ -24,6 +25,7 @@ import scala.build.internal.CsLoggerUtil.*
 import scala.build.internal.{Constants, FetchExternalBinary, OsLibc, Util}
 import scala.build.options.ScalaVersionUtil.fileWithTtl0
 import scala.build.options.{Platform, ScalacOpt, ShadowingSeq}
+import scala.build.preprocessing.directives.Toolkit
 import scala.build.options as bo
 import scala.cli.ScalaCli
 import scala.cli.commands.publish.ConfigUtil.*
@@ -180,6 +182,10 @@ final case class SharedOptions(
   @ValueDescription("/example/path")
   @Tag(tags.must)
     compilationOutput: Option[String] = None,
+  @HelpMessage("Add toolkit to classPath")
+  @ValueDescription("version|latest")
+  @Name("toolkit")
+    withToolkit: Option[String] = None
 ) extends HasLoggingOptions {
   // format: on
 
@@ -310,7 +316,7 @@ final case class SharedOptions(
           SharedOptions.parseDependencies(
             dependencies.dependency.map(Positioned.none),
             ignoreErrors
-          )
+          ) ++ SharedOptions.resolveToolkitDependency(withToolkit)
         )
       ),
       internal = bo.InternalOptions(
@@ -623,4 +629,7 @@ object SharedOptions {
         }
       }
 
+  private def resolveToolkitDependency(toolkitVersion: Option[String])
+    : Seq[Positioned[AnyDependency]] =
+    toolkitVersion.toList.map(Positioned.commandLine).map(Toolkit.resolveDependency)
 }

modules/cli/src/test/scala/cli/commands/tests/RunOptionsTests.scala

@@ -20,4 +20,20 @@ class RunOptionsTests extends munit.FunSuite {
     expect(buildOptions.notForBloopOptions.scalaPyVersion.contains(ver))
   }
 
+  test("resolve toolkit dependency") {
+    val runOptions = RunOptions(
+      shared = SharedOptions(
+        withToolkit = Some("latest")
+      )
+    )
+    val buildOptions = Run.buildOptions(runOptions).value
+    val dep          = buildOptions.classPathOptions.extraDependencies.toSeq.headOption
+    assert(dep.nonEmpty)
+
+    val toolkitDep = dep.get.value
+    expect(toolkitDep.organization == "org.virtuslab")
+    expect(toolkitDep.name == "toolkit")
+    expect(toolkitDep.version == "latest.release")
+  }
+
 }

modules/directives/src/main/scala/scala/build/preprocessing/directives/Toolkit.scala

@@ -0,0 +1,47 @@
+package scala.build.preprocessing.directives
+
+import coursier.core.{Repository, Version}
+import dependency.*
+
+import scala.annotation.tailrec
+import scala.build.EitherCps.{either, value}
+import scala.build.directives.*
+import scala.build.errors.BuildException
+import scala.build.internal.Constants
+import scala.build.options.{BuildOptions, ClassPathOptions, JavaOpt, Scope, ShadowingSeq}
+import scala.build.{Artifacts, Logger, Positioned, options}
+import scala.cli.commands.SpecificationLevel
+
+@DirectiveGroupName("Toolkit")
+@DirectiveExamples("//> using toolkit \"0.1.0\"")
+@DirectiveExamples("//> using toolkit \"latest\"")
+@DirectiveUsage(
+  "//> using toolkit _version_",
+  "`//> using toolkit` _version_"
+)
+@DirectiveDescription("Use a toolkit as dependency")
+@DirectiveLevel(SpecificationLevel.SHOULD)
+// format: off
+final case class Toolkit(
+  toolkit: Option[Positioned[String]] = None
+) extends HasBuildOptions {
+  // format: on
+  def buildOptions: Either[BuildException, BuildOptions] = {
+    val toolkitDep =
+      toolkit.toList.map(Toolkit.resolveDependency)
+    val buildOpt = BuildOptions(
+      classPathOptions = ClassPathOptions(
+        extraDependencies = ShadowingSeq.from(toolkitDep)
+      )
+    )
+    Right(buildOpt)
+  }
+}
+
+object Toolkit {
+  def resolveDependency(toolkitVersion: Positioned[String]) = toolkitVersion.map(version =>
+    val v = if version == "latest" then "latest.release" else version
+    dep"${Constants.toolkitOrganization}::${Constants.toolkitName}:$v"
+  )
+  val handler: DirectiveHandler[Toolkit] = DirectiveHandler.derive
+}

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

@@ -1057,4 +1057,19 @@ abstract class RunTestDefinitions(val scalaVersionOpt: Option[String])
         expect(output.contains(exceptionMsg))
       }
     }
+
+  test("should add toolkit to classpath") {
+    val inputs = TestInputs(
+      os.rel / "Hello.scala" ->
+        s"""object Hello extends App {
+           |  println(os.pwd) // os lib should be added to classpath by toolkit
+           |}""".stripMargin
+    )
+    inputs.fromRoot { root =>
+      val output = os.proc(TestUtil.cli, ".", "--toolkit", "0.1.4")
+        .call(cwd = root).out.trim()
+
+      expect(output == root.toString())
+    }
+  }
 }

project/deps.sc

@@ -177,6 +177,7 @@ object Deps {
   def svm             = ivy"org.graalvm.nativeimage:svm:$graalVmVersion"
   def swoval          = ivy"com.swoval:file-tree-views:2.1.9"
   def testInterface   = ivy"org.scala-sbt:test-interface:1.0"
+  def toolkit         = ivy"org.virtuslab:toolkit:0.1.0"
   def usingDirectives = ivy"org.virtuslab:using_directives:0.0.10"
   // Lives at https://github.com/scala-cli/no-crc32-zip-input-stream, see #865
   // This provides a ZipInputStream that doesn't verify CRC32 checksums, that users

website/docs/reference/cli-options.md

@@ -1408,6 +1408,12 @@ Aliases: `--compile-out`, `--compile-output`, `-d`, `--destination`, `--output-d
 
 Copy compilation results to output directory using either relative or absolute path
 
+### `--with-toolkit`
+
+Aliases: `--toolkit`
+
+Add toolkit to classPath
+
 ## Snippet options
 
 Available in commands:

website/docs/reference/directives.md

@@ -324,6 +324,17 @@ Set the test framework
 #### Examples
 `//> using testFramework "utest.runner.Framework"`
 
+### Toolkit
+
+Use a toolkit as dependency
+
+`//> using toolkit` _version_
+
+#### Examples
+`//> using toolkit "0.1.0"`
+
+`//> using toolkit "latest"`
+
 
 ## target directives
 

website/docs/reference/scala-command/cli-options.md

@@ -962,6 +962,14 @@ Aliases: `--compile-out`, `--compile-output`, `-d`, `--destination`, `--output-d
 
 Copy compilation results to output directory using either relative or absolute path
 
+### `--with-toolkit`
+
+Aliases: `--toolkit`
+
+`IMPLEMENTATION specific` per Scala Runner specification
+
+Add toolkit to classPath
+
 ## Snippet options
 
 Available in commands:

website/docs/reference/scala-command/directives.md

@@ -254,3 +254,14 @@ Set the test framework
 #### Examples
 `//> using testFramework "utest.runner.Framework"`
 
+### Toolkit
+
+Use a toolkit as dependency
+
+`//> using toolkit` _version_
+
+#### Examples
+`//> using toolkit "0.1.0"`
+
+`//> using toolkit "latest"`
+

website/docs/reference/scala-command/runner-specification.md

@@ -544,6 +544,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 </details>
 
 ---
@@ -1051,6 +1057,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 </details>
 
 ---
@@ -1560,6 +1572,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 **--java-prop-option**
 
 Add java properties. Note that options equal `-Dproperty=value` are assumed to be java properties and don't require to be passed after `--java-prop`.
@@ -2099,6 +2117,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 **--java-prop-option**
 
 Add java properties. Note that options equal `-Dproperty=value` are assumed to be java properties and don't require to be passed after `--java-prop`.
@@ -2660,6 +2684,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 **--java-prop-option**
 
 Add java properties. Note that options equal `-Dproperty=value` are assumed to be java properties and don't require to be passed after `--java-prop`.
@@ -3171,6 +3201,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 **--respect-project-filters**
 
 Use project filters defined in the configuration. Turned on by default, use `--respect-project-filters:false` to disable it.
@@ -3748,6 +3784,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 **--java-prop-option**
 
 Add java properties. Note that options equal `-Dproperty=value` are assumed to be java properties and don't require to be passed after `--java-prop`.
@@ -4322,6 +4364,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 **--json-options**
 
 Command-line options JSON file
@@ -5123,6 +5171,12 @@ Aliases: `--help-fmt` ,`--fmt-help` ,`--scalafmt-help`
 
 
 
+**--with-toolkit**
+
+Add toolkit to classPath
+
+Aliases: `--toolkit`
+
 **--bsp-directory**
 
 Custom BSP configuration location