androidctl 0.1.0__py3-none-any.whl

androidctld/commands/command_models.py

@@ -0,0 +1,254 @@
+"""Runtime command models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TypeAlias, TypeGuard
+
+from androidctld.commands.open_targets import OpenAppTarget, OpenUrlTarget
+from androidctld.device.types import ConnectionConfig
+from androidctld.protocol import CommandKind
+
+
+class WaitKind(str, Enum):
+    TEXT = "text"
+    SCREEN_CHANGE = "screen-change"
+    GONE = "gone"
+    APP = "app"
+    IDLE = "idle"
+
+
+@dataclass(frozen=True)
+class ConnectCommand:
+    connection: ConnectionConfig
+    kind: CommandKind = field(default=CommandKind.CONNECT, init=False)
+
+
+@dataclass(frozen=True)
+class ObserveCommand:
+    kind: CommandKind = field(default=CommandKind.OBSERVE, init=False)
+
+
+@dataclass(frozen=True)
+class ScreenshotCommand:
+    kind: CommandKind = field(default=CommandKind.SCREENSHOT, init=False)
+
+
+@dataclass(frozen=True)
+class ListAppsCommand:
+    kind: CommandKind = field(default=CommandKind.LIST_APPS, init=False)
+
+
+class _TypedActionCommandMixin:
+    kind: CommandKind
+
+
+@dataclass(frozen=True)
+class OpenCommand(_TypedActionCommandMixin):
+    target: OpenAppTarget | OpenUrlTarget
+    kind: CommandKind = field(default=CommandKind.OPEN, init=False)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.target, (OpenAppTarget, OpenUrlTarget)):
+            raise ValueError("open requires typed target")
+
+
+@dataclass(frozen=True)
+class TapCommand(_TypedActionCommandMixin):
+    ref: str
+    source_screen_id: str
+    kind: CommandKind = field(default=CommandKind.TAP, init=False)
+
+
+@dataclass(frozen=True)
+class LongTapCommand(_TypedActionCommandMixin):
+    ref: str
+    source_screen_id: str
+    kind: CommandKind = field(default=CommandKind.LONG_TAP, init=False)
+
+
+@dataclass(frozen=True)
+class TypeCommand(_TypedActionCommandMixin):
+    ref: str
+    source_screen_id: str
+    text: str
+    kind: CommandKind = field(default=CommandKind.TYPE, init=False)
+
+
+@dataclass(frozen=True)
+class FocusCommand(_TypedActionCommandMixin):
+    ref: str
+    source_screen_id: str
+    kind: CommandKind = field(default=CommandKind.FOCUS, init=False)
+
+
+@dataclass(frozen=True)
+class SubmitCommand(_TypedActionCommandMixin):
+    ref: str
+    source_screen_id: str
+    kind: CommandKind = field(default=CommandKind.SUBMIT, init=False)
+
+
+@dataclass(frozen=True)
+class ScrollCommand(_TypedActionCommandMixin):
+    ref: str
+    source_screen_id: str
+    direction: str
+    kind: CommandKind = field(default=CommandKind.SCROLL, init=False)
+
+
+@dataclass(frozen=True)
+class GlobalCommand(_TypedActionCommandMixin):
+    action: str
+    source_screen_id: str | None = None
+    kind: CommandKind = field(default=CommandKind.GLOBAL, init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class TextWaitPredicate:
+    text: str
+    wait_kind: WaitKind = field(default=WaitKind.TEXT, init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ScreenChangeWaitPredicate:
+    source_screen_id: str
+    wait_kind: WaitKind = field(default=WaitKind.SCREEN_CHANGE, init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class GoneWaitPredicate:
+    source_screen_id: str
+    ref: str
+    wait_kind: WaitKind = field(default=WaitKind.GONE, init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class AppWaitPredicate:
+    package_name: str
+    wait_kind: WaitKind = field(default=WaitKind.APP, init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class IdleWaitPredicate:
+    wait_kind: WaitKind = field(default=WaitKind.IDLE, init=False)
+
+
+WaitPredicate: TypeAlias = (
+    TextWaitPredicate
+    | ScreenChangeWaitPredicate
+    | GoneWaitPredicate
+    | AppWaitPredicate
+    | IdleWaitPredicate
+)
+
+WAIT_PREDICATE_TYPES = (
+    TextWaitPredicate,
+    ScreenChangeWaitPredicate,
+    GoneWaitPredicate,
+    AppWaitPredicate,
+    IdleWaitPredicate,
+)
+
+
+@dataclass(frozen=True)
+class WaitCommand:
+    predicate: WaitPredicate
+    timeout_ms: int | None = None
+    kind: CommandKind = field(default=CommandKind.WAIT, init=False)
+
+    def __post_init__(self) -> None:
+        if not is_wait_predicate(self.predicate):
+            raise ValueError("wait requires typed predicate")
+
+    @property
+    def wait_kind(self) -> WaitKind:
+        return self.predicate.wait_kind
+
+
+TypedActionCommand: TypeAlias = (
+    OpenCommand
+    | TapCommand
+    | LongTapCommand
+    | TypeCommand
+    | FocusCommand
+    | SubmitCommand
+    | ScrollCommand
+    | GlobalCommand
+)
+
+ActionCommand: TypeAlias = TypedActionCommand
+
+REF_BOUND_ACTION_COMMAND_TYPES = (
+    TapCommand,
+    LongTapCommand,
+    TypeCommand,
+    FocusCommand,
+    SubmitCommand,
+    ScrollCommand,
+)
+
+RefBoundActionCommand: TypeAlias = (
+    TapCommand
+    | LongTapCommand
+    | TypeCommand
+    | FocusCommand
+    | SubmitCommand
+    | ScrollCommand
+)
+
+InternalCommand: TypeAlias = (
+    ConnectCommand
+    | ObserveCommand
+    | ListAppsCommand
+    | ActionCommand
+    | WaitCommand
+    | ScreenshotCommand
+)
+
+
+def wait_timeout_ms(command: WaitCommand) -> int | None:
+    return command.timeout_ms
+
+
+def is_wait_predicate(value: object) -> TypeGuard[WaitPredicate]:
+    return isinstance(value, WAIT_PREDICATE_TYPES)
+
+
+def is_ref_bound_action_command(command: object) -> TypeGuard[RefBoundActionCommand]:
+    return isinstance(command, REF_BOUND_ACTION_COMMAND_TYPES)
+
+
+__all__ = [
+    "REF_BOUND_ACTION_COMMAND_TYPES",
+    "ActionCommand",
+    "AppWaitPredicate",
+    "ConnectCommand",
+    "FocusCommand",
+    "GlobalCommand",
+    "GoneWaitPredicate",
+    "IdleWaitPredicate",
+    "InternalCommand",
+    "ListAppsCommand",
+    "LongTapCommand",
+    "ObserveCommand",
+    "OpenAppTarget",
+    "OpenCommand",
+    "OpenUrlTarget",
+    "RefBoundActionCommand",
+    "ScreenChangeWaitPredicate",
+    "ScreenshotCommand",
+    "ScrollCommand",
+    "SubmitCommand",
+    "TapCommand",
+    "TextWaitPredicate",
+    "TypeCommand",
+    "TypedActionCommand",
+    "WaitCommand",
+    "WaitKind",
+    "WaitPredicate",
+    "is_ref_bound_action_command",
+    "is_wait_predicate",
+    "wait_timeout_ms",
+]

androidctld/commands/dispatch.py

@@ -0,0 +1,99 @@
+"""Per-command semantic boundary dispatch helpers."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from androidctld.commands.command_models import (
+    ConnectCommand,
+    GlobalCommand,
+    InternalCommand,
+    ListAppsCommand,
+    ObserveCommand,
+    OpenCommand,
+    ScreenshotCommand,
+    WaitCommand,
+    is_ref_bound_action_command,
+)
+from androidctld.commands.executor import CommandHandler, CommandResult
+from androidctld.commands.handlers.action import ActionCommandHandler
+from androidctld.commands.handlers.connect import ConnectCommandHandler
+from androidctld.commands.handlers.list_apps import ListAppsCommandHandler
+from androidctld.commands.handlers.observe import ObserveCommandHandler
+from androidctld.commands.handlers.screenshot import ScreenshotCommandHandler
+from androidctld.commands.handlers.wait import WaitCommandHandler
+from androidctld.commands.registry import COMMAND_SPECS
+
+__all__ = ["CommandDispatch"]
+
+
+class CommandDispatch:
+    def __init__(
+        self,
+        *,
+        connect_handler: ConnectCommandHandler,
+        observe_handler: ObserveCommandHandler,
+        list_apps_handler: ListAppsCommandHandler,
+        action_handler: ActionCommandHandler,
+        wait_handler: WaitCommandHandler,
+        screenshot_handler: ScreenshotCommandHandler,
+    ) -> None:
+        self._connect_handler = connect_handler
+        self._observe_handler = observe_handler
+        self._list_apps_handler = list_apps_handler
+        self._action_handler = action_handler
+        self._wait_handler = wait_handler
+        self._screenshot_handler = screenshot_handler
+
+    def build_handlers(self) -> dict[str, CommandHandler]:
+        return {
+            spec.daemon_kind: cast(
+                CommandHandler,
+                getattr(self, spec.dispatch_method_name),
+            )
+            for spec in COMMAND_SPECS.values()
+        }
+
+    def execute_connect(self, *, command: InternalCommand) -> CommandResult:
+        if not isinstance(command, ConnectCommand):
+            raise TypeError(f"connect handler received {command.kind!r} command")
+        return self._connect_handler.handle(command=command)
+
+    def execute_observe(self, *, command: InternalCommand) -> CommandResult:
+        if not isinstance(command, ObserveCommand):
+            raise TypeError(f"observe handler received {command.kind!r} command")
+        return self._observe_handler.handle(command=command)
+
+    def execute_list_apps(self, *, command: InternalCommand) -> CommandResult:
+        if not isinstance(command, ListAppsCommand):
+            raise TypeError(f"list-apps handler received {command.kind!r} command")
+        return self._list_apps_handler.handle(command=command)
+
+    def execute_open(self, *, command: InternalCommand) -> CommandResult:
+        if not isinstance(command, OpenCommand):
+            raise TypeError(f"open handler received {command.kind!r} command")
+        return self._action_handler.handle_open(command=command)
+
+    def execute_ref_action(self, *, command: InternalCommand) -> CommandResult:
+        if not is_ref_bound_action_command(command):
+            raise TypeError(f"ref action handler received {command.kind!r} command")
+        return self._action_handler.handle_ref_action(command=command)
+
+    def execute_global_action(
+        self,
+        *,
+        command: InternalCommand,
+    ) -> CommandResult:
+        if not isinstance(command, GlobalCommand):
+            raise TypeError(f"global action handler received {command.kind!r} command")
+        return self._action_handler.handle_global_action(command=command)
+
+    def execute_wait(self, *, command: InternalCommand) -> CommandResult:
+        if isinstance(command, WaitCommand):
+            return self._wait_handler.handle_service_wait(command=command)
+        raise TypeError(f"wait handler received {command.kind!r} command")
+
+    def execute_screenshot(self, *, command: InternalCommand) -> CommandResult:
+        if not isinstance(command, ScreenshotCommand):
+            raise TypeError(f"screenshot handler received {command.kind!r} command")
+        return self._screenshot_handler.handle(command=command)

androidctld/commands/executor.py

@@ -0,0 +1,31 @@
+"""Thin semantic command executor."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from androidctld.commands.command_models import InternalCommand
+from androidctld.commands.registry import resolve_command_spec
+
+CommandResult = dict[str, object]
+
+
+class CommandHandler(Protocol):
+    def __call__(self, *, command: InternalCommand) -> CommandResult: ...
+
+
+class CommandExecutor:
+    def __init__(self, *, handlers: dict[str, CommandHandler]) -> None:
+        self._handlers = handlers
+
+    def run(
+        self,
+        *,
+        command: InternalCommand,
+    ) -> CommandResult:
+        spec = resolve_command_spec(command)
+        handler = self._handlers[spec.command_name]
+        return handler(command=command)
+
+
+__all__ = ["CommandExecutor", "CommandHandler", "CommandResult"]

androidctld/commands/from_boundary.py

@@ -0,0 +1,175 @@
+"""Pure compilers from validated shared wire payloads to executable commands."""
+
+from __future__ import annotations
+
+from androidctl_contracts import daemon_api as wire_api
+from androidctld.commands.command_models import (
+    AppWaitPredicate,
+    ConnectCommand,
+    FocusCommand,
+    GlobalCommand,
+    GoneWaitPredicate,
+    IdleWaitPredicate,
+    ListAppsCommand,
+    LongTapCommand,
+    ObserveCommand,
+    OpenAppTarget,
+    OpenCommand,
+    OpenUrlTarget,
+    RefBoundActionCommand,
+    ScreenChangeWaitPredicate,
+    ScreenshotCommand,
+    ScrollCommand,
+    SubmitCommand,
+    TapCommand,
+    TextWaitPredicate,
+    TypeCommand,
+    WaitCommand,
+)
+from androidctld.device.types import ConnectionConfig
+from androidctld.protocol import ConnectionMode
+
+
+def compile_connect_command(payload: wire_api.ConnectCommandPayload) -> ConnectCommand:
+    connection = payload.connection
+    mode = ConnectionMode(connection.mode)
+    if mode is ConnectionMode.LAN:
+        if connection.host is None or connection.port is None:
+            raise TypeError("lan connect wire payload requires host and port")
+        return ConnectCommand(
+            connection=ConnectionConfig(
+                mode=mode,
+                token=connection.token,
+                host=connection.host,
+                port=connection.port,
+            )
+        )
+    return ConnectCommand(
+        connection=ConnectionConfig(
+            mode=mode,
+            token=connection.token,
+            serial=connection.serial,
+        )
+    )
+
+
+def compile_observe_command(payload: wire_api.ObserveCommandPayload) -> ObserveCommand:
+    del payload
+    return ObserveCommand()
+
+
+def compile_list_apps_command(
+    payload: wire_api.ListAppsCommandPayload,
+) -> ListAppsCommand:
+    del payload
+    return ListAppsCommand()
+
+
+def compile_open_command(payload: wire_api.OpenCommandPayload) -> OpenCommand:
+    target = payload.target
+    if isinstance(target, wire_api.OpenAppTargetPayload):
+        return OpenCommand(target=OpenAppTarget(package_name=target.value))
+    if isinstance(target, wire_api.OpenUrlTargetPayload):
+        return OpenCommand(target=OpenUrlTarget(url=target.value))
+    raise TypeError(f"unsupported open target payload: {type(target)!r}")
+
+
+def compile_ref_action_command(
+    payload: (
+        wire_api.RefActionCommandPayload
+        | wire_api.TypeCommandPayload
+        | wire_api.ScrollCommandPayload
+    ),
+) -> RefBoundActionCommand:
+    if isinstance(payload, wire_api.TypeCommandPayload):
+        return TypeCommand(
+            ref=payload.ref,
+            source_screen_id=payload.source_screen_id,
+            text=payload.text,
+        )
+    if isinstance(payload, wire_api.ScrollCommandPayload):
+        return ScrollCommand(
+            ref=payload.ref,
+            source_screen_id=payload.source_screen_id,
+            direction=payload.direction,
+        )
+    if payload.kind == "tap":
+        return TapCommand(ref=payload.ref, source_screen_id=payload.source_screen_id)
+    if payload.kind == "longTap":
+        return LongTapCommand(
+            ref=payload.ref,
+            source_screen_id=payload.source_screen_id,
+        )
+    if payload.kind == "focus":
+        return FocusCommand(ref=payload.ref, source_screen_id=payload.source_screen_id)
+    if payload.kind == "submit":
+        return SubmitCommand(
+            ref=payload.ref,
+            source_screen_id=payload.source_screen_id,
+        )
+    raise TypeError(f"unsupported ref action payload kind: {payload.kind!r}")
+
+
+def compile_global_action_command(
+    payload: wire_api.GlobalActionCommandPayload,
+) -> GlobalCommand:
+    return GlobalCommand(
+        action=payload.kind,
+        source_screen_id=payload.source_screen_id,
+    )
+
+
+def compile_service_wait_command(
+    payload: wire_api.WaitCommandPayload,
+) -> WaitCommand:
+    predicate = payload.predicate
+    if isinstance(predicate, wire_api.TextPresentPredicatePayload):
+        return WaitCommand(
+            predicate=TextWaitPredicate(text=predicate.text),
+            timeout_ms=payload.timeout_ms,
+        )
+    if isinstance(predicate, wire_api.ScreenChangePredicatePayload):
+        return WaitCommand(
+            predicate=ScreenChangeWaitPredicate(
+                source_screen_id=predicate.source_screen_id,
+            ),
+            timeout_ms=payload.timeout_ms,
+        )
+    if isinstance(predicate, wire_api.GonePredicatePayload):
+        return WaitCommand(
+            predicate=GoneWaitPredicate(
+                source_screen_id=predicate.source_screen_id,
+                ref=predicate.ref,
+            ),
+            timeout_ms=payload.timeout_ms,
+        )
+    if isinstance(predicate, wire_api.AppPredicatePayload):
+        return WaitCommand(
+            predicate=AppWaitPredicate(package_name=predicate.package_name),
+            timeout_ms=payload.timeout_ms,
+        )
+    if isinstance(predicate, wire_api.IdlePredicatePayload):
+        return WaitCommand(
+            predicate=IdleWaitPredicate(),
+            timeout_ms=payload.timeout_ms,
+        )
+    raise TypeError(f"unsupported wait predicate payload: {type(predicate)!r}")
+
+
+def compile_screenshot_command(
+    payload: wire_api.ScreenshotCommandPayload,
+) -> ScreenshotCommand:
+    del payload
+    return ScreenshotCommand()
+
+
+__all__ = [
+    "compile_connect_command",
+    "compile_global_action_command",
+    "compile_list_apps_command",
+    "compile_observe_command",
+    "compile_open_command",
+    "compile_ref_action_command",
+    "compile_screenshot_command",
+    "compile_service_wait_command",
+]

androidctld/commands/handlers/__init__.py

@@ -0,0 +1,15 @@
+"""Command handler modules."""
+
+from androidctld.commands.handlers.action import ActionCommandHandler
+from androidctld.commands.handlers.connect import ConnectCommandHandler
+from androidctld.commands.handlers.observe import ObserveCommandHandler
+from androidctld.commands.handlers.screenshot import ScreenshotCommandHandler
+from androidctld.commands.handlers.wait import WaitCommandHandler
+
+__all__ = [
+    "ActionCommandHandler",
+    "ConnectCommandHandler",
+    "ObserveCommandHandler",
+    "ScreenshotCommandHandler",
+    "WaitCommandHandler",
+]