Deploy emulator and stack on Ubuntu

[baryhuang]

Summary

Set up and run the OpenPocket stack (Android emulator + application) on an Ubuntu machine.

Tasks

• Install Android SDK, emulator, and platform-tools on Ubuntu
• Configure KVM acceleration for emulator performance
• Create an AVD and verify emulator boots in headless mode
• Run the OpenPocket stack end-to-end on Ubuntu
• Fix any platform-specific issues encountered (e.g. missing Linux fallback paths, macOS-gated force-kill methods)
• Document the Ubuntu setup steps

[tsubasakong]

/fix

[github-actions]

Here’s a focused analysis + fix recommendation for Ubuntu deployment. I did lightweight read‑only inspection of README.md, src/device/emulator-manager.ts, and src/environment/android-prerequisites.ts.

Probable root cause(s)

• Linux SDK/ADB discovery is inconsistent: EmulatorManager only checks ANDROID_SDK_ROOT/ANDROID_HOME, then macOS/Homebrew paths and PATH. On Ubuntu, the common default ~/Android/Sdk is not in those fallbacks, so openpocket emulator start fails unless the env var or PATH is set. See src/device/emulator-manager.ts (emulatorBinary/adbBinary) vs src/environment/android-prerequisites.ts (does include ~/Android/Sdk).
• openpocket emulator start does not run ensureAndroidPrerequisites, so the Linux SDK autodiscovery + config update path isn’t invoked unless the user runs openpocket onboard or openpocket bootstrap. See src/cli.ts.
• Process control helpers (show/hide/force‑kill) are macOS‑only; on Ubuntu these return “macOS only” or skip the force‑kill fallback, which can leave stuck emulator processes in headless mode. See src/device/emulator-manager.ts.

Likely files/modules involved

• src/device/emulator-manager.ts (SDK/ADB lookup paths, headless process management)
• src/environment/android-prerequisites.ts (Linux SDK detection is already here)
• src/cli.ts (ensureAndroidPrerequisites is not called for openpocket emulator start)
• README.md (Ubuntu instructions are high-level; missing concrete SDK install + env var guidance)

Reproduction / verification steps (Ubuntu)

1. Fresh Ubuntu with no ANDROID_SDK_ROOT and default Android SDK install to ~/Android/Sdk.
2. Run openpocket emulator list-avds or openpocket emulator start without running openpocket onboard first.
3. Observe failure: “Android emulator binary not found…” or “adb not found…”.
4. Set ANDROID_SDK_ROOT=$HOME/Android/Sdk and rerun: command succeeds. This confirms the lookup gap.

Minimal fix options (recommended first)

1. Recommended: make openpocket emulator start (and list-avds) call ensureAndroidPrerequisites before instantiating EmulatorManager.
   • Pros: reuses existing Linux SDK detection + optional auto‑install; updates config automatically.
   • Cons: adds some overhead to CLI subcommand; but can be cheap if tools are already present.
2. Add Linux fallback SDK paths in EmulatorManager to match android-prerequisites (e.g. ~/Android/Sdk).
   • Pros: quick fix for the common case.
   • Cons: still won’t handle cases where SDK is present but needs config update; duplicated logic.
3. Extend force‑kill logic to Linux (use pkill -f for emulator/qemu-system with -no-window and -avd (name) in EmulatorManager).
   • Pros: more robust headless control.
   • Cons: risk of over‑matching if users have multiple emulators; should be scoped to -avd.

Recommended approach

• Do (1) + (2): call ensureAndroidPrerequisites before EmulatorManager is used in openpocket emulator start and list-avds, and add ~/Android/Sdk to EmulatorManager fallbacks for direct usage. This is a small change with immediate Ubuntu benefits.
• Optionally add (3) if you observe stuck emulator processes during Ubuntu testing.

Tests to add/update

• Unit test for SDK discovery parity:
  • Ensure collectSdkRoot and EmulatorManager locate ~/Android/Sdk when present.
• CLI integration test (lightweight):
  • In a mocked env where ANDROID_SDK_ROOT is unset but ~/Android/Sdk exists, openpocket emulator list-avds should attempt detection via ensureAndroidPrerequisites and not fail with “binary not found”.
• If adding Linux force‑kill: test that pkill -f is only invoked when -avd (name) is present in process list.

Risk and rollback notes

• Risk: calling ensureAndroidPrerequisites in emulator start could trigger auto‑install prompts or license acceptance on first run. Mitigation: gate auto‑install by config or prompt; or only run detection (autoInstall=false) for emulator subcommands.
• Risk: broader process kill patterns could terminate unrelated emulator processes. Mitigation: match -avd (name) or require explicit config flag for force‑kill.
• Rollback: revert the CLI change to remove prereq checks; or disable Linux force‑kill path if it’s too aggressive.

Follow‑up questions to unblock

1. What Ubuntu version and kernel are you targeting (e.g., 22.04, 24.04)?
2. Are you installing SDK via Android Studio, sdkmanager, or apt?
3. What exact error(s) do you see when running openpocket emulator start on Ubuntu?

If you want, I can propose a concrete patch (no PR) once you confirm the Ubuntu setup details.

Generated by issue-fix for issue #13