dsh-apk-vm 0.11.1 → 0.12.1

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,5 +1,222 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.1
4
+
5
+ ### Added
6
+
7
+ - **Remote VM multi-session.** Remote hosts are now first-class VM sources: profiles live in
8
+ `<profile>/.apk-vm/remote-profiles.json` (validated, no key contents), `RemoteSessionManager`
9
+ can run several sessions concurrently (`remoteMaxSessions`, default 4), each with its own AVD,
10
+ adb tunnel, H.264 stream and instance id. New helpers: `RemoteProfileBook`,
11
+ `RemoteSessionManager`, `normalizeExtraEmulatorArgs`, `parseRemoteListeningPorts`;
12
+ `lib/remote-instance.js` implements the remote instance surface. Remote `disconnect` now kills
13
+ the remote emulator through `<sdkRoot>/platform-tools/adb` (fixed: non-interactive SSH PATH
14
+ often has no adb). Covered by `spike/remote-test.mjs` (45 checks) and
15
+ `spike/remote-instance-test.mjs` (23 checks).
16
+ - **Emulator inventory.** `GET /apk-vm/emulators` merges local AVD/device state with every saved
17
+ remote host (`lib/emulator-inventory.js`, one SSH round trip per host) plus the panel
18
+ "Available emulators" card.
19
+ - **Virtual camera.** Camera back/front modes and `-virtualscene-poster` posters, managed by
20
+ `GET/POST /apk-vm/camera`, the panel Media card, or `cfg.camera` (`lib/media.js`).
21
+ - **Virtual microphone.** Mic modes `off` / `host` / `file`; file mode loops audio into a
22
+ virtual PulseAudio source (null-sink + remap-source) and is available on Linux and remote
23
+ hosts; managed by `GET/POST /apk-vm/mic`, the panel Media card, or `cfg.mic`.
24
+ - **Remote VM host over SSH (远端虚拟机).** `/apk-vm/remote` now turns an SSH-reachable host
25
+ into the VM proxy instead of only opening a bare tunnel: it forwards a loopback port to the
26
+ remote emulator's adb port, runs `adb connect` and attaches the device to the normal
27
+ boot-wait/H.264/input/debug path. `launch: true` starts a fixed headless emulator
28
+ (`-no-window -no-audio -no-boot-anim -gpu swiftshader_indirect`) on the remote host over the
29
+ same connection, and `disconnect` can stop it again. The validated profile (host/user/ports/
30
+ AVD; no key material) is persisted under `<profile>/.apk-vm/remote-profile.json`, the panel
31
+ card prefills from it and polls the tunnel/launch state every two seconds. New helpers in
32
+ `lib/remote.js` and a rewritten `spike/remote-test.mjs` (27 checks: validation/injection
33
+ safety, fixed command builders, profile store, bounded `runSshCommand`, route round-trip).
34
+
35
+ ### Changed
36
+
37
+ - New plugin icon (`icon.svg`, 36×36): layered screens in lemon/grass-green and violet, replacing
38
+ the thin `currentColor` glyph that rendered nearly invisible on dark tiles.
39
+ - Refreshed the demo screenshots from the 0.12.0 panel UI (main panel, Activity card, guest,
40
+ Environment, APK files and Rooted debug cards). Private host details — the Windows user name,
41
+ real APK names/paths and the assistant avatar — are masked with Gaussian blur.
42
+
43
+ ### Removed
44
+
45
+ - `docs/screenshot-sidebar.png`: replaced by the refreshed panel and card screenshots.
46
+
47
+ ## 0.12.0
48
+
49
+ WebView read-out, remembered APKs and zero-config first run.
50
+
51
+ `webviewAction=eval` now returns real values, APKs installed through the plugin survive a guest
52
+ reset, and the plugin can provision its own JDK / Android SDK / system image / AVD on first use.
53
+
54
+ ### Added
55
+
56
+ - **JSON-safe `webviewAction=eval`.** The CDP evaluation path now returns `result.value` for
57
+ ordinary JSON values and, for objects that do not survive JSON by value (`DOMRect`,
58
+ `MediaQueryList`, class instances), a JSON-safe property snapshot built from own properties and
59
+ prototype getters. A compact preview of the value is appended to the tool summary, so reading
60
+ `getBoundingClientRect().width` or `matchMedia("(pointer: coarse)").matches` no longer needs a
61
+ screenshot. Statement blocks fall back to plain CDP evaluation (no property snapshot; the
62
+ result is whatever the runtime returns, often `null`). New helpers
63
+ `isSingleJsExpression`, `jsonSafeEvaluateExpression`, `previewJsValue` and
64
+ `CdpSession.evaluateJson`; covered by five new cases in `spike/cdp-test.mjs` (17 total).
65
+ - **Remembered APKs / auto-reinstall.** Installs through the tool or the panel are recorded in
66
+ `<profile>/.apk-vm/installed-apps.json`; uploaded APKs are archived under
67
+ `<profile>/.apk-vm/apks` (newest 10). When the guest no longer has a remembered package (after a
68
+ quick-boot snapshot reset, an AVD recreation or a plugin/emulator upgrade), the plugin
69
+ re-installs it on the next boot and journals the pass as a `source: system` activity entry.
70
+ Config: `autoReinstall` (default `true`). New `lib/installed-apps.js` and
71
+ `spike/installed-apps-test.mjs` (9 hermetic checks).
72
+
73
+ ### Changed
74
+
75
+ - `webviewAction=eval` now accepts a single expression and reports the value; the old
76
+ statement-style fallback is unchanged.
77
+ - Multi-instance installs (HTTP and tool) also remember the APK under that instance id.
78
+
79
+ ### Fixed
80
+
81
+ - `webviewAction=eval` returned `null` for `DOMRect`/`MediaQueryList` and other non-by-value
82
+ values; it now returns a readable snapshot.
83
+
84
+ ## 1.0.0
85
+
86
+ Observability and reliability release: a local Agent activity journal, hardened device
87
+ interactions, and a first-class zero-config provisioning chain.
88
+
89
+ ### Added
90
+
91
+ - **Agent activity log.** Every `apk_vm` tool call and every mutating panel/HTTP request is
92
+ journaled locally as JSONL under `<profile>/.apk-vm/activity` (override with `activityDir`);
93
+ entries carry `source: tool|http` and a screenshot is attached to mutating actions. New
94
+ `GET /apk-vm/activity` (list + stats, filterable by source / action / instance / result),
95
+ `GET /apk-vm/activity/<id>`, `GET /apk-vm/activity/<id>/shot` and
96
+ `POST /apk-vm/activity/clear`. The sidebar gains an **Activity** timeline card with
97
+ filters, lazy thumbnails, a full-image overlay and confirm-to-clear. Journal and screenshots
98
+ stay on this host; nothing is uploaded (typed text is stored as a character count, not its
99
+ content). New `lib/activity-log.js` (ring-pruned at 1000 entries / 250 MB by default).
100
+ - **Device resilience and recovery** in `lib/android.js`: bounded-budget `screenshot()` with
101
+ health probes and structured error codes (`EDEVICE_UNRESPONSIVE`, `ESYSTEM_SERVER_DEAD`,
102
+ `ESURFACEFLINGER_DEAD`, `ESCREENSHOT_TIMEOUT`, …) plus opt-in one-shot reconnect/reboot
103
+ recovery; `uiDump()` WebView text salvage (`/dev/tty`, `--compressed`, `adb pull`, synthetic
104
+ text nodes); root execution helpers (`shell(…, { forceRoot: true })` with `su` fallback,
105
+ `readRootFile` / `writeRootFile` / `readAppDataFile` / `writeAppDataFile` /
106
+ `writeSharedPrefs`); opt-in tap verification (before/after frame hash + jitter retry);
107
+ clipboard-paste fallback for non-ASCII `text`; automatic guest default-route repair after an
108
+ `isolated → shared` switch or an env restore; `probeHealth()` / `recoverDevice()` watchdog/ANR
109
+ classification; opt-in appops preservation across `installApk()`.
110
+ - **Provisioning hardening** in `lib/jdk.js` / `lib/autosetup.js`: bundled known-good Temurin
111
+ `17.0.21+9` checksum table (including macOS arm64) used when the Adoptium API is unreachable;
112
+ resumable downloads with verified-archive reuse and HTTP `Range`; download-candidate probes and
113
+ per-candidate timeouts (a blocked GitHub host can no longer stall the chain); 3 GB free-disk
114
+ precheck; cross-process `<jdkRoot>/.lock` guard; `jdkVersion` pin; live download progress
115
+ (`detail.progress`) in the panel; host-arch default system image (`arm64-v8a` on arm64 hosts).
116
+ - `examples/agent-workflow.mjs` — a six-step, copy-pasteable Agent workflow (state → install →
117
+ UI tree → tap → assert → screenshot → activity timeline → device identity).
118
+ - `scripts/make-demo-gif.mjs` — dependency-free GIF89a encoder for guest screencap frames, plus
119
+ `docs/demo.gif` (28 s: home → sample APK installed and driven through the HTTP API → 60 fps
120
+ animation). `docs/DEMO.md` documents how to reproduce it.
121
+ - WebView control docs and examples now point at `webview`/`tap_css`/`tap_selector`
122
+ as the preferred path for DOM content.
123
+
124
+ ### Changed
125
+
126
+ - `sdkmanager` installs (`installSystemImage`, `installSdkPackages`) always pass
127
+ `--sdk_root=<sdkRoot>`, so a `sdkmanager` found elsewhere on `PATH` cannot install into the
128
+ wrong SDK. `bootstrapSdk` already did this.
129
+ - The Environment report includes `javaHome` / `javaPresent`, the auto-setup state and the
130
+ activity routes; the panel adds a Java row, auto-setup progress percent/bytes, and the Agent
131
+ activity card. Hypervisor hints are host-architecture neutral.
132
+ - README/docs are now 1.0.0: new sections for the activity log and for multiple instances,
133
+ physical devices and snapshots; expanded troubleshooting for the fixes above; macOS/arm64
134
+ image selection documented; demo media checked in.
135
+
136
+ ### Fixed
137
+
138
+ - `adb` tool action failed with `Cannot access 'api' before initialization` on every call — the
139
+ tool API is now resolved lazily per action.
140
+ - Auto-start after first-use provisioning now uses a dedicated one-shot kick, so a partially
141
+ configured host that attempted a start before provisioning finished still boots once the
142
+ environment reports `ok`.
143
+ - `storage` tool action failed with `storageSdkRoot is not defined` — the helper is hoisted into
144
+ the `apply()` scope shared by the route and the tool.
145
+ - Tool failures now return JSON-safe `{ ok: false, summary, result }` errors instead of throwing
146
+ non-round-trippable exceptions.
147
+ - `push` reported a misleading "local file not found under an allowed root" for files that exist
148
+ but sit outside the configured roots, or for paths on case-insensitive filesystems. Paths are
149
+ realpath-canonicalized, and "outside the allowed roots" (with the resolved roots and a `roots`
150
+ config hint) is now distinct from "file not found".
151
+ - Screenshots could block for the full 180 s budget when the guest `SurfaceFlinger` /
152
+ `system_server` had wedged, with no hint or recovery path. They now fail fast with a
153
+ structured, actionable device error and an opt-in recovery hook.
154
+ - `ui_dump` / `inspect_ui` returned almost no text for WebView-hosted content on some images;
155
+ the dump is now supplemented from guest-side `uiautomator dump`/`adb pull` text nodes.
156
+ - `shell` ran as the unprivileged `shell` user even when the VM reported `root: true`; root
157
+ helpers now make `su` usage explicit (app-data writes still need the app's SELinux category,
158
+ which is documented).
159
+ - Taps on WebView buttons could be silently lost; callers can opt into verification (frame hash
160
+ diff + ±1 px retry). Non-ASCII `type_text` that reached the IME but not a WebView field falls
161
+ back to clipboard paste.
162
+ - After switching an isolated VM to shared networking (or restoring a snapshot created in shared
163
+ mode) the guest could be left without a default route and apps reported `ENETUNREACH`; the
164
+ default route is now repaired in the background.
165
+ - Reinstalling an APK could reset the "install unknown apps" appops flag; `installApk()` can now
166
+ snapshot and restore allowed appops (opt-in).
167
+ - `autoSetup` could hang for the full download budget on a blocked GitHub host; candidate probes
168
+ and per-candidate timeouts plus the known-good JDK table make it fail over instead.
169
+ - macOS arm64 provisioning selected the x86_64 image; it now defaults to `arm64-v8a`.
170
+
171
+ ### Fixed
172
+
173
+ - `GET/POST /apk-vm/camera` accepted poster paths that did not exist; save/apply now reject
174
+ missing or unreadable `-virtualscene-poster` files with the offending poster name and path
175
+ instead of failing later on the next emulator launch.
176
+
177
+ ### Zero-config first run
178
+
179
+ ### Added
180
+
181
+ - **Automatic environment provisioning (`autoSetup`, default `true`).** The first
182
+ `GET /apk-vm/state` or `GET /apk-vm/setup` request — opening the panel, or an Agent's first
183
+ `apk_vm` call — starts a background chain when the environment is incomplete: download a
184
+ portable **Temurin JDK 17** from Adoptium (SHA-256-verified), bootstrap the Android SDK
185
+ command-line tools and accept licenses, install `platform-tools`/`emulator`/`build-tools`/
186
+ `platforms`, install the configured system image, and create the AVD. The existing
187
+ `autoStart` flow then boots the VM. A cold machine downloads roughly 2.5 GB; set
188
+ `autoSetup: false` to keep setup manual.
189
+ - New `lib/jdk.js`: `findManagedJdk()` / `ensureJdk()` — Temurin 17 download with checksum
190
+ verification, retry-friendly archive reuse, cross-platform extraction, and a managed JDK root
191
+ (`~/.dsh/apk-vm/jdk`, override with `jdkRoot`).
192
+ - JDK download mirror fallback: when the GitHub-hosted Adoptium asset is unreachable (common on
193
+ mainland-China networks), the archive is fetched from the built-in Tsinghua mirror — or the
194
+ `jdkMirror` config / `DSH_APK_VM_JDK_MIRROR` env override — and still verified against
195
+ Adoptium's published SHA-256 checksum.
196
+ - New `lib/autosetup.js`: single-flight orchestrator with per-step progress, cancel and retry;
197
+ exposed as `autoSetup` on `GET /apk-vm/setup`, `POST /apk-vm/setup`
198
+ (`action: auto-setup` / `cancel-auto-setup`), `/apk-vm/state` and the `apk_vm` `info` result.
199
+ - `GET /apk-vm/setup` now reports `javaHome` / `javaPresent`; the Environment card shows a Java
200
+ row plus live auto-setup progress with cancel/retry.
201
+
202
+ ### Changed
203
+
204
+ - `findJavaHome()` also looks in the plugin-managed JDK directory and `extraJavaHomes`, so
205
+ `sdkmanager`/`avdmanager` work without a system-wide JDK or `JAVA_HOME`.
206
+ - When provisioning finishes, the VM and the instance manager adopt the freshly detected SDK,
207
+ emulator and AVD paths (without overriding explicit config), then boot once through the normal
208
+ `autoStart` flow — a cold install goes from zero to a running VM without extra clicks.
209
+ - First-run documentation is now install → open the panel → automatic provisioning → VM start.
210
+
211
+ ### Fixed
212
+
213
+ - The Environment card could stay empty on exactly the machines that needed setup: a
214
+ `GET /apk-vm/setup` payload with `ok: false` was treated as a failed request. It now renders
215
+ the report and exposes the manual and automatic setup actions from there.
216
+ - The privacy scanner also matches non-ASCII workspace paths written with `/` (not only `\`),
217
+ gained an `--untracked` mode for scanning uncommitted files, and two host-specific example
218
+ paths in comments plus a test fixture were made host-neutral.
219
+
3
220
  ## 0.11.1
4
221
 
5
222
  Clipboard/text tools no longer need a panel to already have a control stream; network proxy has an alias.
package/DEMO.md CHANGED
@@ -1,9 +1,9 @@
1
1
  # Demo & verification script
2
2
 
3
3
  This file is the reproducible demo script behind `docs/demo.gif` and the screenshots referenced
4
- in [README.md](README.md). No media is checked in yet; the commands below produce the real
5
- artifacts on a Windows reference host (AEHD + AOSP Android 14). Do not invent numbers — copy them
6
- from the outputs.
4
+ in [README.md](README.md). `docs/demo.gif` is checked in (720×1280, 28 s, 3.2 MiB); the commands
5
+ below re-produce it and the screenshots on a Windows reference host (AEHD + AOSP Android 14).
6
+ Do not invent numbers — copy them from the outputs.
7
7
 
8
8
  ## Install (local link)
9
9
 
@@ -19,15 +19,21 @@ Refresh the DSH page after installing the client half.
19
19
  ## 30-second demo flow
20
20
 
21
21
  1. Open **APK Virtual Machine** in the sidebar.
22
- 2. Expand **Environment** — show SDK/adb/emulator/system image/AVD/acceleration all green.
23
- The "Create AVD" action is offered when the image exists but the AVD does not.
22
+ 2. Expand **Environment** — on a cold host the card shows **Setup needed** and the `autoSetup`
23
+ chain starts automatically (Temurin JDK → SDK command-line tools → packages → system image →
24
+ AVD, roughly 2.5 GB on the first run). On a provisioned host it shows SDK/adb/emulator/system
25
+ image/AVD/acceleration all green.
24
26
  3. Press **Start VM** (or just open the panel with `autoStart` on). Show the measured boot label
25
27
  (`quick N s` / `cold N s`).
26
28
  4. **Upload APK** or drag a file onto the panel. The app installs and launches; the phone frame
27
29
  switches to the H.264 canvas.
28
30
  5. Expand **Rooted debug**: run `id -u; getprop ro.build.version.release`; click **UI tree**,
29
31
  **Perf**, **Record 5s**, **Rotate**, **Screenshot**.
30
- 6. Interact with the phone frame, then note the live `FPS` reading in the header. A static home
32
+ 6. Drive the VM through the HTTP API or the `apk_vm` tool (see
33
+ [examples/agent-workflow.mjs](examples/agent-workflow.mjs)), then open the sidebar
34
+ **Agent activity** card: it shows the tool-call timeline (action, ok/error, duration,
35
+ instance, screenshot thumbnails) recorded by the plugin.
36
+ 7. Interact with the phone frame, then note the live `FPS` reading in the header. A static home
31
37
  screen has a low frame rate because scrcpy only emits frames on change; use an animated app or
32
38
  a scroll gesture for the 60 fps path.
33
39
 
@@ -62,18 +68,43 @@ first `init` in about 1 s, `width`/`height` matching the current orientation.
62
68
 
63
69
  ## Recording the media
64
70
 
65
- - `docs/demo.gif`: record the flow above at ~1280 px width; trim to 20–30 s; keep file < 8 MiB.
66
- - `docs/screenshot-panel.png`: main panel with the Environment + APK cards and the phone frame.
67
- - `docs/screenshot-setup.png`: expanded Environment card on a green host.
68
- - `docs/screenshot-debug.png`: expanded Rooted debug card with `ui_dump` / `perf` / record output.
71
+ - `docs/demo.gif` — 28 s, 720×1280, 3.2 MiB (checked in). Captured from the guest, not the host
72
+ UI: start a guest-side `screencap` loop (raw frames land under `/data/local/tmp`), drive the
73
+ storyboard (home screen → sample APK install/launch → tap → 60 fps animation), pull the frames,
74
+ then assemble them with the repository's dependency-free encoder:
75
+
76
+ ```powershell
77
+ # 100 raw frames captured on the guest into C:\apk-vm-frames\ (raw screencap dumps)
78
+ node scripts/make-demo-gif.mjs --in C:\apk-vm-frames --out docs/demo.gif `
79
+ --scale 1 --fps 3.6 --colors 96 --palette global
80
+ ```
81
+
82
+ Raw dumps are either the classic 12-byte header (`width`, `height`, `format`, then RGBA) or
83
+ the 16-byte variant some AVD images emit (same header plus four extra bytes); the encoder
84
+ detects the layout from the file size. A `--scale 0.5` produces a smaller mobile-friendly
85
+ file; `--colors 128 --palette local` improves gradients at a slightly larger size.
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).
91
+ - `docs/demo.gif`: the loop itself — home screen → sample APK installed and driven through the
92
+ HTTP API → 60 fps animation in the guest (checked in; see the command above).
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.
69
97
 
70
98
  ## Acceptance checklist
71
99
 
72
100
  - [ ] Environment card reports Ready on a host with SDK + image + AVD + acceleration.
101
+ - [ ] On a cold host the `autoSetup` chain runs to Ready and the VM starts without manual steps.
73
102
  - [ ] Upload and drag-drop both install and launch an APK.
74
103
  - [ ] Phone frame uses `<canvas>` (H.264) when WebCodecs is available; PNG fallback otherwise.
75
104
  - [ ] Header FPS changes when the guest screen animates.
76
105
  - [ ] Rooted debug shell returns `uid=0(root)`; rotate/ui_dump/perf/record/screenshot work.
106
+ - [ ] The **Agent activity** card lists the `apk_vm` calls from the examples/tool run, with
107
+ screenshots for mutating actions.
77
108
  - [ ] Cross-origin request to `/apk-vm/*` is rejected (`403`).
78
109
  - [ ] Quick boot measured under 30 s after the snapshot exists.
79
110