androidctl 0.1.0__py3-none-any.whl

androidctld/commands/handlers/list_apps.py

@@ -0,0 +1,215 @@
+"""Thin list-apps command handler backed by wrapper-backed apps.list RPC."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, NoReturn, Protocol
+
+from androidctl_contracts.command_results import ListAppsResult
+from androidctld.commands.command_models import ListAppsCommand
+from androidctld.device.bootstrap import DeviceBootstrapper
+from androidctld.device.rpc import DeviceRpcClient
+from androidctld.device.types import DeviceEndpoint
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.runtime import RuntimeKernel, RuntimeLifecycleLease
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime_policy import DEVICE_RPC_REQUEST_ID_LIST_APPS
+
+ANDROID_APPS_LIST_METHOD = "apps.list"
+
+
+class ListAppsRpcClient(Protocol):
+    def call_result_payload(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        request_id: str,
+    ) -> object: ...
+
+
+ListAppsRpcClientFactory = Callable[[DeviceEndpoint, str], ListAppsRpcClient]
+
+
+class ListAppsCommandHandler:
+    def __init__(
+        self,
+        *,
+        runtime_kernel: RuntimeKernel,
+        bootstrapper: DeviceBootstrapper,
+        rpc_client_factory: ListAppsRpcClientFactory | None = None,
+    ) -> None:
+        self._runtime_kernel = runtime_kernel
+        self._bootstrapper = bootstrapper
+        self._rpc_client_factory = rpc_client_factory or DeviceRpcClient
+
+    def handle(
+        self,
+        *,
+        command: ListAppsCommand,
+    ) -> dict[str, object]:
+        del command
+        runtime = self._runtime_kernel.ensure_runtime()
+        query_lane_acquired = False
+        try:
+            lifecycle_lease = self._runtime_kernel.capture_lifecycle_lease(runtime)
+            self._runtime_kernel.acquire_query_lane(runtime)
+            query_lane_acquired = True
+            client = self._client_without_readiness(
+                runtime,
+                lifecycle_lease=lifecycle_lease,
+            )
+            payload = client.call_result_payload(
+                ANDROID_APPS_LIST_METHOD,
+                {},
+                request_id=DEVICE_RPC_REQUEST_ID_LIST_APPS,
+            )
+            result = build_list_apps_result(payload)
+            _raise_runtime_not_connected_if_stale(runtime, lifecycle_lease)
+            return result.model_dump(by_alias=True, mode="json")
+        finally:
+            if query_lane_acquired:
+                self._runtime_kernel.release_progress_lane(runtime)
+
+    def _client_without_readiness(
+        self,
+        runtime: WorkspaceRuntime,
+        *,
+        lifecycle_lease: RuntimeLifecycleLease,
+    ) -> ListAppsRpcClient:
+        with runtime.lock:
+            if not lifecycle_lease.is_current(runtime):
+                raise _runtime_not_connected_error(runtime)
+            if runtime.connection is None:
+                raise _runtime_not_connected_error(runtime)
+            token = _require_device_token(runtime)
+            if runtime.transport is not None:
+                endpoint = runtime.transport.endpoint
+                return self._rpc_client_factory(endpoint, token)
+
+        rebuilt_transport = self._runtime_kernel.rebootstrap_transport(
+            runtime,
+            bootstrap=self._bootstrapper.bootstrap_rpc_only,
+            lease=lifecycle_lease,
+        )
+
+        with runtime.lock:
+            if not lifecycle_lease.is_current(runtime):
+                raise _runtime_not_connected_error(runtime)
+            transport = runtime.transport or rebuilt_transport
+            token = _require_device_token(runtime)
+            return self._rpc_client_factory(
+                transport.endpoint,
+                token,
+            )
+
+
+def build_list_apps_result(payload: object) -> ListAppsResult:
+    if not isinstance(payload, dict):
+        _raise_malformed_payload("result")
+    raw_apps = payload.get("apps", _MISSING)
+    if not isinstance(raw_apps, list):
+        _raise_malformed_payload("result.apps")
+
+    apps: list[dict[str, str]] = []
+    for index, raw_app in enumerate(raw_apps):
+        field_prefix = f"result.apps[{index}]"
+        if not isinstance(raw_app, dict):
+            _raise_malformed_payload(field_prefix)
+        package_name = _required_non_empty_string(
+            raw_app.get("packageName", _MISSING),
+            field=f"{field_prefix}.packageName",
+        )
+        app_label = _required_non_empty_string(
+            raw_app.get("appLabel", _MISSING),
+            field=f"{field_prefix}.appLabel",
+        )
+        if raw_app.get("launchable", _MISSING) is not True:
+            _raise_malformed_payload(f"{field_prefix}.launchable")
+        apps.append({"packageName": package_name, "appLabel": app_label})
+
+    try:
+        return ListAppsResult.model_validate(
+            {"ok": True, "command": "list-apps", "apps": apps},
+            strict=True,
+        )
+    except ValueError as error:
+        raise _malformed_payload_error("result") from error
+
+
+def _required_non_empty_string(value: object, *, field: str) -> str:
+    if type(value) is not str:
+        _raise_malformed_payload(field)
+    normalized = value.strip()
+    if not normalized:
+        _raise_malformed_payload(field)
+    return normalized
+
+
+def _raise_runtime_not_connected_if_stale(
+    runtime: WorkspaceRuntime,
+    lifecycle_lease: RuntimeLifecycleLease,
+) -> None:
+    with runtime.lock:
+        if lifecycle_lease.is_current(runtime):
+            return
+    raise _runtime_not_connected_error(
+        runtime,
+        details={"reason": "runtime_lifecycle_changed"},
+    )
+
+
+def _require_device_token(runtime: WorkspaceRuntime) -> str:
+    token = runtime.device_token
+    if not token:
+        raise _runtime_not_connected_error(runtime)
+    return token
+
+
+def _runtime_not_connected_error(
+    runtime: WorkspaceRuntime,
+    *,
+    details: dict[str, object] | None = None,
+) -> DaemonError:
+    error_details: dict[str, object] = {
+        "workspaceRoot": runtime.workspace_root.as_posix()
+    }
+    if details is not None:
+        error_details.update(details)
+    return DaemonError(
+        code=DaemonErrorCode.RUNTIME_NOT_CONNECTED,
+        message="runtime is not connected to a device",
+        retryable=False,
+        details=error_details,
+        http_status=200,
+    )
+
+
+def _raise_malformed_payload(field: str) -> NoReturn:
+    raise _malformed_payload_error(field)
+
+
+def _malformed_payload_error(field: str) -> DaemonError:
+    return DaemonError(
+        code=DaemonErrorCode.DEVICE_RPC_FAILED,
+        message="apps.list returned malformed payload",
+        retryable=False,
+        details={"field": field, "reason": "invalid_payload"},
+        http_status=200,
+    )
+
+
+class _Missing:
+    pass
+
+
+_MISSING = _Missing()
+
+
+__all__ = [
+    "ANDROID_APPS_LIST_METHOD",
+    "ListAppsCommandHandler",
+    "ListAppsRpcClient",
+    "ListAppsRpcClientFactory",
+    "build_list_apps_result",
+]

androidctld/commands/handlers/observe.py

@@ -0,0 +1,121 @@
+"""Semantic observe command handler."""
+
+from __future__ import annotations
+
+from androidctl_contracts.vocabulary import SemanticResultCode
+from androidctld.commands.command_models import ObserveCommand
+from androidctld.commands.result_models import (
+    build_semantic_failure_result,
+    build_semantic_success_result,
+)
+from androidctld.commands.semantic_error_mapping import (
+    map_daemon_error_to_semantic_failure,
+)
+from androidctld.commands.semantic_truth import resolve_screen_continuity
+from androidctld.errors import DaemonError
+from androidctld.runtime import RuntimeKernel
+from androidctld.runtime.screen_state import (
+    current_compiled_screen,
+    get_authoritative_current_basis,
+)
+from androidctld.snapshots.refresh import ScreenRefreshService
+from androidctld.snapshots.service import SnapshotService
+
+
+class ObserveCommandHandler:
+    def __init__(
+        self,
+        *,
+        runtime_kernel: RuntimeKernel,
+        snapshot_service: SnapshotService,
+        screen_refresh: ScreenRefreshService,
+    ) -> None:
+        self._runtime_kernel = runtime_kernel
+        self._snapshot_service = snapshot_service
+        self._screen_refresh = screen_refresh
+
+    def handle(
+        self,
+        *,
+        command: ObserveCommand,
+    ) -> dict[str, object]:
+        runtime = self._runtime_kernel.ensure_runtime()
+        source_basis = get_authoritative_current_basis(runtime)
+        if runtime.connection is None or runtime.device_token is None:
+            return build_semantic_failure_result(
+                command="observe",
+                category="observe",
+                code=SemanticResultCode.DEVICE_UNAVAILABLE,
+                message="No current device observation is available.",
+                source_screen_id=None,
+                current_screen=(
+                    None if source_basis is None else source_basis.public_screen
+                ),
+                artifacts=None if source_basis is None else source_basis.artifacts,
+            ).model_dump(by_alias=True, mode="json")
+        lifecycle_lease = self._runtime_kernel.capture_lifecycle_lease(runtime)
+        force_refresh = source_basis is None
+        self._runtime_kernel.acquire_progress_lane(
+            runtime,
+            occupant_kind=command.kind.value,
+        )
+        try:
+            snapshot = self._snapshot_service.fetch(
+                runtime,
+                force_refresh=force_refresh,
+                lifecycle_lease=lifecycle_lease,
+            )
+            previous_screen = (
+                None if source_basis is None else source_basis.public_screen
+            )
+            previous_compiled = (
+                None if source_basis is None else source_basis.compiled_screen
+            )
+            snapshot, public_screen, artifacts = self._screen_refresh.refresh(
+                runtime,
+                snapshot,
+                lifecycle_lease=lifecycle_lease,
+                command_kind=command.kind,
+            )
+            source_screen_id = (
+                None if previous_screen is None else previous_screen.screen_id
+            )
+            continuity = resolve_screen_continuity(
+                source_screen_id=source_screen_id,
+                source_compiled_screen=previous_compiled,
+                current_screen=public_screen,
+                candidate_compiled_screen=current_compiled_screen(
+                    runtime,
+                    copy_value=False,
+                ),
+            )
+            return build_semantic_success_result(
+                command="observe",
+                category="observe",
+                source_screen_id=source_screen_id,
+                next_screen=public_screen,
+                artifacts=artifacts,
+                continuity_status=continuity.continuity_status,
+                execution_outcome="notApplicable",
+                changed=continuity.changed,
+            ).model_dump(by_alias=True, mode="json")
+        except DaemonError as error:
+            mapped = map_daemon_error_to_semantic_failure(
+                command_name="observe",
+                error=error,
+            )
+            if mapped is None:
+                raise
+            return build_semantic_failure_result(
+                command="observe",
+                category="observe",
+                code=mapped.code,
+                message=mapped.message,
+                source_screen_id=None,
+                current_screen=(
+                    None if source_basis is None else source_basis.public_screen
+                ),
+                artifacts=None if source_basis is None else source_basis.artifacts,
+            ).model_dump(by_alias=True, mode="json")
+        finally:
+            self._runtime_kernel.release_progress_lane(runtime)

androidctld/commands/handlers/screenshot.py

@@ -0,0 +1,105 @@
+"""Thin screenshot command handler."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+
+from androidctld.actions.capabilities import ensure_command_supported
+from androidctld.artifacts.writer import ArtifactWriter
+from androidctld.commands.command_models import ScreenshotCommand
+from androidctld.commands.result_models import (
+    build_projected_retained_failure_result_for_error,
+    build_retained_success_result,
+)
+from androidctld.device.interfaces import DeviceClientFactory
+from androidctld.device.parsing import (
+    decode_screenshot_body_base64,
+    validate_screenshot_png_bytes,
+)
+from androidctld.errors import DaemonError
+from androidctld.runtime import RuntimeKernel
+from androidctld.runtime_policy import DEVICE_RPC_REQUEST_ID_SCREENSHOT
+
+
+class ScreenshotCommandHandler:
+    def __init__(
+        self,
+        *,
+        runtime_kernel: RuntimeKernel,
+        device_client_factory: DeviceClientFactory,
+        artifact_writer: ArtifactWriter,
+    ) -> None:
+        self._runtime_kernel = runtime_kernel
+        self._device_client_factory = device_client_factory
+        self._artifact_writer = artifact_writer
+
+    def handle(
+        self,
+        *,
+        command: ScreenshotCommand,
+    ) -> dict[str, object]:
+        runtime = self._runtime_kernel.ensure_runtime()
+        query_lane_acquired = False
+        try:
+            lifecycle_lease = self._runtime_kernel.capture_lifecycle_lease(runtime)
+            self._runtime_kernel.acquire_query_lane(runtime)
+            query_lane_acquired = True
+            client = None
+            if (
+                runtime.connection is not None
+                and runtime.device_token is not None
+                and runtime.transport is None
+            ):
+                client = self._device_client_factory(
+                    runtime,
+                    lifecycle_lease=lifecycle_lease,
+                )
+            ensure_command_supported(runtime, command)
+            if client is None:
+                client = self._device_client_factory(
+                    runtime,
+                    lifecycle_lease=lifecycle_lease,
+                )
+            payload = client.screenshot_capture(
+                request_id=DEVICE_RPC_REQUEST_ID_SCREENSHOT,
+            )
+            with runtime.lock:
+                if not lifecycle_lease.is_current(runtime):
+                    raise RuntimeError("runtime lifecycle changed during screenshot")
+                decoded_body = decode_screenshot_body_base64(
+                    payload.body_base64,
+                    field_name="result.bodyBase64",
+                )
+                validate_screenshot_png_bytes(
+                    decoded_body,
+                    field_name="result.bodyBase64",
+                    expected_width_px=payload.width_px,
+                    expected_height_px=payload.height_px,
+                )
+                output_path = self._artifact_writer.write_screenshot_png(
+                    runtime,
+                    decoded_body,
+                )
+                attachment = self._runtime_kernel.attach_screenshot_artifact(
+                    runtime,
+                    lifecycle_lease,
+                    screenshot_png=output_path.as_posix(),
+                )
+                if attachment is None:
+                    with suppress(OSError):
+                        output_path.unlink()
+                    raise RuntimeError("runtime lifecycle changed during screenshot")
+                artifacts = attachment.artifacts
+                return build_retained_success_result(
+                    command="screenshot",
+                    artifacts=artifacts,
+                ).model_dump(by_alias=True, mode="json")
+        except DaemonError as error:
+            return build_projected_retained_failure_result_for_error(
+                command="screenshot",
+                error=error,
+                artifacts=None,
+            ).model_dump(by_alias=True, mode="json")
+        finally:
+            if query_lane_acquired:
+                self._runtime_kernel.release_progress_lane(runtime)