[sk-33] Feature: Kotlin Workflow CLI 구현

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## 해결하려는 문제
+
+> 어떤 문제를 해결하는지 적습니다. 필요에 따라 사진이나 링크를 첨부하고, 어떤 문제를 마주했는지에 집중해서 설명합니다.
+
+## 필요성
+
+> 문제를 해결해야 하는 이유를 적습니다. 어떤 불편이 생기는지, 왜 문제로 다뤄야 하는지 설명합니다.
+
+## 해결 방법
+
+> 문제를 어떤 방식으로 해결하는지 작성합니다. 설계부터 코드, 테스트까지 엔지니어링 영역에서 고려한 내용을 편안하게 설명합니다.
+
+## 한계와 트레이드오프
+
+> 해결하지 못해 추가 작업이 필요하거나 함께 고려했지만 선택하지 않은 내용을 공유합니다. 리뷰 과정에서 선택지와 그에 따른 영향을 폭넓게 검토할 수 있도록 적습니다.
+
+## 기존 기능에 미치는 영향
+
+> 기존 기능과 달라지는 부분이나 영향을 줄 수 있는 변경을 적습니다.
+
+## 예외 및 실패 사례
+
+> 아직 해결하지 못한 예외나 실패 사례가 있다면 작성합니다. 해결하지 못한 사항도 드러내어 이후 개선할 목표로 이어질 수 있게 합니다.

tools/workflow/MANUAL.md

@@ -0,0 +1,46 @@
+# Workflow 명령줄 도구
+
+Workflow CLI(Command line interface, 명령줄 인터페이스)는 저장소 루트에서 실행합니다.
+
+```sh
+tools/workflow/bin/workflow <명령> [인자와 옵션]
+```
+
+## 명령
+
+| 명령 | 필수 입력 | 주요 옵션과 동작 |
+| --- | --- | --- |
+| `start` | `--task <task-id>`, `--request-id <request-id>`, `--title <text>` | `--requires <subtask-id>`로 직접 선행 작업을 지정합니다. |
+| `check` | 없음 | 현재 Worktree 변경을 검증합니다. |
+| `review open` | `--body-file <경로>`, `--risk` (`normal` 또는 `high`) | 변경을 게시하고 초안 PR(Pull request)을 엽니다. |
+| `review show` | 없음 | `--diff`, `--threads` (`open` 또는 `all`)를 지원합니다. 기본 조회 범위는 `open`입니다. |
+| `review update` | `--revision <revision>` | 변경 커밋을 다시 게시합니다. `--body-file <경로>`를 지정하면 PR 설명도 갱신합니다. |
+| `review comment` | `--revision <revision>`, `--level` (`R`, `C` 또는 `A`), `--body <내용>` 또는 `--body-file <경로>` | 본문 입력은 하나만 지정합니다. 인라인 댓글에는 `--path <파일>`과 `--line <번호>`를 함께 지정합니다. |
+| `review reply` | `--revision <revision>`, `--thread <thread-id>`, `--body <내용>` 또는 `--body-file <경로>` | 본문 입력은 하나만 지정합니다. |
+| `review resolve` | `--revision <revision>`, `--thread <thread-id>` | 지정한 리뷰 대화를 해결 상태로 바꿉니다. |
+| `stack` | `--requires <subtask-id>` 또는 `--clear` | 두 옵션 중 하나만 지정합니다. |
+| `sync` | 없음 | `--continue`로 동기화를 계속하거나 `--abort`로 중단합니다. 두 옵션은 함께 쓸 수 없습니다. |
+| `status` | 없음 | 대상 조회에는 `--subtask`, `--task`, `--candidate`, `--release` 중 하나를 지정합니다. |
+| `gate ready <subtask-id>` | `--review-revision <revision>` | PR을 사람 검토 대상으로 전환합니다. |
+| `gate approve <subtask-id>` | `--change-revision <revision>` | 코드 변경을 승인합니다. |
+| `gate deploy <candidate-id>` | `candidate-id` 인자 | Production Canary 배포를 승인합니다. |
+| `gate release <release-id>` | `release-id` 인자 | 외부 공개를 승인합니다. |
+
+각 작업 명령에 `--json`을 붙이면 결과를 구조화된 JSON으로 출력합니다.
+
+`--allow-account-mismatch`는 `review update`, `review comment`, `review reply`, `review resolve`, `gate ready`, `gate approve`, `stack`, `sync`에서 사용할 수 있습니다. PR 변경 전에 현재 `gh` 사용자와 PR 작성자를 비교하며, 다르면 기본적으로 중단합니다. 이 옵션으로 계정 차이만 허용하면 작업을 계속하고 경고를 표준 오류(stderr)에 출력합니다. `--json` 결과는 표준 출력(stdout)에 유지됩니다.
+
+```sh
+tools/workflow/bin/workflow start --task SK-33 --request-id sk-33-start --title '문서 추가'
+tools/workflow/bin/workflow review open --body-file /tmp/pr-body.md --risk normal
+tools/workflow/bin/workflow review show --diff --threads all --json
+tools/workflow/bin/workflow review comment --revision abc123 --level C --body '[Agent] 검토 의견입니다.'
+tools/workflow/bin/workflow review update --revision rv-4 --allow-account-mismatch --json
+tools/workflow/bin/workflow status --subtask sk-33
+```
+
+## 댓글과 인증
+
+에이전트가 `review comment` 또는 `review reply`로 작성하는 댓글 본문은 `[Agent]`로 시작해야 합니다. `--body`와 `--body-file` 모두 같은 규칙을 적용합니다.
+
+Workflow CLI는 설정된 인증을 사용하며 로그인이나 인증 절차를 다시 실행하지 않습니다.

tools/workflow/build.gradle.kts

@@ -0,0 +1,84 @@
+import io.springkit.workflow.build.WorkflowNativeSmokeTest
+
+plugins {
+  kotlin("jvm") version "2.4.20"
+  kotlin("plugin.serialization") version "2.4.20"
+  application
+  id("com.diffplug.spotless") version "8.10.2"
+  id("org.graalvm.buildtools.native") version "1.1.14"
+}
+
+group = "io.springkit"
+
+version = "0.1.0-SNAPSHOT"
+
+java {
+  toolchain {
+    languageVersion = JavaLanguageVersion.of(21)
+  }
+}
+
+repositories {
+  mavenCentral()
+}
+
+application {
+  mainClass.set("io.springkit.workflow.MainKt")
+}
+
+dependencies {
+  implementation("com.github.ajalt.clikt:clikt:5.0.1")
+  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
+  implementation("com.squareup.okio:okio:3.18.1")
+
+  testImplementation("io.kotest:kotest-assertions-core:6.2.4")
+  testImplementation("io.kotest:kotest-runner-junit5:6.2.4")
+  testImplementation("com.squareup.okio:okio-fakefilesystem:3.18.1")
+  testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+kotlin {
+  jvmToolchain(21)
+}
+
+spotless {
+  isEnforceCheck = false
+
+  kotlin {
+    target("src/*/kotlin/**/*.kt", "buildSrc/src/**/*.kt")
+    ktfmt("0.63").metaStyle()
+  }
+
+  kotlinGradle {
+    target("*.gradle.kts", "buildSrc/*.gradle.kts")
+    ktfmt("0.63").metaStyle()
+  }
+}
+
+tasks.withType<Test>().configureEach {
+  useJUnitPlatform()
+}
+
+graalvmNative {
+  binaries {
+    named("main") {
+      imageName = "workflow"
+      buildArgs.add("--initialize-at-build-time=kotlin.DeprecationLevel")
+    }
+  }
+}
+
+val installWorkflowNative =
+    tasks.register<Copy>("installWorkflowNative") {
+      dependsOn("nativeCompile")
+      from(layout.buildDirectory.dir("native/nativeCompile")) {
+        include("workflow")
+      }
+      into(layout.projectDirectory.dir("bin"))
+    }
+
+tasks.register<WorkflowNativeSmokeTest>("workflowNativeSmokeTest") {
+  dependsOn(installWorkflowNative)
+  repositoryRoot.set(layout.projectDirectory.dir("../.."))
+  executable.set(layout.projectDirectory.file("bin/workflow"))
+}

tools/workflow/buildSrc/build.gradle.kts

@@ -0,0 +1,7 @@
+plugins {
+  `kotlin-dsl`
+}
+
+repositories {
+  mavenCentral()
+}

tools/workflow/buildSrc/src/main/kotlin/io/springkit/workflow/build/WorkflowNativeSmokeTest.kt

@@ -0,0 +1,189 @@
+package io.springkit.workflow.build
+
+import groovy.json.JsonSlurper
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.nio.charset.StandardCharsets
+import javax.inject.Inject
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.Internal
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
+import org.gradle.process.ExecOperations
+
+/*
+ * Native 바이너리의 시작과 JSON 결과 계약을 확인하는 최소 실행 검증입니다.
+ */
+abstract class WorkflowNativeSmokeTest : DefaultTask() {
+  @get:Inject abstract val execOperations: ExecOperations
+
+  /*
+   * 실행 위치와 환경 변수에만 사용하므로 입력 fingerprint에서 제외한 저장소 루트입니다.
+   */
+  @get:Internal abstract val repositoryRoot: DirectoryProperty
+
+  /*
+   * 시작과 JSON 결과 계약을 검증할 Native 실행 파일입니다.
+   */
+  @get:InputFile
+  @get:PathSensitive(PathSensitivity.RELATIVE)
+  abstract val executable: RegularFileProperty
+
+  @TaskAction
+  fun verifyNativeBinary() {
+    val repositoryRootFile = repositoryRoot.get().asFile
+    val executableFile = executable.get().asFile
+    val stateFile = temporaryDir.resolve("state.json")
+    stateFile.writeText(
+        """
+        {
+          "schema_version": 1,
+          "store_revision": 0,
+          "tasks": {
+            "smoke-task": {
+              "id": "smoke-task",
+              "external_id": {"value": "SMOKE-1"},
+              "title": "Native smoke task",
+              "state": "OPEN",
+              "sub_task_ids": []
+            }
+          }
+        }
+        """
+            .trimIndent()
+    )
+
+    val help = invoke(executableFile, repositoryRootFile, stateFile, "--help")
+    check(help.exitCode == 0) {
+      "Native 바이너리의 --help 실행이 실패했습니다. 종료 코드: ${help.exitCode}\n${help.stderr}"
+    }
+    check(help.stdout.contains("Usage: workflow")) {
+      "Native 바이너리가 도움말을 출력하지 않았습니다.\n${help.stdout}"
+    }
+
+    val success =
+        invoke(
+            executableFile,
+            repositoryRootFile,
+            stateFile,
+            "status",
+            "--task",
+            "smoke-task",
+            "--json",
+        )
+    requireJsonResult(success, expectedType = "success", expectedExitCode = 0)
+
+    val failure =
+        invoke(
+            executableFile,
+            repositoryRootFile,
+            stateFile,
+            "status",
+            "--subtask",
+            "missing-subtask",
+            "--json",
+        )
+    val failureJson = requireJsonResult(failure, expectedType = "failure", expectedExitCode = 1)
+    val failureData = failureJson["data"] as? Map<*, *>
+    check(failureData?.get("code") == "SUBTASK_NOT_FOUND") {
+      "대표 JSON 실패 코드가 예상과 다릅니다.\n${failure.stdout}"
+    }
+
+    val configurationFailure =
+        invoke(
+            executableFile,
+            repositoryRootFile,
+            stateFile,
+            "status",
+            "--json",
+            extraEnvironment =
+                mapOf(
+                    "WORKFLOW_DEPLOYMENT_COMMAND" to "[\"deploy\"]",
+                    "WORKFLOW_RELEASE_COMMAND" to "",
+                ),
+        )
+    val configurationJson =
+        requireJsonResult(configurationFailure, expectedType = "failure", expectedExitCode = 1)
+    val configurationData = configurationJson["data"] as? Map<*, *>
+    check(configurationData?.get("code") == "INVALID_ARGUMENT") {
+      "구성 오류가 공통 JSON 실패로 변환되지 않았습니다.\n${configurationFailure.stdout}"
+    }
+
+    val actorConfigurationFailure =
+        invoke(
+            executableFile,
+            repositoryRootFile,
+            stateFile,
+            "status",
+            "--json",
+            extraEnvironment = mapOf("WORKFLOW_ACTOR_KIND" to "HUMAN"),
+        )
+    val actorConfigurationJson =
+        requireJsonResult(actorConfigurationFailure, expectedType = "failure", expectedExitCode = 1)
+    val actorConfigurationData = actorConfigurationJson["data"] as? Map<*, *>
+    check(actorConfigurationData?.get("code") == "INVALID_ARGUMENT") {
+      "주체 종류 구성 오류가 공통 JSON 실패로 변환되지 않았습니다.\n${actorConfigurationFailure.stdout}"
+    }
+  }
+
+  private fun invoke(
+      executable: File,
+      repositoryRoot: File,
+      stateFile: File,
+      vararg arguments: String,
+      extraEnvironment: Map<String, String> = emptyMap(),
+  ): NativeInvocation {
+    val stdout = ByteArrayOutputStream()
+    val stderr = ByteArrayOutputStream()
+    val result = execOperations.exec {
+      commandLine(executable.absolutePath, *arguments)
+      workingDir(repositoryRoot)
+      environment("WORKFLOW_REPO_ROOT", repositoryRoot.absolutePath)
+      environment("WORKFLOW_STATE_FILE", stateFile.absolutePath)
+      extraEnvironment.forEach { (name, value) -> environment(name, value) }
+      standardOutput = stdout
+      errorOutput = stderr
+      isIgnoreExitValue = true
+    }
+    return NativeInvocation(
+        exitCode = result.exitValue,
+        stdout = stdout.toString(StandardCharsets.UTF_8.name()),
+        stderr = stderr.toString(StandardCharsets.UTF_8.name()),
+    )
+  }
+
+  private fun requireJsonResult(
+      invocation: NativeInvocation,
+      expectedType: String,
+      expectedExitCode: Int,
+  ): Map<*, *> {
+    check(invocation.exitCode == expectedExitCode) {
+      "JSON 경로의 종료 코드가 다릅니다. " +
+          "기대값: $expectedExitCode, 실제값: ${invocation.exitCode}\n${invocation.stderr}"
+    }
+    val lines = invocation.stdout.lineSequence().filter(String::isNotBlank).toList()
+    check(lines.size == 1) {
+      "JSON 경로는 표준 출력에 JSON 객체 하나만 기록해야 합니다.\n${invocation.stdout}"
+    }
+    val json = lines.single().trim()
+    val parsed = JsonSlurper().parseText(json) as? Map<*, *>
+    check(parsed != null) { "JSON 경로가 객체를 출력하지 않았습니다.\n$json" }
+    check(parsed["type"] == expectedType) {
+      "JSON 결과 type이 다릅니다. 기대값: $expectedType\n$json"
+    }
+    check(parsed["data"] is Map<*, *>) {
+      "JSON 결과에 data가 없습니다.\n$json"
+    }
+    return parsed
+  }
+
+  private data class NativeInvocation(
+      val exitCode: Int,
+      val stdout: String,
+      val stderr: String,
+  )
+}

tools/workflow/gradle.properties

@@ -0,0 +1,3 @@
+org.gradle.configuration-cache=true
+org.gradle.parallel=true
+kotlin.code.style=official

tools/workflow/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "workflow"