androidctl 0.1.0__py3-none-any.whl

androidctl/commands/observe.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 ObserveCommandPayload
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("observe")
+    def observe(
+        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="observe",
+                command=ObserveCommandPayload(kind="observe"),
+                workspace_root=options.workspace_root,
+            ),
+        )

androidctl/commands/open.py

@@ -0,0 +1,41 @@
+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.parsing.open_target import parse_open_target
+from androidctl_contracts.daemon_api import OpenCommandPayload
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("open")
+    def open_target(
+        ctx: typer.Context,
+        target: str = typer.Argument(
+            ...,
+            help="Target app:..., url:<target>, or bare http(s)://...",
+        ),
+        workspace_root: Path | None = typer.Option(None, "--workspace-root"),
+    ) -> None:
+        def build_request(options: CliOptions) -> run_pipeline.CliCommandRequest:
+            try:
+                parsed_target = parse_open_target(target)
+            except ValueError as error:
+                emit_usage_error(str(error))
+
+            return run_pipeline.CliCommandRequest(
+                public_command="open",
+                command=OpenCommandPayload(kind="open", target=parsed_target),
+                workspace_root=options.workspace_root,
+            )
+
+        build_and_run_command(
+            ctx=ctx,
+            workspace_root=workspace_root,
+            build_request=build_request,
+        )

androidctl/commands/plumbing.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import typer
+from pydantic import ValidationError
+
+from androidctl.cli_options import CliOptions, command_cli_options
+from androidctl.commands import run_pipeline
+from androidctl.commands.execute import emit_usage_error, run_and_render
+
+RequestBuilder = Callable[[CliOptions], run_pipeline.CliCommandRequest]
+
+
+def build_and_run_command(
+    *,
+    ctx: typer.Context,
+    workspace_root: Path | None,
+    build_request: RequestBuilder,
+    public_command: str | None = None,
+) -> None:
+    options = command_cli_options(
+        ctx,
+        workspace_root=workspace_root,
+    )
+    try:
+        request = build_request(options)
+    except ValidationError as error:
+        emit_usage_error(
+            _validation_error_message(error),
+            command=public_command or _context_command_name(ctx),
+        )
+    run_and_render(
+        request,
+        public_command=public_command or _context_command_name(ctx),
+    )
+
+
+def _context_command_name(ctx: typer.Context) -> str | None:
+    command_name = ctx.info_name
+    if isinstance(command_name, str) and command_name:
+        return command_name
+    return None
+
+
+def _validation_error_message(error: ValidationError) -> str:
+    details = error.errors(include_url=False)
+    if not details:
+        return str(error)
+    first = details[0]
+    location = ".".join(
+        str(part) for part in first.get("loc", ()) if part != "__root__"
+    ).strip(".")
+    message = str(first.get("msg", "invalid input"))
+    if not location:
+        return message
+    return f"{location}: {message}"

androidctl/commands/run_pipeline.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NoReturn, Protocol
+
+import click
+import httpx
+from pydantic import ValidationError
+
+from androidctl.command_payloads import (
+    CliCommandPayload,
+    LateBoundActionCommand,
+    LateBoundGlobalActionCommand,
+    LateBoundWaitCommand,
+)
+from androidctl.daemon.client import (
+    DaemonApiError,
+    DaemonProtocolError,
+    IncompatibleDaemonError,
+)
+from androidctl.daemon.discovery import (
+    discover_existing_daemon_client,
+    resolve_daemon_client,
+)
+from androidctl.errors.models import ErrorTier
+from androidctl.workspace.resolve import resolve_workspace_root
+from androidctl_contracts.command_catalog import runtime_close_entry
+from androidctl_contracts.command_results import (
+    CommandResultCore,
+    ListAppsResult,
+    RetainedResultEnvelope,
+    dump_canonical_command_result,
+)
+from androidctl_contracts.daemon_api import (
+    CommandRunRequest,
+    RuntimePayload,
+)
+
+CommandResultPayload = CommandResultCore | RetainedResultEnvelope | ListAppsResult
+
+
+class RuntimeCommandClient(Protocol):
+    def get_runtime(self) -> RuntimePayload: ...
+
+    def run_command(
+        self,
+        *,
+        request: CommandRunRequest,
+    ) -> CommandResultPayload: ...
+
+    def close_runtime(self) -> RetainedResultEnvelope: ...
+
+
+class PreDispatchCommandError(Exception):
+    def __init__(
+        self,
+        cause: Exception,
+        *,
+        execution_outcome: str | None = None,
+        error_tier: ErrorTier | None = None,
+    ) -> None:
+        super().__init__(str(cause))
+        self.cause = cause
+        self.execution_outcome = execution_outcome
+        self.error_tier = error_tier
+
+
+@dataclass(frozen=True)
+class CliCommandRequest:
+    public_command: str
+    command: CliCommandPayload
+    workspace_root: Path | None = None
+
+
+@dataclass(frozen=True)
+class CommandOutcome:
+    payload: dict[str, object]
+
+
+@dataclass(frozen=True)
+class AppContext:
+    daemon: RuntimeCommandClient | None
+    cwd: Path
+    env: Mapping[str, str]
+    daemon_discovery: Callable[[Path], RuntimeCommandClient] | None = None
+
+
+def build_context() -> AppContext:
+    return AppContext(
+        daemon=None,
+        cwd=Path.cwd(),
+        env=os.environ,
+        daemon_discovery=lambda workspace_root: resolve_daemon_client(
+            workspace_root=workspace_root,
+            cwd=Path.cwd(),
+            env=os.environ,
+        ),
+    )
+
+
+def run_command(cli_request: CliCommandRequest, ctx: AppContext) -> CommandOutcome:
+    try:
+        workspace_root = resolve_runtime_paths(cli_request.workspace_root, ctx)
+    except (OSError, ValueError) as error:
+        _raise_pre_dispatch_error(error, cli_request.command)
+
+    try:
+        daemon = _resolve_command_daemon(ctx, workspace_root)
+    except (DaemonApiError, click.ClickException, OSError, ValidationError) as error:
+        _raise_pre_dispatch_error(error, cli_request.command)
+
+    try:
+        runtime_payload = daemon.get_runtime()
+    except (
+        DaemonApiError,
+        DaemonProtocolError,
+        OSError,
+        ValidationError,
+        httpx.HTTPStatusError,
+        httpx.RequestError,
+    ) as error:
+        _raise_pre_dispatch_error(error, cli_request.command)
+
+    try:
+        prepared_request = _prepare_ref_bound_request(cli_request, runtime_payload)
+    except DaemonApiError as error:
+        _raise_pre_dispatch_error(
+            error,
+            cli_request.command,
+            error_tier=_late_bind_error_tier(error),
+        )
+
+    try:
+        command_request = _build_command_run_request(prepared_request.command)
+    except ValidationError as error:
+        _raise_pre_dispatch_error(error, cli_request.command)
+
+    result = daemon.run_command(request=command_request)
+    return CommandOutcome(payload=_dump_command_result(result))
+
+
+def run_close_command(
+    ctx: AppContext,
+    workspace_root_override: Path | None,
+) -> CommandOutcome:
+    workspace_root = resolve_runtime_paths(workspace_root_override, ctx)
+    daemon = ctx.daemon
+    if daemon is None:
+        daemon = discover_existing_daemon_client(
+            workspace_root=workspace_root,
+            env=ctx.env,
+        )
+    result = _close_result(daemon)
+    return CommandOutcome(payload=_dump_command_result(result))
+
+
+def resolve_runtime_paths(
+    workspace_root_override: Path | None,
+    ctx: AppContext,
+) -> Path:
+    return resolve_workspace_root(
+        flag_value=workspace_root_override,
+        env_value=ctx.env.get("ANDROIDCTL_WORKSPACE_ROOT"),
+        cwd=ctx.cwd,
+    )
+
+
+def _prepare_ref_bound_request(
+    cli_request: CliCommandRequest,
+    runtime_payload: RuntimePayload,
+) -> CliCommandRequest:
+    bound_command = bind_screen_relative_command(cli_request.command, runtime_payload)
+    if bound_command is cli_request.command:
+        return cli_request
+    return CliCommandRequest(
+        public_command=cli_request.public_command,
+        command=bound_command,
+        workspace_root=cli_request.workspace_root,
+    )
+
+
+def bind_screen_relative_command(
+    command: CliCommandPayload,
+    runtime_payload: RuntimePayload,
+) -> CliCommandPayload:
+    if not isinstance(
+        command,
+        (
+            LateBoundActionCommand,
+            LateBoundGlobalActionCommand,
+            LateBoundWaitCommand,
+        ),
+    ):
+        return command
+
+    if isinstance(command, LateBoundGlobalActionCommand):
+        return command.bind(_live_screen_id(runtime_payload))
+
+    return command.bind(_required_live_screen_id(runtime_payload))
+
+
+def _required_live_screen_id(runtime_payload: RuntimePayload) -> str:
+    live_screen_id = _live_screen_id(runtime_payload)
+    if live_screen_id is not None:
+        return live_screen_id
+    status = runtime_payload.status.strip().lower()
+    if status in {"ready", "connected"}:
+        raise DaemonApiError(
+            code="SCREEN_NOT_READY",
+            message="screen is not ready yet",
+            details={},
+        )
+    raise DaemonApiError(
+        code="RUNTIME_NOT_CONNECTED",
+        message="runtime is not connected to a device",
+        details={},
+    )
+
+
+def _live_screen_id(runtime_payload: RuntimePayload) -> str | None:
+    status = runtime_payload.status.strip().lower()
+    current_screen_id = runtime_payload.current_screen_id
+    if status != "ready" or not isinstance(current_screen_id, str):
+        return None
+    normalized_screen_id = current_screen_id.strip()
+    return normalized_screen_id or None
+
+
+def _resolve_command_daemon(
+    ctx: AppContext,
+    workspace_root: Path,
+) -> RuntimeCommandClient:
+    if ctx.daemon is not None:
+        return ctx.daemon
+    if ctx.daemon_discovery is None:
+        raise click.ClickException("unable to start or discover androidctld daemon")
+    try:
+        return ctx.daemon_discovery(workspace_root)
+    except (DaemonApiError, IncompatibleDaemonError):
+        raise
+    except (FileNotFoundError, OSError, RuntimeError, ValidationError) as error:
+        raise click.ClickException(
+            f"unable to start or discover androidctld daemon: {error}"
+        ) from error
+
+
+def _build_command_run_request(command: CliCommandPayload) -> CommandRunRequest:
+    if isinstance(
+        command,
+        (
+            LateBoundActionCommand,
+            LateBoundGlobalActionCommand,
+            LateBoundWaitCommand,
+        ),
+    ):
+        raise RuntimeError("prepared command was not bound to a live screen")
+    return CommandRunRequest.model_validate(
+        {"command": command.model_dump(exclude_none=True, exclude_defaults=True)}
+    )
+
+
+def _raise_pre_dispatch_error(
+    error: Exception,
+    command: CliCommandPayload,
+    *,
+    error_tier: ErrorTier | None = None,
+) -> NoReturn:
+    del command
+    raise PreDispatchCommandError(
+        error,
+        execution_outcome=None,
+        error_tier=error_tier,
+    ) from error
+
+
+def _late_bind_error_tier(error: DaemonApiError) -> ErrorTier | None:
+    if error.code in {"RUNTIME_NOT_CONNECTED", "SCREEN_NOT_READY"}:
+        return "preDispatch"
+    return None
+
+
+def _dump_command_result(result: CommandResultPayload) -> dict[str, object]:
+    if isinstance(result, CommandResultCore):
+        return dump_canonical_command_result(result)
+    return result.model_dump(by_alias=True, mode="json", exclude_none=True)
+
+
+def _close_result(
+    daemon: RuntimeCommandClient | None,
+) -> RetainedResultEnvelope:
+    if daemon is not None:
+        return daemon.close_runtime()
+    close_entry = runtime_close_entry()
+    if close_entry.retained_envelope_kind is None:
+        raise RuntimeError("runtime close command must use a retained envelope")
+    return RetainedResultEnvelope.model_validate(
+        {
+            "ok": True,
+            "command": close_entry.result_command,
+            "envelope": close_entry.retained_envelope_kind.value,
+            "artifacts": {},
+            "details": {},
+        }
+    )

androidctl/commands/screenshot.py

@@ -0,0 +1,29 @@
+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 ScreenshotCommandPayload
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "screenshot",
+        help="Retained support route that captures an explicit screenshot artifact.",
+    )
+    def screenshot(
+        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="screenshot",
+                command=ScreenshotCommandPayload(kind="screenshot"),
+                workspace_root=options.workspace_root,
+            ),
+        )