androidctl 0.1.0__py3-none-any.whl

androidctl/commands/setup.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+from contextlib import AbstractContextManager, nullcontext
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NoReturn
+
+import typer
+
+from androidctl import __version__
+from androidctl.cli_options import command_cli_options
+from androidctl.exit_codes import ExitCode
+from androidctl.setup import accessibility as setup_accessibility
+from androidctl.setup import adb as setup_adb
+from androidctl.setup import pairing as setup_pairing
+from androidctl.setup import verify as setup_verify
+from androidctl.setup.apk_resource import (
+    packaged_agent_apk_name,
+    packaged_agent_apk_path,
+)
+
+
+@dataclass(frozen=True)
+class SetupError(RuntimeError):
+    code: str
+    layer: str
+    message: str
+    exit_code: ExitCode = ExitCode.ERROR
+
+    def __str__(self) -> str:
+        return self.message
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "setup",
+        help="Onboarding helper for preparing an authorized ADB device.",
+    )
+    def setup(
+        ctx: typer.Context,
+        adb: bool = typer.Option(False, "--adb", help="Use authorized ADB transport."),
+        serial: str | None = typer.Option(None, "--serial", help="ADB serial."),
+        apk: Path | None = typer.Option(
+            None,
+            "--apk",
+            help="Override Android Device Agent APK path.",
+        ),
+        dry_run: bool = typer.Option(
+            False,
+            "--dry-run",
+            help="Print the setup plan without running ADB or mutating a device.",
+        ),
+        skip_install: bool = typer.Option(
+            False,
+            "--skip-install",
+            help="Skip the APK install step.",
+        ),
+        manual_accessibility: bool = typer.Option(
+            False,
+            "--manual-accessibility",
+            help="Skip ADB Accessibility writes and guide manual enablement.",
+        ),
+        workspace_root: Path | None = typer.Option(None, "--workspace-root"),
+    ) -> None:
+        options = command_cli_options(ctx, workspace_root=workspace_root)
+        try:
+            run_setup(
+                adb=adb,
+                serial=serial,
+                apk=apk,
+                dry_run=dry_run,
+                skip_install=skip_install,
+                manual_accessibility=manual_accessibility,
+                workspace_root=options.workspace_root,
+            )
+        except SetupError as error:
+            _emit_failure(error)
+
+
+def run_setup(
+    *,
+    adb: bool,
+    serial: str | None,
+    apk: Path | None,
+    dry_run: bool,
+    skip_install: bool,
+    manual_accessibility: bool,
+    workspace_root: Path | None,
+) -> None:
+    if not adb:
+        raise SetupError(
+            code="SETUP_REQUIRES_ADB",
+            layer="usage",
+            message="setup currently requires --adb",
+            exit_code=ExitCode.USAGE,
+        )
+
+    _emit_progress("androidctl setup: authorized ADB onboarding")
+    if dry_run:
+        _emit_dry_run_plan(
+            serial=serial,
+            apk=apk,
+            skip_install=skip_install,
+            manual_accessibility=manual_accessibility,
+            workspace_root=workspace_root,
+        )
+        return
+
+    try:
+        devices = setup_adb.list_adb_devices()
+        selected_device = setup_adb.select_eligible_device(devices, serial=serial)
+    except setup_adb.SetupAdbError as error:
+        raise SetupError(
+            code=error.code,
+            layer=error.layer,
+            message=error.message,
+            exit_code=ExitCode.ENVIRONMENT,
+        ) from error
+
+    if serial is None:
+        _emit_progress("ADB: selected the only authorized device")
+    else:
+        _emit_progress("ADB: selected requested authorized device")
+
+    if skip_install:
+        _emit_progress("install: skipped by --skip-install")
+    else:
+        _emit_progress(_apk_plan_line(apk, dry_run=False))
+        _install_agent_apk(apk=apk, serial=selected_device.serial)
+
+    token = _start_setup_activity_with_token(serial=selected_device.serial)
+    _enable_accessibility(
+        serial=selected_device.serial,
+        manual_accessibility=manual_accessibility,
+    )
+    _verify_setup_readiness(
+        serial=selected_device.serial,
+        token=token,
+        workspace_root=workspace_root,
+    )
+    _emit_progress("status: setup complete")
+
+
+def _emit_dry_run_plan(
+    *,
+    serial: str | None,
+    apk: Path | None,
+    skip_install: bool,
+    manual_accessibility: bool,
+    workspace_root: Path | None,
+) -> None:
+    _emit_progress("mode: dry-run; no ADB command or device mutation will run")
+    if workspace_root is not None:
+        _emit_progress("workspace: command override provided")
+    if serial is None:
+        _emit_progress("ADB: would select the only authorized device")
+    else:
+        _emit_progress("ADB: would select the requested authorized device")
+    if skip_install:
+        _emit_progress("install: skipped by --skip-install")
+    else:
+        _emit_progress(_apk_plan_line(apk, dry_run=True))
+    _emit_progress("launch: would open AndroidCtl and start the foreground server")
+    _emit_progress("token: would provision a host-generated device token")
+    if manual_accessibility:
+        _emit_progress("accessibility: would enter manual enablement fallback")
+    else:
+        _emit_progress("accessibility: would try ADB enable, then fallback if needed")
+    _emit_progress("verify: would connect daemon runtime and run readiness checks")
+    _emit_progress("status: dry-run complete")
+
+
+def _apk_plan_line(
+    apk: Path | None,
+    *,
+    dry_run: bool,
+) -> str:
+    prefix = "would use" if dry_run else "using"
+    if apk is not None:
+        return f"install: {prefix} override APK path"
+    apk_name = packaged_agent_apk_name(__version__)
+    return f"install: {prefix} packaged APK {apk_name}"
+
+
+def _install_agent_apk(
+    *,
+    apk: Path | None,
+    serial: str,
+) -> None:
+    try:
+        with _apk_path_context(apk) as apk_path:
+            setup_adb.install_apk(apk_path, serial=serial)
+    except FileNotFoundError as error:
+        raise SetupError(
+            code="APK_NOT_FOUND",
+            layer="install",
+            message=str(error),
+        ) from error
+    except setup_adb.SetupAdbError as error:
+        raise SetupError(
+            code=error.code,
+            layer="install",
+            message=error.message,
+        ) from error
+    _emit_progress("install: APK installed")
+
+
+def _apk_path_context(apk: Path | None) -> AbstractContextManager[Path]:
+    if apk is not None:
+        return nullcontext(apk)
+    return packaged_agent_apk_path(__version__)
+
+
+def _start_setup_activity_with_token(*, serial: str) -> str:
+    try:
+        setup_adb.force_stop_app(serial=serial)
+        token = setup_pairing.generate_host_token()
+        setup_adb.start_setup_activity(
+            serial=serial,
+            string_extras={setup_pairing.SETUP_DEVICE_TOKEN_EXTRA: token},
+        )
+    except setup_pairing.SetupPairingError as error:
+        raise SetupError(
+            code=error.code,
+            layer=error.layer,
+            message=error.message,
+        ) from error
+    except setup_adb.SetupAdbError as error:
+        raise SetupError(
+            code=error.code,
+            layer="launch",
+            message=error.message,
+        ) from error
+    _emit_progress("launch: existing app process stopped")
+    _emit_progress("launch: setup activity started")
+    _emit_progress("token: provisioned host-generated device token")
+    return token
+
+
+def _enable_accessibility(
+    *,
+    serial: str,
+    manual_accessibility: bool,
+) -> None:
+    if manual_accessibility:
+        _emit_accessibility_fallback("manual enablement requested")
+        return
+    try:
+        result = setup_accessibility.enable_agent_accessibility(serial=serial)
+    except setup_accessibility.SetupAccessibilityError as error:
+        _emit_progress(
+            f"accessibility: ADB enable not confirmed ({error.code}); "
+            "using manual fallback"
+        )
+        _emit_accessibility_fallback(error.message)
+        return
+    if result.changed_service_list:
+        _emit_progress("accessibility: AndroidCtl service added via ADB settings")
+    else:
+        _emit_progress("accessibility: AndroidCtl service already in ADB settings")
+    _emit_progress("accessibility: ADB settings write confirmed")
+
+
+def _emit_accessibility_fallback(reason: str) -> None:
+    _emit_progress(f"accessibility: manual fallback required: {reason}")
+    _emit_progress(
+        f"accessibility: {setup_accessibility.MANUAL_ACCESSIBILITY_FALLBACK}"
+    )
+
+
+def _verify_setup_readiness(
+    *,
+    serial: str,
+    token: str,
+    workspace_root: Path | None,
+) -> None:
+    try:
+        setup_verify.verify_setup_readiness(
+            serial=serial,
+            token=token,
+            workspace_root=workspace_root,
+        )
+    except setup_verify.SetupVerificationError as error:
+        raise SetupError(
+            code=error.code,
+            layer=error.layer,
+            message=error.message,
+        ) from error
+    _emit_progress("verify: daemon connect/readiness check succeeded")
+
+
+def _emit_progress(message: str) -> None:
+    typer.echo(message, err=True)
+
+
+def _emit_failure(error: SetupError) -> NoReturn:
+    typer.echo(
+        f"androidctl setup failed [{error.layer}/{error.code}]: {error.message}",
+        err=True,
+    )
+    raise typer.Exit(code=int(error.exit_code))

androidctl/commands/wait.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from androidctl.cli_options import CliOptions
+from androidctl.command_payloads import build_wait_command
+from androidctl.commands import run_pipeline
+from androidctl.commands.execute import emit_usage_error
+from androidctl.commands.plumbing import build_and_run_command
+from androidctl.parsing.duration import parse_duration_ms
+from androidctl.parsing.wait import parse_wait_predicate
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("wait")
+    def wait_command(
+        ctx: typer.Context,
+        until: str = typer.Option(..., "--until", help="Predicate kind to wait for."),
+        ref: str | None = typer.Option(None, "--ref", help="Ref for gone waits."),
+        text: str | None = typer.Option(
+            None, "--text", help="Text to match for text-present waits."
+        ),
+        app_target: str | None = typer.Option(
+            None, "--app", help="Package name to match for app waits."
+        ),
+        screen_id: str | None = typer.Option(
+            None, "--screen-id", help="Override the source screen id for this wait."
+        ),
+        timeout: str = typer.Option("2000ms", "--timeout"),
+        workspace_root: Path | None = typer.Option(None, "--workspace-root"),
+    ) -> None:
+        def build_request(options: CliOptions) -> run_pipeline.CliCommandRequest:
+            try:
+                predicate = parse_wait_predicate(
+                    until,
+                    ref=ref,
+                    text=text,
+                    package_name=app_target,
+                    source_screen_id=screen_id,
+                )
+                timeout_ms = parse_duration_ms(timeout)
+            except ValueError as error:
+                emit_usage_error(str(error))
+
+            return run_pipeline.CliCommandRequest(
+                public_command="wait",
+                command=build_wait_command(
+                    predicate=predicate,
+                    timeout_ms=timeout_ms,
+                ),
+                workspace_root=options.workspace_root,
+            )
+
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=build_request,
+        )

androidctl/daemon/__init__.py

@@ -0,0 +1 @@
+"""Daemon discovery/startup/client helpers."""

androidctl/daemon/client.py

@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+import json
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from androidctl import __version__ as ANDROIDCTL_VERSION
+from androidctl_contracts.command_catalog import (
+    entry_for_daemon_kind,
+    runtime_close_entry,
+)
+from androidctl_contracts.command_results import (
+    CommandResultCore,
+    ListAppsResult,
+    RetainedResultEnvelope,
+)
+from androidctl_contracts.daemon_api import (
+    OWNER_HEADER_NAME,
+    TOKEN_HEADER_NAME,
+    CommandRunRequest,
+    DaemonErrorEnvelope,
+    HealthResult,
+    RuntimeGetResult,
+    RuntimePayload,
+    WaitCommandPayload,
+)
+from androidctl_contracts.user_state import ActiveDaemonRecord
+from androidctl_contracts.vocabulary import PublicResultFamily
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+CommandResultPayload = CommandResultCore | RetainedResultEnvelope | ListAppsResult
+
+_DEFAULT_DAEMON_TIMEOUT_SECONDS = 5.0
+_LONG_REQUEST_READ_TIMEOUT_GRACE_SECONDS = 2.0
+
+
+class DaemonProtocolError(RuntimeError):
+    pass
+
+
+class IncompatibleDaemonError(DaemonProtocolError):
+    pass
+
+
+class IncompatibleDaemonVersionError(IncompatibleDaemonError):
+    def __init__(self, *, expected_version: str, actual_version: str) -> None:
+        super().__init__(
+            "androidctl/androidctld release version mismatch: "
+            f"cli={expected_version} daemon={actual_version}"
+        )
+        self.expected_version = expected_version
+        self.actual_version = actual_version
+
+
+class DaemonApiError(RuntimeError):
+    def __init__(
+        self,
+        *,
+        code: str = "DAEMON_API_ERROR",
+        message: str = "daemon request failed",
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+
+class DaemonClient:
+    def __init__(
+        self,
+        http_client: httpx.Client,
+        *,
+        owner_id: str | None = None,
+        token: str | None = None,
+    ) -> None:
+        self._http = http_client
+        self._owner_id = owner_id
+        self._token = token
+
+    @classmethod
+    def from_active_record(
+        cls,
+        record: ActiveDaemonRecord,
+        *,
+        owner_id: str,
+        http_client: httpx.Client | None = None,
+    ) -> DaemonClient:
+        base_url = f"http://{record.host}:{record.port}"
+        return cls(
+            http_client or httpx.Client(base_url=base_url, trust_env=False),
+            owner_id=owner_id,
+            token=record.token,
+        )
+
+    def health(self, record: ActiveDaemonRecord | None = None) -> HealthResult:
+        result = self._post_json(
+            "/health",
+            payload={},
+            token=self._resolve_token(record),
+        )
+        try:
+            health = HealthResult.model_validate(result)
+        except ValidationError as error:
+            if _is_legacy_health_schema_failure(error):
+                raise IncompatibleDaemonError(
+                    "androidctl/androidctld health payload is incompatible; "
+                    "install matching androidctl and androidctld versions"
+                ) from error
+            raise DaemonProtocolError("invalid health response schema") from error
+
+        if health.service != "androidctld":
+            raise DaemonProtocolError(
+                f"incompatible daemon service: {health.service!r}"
+            )
+        if record is not None:
+            if health.workspace_root != record.workspace_root:
+                raise DaemonProtocolError("health response workspace root mismatch")
+            if health.owner_id != record.owner_id:
+                raise DaemonProtocolError("health response owner id mismatch")
+        if health.version != ANDROIDCTL_VERSION:
+            raise IncompatibleDaemonVersionError(
+                expected_version=ANDROIDCTL_VERSION,
+                actual_version=health.version,
+            )
+        return health
+
+    def get_runtime(
+        self,
+        record: ActiveDaemonRecord | None = None,
+    ) -> RuntimePayload:
+        result = self._post_json(
+            "/runtime/get",
+            payload={},
+            token=self._resolve_token(record),
+        )
+        return _validate_model(
+            RuntimeGetResult,
+            result,
+            message="invalid runtime/get response schema",
+        ).runtime
+
+    def close_runtime(
+        self,
+        record: ActiveDaemonRecord | None = None,
+    ) -> RetainedResultEnvelope:
+        result = self._post_json(
+            "/runtime/close",
+            payload={},
+            token=self._resolve_token(record),
+        )
+        entry = runtime_close_entry()
+        close_result = _validate_model(
+            RetainedResultEnvelope,
+            result,
+            message="invalid runtime/close response schema",
+        )
+        _assert_result_command(close_result, entry.result_command)
+        return close_result
+
+    def run_command(
+        self,
+        *,
+        request: CommandRunRequest,
+        record: ActiveDaemonRecord | None = None,
+    ) -> CommandResultPayload:
+        result = self._post_json(
+            "/commands/run",
+            payload=request.model_dump(exclude_none=True, exclude_defaults=True),
+            token=self._resolve_token(record),
+            timeout=_command_request_timeout(request),
+        )
+        entry = entry_for_daemon_kind(request.command.kind)
+        if entry is None:
+            raise DaemonProtocolError(
+                f"unknown command catalog entry for kind={request.command.kind!r}"
+            )
+        if entry.result_family is PublicResultFamily.SEMANTIC:
+            command_result: CommandResultPayload = _validate_model(
+                CommandResultCore,
+                result,
+                message="invalid commands/run response schema",
+            )
+        elif entry.result_family is PublicResultFamily.RETAINED:
+            command_result = _validate_model(
+                RetainedResultEnvelope,
+                result,
+                message="invalid commands/run response schema",
+            )
+        elif entry.result_family is PublicResultFamily.LIST_APPS:
+            command_result = _validate_model(
+                ListAppsResult,
+                result,
+                message="invalid commands/run response schema",
+            )
+        else:
+            raise DaemonProtocolError(
+                f"unsupported result family {entry.result_family!r}"
+            )
+        _assert_result_command(command_result, entry.result_command)
+        return command_result
+
+    def _resolve_token(self, record: ActiveDaemonRecord | None) -> str:
+        if record is not None:
+            return record.token
+        if self._token:
+            return self._token
+        raise DaemonProtocolError("daemon token is not configured")
+
+    def _post_json(
+        self,
+        path: str,
+        *,
+        payload: dict[str, Any],
+        token: str,
+        timeout: httpx.Timeout | None = None,
+    ) -> dict[str, Any]:
+        headers = {TOKEN_HEADER_NAME: token}
+        if self._owner_id is not None:
+            headers[OWNER_HEADER_NAME] = self._owner_id
+        response = self._http.post(
+            path,
+            headers=headers,
+            json=payload,
+            timeout=timeout or _default_request_timeout(),
+        )
+        envelope: dict[str, Any] | None = None
+        envelope_error: DaemonProtocolError | None = None
+        try:
+            envelope = self._parse_json_envelope(response)
+        except DaemonProtocolError as error:
+            envelope_error = error
+
+        if envelope is None:
+            response.raise_for_status()
+            if envelope_error is None:
+                raise DaemonProtocolError("invalid daemon response envelope")
+            raise envelope_error
+
+        ok = envelope.get("ok")
+        if ok is False:
+            typed_error = _validate_model(
+                DaemonErrorEnvelope,
+                envelope,
+                message="invalid daemon error envelope",
+            ).error
+            raise DaemonApiError(
+                code=typed_error.code.value,
+                message=typed_error.message,
+                details=dict(typed_error.details),
+            )
+        if response.is_error:
+            response.raise_for_status()
+        if ok is not True:
+            raise DaemonProtocolError("daemon success envelope missing ok=true")
+
+        result = envelope.get("result")
+        if not isinstance(result, dict):
+            raise DaemonProtocolError("daemon response missing 'result' payload")
+        return result
+
+    def _parse_json_envelope(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except json.JSONDecodeError as error:
+            raise DaemonProtocolError("daemon response is not valid JSON") from error
+        if not isinstance(payload, dict):
+            raise DaemonProtocolError("daemon response is not a JSON object")
+        return payload
+
+
+def try_get_healthy_daemon(
+    client: DaemonClient,
+    record: ActiveDaemonRecord,
+) -> HealthResult | None:
+    try:
+        return client.health(record)
+    except (DaemonApiError, httpx.RequestError, httpx.HTTPStatusError):
+        return None
+
+
+def _command_request_timeout(request: CommandRunRequest) -> httpx.Timeout:
+    return _timeout_with_read_budget(_command_read_budget_ms(request))
+
+
+def _command_read_budget_ms(request: CommandRunRequest) -> int | None:
+    if not isinstance(request.command, WaitCommandPayload):
+        return None
+    return _optional_non_negative_int(request.command.timeout_ms)
+
+
+def _timeout_with_read_budget(read_budget_ms: int | None) -> httpx.Timeout:
+    read_timeout = _DEFAULT_DAEMON_TIMEOUT_SECONDS
+    if read_budget_ms is not None:
+        read_timeout = max(
+            _DEFAULT_DAEMON_TIMEOUT_SECONDS,
+            (read_budget_ms / 1000.0) + _LONG_REQUEST_READ_TIMEOUT_GRACE_SECONDS,
+        )
+    return httpx.Timeout(
+        connect=_DEFAULT_DAEMON_TIMEOUT_SECONDS,
+        read=read_timeout,
+        write=_DEFAULT_DAEMON_TIMEOUT_SECONDS,
+        pool=_DEFAULT_DAEMON_TIMEOUT_SECONDS,
+    )
+
+
+def _default_request_timeout() -> httpx.Timeout:
+    return _timeout_with_read_budget(None)
+
+
+def _optional_non_negative_int(value: object) -> int | None:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        return None
+    return value
+
+
+def _validate_model(
+    model_type: type[ModelT],
+    payload: object,
+    *,
+    message: str,
+) -> ModelT:
+    try:
+        return model_type.model_validate(payload)
+    except ValidationError as error:
+        raise DaemonProtocolError(message) from error
+
+
+def _assert_result_command(
+    result: CommandResultPayload,
+    expected_command: str,
+) -> None:
+    if result.command != expected_command:
+        raise DaemonProtocolError(
+            "daemon result command mismatch: "
+            f"expected {expected_command!r}, got {result.command!r}"
+        )
+
+
+def _is_legacy_health_schema_failure(error: ValidationError) -> bool:
+    errors = error.errors()
+    if len(errors) != 1:
+        return False
+    first_error = errors[0]
+    location = first_error.get("loc")
+    return first_error.get("type") == "extra_forbidden" and location == ("apiVersion",)