dsh-apk-vm 0.11.0 → 0.12.0

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,185 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.0
4
+
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.
7
+
8
+ ### Added
9
+
10
+ - **JSON-safe `webviewAction=eval`.** The CDP evaluation path now returns `result.value` for
11
+ ordinary JSON values and, for objects that do not survive JSON by value (`DOMRect`,
12
+ `MediaQueryList`, class instances), a JSON-safe property snapshot built from own properties and
13
+ prototype getters. A compact preview of the value is appended to the tool summary, so reading
14
+ `getBoundingClientRect().width` or `matchMedia("(pointer: coarse)").matches` no longer needs a
15
+ screenshot. Statement blocks fall back to plain CDP evaluation (no property snapshot; the
16
+ result is whatever the runtime returns, often `null`). New helpers
17
+ `isSingleJsExpression`, `jsonSafeEvaluateExpression`, `previewJsValue` and
18
+ `CdpSession.evaluateJson`; covered by five new cases in `spike/cdp-test.mjs` (17 total).
19
+ - **Remembered APKs / auto-reinstall.** Installs through the tool or the panel are recorded in
20
+ `<profile>/.apk-vm/installed-apps.json`; uploaded APKs are archived under
21
+ `<profile>/.apk-vm/apks` (newest 10). When the guest no longer has a remembered package (after a
22
+ quick-boot snapshot reset, an AVD recreation or a plugin/emulator upgrade), the plugin
23
+ re-installs it on the next boot and journals the pass as a `source: system` activity entry.
24
+ Config: `autoReinstall` (default `true`). New `lib/installed-apps.js` and
25
+ `spike/installed-apps-test.mjs` (9 hermetic checks).
26
+
27
+ ### Changed
28
+
29
+ - `webviewAction=eval` now accepts a single expression and reports the value; the old
30
+ statement-style fallback is unchanged.
31
+ - Multi-instance installs (HTTP and tool) also remember the APK under that instance id.
32
+
33
+ ### Fixed
34
+
35
+ - `webviewAction=eval` returned `null` for `DOMRect`/`MediaQueryList` and other non-by-value
36
+ values; it now returns a readable snapshot.
37
+
38
+ ## 1.0.0
39
+
40
+ Observability and reliability release: a local Agent activity journal, hardened device
41
+ interactions, and a first-class zero-config provisioning chain.
42
+
43
+ ### Added
44
+
45
+ - **Agent activity log.** Every `apk_vm` tool call and every mutating panel/HTTP request is
46
+ journaled locally as JSONL under `<profile>/.apk-vm/activity` (override with `activityDir`);
47
+ entries carry `source: tool|http` and a screenshot is attached to mutating actions. New
48
+ `GET /apk-vm/activity` (list + stats, filterable by source / action / instance / result),
49
+ `GET /apk-vm/activity/<id>`, `GET /apk-vm/activity/<id>/shot` and
50
+ `POST /apk-vm/activity/clear`. The sidebar gains an **Activity** timeline card with
51
+ filters, lazy thumbnails, a full-image overlay and confirm-to-clear. Journal and screenshots
52
+ stay on this host; nothing is uploaded (typed text is stored as a character count, not its
53
+ content). New `lib/activity-log.js` (ring-pruned at 1000 entries / 250 MB by default).
54
+ - **Device resilience and recovery** in `lib/android.js`: bounded-budget `screenshot()` with
55
+ health probes and structured error codes (`EDEVICE_UNRESPONSIVE`, `ESYSTEM_SERVER_DEAD`,
56
+ `ESURFACEFLINGER_DEAD`, `ESCREENSHOT_TIMEOUT`, …) plus opt-in one-shot reconnect/reboot
57
+ recovery; `uiDump()` WebView text salvage (`/dev/tty`, `--compressed`, `adb pull`, synthetic
58
+ text nodes); root execution helpers (`shell(…, { forceRoot: true })` with `su` fallback,
59
+ `readRootFile` / `writeRootFile` / `readAppDataFile` / `writeAppDataFile` /
60
+ `writeSharedPrefs`); opt-in tap verification (before/after frame hash + jitter retry);
61
+ clipboard-paste fallback for non-ASCII `text`; automatic guest default-route repair after an
62
+ `isolated → shared` switch or an env restore; `probeHealth()` / `recoverDevice()` watchdog/ANR
63
+ classification; opt-in appops preservation across `installApk()`.
64
+ - **Provisioning hardening** in `lib/jdk.js` / `lib/autosetup.js`: bundled known-good Temurin
65
+ `17.0.21+9` checksum table (including macOS arm64) used when the Adoptium API is unreachable;
66
+ resumable downloads with verified-archive reuse and HTTP `Range`; download-candidate probes and
67
+ per-candidate timeouts (a blocked GitHub host can no longer stall the chain); 3 GB free-disk
68
+ precheck; cross-process `<jdkRoot>/.lock` guard; `jdkVersion` pin; live download progress
69
+ (`detail.progress`) in the panel; host-arch default system image (`arm64-v8a` on arm64 hosts).
70
+ - `examples/agent-workflow.mjs` — a six-step, copy-pasteable Agent workflow (state → install →
71
+ UI tree → tap → assert → screenshot → activity timeline → device identity).
72
+ - `scripts/make-demo-gif.mjs` — dependency-free GIF89a encoder for guest screencap frames, plus
73
+ `docs/demo.gif` (28 s: home → sample APK installed and driven through the HTTP API → 60 fps
74
+ animation). `docs/DEMO.md` documents how to reproduce it.
75
+ - WebView control docs and examples now point at `webview`/`tap_css`/`tap_selector`
76
+ as the preferred path for DOM content.
77
+
78
+ ### Changed
79
+
80
+ - `sdkmanager` installs (`installSystemImage`, `installSdkPackages`) always pass
81
+ `--sdk_root=<sdkRoot>`, so a `sdkmanager` found elsewhere on `PATH` cannot install into the
82
+ wrong SDK. `bootstrapSdk` already did this.
83
+ - The Environment report includes `javaHome` / `javaPresent`, the auto-setup state and the
84
+ activity routes; the panel adds a Java row, auto-setup progress percent/bytes, and the Agent
85
+ activity card. Hypervisor hints are host-architecture neutral.
86
+ - README/docs are now 1.0.0: new sections for the activity log and for multiple instances,
87
+ physical devices and snapshots; expanded troubleshooting for the fixes above; macOS/arm64
88
+ image selection documented; demo media checked in.
89
+
90
+ ### Fixed
91
+
92
+ - `adb` tool action failed with `Cannot access 'api' before initialization` on every call — the
93
+ tool API is now resolved lazily per action.
94
+ - Auto-start after first-use provisioning now uses a dedicated one-shot kick, so a partially
95
+ configured host that attempted a start before provisioning finished still boots once the
96
+ environment reports `ok`.
97
+ - `storage` tool action failed with `storageSdkRoot is not defined` — the helper is hoisted into
98
+ the `apply()` scope shared by the route and the tool.
99
+ - Tool failures now return JSON-safe `{ ok: false, summary, result }` errors instead of throwing
100
+ non-round-trippable exceptions.
101
+ - `push` reported a misleading "local file not found under an allowed root" for files that exist
102
+ but sit outside the configured roots, or for paths on case-insensitive filesystems. Paths are
103
+ realpath-canonicalized, and "outside the allowed roots" (with the resolved roots and a `roots`
104
+ config hint) is now distinct from "file not found".
105
+ - Screenshots could block for the full 180 s budget when the guest `SurfaceFlinger` /
106
+ `system_server` had wedged, with no hint or recovery path. They now fail fast with a
107
+ structured, actionable device error and an opt-in recovery hook.
108
+ - `ui_dump` / `inspect_ui` returned almost no text for WebView-hosted content on some images;
109
+ the dump is now supplemented from guest-side `uiautomator dump`/`adb pull` text nodes.
110
+ - `shell` ran as the unprivileged `shell` user even when the VM reported `root: true`; root
111
+ helpers now make `su` usage explicit (app-data writes still need the app's SELinux category,
112
+ which is documented).
113
+ - Taps on WebView buttons could be silently lost; callers can opt into verification (frame hash
114
+ diff + ±1 px retry). Non-ASCII `type_text` that reached the IME but not a WebView field falls
115
+ back to clipboard paste.
116
+ - After switching an isolated VM to shared networking (or restoring a snapshot created in shared
117
+ mode) the guest could be left without a default route and apps reported `ENETUNREACH`; the
118
+ default route is now repaired in the background.
119
+ - Reinstalling an APK could reset the "install unknown apps" appops flag; `installApk()` can now
120
+ snapshot and restore allowed appops (opt-in).
121
+ - `autoSetup` could hang for the full download budget on a blocked GitHub host; candidate probes
122
+ and per-candidate timeouts plus the known-good JDK table make it fail over instead.
123
+ - macOS arm64 provisioning selected the x86_64 image; it now defaults to `arm64-v8a`.
124
+
125
+ ## 0.12.0
126
+
127
+ Zero-config first run: the plugin now provisions its own JDK, Android SDK, system image and AVD.
128
+
129
+ ### Added
130
+
131
+ - **Automatic environment provisioning (`autoSetup`, default `true`).** The first
132
+ `GET /apk-vm/state` or `GET /apk-vm/setup` request — opening the panel, or an Agent's first
133
+ `apk_vm` call — starts a background chain when the environment is incomplete: download a
134
+ portable **Temurin JDK 17** from Adoptium (SHA-256-verified), bootstrap the Android SDK
135
+ command-line tools and accept licenses, install `platform-tools`/`emulator`/`build-tools`/
136
+ `platforms`, install the configured system image, and create the AVD. The existing
137
+ `autoStart` flow then boots the VM. A cold machine downloads roughly 2.5 GB; set
138
+ `autoSetup: false` to keep setup manual.
139
+ - New `lib/jdk.js`: `findManagedJdk()` / `ensureJdk()` — Temurin 17 download with checksum
140
+ verification, retry-friendly archive reuse, cross-platform extraction, and a managed JDK root
141
+ (`~/.dsh/apk-vm/jdk`, override with `jdkRoot`).
142
+ - JDK download mirror fallback: when the GitHub-hosted Adoptium asset is unreachable (common on
143
+ mainland-China networks), the archive is fetched from the built-in Tsinghua mirror — or the
144
+ `jdkMirror` config / `DSH_APK_VM_JDK_MIRROR` env override — and still verified against
145
+ Adoptium's published SHA-256 checksum.
146
+ - New `lib/autosetup.js`: single-flight orchestrator with per-step progress, cancel and retry;
147
+ exposed as `autoSetup` on `GET /apk-vm/setup`, `POST /apk-vm/setup`
148
+ (`action: auto-setup` / `cancel-auto-setup`), `/apk-vm/state` and the `apk_vm` `info` result.
149
+ - `GET /apk-vm/setup` now reports `javaHome` / `javaPresent`; the Environment card shows a Java
150
+ row plus live auto-setup progress with cancel/retry.
151
+
152
+ ### Changed
153
+
154
+ - `findJavaHome()` also looks in the plugin-managed JDK directory and `extraJavaHomes`, so
155
+ `sdkmanager`/`avdmanager` work without a system-wide JDK or `JAVA_HOME`.
156
+ - When provisioning finishes, the VM and the instance manager adopt the freshly detected SDK,
157
+ emulator and AVD paths (without overriding explicit config), then boot once through the normal
158
+ `autoStart` flow — a cold install goes from zero to a running VM without extra clicks.
159
+ - First-run documentation is now install → open the panel → automatic provisioning → VM start.
160
+
161
+ ### Fixed
162
+
163
+ - The Environment card could stay empty on exactly the machines that needed setup: a
164
+ `GET /apk-vm/setup` payload with `ok: false` was treated as a failed request. It now renders
165
+ the report and exposes the manual and automatic setup actions from there.
166
+ - The privacy scanner also matches non-ASCII workspace paths written with `/` (not only `\`),
167
+ gained an `--untracked` mode for scanning uncommitted files, and two host-specific example
168
+ paths in comments plus a test fixture were made host-neutral.
169
+
170
+ ## 0.11.1
171
+
172
+ Clipboard/text tools no longer need a panel to already have a control stream; network proxy has an alias.
173
+
174
+ ### Fixed
175
+
176
+ - `clipboard_get` / `clipboard_set` and Unicode `type_text` now start the scrcpy control
177
+ stream on demand when no panel client is connected, then release it through the normal
178
+ idle timer. Clipboard reads time out with `504` instead of misreporting a stale stream
179
+ as a missing one (`409`).
180
+ - `action=network, networkAction=proxy` is accepted as an alias for the top-level `proxy`
181
+ action, including `enabled:false` / `clear:true` to disable it.
182
+
3
183
  ## 0.11.0
4
184
 
5
185
  WebView/CDP control, reliable tool JSON, CSS-coordinate input, Unicode typing and reboot-safe network state.
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,40 @@ 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 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).
89
+ - `docs/demo.gif`: the loop itself — home screen → sample APK installed and driven through the
90
+ 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.
69
94
 
70
95
  ## Acceptance checklist
71
96
 
72
97
  - [ ] Environment card reports Ready on a host with SDK + image + AVD + acceleration.
98
+ - [ ] On a cold host the `autoSetup` chain runs to Ready and the VM starts without manual steps.
73
99
  - [ ] Upload and drag-drop both install and launch an APK.
74
100
  - [ ] Phone frame uses `<canvas>` (H.264) when WebCodecs is available; PNG fallback otherwise.
75
101
  - [ ] Header FPS changes when the guest screen animates.
76
102
  - [ ] Rooted debug shell returns `uid=0(root)`; rotate/ui_dump/perf/record/screenshot work.
103
+ - [ ] The **Agent activity** card lists the `apk_vm` calls from the examples/tool run, with
104
+ screenshots for mutating actions.
77
105
  - [ ] Cross-origin request to `/apk-vm/*` is rejected (`403`).
78
106
  - [ ] Quick boot measured under 30 s after the snapshot exists.
79
107