feat: support device selector for runtime url

Author: linhay

.agents/tritonkit-skills/public/tritonkit-dev-feedback/SKILL.md

@@ -103,7 +103,7 @@ Repository: `NeptuneKit/TritonKit` (`https://github.com/NeptuneKit/TritonKit`)
      - host-side layout and screenshot artifacts may contain private UI data; inspect or summarize instead of attaching raw files when redaction is uncertain.
      - when a disposable HarmonyOS NEXT smoke app is needed, use the local `harmony-next` skill's `references/quickStart/ets/minimal-project-scaffold.md` and copy `references/templates/empty-ability-app/` instead of hand-rolling `oh-package.json5` / `module.json5` / `hvigorfile.ts`.
    - Harmony embedded SDK feedback should distinguish generic HAR capability from app-provided semantics:
-     - run `triton device runtime-url --platform harmony --target <hdc-target> --probe-manifest --json` first when the runtime is on a Harmony emulator/device and the host needs an HDC fport base URL;
+     - run `triton device runtime-url --device harmony-a --probe-manifest --json` first when the runtime is on a Harmony emulator/device and the host needs an HDC fport base URL; `--platform harmony --target <hdc-target>` remains available as a compatibility path;
      - Harmony demo host-access embedded runtime defaults to `http://127.0.0.1:28767`; `18765` is the demo device-to-host gateway fallback port and should not be treated as the host direct runtime default;
      - if an HDC fport already exists, use `docs-linhay/scripts/verify-harmony-runtime-emulator-smoke.sh --target <hdc-target> --no-forward` to verify the live endpoint without re-registering the same port mapping;
      - use `triton runtime manifest --runtime-base-url http://127.0.0.1:<port> --json`, `triton state route --runtime-base-url ... --json`, `triton snapshot --runtime-base-url ... --json`, `triton ledger --runtime-base-url ... --jsonl`, and `triton set-text "密码" "$TRITON_PASSWORD" --secure --runtime-base-url ... --json` when validating a standalone embedded HTTP runtime before it is connected through `triton serve`;
@@ -401,7 +401,8 @@ Business semantics must be app-provided. A generic HAR should return `unsupporte
 When validating a standalone embedded HTTP runtime before it is connected through `triton serve`, first ask Triton to prepare or discover the HDC fport URL, then use direct runtime commands:
 
 ```bash
-triton device runtime-url --platform harmony --target 127.0.0.1:10100 --probe-manifest --json
+triton device alias set harmony-a --platform harmony --target 127.0.0.1:10100 --json
+triton device runtime-url --device harmony-a --probe-manifest --json
 triton runtime manifest --runtime-base-url http://127.0.0.1:28767 --json
 triton state route --runtime-base-url http://127.0.0.1:28767 --json
 triton snapshot --runtime-base-url http://127.0.0.1:28767 --json

.agents/tritonkit-skills/public/tritonkit-emulator-cli-takeover/SKILL.md

@@ -82,7 +82,7 @@ triton device screenshot --device iphone15 --output /tmp/<case>-sim.png --json
 triton device screenshot --device harmony-a --output /tmp/<case>.jpeg --json
 ```
 
-Use `--device <selector>` as the default agent-facing target selector for common host-side commands. Selectors can be aliases, full ids such as `sim:<udid>` / `harmony:<target>`, raw platform ids, `booted`, or `current`. `--platform`, `--name`, `--runtime`, `--state`, and `--ready` are filters; they may auto-select only when the filtered candidate set is unique. Keep `sim` for iOS-only advanced maintenance and `device runtime-url` for Harmony embedded runtime port-forward setup.
+Use `--device <selector>` as the default agent-facing target selector for common host-side commands. Selectors can be aliases, full ids such as `sim:<udid>` / `harmony:<target>`, raw platform ids, `booted`, or `current`. `--platform`, `--name`, `--runtime`, `--state`, and `--ready` are filters; they may auto-select only when the filtered candidate set is unique. Keep `sim` for iOS-only advanced maintenance; `device runtime-url --device <selector>` is the Harmony embedded runtime port-forward setup path, with `--platform harmony --target <target>` retained for compatibility.
 
 iOS Simulator:
 
@@ -160,6 +160,8 @@ triton node resolve --device harmony-a --text "登录" --json
 Standalone Harmony embedded HTTP runtime:
 
 ```bash
+triton device runtime-url --device harmony-a --probe-manifest --json
+# Compatibility path:
 triton device runtime-url --platform harmony --target <hdc-target> --probe-manifest --json
 triton runtime manifest --runtime-base-url http://127.0.0.1:28767 --json
 triton state route --runtime-base-url http://127.0.0.1:28767 --json

.agents/tritonkit-skills/public/tritonkit-real-project-regression/SKILL.md

@@ -101,7 +101,7 @@ Real-project validation is not the same as demo smoke. Treat the business app as
      - stable UI signals: `Harmony Smoke Ready`, `smoke-title`, `smoke-counter`, `smoke-increment`;
      - validation path: `ohpm install`, `hvigorw --mode module -p module=entry@default assembleHap`, HDC install/start, `uitest dumpLayout`, and `uitest screenCap`.
    - when validating a standalone Harmony embedded HTTP runtime before it is connected through `triton serve`, use direct runtime checks:
-     - `triton device runtime-url --platform harmony --target <hdc-target> --probe-manifest --json` to prepare HDC fport and get the `baseURL`;
+     - `triton device runtime-url --device harmony-a --probe-manifest --json` to prepare HDC fport and get the `baseURL`; `--platform harmony --target <hdc-target>` remains available as a compatibility path;
      - the Harmony demo host-access embedded runtime default is `http://127.0.0.1:28767`; `18765` is reserved for the demo device-to-host gateway fallback path;
      - `triton runtime manifest --runtime-base-url http://127.0.0.1:<port> --json`;
      - `triton state route --runtime-base-url http://127.0.0.1:<port> --json`;
@@ -299,7 +299,7 @@ Business semantics are not generic HAR capabilities. Route, responder, and seman
 For a standalone Harmony embedded runtime before it is connected through `triton serve`, use direct runtime checks:
 
 ```bash
-triton device runtime-url --platform harmony --target <hdc-target> --probe-manifest --json
+triton device runtime-url --device harmony-a --probe-manifest --json
 triton runtime manifest --runtime-base-url http://127.0.0.1:28767 --json
 triton state route --runtime-base-url http://127.0.0.1:28767 --json
 triton snapshot --runtime-base-url http://127.0.0.1:28767 --json

CLI/Tests/TritonKitCLITests/DeviceCrossPlatformTests.swift

@@ -18,10 +18,12 @@ struct DeviceCrossPlatformTests {
         #expect(optionNames.contains("resolve <selector>"))
         #expect(optionNames.contains("wait-ready --device <selector>"))
         #expect(optionNames.contains("screenshot --device <selector> --output <path>"))
+        #expect(optionNames.contains("runtime-url --device <selector>"))
         #expect(optionNames.contains("--device"))
         #expect(optionNames.contains("--name"))
         #expect(optionNames.contains("--runtime"))
         #expect(optionNames.contains("runtime-url --platform harmony --target <target>"))
+        #expect(device.examples.contains("triton device runtime-url --device harmony-a --probe-manifest --json"))
         #expect(device.providedCapabilities.contains("host-device"))
         #expect(device.providedCapabilities.contains("device-alias"))
         #expect(device.providedCapabilities.contains("host-device-selector"))
@@ -96,6 +98,28 @@ struct DeviceCrossPlatformTests {
         #expect(harmony.transport == "TCP")
     }
 
+    @Test("host device target can round-trip into Harmony runtime target")
+    func hostDeviceTargetCanRoundTripIntoHarmonyRuntimeTarget() {
+        let target = HostDeviceTarget(
+            platform: "harmony",
+            id: "harmony:127.0.0.1:10100",
+            target: "127.0.0.1:10100",
+            state: "Connected",
+            ready: true,
+            source: "hdc",
+            name: nil,
+            runtime: nil,
+            transport: "TCP"
+        )
+
+        let harmony = harmonyTarget(from: target)
+
+        #expect(harmony.target == "127.0.0.1:10100")
+        #expect(harmony.state == "Connected")
+        #expect(harmony.transport == "TCP")
+        #expect(harmony.source == "hdc")
+    }
+
     @Test("host device selector prefers explicit matches and unique ready candidates")
     func hostDeviceSelectorPrefersExplicitMatchesAndUniqueReadyCandidates() {
         let first = HostDeviceTarget(

README.md

@@ -299,14 +299,17 @@ When multiple iOS Simulator apps are connected to the same `triton serve`, `trit
 When validating a standalone embedded runtime HTTP endpoint before it is connected through `triton serve`, bypass the local control server with `--runtime-base-url`:
 
 ```bash
-triton device runtime-url --platform harmony --target 127.0.0.1:10100 --probe-manifest --json
+triton device alias set harmony-a --platform harmony --target 127.0.0.1:10100 --json
+triton device runtime-url --device harmony-a --probe-manifest --json
 triton runtime manifest --runtime-base-url http://127.0.0.1:28767 --json
 triton state route --runtime-base-url http://127.0.0.1:28767 --json
 triton snapshot --runtime-base-url http://127.0.0.1:28767 --json
 triton ledger --runtime-base-url http://127.0.0.1:28767 --jsonl
 triton set-text "密码" "$TRITON_PASSWORD" --secure --runtime-base-url http://127.0.0.1:28767 --json
 ```
 
+`triton device runtime-url --platform harmony --target 127.0.0.1:10100 --probe-manifest --json` remains available as a compatibility path.
+
 For the Harmony demo, `28767` is the host-access embedded runtime port exposed through HDC `fport`; `18765` remains the device-to-host gateway fallback port used by the demo UI.
 
 Host-side simulator helpers are available without a running TritonKit runtime. They wrap `xcrun simctl` but keep JSON output and stable Triton error envelopes:
@@ -511,14 +514,17 @@ Business semantics are opt-in provider hooks. A generic HAR must not pretend it
 When the Harmony embedded runtime is reachable through HDC `fport` but has not been connected through `triton serve`, use direct runtime checks:
 
 ```bash
-triton device runtime-url --platform harmony --target 127.0.0.1:10100 --probe-manifest --json
+triton device alias set harmony-a --platform harmony --target 127.0.0.1:10100 --json
+triton device runtime-url --device harmony-a --probe-manifest --json
 triton runtime manifest --runtime-base-url http://127.0.0.1:28767 --json
 triton state route --runtime-base-url http://127.0.0.1:28767 --json
 triton snapshot --runtime-base-url http://127.0.0.1:28767 --json
 triton ledger --runtime-base-url http://127.0.0.1:28767 --jsonl
 triton set-text "密码" "$TRITON_PASSWORD" --secure --runtime-base-url http://127.0.0.1:28767 --json
 ```
 
+`triton device runtime-url --platform harmony --target 127.0.0.1:10100 --probe-manifest --json` remains available as a compatibility path.
+
 For the Harmony demo, `28767` is the host-access embedded runtime port exposed through HDC `fport`; `18765` remains the device-to-host gateway fallback port used by the demo UI.
 
 ## Release Assets

Sources/TritonKitCLI/CLIHostCommands.swift

@@ -2062,7 +2062,12 @@ struct DeviceRuntimeURL: AsyncParsableCommand {
     static let configuration = CommandConfiguration(commandName: "runtime-url", abstract: "Prepare and print a Harmony embedded runtime base URL")
 
     @Option(help: "Platform adapter: harmony") var platform: HostDevicePlatform = .harmony
-    @Option(help: "Target id, for example 127.0.0.1:10100") var target: String?
+    @Option(help: "Unified host device selector: alias, harmony:<target>, raw id, or current") var device: String?
+    @Option(help: "Target id, for example 127.0.0.1:10100; compatibility path") var target: String?
+    @Option(help: "Device name filter when available") var name: String?
+    @Option(help: "Runtime filter when available") var runtime: String?
+    @Option(help: "Target state filter, for example connected") var state: String?
+    @Flag(help: "Only match ready targets") var ready = false
     @Option(help: "Path to hdc executable") var hdc: String = "hdc"
     @Option(help: "Local TCP port for host-side runtime access") var localPort: Int = TKHarmonyRuntimeDefaults.hostAccessPort
     @Option(help: "Remote TCP port where the Harmony embedded runtime listens") var remotePort: Int = TKHarmonyRuntimeDefaults.hostAccessPort
@@ -2077,9 +2082,23 @@ struct DeviceRuntimeURL: AsyncParsableCommand {
             guard platform == .harmony else {
                 throw RuntimeError("device runtime-url only supports Harmony targets")
             }
+            if device != nil && target != nil {
+                throw HostDeviceSelectionError.parameterConflict("--device cannot be combined with --target.")
+            }
             try validateTCPPort(localPort, name: "--local-port")
             try validateTCPPort(remotePort, name: "--remote-port")
-            let selected = try resolveHarmonyTarget(target: target, hdc: hdc)
+            let selection = try resolveHostDeviceSelection(
+                request: HostDeviceSelectionRequest(
+                    device: device ?? target,
+                    platform: .harmony,
+                    name: name,
+                    runtime: runtime,
+                    state: state,
+                    ready: ready
+                ),
+                hdc: hdc
+            )
+            let selected = harmonyTarget(from: selection.target)
             let baseURL = "http://127.0.0.1:\(localPort)"
             var sourceCommand: String?
             var forwarded = false

Sources/TritonKitCLI/CLIHostRuntime.swift

@@ -538,6 +538,15 @@ func hostDeviceTarget(from target: TKHarmonyTarget) -> HostDeviceTarget {
     )
 }
 
+func harmonyTarget(from target: HostDeviceTarget) -> TKHarmonyTarget {
+    TKHarmonyTarget(
+        target: target.target,
+        state: target.state,
+        transport: target.transport ?? "hdc",
+        source: target.source
+    )
+}
+
 func ensureParentDirectory(for path: String) throws {
     let directory = URL(fileURLWithPath: path).deletingLastPathComponent()
     try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
@@ -614,13 +623,7 @@ func captureHostDeviceScreenshot(platform: HostDevicePlatform, target: HostDevic
             note: "Host-side iOS simulator screenshot was written."
         )
     case .harmony:
-        let harmonyTarget = TKHarmonyTarget(
-            target: target.target,
-            state: target.state,
-            transport: target.transport ?? "hdc",
-            source: target.source
-        )
-        let capture = try captureHarmonyScreenshot(selected: harmonyTarget, hdc: hdc, output: output)
+        let capture = try captureHarmonyScreenshot(selected: harmonyTarget(from: target), hdc: hdc, output: output)
         return HostDeviceArtifactOutput(
             ok: true,
             action: "screenshot",
@@ -667,12 +670,7 @@ func waitForHostDeviceReady(
                 return event
             }
         case .harmony:
-            let harmonyTarget = TKHarmonyTarget(
-                target: selected.target,
-                state: selected.state,
-                transport: selected.transport ?? "hdc",
-                source: selected.source
-            )
+            let harmonyTarget = harmonyTarget(from: selected)
             let command = TKHarmonyHDCCommand.bootCompleted(target: harmonyTarget.target, executable: hdc)
             let result = try runHostCommand(command)
             let ready = TKHarmonyBootCompletedParser.isReady(result.stdout)

Sources/TritonKitCLI/CLISchemaRuntime.swift

@@ -815,7 +815,8 @@ func commandSchemas() -> [TKCommandSchema] {
                 TKCommandSchemaOption(name: "resolve <selector>", type: "Subcommand", description: "Resolve a target selector without executing an action"),
                 TKCommandSchemaOption(name: "wait-ready --device <selector>", type: "Subcommand", description: "Wait for iOS Booted or Harmony bootevent.boot.completed"),
                 TKCommandSchemaOption(name: "screenshot --device <selector> --output <path>", type: "Subcommand", description: "Capture a host-side iOS or Harmony screenshot artifact"),
-                TKCommandSchemaOption(name: "runtime-url --platform harmony --target <target>", type: "Subcommand", description: "Prepare HDC fport and print a direct embedded runtime base URL"),
+                TKCommandSchemaOption(name: "runtime-url --device <selector>", type: "Subcommand", description: "Prepare HDC fport and print a direct Harmony embedded runtime base URL"),
+                TKCommandSchemaOption(name: "runtime-url --platform harmony --target <target>", type: "Subcommand", description: "Compatibility path for preparing a direct Harmony embedded runtime base URL"),
                 TKCommandSchemaOption(name: "--platform", type: "ios|harmony", defaultValue: "harmony", description: "Host device platform adapter"),
                 TKCommandSchemaOption(name: "--device", type: "String", description: "Unified target selector: alias, sim:<udid>, harmony:<target>, raw id, booted, or current"),
                 TKCommandSchemaOption(name: "--name", type: "String", description: "Device name filter, for example iPhone 15"),
@@ -847,6 +848,7 @@ func commandSchemas() -> [TKCommandSchema] {
                 "triton device alias set harmony-a --platform harmony --target 127.0.0.1:10100 --json",
                 "triton device wait-ready --device harmony-a --json",
                 "triton device screenshot --device harmony-a --output /tmp/smoke.jpeg --json",
+                "triton device runtime-url --device harmony-a --probe-manifest --json",
                 "triton device runtime-url --platform harmony --target 127.0.0.1:10100 --probe-manifest --json",
             ],
             successShape: "{ ok, platform, tools[]?, targets[]?, defaultTarget?, target?, defaultsPath?, ready?, artifact?, baseURL?, manifest?, sourceCommand?, sourceCommands?[] }",