dsh-apk-vm 0.12.0 → 0.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,9 +1,65 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.2
4
+
5
+ ### Fixed
6
+
7
+ - **Panel version chip reported `v0.11.1`.** `client.js` kept a hand-maintained `CLIENT_VERSION`
8
+ constant that was never bumped after 0.11.1, so the header pill showed the wrong version on
9
+ 0.12.0/0.12.1 even though the host reported the correct `pluginVersion`. The chip now prefers
10
+ the host-reported version, the constant is set to `0.12.2`, and `scripts/check-version.mjs`
11
+ (run by `npm run check`) fails the build when `CLIENT_VERSION` and `package.json` disagree.
12
+
13
+ ## 0.12.1
14
+
15
+ ### Added
16
+
17
+ - **Remote VM multi-session.** Remote hosts are now first-class VM sources: profiles live in
18
+ `<profile>/.apk-vm/remote-profiles.json` (validated, no key contents), `RemoteSessionManager`
19
+ can run several sessions concurrently (`remoteMaxSessions`, default 4), each with its own AVD,
20
+ adb tunnel, H.264 stream and instance id. New helpers: `RemoteProfileBook`,
21
+ `RemoteSessionManager`, `normalizeExtraEmulatorArgs`, `parseRemoteListeningPorts`;
22
+ `lib/remote-instance.js` implements the remote instance surface. Remote `disconnect` now kills
23
+ the remote emulator through `<sdkRoot>/platform-tools/adb` (fixed: non-interactive SSH PATH
24
+ often has no adb). Covered by `spike/remote-test.mjs` (45 checks) and
25
+ `spike/remote-instance-test.mjs` (23 checks).
26
+ - **Emulator inventory.** `GET /apk-vm/emulators` merges local AVD/device state with every saved
27
+ remote host (`lib/emulator-inventory.js`, one SSH round trip per host) plus the panel
28
+ "Available emulators" card.
29
+ - **Virtual camera.** Camera back/front modes and `-virtualscene-poster` posters, managed by
30
+ `GET/POST /apk-vm/camera`, the panel Media card, or `cfg.camera` (`lib/media.js`).
31
+ - **Virtual microphone.** Mic modes `off` / `host` / `file`; file mode loops audio into a
32
+ virtual PulseAudio source (null-sink + remap-source) and is available on Linux and remote
33
+ hosts; managed by `GET/POST /apk-vm/mic`, the panel Media card, or `cfg.mic`.
34
+ - **Remote VM host over SSH (远端虚拟机).** `/apk-vm/remote` now turns an SSH-reachable host
35
+ into the VM proxy instead of only opening a bare tunnel: it forwards a loopback port to the
36
+ remote emulator's adb port, runs `adb connect` and attaches the device to the normal
37
+ boot-wait/H.264/input/debug path. `launch: true` starts a fixed headless emulator
38
+ (`-no-window -no-audio -no-boot-anim -gpu swiftshader_indirect`) on the remote host over the
39
+ same connection, and `disconnect` can stop it again. The validated profile (host/user/ports/
40
+ AVD; no key material) is persisted under `<profile>/.apk-vm/remote-profile.json`, the panel
41
+ card prefills from it and polls the tunnel/launch state every two seconds. New helpers in
42
+ `lib/remote.js` and a rewritten `spike/remote-test.mjs` (27 checks: validation/injection
43
+ safety, fixed command builders, profile store, bounded `runSshCommand`, route round-trip).
44
+
45
+ ### Changed
46
+
47
+ - New plugin icon (`icon.svg`, 36×36): layered screens in lemon/grass-green and violet, replacing
48
+ the thin `currentColor` glyph that rendered nearly invisible on dark tiles.
49
+ - Refreshed the demo screenshots from the 0.12.0 panel UI (main panel, Activity card, guest,
50
+ Environment, APK files and Rooted debug cards). Private host details — the Windows user name,
51
+ real APK names/paths and the assistant avatar — are masked with Gaussian blur.
52
+
53
+ ### Removed
54
+
55
+ - `docs/screenshot-sidebar.png`: replaced by the refreshed panel and card screenshots.
56
+
3
57
  ## 0.12.0
4
58
 
5
- WebView read-out and remembered-APK release: `webviewAction=eval` now returns real values, and
6
- APKs installed through the plugin survive a guest reset.
59
+ WebView read-out, remembered APKs and zero-config first run.
60
+
61
+ `webviewAction=eval` now returns real values, APKs installed through the plugin survive a guest
62
+ reset, and the plugin can provision its own JDK / Android SDK / system image / AVD on first use.
7
63
 
8
64
  ### Added
9
65
 
@@ -122,9 +178,13 @@ interactions, and a first-class zero-config provisioning chain.
122
178
  and per-candidate timeouts plus the known-good JDK table make it fail over instead.
123
179
  - macOS arm64 provisioning selected the x86_64 image; it now defaults to `arm64-v8a`.
124
180
 
125
- ## 0.12.0
181
+ ### Fixed
182
+
183
+ - `GET/POST /apk-vm/camera` accepted poster paths that did not exist; save/apply now reject
184
+ missing or unreadable `-virtualscene-poster` files with the offending poster name and path
185
+ instead of failing later on the next emulator launch.
126
186
 
127
- Zero-config first run: the plugin now provisions its own JDK, Android SDK, system image and AVD.
187
+ ### Zero-config first run
128
188
 
129
189
  ### Added
130
190
 
package/DEMO.md CHANGED
@@ -83,14 +83,17 @@ first `init` in about 1 s, `width`/`height` matching the current orientation.
83
83
  the 16-byte variant some AVD images emit (same header plus four extra bytes); the encoder
84
84
  detects the layout from the file size. A `--scale 0.5` produces a smaller mobile-friendly
85
85
  file; `--colors 128 --palette local` improves gradients at a slightly larger size.
86
- - `docs/screenshot-panel.png`: main panel with the Environment + APK cards and the phone frame
87
- (checked in).
88
- - `docs/screenshot-sidebar.png`: the plugin inside the right sidebar next to a session (checked in).
86
+ - `docs/screenshot-panel.png`: main panel with the Environment, APK files, ownership, Activity
87
+ and Rooted debug cards plus the phone frame (checked in).
88
+ - `docs/screenshot-activity.png`, `docs/screenshot-device.png`, `docs/screenshot-environment.png`,
89
+ `docs/screenshot-apk-files.png`, `docs/screenshot-debug.png`: close-ups of the cards and the
90
+ guest (checked in).
89
91
  - `docs/demo.gif`: the loop itself — home screen → sample APK installed and driven through the
90
92
  HTTP API → 60 fps animation in the guest (checked in; see the command above).
91
- - Optional extra captures that are **not** checked in: an expanded green Environment card, and
92
- the Rooted debug card with `ui_dump`/`perf`/record output. Re-capture them from your own host
93
- before publishing new ones; keep the same 720–1280 px / PNG style.
93
+ - Screenshots are captured from the 0.12.0 UI with demo data only; the Windows user name, real
94
+ APK names/paths and the assistant avatar are masked with Gaussian blur (Pillow) before
95
+ publishing. Re-capture them from your own host before publishing new ones; keep the same
96
+ 720–1280 px / PNG style.
94
97
 
95
98
  ## Acceptance checklist
96
99
 
package/README.md CHANGED
@@ -45,7 +45,7 @@ same-origin, loopback-only debug HTTP API and an `apk_vm` Agent tool.
45
45
  > 当前 **Windows x64 与 Linux x86_64(headless)为端到端已验证平台**;macOS 仅做探测/CI
46
46
  > 覆盖,详见 `docs/LINUX-E2E.md`。
47
47
 
48
- **Status:** `0.12.0` · Apache-2.0 · no npm runtime dependencies · no build step.
48
+ **Status:** `0.12.2` · Apache-2.0 · no npm runtime dependencies · no build step.
49
49
 
50
50
  This is an open-source DSH plugin published on npm as **`dsh-apk-vm`**. Repository:
51
51
  [github.com/yuxiaole-bili/dsh-apk-vm](https://github.com/yuxiaole-bili/dsh-apk-vm).
@@ -130,11 +130,14 @@ and Agent-facing UI automation for development workflows.
130
130
 
131
131
  ## Demo / visible proof
132
132
 
133
- Real screenshots from the reference host:
133
+ Real screenshots from the reference host (0.12.0 UI; the Windows user name, real APK names/paths
134
+ and the assistant avatar are Gaussian-blurred):
134
135
 
135
136
  ![APK VM main panel](docs/screenshot-panel.png)
136
137
 
137
- ![APK VM in the right sidebar](docs/screenshot-sidebar.png)
138
+ ![Agent and user activity journal](docs/screenshot-activity.png)
139
+
140
+ ![The sample APK running inside the Android guest](docs/screenshot-device.png)
138
141
 
139
142
  28-second capture of the loop: home screen → sample APK installed and driven by the API →
140
143
  60 fps animation in the guest (720×1280, 3.2 MiB):
@@ -143,8 +146,12 @@ Real screenshots from the reference host:
143
146
 
144
147
  | Asset | Status |
145
148
  | --- | --- |
146
- | `docs/screenshot-panel.png` | ✅ main panel: Environment, guest H.264, controls |
147
- | `docs/screenshot-sidebar.png` | ✅ right-sidebar layout next to a session |
149
+ | `docs/screenshot-panel.png` | ✅ main panel: Environment, APK files, ownership, Activity, rooted debug, guest H.264 |
150
+ | `docs/screenshot-activity.png` | ✅ Activity card: agent + user operations with screenshot thumbnails |
151
+ | `docs/screenshot-device.png` | ✅ guest running the sample APK on the H.264 canvas |
152
+ | `docs/screenshot-environment.png` | ✅ Environment self-check card |
153
+ | `docs/screenshot-apk-files.png` | ✅ APK files / remembered installs card |
154
+ | `docs/screenshot-debug.png` | ✅ Rooted debug toolbox card |
148
155
  | `docs/demo.gif` | ✅ 28 s loop (720×1280, 3.2 MiB); reproducible from the guest-side screencap loop in [DEMO.md](DEMO.md) |
149
156
 
150
157
  The [Performance](#performance) and [Verification](#verification) sections list exactly what was
@@ -254,6 +261,27 @@ key {"text":"HOME"} -> returned to launcher
254
261
  Environment card lists all adb devices (emulator, USB/physical, network) and can attach one at
255
262
  runtime. Detach restores the managed AVD identity. Live state, serial, boot mode/time, and a
256
263
  bounded diagnostic log are shown.
264
+ - **Remote VM hosts over SSH (multiple concurrent sessions, 远端虚拟机).** Any SSH-reachable
265
+ macOS/Linux/Windows box can back one or more VM sessions: the plugin keeps validated profiles
266
+ under `<profile>/.apk-vm/remote-profiles.json` (host/user/ports/AVD, never the key contents),
267
+ forwards a loopback port to the remote emulator's adb port, runs `adb connect` and attaches the
268
+ device, so the same panel/H.264/input/debug surface drives the remote guest. Up to
269
+ `remoteMaxSessions` sessions can run at once, each with its own AVD; `launch: true` starts a
270
+ fixed headless emulator on the remote host over the same SSH connection and `disconnect` stops
271
+ it again. The panel lists saved profiles and live sessions with per-session connect/disconnect.
272
+ See [Multiple instances, physical devices and snapshots](#multiple-instances-physical-devices-and-snapshots).
273
+ - **Available emulator inventory.** `GET /apk-vm/emulators` returns one merged table of local AVDs
274
+ (name, target, ABI, RAM, LCD, snapshot count, running state, size) plus the AVDs and adb devices
275
+ of every saved remote host, so you can see what can be started before spawning anything.
276
+ - **Virtual camera.** Configure the guest camera (`-camera-back` / `-camera-front`: `emulated`,
277
+ `virtualscene`, `webcam`, `none`) and feed the virtual scene with PNG/JPEG posters
278
+ (`-virtualscene-poster`). The panel's Media card manages the modes and poster list; settings
279
+ apply to newly spawned instances and to the default VM after a restart.
280
+ - **Virtual microphone.** Microphone modes: `off`, `host` (pass a host input device through to the
281
+ guest; Windows/Linux/macOS) and `file` (loop an audio file into a virtual PulseAudio source;
282
+ Linux hosts and remote SSH hosts). Configure it in the panel Media card, through
283
+ `/apk-vm/mic`, or with `cfg.mic`; remote sessions upload posters/audio to
284
+ `/tmp/apk-vm-media/<id>` over the same SSH connection.
257
285
  - **APK discovery + one-click install.** Recursively finds `*.apk` under the configured roots,
258
286
  reads package name / label / launcher activity with `aapt2 dump badging`, then runs
259
287
  `adb install -r` and launches the app with `am start`.
@@ -444,9 +472,19 @@ or `project`), session id, workspace, and `since` / `lastSeenAt` timestamps; lea
444
472
  idle-stopped after `instanceIdleMs`; the AVD is kept for quick reuse.
445
473
  - **Physical / network devices.** `GET /apk-vm/devices` lists adb devices;
446
474
  `POST /apk-vm/device {"serial":"…"}` attaches an online USB/physical/network device and
447
- detaches back to the managed AVD with `{"serial":""}`. `GET/POST /apk-vm/remote` manages an
448
- SSH adb tunnel (`allowRemote` / `remote` config; never a shell). The Environment card offers
449
- the same attach/detach actions.
475
+ detaches back to the managed AVD with `{"serial":""}`. The Environment card offers the same
476
+ attach/detach actions.
477
+ - **Remote VM host (SSH proxy).** `GET/POST /apk-vm/remote` runs the guest behind an SSH host:
478
+ an `ssh -N -L` loopback tunnel forwards the remote emulator's adb port, `adb connect
479
+ 127.0.0.1:<localPort>` registers it and the normal attach/boot-wait path runs, so the panel
480
+ streams the remote guest over the same H.264 channel. `POST {"action":"connect","host","user",
481
+ "keyPath"?,"remotePort":5558,"avdName"?,"launch":true}` optionally starts a **fixed headless
482
+ emulator** on the remote host (`-no-window -no-audio -no-boot-anim -gpu
483
+ swiftshader_indirect`) over the same SSH connection; `{"action":"disconnect",
484
+ "stopEmulator":true}` also kills an emulator the plugin launched. The validated profile has no
485
+ secrets (the SSH key path stays on this host) and is persisted under
486
+ `<profile>/.apk-vm/remote-profile.json`, so the panel card prefills after a restart. Only the
487
+ fixed command shape is executed; every value is validated and single-quote escaped.
450
488
  - **Named AVD snapshots.** `GET /apk-vm/snapshots` lists snapshots;
451
489
  `POST /apk-vm/snapshots {"action":"save|load|delete","name":"…"}` manages them. The quick-boot
452
490
  snapshot (`snapshotName`, default `default_boot`) is handled automatically. The panel's
@@ -741,6 +779,9 @@ All keys are optional; defaults are shown in the **Default** column.
741
779
  | `prewarmDelayMs` | `3000` | Delay before the prewarm start. |
742
780
  | `autoStart` | `true` | Start the VM on the first `/apk-vm/state` or `/apk-vm/frame` request. |
743
781
  | `autoReinstall` | `true` | Remember APKs installed through the plugin and reinstall missing ones on the next boot (registry in `<profile>/.apk-vm/installed-apps.json`, archived APKs in `<profile>/.apk-vm/apks`). Set `false` to opt out. |
782
+ | `remoteMaxSessions` | `4` | Maximum concurrent remote SSH VM sessions (1–16). |
783
+ | `camera` | `{ back: "emulated", front: "none", posters: [] }` | Guest camera modes and virtual-scene poster list (`posters` entries: `{name, path}`). |
784
+ | `mic` | `{ mode: "off" }` | Guest microphone: `off` / `host` (host input passthrough) / `file` (loop an audio file into a virtual source; Linux and remote hosts). Optional `backend`, `filePath`. |
744
785
  | `multiInstance` | `true` | Allow isolated extra VMs for concurrent Agents. |
745
786
  | `maxInstances` | `3` | Maximum number of extra instances (in addition to the default VM). Each running instance costs guest RAM/CPU. |
746
787
  | `instanceIdleMs` | `900000` | Stop an extra instance after this long without panel frames, a video client, or an Agent command (AVD is kept). |
@@ -862,7 +903,10 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
862
903
  | GET/HEAD | `/apk-vm/apk-icon?path=…` | Extract the raster launcher icon from the APK ZIP (PNG/WebP/JPEG). |
863
904
  | GET | `/apk-vm/devices` | List adb devices (`serial`, `state`, `kind`, `model`, `product`, transport) plus current/managed-device metadata. |
864
905
  | POST | `/apk-vm/device` | `{"serial":"<adb-serial>"}` attach an online physical/network device; `{"serial":""}` detach and restore the managed AVD. |
865
- | GET/POST | `/apk-vm/remote` | SSH adb tunnel: `POST {"action":"connect","host","user","keyPath"?,"remotePort":5558}` or `{"action":"disconnect"}`; `GET` returns tunnel status. |
906
+ | GET/POST | `/apk-vm/remote` | Multi-session SSH-proxied VMs: `POST {"action":"connect","profile":{host,user,keyPath?,sshPort?,remotePort?,avdName?,launch?},"connectTimeoutMs"?}`, `{"action":"disconnect","id"?,"stopEmulator"?,"detachDevice"?}`, `{"action":"remove-session","id"?}`, `{"action":"status"}`, `{"action":"save-profile"}`, `{"action":"forget-profile","id"?}`; `GET` returns `{sessions,profiles,counts,…}`. |
907
+ | GET | `/apk-vm/emulators` | Merged local + remote emulator inventory (`local`, `remotes[]`, `updatedAt`). |
908
+ | GET/POST | `/apk-vm/camera` | Virtual camera settings: `POST {"action":"save"|"apply","camera":{back,front,posters[]},"restart"?}`. |
909
+ | GET/POST | `/apk-vm/mic` | Virtual microphone settings: `POST {"action":"save"|"apply","mic":{mode,backend,filePath},"restart"?}`. |
866
910
  | POST | `/apk-vm/vm` | `{"action":"start"\|"stop"\|"restart"\|"snapshot"}`. |
867
911
  | POST | `/apk-vm/install` | `{"path":"C:/path/app.apk"}` → install + launch. |
868
912
  | POST | `/apk-vm/upload` | Raw APK/APKS/XAPK/AAB bytes (≤ 500 MiB) with the file name in the `x-apk-name` header → validate ZIP/APK magic, write to the OS temp dir, install + launch. |
@@ -1355,11 +1399,16 @@ not a public issue.
1355
1399
  The features below are **not shipped yet** — they are tracked for future releases. Everything
1356
1400
  described above is implemented in this release.
1357
1401
 
1358
- - **Physical-device attach is available but not exhaustively verified.** `/apk-vm/devices` +
1359
- `/apk-vm/device` and the SSH adb tunnel are shipped; per-device quirks (OEM adb authorization,
1360
- screen size/orientation, root availability) still need a device-specific smoke test.
1402
+ - **Physical-device attach and the remote VM proxy are shipped but not exhaustively verified.**
1403
+ `/apk-vm/devices` + `/apk-vm/device` and the SSH-proxied `/apk-vm/remote` path (loopback
1404
+ tunnel, `adb connect`, attach/boot-wait, optional fixed headless emulator launch) are
1405
+ implemented and covered hermetically by `spike/remote-test.mjs`; per-device/per-host quirks
1406
+ (OEM adb authorization, screen size/orientation, root availability, a host without an
1407
+ emulator binary) still need an environment-specific smoke test.
1361
1408
  - **Audio streaming** — forward guest audio alongside the video stream.
1362
- - **Cloud / remote VM execution** — run the guest on a remote host and stream it to the panel.
1409
+ - **Cloud runners** — a managed cloud VM service. The SSH-proxied remote host path is already
1410
+ available (see [Multiple instances, physical devices and snapshots](#multiple-instances-physical-devices-and-snapshots)),
1411
+ but it expects an Android SDK/emulator on a host you control rather than provisioning one.
1363
1412
 
1364
1413
  QEMU + Android-x86 for hosts without hardware virtualization and `-writable-system` image
1365
1414
  customization remain research notes in [DESIGN.md](DESIGN.md) §8.
@@ -1367,6 +1416,15 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
1367
1416
  ---
1368
1417
 
1369
1418
  ## Known limitations
1419
+ - **Remote multi-session needs distinct AVDs.** Android refuses to run a second emulator on the
1420
+ same AVD unless every instance was started with `-read-only`; the plugin therefore expects a
1421
+ separate AVD per remote session (clone the AVD on the remote host if needed).
1422
+ - **The virtual camera is not a file-to-camera bridge.** Supported inputs are the emulator's
1423
+ built-in virtual scene (with PNG/JPEG posters) and host webcams; arbitrary video files are not
1424
+ injected as camera frames.
1425
+ - **The virtual microphone `file` mode needs a Linux/PulseAudio host.** On Windows only `host`
1426
+ passthrough is available, and camera/mic changes apply to a running default VM only after it is
1427
+ restarted.
1370
1428
 
1371
1429
  - **Windows x64 and Linux x86_64 are the end-to-end verified platforms.** macOS SDK/adb/
1372
1430
  emulator/AVD discovery is implemented and `arm64` hosts automatically select the
package/SECURITY.md CHANGED
@@ -109,8 +109,25 @@ they demonstrate a way to exceed the stated boundaries.
109
109
  `sdkmanager`.
110
110
  9. **The plugin does not send telemetry** or contact third-party services on its own; it talks
111
111
  to the local adb/emulator and the same-origin DSH Web server. Network activity is limited to
112
- the `autoSetup` provisioning described above and the user's own `sdkmanager`; no analytics,
113
- identifiers or usage data are collected.
112
+ the `autoSetup` provisioning described above, the user's own `sdkmanager`, and an SSH
113
+ connection to a host the user explicitly configures for a remote VM; no analytics, identifiers
114
+ or usage data are collected.
115
+ 10. **The remote VM proxy runs fixed commands on a user-configured SSH host.** When you connect a
116
+ remote VM (`POST /apk-vm/remote`), the plugin starts the local `ssh` client with
117
+ `BatchMode=yes` (a password prompt fails instead of hanging) and forwards a loopback port to
118
+ the remote emulator's adb port. With `launch: true` it additionally runs one fixed
119
+ `emulator -avd … -no-window …` command on that host over the same connection; every value is
120
+ validated and single-quote escaped, so profile fields cannot inject shell commands. The SSH
121
+ key path is only passed to the local `ssh` process; `<profile>/.apk-vm/remote-profile.json`
122
+ stores host/user/port/AVD and no key material. The remote host is trusted infrastructure —
123
+ the plugin does not harden it, and the rooted adb device exposed there has the same trust
124
+ level as a local AVD.
125
+
126
+ 11. **Virtual camera/microphone media are uploaded to the configured remote host.** When a
127
+ remote session uses a poster or audio file, the plugin copies that file over the existing
128
+ SSH connection (stdin write with quoted, validated fixed paths under `/tmp/apk-vm-media`).
129
+ The file is audio/image content only and no shell string is constructed from user input;
130
+ local media settings are stored in `<profile>/.apk-vm/media.json`.
114
131
 
115
132
  ## Hardening status
116
133