androidctl 0.1.0__py3-none-any.whl

androidctld/artifacts/screen_lookup.py

@@ -0,0 +1,241 @@
+"""Read-only source screen artifact lookup."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import ValidationError
+
+from androidctld.artifacts.screen_payloads import ScreenArtifactPayload
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime.screen_state import current_artifacts
+
+ArtifactScanStatus = Literal["valid", "malformed", "unreadable"]
+SourceScreenArtifactStatus = Literal["found", "not_found", "invalid_artifact"]
+
+
+@dataclass(frozen=True)
+class ScannedArtifactPath:
+    path: Path
+
+
+@dataclass(frozen=True)
+class ScreenArtifactScan:
+    path: Path
+    status: ArtifactScanStatus
+    screen_id: str | None
+    sequence: int | None
+    payload: ScreenArtifactPayload | None = None
+
+
+@dataclass(frozen=True)
+class ScannedScreenArtifact:
+    candidate: ScannedArtifactPath
+    artifact: ScreenArtifactScan
+
+
+@dataclass(frozen=True)
+class SourceScreenArtifactLookup:
+    status: SourceScreenArtifactStatus
+    source_screen_id: str
+    path: Path | None = None
+    payload: ScreenArtifactPayload | None = None
+    scanned: tuple[ScannedScreenArtifact, ...] = ()
+
+
+def lookup_source_screen_artifact(
+    session: WorkspaceRuntime,
+    source_screen_id: str,
+) -> SourceScreenArtifactLookup:
+    """Find the newest source artifact without mutating artifact storage."""
+
+    matching_candidates: list[ScreenArtifactScan] = []
+    unknown_screen_candidates: list[ScreenArtifactScan] = []
+    scanned_candidates: list[ScannedScreenArtifact] = []
+    for candidate in screen_artifact_candidates(session):
+        if not candidate.path.exists():
+            continue
+        artifact = scan_screen_artifact(candidate.path)
+        scanned_candidates.append(
+            ScannedScreenArtifact(candidate=candidate, artifact=artifact)
+        )
+        if artifact.screen_id == source_screen_id:
+            matching_candidates.append(artifact)
+            continue
+        if artifact.screen_id is None and artifact.status != "valid":
+            unknown_screen_candidates.append(artifact)
+            continue
+
+    scanned = tuple(scanned_candidates)
+    if not matching_candidates:
+        return SourceScreenArtifactLookup(
+            status="not_found",
+            source_screen_id=source_screen_id,
+            scanned=scanned,
+        )
+
+    unknown_sequence_invalid = [
+        artifact for artifact in unknown_screen_candidates if artifact.sequence is None
+    ]
+    if unknown_sequence_invalid:
+        selected = sorted(
+            unknown_sequence_invalid,
+            key=lambda artifact: artifact.path.name,
+            reverse=True,
+        )[0]
+        return SourceScreenArtifactLookup(
+            status="invalid_artifact",
+            source_screen_id=source_screen_id,
+            path=selected.path,
+            scanned=scanned,
+        )
+
+    matching_candidates.sort(
+        key=lambda artifact: (
+            -1 if artifact.sequence is None else artifact.sequence,
+            artifact.path.name,
+        ),
+        reverse=True,
+    )
+    selected_match = matching_candidates[0]
+
+    if unknown_screen_candidates:
+        unknown_screen_candidates.sort(
+            key=lambda artifact: (
+                -1 if artifact.sequence is None else artifact.sequence,
+                artifact.path.name,
+            ),
+            reverse=True,
+        )
+        selected_unknown = unknown_screen_candidates[0]
+    else:
+        selected_unknown = None
+
+    if selected_unknown is not None:
+        unknown_sequence = selected_unknown.sequence
+        match_sequence = selected_match.sequence
+        if (
+            unknown_sequence is None
+            or match_sequence is None
+            or unknown_sequence >= match_sequence
+        ):
+            return SourceScreenArtifactLookup(
+                status="invalid_artifact",
+                source_screen_id=source_screen_id,
+                path=selected_unknown.path,
+                scanned=scanned,
+            )
+
+    selected = selected_match
+    if selected.status != "valid":
+        return SourceScreenArtifactLookup(
+            status="invalid_artifact",
+            source_screen_id=source_screen_id,
+            path=selected.path,
+            scanned=scanned,
+        )
+    if selected.payload is None:
+        raise RuntimeError("valid source screen artifact is missing payload")
+    return SourceScreenArtifactLookup(
+        status="found",
+        source_screen_id=source_screen_id,
+        path=selected.path,
+        payload=selected.payload,
+        scanned=scanned,
+    )
+
+
+def screen_artifact_candidates(
+    session: WorkspaceRuntime,
+) -> list[ScannedArtifactPath]:
+    candidates: dict[Path, ScannedArtifactPath] = {}
+
+    def add_candidate(path: Path) -> None:
+        resolved = path.resolve()
+        candidates.setdefault(resolved, ScannedArtifactPath(path=path))
+
+    current_artifact_bag = current_artifacts(session)
+    current_artifact = (
+        None if current_artifact_bag is None else current_artifact_bag.screen_json
+    )
+    if current_artifact is not None:
+        current_artifact_path = Path(current_artifact)
+        if is_internal_screen_artifact_path(current_artifact_path):
+            add_candidate(current_artifact_path)
+
+    screens_dir = session.artifact_root / "screens"
+    if screens_dir.exists():
+        for path in sorted(screens_dir.glob("obs-*.json")):
+            add_candidate(path)
+
+    return list(candidates.values())
+
+
+def scan_screen_artifact(path: Path) -> ScreenArtifactScan:
+    try:
+        raw_payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError:
+        return ScreenArtifactScan(
+            path=path,
+            status="unreadable",
+            screen_id=None,
+            sequence=sequence_from_artifact_path(path),
+        )
+    except ValueError:
+        return ScreenArtifactScan(
+            path=path,
+            status="malformed",
+            screen_id=None,
+            sequence=sequence_from_artifact_path(path),
+        )
+
+    if not isinstance(raw_payload, dict):
+        return ScreenArtifactScan(
+            path=path,
+            status="malformed",
+            screen_id=None,
+            sequence=sequence_from_artifact_path(path),
+        )
+
+    screen_id = raw_payload.get("screenId")
+    screen_id_hint = screen_id if isinstance(screen_id, str) else None
+    sequence = raw_payload.get("sequence")
+    sequence_hint = (
+        sequence
+        if isinstance(sequence, int) and not isinstance(sequence, bool)
+        else sequence_from_artifact_path(path)
+    )
+    try:
+        payload = ScreenArtifactPayload.model_validate_json(json.dumps(raw_payload))
+    except ValidationError:
+        return ScreenArtifactScan(
+            path=path,
+            status="malformed",
+            screen_id=screen_id_hint,
+            sequence=sequence_hint,
+        )
+
+    return ScreenArtifactScan(
+        path=path,
+        status="valid",
+        screen_id=payload.screen_id,
+        sequence=payload.sequence,
+        payload=payload,
+    )
+
+
+def sequence_from_artifact_path(path: Path) -> int | None:
+    name = path.name
+    if not name.startswith("obs-") or not name.endswith(".json"):
+        return None
+    digits = name[4:-5]
+    if not digits.isdigit():
+        return None
+    return int(digits)
+
+
+def is_internal_screen_artifact_path(path: Path) -> bool:
+    return sequence_from_artifact_path(path) is not None

androidctld/artifacts/screen_payloads.py

@@ -0,0 +1,109 @@
+"""Payload builders for persisted screen artifacts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from androidctld.refs.models import (
+    RefBinding,
+    RefFingerprint,
+    RefRegistry,
+    SemanticProfile,
+)
+from androidctld.schema import ApiModel
+from androidctld.semantics.public_models import PublicGroup, PublicScreen
+
+
+class RepairFingerprintPayload(ApiModel):
+    role: str
+    normalized_label: str
+    resource_id: str
+    class_name: str
+    parent_role: str
+    parent_label: str
+    sibling_labels: tuple[str, ...] = Field(default_factory=tuple)
+    relative_bounds: tuple[int, int, int, int]
+
+
+class RepairSemanticProfilePayload(ApiModel):
+    state: tuple[str, ...] = Field(default_factory=tuple)
+    actions: tuple[str, ...] = Field(default_factory=tuple)
+
+
+class RepairBindingPayload(ApiModel):
+    fingerprint: RepairFingerprintPayload
+    semantic_profile: RepairSemanticProfilePayload
+
+
+class ScreenArtifactPayload(ApiModel):
+    model_config = ConfigDict(extra="forbid")
+
+    screen_id: str
+    sequence: int
+    source_snapshot_id: int
+    captured_at: str
+    package_name: str | None
+    activity_name: str | None
+    keyboard_visible: bool
+    groups: tuple[PublicGroup, ...]
+    repair_bindings: dict[str, RepairBindingPayload] = Field(default_factory=dict)
+
+
+def build_repair_fingerprint_payload(
+    fingerprint: RefFingerprint,
+) -> RepairFingerprintPayload:
+    return RepairFingerprintPayload(
+        role=fingerprint.role,
+        normalized_label=fingerprint.normalized_label,
+        resource_id=fingerprint.resource_id,
+        class_name=fingerprint.class_name,
+        parent_role=fingerprint.parent_role,
+        parent_label=fingerprint.parent_label,
+        sibling_labels=fingerprint.sibling_labels,
+        relative_bounds=fingerprint.relative_bounds,
+    )
+
+
+def build_repair_semantic_profile_payload(
+    semantic_profile: SemanticProfile,
+) -> RepairSemanticProfilePayload:
+    return RepairSemanticProfilePayload(
+        state=semantic_profile.state,
+        actions=semantic_profile.actions,
+    )
+
+
+def build_repair_binding_payload(binding: RefBinding) -> RepairBindingPayload:
+    return RepairBindingPayload(
+        fingerprint=build_repair_fingerprint_payload(binding.fingerprint),
+        semantic_profile=build_repair_semantic_profile_payload(
+            binding.semantic_profile
+        ),
+    )
+
+
+def build_screen_artifact_payload(
+    public_screen: PublicScreen,
+    ref_registry: RefRegistry,
+    *,
+    sequence: int,
+    source_snapshot_id: int,
+    captured_at: str,
+) -> dict[str, Any]:
+    payload = ScreenArtifactPayload(
+        screen_id=public_screen.screen_id,
+        sequence=sequence,
+        source_snapshot_id=source_snapshot_id,
+        captured_at=captured_at,
+        package_name=public_screen.app.package_name,
+        activity_name=public_screen.app.activity_name,
+        keyboard_visible=public_screen.surface.keyboard_visible,
+        groups=public_screen.groups,
+        repair_bindings={
+            ref: build_repair_binding_payload(binding)
+            for ref, binding in ref_registry.bindings.items()
+        },
+    )
+    return payload.model_dump(by_alias=True, mode="json")

androidctld/artifacts/writer.py

@@ -0,0 +1,286 @@
+"""Screen artifact rendering and persistence."""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+
+from androidctld.artifacts.models import ScreenArtifacts
+from androidctld.artifacts.screen_payloads import build_screen_artifact_payload
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.refs.models import RefRegistry
+from androidctld.rendering.screen_xml import render_screen_xml
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime_policy import SCREENSHOT_MAX_BINARY_BYTES
+from androidctld.semantics.public_models import PublicScreen
+
+
+@dataclass
+class StagedArtifactWrite:
+    artifacts: ScreenArtifacts
+    file_updates: tuple[StagedFileUpdate, ...] = ()
+
+    def commit(self) -> None:
+        for update in self.file_updates:
+            update.commit()
+
+    def discard(self) -> None:
+        for update in self.file_updates:
+            update.discard()
+
+    def rollback(self) -> None:
+        for update in reversed(self.file_updates):
+            update.rollback()
+
+
+@dataclass
+class StagedFileUpdate:
+    staged_path: Path
+    final_path: Path
+    backup_path: Path | None = None
+    original_backed_up: bool = False
+    final_replaced: bool = False
+
+    def commit(self) -> None:
+        self.final_path.parent.mkdir(parents=True, exist_ok=True)
+        if self.backup_path is not None:
+            try:
+                self.final_path.replace(self.backup_path)
+            except FileNotFoundError:
+                pass
+            else:
+                self.original_backed_up = True
+        try:
+            self.staged_path.replace(self.final_path)
+        except Exception:
+            if self.original_backed_up and self.backup_path is not None:
+                self.backup_path.replace(self.final_path)
+                self.original_backed_up = False
+            raise
+        self.final_replaced = True
+
+    def rollback(self) -> None:
+        if not self.final_replaced:
+            return
+        if self.original_backed_up and self.backup_path is not None:
+            with suppress(FileNotFoundError):
+                self.final_path.unlink()
+            self.backup_path.replace(self.final_path)
+            self.original_backed_up = False
+            self.final_replaced = False
+            return
+        with suppress(FileNotFoundError):
+            self.final_path.unlink()
+        self.final_replaced = False
+
+    def discard(self) -> None:
+        for path in (self.staged_path, self.backup_path):
+            if path is None:
+                continue
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                continue
+
+
+class ArtifactWriter:
+    def stage_screen(
+        self,
+        session: WorkspaceRuntime,
+        public_screen: PublicScreen,
+        *,
+        sequence: int,
+        source_snapshot_id: int,
+        captured_at: str,
+        ref_registry: RefRegistry | None = None,
+    ) -> StagedArtifactWrite:
+        token = uuid.uuid4().hex
+        staged_screen_json = self.stage_screen_json_update(
+            session,
+            public_screen,
+            sequence=sequence,
+            source_snapshot_id=source_snapshot_id,
+            captured_at=captured_at,
+            ref_registry=ref_registry,
+            token=token,
+        )
+        staged_screen_xml = self.stage_screen_xml_update(
+            session,
+            public_screen,
+            sequence=sequence,
+            token=token,
+        )
+
+        artifacts = ScreenArtifacts(
+            screen_json=staged_screen_json.final_path.as_posix(),
+            screen_xml=staged_screen_xml.final_path.as_posix(),
+        )
+        return StagedArtifactWrite(
+            artifacts=artifacts,
+            file_updates=(staged_screen_json, staged_screen_xml),
+        )
+
+    def stage_screen_json_update(
+        self,
+        session: WorkspaceRuntime,
+        public_screen: PublicScreen,
+        *,
+        sequence: int,
+        source_snapshot_id: int,
+        captured_at: str,
+        ref_registry: RefRegistry | None = None,
+        token: str | None = None,
+    ) -> StagedFileUpdate:
+        screens_dir = session.artifact_root / "screens"
+        screens_dir.mkdir(parents=True, exist_ok=True)
+        write_token = token or uuid.uuid4().hex
+        json_path = screens_dir / f"{artifact_stem(sequence)}.json"
+        staged_json_path = staged_path_for(json_path, write_token)
+        write_json_file(
+            staged_json_path,
+            build_screen_artifact_payload(
+                public_screen,
+                ref_registry or RefRegistry(),
+                sequence=sequence,
+                source_snapshot_id=source_snapshot_id,
+                captured_at=captured_at,
+            ),
+        )
+        return StagedFileUpdate(
+            staged_path=staged_json_path,
+            final_path=json_path,
+            backup_path=backup_path_for(json_path, write_token),
+        )
+
+    def stage_screen_xml_update(
+        self,
+        session: WorkspaceRuntime,
+        public_screen: PublicScreen,
+        *,
+        sequence: int,
+        token: str | None = None,
+    ) -> StagedFileUpdate:
+        screens_dir = session.artifact_root / "artifacts" / "screens"
+        screens_dir.mkdir(parents=True, exist_ok=True)
+        write_token = token or uuid.uuid4().hex
+        xml_path = screens_dir / f"{artifact_stem(sequence)}.xml"
+        staged_xml_path = staged_path_for(xml_path, write_token)
+        write_text_file(staged_xml_path, render_screen_xml(public_screen))
+        return StagedFileUpdate(
+            staged_path=staged_xml_path,
+            final_path=xml_path,
+            backup_path=backup_path_for(xml_path, write_token),
+        )
+
+    def write_screenshot_png(self, session: WorkspaceRuntime, body: bytes) -> Path:
+        if len(body) > SCREENSHOT_MAX_BINARY_BYTES:
+            raise ValueError(
+                f"screenshot PNG exceeds {SCREENSHOT_MAX_BINARY_BYTES} byte budget"
+            )
+        screenshots_dir = session.artifact_root / "screenshots"
+        try:
+            screenshots_dir.mkdir(parents=True, exist_ok=True)
+            if not screenshots_dir.is_dir():
+                raise _artifact_root_unwritable("namespace-not-directory")
+        except DaemonError:
+            raise
+        except Exception as error:
+            raise _artifact_root_unwritable("namespace-create-failed") from error
+
+        try:
+            next_index = _next_screenshot_index(screenshots_dir)
+        except Exception as error:
+            raise _artifact_root_unwritable("namespace-scan-failed") from error
+        binary_flag = getattr(os, "O_BINARY", 0)
+        while True:
+            try:
+                candidate = (screenshots_dir / f"shot-{next_index:05d}.png").resolve()
+            except Exception as error:
+                raise _artifact_write_failed("candidate-resolve-failed") from error
+            fd: int | None = None
+            handle = None
+            try:
+                fd = os.open(
+                    candidate,
+                    os.O_CREAT | os.O_EXCL | os.O_WRONLY | binary_flag,
+                )
+            except FileExistsError:
+                next_index += 1
+                continue
+            except Exception as error:
+                raise _artifact_write_failed("candidate-open-failed") from error
+            failure_reason = "candidate-fdopen-failed"
+            try:
+                handle = os.fdopen(fd, "wb")
+                fd = None
+                failure_reason = "candidate-write-failed"
+                handle.write(body)
+                failure_reason = "candidate-flush-failed"
+                handle.flush()
+                failure_reason = "candidate-close-failed"
+                handle.close()
+                return candidate
+            except Exception as error:
+                if handle is not None:
+                    with suppress(Exception):
+                        handle.close()
+                if fd is not None:
+                    with suppress(OSError):
+                        os.close(fd)
+                with suppress(OSError):
+                    candidate.unlink()
+                raise _artifact_write_failed(failure_reason) from error
+
+
+def _next_screenshot_index(screenshots_dir: Path) -> int:
+    highest_index = 0
+    for path in screenshots_dir.glob("shot-*.png"):
+        suffix = path.stem.removeprefix("shot-")
+        if not suffix.isdigit():
+            continue
+        highest_index = max(highest_index, int(suffix))
+    return highest_index + 1
+
+
+def _artifact_root_unwritable(reason: str) -> DaemonError:
+    return DaemonError(
+        code=DaemonErrorCode.ARTIFACT_ROOT_UNWRITABLE,
+        message="artifact root is not writable",
+        details={"reason": reason},
+    )
+
+
+def _artifact_write_failed(reason: str) -> DaemonError:
+    return DaemonError(
+        code=DaemonErrorCode.ARTIFACT_WRITE_FAILED,
+        message="artifact write failed",
+        details={"reason": reason},
+    )
+
+
+def staged_path_for(final_path: Path, token: str) -> Path:
+    return final_path.with_name(f"{final_path.name}.tmp-{token}")
+
+
+def backup_path_for(final_path: Path, token: str) -> Path:
+    return final_path.with_name(f"{final_path.name}.bak-{token}")
+
+
+def artifact_stem(sequence: int) -> str:
+    return f"obs-{sequence:05d}"
+
+
+def write_json_file(path: Path, payload: dict[str, object]) -> None:
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+
+
+def write_text_file(path: Path, payload: str) -> None:
+    with path.open("w", encoding="utf-8") as handle:
+        handle.write(payload)
+        handle.write("\n")

androidctld/auth/__init__.py

@@ -0,0 +1 @@
+"""Authentication helpers for androidctld."""