Introduce CommandFactory to aggregate commands (#75)

* Introduce CommandFactory to aggregate commands

This makes it easier to invoke any command by known key rather than just creating one-off kts scripts

* Remove internal name

* Print to err

* API dump

Author: ZacSweers

api/kotlin-cli-util.api

@@ -32,31 +32,74 @@ public final class slack/cli/CliktExtensionsKt {
 	public static synthetic fun projectDirOption$default (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/options/OptionDelegate;
 }
 
+public abstract interface class slack/cli/CommandFactory {
+	public abstract fun create ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public abstract fun getDescription ()Ljava/lang/String;
+	public abstract fun getKey ()Ljava/lang/String;
+}
+
+public final class slack/cli/CommandFactoryKt {
+	public static final fun runCommand ([Ljava/lang/String;Z)V
+	public static synthetic fun runCommand$default ([Ljava/lang/String;ZILjava/lang/Object;)V
+}
+
 public final class slack/cli/Toml {
 	public static final field INSTANCE Lslack/cli/Toml;
 	public final fun parseVersion (Ljava/io/File;)Ljava/util/Map;
 }
 
 public final class slack/cli/gradle/GradleProjectFlattenerCli : com/github/ajalt/clikt/core/CliktCommand {
+	public static final field DESCRIPTION Ljava/lang/String;
 	public fun <init> ()V
 	public fun run ()V
 }
 
+public final class slack/cli/gradle/GradleProjectFlattenerCli$Factory : slack/cli/CommandFactory {
+	public fun <init> ()V
+	public fun create ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public fun getDescription ()Ljava/lang/String;
+	public fun getKey ()Ljava/lang/String;
+}
+
 public final class slack/cli/gradle/GradleSettingsVerifierCli : com/github/ajalt/clikt/core/CliktCommand {
+	public static final field DESCRIPTION Ljava/lang/String;
 	public fun <init> ()V
 	public fun run ()V
 }
 
+public final class slack/cli/gradle/GradleSettingsVerifierCli$Factory : slack/cli/CommandFactory {
+	public fun <init> ()V
+	public fun create ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public fun getDescription ()Ljava/lang/String;
+	public fun getKey ()Ljava/lang/String;
+}
+
 public final class slack/cli/lint/LintBaselineMergerCli : com/github/ajalt/clikt/core/CliktCommand {
+	public static final field DESCRIPTION Ljava/lang/String;
 	public fun <init> ()V
 	public fun run ()V
 }
 
+public final class slack/cli/lint/LintBaselineMergerCli$Factory : slack/cli/CommandFactory {
+	public fun <init> ()V
+	public fun create ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public fun getDescription ()Ljava/lang/String;
+	public fun getKey ()Ljava/lang/String;
+}
+
 public final class slack/cli/sarif/MergeSarifReports : com/github/ajalt/clikt/core/CliktCommand {
+	public static final field DESCRIPTION Ljava/lang/String;
 	public fun <init> ()V
 	public fun run ()V
 }
 
+public final class slack/cli/sarif/MergeSarifReports$Factory : slack/cli/CommandFactory {
+	public fun <init> ()V
+	public fun create ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public fun getDescription ()Ljava/lang/String;
+	public fun getKey ()Ljava/lang/String;
+}
+
 public final class slack/cli/shellsentry/AnalysisResult {
 	public fun <init> (Ljava/lang/String;Ljava/lang/String;Lslack/cli/shellsentry/RetrySignal;ILkotlin/jvm/functions/Function1;)V
 	public final fun component1 ()Ljava/lang/String;
@@ -181,10 +224,18 @@ public final class slack/cli/shellsentry/ShellSentry$Companion {
 }
 
 public final class slack/cli/shellsentry/ShellSentryCli : com/github/ajalt/clikt/core/CliktCommand {
+	public static final field DESCRIPTION Ljava/lang/String;
 	public fun <init> ()V
 	public fun run ()V
 }
 
+public final class slack/cli/shellsentry/ShellSentryCli$Factory : slack/cli/CommandFactory {
+	public fun <init> ()V
+	public fun create ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public fun getDescription ()Ljava/lang/String;
+	public fun getKey ()Ljava/lang/String;
+}
+
 public final class slack/cli/shellsentry/ShellSentryConfig {
 	public fun <init> ()V
 	public fun <init> (ILjava/lang/String;Ljava/util/List;I)V

build.gradle.kts

@@ -28,6 +28,7 @@ plugins {
   alias(libs.plugins.moshix)
   alias(libs.plugins.kotlin.serialization)
   alias(libs.plugins.retry)
+  alias(libs.plugins.ksp)
 }
 
 spotless {
@@ -98,7 +99,9 @@ if (System.getenv("CI") != null) {
 }
 
 dependencies {
+  ksp(libs.autoService.ksp)
   api(libs.clikt)
+  implementation(libs.autoService.annotations)
   implementation(libs.tikxml.htmlEscape)
   implementation(libs.kotlinx.serialization.core)
   implementation(libs.xmlutil.serialization)

gradle/libs.versions.toml

@@ -1,6 +1,7 @@
 [versions]
 kotlin = "1.9.21"
 kotlinx-serialization = "1.6.2"
+ksp = "1.9.21-1.0.15"
 ktfmt = "0.46"
 jvmTarget = "17"
 moshix = "0.25.1"
@@ -16,11 +17,14 @@ mavenPublish = { id = "com.vanniktech.maven.publish", version = "0.25.3" }
 moshix = { id = "dev.zacsweers.moshix", version.ref = "moshix" }
 kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
 kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
 spotless = { id = "com.diffplug.spotless", version = "6.23.2" }
 binaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.13.2" }
 retry = { id = "org.gradle.test-retry", version = "1.5.7" }
 
 [libraries]
+autoService-annotations = "com.google.auto.service:auto-service-annotations:1.1.1"
+autoService-ksp = "dev.zacsweers.autoservice:auto-service-ksp:1.1.0"
 bugsnag = "com.bugsnag:bugsnag:3.7.1"
 clikt = "com.github.ajalt.clikt:clikt:4.2.1"
 kotlinShell = "eu.jrie.jetbrains:kotlin-shell-core:0.2.1"

src/main/kotlin/slack/cli/CommandFactory.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright (C) 2023 Slack Technologies, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package slack.cli
+
+import com.github.ajalt.clikt.core.CliktCommand
+import java.util.ServiceLoader
+import kotlin.system.exitProcess
+
+/** Marker interface for a [CliktCommand] that can be aggregated and loaded via service loader. */
+public interface CommandFactory {
+  public val key: String
+  public val description: String
+
+  public fun create(): CliktCommand
+}
+
+/**
+ * Primary entry point to run any command registered via [CommandFactory]. First argument should be
+ * the command key and remaining arguments are passed to the created CLI.
+ */
+public fun runCommand(args: Array<String>, exitOnError: Boolean = true) {
+  val commands = ServiceLoader.load(CommandFactory::class.java).associateBy { it.key }
+
+  if (args.isEmpty()) {
+    System.err.println("Usage: <command> <args>")
+    System.err.println("Available commands:")
+    commands.forEach { (key, factory) -> System.err.println("  $key: ${factory.description}") }
+    if (exitOnError) {
+      exitProcess(1)
+    }
+  }
+
+  val command = args[0]
+  val commandArgs =
+    when (args.size) {
+      1 -> emptyArray()
+      else -> args.sliceArray(1..args.lastIndex)
+    }
+
+  commands[command]?.create()?.main(commandArgs) ?: error("Unknown command: '$command'")
+}

src/main/kotlin/slack/cli/gradle/GradleProjectFlattenerCli.kt

@@ -21,6 +21,7 @@ import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
 import com.github.ajalt.clikt.parameters.types.path
+import com.google.auto.service.AutoService
 import java.io.File
 import kotlin.io.path.ExperimentalPathApi
 import kotlin.io.path.appendLines
@@ -30,6 +31,7 @@ import kotlin.io.path.exists
 import kotlin.io.path.isDirectory
 import kotlin.io.path.readText
 import kotlin.io.path.relativeTo
+import slack.cli.CommandFactory
 import slack.cli.dryRunOption
 import slack.cli.projectDirOption
 
@@ -42,12 +44,21 @@ import slack.cli.projectDirOption
  *
  * It's recommended to run `./gradlew clean` first before running this script to minimize work.
  */
-public class GradleProjectFlattenerCli :
-  CliktCommand(
-    help =
+public class GradleProjectFlattenerCli : CliktCommand(help = DESCRIPTION) {
+
+  private companion object {
+    const val DESCRIPTION =
       "A CLI that flattens all gradle projects in a given directory to be top level while " +
         "preserving their original project paths."
-  ) {
+  }
+
+  @AutoService(CommandFactory::class)
+  public class Factory : CommandFactory {
+    override val key: String = "flatten-gradle-projects"
+    override val description: String = DESCRIPTION
+
+    override fun create(): CliktCommand = GradleProjectFlattenerCli()
+  }
 
   private val projectDir by projectDirOption()
 

src/main/kotlin/slack/cli/gradle/GradleSettingsVerifierCli.kt

@@ -19,6 +19,7 @@ import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
 import com.github.ajalt.clikt.parameters.types.path
+import com.google.auto.service.AutoService
 import java.io.File
 import kotlin.io.path.ExperimentalPathApi
 import kotlin.io.path.exists
@@ -27,11 +28,23 @@ import kotlin.io.path.name
 import kotlin.io.path.readText
 import kotlin.io.path.relativeTo
 import kotlin.system.exitProcess
+import slack.cli.CommandFactory
 import slack.cli.projectDirOption
 
 /** A CLI that verifies a given settings file has only valid projects. */
-public class GradleSettingsVerifierCli :
-  CliktCommand(help = "A CLI that verifies a given settings file has only valid projects.") {
+public class GradleSettingsVerifierCli : CliktCommand(help = DESCRIPTION) {
+
+  private companion object {
+    const val DESCRIPTION = "A CLI that verifies a given settings file has only valid projects."
+  }
+
+  @AutoService(CommandFactory::class)
+  public class Factory : CommandFactory {
+    override val key: String = "verify-gradle-settings"
+    override val description: String = DESCRIPTION
+
+    override fun create(): CliktCommand = GradleSettingsVerifierCli()
+  }
 
   private val projectDir by projectDirOption()
 

src/main/kotlin/slack/cli/lint/LintBaselineMergerCli.kt

@@ -20,6 +20,7 @@ import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
 import com.github.ajalt.clikt.parameters.types.path
+import com.google.auto.service.AutoService
 import com.tickaroo.tikxml.converter.htmlescape.StringEscapeUtils
 import io.github.detekt.sarif4k.ArtifactContent
 import io.github.detekt.sarif4k.ArtifactLocation
@@ -57,11 +58,23 @@ import kotlinx.serialization.json.Json
 import kotlinx.serialization.serializer
 import nl.adaptivity.xmlutil.serialization.XML
 import nl.adaptivity.xmlutil.serialization.XmlSerialName
+import slack.cli.CommandFactory
 import slack.cli.projectDirOption
 import slack.cli.skipBuildAndCacheDirs
 
 /** A CLI that merges lint baseline xml files into one. */
-public class LintBaselineMergerCli : CliktCommand("Merges multiple lint baselines into one") {
+public class LintBaselineMergerCli : CliktCommand(DESCRIPTION) {
+  private companion object {
+    const val DESCRIPTION = "Merges multiple lint baselines into one"
+  }
+
+  @AutoService(CommandFactory::class)
+  public class Factory : CommandFactory {
+    override val key: String = "merge-lint-baselines"
+    override val description: String = DESCRIPTION
+
+    override fun create(): CliktCommand = LintBaselineMergerCli()
+  }
 
   private val projectDir by projectDirOption()
 

src/main/kotlin/slack/cli/sarif/MergeSarifReports.kt

@@ -22,6 +22,7 @@ import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
 import com.github.ajalt.clikt.parameters.types.path
+import com.google.auto.service.AutoService
 import io.github.detekt.sarif4k.SarifSchema210
 import io.github.detekt.sarif4k.SarifSerializer
 import java.nio.file.Path
@@ -33,13 +34,19 @@ import kotlin.io.path.readText
 import kotlin.io.path.relativeTo
 import kotlin.io.path.writeText
 import kotlin.system.exitProcess
+import slack.cli.CommandFactory
 import slack.cli.projectDirOption
 import slack.cli.skipBuildAndCacheDirs
 
-public class MergeSarifReports :
-  CliktCommand(
-    help = "Merges all matching sarif reports into a single file for ease of uploading."
-  ) {
+public class MergeSarifReports : CliktCommand(help = DESCRIPTION) {
+
+  @AutoService(CommandFactory::class)
+  public class Factory : CommandFactory {
+    override val key: String = "merge-sarif-reports"
+    override val description: String = DESCRIPTION
+
+    override fun create(): CliktCommand = MergeSarifReports()
+  }
 
   private val projectDir by projectDirOption()
   private val outputFile by option("--output-file").path().required()
@@ -358,5 +365,7 @@ public class MergeSarifReports :
 
   private companion object {
     private const val SRC_ROOT = "%SRCROOT%"
+    const val DESCRIPTION =
+      "Merges all matching sarif reports into a single file for ease of uploading."
   }
 }

src/main/kotlin/slack/cli/shellsentry/ShellSentryCli.kt

@@ -21,7 +21,9 @@ import com.github.ajalt.clikt.parameters.arguments.multiple
 import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.types.path
+import com.google.auto.service.AutoService
 import org.jetbrains.annotations.TestOnly
+import slack.cli.CommandFactory
 import slack.cli.projectDirOption
 
 /**
@@ -33,8 +35,19 @@ import slack.cli.projectDirOption
  * $ ./<binary> --bugsnag-key=1234 --verbose --configurationFile config.json ./gradlew build
  * ```
  */
-public class ShellSentryCli :
-  CliktCommand("Executes a command with Bugsnag tracing and retries as needed.") {
+public class ShellSentryCli : CliktCommand(DESCRIPTION) {
+
+  private companion object {
+    const val DESCRIPTION = "Executes a command with Bugsnag tracing and retries as needed."
+  }
+
+  @AutoService(CommandFactory::class)
+  public class Factory : CommandFactory {
+    override val key: String = "shell-sentry"
+    override val description: String = DESCRIPTION
+
+    override fun create(): CliktCommand = ShellSentryCli()
+  }
 
   internal val projectDir by projectDirOption()