androidctl 0.1.0__py3-none-any.whl

androidctl/commands/actions.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from collections.abc import Collection
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Literal, cast
+
+import typer
+
+from androidctl.command_payloads import (
+    SCROLL_DIRECTIONS,
+    build_global_action_command,
+    build_ref_action_command,
+    build_scroll_command,
+    build_type_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.refs import parse_ref
+from androidctl.parsing.screen_id import parse_screen_id_override
+from androidctl_contracts.command_catalog import daemon_kind_for_public_command
+
+RefActionKind = Literal["tap", "longTap", "focus", "submit"]
+GlobalActionKind = Literal["back", "home", "recents", "notifications"]
+ActionCommandKind = Literal[
+    "tap",
+    "longTap",
+    "focus",
+    "submit",
+    "type",
+    "scroll",
+    "back",
+    "home",
+    "recents",
+    "notifications",
+]
+ActionCommandSignature = Literal["ref", "ref_text", "ref_direction", "screen"]
+ScrollDirection = Literal["up", "down", "left", "right", "backward"]
+TargetRefArgument = Annotated[
+    str,
+    typer.Argument(help="Target ref, for example n3."),
+]
+ScrollableRefArgument = Annotated[
+    str,
+    typer.Argument(help="Scrollable ref, for example n8."),
+]
+TypeTextArgument = Annotated[
+    str,
+    typer.Argument(help="Text to replace the current value with."),
+]
+ScrollDirectionArgument = Annotated[
+    str,
+    typer.Argument(help="Scroll direction: up/down/left/right/backward."),
+]
+ScreenIdOption = Annotated[
+    str | None,
+    typer.Option("--screen-id", help="Override the source screen id for this command."),
+]
+WorkspaceRootOption = Annotated[Path | None, typer.Option("--workspace-root")]
+
+
+@dataclass(frozen=True)
+class _ActionCommandSpec:
+    public_command: str
+    signature: ActionCommandSignature
+
+    @property
+    def kind(self) -> ActionCommandKind:
+        daemon_kind = daemon_kind_for_public_command(self.public_command)
+        if daemon_kind is None:
+            raise RuntimeError(
+                f"missing daemon kind for action command {self.public_command!r}"
+            )
+        return cast(ActionCommandKind, daemon_kind)
+
+
+_ACTION_COMMAND_SPECS = (
+    _ActionCommandSpec(public_command="tap", signature="ref"),
+    _ActionCommandSpec(public_command="long-tap", signature="ref"),
+    _ActionCommandSpec(public_command="focus", signature="ref"),
+    _ActionCommandSpec(public_command="submit", signature="ref"),
+    _ActionCommandSpec(public_command="type", signature="ref_text"),
+    _ActionCommandSpec(
+        public_command="scroll",
+        signature="ref_direction",
+    ),
+    _ActionCommandSpec(public_command="back", signature="screen"),
+    _ActionCommandSpec(public_command="home", signature="screen"),
+    _ActionCommandSpec(public_command="recents", signature="screen"),
+    _ActionCommandSpec(
+        public_command="notifications",
+        signature="screen",
+    ),
+)
+
+
+def register(app: typer.Typer) -> None:
+    for spec in _ACTION_COMMAND_SPECS:
+        if spec.signature == "ref":
+            _register_ref_command(app, spec)
+            continue
+        if spec.signature == "ref_text":
+            _register_ref_text_command(app, spec)
+            continue
+        if spec.signature == "ref_direction":
+            _register_ref_direction_command(app, spec)
+            continue
+        _register_screen_command(app, spec)
+
+
+def _register_ref_command(app: typer.Typer, spec: _ActionCommandSpec) -> None:
+    @app.command(spec.public_command)
+    def action_command(
+        ctx: typer.Context,
+        ref: TargetRefArgument,
+        screen_id: ScreenIdOption = None,
+        workspace_root: WorkspaceRootOption = None,
+    ) -> None:
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=lambda options: run_pipeline.CliCommandRequest(
+                public_command=spec.public_command,
+                command=build_ref_action_command(
+                    kind=cast(RefActionKind, spec.kind),
+                    ref=_parse_ref_or_fail(ref),
+                    source_screen_id=_parse_screen_id_or_fail(screen_id),
+                ),
+                workspace_root=options.workspace_root,
+            ),
+            public_command=spec.public_command,
+        )
+
+
+def _register_ref_text_command(app: typer.Typer, spec: _ActionCommandSpec) -> None:
+    @app.command(spec.public_command)
+    def action_command(
+        ctx: typer.Context,
+        ref: TargetRefArgument,
+        text: TypeTextArgument,
+        screen_id: ScreenIdOption = None,
+        workspace_root: WorkspaceRootOption = None,
+    ) -> None:
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=lambda options: run_pipeline.CliCommandRequest(
+                public_command=spec.public_command,
+                command=build_type_command(
+                    ref=_parse_ref_or_fail(ref),
+                    text=text,
+                    source_screen_id=_parse_screen_id_or_fail(screen_id),
+                ),
+                workspace_root=options.workspace_root,
+            ),
+            public_command=spec.public_command,
+        )
+
+
+def _register_ref_direction_command(
+    app: typer.Typer,
+    spec: _ActionCommandSpec,
+) -> None:
+    @app.command(spec.public_command)
+    def action_command(
+        ctx: typer.Context,
+        ref: ScrollableRefArgument,
+        direction: ScrollDirectionArgument,
+        screen_id: ScreenIdOption = None,
+        workspace_root: WorkspaceRootOption = None,
+    ) -> None:
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=lambda options: run_pipeline.CliCommandRequest(
+                public_command=spec.public_command,
+                command=build_scroll_command(
+                    ref=_parse_ref_or_fail(ref),
+                    direction=_parse_direction_or_fail(
+                        direction,
+                        allowed=SCROLL_DIRECTIONS,
+                    ),
+                    source_screen_id=_parse_screen_id_or_fail(screen_id),
+                ),
+                workspace_root=options.workspace_root,
+            ),
+            public_command=spec.public_command,
+        )
+
+
+def _register_screen_command(app: typer.Typer, spec: _ActionCommandSpec) -> None:
+    @app.command(spec.public_command)
+    def action_command(
+        ctx: typer.Context,
+        screen_id: ScreenIdOption = None,
+        workspace_root: WorkspaceRootOption = None,
+    ) -> None:
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=lambda options: run_pipeline.CliCommandRequest(
+                public_command=spec.public_command,
+                command=build_global_action_command(
+                    kind=cast(GlobalActionKind, spec.kind),
+                    source_screen_id=_parse_screen_id_or_fail(screen_id),
+                ),
+                workspace_root=options.workspace_root,
+            ),
+            public_command=spec.public_command,
+        )
+
+
+def _parse_ref_or_fail(raw_ref: str) -> str:
+    try:
+        return parse_ref(raw_ref)
+    except ValueError as error:
+        emit_usage_error(str(error))
+
+
+def _parse_direction_or_fail(
+    raw_direction: str,
+    *,
+    allowed: Collection[str],
+) -> ScrollDirection:
+    normalized = raw_direction.strip().lower()
+    if normalized not in allowed:
+        emit_usage_error(f"direction must be one of: {', '.join(sorted(allowed))}")
+    return cast(ScrollDirection, normalized)
+
+
+def _parse_screen_id_or_fail(raw_screen_id: str | None) -> str | None:
+    try:
+        return parse_screen_id_override(raw_screen_id)
+    except ValueError as error:
+        emit_usage_error(str(error))

androidctl/commands/adb_wireless.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+from androidctl.exit_codes import ExitCode
+from androidctl.setup import adb as setup_adb
+
+_WORKSPACE_ROOT_HELP = "Accepted for CLI consistency; ignored by wireless ADB helpers."
+
+
+@dataclass(frozen=True)
+class WirelessAdbCommandError(RuntimeError):
+    code: str
+    message: str
+    exit_code: ExitCode = ExitCode.ENVIRONMENT
+
+    def __str__(self) -> str:
+        return self.message
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "adb-pair",
+        help="Auxiliary helper for Android wireless debugging pairing.",
+    )
+    def adb_pair(
+        pair: str | None = typer.Option(
+            None,
+            "--pair",
+            help="Wireless debugging pair endpoint as HOST:PORT.",
+        ),
+        code: str | None = typer.Option(
+            None,
+            "--code",
+            help="Pairing code shown on the Android device.",
+        ),
+        workspace_root: Path | None = typer.Option(
+            None,
+            "--workspace-root",
+            help=_WORKSPACE_ROOT_HELP,
+        ),
+    ) -> None:
+        _ignore_workspace_root(workspace_root)
+        try:
+            _run_adb_pair(pair=pair, code=code)
+        except WirelessAdbCommandError as error:
+            _emit_failure("adb-pair", error)
+
+    @app.command(
+        "adb-connect",
+        help="Auxiliary helper for connecting an already paired wireless ADB device.",
+    )
+    def adb_connect(
+        endpoint: str = typer.Argument(
+            ...,
+            help="Wireless debugging connect endpoint as HOST:PORT.",
+        ),
+        workspace_root: Path | None = typer.Option(
+            None,
+            "--workspace-root",
+            help=_WORKSPACE_ROOT_HELP,
+        ),
+    ) -> None:
+        _ignore_workspace_root(workspace_root)
+        try:
+            _run_adb_connect(endpoint=endpoint)
+        except WirelessAdbCommandError as error:
+            _emit_failure("adb-connect", error)
+
+
+def _run_adb_pair(*, pair: str | None, code: str | None) -> None:
+    pair_endpoint = _required_value(
+        pair,
+        code="ADB_PAIR_ENDPOINT_REQUIRED",
+        message="pair endpoint is required; pass --pair HOST:PAIR_PORT",
+    )
+    pairing_code = _required_value(
+        code,
+        code="ADB_PAIR_CODE_REQUIRED",
+        message=(
+            "pairing code is required; open Android Wireless debugging and pass "
+            "--code"
+        ),
+    )
+    wireless_error: WirelessAdbCommandError | None = None
+    try:
+        setup_adb.pair_wireless_device(
+            pair_endpoint=pair_endpoint,
+            code=pairing_code,
+        )
+    except setup_adb.SetupAdbError as error:
+        wireless_error = _wireless_error_from_adb(error)
+    if wireless_error is not None:
+        raise wireless_error
+    _emit_progress("wireless ADB: paired device")
+
+
+def _run_adb_connect(*, endpoint: str) -> None:
+    connect_endpoint: str | None = None
+    wireless_error: WirelessAdbCommandError | None = None
+    try:
+        connect_endpoint = setup_adb.validate_wireless_endpoint(
+            endpoint,
+            label="connect endpoint",
+        )
+        setup_adb.connect_wireless_device(connect_endpoint=connect_endpoint)
+    except setup_adb.SetupAdbError as error:
+        wireless_error = _wireless_error_from_adb(error)
+    if wireless_error is not None:
+        raise wireless_error
+    if connect_endpoint is None:
+        raise WirelessAdbCommandError(
+            "ADB_CONNECT_FAILED",
+            "adb connect endpoint was not validated",
+        )
+    _emit_progress("wireless ADB: connected device")
+    _emit_progress(f"wireless ADB: run setup with --serial {connect_endpoint}")
+
+
+def _required_value(value: str | None, *, code: str, message: str) -> str:
+    normalized = value.strip() if value is not None else ""
+    if not normalized:
+        raise WirelessAdbCommandError(
+            code=code,
+            message=message,
+            exit_code=ExitCode.USAGE,
+        )
+    return normalized
+
+
+def _wireless_error_from_adb(error: setup_adb.SetupAdbError) -> WirelessAdbCommandError:
+    exit_code = (
+        ExitCode.USAGE
+        if error.code in {"ADB_PAIR_CODE_REQUIRED", "ADB_INVALID_WIRELESS_ENDPOINT"}
+        else ExitCode.ENVIRONMENT
+    )
+    return WirelessAdbCommandError(
+        code=error.code,
+        message=error.message,
+        exit_code=exit_code,
+    )
+
+
+def _ignore_workspace_root(workspace_root: Path | None) -> None:
+    del workspace_root
+
+
+def _emit_progress(message: str) -> None:
+    typer.echo(message, err=True)
+
+
+def _emit_failure(command: str, error: WirelessAdbCommandError) -> None:
+    typer.echo(f"androidctl {command} failed [{error.code}]: {error.message}", err=True)
+    raise typer.Exit(code=int(error.exit_code))

androidctl/commands/close.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from androidctl.cli_options import command_cli_options
+from androidctl.commands import execute, run_pipeline
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("close", help="Retained support route for runtime lifecycle shutdown.")
+    def close(
+        ctx: typer.Context,
+        workspace_root: Path | None = typer.Option(None, "--workspace-root"),
+    ) -> None:
+        options = command_cli_options(ctx, workspace_root=workspace_root)
+        try:
+            outcome = run_pipeline.run_close_command(
+                run_pipeline.build_context(),
+                options.workspace_root,
+            )
+        except typer.Exit:
+            raise
+        except Exception as error:
+            execute.render_exception(error, command="close")
+        execute.render_command_outcome(
+            outcome=outcome,
+            public_command="close",
+        )

androidctl/commands/connect.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from androidctl.cli_options import CliOptions
+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_contracts.daemon_api import ConnectCommandPayload, ConnectionPayload
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "connect",
+        help="Retained support route for starting a device runtime.",
+    )
+    def connect(
+        ctx: typer.Context,
+        adb: bool = typer.Option(False, "--adb", help="Use ADB transport."),
+        token: str = typer.Option(..., "--token", help="Device agent token."),
+        serial: str | None = typer.Option(None, "--serial", help="ADB serial."),
+        host: str | None = typer.Option(None, "--host", help="Device host."),
+        port: int | None = typer.Option(None, "--port", help="Device port."),
+        workspace_root: Path | None = typer.Option(None, "--workspace-root"),
+    ) -> None:
+        def build_request(options: CliOptions) -> run_pipeline.CliCommandRequest:
+            if adb and host:
+                emit_usage_error("--adb cannot be used with --host")
+            if adb and port is not None:
+                emit_usage_error("--adb cannot be used with --port")
+            if not adb and host is None:
+                emit_usage_error("choose --adb or provide --host and --port")
+            if not adb and port is None:
+                emit_usage_error("choose --adb or provide --host and --port")
+            if not adb and serial:
+                emit_usage_error("--serial can only be used with --adb")
+            normalized_token = token.strip()
+            if not normalized_token:
+                emit_usage_error("--token cannot be empty")
+
+            if adb:
+                connection = ConnectionPayload(
+                    mode="adb",
+                    token=normalized_token,
+                    serial=serial,
+                )
+            else:
+                if host is None or port is None:
+                    emit_usage_error("choose --adb or provide --host and --port")
+                connection = ConnectionPayload(
+                    mode="lan",
+                    token=normalized_token,
+                    host=host,
+                    port=port,
+                )
+
+            return run_pipeline.CliCommandRequest(
+                public_command="connect",
+                command=ConnectCommandPayload(kind="connect", connection=connection),
+                workspace_root=options.workspace_root,
+            )
+
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=build_request,
+        )

androidctl/commands/execute.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import NoReturn
+
+import click
+import typer
+
+from androidctl.command_views import pre_dispatch_execution_outcome_for_public_command
+from androidctl.commands import run_pipeline
+from androidctl.errors.mapping import map_exception
+from androidctl.errors.models import ErrorTier
+from androidctl.exit_codes import ExitCode
+from androidctl.output import (
+    CLI_OUTPUT_FAILED,
+    CLI_RENDER_FAILED,
+    CliOutputError,
+    static_cli_failure_xml_bytes,
+    write_stderr_bytes,
+    write_stderr_xml,
+    write_stdout_xml,
+)
+from androidctl.renderers.xml import render_error_text, render_success_text
+
+_RETAINED_ENVIRONMENT_FAILURE_CODES = frozenset(
+    {
+        "WORKSPACE_STATE_UNWRITABLE",
+        "DEVICE_AGENT_UNAUTHORIZED",
+        "DEVICE_AGENT_VERSION_MISMATCH",
+    }
+)
+
+
+def run_and_render(
+    cli_request: run_pipeline.CliCommandRequest,
+    *,
+    public_command: str | None = None,
+) -> None:
+    render_command = public_command or cli_request.public_command
+    try:
+        outcome = run_pipeline.run_command(cli_request, run_pipeline.build_context())
+    except typer.Exit:
+        raise
+    except Exception as error:
+        render_exception(error, command=render_command)
+    render_command_outcome(
+        outcome=outcome,
+        public_command=render_command,
+    )
+
+
+def render_command_outcome(
+    *,
+    outcome: run_pipeline.CommandOutcome,
+    public_command: str,
+) -> None:
+    try:
+        xml_text = render_outcome(payload=outcome.payload)
+    except Exception:
+        _emit_cli_render_failed(command=public_command)
+    try:
+        write_stdout_xml(xml_text)
+    except CliOutputError:
+        _emit_cli_output_failed(command=public_command)
+    _exit_for_command_failure(outcome.payload)
+
+
+def render_outcome(
+    *,
+    payload: dict[str, object],
+) -> str:
+    return render_success_text(payload=payload)
+
+
+def render_exception(
+    error: Exception,
+    *,
+    command: str | None = None,
+    execution_outcome: str | None = None,
+) -> NoReturn:
+    resolved_command = command or _current_public_command()
+    mapped_error = error
+    if isinstance(error, run_pipeline.PreDispatchCommandError):
+        mapped_error = error.cause
+        if execution_outcome is None:
+            execution_outcome = error.execution_outcome or (
+                pre_dispatch_execution_outcome_for_public_command(resolved_command)
+            )
+
+    public_error = map_exception(mapped_error)
+    tier = _error_tier(
+        wrapper=error,
+        mapped_error=mapped_error,
+    )
+    try:
+        xml_text = render_error_text(
+            public_error,
+            command=resolved_command,
+            tier=tier,
+            execution_outcome=execution_outcome,
+        )
+    except Exception:
+        _emit_cli_render_failed(command=resolved_command)
+    try:
+        write_stderr_xml(xml_text)
+    except CliOutputError:
+        _emit_cli_output_failed(command=resolved_command)
+    raise typer.Exit(code=int(public_error.exit_code)) from error
+
+
+def _emit_cli_render_failed(*, command: str | None) -> NoReturn:
+    _emit_static_cli_failure(command=command, code=CLI_RENDER_FAILED)
+
+
+def _emit_cli_output_failed(*, command: str | None) -> NoReturn:
+    _emit_static_cli_failure(command=command, code=CLI_OUTPUT_FAILED)
+
+
+def _emit_static_cli_failure(*, command: str | None, code: str) -> NoReturn:
+    with suppress(CliOutputError):
+        write_stderr_bytes(static_cli_failure_xml_bytes(command=command, code=code))
+    raise typer.Exit(code=int(ExitCode.ENVIRONMENT))
+
+
+def _exit_for_command_failure(payload: dict[str, object]) -> None:
+    if payload.get("ok") is False:
+        raise typer.Exit(code=int(_failure_exit_code(payload)))
+
+
+def _failure_exit_code(payload: dict[str, object]) -> ExitCode:
+    if "envelope" in payload:
+        return _retained_failure_exit_code(payload)
+    return ExitCode.ERROR
+
+
+def _retained_failure_exit_code(payload: dict[str, object]) -> ExitCode:
+    code = payload.get("code")
+    if isinstance(code, str) and code in _RETAINED_ENVIRONMENT_FAILURE_CODES:
+        return ExitCode.ENVIRONMENT
+    return ExitCode.ERROR
+
+
+def emit_usage_error(
+    message: str,
+    *,
+    command: str | None = None,
+    execution_outcome: str | None = None,
+) -> NoReturn:
+    resolved_command = command or _current_public_command()
+    render_exception(
+        click.UsageError(message),
+        command=resolved_command,
+        execution_outcome=execution_outcome
+        or pre_dispatch_execution_outcome_for_public_command(resolved_command),
+    )
+
+
+def _error_tier(
+    *,
+    wrapper: Exception,
+    mapped_error: Exception,
+) -> ErrorTier:
+    if isinstance(mapped_error, click.UsageError):
+        return "usage"
+    if not isinstance(wrapper, run_pipeline.PreDispatchCommandError):
+        return "outer"
+    if wrapper.error_tier == "preDispatch":
+        return "preDispatch"
+    return "outer"
+
+
+def _current_public_command() -> str | None:
+    context = click.get_current_context(silent=True)
+    if context is None:
+        return None
+    command_name = context.info_name
+    if isinstance(command_name, str) and command_name:
+        return command_name
+    return None

androidctl/commands/list_apps.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from androidctl.commands import run_pipeline
+from androidctl.commands.plumbing import build_and_run_command
+from androidctl_contracts.daemon_api import ListAppsCommandPayload
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("list-apps")
+    def list_apps(
+        ctx: typer.Context,
+        workspace_root: Path | None = typer.Option(None, "--workspace-root"),
+    ) -> None:
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=lambda options: run_pipeline.CliCommandRequest(
+                public_command="list-apps",
+                command=ListAppsCommandPayload(kind="listApps"),
+                workspace_root=options.workspace_root,
+            ),
+        )