feat(orchestra): derive the flow-command schema from the parser's own types

maestro-client/src/main/java/maestro/KeyCode.kt

@@ -1,5 +1,13 @@
 package maestro
 
+/**
+ * A key `pressKey` can press. [description] is the word written in YAML, matched case-insensitively by
+ * [getByName]; the schema derived from the parser reads it through `@YamlValues(spelledBy = "description")`.
+ *
+ * The spelling deliberately does NOT live in a `@JsonProperty` on each constant. Jackson serializes this
+ * enum as `PressKeyCommand.code` on the MaestroCommand wire, where the constant name is what is written
+ * and read back, so renaming it there would break every command already persisted or in flight.
+ */
 enum class KeyCode(
     val description: String,
 ) {

maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt

@@ -1177,9 +1177,15 @@ data class StopRecordingCommand(
     }
 }
 
-enum class AirplaneValue {
-    Enable,
-    Disable,
+/**
+ * [yamlValue] is the word written in YAML. It is deliberately NOT a `@JsonProperty` on each constant:
+ * Jackson serializes this enum as `SetAirplaneModeCommand.value` on the MaestroCommand wire, where the
+ * constant name is what is written and read back, so renaming it there would break every command already
+ * persisted or in flight. The schema reads the word through `@YamlValues(spelledBy = "yamlValue")`.
+ */
+enum class AirplaneValue(val yamlValue: String) {
+    Enable("enabled"),
+    Disable("disabled"),
 }
 
 data class SetAirplaneModeCommand(
@@ -1210,9 +1216,15 @@ data class ToggleAirplaneModeCommand(
     }
 }
 
-enum class DarkModeValue {
-    Enable,
-    Disable,
+/**
+ * [yamlValue] is the word written in YAML. It is deliberately NOT a `@JsonProperty` on each constant:
+ * Jackson serializes this enum as `SetDarkModeCommand.value` on the MaestroCommand wire, where the
+ * constant name is what is written and read back, so renaming it there would break every command already
+ * persisted or in flight. The schema reads the word through `@YamlValues(spelledBy = "yamlValue")`.
+ */
+enum class DarkModeValue(val yamlValue: String) {
+    Enable("enabled"),
+    Disable("disabled"),
 }
 
 data class SetDarkModeCommand(

maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt

@@ -137,7 +137,11 @@ private fun String.indentWidth(): Int {
 
 // Each lambda receives a YamlFluentCommand pre-populated with sourceInfo, and
 // fills in the matching command field via copy().
-private val stringCommands = mapOf<String, (YamlFluentCommand) -> YamlFluentCommand>(
+//
+// Internal rather than private: this map is the only record of which commands may be written as a
+// bare string (`- back`), and maestro.orchestra.yaml.schema.FlowCommandSchema reads its keys so the
+// published schema cannot drift from what the parser accepts.
+internal val stringCommands = mapOf<String, (YamlFluentCommand) -> YamlFluentCommand>(
     "launchApp" to { it.copy(launchApp = YamlLaunchApp(
         appId = null,
         clearState = null,

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlAddMedia.kt

@@ -1,7 +1,9 @@
 package maestro.orchestra.yaml
 
 import com.fasterxml.jackson.annotation.JsonCreator
+import maestro.orchestra.yaml.schema.YamlRequiresOneOf
 
+@YamlRequiresOneOf("files")
 data class YamlAddMedia(
     val files: List<String?>? = null,
     val label: String? = null,

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlConfig.kt

@@ -1,7 +1,7 @@
 package maestro.orchestra.yaml
 
-import com.fasterxml.jackson.annotation.JsonAlias
 import com.fasterxml.jackson.annotation.JsonAnySetter
+import com.fasterxml.jackson.annotation.JsonProperty
 import com.fasterxml.jackson.core.JsonLocation
 import maestro.orchestra.ApplyConfigurationCommand
 import maestro.orchestra.MaestroCommand
@@ -18,7 +18,11 @@ class ConfigParseError(
 
 data class YamlConfig(
     val name: String?,
-    @JsonAlias("appId") private val _appId: String?,
+    // Named `_appId` only because the class exposes a computed `appId` below and Kotlin will not let a
+    // constructor parameter and a property share a name. `@JsonProperty` makes `appId` the wire name, so
+    // that collision stays an implementation detail: `appId:` is what a flow writes, `_appId:` is not
+    // accepted, and a schema derived from this type advertises `appId` rather than the private spelling.
+    @JsonProperty("appId") private val _appId: String?,
 
     val url: String?, // Raw url from YAML - preserved to distinguish web vs app configs
     val tags: List<String>? = emptyList(),

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlElementSelector.kt

@@ -20,6 +20,8 @@
 package maestro.orchestra.yaml
 
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize
+import maestro.orchestra.ElementTrait
+import maestro.orchestra.yaml.schema.YamlValues
 
 @JsonDeserialize(`as` = YamlElementSelector::class)
 data class YamlElementSelector(
@@ -32,14 +34,14 @@ data class YamlElementSelector(
     val retryTapIfNoChange: Boolean? = null,
     val waitUntilVisible: Boolean? = null,
     val point: String? = null,
-    val start: String? = null,
-    val end: String? = null,
     val below: YamlElementSelectorUnion? = null,
     val above: YamlElementSelectorUnion? = null,
     val leftOf: YamlElementSelectorUnion? = null,
     val rightOf: YamlElementSelectorUnion? = null,
     val containsChild: YamlElementSelectorUnion? = null,
     val containsDescendants: List<YamlElementSelectorUnion>? = null,
+    /** One or more trait names separated by spaces; each is looked up in [ElementTrait]. */
+    @YamlValues(ElementTrait::class)
     val traits: String? = null,
     val index: String? = null,
     val enabled: Boolean? = null,

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlExtendedWaitUntil.kt

@@ -1,5 +1,8 @@
 package maestro.orchestra.yaml
 
+import maestro.orchestra.yaml.schema.YamlRequiresOneOf
+
+@YamlRequiresOneOf("visible", "notVisible")
 data class YamlExtendedWaitUntil(
     val visible: YamlElementSelectorUnion? = null,
     val notVisible: YamlElementSelectorUnion? = null,

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlFluentCommand.kt

@@ -77,6 +77,7 @@ import maestro.orchestra.ToggleDarkModeCommand
 import maestro.orchestra.TravelCommand
 import maestro.orchestra.WaitForAnimationToEndCommand
 import maestro.orchestra.error.InvalidFlowFile
+import maestro.orchestra.yaml.schema.YamlValues
 import maestro.orchestra.error.MediaFileNotFound
 import maestro.orchestra.error.SyntaxError
 import maestro.orchestra.util.Env.withEnv
@@ -119,9 +120,9 @@ data class YamlFluentCommand(
     val setPermissions: YamlSetPermissions? = null,
     val swipe: YamlSwipe? = null,
     val openLink: YamlOpenLink? = null,
-    val openBrowser: String? = null,
     val pressKey: YamlPressKey? = null,
     val eraseText: YamlEraseText? = null,
+    @YamlValues(YamlNavigationAction::class, spelledBy = "yamlValue")
     val action: String? = null,
     val takeScreenshot: YamlTakeScreenshot? = null,
     val extendedWaitUntil: YamlExtendedWaitUntil? = null,
@@ -284,13 +285,13 @@ data class YamlFluentCommand(
 
             eraseText != null -> listOf(eraseCommand(eraseText))
             action != null -> listOf(
-                when (action) {
-                    "back" -> MaestroCommand(BackPressCommand())
-                    "hideKeyboard" -> MaestroCommand(HideKeyboardCommand())
-                    "scroll" -> MaestroCommand(ScrollCommand())
-                    "clearKeychain" -> MaestroCommand(ClearKeychainCommand())
-                    "pasteText" -> MaestroCommand(PasteTextCommand())
-                    else -> error("Unknown navigation target: $action")
+                when (YamlNavigationAction.entries.firstOrNull { it.yamlValue == action }) {
+                    YamlNavigationAction.Back -> MaestroCommand(BackPressCommand())
+                    YamlNavigationAction.HideKeyboard -> MaestroCommand(HideKeyboardCommand())
+                    YamlNavigationAction.Scroll -> MaestroCommand(ScrollCommand())
+                    YamlNavigationAction.ClearKeychain -> MaestroCommand(ClearKeychainCommand())
+                    YamlNavigationAction.PasteText -> MaestroCommand(PasteTextCommand())
+                    null -> error("Unknown navigation target: $action")
                 }
             )
 
@@ -921,12 +922,6 @@ data class YamlFluentCommand(
             }
 
             is YamlSwipeElement -> return swipeElementCommand(swipe)
-            else -> {
-                throw IllegalStateException(
-                    "Provide swipe direction UP, DOWN, RIGHT OR LEFT or by giving explicit " +
-                            "start and end coordinates."
-                )
-            }
         }
     }
 

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlNavigationAction.kt

@@ -0,0 +1,15 @@
+package maestro.orchestra.yaml
+
+/**
+ * The words `action` accepts. `action` is a legacy spelling of commands that all exist under their own
+ * names — `action: back` is `- back` — and it is a plain `String` so that it keeps parsing as one, but
+ * the set of words it takes is closed. Holding them here rather than as literals in a `when` is what
+ * lets the schema advertise them; [yamlValue] is the word, the constant name is not on any wire.
+ */
+enum class YamlNavigationAction(val yamlValue: String) {
+    Back("back"),
+    HideKeyboard("hideKeyboard"),
+    Scroll("scroll"),
+    ClearKeychain("clearKeychain"),
+    PasteText("pasteText"),
+}

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlPressKey.kt

@@ -1,16 +1,19 @@
 package maestro.orchestra.yaml
 
 import com.fasterxml.jackson.annotation.JsonCreator
+import maestro.KeyCode
+import maestro.orchestra.yaml.schema.YamlValues
 
 data class YamlPressKey (
+    @YamlValues(KeyCode::class, spelledBy = "description")
     val key: String,
     val label: String? = null,
     val optional: Boolean = false,
 ){
     companion object {
         @JvmStatic
         @JsonCreator(mode = JsonCreator.Mode.DELEGATING)
-        fun parse(key: String) = YamlPressKey(
+        fun parse(@YamlValues(KeyCode::class, spelledBy = "description") key: String) = YamlPressKey(
             key = key,
         )
     }

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlRetry.kt

@@ -1,5 +1,12 @@
 package maestro.orchestra.yaml
 
+import maestro.orchestra.yaml.schema.YamlRequiresOneOf
+
+// The order is the order a consumer should prefer, and the schema publishes it verbatim: `retry` has
+// no `retry: "path"` shorthand, so an inline block is the common way to write it. `runFlow` lists
+// `file` first for the opposite reason -- it does have that shorthand. Reordering either changes
+// what a consumer seeds, so it is a deliberate choice rather than declaration order.
+@YamlRequiresOneOf("commands", "file", exclusive = true)
 data class YamlRetryCommand(
     val maxRetries: String? = null,
     val file: String? = null,

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlRunFlow.kt

@@ -1,7 +1,9 @@
 package maestro.orchestra.yaml
 
 import com.fasterxml.jackson.annotation.JsonCreator
+import maestro.orchestra.yaml.schema.YamlRequiresOneOf
 
+@YamlRequiresOneOf("file", "commands", exclusive = true)
 data class YamlRunFlow(
     val file: String? = null,
     val `when`: YamlCondition? = null,

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlSetAirplaneMode.kt

@@ -7,48 +7,61 @@ import com.fasterxml.jackson.databind.DeserializationContext
 import com.fasterxml.jackson.databind.JsonDeserializer
 import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize
+import com.fasterxml.jackson.databind.node.TextNode
 import maestro.orchestra.AirplaneValue
+import maestro.orchestra.yaml.schema.YamlValues
 
 @JsonDeserialize(using = YamlSetAirplaneModeDeserializer::class)
 data class YamlSetAirplaneMode(
+    @YamlValues(AirplaneValue::class, spelledBy = "yamlValue")
     val value: AirplaneValue,
     val label: String? = null,
     val optional: Boolean = false,
 ) {
     companion object {
         @JvmStatic
         @JsonCreator(mode = JsonCreator.Mode.DELEGATING)
-        fun parse(value: AirplaneValue): YamlSetAirplaneMode {
+        fun parse(@YamlValues(AirplaneValue::class, spelledBy = "yamlValue") value: AirplaneValue): YamlSetAirplaneMode {
             return YamlSetAirplaneMode(value)
         }
     }
 }
 
+/**
+ * Accepts `setAirplaneMode: enabled` and the object form carrying `value`, `label` and `optional`.
+ *
+ * The accepted vocabulary is not spelled out here: it lives on [AirplaneValue] as `yamlValue`, read both by
+ * this deserializer and by the schema derived from these types, so the two cannot disagree. It is
+ * deliberately not a `@JsonProperty` on each constant -- that name is the MaestroCommand wire format.
+ */
 class YamlSetAirplaneModeDeserializer : JsonDeserializer<YamlSetAirplaneMode>() {
 
     override fun deserialize(parser: JsonParser, ctxt: DeserializationContext): YamlSetAirplaneMode {
-        val mapper = (parser.codec as ObjectMapper)
+        val mapper = parser.codec as ObjectMapper
         val root: TreeNode = mapper.readTree(parser)
-        val input = root.fieldNames().asSequence().toList()
-        val label = getLabel(root)
-        when {
-            input.contains("value") -> {
-                val parsedValue = root.get("value").toString().replace("\"", "")
-                val returnValue = when (parsedValue) {
-                    "enabled" -> AirplaneValue.Enable
-                    "disabled" -> AirplaneValue.Disable
-                    else -> throwInvalidInputException(input)
-                }
-                return YamlSetAirplaneMode(returnValue, label)
-            }
-            (root.isValueNode && root.toString().contains("enabled")) -> {
-                return YamlSetAirplaneMode(AirplaneValue.Enable, label)
-            }
-            (root.isValueNode && root.toString().contains("disabled")) -> {
-                return YamlSetAirplaneMode(AirplaneValue.Disable, label)
-            }
-            else -> throwInvalidInputException(input)
+
+        if (root.isValueNode) {
+            return YamlSetAirplaneMode(toAirplaneValue(root))
         }
+
+        val valueNode = root.get("value")
+            ?: throwInvalidInputException(root.fieldNames().asSequence().toList())
+
+        return YamlSetAirplaneMode(
+            value = toAirplaneValue(valueNode),
+            label = root.get("label")?.let { mapper.convertValue(it, String::class.java) },
+            optional = root.get("optional")?.let { mapper.convertValue(it, Boolean::class.java) } ?: false,
+        )
+    }
+
+    /**
+     * Looks the word up on [AirplaneValue] rather than letting Jackson convert it, so the constant names stay
+     * the MaestroCommand wire format while YAML keeps its own spelling. Still derived from the enum, so
+     * the parser and the schema cannot disagree.
+     */
+    private fun toAirplaneValue(node: TreeNode): AirplaneValue {
+        val text = (node as? TextNode)?.textValue() ?: throwInvalidInputException(listOf(node.toString()))
+        return AirplaneValue.entries.firstOrNull { it.yamlValue == text } ?: throwInvalidInputException(listOf(text))
     }
 
     private fun throwInvalidInputException(input: List<String>): Nothing {
@@ -60,13 +73,4 @@ class YamlSetAirplaneModeDeserializer : JsonDeserializer<YamlSetAirplaneMode>()
                     "It seems you provided invalid input with: $input"
         )
     }
-
-    private fun getLabel(root: TreeNode): String? {
-        return if (root.path("label").isMissingNode) {
-            null
-        } else {
-            root.path("label").toString().replace("\"", "")
-        }
-    }
-
 }