dsh-apk-vm 0.3.13 → 0.4.0

package/docs/LINUX-E2E.md

@@ -0,0 +1,81 @@
+# Linux end-to-end validation
+
+A real headless Linux run was performed on Ubuntu 22.04.5 LTS (kernel 6.8, x86_64),
+using the plugin's own `AndroidVm` and `ScrcpySession` code. This is not a mock or a
+CI-only check.
+
+## Host
+
+| Item | Value |
+| --- | --- |
+| OS | Ubuntu 22.04.5 LTS, x86_64 |
+| CPU | 192 cores, KVM v12 (`/dev/kvm` usable) |
+| RAM | 94 GiB |
+| Display | none (`DISPLAY` unset) |
+| Node | v24.22.1 |
+| Java | OpenJDK 17 JRE |
+| Android SDK | cmdline-tools 12.0, platform-tools 37.0.1, emulator 37.2.12.0, build-tools 34.0.0 |
+| System image | `system-images;android-34;default;x86_64` |
+| AVD | `dsh_linux_test` (1080×2340, pixel_5) |
+
+The regular `OPENCODE` account is **not in the `kvm` group** and has no passwordless sudo;
+`/dev/kvm` is denied for it. The emulator portion was therefore run as the provided
+`OPENCODE_100` account (same SSH key), which is in the `kvm` group. The plugin itself never
+requires sudo or system-wide changes.
+
+## Emulator launch
+
+```text
+qemu-system-x86_64-headless -avd dsh_linux_test -no-window -no-audio -no-boot-anim \
+  -no-snapshot -gpu swiftshader_indirect -port 5558
+```
+
+- KVM detected: **`accel=true`**
+- Cold boot: **35.2 s** (first run 49.0 s)
+- adb serial: `emulator-5558`, API 34, userdebug, 1080×2340
+- `adb root`: **uid=0**
+
+## Verified on Linux
+
+- `AndroidVm` lifecycle: start → attach → boot probe → ready; state and boot time.
+- `adb root` and the on-device debug toolkit.
+- Real signed APK install + auto-launch; UIAutomator dump; input tap; result text assertion.
+- PNG screenshot (`exec-out screencap -p`, 46,650 bytes in 415 ms).
+- HTTP proxy set / clear.
+- CA certificate installation (`73393196.0`, user CA store).
+- `ScrcpySession` 5.0.1 H.264: `avc1.42C029`, 332×720, 30 media packets, 1 keyframe,
+  9,057-byte capture; scrcpy control swipe produced new video.
+- `screenrecord` 3 s MP4.
+- `stop()` safety: a pre-existing/auto-attached emulator is left running, not killed.
+
+## Test suite
+
+On the validated snapshot:
+
+- `npm run check` — pass
+- `npm test` — pass (UI/sidebar, setup 32/32, mock-device 25/25, launch-plan, instances,
+  features 4/4)
+- `spike/scrcpy/test-fake-device.js` — 160/160 pass
+
+The final tree should be re-run in CI for the release tag.
+
+## Known limitations
+
+- `quickBoot` snapshots were not exercised on Linux (tests used `-no-snapshot` to save disk).
+- Headless `swiftshader_indirect` can print non-fatal `ColorBuffer` warnings while taking
+  screenshots; the screenshots still succeed.
+- The emulator prints a metrics-collection warning; the launch args now include
+  `-no-metrics`.
+- `OPENCODE` without `kvm` group membership gets the documented "No usable CPU hypervisor"
+  error instead of a hung boot. Add the user to `kvm` (or use an account that has it) for
+  hardware acceleration.
+- The platform still requires an Android SDK and AVD; only the SDK install and test harness
+  were performed as a separate account on this shared host.
+
+## Cross-platform status
+
+| Platform | Status |
+| --- | --- |
+| Windows x64 | end-to-end verified (AEHD, live panel, H.264, Agent tool) |
+| Linux x86_64 | end-to-end verified headless (KVM + SwiftShader, H.264, root, APK install) |
+| macOS | SDK discovery + headless CI only; no live emulator run in this repository |

package/docs/README.md

@@ -14,3 +14,18 @@ Still optional:
 
 The assets are not fabricated. Before adding a new screenshot, crop out or redact the DSH
 sidebar conversation names, local paths and any LAN IPs.
+
+## Reproducible demo source
+
+[`examples/`](../examples/README.md) contains a self-contained, dependency-free demo:
+
+- a tiny MIT-licensed sample APK whose sources and deterministic SDK-only build script are
+  checked in (`examples/sample-apk/`),
+- `examples/demo.mjs`, which drives the documented local HTTP API through state → install →
+  UI inspection → tap → text assertion → screenshot,
+- exact commands, expected output and troubleshooting in
+  [`examples/README.md`](../examples/README.md).
+
+The sample screenshot at [`examples/sample-app.png`](../examples/sample-app.png) is the app
+running in the VM, not a desktop capture.
+

package/docs/SUBMISSION.md

@@ -25,6 +25,8 @@ npm 包安装（插件中心/社区市场推荐命令）：
 dsh plugin --profile web add dsh-apk-vm
 ```
 
+npm 包：<https://www.npmjs.com/package/dsh-apk-vm>
+
 源码 fallback：
 
 ```bash
@@ -36,8 +38,9 @@ DSH Desktop（`desktop` profile）通过 **Plugins → add/install local bundle*
 ### 兼容与运行要求
 
 - DSH Desktop `0.2.1-rc.3` 已实测；静态 bundle/plugin API。
-- Windows x64 为唯一端到端验证平台（启动、H.264、root 调试、Agent tool）；macOS/Linux 有
-  headless setup/CI 覆盖，但未做真实模拟器运行验证。
+- Windows x64 与 Linux x86_64（headless，KVM + SwiftShader）为端到端验证平台（启动、
+  H.264、root 调试、APK 安装、Agent tool）；macOS 有 SDK 探测/headless CI 覆盖，但未做
+  真实模拟器运行验证。详见 `docs/LINUX-E2E.md`。
 - 需要 Android SDK/emulator/platform-tools、Android 14 x86_64 system image、AVD，以及
   AEHD/WHPX（Windows）、KVM（Linux）或 HVF（macOS）硬件虚拟化。
 - 每个运行中的 VM 约占 2.5 GB 内存；默认最多 3 个额外实例。

package/index.js

@@ -26,6 +26,8 @@ import { InstanceManager } from './lib/instances.js';
 import { ScrcpySession, annexbToAvcc, CONTROL_MESSAGE_TYPE } from './lib/scrcpy.js';
 import { detectEnvironment, createAvd, installSystemImage, installSdkPackages, bootstrapSdk, DEFAULT_SYSTEM_IMAGE } from './lib/setup.js';
 import { acceptWebSocket } from './lib/ws.js';
+import { parseUiHierarchy, decorateUiNodes, buildInspectorPayload } from './lib/ui-inspector.js';
+import { FlowRecorder } from './lib/flows.js';
 
 export const name = 'dsh-apk-vm';
 
@@ -207,7 +209,7 @@ function resolveApkPath(candidate, roots) {
   for (const p of paths) {
     try {
       const resolved = path.resolve(p);
-      if (!resolved.toLowerCase().endsWith('.apk')) continue;
+      if (!/\.(?:apk|apks|xapk)$/i.test(resolved)) continue;
       if (existsSync(resolved)) return resolved;
     } catch {
       /* try next */
@@ -269,6 +271,7 @@ export function apply(ctx, config = {}) {
   let serverOrigin = null;
   let registerInstanceRoutes = null;
   let disposeInstanceRoutes = null;
+  const flowRecorder = new FlowRecorder();
   if (instanceManager) {
     instanceManager.onCreated = (id) => {
       registerInstanceRoutes?.(id);
@@ -602,8 +605,8 @@ export function apply(ctx, config = {}) {
     let apkPath;
     if (options.trustedPath === true) {
       apkPath = path.resolve(String(candidate || ''));
-      if (!apkPath.toLowerCase().endsWith('.apk') || !existsSync(apkPath)) {
-        throw new Error(`uploaded APK is missing or invalid: ${apkPath}`);
+      if (!/\.(?:apk|apks|xapk)$/i.test(apkPath) || !existsSync(apkPath)) {
+        throw new Error(`uploaded APK/bundle is missing or invalid: ${apkPath}`);
       }
     } else {
       apkPath = resolveApkPath(candidate, rootsFor());
@@ -618,6 +621,7 @@ export function apply(ctx, config = {}) {
       launchActivity: meta.launchActivity || null,
       launched: meta.launched !== false,
       installedAt: Date.now(),
+      bundle: meta.bundle || null,
     };
     frame.buffer = null;
     frame.at = 0;
@@ -811,6 +815,59 @@ export function apply(ctx, config = {}) {
       );
     };
 
+    async function handleFlowRequest(req, res, instanceId, inputFn) {
+      if (req.method === 'GET') {
+        sendJson(res, 200, {
+          ok: true,
+          instance: instanceId,
+          recording: flowRecorder.isRecording(instanceId),
+          flows: await flowRecorder.list(instanceId),
+        });
+        return;
+      }
+      if (req.method !== 'POST') {
+        sendError(res, 405, 'GET or POST only');
+        return;
+      }
+      const body = await readJsonBody(req);
+      const action = String(body.action || '').toLowerCase();
+      try {
+        if (action === 'start') {
+          const flow = flowRecorder.start(instanceId, body.name);
+          sendJson(res, 200, { ok: true, action, ...flow });
+          return;
+        }
+        if (action === 'stop') {
+          const flow = await flowRecorder.stop(instanceId);
+          sendJson(res, 200, { ok: true, action, ...flow });
+          return;
+        }
+        if (action === 'replay') {
+          if (!body.id) throw new Error('replay requires id');
+          const result = await flowRecorder.replay(body.id, inputFn, { instanceId });
+          sendJson(res, 200, { ok: true, action, ...result });
+          return;
+        }
+        if (action === 'delete') {
+          if (!body.id) throw new Error('delete requires id');
+          const removed = await flowRecorder.remove(body.id, instanceId);
+          sendJson(res, 200, { ok: true, action, removed });
+          return;
+        }
+        throw new Error(`unsupported flow action: ${action || '(missing)'}`);
+      } catch (error) {
+        sendError(res, 400, error.message);
+      }
+    }
+
+    register('/apk-vm/flows', async (req, res) => {
+      await handleFlowRequest(req, res, 'default', async (payload) => {
+        const status = await vm.status();
+        if (!isReady(status)) throw new Error(`VM is not ready (state: ${status.state})`);
+        return vm.input(payload);
+      });
+    });
+
     register('/apk-vm/state', async (req, res) => {
       if (req.method !== 'GET' && req.method !== 'HEAD') {
         sendError(res, 405, 'GET only');
@@ -1077,10 +1134,20 @@ export function apply(ctx, config = {}) {
       }
       if (rest === 'input' && req.method === 'POST') {
         if (!(await ready())) return;
-        await instance.input(await readJsonBody(req));
+        const body = await readJsonBody(req);
+        flowRecorder.record(id, body);
+        await instance.input(body);
         sendJson(res, 200, { ok: true });
         return;
       }
+      if (rest === 'flows') {
+        await handleFlowRequest(req, res, id, async (payload) => {
+          const status = await instance.status();
+          if (status.state !== 'ready') throw new Error(`instance ${id} is not ready (state: ${status.state})`);
+          return instance.input(payload);
+        });
+        return;
+      }
       if (rest === 'touch' && req.method === 'POST') {
         const body = await readJsonBody(req);
         const action = String(body.action || '').toLowerCase();
@@ -1188,6 +1255,39 @@ export function apply(ctx, config = {}) {
           sendJson(res, 200, await instance.uiDump());
           return;
         }
+        if (op === 'inspect' && req.method === 'GET') {
+          if (!(await ready())) return;
+          const dump = await instance.uiDump();
+          let screen = null;
+          try {
+            screen = await instance.vm.screenSize();
+          } catch {
+            screen = null;
+          }
+          sendJson(res, 200, buildInspectorPayload(dump, screen));
+          return;
+        }
+        if (op === 'proxy' && ['GET', 'POST', 'DELETE'].includes(req.method)) {
+          if (!(await ready())) return;
+          try {
+            if (req.method === 'GET') sendJson(res, 200, await instance.vm.getProxy());
+            else if (req.method === 'DELETE') sendJson(res, 200, await instance.vm.setProxy({ enabled: false }));
+            else sendJson(res, 200, await instance.vm.setProxy(await readJsonBody(req)));
+          } catch (error) {
+            sendError(res, 400, error.message);
+          }
+          return;
+        }
+        if (op === 'ca' && req.method === 'POST') {
+          if (!(await ready())) return;
+          try {
+            const body = await readJsonBody(req);
+            sendJson(res, 200, await instance.vm.installCaCertificate(body.path));
+          } catch (error) {
+            sendError(res, 400, error.message);
+          }
+          return;
+        }
         if (op === 'record' && req.method === 'POST') {
           if (!(await ready())) return;
           sendJson(res, 200, await instance.screenRecord({ seconds: (await readJsonBody(req)).seconds }));
@@ -1271,6 +1371,9 @@ export function apply(ctx, config = {}) {
         'debug/root',
         'debug/rotate',
         'debug/ui',
+        'debug/inspect',
+        'debug/proxy',
+        'debug/ca',
         'debug/record',
         'debug/perf',
         'debug/screenshot',
@@ -1278,6 +1381,7 @@ export function apply(ctx, config = {}) {
         'debug/push',
         'debug/pull',
         'debug/reboot',
+        'flows',
       ];
       const disposers = [];
       for (const suffix of suffixes) {
@@ -1550,7 +1654,7 @@ export function apply(ctx, config = {}) {
       }
       let safeName = path.basename(rawName || 'upload.apk').replace(/[^A-Za-z0-9._-]+/g, '_');
       if (!safeName) safeName = 'upload.apk';
-      if (!/\.apk$/i.test(safeName)) safeName += '.apk';
+      if (!/\.(?:apk|apks|xapk)$/i.test(safeName)) safeName += '.apk';
       let data;
       try {
         data = await readRawBody(req, UPLOAD_LIMIT_BYTES);
@@ -1616,6 +1720,7 @@ export function apply(ctx, config = {}) {
         sendError(res, 409, `VM is not ready (state: ${status.state})`);
         return;
       }
+      flowRecorder.record('default', body);
       await vm.input(body);
       sendJson(res, 200, { ok: true });
     });
@@ -1859,6 +1964,58 @@ export function apply(ctx, config = {}) {
       sendJson(res, 200, await vm.uiDump());
     });
 
+    register('/apk-vm/debug/inspect', async (req, res) => {
+      if (req.method !== 'GET') {
+        sendError(res, 405, 'GET only');
+        return;
+      }
+      if (!(await ensureDebugReady(res))) return;
+      const dump = await vm.uiDump();
+      let screen = null;
+      try {
+        screen = await vm.screenSize();
+      } catch {
+        screen = null;
+      }
+      sendJson(res, 200, buildInspectorPayload(dump, screen));
+    });
+
+    register('/apk-vm/debug/proxy', async (req, res) => {
+      if (!['GET', 'POST', 'DELETE'].includes(req.method)) {
+        sendError(res, 405, 'GET, POST or DELETE only');
+        return;
+      }
+      if (!(await ensureDebugReady(res))) return;
+      try {
+        if (req.method === 'GET') {
+          sendJson(res, 200, await vm.getProxy());
+          return;
+        }
+        if (req.method === 'DELETE') {
+          sendJson(res, 200, await vm.setProxy({ enabled: false }));
+          return;
+        }
+        const body = await readJsonBody(req);
+        sendJson(res, 200, await vm.setProxy(body));
+      } catch (error) {
+        sendError(res, 400, error.message);
+      }
+    });
+
+    register('/apk-vm/debug/ca', async (req, res) => {
+      if (req.method !== 'POST') {
+        sendError(res, 405, 'POST only');
+        return;
+      }
+      if (!(await ensureDebugReady(res))) return;
+      try {
+        const body = await readJsonBody(req);
+        sendJson(res, 200, await vm.installCaCertificate(body.path));
+      } catch (error) {
+        sendError(res, 400, error.message);
+      }
+    });
+
     register('/apk-vm/debug/record', async (req, res) => {
       if (req.method !== 'POST') {
         sendError(res, 405, 'POST only');
@@ -2039,7 +2196,10 @@ export function apply(ctx, config = {}) {
       getprop: (name) => vm.getprop(name),
       setprop: (name, value) => vm.setprop(name, value),
       listPackages: (options) => vm.listPackages(options),
-      input: (payload) => vm.input(payload),
+      input: (payload) => {
+        flowRecorder.record('default', payload);
+        return vm.input(payload);
+      },
       getClipboard: async () => {
         const session = scrcpyState && scrcpyState.session;
         if (!session || session.state !== 'running') throw new Error('H.264 control stream is not running');
@@ -2059,6 +2219,10 @@ export function apply(ctx, config = {}) {
       uninstall: (pkg) => vm.uninstall(pkg),
       rotate: (orientation) => vm.rotate(orientation),
       uiDump: () => vm.uiDump(),
+      screenSize: () => vm.screenSize(),
+      getProxy: () => vm.getProxy(),
+      setProxy: (options) => vm.setProxy(options),
+      installCaCertificate: (certPath) => vm.installCaCertificate(certPath),
       screenRecord: (options) => vm.screenRecord(options),
       perfSnapshot: () => vm.perfSnapshot(),
       screenshot: async () => {
@@ -2084,7 +2248,10 @@ export function apply(ctx, config = {}) {
       getprop: (name) => instance.getprop(name),
       setprop: (name, value) => instance.setprop(name, value),
       listPackages: (options) => instance.listPackages(options),
-      input: (payload) => instance.input(payload),
+      input: (payload) => {
+        flowRecorder.record(instance.id, payload);
+        return instance.input(payload);
+      },
       getClipboard: () => instance.getClipboard(),
       setClipboard: (text, paste) => instance.setClipboard(text, paste),
       install: async (apkPath) => instance.installApk(resolveApkPath(apkPath, rootsFor())),
@@ -2096,6 +2263,10 @@ export function apply(ctx, config = {}) {
       uninstall: (pkg) => instance.uninstall(pkg),
       rotate: (orientation) => instance.rotate(orientation),
       uiDump: () => instance.uiDump(),
+      screenSize: () => instance.vm.screenSize(),
+      getProxy: () => instance.vm.getProxy(),
+      setProxy: (options) => instance.vm.setProxy(options),
+      installCaCertificate: (certPath) => instance.vm.installCaCertificate(certPath),
       screenRecord: (options) => instance.screenRecord(options),
       perfSnapshot: () => instance.perfSnapshot(),
       screenshot: async () => {
@@ -2197,8 +2368,8 @@ export function apply(ctx, config = {}) {
       'Operate the local rooted Android APK virtual machine (Android emulator) that the APK VM panel manages. ' +
       'The VM is usually already running (warm start); adbd runs as root once ready. ' +
       'Actions: info, shell, logcat, getprop, setprop, packages, install, push, pull, reboot, root, ' +
-      'force_stop, clear_data, uninstall, rotate, ui_dump, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
-      'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance. ' +
+      'force_stop, clear_data, uninstall, rotate, ui_dump, inspect_ui, proxy, install_ca, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
+      'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance, flow_start, flow_stop, flow_list, flow_replay. ' +
       'Multi-instance: pass `instance` to target an isolated VM; omit it to use the calling Agent\'s ' +
       'assigned instance (first Agent gets the default VM, later Agents get isolated instances). ' +
       'Use shell for low-level Android commands, logcat for logs, ' +
@@ -2211,7 +2382,7 @@ export function apply(ctx, config = {}) {
       properties: {
         action: {
           type: 'string',
-          description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance',
+          description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|flow_start|flow_stop|flow_list|flow_replay',
         },
         instance: { type: 'string', description: 'Target VM instance id (default or an extra instance from list_instances). Omit for the calling Agent\'s assigned instance.' },
         instanceName: { type: 'string', description: 'create_instance: optional name for the new isolated instance.' },
@@ -2243,6 +2414,10 @@ export function apply(ctx, config = {}) {
         className: { type: 'string', description: 'find_ui: substring of the Android class name.' },
         paste: { type: 'boolean', description: 'clipboard_set: also paste immediately (scrcpy paste flag).' },
         serial: { type: 'string', description: 'attach_device: adb serial of an online physical/remote device; detach_device ignores it.' },
+        host: { type: 'string', description: 'proxy: HTTP proxy host (the emulator host alias reaches the host machine).' },
+        port: { type: 'integer', description: 'proxy: HTTP proxy port (1-65535).' },
+        bypass: { type: 'string', description: 'proxy: optional no-proxy/exclusion list.' },
+        flowId: { type: 'string', description: 'flow_replay: saved flow id from flow_list.' },
       },
       required: ['action'],
     },
@@ -2346,6 +2521,29 @@ export function apply(ctx, config = {}) {
       }
 
       const api = await resolveToolApi(args, exec);
+      if (action === 'flow_list') {
+        return {
+          ok: true,
+          summary: `${(await flowRecorder.list(api.id)).length} saved flow(s) on ${api.id}`,
+          result: { instance: api.id, recording: flowRecorder.isRecording(api.id), flows: await flowRecorder.list(api.id) },
+        };
+      }
+      if (action === 'flow_start') {
+        const flow = flowRecorder.start(api.id, args.name);
+        return { ok: true, summary: `recording flow ${flow.name} (${flow.id}) on ${api.id}`, result: flow };
+      }
+      if (action === 'flow_stop') {
+        const flow = await flowRecorder.stop(api.id);
+        return { ok: true, summary: `saved flow ${flow.name} (${flow.id}, ${flow.events} events)`, result: flow };
+      }
+      if (action === 'flow_replay') {
+        if (!args.flowId) throw new Error('action=flow_replay requires flowId from flow_list');
+        await ensureToolApiReady(api, action);
+        const replayed = await flowRecorder.replay(args.flowId, async (payload) => api.input(payload), {
+          instanceId: api.id,
+        });
+        return { ok: true, summary: `replayed ${replayed.steps} step(s) from ${replayed.name}`, result: replayed };
+      }
       if (action === 'start') {
         const snapshot = await api.start();
         return { ok: true, summary: `started ${api.id}`, result: snapshot || {} };
@@ -2461,6 +2659,44 @@ export function apply(ctx, config = {}) {
           const result = await api.uiDump();
           return { ok: true, summary: `UI dump: ${result.nodes} nodes, ${result.bytes} bytes`, result };
         }
+        case 'inspect_ui': {
+          const dump = await api.uiDump();
+          let screen = null;
+          try {
+            screen = await api.screenSize();
+          } catch {
+            screen = null;
+          }
+          const inspector = buildInspectorPayload(dump, screen);
+          const interactive = inspector.nodes.filter((node) => node.interactive);
+          return {
+            ok: true,
+            summary:
+              `${inspector.nodes.length} UI node(s), ${interactive.length} interactive; ` +
+              `screen ${screen ? `${screen.width}x${screen.height}` : '?'}`,
+            result: inspector,
+          };
+        }
+        case 'proxy': {
+          if (args.enabled === false || args.clear === true) {
+            const cleared = await api.setProxy({ enabled: false });
+            return { ok: true, summary: 'HTTP proxy cleared', result: cleared };
+          }
+          if (args.host !== undefined) {
+            const applied = await api.setProxy({ host: args.host, port: args.port, bypass: args.bypass, enabled: true });
+            return { ok: true, summary: `HTTP proxy set to ${applied.proxy}`, result: applied };
+          }
+          return { ok: true, summary: 'current HTTP proxy settings', result: await api.getProxy() };
+        }
+        case 'install_ca': {
+          if (!args.path) throw new Error('action=install_ca requires path to a .pem/.crt certificate');
+          const installed = await api.installCaCertificate(args.path);
+          return {
+            ok: true,
+            summary: `installed CA ${installed.fileName}${installed.systemCa ? ' (system+user)' : ' (user store)'}`,
+            result: installed,
+          };
+        }
         case 'find_ui': {
           const dump = await api.uiDump();
           const matches = parseUiNodes(dump.xml).filter((node) => uiNodeMatches(node, args)).slice(0, 20);