serve-emul 0.0.4

package/src/app-management.ts

@@ -0,0 +1,150 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export type AppActionResult = {
+  ok: true;
+  output: string;
+};
+
+export type FileImportResult = AppActionResult & {
+  path: string;
+  kind: "image" | "video" | "file";
+};
+
+const PACKAGE_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/;
+const PERMISSION_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/;
+const ACTIVITY_RE = /^([A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+|\.?[A-Za-z][A-Za-z0-9_.$]*)(\/[A-Za-z0-9_.$]+)?$/;
+
+function output(stdout: string, stderr: string): string {
+  return `${stdout}${stderr}`.trim();
+}
+
+function adb(serial: string, args: string[], timeout = 30_000): AppActionResult {
+  const result = spawnSync("adb", ["-s", serial, ...args], {
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024,
+    timeout,
+  });
+  const text = output(result.stdout, result.stderr);
+  if (result.status !== 0) {
+    throw new Error(text || `adb ${args.join(" ")} failed`);
+  }
+  return { ok: true, output: text };
+}
+
+function adbHost(serial: string, args: string[], timeout = 30_000): AppActionResult {
+  return adb(serial, args, timeout);
+}
+
+function validate(value: unknown, name: string, pattern: RegExp): string {
+  if (typeof value !== "string" || !pattern.test(value.trim())) {
+    throw new Error(`${name} is invalid`);
+  }
+  return value.trim();
+}
+
+export function packageName(value: unknown): string {
+  return validate(value, "packageName", PACKAGE_RE);
+}
+
+export function activityName(value: unknown): string {
+  return validate(value, "activity", ACTIVITY_RE);
+}
+
+export function permissionName(value: unknown): string {
+  return validate(value, "permission", PERMISSION_RE);
+}
+
+export async function installApk(serial: string, file: File): Promise<AppActionResult> {
+  if (!file.name.toLowerCase().endsWith(".apk")) throw new Error("APK file must end with .apk");
+  const dir = mkdtempSync(join(tmpdir(), "serve-emul-apk-"));
+  const path = join(dir, "upload.apk");
+  try {
+    writeFileSync(path, new Uint8Array(await file.arrayBuffer()));
+    return adb(serial, ["install", "-r", path], 120_000);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function safeFileName(name: string): string {
+  const clean = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return clean || `upload-${Date.now()}`;
+}
+
+function mediaKind(file: File): FileImportResult["kind"] {
+  if (file.type.startsWith("image/")) return "image";
+  if (file.type.startsWith("video/")) return "video";
+  const lower = file.name.toLowerCase();
+  if (/\.(png|jpe?g|gif|webp|heic|heif)$/.test(lower)) return "image";
+  if (/\.(mp4|m4v|mov|webm|3gp|mkv)$/.test(lower)) return "video";
+  return "file";
+}
+
+export async function importMediaFile(serial: string, file: File): Promise<FileImportResult> {
+  const dir = mkdtempSync(join(tmpdir(), "serve-emul-media-"));
+  const localPath = join(dir, safeFileName(file.name));
+  const kind = mediaKind(file);
+  const remoteDir =
+    kind === "image" ? "/sdcard/Pictures" : kind === "video" ? "/sdcard/Movies" : "/sdcard/Download";
+  const remotePath = `${remoteDir}/${safeFileName(file.name)}`;
+  try {
+    writeFileSync(localPath, new Uint8Array(await file.arrayBuffer()));
+    adb(serial, ["shell", "mkdir", "-p", remoteDir]);
+    adbHost(serial, ["push", localPath, remotePath], 120_000);
+    adb(serial, [
+      "shell",
+      "am",
+      "broadcast",
+      "-a",
+      "android.intent.action.MEDIA_SCANNER_SCAN_FILE",
+      "-d",
+      `file://${remotePath}`,
+    ]);
+    return { ok: true, output: `Imported ${file.name} to ${remotePath}`, path: remotePath, kind };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export function launchApp(serial: string, packageNameValue: string, activity?: string): AppActionResult {
+  const pkg = packageName(packageNameValue);
+  if (activity) {
+    const act = activityName(activity);
+    const component = act.includes("/") ? act : `${pkg}/${act}`;
+    return adb(serial, ["shell", "am", "start", "-n", component]);
+  }
+  return adb(serial, [
+    "shell",
+    "monkey",
+    "-p",
+    pkg,
+    "-c",
+    "android.intent.category.LAUNCHER",
+    "1",
+  ]);
+}
+
+export function clearAppData(serial: string, packageNameValue: string): AppActionResult {
+  return adb(serial, ["shell", "pm", "clear", packageName(packageNameValue)]);
+}
+
+export function forceStopApp(serial: string, packageNameValue: string): AppActionResult {
+  return adb(serial, ["shell", "am", "force-stop", packageName(packageNameValue)]);
+}
+
+export function grantPermission(
+  serial: string,
+  packageNameValue: string,
+  permissionValue: string,
+): AppActionResult {
+  return adb(serial, [
+    "shell",
+    "pm",
+    "grant",
+    packageName(packageNameValue),
+    permissionName(permissionValue),
+  ]);
+}

package/src/cli.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { pickDevice } from "./adb.ts";
+import { listAvds, listRunningAvds, startEmulator } from "./emulator.ts";
+import { startServer } from "./server.ts";
+import { getUpdateNotice } from "./update-check.ts";
+import packageJson from "../package.json";
+
+const argv = Bun.argv.slice(2);
+const { values } = parseArgs({
+  args: argv,
+  options: {
+    port: { type: "string", short: "p", default: "3300" },
+    serial: { type: "string", short: "s" },
+    "max-fps": { type: "string", default: "60" },
+    "bit-rate": { type: "string", default: "8000000" },
+    "max-size": { type: "string", default: "1920" },
+    "key-frame-interval": { type: "string", default: "1" },
+    avd: { type: "string" },
+    "avd-list": { type: "boolean" },
+    "running-avds": { type: "boolean" },
+    "restart-avd": { type: "boolean" },
+    emulator: { type: "string" },
+    "emulator-port": { type: "string" },
+    help: { type: "boolean", short: "h" },
+  },
+  allowPositionals: true,
+});
+
+function numberOption(name: string, fallback: number): number {
+  const value = values[name as keyof typeof values];
+  if (typeof value !== "string") return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new Error(`--${name} must be a number.`);
+  return n;
+}
+
+async function checkForUpdate() {
+  if (process.env.SERVE_EMUL_UPDATE_CHECK === "0") return;
+
+  const notice = await getUpdateNotice({
+    packageName: packageJson.name,
+    currentVersion: packageJson.version,
+    cachePath: process.env.SERVE_EMUL_UPDATE_CHECK_CACHE,
+  });
+  if (notice) console.error(notice);
+}
+
+if (values.help) {
+  console.log(`serve-emul — host an Android device over scrcpy + WebSocket
+
+Usage:
+  serve-emul [-p <port>] [-s <serial>] [--max-fps N] [--bit-rate N] [--max-size N] [--key-frame-interval sec]
+  serve-emul --avd <name> [--restart-avd]
+  serve-emul --avd-list
+  serve-emul --running-avds
+
+Options:
+  -p, --port <port>      Port to listen on (default: 3300)
+  -s, --serial <serial>  adb device serial (defaults to the only booted device)
+      --max-fps <n>      Cap source frame rate (default: 60)
+      --bit-rate <bps>   H.264 bit rate (default: 8000000)
+      --max-size <px>    Cap longest screen edge in pixels; 0 = native, but many
+                         emulators reject native resolutions above ~2560 so this
+                         defaults to 1920.
+      --key-frame-interval <sec>
+                         Ask the encoder for regular keyframes; 0 disables this
+                         codec option (default: 1)
+      --avd <name>       Launch this Android Virtual Device before streaming
+      --restart-avd      Stop a running matching AVD before launching it
+      --avd-list         Print available Android Virtual Device names
+      --running-avds     Print currently running emulator AVDs
+      --emulator <path>  Android Emulator binary (default: PATH or Android SDK)
+      --emulator-port <n>
+                         Emulator console port for --avd (even 5554-5682)
+  -h, --help             Show this help
+`);
+  process.exit(0);
+}
+
+async function main() {
+  await checkForUpdate().catch(() => {});
+
+  if (values["avd-list"]) {
+    console.log(listAvds(values.emulator).join("\n"));
+    return;
+  }
+
+  if (values["running-avds"]) {
+    const running = listRunningAvds();
+    console.log(running.length ? running.map((avd) => `${avd.serial}\t${avd.avd}\t${avd.state}`).join("\n") : "");
+    return;
+  }
+
+  if ((values["emulator-port"] || values["restart-avd"]) && !values.avd) {
+    throw new Error("--emulator-port and --restart-avd require --avd.");
+  }
+
+  if (values.avd && values.serial) {
+    throw new Error("Use either --avd to launch an emulator or --serial to attach to an existing device, not both.");
+  }
+
+  let emulatorLaunch: Awaited<ReturnType<typeof startEmulator>> | null = null;
+  const serial = values.avd
+    ? (emulatorLaunch = await startEmulator({
+        avd: values.avd,
+        emulatorPath: values.emulator,
+        port: values["emulator-port"] ? Number(values["emulator-port"]) : undefined,
+        restartAvd: values["restart-avd"],
+      })).serial
+    : pickDevice(values.serial);
+  const port = Number(values.port);
+  const maxFps = numberOption("max-fps", 60);
+  const bitRate = numberOption("bit-rate", 8_000_000);
+  const maxSize = numberOption("max-size", 1920);
+  const keyFrameInterval = numberOption("key-frame-interval", 1);
+
+  const { server, stop: stopServer } = await startServer({
+    serial,
+    port,
+    maxFps,
+    bitRate,
+    maxSize,
+    keyFrameInterval,
+  }).catch((err) => {
+    emulatorLaunch?.stop();
+    throw err;
+  });
+
+  const stop = () => {
+    stopServer();
+    emulatorLaunch?.stop();
+  };
+  process.once("SIGINT", () => {
+    stop();
+    process.exit(0);
+  });
+  process.once("SIGTERM", () => {
+    stop();
+    process.exit(0);
+  });
+
+  console.log(`serve-emul → http://localhost:${server.port}  (device: ${serial})`);
+}
+
+await main().catch((err) => {
+  console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/src/emulator.ts

@@ -0,0 +1,229 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { listAllDevices } from "./adb.ts";
+
+export type EmulatorLaunch = {
+  serial: string;
+  proc: ChildProcess | null;
+  ownsProcess: boolean;
+  stop: () => void;
+};
+
+export type RunningAvd = {
+  serial: string;
+  avd: string;
+  state: string;
+};
+
+export type StartEmulatorOpts = {
+  avd: string;
+  emulatorPath?: string;
+  port?: number;
+  restartAvd?: boolean;
+  bootTimeoutMs?: number;
+};
+
+function sdkEmulatorCandidates(): string[] {
+  const roots = [
+    process.env.ANDROID_HOME,
+    process.env.ANDROID_SDK_ROOT,
+    process.env.HOME ? join(process.env.HOME, "Library", "Android", "sdk") : undefined,
+  ].filter((v): v is string => Boolean(v));
+  return [...new Set(roots)].flatMap((root) => [
+    join(root, "emulator", "emulator"),
+    join(root, "tools", "emulator"),
+  ]);
+}
+
+export function resolveEmulator(explicit?: string): string {
+  if (explicit) return explicit;
+
+  const pathProbe = spawnSync("emulator", ["-version"], { encoding: "utf8" });
+  if (pathProbe.status === 0 || pathProbe.error?.message.includes("EPIPE")) return "emulator";
+
+  for (const candidate of sdkEmulatorCandidates()) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  throw new Error(
+    "Could not find Android Emulator. Put `emulator` on PATH or set ANDROID_HOME / ANDROID_SDK_ROOT.",
+  );
+}
+
+function listAvdsWithEmulator(emulator: string): string[] {
+  const r = spawnSync(emulator, ["-list-avds"], { encoding: "utf8" });
+  if (r.status !== 0) {
+    throw new Error(`emulator -list-avds failed: ${r.stderr || r.stdout}`);
+  }
+  return r.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+export function listAvds(emulatorPath?: string): string[] {
+  return listAvdsWithEmulator(resolveEmulator(emulatorPath));
+}
+
+function avdName(avd: string): string {
+  return avd.startsWith("@") ? avd.slice(1) : avd;
+}
+
+function emulatorAvdArg(avd: string): string {
+  return avd.startsWith("@") ? avd : `@${avd}`;
+}
+
+function usedEmulatorPorts(): Set<number> {
+  const ports = new Set<number>();
+  for (const device of listAllDevices()) {
+    const match = device.serial.match(/^emulator-(\d+)$/);
+    if (match) ports.add(Number(match[1]));
+  }
+  return ports;
+}
+
+function pickEmulatorPort(): number {
+  const used = usedEmulatorPorts();
+  for (let port = 5554; port <= 5682; port += 2) {
+    if (!used.has(port)) return port;
+  }
+  throw new Error("No available emulator console ports in the 5554-5682 range.");
+}
+
+function validateEmulatorPort(port: number): void {
+  if (!Number.isInteger(port) || port < 5554 || port > 5682 || port % 2 !== 0) {
+    throw new Error("--emulator-port must be an even integer from 5554 through 5682.");
+  }
+}
+
+function adb(serial: string, args: string[]) {
+  return spawnSync("adb", ["-s", serial, ...args], {
+    encoding: "utf8",
+    timeout: 5_000,
+  });
+}
+
+function parseEmuAvdName(stdout: string): string | null {
+  return (
+    stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find((line) => line && line !== "OK" && !line.startsWith("KO:")) ?? null
+  );
+}
+
+function runningAvdName(serial: string): string | null {
+  const fromConsole = adb(serial, ["emu", "avd", "name"]);
+  if (fromConsole.status === 0) {
+    const name = parseEmuAvdName(fromConsole.stdout);
+    if (name) return name;
+  }
+
+  const fromProp = adb(serial, ["shell", "getprop", "ro.boot.qemu.avd_name"]);
+  if (fromProp.status === 0) {
+    const name = fromProp.stdout.trim();
+    if (name) return name;
+  }
+
+  return null;
+}
+
+export function listRunningAvds(): RunningAvd[] {
+  return listAllDevices()
+    .filter((device) => /^emulator-\d+$/.test(device.serial))
+    .flatMap((device) => {
+      const avd = runningAvdName(device.serial);
+      return avd ? [{ serial: device.serial, avd, state: device.state }] : [];
+    });
+}
+
+function findRunningAvd(name: string): RunningAvd | null {
+  return listRunningAvds().find((running) => running.avd === name) ?? null;
+}
+
+export function stopEmulator(serial: string): void {
+  const r = adb(serial, ["emu", "kill"]);
+  if (r.status !== 0) {
+    throw new Error(`Failed to stop ${serial}: ${r.stderr || r.stdout}`);
+  }
+}
+
+async function waitForEmulatorExit(serial: string, timeoutMs = 30_000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!listAllDevices().some((device) => device.serial === serial)) return;
+    await sleep(500);
+  }
+  throw new Error(`Timed out waiting for ${serial} to stop.`);
+}
+
+async function waitForBoot(serial: string, proc: ChildProcess, timeoutMs: number): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (proc.exitCode !== null || proc.signalCode !== null) {
+      throw new Error(`emulator exited before boot completed (code ${proc.exitCode ?? "null"})`);
+    }
+
+    const state = adb(serial, ["get-state"]);
+    if (state.status === 0 && state.stdout.trim() === "device") {
+      const boot = adb(serial, ["shell", "getprop", "sys.boot_completed"]);
+      if (boot.status === 0 && boot.stdout.trim() === "1") return;
+    }
+
+    await sleep(1_000);
+  }
+
+  throw new Error(`Timed out waiting for ${serial} to boot.`);
+}
+
+export async function startEmulator(opts: StartEmulatorOpts): Promise<EmulatorLaunch> {
+  const emulator = resolveEmulator(opts.emulatorPath);
+  const name = avdName(opts.avd);
+  const avds = listAvdsWithEmulator(emulator);
+  if (!avds.includes(name)) {
+    const available = avds.length ? avds.join(", ") : "(none)";
+    throw new Error(`Unknown AVD "${name}". Available AVDs: ${available}`);
+  }
+
+  const running = findRunningAvd(name);
+  if (running) {
+    if (!opts.restartAvd) {
+      return { serial: running.serial, proc: null, ownsProcess: false, stop: () => {} };
+    }
+    stopEmulator(running.serial);
+    await waitForEmulatorExit(running.serial);
+  }
+
+  const port = opts.port ?? pickEmulatorPort();
+  validateEmulatorPort(port);
+
+  const args = [emulatorAvdArg(name), "-port", String(port)];
+
+  const proc = spawn(emulator, args, { stdio: ["ignore", "inherit", "inherit"] });
+  const spawnError = new Promise<never>((_, reject) => {
+    proc.once("error", reject);
+  });
+  const serial = `emulator-${port}`;
+  let stopped = false;
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    try {
+      adb(serial, ["emu", "kill"]);
+    } catch {}
+    try {
+      proc.kill("SIGTERM");
+    } catch {}
+  };
+
+  try {
+    await Promise.race([waitForBoot(serial, proc, opts.bootTimeoutMs ?? 120_000), spawnError]);
+    return { serial, proc, ownsProcess: true, stop };
+  } catch (err) {
+    stop();
+    throw err;
+  }
+}