androidctl 0.1.0__py3-none-any.whl

androidctl/__init__.py

@@ -0,0 +1,5 @@
+"""androidctl package."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

androidctl/__main__.py

@@ -0,0 +1,4 @@
+from .app import app
+
+if __name__ == "__main__":
+    app()

androidctl/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

androidctl/app.py

@@ -0,0 +1,73 @@
+from pathlib import Path
+
+import click
+import typer
+from typer.core import TyperGroup
+
+from androidctl import __version__
+from androidctl.cli_options import CliOptions
+from androidctl.command_views import help_order_for_public_command
+from androidctl.commands.actions import register as register_action_commands
+from androidctl.commands.adb_wireless import register as register_adb_wireless_commands
+from androidctl.commands.close import register as register_close_command
+from androidctl.commands.connect import register as register_connect_command
+from androidctl.commands.list_apps import register as register_list_apps_command
+from androidctl.commands.observe import register as register_observe_command
+from androidctl.commands.open import register as register_open_command
+from androidctl.commands.screenshot import register as register_screenshot_command
+from androidctl.commands.setup import register as register_setup_command
+from androidctl.commands.wait import register as register_wait_command
+
+
+class OrderedHelpGroup(TyperGroup):
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        names = list(super().list_commands(ctx))
+        return sorted(names, key=help_order_for_public_command)
+
+
+app = typer.Typer(
+    name="androidctl",
+    cls=OrderedHelpGroup,
+    help=(
+        "Agent loop: observe/list-apps/open -> act -> wait. Retained support routes: "
+        "connect, screenshot, close."
+    ),
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+
+def _show_version(value: bool) -> None:
+    if not value:
+        return
+    typer.echo(__version__)
+    raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_show_version,
+        is_eager=True,
+        help="Show the androidctl release version and exit.",
+    ),
+    workspace_root: Path | None = typer.Option(None, "--workspace-root"),
+) -> None:
+    """Public happy path for driving the daemon-backed device runtime."""
+    del version
+    ctx.obj = CliOptions(workspace_root=workspace_root)
+
+
+register_connect_command(app)
+register_observe_command(app)
+register_list_apps_command(app)
+register_open_command(app)
+register_action_commands(app)
+register_wait_command(app)
+register_screenshot_command(app)
+register_close_command(app)
+register_setup_command(app)
+register_adb_wireless_commands(app)

androidctl/cli_options.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+
+@dataclass(frozen=True)
+class CliOptions:
+    workspace_root: Path | None
+
+
+def read_cli_options(ctx: typer.Context) -> CliOptions:
+    payload = ctx.obj
+    if isinstance(payload, CliOptions):
+        return payload
+    return CliOptions(workspace_root=None)
+
+
+def command_cli_options(
+    ctx: typer.Context,
+    *,
+    workspace_root: Path | None = None,
+) -> CliOptions:
+    root_options = read_cli_options(ctx)
+    return CliOptions(workspace_root=workspace_root or root_options.workspace_root)

androidctl/command_payloads.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final, Literal, TypeAlias
+
+from androidctl_contracts.daemon_api import (
+    DaemonCommandPayload,
+    GlobalActionCommandPayload,
+    GonePredicatePayload,
+    LiveScreenBoundCommandPayload,
+    RefActionCommandPayload,
+    ScreenChangePredicatePayload,
+    ScreenRelativeWaitPredicatePayload,
+    ScrollCommandPayload,
+    TypeCommandPayload,
+    WaitCommandPayload,
+    WaitPredicatePayload,
+)
+
+ScrollDirection = Literal["up", "down", "left", "right", "backward"]
+RefActionKind = Literal["tap", "longTap", "focus", "submit"]
+GlobalActionKind = Literal["back", "home", "recents", "notifications"]
+LateBoundActionKind = Literal["tap", "longTap", "focus", "submit", "type", "scroll"]
+SCROLL_DIRECTIONS: Final = frozenset({"up", "down", "left", "right", "backward"})
+
+
+def _normalize_optional_cli_string(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    return normalized or None
+
+
+def _normalize_source_screen_id(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    if not normalized:
+        raise ValueError("source_screen_id must be non-empty when provided")
+    return normalized
+
+
+def _required_source_screen_id(value: str) -> str:
+    normalized = _normalize_optional_cli_string(value)
+    if normalized is None:
+        raise RuntimeError("prepared command is missing source_screen_id")
+    return normalized
+
+
+def _validate_timeout_ms(value: int | None) -> int | None:
+    if isinstance(value, bool):
+        raise TypeError("timeout_ms must be an int, not bool")
+    if value is not None and not isinstance(value, int):
+        raise TypeError("timeout_ms must be an int")
+    if value is not None and value < 0:
+        raise ValueError("timeout_ms must be >= 0")
+    return value
+
+
+@dataclass(frozen=True)
+class LateBoundActionCommand:
+    kind: LateBoundActionKind
+    ref: str
+    text: str | None = None
+    direction: ScrollDirection | None = None
+
+    def __post_init__(self) -> None:
+        if _normalize_optional_cli_string(self.ref) is None:
+            raise ValueError("late-bound action command requires ref")
+        if self.kind == "type":
+            if self.text is None:
+                raise ValueError("late-bound type command requires text")
+            if self.direction is not None:
+                raise ValueError("late-bound type command does not accept direction")
+            return
+        if self.kind == "scroll":
+            if self.direction is None:
+                raise ValueError("late-bound scroll command requires direction")
+            if self.direction not in SCROLL_DIRECTIONS:
+                raise ValueError("late-bound scroll command requires a valid direction")
+            if self.text is not None:
+                raise ValueError("late-bound scroll command does not accept text")
+            return
+        if self.text is not None or self.direction is not None:
+            raise ValueError(
+                "late-bound ref action commands only accept kind and ref fields"
+            )
+
+    def bind(self, source_screen_id: str) -> LiveScreenBoundCommandPayload:
+        resolved_source_screen_id = _required_source_screen_id(source_screen_id)
+        if self.kind == "type":
+            if self.text is None:
+                raise RuntimeError("prepared type command is missing text")
+            return TypeCommandPayload(
+                kind="type",
+                ref=self.ref,
+                text=self.text,
+                source_screen_id=resolved_source_screen_id,
+            )
+        if self.kind == "scroll":
+            if self.direction is None:
+                raise RuntimeError("prepared scroll command is missing direction")
+            return ScrollCommandPayload(
+                kind="scroll",
+                ref=self.ref,
+                direction=self.direction,
+                source_screen_id=resolved_source_screen_id,
+            )
+        return RefActionCommandPayload(
+            kind=self.kind,
+            ref=self.ref,
+            source_screen_id=resolved_source_screen_id,
+        )
+
+
+@dataclass(frozen=True)
+class LateBoundScreenRelativePredicate:
+    kind: Literal["screen-change", "gone"]
+    ref: str | None = None
+
+    def __post_init__(self) -> None:
+        normalized_ref = _normalize_optional_cli_string(self.ref)
+        if self.kind == "gone" and normalized_ref is None:
+            raise ValueError("late-bound gone predicate requires a non-empty ref")
+        if self.kind == "screen-change" and self.ref is not None:
+            raise ValueError("screen-change predicate does not accept ref")
+
+    def bind(self, source_screen_id: str) -> ScreenRelativeWaitPredicatePayload:
+        resolved_source_screen_id = _required_source_screen_id(source_screen_id)
+        if self.kind == "screen-change":
+            return ScreenChangePredicatePayload(
+                kind="screen-change",
+                source_screen_id=resolved_source_screen_id,
+            )
+        if self.ref is None:
+            raise RuntimeError("prepared gone predicate is missing ref")
+        return GonePredicatePayload(
+            kind="gone",
+            ref=self.ref,
+            source_screen_id=resolved_source_screen_id,
+        )
+
+
+CliWaitPredicatePayload: TypeAlias = (
+    WaitPredicatePayload | LateBoundScreenRelativePredicate
+)
+
+
+@dataclass(frozen=True)
+class LateBoundWaitCommand:
+    predicate: LateBoundScreenRelativePredicate
+    timeout_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        _validate_timeout_ms(self.timeout_ms)
+
+    def bind(self, source_screen_id: str) -> WaitCommandPayload:
+        return WaitCommandPayload(
+            kind="wait",
+            predicate=self.predicate.bind(source_screen_id),
+            timeout_ms=self.timeout_ms,
+        )
+
+
+@dataclass(frozen=True)
+class LateBoundGlobalActionCommand:
+    kind: GlobalActionKind
+
+    def bind(self, source_screen_id: str | None) -> GlobalActionCommandPayload:
+        normalized_source_screen_id = (
+            None if source_screen_id is None else source_screen_id.strip() or None
+        )
+        return GlobalActionCommandPayload(
+            kind=self.kind,
+            source_screen_id=normalized_source_screen_id,
+        )
+
+
+LateBoundCommand: TypeAlias = (
+    LateBoundActionCommand | LateBoundGlobalActionCommand | LateBoundWaitCommand
+)
+CliCommandPayload: TypeAlias = DaemonCommandPayload | LateBoundCommand
+
+
+def build_ref_action_command(
+    *,
+    kind: RefActionKind,
+    ref: str,
+    source_screen_id: str | None,
+) -> CliCommandPayload:
+    normalized_source_screen_id = _normalize_source_screen_id(source_screen_id)
+    if normalized_source_screen_id is None:
+        return LateBoundActionCommand(kind=kind, ref=ref)
+    return RefActionCommandPayload(
+        kind=kind,
+        ref=ref,
+        source_screen_id=normalized_source_screen_id,
+    )
+
+
+def build_type_command(
+    *,
+    ref: str,
+    text: str,
+    source_screen_id: str | None,
+) -> CliCommandPayload:
+    normalized_source_screen_id = _normalize_source_screen_id(source_screen_id)
+    if normalized_source_screen_id is None:
+        return LateBoundActionCommand(kind="type", ref=ref, text=text)
+    return TypeCommandPayload(
+        kind="type",
+        ref=ref,
+        text=text,
+        source_screen_id=normalized_source_screen_id,
+    )
+
+
+def build_scroll_command(
+    *,
+    ref: str,
+    direction: ScrollDirection,
+    source_screen_id: str | None,
+) -> CliCommandPayload:
+    normalized_source_screen_id = _normalize_source_screen_id(source_screen_id)
+    if normalized_source_screen_id is None:
+        return LateBoundActionCommand(kind="scroll", ref=ref, direction=direction)
+    return ScrollCommandPayload(
+        kind="scroll",
+        ref=ref,
+        direction=direction,
+        source_screen_id=normalized_source_screen_id,
+    )
+
+
+def build_wait_command(
+    *,
+    predicate: CliWaitPredicatePayload,
+    timeout_ms: int | None,
+) -> CliCommandPayload:
+    validated_timeout_ms = _validate_timeout_ms(timeout_ms)
+    if isinstance(predicate, LateBoundScreenRelativePredicate):
+        return LateBoundWaitCommand(
+            predicate=predicate,
+            timeout_ms=validated_timeout_ms,
+        )
+    return WaitCommandPayload(
+        kind="wait",
+        predicate=predicate,
+        timeout_ms=validated_timeout_ms,
+    )
+
+
+def build_global_action_command(
+    *,
+    kind: GlobalActionKind,
+    source_screen_id: str | None,
+) -> CliCommandPayload:
+    normalized_source_screen_id = _normalize_source_screen_id(source_screen_id)
+    if normalized_source_screen_id is None:
+        return LateBoundGlobalActionCommand(kind=kind)
+    return GlobalActionCommandPayload(
+        kind=kind,
+        source_screen_id=normalized_source_screen_id,
+    )

androidctl/command_views.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from androidctl_contracts.command_catalog import (
+    PUBLIC_COMMAND_NAMES,
+    entry_for_public_command,
+)
+
+
+@dataclass(frozen=True)
+class CommandView:
+    public_name: str
+    help_order: int
+    pre_dispatch_execution_outcome: str | None
+
+
+def _command_view(
+    public_name: str,
+    *,
+    help_order: int,
+    pre_dispatch_execution_outcome: str | None,
+) -> CommandView:
+    if entry_for_public_command(public_name) is None:
+        raise RuntimeError(f"missing shared command catalog entry for {public_name!r}")
+    return CommandView(
+        public_name=public_name,
+        help_order=help_order,
+        pre_dispatch_execution_outcome=pre_dispatch_execution_outcome,
+    )
+
+
+_COMMAND_VIEWS = (
+    _command_view(
+        public_name="observe",
+        help_order=0,
+        pre_dispatch_execution_outcome="notApplicable",
+    ),
+    _command_view(
+        public_name="list-apps",
+        help_order=1,
+        pre_dispatch_execution_outcome="notApplicable",
+    ),
+    _command_view(
+        public_name="open",
+        help_order=2,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="tap",
+        help_order=3,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="long-tap",
+        help_order=4,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="focus",
+        help_order=5,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="type",
+        help_order=6,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="submit",
+        help_order=7,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="scroll",
+        help_order=8,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="back",
+        help_order=9,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="home",
+        help_order=10,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="recents",
+        help_order=11,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="notifications",
+        help_order=12,
+        pre_dispatch_execution_outcome="notAttempted",
+    ),
+    _command_view(
+        public_name="wait",
+        help_order=13,
+        pre_dispatch_execution_outcome="notApplicable",
+    ),
+    _command_view(
+        public_name="connect",
+        help_order=14,
+        pre_dispatch_execution_outcome="notApplicable",
+    ),
+    _command_view(
+        public_name="screenshot",
+        help_order=15,
+        pre_dispatch_execution_outcome="notApplicable",
+    ),
+    _command_view(
+        public_name="close",
+        help_order=16,
+        pre_dispatch_execution_outcome="notApplicable",
+    ),
+)
+
+_command_view_names = [view.public_name for view in _COMMAND_VIEWS]
+_help_orders = [view.help_order for view in _COMMAND_VIEWS]
+if len(_command_view_names) != len(set(_command_view_names)):
+    raise RuntimeError("duplicate public command in CLI command views")
+if len(_help_orders) != len(set(_help_orders)):
+    raise RuntimeError("duplicate help order in CLI command views")
+if set(_command_view_names) != PUBLIC_COMMAND_NAMES:
+    missing = sorted(PUBLIC_COMMAND_NAMES - set(_command_view_names))
+    extra = sorted(set(_command_view_names) - PUBLIC_COMMAND_NAMES)
+    raise RuntimeError(
+        "CLI command views drifted from shared public catalog: "
+        f"missing={missing}, extra={extra}"
+    )
+
+_COMMAND_VIEW_BY_PUBLIC_NAME = {view.public_name: view for view in _COMMAND_VIEWS}
+
+
+def command_view_for_public_command(public_name: str) -> CommandView | None:
+    return _COMMAND_VIEW_BY_PUBLIC_NAME.get(public_name)
+
+
+def help_order_for_public_command(public_name: str) -> int:
+    view = command_view_for_public_command(public_name)
+    if view is None:
+        return len(_COMMAND_VIEWS)
+    return view.help_order
+
+
+def pre_dispatch_execution_outcome_for_public_command(
+    public_name: str | None,
+) -> str | None:
+    if public_name is None:
+        return None
+    view = command_view_for_public_command(public_name)
+    if view is None:
+        return None
+    return view.pre_dispatch_execution_outcome

androidctl/commands/__init__.py

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