android-emu-agent 0.1.3__py3-none-any.whl

android_emu_agent/artifacts/manager.py

@@ -0,0 +1,125 @@
+"""Artifact manager - Screenshots, logs, and debug bundles."""
+
+from __future__ import annotations
+
+import asyncio
+import zipfile
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import structlog
+
+if TYPE_CHECKING:
+    import uiautomator2 as u2
+
+logger = structlog.get_logger()
+
+
+class ArtifactManager:
+    """Manages artifact capture and storage."""
+
+    def __init__(self, output_dir: Path | None = None) -> None:
+        default_dir = Path.home() / ".android-agent" / "artifacts"
+        self.output_dir = output_dir or default_dir
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    async def screenshot(
+        self,
+        device: u2.Device,
+        session_id: str,
+        filename: str | None = None,
+    ) -> Path:
+        """Capture a screenshot from device."""
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"{session_id}_{timestamp}.png"
+
+        output_path = self.output_dir / filename
+
+        # uiautomator2 returns PIL Image
+        image = await asyncio.to_thread(device.screenshot)
+        if image is None:
+            raise RuntimeError("Failed to capture screenshot from device")
+        await asyncio.to_thread(image.save, str(output_path))
+
+        logger.info("screenshot_captured", path=str(output_path))
+        return output_path
+
+    async def pull_logs(
+        self,
+        device: u2.Device,
+        session_id: str,
+        since: str | None = None,
+        filename: str | None = None,
+    ) -> Path:
+        """Pull logcat logs from device."""
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"{session_id}_{timestamp}_logcat.txt"
+
+        output_path = self.output_dir / filename
+
+        def _pull() -> str:
+            cmd = "logcat -d"
+            if since:
+                cmd += f" -t '{since}'"
+            result = device.shell(cmd)
+            output = getattr(result, "output", None)
+            return output if isinstance(output, str) else str(result)
+
+        logs = await asyncio.to_thread(_pull)
+        output_path.write_text(logs)
+
+        logger.info("logs_pulled", path=str(output_path), size=len(logs))
+        return output_path
+
+    async def save_snapshot(
+        self,
+        snapshot_json: str,
+        session_id: str,
+        generation: int,
+    ) -> Path:
+        """Save a snapshot to disk."""
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename = f"{session_id}_gen{generation}_{timestamp}.json"
+        output_path = self.output_dir / filename
+
+        output_path.write_text(snapshot_json)
+        logger.info("snapshot_saved", path=str(output_path))
+        return output_path
+
+    async def create_debug_bundle(
+        self,
+        device: u2.Device,
+        session_id: str,
+        snapshot_json: str | None = None,
+    ) -> Path:
+        """Create a debug bundle with screenshot, logs, and snapshot."""
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        bundle_name = f"{session_id}_{timestamp}_debug.zip"
+        bundle_path = self.output_dir / bundle_name
+
+        # Collect artifacts
+        screenshot_path = await self.screenshot(device, session_id)
+        logs_path = await self.pull_logs(device, session_id)
+
+        # Create zip bundle
+        def _create_zip() -> None:
+            with zipfile.ZipFile(bundle_path, "w", zipfile.ZIP_DEFLATED) as zf:
+                zf.write(screenshot_path, screenshot_path.name)
+                zf.write(logs_path, logs_path.name)
+                if snapshot_json:
+                    zf.writestr("snapshot.json", snapshot_json)
+                # Add metadata
+                metadata = f"session_id: {session_id}\ntimestamp: {timestamp}\n"
+                zf.writestr("metadata.txt", metadata)
+
+        await asyncio.to_thread(_create_zip)
+
+        # Cleanup temp files
+        screenshot_path.unlink(missing_ok=True)
+        logs_path.unlink(missing_ok=True)
+
+        logger.info("debug_bundle_created", path=str(bundle_path))
+        return bundle_path

android_emu_agent/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI - Thin client that communicates with the daemon."""

android_emu_agent/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command groups."""

android_emu_agent/cli/commands/action.py

@@ -0,0 +1,158 @@
+"""Action execution CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient
+from android_emu_agent.cli.utils import handle_response
+
+app = typer.Typer(help="Action execution commands")
+
+
+@app.command("tap")
+def action_tap(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    ref: str = typer.Argument(..., help="Element ref (@a1)"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Tap an element."""
+    client = DaemonClient()
+    resp = client.request("POST", "/actions/tap", json_body={"session_id": session_id, "ref": ref})
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("long-tap")
+def action_long_tap(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    ref: str = typer.Argument(..., help="Element ref (@a1)"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Long tap an element."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST", "/actions/long_tap", json_body={"session_id": session_id, "ref": ref}
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("set-text")
+def action_set_text(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    ref: str = typer.Argument(..., help="Element ref (@a1)"),
+    text: str = typer.Argument(..., help="Text to set"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Set text on an element."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/actions/set_text",
+        json_body={"session_id": session_id, "ref": ref, "text": text},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("clear")
+def action_clear(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    ref: str = typer.Argument(..., help="Element ref (@a1)"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Clear text."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST", "/actions/clear", json_body={"session_id": session_id, "ref": ref}
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("back")
+def action_back(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Press back."""
+    client = DaemonClient()
+    resp = client.request("POST", "/actions/back", json_body={"session_id": session_id})
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("home")
+def action_home(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Press home."""
+    client = DaemonClient()
+    resp = client.request("POST", "/actions/home", json_body={"session_id": session_id})
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("recents")
+def action_recents(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Press recents."""
+    client = DaemonClient()
+    resp = client.request("POST", "/actions/recents", json_body={"session_id": session_id})
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("swipe")
+def action_swipe(
+    direction: str = typer.Argument(..., help="Direction: up, down, left, right"),
+    session: str = typer.Option(..., "--session", "-s", help="Session ID"),
+    container: str | None = typer.Option(None, "--in", help="Container @ref or selector"),
+    distance: float = typer.Option(0.8, "--distance", "-d", help="Swipe distance (0.0-1.0)"),
+    duration: int = typer.Option(300, "--duration", help="Swipe duration in ms"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Perform swipe gesture."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/actions/swipe",
+        json_body={
+            "session_id": session,
+            "direction": direction,
+            "container": container,
+            "distance": distance,
+            "duration_ms": duration,
+        },
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("scroll")
+def action_scroll(
+    direction: str = typer.Argument(..., help="Direction: up, down, left, right"),
+    session: str = typer.Option(..., "--session", "-s", help="Session ID"),
+    container: str | None = typer.Option(None, "--in", help="Container @ref or selector"),
+    distance: float = typer.Option(0.8, "--distance", "-d", help="Scroll distance (0.0-1.0)"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Scroll in a direction (alias for swipe)."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/actions/swipe",
+        json_body={
+            "session_id": session,
+            "direction": direction,
+            "container": container,
+            "distance": distance,
+            "duration_ms": 300,
+        },
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)

android_emu_agent/cli/commands/app_cmd.py

@@ -0,0 +1,95 @@
+"""App management CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient
+from android_emu_agent.cli.utils import handle_output_response, handle_response, require_target
+
+app = typer.Typer(help="App management commands")
+
+
+@app.command("reset")
+def app_reset(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    package: str = typer.Argument(..., help="Package name"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Clear app data for a package."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/app/reset",
+        json_body={"session_id": session_id, "package": package},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("launch")
+def app_launch(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    package: str = typer.Argument(..., help="Package name"),
+    activity: str | None = typer.Option(None, "--activity", "-a", help="Activity name"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Launch an app."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/app/launch",
+        json_body={"session_id": session_id, "package": package, "activity": activity},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("force-stop")
+def app_force_stop(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    package: str = typer.Argument(..., help="Package name"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Force stop an app."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/app/force_stop",
+        json_body={"session_id": session_id, "package": package},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("deeplink")
+def app_deeplink(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    uri: str = typer.Argument(..., help="URI to open"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Open a deeplink URI."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/app/deeplink",
+        json_body={"session_id": session_id, "uri": uri},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("list")
+def app_list(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    scope: str = typer.Option("all", "--scope", help="all|system|third-party"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """List installed packages."""
+    payload = require_target(device, session_id)
+    payload.update({"scope": scope})
+    client = DaemonClient()
+    resp = client.request("POST", "/app/list", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)

android_emu_agent/cli/commands/artifact.py

@@ -0,0 +1,81 @@
+"""Artifact and debugging CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient
+from android_emu_agent.cli.utils import (
+    handle_response,
+    handle_response_with_pull,
+    require_target,
+    resolve_session_id,
+)
+
+app = typer.Typer(help="Artifact and debugging commands")
+
+
+@app.command("save-snapshot")
+def artifact_save_snapshot(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Save the last snapshot to disk."""
+    client = DaemonClient()
+    resp = client.request("POST", "/artifacts/save_snapshot", json_body={"session_id": session_id})
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("screenshot")
+def artifact_screenshot(
+    session_id: str | None = typer.Argument(None, help="Session ID"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    pull: bool = typer.Option(False, "--pull", help="Copy screenshot to local path"),
+    output: str | None = typer.Option(
+        None, "--output", "-o", help="Output path (file or directory)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Capture a screenshot artifact."""
+    try:
+        resolved_session = resolve_session_id(session_id, session)
+    except typer.BadParameter as exc:
+        typer.echo(f"Error: {exc}")
+        raise typer.Exit(code=1) from None
+
+    payload = require_target(device, resolved_session)
+    client = DaemonClient()
+    resp = client.request("POST", "/ui/screenshot", json_body=payload)
+    client.close()
+    handle_response_with_pull(resp, json_output=json_output, pull=pull, output=output)
+
+
+@app.command("logs")
+def artifact_logs(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    since: str | None = typer.Option(None, "--since", help="Logcat since timestamp"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Pull logcat logs."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/artifacts/logs",
+        json_body={"session_id": session_id, "since": since},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("bundle")
+def artifact_bundle(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Create a debug bundle."""
+    client = DaemonClient()
+    resp = client.request("POST", "/artifacts/debug_bundle", json_body={"session_id": session_id})
+    client.close()
+    handle_response(resp, json_output=json_output)

android_emu_agent/cli/commands/daemon.py

@@ -0,0 +1,62 @@
+"""Daemon lifecycle CLI commands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient, DaemonController, format_json
+
+app = typer.Typer(help="Daemon lifecycle commands")
+
+
+@app.command("start")
+def daemon_start() -> None:
+    """Start the daemon process."""
+    controller = DaemonController()
+    status = controller.status()
+    if status["pid_running"]:
+        typer.echo(f"Daemon already running (pid {status['pid']})")
+        return
+    if controller.health():
+        typer.echo("Daemon already running (pid unknown)")
+        return
+    pid = controller.start()
+    if pid == -1:
+        typer.echo("Daemon already running (pid unknown)")
+        return
+    typer.echo(f"Daemon started (pid {pid})")
+
+
+@app.command("stop")
+def daemon_stop() -> None:
+    """Stop the daemon process."""
+    controller = DaemonController()
+    stopped = controller.stop()
+    if stopped:
+        typer.echo("Daemon stopped")
+    else:
+        typer.echo("Daemon not running")
+
+
+@app.command("status")
+def daemon_status(json_output: bool = typer.Option(False, "--json", help="Output JSON")) -> None:
+    """Show daemon status."""
+    controller = DaemonController()
+    status = controller.status()
+
+    health: dict[str, Any] | None = None
+    try:
+        client = DaemonClient(auto_start=False)
+        resp = client.request("GET", "/health")
+        health = resp.json()
+        client.close()
+    except Exception:
+        health = None
+
+    status["health"] = health
+    if json_output:
+        typer.echo(format_json(status))
+    else:
+        typer.echo(format_json(status))

android_emu_agent/cli/commands/device.py

@@ -0,0 +1,122 @@
+"""Device management CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient, format_json
+from android_emu_agent.cli.utils import handle_response
+
+app = typer.Typer(help="Device management commands")
+device_set_app = typer.Typer(help="Determinism controls")
+app.add_typer(device_set_app, name="set")
+
+
+@app.command("list")
+def device_list(json_output: bool = typer.Option(False, "--json", help="Output JSON")) -> None:
+    """List connected devices."""
+    client = DaemonClient()
+    resp = client.request("GET", "/devices")
+    client.close()
+
+    data = resp.json()
+    if json_output:
+        typer.echo(format_json(data))
+        return
+
+    for device in data.get("devices", []):
+        typer.echo(
+            f"{device['serial']}  model={device['model']} sdk={device['sdk_version']} "
+            f"root={device['is_rooted']} emulator={device['is_emulator']}"
+        )
+
+
+@device_set_app.command("animations")
+def device_set_animations(
+    state: str = typer.Argument(..., help="on|off"),
+    device: str = typer.Option(..., "--device", "-d", help="Device serial"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Enable or disable system animations."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST", "/devices/animations", json_body={"serial": device, "state": state}
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@device_set_app.command("stay_awake")
+def device_set_stay_awake(
+    state: str = typer.Argument(..., help="on|off"),
+    device: str = typer.Option(..., "--device", "-d", help="Device serial"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Enable or disable stay-awake."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST", "/devices/stay_awake", json_body={"serial": device, "state": state}
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@device_set_app.command("rotation")
+def device_set_rotation(
+    orientation: str = typer.Argument(
+        ..., help="portrait|landscape|reverse-portrait|reverse-landscape|auto"
+    ),
+    device: str = typer.Option(..., "--device", "-d", help="Device serial"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Set screen rotation."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST", "/devices/rotation", json_body={"serial": device, "orientation": orientation}
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@device_set_app.command("wifi")
+def device_set_wifi(
+    state: str = typer.Argument(..., help="on|off"),
+    device: str = typer.Option(..., "--device", "-d", help="Device serial"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Enable or disable WiFi."""
+    client = DaemonClient()
+    enabled = state.lower() == "on"
+    resp = client.request("POST", "/devices/wifi", json_body={"serial": device, "enabled": enabled})
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@device_set_app.command("mobile")
+def device_set_mobile(
+    state: str = typer.Argument(..., help="on|off"),
+    device: str = typer.Option(..., "--device", "-d", help="Device serial"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Enable or disable mobile data."""
+    client = DaemonClient()
+    enabled = state.lower() == "on"
+    resp = client.request(
+        "POST", "/devices/mobile", json_body={"serial": device, "enabled": enabled}
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@device_set_app.command("doze")
+def device_set_doze(
+    state: str = typer.Argument(..., help="on|off"),
+    device: str = typer.Option(..., "--device", "-d", help="Device serial"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Force device into or out of doze mode."""
+    client = DaemonClient()
+    enabled = state.lower() == "on"
+    resp = client.request("POST", "/devices/doze", json_body={"serial": device, "enabled": enabled})
+    client.close()
+    handle_response(resp, json_output=json_output)