androidctl 0.1.0__py3-none-any.whl

androidctl/errors/mapping.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import click
+import httpx
+
+from androidctl.daemon.client import (
+    DaemonApiError,
+    DaemonProtocolError,
+    IncompatibleDaemonError,
+)
+from androidctl.errors.models import PublicError
+from androidctl.exit_codes import ExitCode
+
+
+@dataclass(frozen=True)
+class _MappedCode:
+    code: str
+    exit_code: ExitCode
+    hint: str | None = None
+    message: str | None = None
+
+
+_DAEMON_CODE_TABLE: Mapping[str, _MappedCode] = {
+    # This table only applies to daemon error envelopes, not semantic result codes.
+    "DAEMON_BAD_REQUEST": _MappedCode("DAEMON_UNAVAILABLE", ExitCode.ENVIRONMENT),
+    "WORKSPACE_BUSY": _MappedCode(
+        "WORKSPACE_BUSY",
+        ExitCode.ERROR,
+        "close the conflicting workspace daemon or use a different workspace",
+    ),
+    "RUNTIME_BUSY": _MappedCode(
+        "RUNTIME_BUSY",
+        ExitCode.ERROR,
+        "wait for the active progress command to finish, then retry",
+    ),
+    "RUNTIME_NOT_CONNECTED": _MappedCode(
+        "DEVICE_NOT_CONNECTED",
+        ExitCode.ENVIRONMENT,
+        "re-run `androidctl connect`",
+    ),
+    "SCREEN_NOT_READY": _MappedCode(
+        "SCREEN_UNAVAILABLE",
+        ExitCode.ERROR,
+        "run `androidctl observe` to refresh the current screen",
+    ),
+    "REF_RESOLUTION_FAILED": _MappedCode(
+        "REF_NOT_FOUND",
+        ExitCode.ERROR,
+        "run `androidctl observe` and choose a ref from the latest screen",
+    ),
+    "WORKSPACE_UNAVAILABLE": _MappedCode("WORKSPACE_UNAVAILABLE", ExitCode.ENVIRONMENT),
+    "ARTIFACT_ROOT_UNWRITABLE": _MappedCode(
+        "WORKSPACE_STATE_UNWRITABLE", ExitCode.ENVIRONMENT
+    ),
+    "DEVICE_DISCONNECTED": _MappedCode(
+        "DEVICE_NOT_CONNECTED",
+        ExitCode.ENVIRONMENT,
+    ),
+    "DEVICE_AGENT_UNAVAILABLE": _MappedCode(
+        "DEVICE_AGENT_UNAVAILABLE", ExitCode.ENVIRONMENT
+    ),
+    "DEVICE_AGENT_VERSION_MISMATCH": _MappedCode(
+        "DEVICE_AGENT_VERSION_MISMATCH",
+        ExitCode.ENVIRONMENT,
+        "install matching androidctld and Android agent/APK versions",
+    ),
+    "DEVICE_AGENT_UNAUTHORIZED": _MappedCode(
+        "DAEMON_UNAVAILABLE",
+        ExitCode.ENVIRONMENT,
+        "re-run androidctl connect to refresh daemon-to-device authorization",
+        "device agent rejected daemon authorization",
+    ),
+    "ACCESSIBILITY_NOT_READY": _MappedCode("ACCESSIBILITY_NOT_READY", ExitCode.ERROR),
+    "DAEMON_UNAUTHORIZED": _MappedCode("DAEMON_UNAVAILABLE", ExitCode.ENVIRONMENT),
+    "INTERNAL_COMMAND_FAILURE": _MappedCode(
+        "DAEMON_UNAVAILABLE",
+        ExitCode.ENVIRONMENT,
+        "retry the command; if it keeps failing, inspect daemon logs",
+        "androidctld failed while handling the request",
+    ),
+    "DEVICE_RPC_TRANSPORT_RESET": _MappedCode(
+        "DAEMON_UNAVAILABLE",
+        ExitCode.ENVIRONMENT,
+        "retry the command after the daemon is available",
+        "device RPC transport was reset",
+    ),
+}
+
+
+def map_exception(error: Exception) -> PublicError:
+    if isinstance(error, click.UsageError):
+        return PublicError(
+            code="USAGE_ERROR",
+            message=error.format_message(),
+            hint=None,
+            exit_code=ExitCode.USAGE,
+        )
+    if isinstance(error, DaemonApiError):
+        return _map_daemon_api_error(error)
+    if isinstance(error, IncompatibleDaemonError):
+        return PublicError(
+            code="DAEMON_UNAVAILABLE",
+            message=str(error),
+            hint="install matching androidctl and androidctld versions",
+            exit_code=ExitCode.ENVIRONMENT,
+        )
+    if isinstance(error, (httpx.RequestError, httpx.HTTPStatusError)):
+        return PublicError(
+            code="DAEMON_UNAVAILABLE",
+            message="unable to reach androidctld daemon",
+            hint="retry the command after the daemon is available",
+            exit_code=ExitCode.ENVIRONMENT,
+        )
+    if isinstance(
+        error,
+        (DaemonProtocolError, click.ClickException, RuntimeError, OSError),
+    ):
+        return PublicError(
+            code="DAEMON_UNAVAILABLE",
+            message=str(error),
+            hint="retry the command after the daemon is available",
+            exit_code=ExitCode.ENVIRONMENT,
+        )
+    return PublicError(
+        code="DAEMON_UNAVAILABLE",
+        message=str(error),
+        hint="retry the command after the daemon is available",
+        exit_code=ExitCode.ENVIRONMENT,
+    )
+
+
+def _map_daemon_api_error(error: DaemonApiError) -> PublicError:
+    mapped = _DAEMON_CODE_TABLE.get(error.code)
+    if mapped is None:
+        return PublicError(
+            code="DAEMON_UNAVAILABLE",
+            message=error.message,
+            hint="retry the command after the daemon is available",
+            exit_code=ExitCode.ENVIRONMENT,
+        )
+    return PublicError(
+        code=mapped.code,
+        message=mapped.message or error.message,
+        hint=mapped.hint,
+        exit_code=mapped.exit_code,
+    )

androidctl/errors/models.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from androidctl.exit_codes import ExitCode
+
+ErrorTier = Literal["usage", "preDispatch", "outer"]
+
+
+@dataclass(frozen=True)
+class PublicError:
+    code: str
+    message: str
+    hint: str | None
+    exit_code: ExitCode

androidctl/exit_codes.py

@@ -0,0 +1,8 @@
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    ERROR = 1
+    USAGE = 2
+    ENVIRONMENT = 3

androidctl/output.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from typing import Literal
+from xml.sax.saxutils import escape
+
+import click
+
+CLI_RENDER_FAILED = "CLI_RENDER_FAILED"
+CLI_OUTPUT_FAILED = "CLI_OUTPUT_FAILED"
+
+CLI_RENDER_FAILED_MESSAGE = "androidctl failed while rendering command output"
+CLI_OUTPUT_FAILED_MESSAGE = "androidctl failed while writing command output"
+
+_RETAINED_FALLBACK_ENVELOPES = {
+    "connect": "bootstrap",
+    "screenshot": "artifact",
+    "close": "lifecycle",
+}
+
+_SEMANTIC_FALLBACK_CATEGORIES = {
+    "observe": "observe",
+    "open": "open",
+    "tap": "transition",
+    "long-tap": "transition",
+    "focus": "transition",
+    "type": "transition",
+    "submit": "transition",
+    "scroll": "transition",
+    "back": "transition",
+    "home": "transition",
+    "recents": "transition",
+    "notifications": "transition",
+    "wait": "wait",
+}
+
+_LIST_APPS_FALLBACK_COMMAND = "list-apps"
+
+
+class CliOutputError(Exception):
+    def __init__(self, stream_name: str) -> None:
+        super().__init__(stream_name)
+        self.stream_name = stream_name
+
+
+def xml_text_to_utf8_bytes(xml_text: str) -> bytes:
+    try:
+        return xml_text.encode("utf-8") + b"\n"
+    except Exception as error:
+        raise CliOutputError("encoding") from error
+
+
+def write_stdout_xml(xml_text: str) -> None:
+    write_stdout_bytes(xml_text_to_utf8_bytes(xml_text))
+
+
+def write_stderr_xml(xml_text: str) -> None:
+    write_stderr_bytes(xml_text_to_utf8_bytes(xml_text))
+
+
+def write_stdout_bytes(data: bytes) -> None:
+    _write_binary_stream("stdout", data)
+
+
+def write_stderr_bytes(data: bytes) -> None:
+    _write_binary_stream("stderr", data)
+
+
+def static_cli_failure_xml_bytes(*, command: str | None, code: str) -> bytes:
+    message = (
+        CLI_RENDER_FAILED_MESSAGE
+        if code == CLI_RENDER_FAILED
+        else CLI_OUTPUT_FAILED_MESSAGE
+    )
+    public_command = _fallback_public_command(command)
+    xml_text = _static_cli_failure_xml(
+        command=public_command,
+        code=code,
+        message=message,
+    )
+    return xml_text.encode("ascii") + b"\n"
+
+
+def _write_binary_stream(
+    stream_name: Literal["stdout", "stderr"],
+    data: bytes,
+) -> None:
+    try:
+        stream = click.get_binary_stream(stream_name)
+        written = stream.write(data)
+        if isinstance(written, int) and written < len(data):
+            raise OSError("short write")
+        stream.flush()
+    except Exception as error:
+        raise CliOutputError(stream_name) from error
+
+
+def _static_cli_failure_xml(*, command: str, code: str, message: str) -> str:
+    if command == _LIST_APPS_FALLBACK_COMMAND:
+        return (
+            f'<errorResult ok="false" code="{_xml_attr(code)}" '
+            'exitCode="3" tier="outer" '
+            f'command="{_xml_attr(command)}">'
+            f"<message>{_xml_text(message)}</message>"
+            "</errorResult>"
+        )
+
+    retained_envelope = _RETAINED_FALLBACK_ENVELOPES.get(command)
+    if retained_envelope is not None:
+        return (
+            f'<retainedResult ok="false" command="{_xml_attr(command)}" '
+            f'envelope="{_xml_attr(retained_envelope)}" code="{_xml_attr(code)}">'
+            f"<message>{_xml_text(message)}</message>"
+            "<artifacts />"
+            "</retainedResult>"
+        )
+
+    category = _SEMANTIC_FALLBACK_CATEGORIES.get(command, "transition")
+    return (
+        f'<result ok="false" command="{_xml_attr(command)}" '
+        f'category="{_xml_attr(category)}" payloadMode="none" '
+        f'code="{_xml_attr(code)}">'
+        f"<message>{_xml_text(message)}</message>"
+        '<truth executionOutcome="unknown" continuityStatus="none" '
+        'observationQuality="none" />'
+        "<uncertainty />"
+        "<warnings />"
+        "<artifacts />"
+        "</result>"
+    )
+
+
+def _fallback_public_command(command: str | None) -> str:
+    if command == _LIST_APPS_FALLBACK_COMMAND:
+        return command
+    if command in _RETAINED_FALLBACK_ENVELOPES:
+        return command
+    if command in _SEMANTIC_FALLBACK_CATEGORIES:
+        return command
+    return "observe"
+
+
+def _xml_attr(value: str) -> str:
+    return escape(value, {'"': "&quot;"})
+
+
+def _xml_text(value: str) -> str:
+    return escape(value)

androidctl/parsing/__init__.py

@@ -0,0 +1 @@
+"""Command argument parsing helpers."""

androidctl/parsing/duration.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import re
+
+_DURATION_RE = re.compile(r"^(?P<value>\d+)(?P<unit>ms|s)$")
+
+
+def parse_duration_ms(raw: str) -> int:
+    normalized = raw.strip().lower()
+    match = _DURATION_RE.fullmatch(normalized)
+    if match is None:
+        raise ValueError("duration must use an integer followed by ms or s")
+    value = int(match.group("value"))
+    unit = match.group("unit")
+    if unit == "ms":
+        return value
+    return value * 1000

androidctl/parsing/open_target.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from urllib.parse import SplitResult, urlsplit
+
+from androidctl_contracts.daemon_api import (
+    OpenAppTargetPayload,
+    OpenTargetPayload,
+    OpenUrlTargetPayload,
+)
+
+
+def parse_open_target(raw_target: str) -> OpenTargetPayload:
+    target = raw_target.strip()
+    if not target:
+        raise ValueError("open target cannot be empty")
+    if target.startswith("app:"):
+        package_name = target[len("app:") :].strip()
+        if not package_name:
+            raise ValueError("app target must include a package name")
+        return OpenAppTargetPayload(kind="app", value=package_name)
+    if target.startswith("url:"):
+        url = target[len("url:") :].strip()
+        if not url:
+            raise ValueError("url target must not be empty")
+        return OpenUrlTargetPayload(kind="url", value=url)
+    if _is_http_url(target):
+        return OpenUrlTargetPayload(kind="url", value=target)
+    raise ValueError(
+        "target must be app:<package>, url:<target>, or absolute http(s)://..."
+    )
+
+
+def _is_http_url(value: str) -> bool:
+    if any(char.isspace() for char in value):
+        return False
+    parsed = urlsplit(value)
+    if parsed.scheme not in {"http", "https"}:
+        return False
+    return _is_valid_http_url(parsed)
+
+
+def _is_valid_http_url(parsed: SplitResult) -> bool:
+    if not parsed.netloc:
+        return False
+    if not parsed.hostname or any(char.isspace() for char in parsed.hostname):
+        return False
+    try:
+        _ = parsed.port
+    except ValueError:
+        return False
+    return True

androidctl/parsing/refs.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import re
+
+REF_PATTERN = re.compile(r"^n[1-9][0-9]*$")
+
+
+def parse_ref(raw_ref: str) -> str:
+    value = raw_ref.strip()
+    if not REF_PATTERN.fullmatch(value):
+        raise ValueError("ref must match n<number>, for example n3")
+    return value

androidctl/parsing/screen_id.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+def parse_screen_id_override(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    if not normalized:
+        raise ValueError("--screen-id must be non-empty")
+    return normalized

androidctl/parsing/wait.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from androidctl.command_payloads import (
+    CliWaitPredicatePayload,
+    LateBoundScreenRelativePredicate,
+)
+from androidctl.parsing.refs import parse_ref
+from androidctl.parsing.screen_id import parse_screen_id_override
+from androidctl_contracts.daemon_api import (
+    AppPredicatePayload,
+    GonePredicatePayload,
+    IdlePredicatePayload,
+    ScreenChangePredicatePayload,
+    TextPresentPredicatePayload,
+)
+
+_WAIT_PREDICATES = {"app", "gone", "idle", "screen-change", "text-present"}
+
+
+def parse_wait_predicate(
+    until: str,
+    *,
+    ref: str | None = None,
+    text: str | None = None,
+    package_name: str | None = None,
+    source_screen_id: str | None = None,
+) -> CliWaitPredicatePayload:
+    normalized_until = until.strip().lower()
+    if normalized_until not in _WAIT_PREDICATES:
+        allowed = ", ".join(sorted(_WAIT_PREDICATES))
+        raise ValueError(f"wait predicate must be one of: {allowed}")
+
+    if normalized_until == "screen-change":
+        normalized_source_screen_id = parse_screen_id_override(source_screen_id)
+        if normalized_source_screen_id is None:
+            return LateBoundScreenRelativePredicate(kind="screen-change")
+        return ScreenChangePredicatePayload(
+            kind="screen-change",
+            source_screen_id=normalized_source_screen_id,
+        )
+
+    if normalized_until == "gone":
+        if ref is None or not ref.strip():
+            raise ValueError("gone wait requires --ref")
+        normalized_source_screen_id = parse_screen_id_override(source_screen_id)
+        if normalized_source_screen_id is None:
+            return LateBoundScreenRelativePredicate(
+                kind="gone",
+                ref=parse_ref(ref),
+            )
+        return GonePredicatePayload(
+            kind="gone",
+            ref=parse_ref(ref),
+            source_screen_id=normalized_source_screen_id,
+        )
+
+    if normalized_until == "text-present":
+        if text is None or not text.strip():
+            raise ValueError("text-present wait requires --text")
+        return TextPresentPredicatePayload(kind="text-present", text=text)
+
+    if normalized_until == "app":
+        if package_name is None or not package_name.strip():
+            raise ValueError("app wait requires --app")
+        return AppPredicatePayload(
+            kind="app",
+            package_name=package_name.strip(),
+        )
+
+    return IdlePredicatePayload(kind="idle")

androidctl/renderers/__init__.py

@@ -0,0 +1,110 @@
+"""Public renderer entrypoints and semantic projection helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TypeAlias
+
+from pydantic import BaseModel
+
+from androidctl.renderers._paths import normalize_public_path
+from androidctl_contracts.command_catalog import entry_for_result_command
+from androidctl_contracts.command_results import (
+    CommandResultCore,
+    ListAppsResult,
+    RetainedResultEnvelope,
+    dump_canonical_command_result,
+)
+from androidctl_contracts.vocabulary import PublicResultFamily
+
+_PATH_KEYS = {"screenshotPng", "screenXml"}
+RenderPayload: TypeAlias = BaseModel | Mapping[str, object]
+ProjectionValue: TypeAlias = (
+    str
+    | int
+    | float
+    | bool
+    | None
+    | list["ProjectionValue"]
+    | dict[str, "ProjectionValue"]
+)
+ProjectionDict: TypeAlias = dict[str, ProjectionValue]
+
+
+def projection_dict(
+    payload: RenderPayload,
+) -> ProjectionDict:
+    validated = _validated_payload(payload)
+    if isinstance(validated, CommandResultCore):
+        dumped = dump_canonical_command_result(validated)
+    elif isinstance(validated, (RetainedResultEnvelope, ListAppsResult)):
+        dumped = validated.model_dump(by_alias=True, mode="json", exclude_none=True)
+    else:
+        dumped = validated.model_dump(mode="json", exclude_none=True)
+    return _normalize_mapping(dumped)
+
+
+def _validated_payload(payload: RenderPayload) -> BaseModel:
+    string_keyed = _string_keyed_payload(payload)
+    command = string_keyed.get("command")
+    if isinstance(command, str):
+        entry = entry_for_result_command(command)
+        if entry is not None and entry.result_family is PublicResultFamily.RETAINED:
+            return RetainedResultEnvelope.model_validate(string_keyed)
+        if entry is not None and entry.result_family is PublicResultFamily.LIST_APPS:
+            return ListAppsResult.model_validate(string_keyed)
+    return CommandResultCore.model_validate(string_keyed)
+
+
+def _string_keyed_payload(payload: RenderPayload) -> dict[str, object]:
+    if isinstance(payload, BaseModel):
+        dumped = payload.model_dump(mode="json", by_alias=True)
+        if not isinstance(dumped, Mapping):
+            raise TypeError("renderer payload model must dump to a mapping")
+        return {key: item for key, item in dumped.items() if isinstance(key, str)}
+    if isinstance(payload, Mapping):
+        return {key: item for key, item in payload.items() if isinstance(key, str)}
+    raise TypeError("renderer payload must be a pydantic model or mapping")
+
+
+def _normalize_mapping(value: Mapping[str, object]) -> ProjectionDict:
+    normalized: ProjectionDict = {}
+    for key, item in value.items():
+        if key in _PATH_KEYS and isinstance(item, str):
+            normalized[key] = _normalize_path(item)
+            continue
+        normalized[key] = _normalize_value(item)
+    return normalized
+
+
+def _normalize_sequence(value: Sequence[object]) -> list[ProjectionValue]:
+    return [_normalize_value(item) for item in value]
+
+
+def _normalize_value(value: object) -> ProjectionValue:
+    if isinstance(value, Mapping):
+        string_keyed = {
+            key: item for key, item in value.items() if isinstance(key, str)
+        }
+        return _normalize_mapping(string_keyed)
+    if isinstance(value, Sequence) and not isinstance(value, str):
+        return _normalize_sequence(value)
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    raise TypeError(f"unsupported renderer projection value: {type(value).__name__}")
+
+
+def _normalize_path(path: str) -> str:
+    normalized = path.replace("\\", "/")
+    marker = "/.androidctl/"
+    marker_index = normalized.rfind(marker)
+    workspace_root = normalized[:marker_index] if marker_index >= 0 else None
+    artifact_root = (
+        f"{workspace_root}/.androidctl" if workspace_root is not None else None
+    )
+    public_path = normalize_public_path(
+        normalized,
+        workspace_root=workspace_root,
+        artifact_root=artifact_root,
+    )
+    return public_path or normalized