feat: add HarmonyOS platform support

[wz9527]

Summary

Add HarmonyOS (OpenHarmony / HarmonyOS NEXT) platform support to agent-device, enabling CLI control of HarmonyOS physical devices and emulators via HDC (HarmonyOS Device
Connector).

What was implemented

Device connection and discovery

• Device communication via HDC (hdc -t <serial>)
• devices command lists connected HarmonyOS devices
• Device serial number used as unique identifier

App lifecycle

• apps: lists installed apps via bm dump -a and wukong appinfo, automatically resolves launchAbility
• open: 5-strategy launch chain (wukong → uitest → hdc aa start → EntryAbility → system default)
• close: stops app via aa force-stop
• install / reinstall: installs HAP packages via hdc install / uninstall
• appstate: reads foreground app via aa dump -l

UI interactions

• Tap / long-press / swipe: based on uitest uiInput commands
• Scroll: calculates gesture plan from screen dimensions
• Keyboard: supports status, dismiss, and enter; detects keyboard visibility via WindowManagerService dump
• Text input: fill includes verification and retry (reads back text via dumpLayout snapshot to confirm)
• Clipboard: based on uitest uiInput getClipboard / setClipboard

Snapshot and screenshot

• snapshot: generates ArkUI component tree from uitest dumpLayout, supports interactiveOnly, compact, depth, scope, and raw modes
• screenshot: captures screen via snapshot_display

System functions

• alert: supports accept, dismiss, and wait; includes bilingual (EN/CN) button matching and auto-dismiss of system dialogs
• settings: animations, clear-app-state, dark-mode, wifi, location, bluetooth, volume, brightness, and permissions
• rotate: sets screen orientation via DisplayManagerService or param
• logs: reads logs via hilog
• perf: reads CPU / memory / process info via hidumper
• push: sends test notifications via aa send

CLI and help

• --platform harmonyos flag support
• agent-device help harmonyos complete help topic
• Examples updated with HarmonyOS usage

Known limitations

The following commands are not supported on HarmonyOS:

• boot: device boot
• network: network traffic capture (hilog lacks PID filtering, cannot implement reliably)
• pinch / rotate-gesture / transform-gesture: multi-touch gestures (uitest does not support)

Test results

Tested on HarmonyOS NEXT physical device (22M0223824043030):

Command	Status
devices	✅
apps (with EntryAbility shown)	✅
open --activity	✅
close	✅
install / reinstall	✅
snapshot / snapshot -i	✅
screenshot	✅
press / click / longpress	✅
swipe / scroll / fling / pan	✅
home / back / app-switcher	✅
rotate	✅
fill (with verification)	✅
type	✅
keyboard status / dismiss / enter	✅
clipboard read / write	✅
alert accept / dismiss / wait	✅
settings animations / clear-app-state / dark-mode	✅
logs / perf	✅
push	✅
boot	❌ expected unsupported
network	❌ expected unsupported
gesture pinch / rotate / transform	❌ expected unsupported

[wz9527]

Context for this PR:

This PR is a re-implementation of HarmonyOS platform support based on the latest main branch.

I previously submitted an initial version in #613, but that was based on an older main branch (roughly 89 commits behind). During that period, the main branch evolved
significantly with major refactors to core files like capabilities.ts, dispatch.ts, and cli-flags.ts, making a direct rebase impractical due to massive conflicts. I chose to
create a fresh branch from the latest main (6946c2f) and migrate the HarmonyOS support code file by file.

Both versions implement the same feature set, but this version:

• Targets the latest type system and architecture
• Fixes the incomplete keyboard action enum issue left in feat: add HarmonyOS platform support #613
• Adds install / reinstall support
• Adds fill text verification and push notification support
• Updates the help system with the help harmonyos topic

If maintainers previously reviewed #613, the core platform implementation logic (under platforms/harmonyos/) remains essentially unchanged — this is primarily an adaptation to the
latest interfaces and types. The old PR #613 can be closed.

[thymikee]

Thanks for the contribution. This is a big piece of work, and directionally the approach looks right to me: HDC as the transport, uitest dumpLayout / uiInput for snapshot + input, aa for ability launch, and bm for app inventory/install all line up with the HarmonyOS/OpenHarmony docs I checked.

I found a few things that I think need fixing before we can land this:

1. pnpm check:quick currently fails on a duplicate import in src/platforms/harmonyos/snapshot.ts (../../utils/snapshot.ts is imported twice). Typecheck passes, but lint blocks CI.

2. record is marked as supported for HarmonyOS in src/core/capabilities.ts, but the daemon recording path is not wired for HarmonyOS. In record-trace-recording.ts, non-iOS/macOS devices fall through to startAndroidRecording, so record start --platform harmonyos will try the Android/ADB path instead of the new HarmonyOS recording helpers.

3. settings permission deny ... --platform harmonyos looks wrong: setHarmonyPermission parses grant|deny|reset, but both grant and deny currently execute bm grant-permission. If deny is not supported yet, I think we should reject it explicitly instead of silently granting.

4. The typed Node client normalization needs HarmonyOS fields. The daemon returns bundleName for HarmonyOS install/reinstall, but normalizeDeployResult only reads bundleId / package, so apps.install() / apps.reinstall() lose appId. normalizeOpenDevice also rejects platform: "harmonyos", so apps.open() loses device metadata for HarmonyOS sessions.

5. There is a likely typo in the locked-screen fallback: app-lifecycle.ts uses uitest ui-input swipe, while the rest of the implementation and the docs use uitest uiInput.

Validation I ran:

• pnpm typecheck passes
• pnpm exec vitest run --project unit src/platforms/harmonyos passes: 6 files, 20 tests
• pnpm check:quick fails on the duplicate import above

I also tried to validate locally. I have DevEco Studio installed on macOS/Apple Silicon; bundled hdc works outside the sandbox and reports Ver: 3.1.0e, but hdc list targets returns [Empty]. I can see the DevEco emulator binary, but I do not have a local HarmonyOS emulator image/device configured.

Could you share the exact steps you used to install/create a HarmonyOS emulator on macOS? A DevEco menu path is fine, but a CLI-friendly flow would be even better if one exists. That would help us verify this against a real emulator in addition to the physical-device testing you already did.

[wz9527]

@thymikee

To use the HarmonyOS emulator, follow these steps:
Launch DevEco Studio My version is 6.0.2 Release
In the top-right corner of the IDE, click No Devices, then choose Device Manager.
In Device Manager, click New Emulator in the bottom-right corner and follow the wizard to create the emulator.

I need some time to review the other 4 bux.