android-midscene-automation 0.2.4 → 1.1.0

package/artemis-main/artemis/interfaces/cli/commands/doctor.py

@@ -0,0 +1,468 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""System, environment, and device diagnostics (artemis doctor).
+
+The command renders the same readiness probes the web console's device wizard
+and the ``mobile_diagnose`` MCP tool run (:mod:`artemis.core.diagnostics`), so
+the terminal, the browser and the IDE agree on one verdict. Only two rows are
+CLI-specific and not engine probes: Node.js/npm and the Showcase UI build.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+import json
+import platform as sys_platform
+import shutil
+import subprocess
+from typing import Any
+
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+import typer
+
+from artemis.config.paths import ROOT_DIR
+from artemis.core.diagnostics.engine import readiness_engine
+from artemis.core.diagnostics.readiness import (
+    Verdict,
+    adb_keys_corrupted,
+    base_verdict,
+    collect_readiness,
+    sort_by_fix_order,
+)
+from artemis.core.diagnostics.schema import ProbeResult, ProbeStatus
+from artemis.platform import OSType, platform
+from artemis.runtime.device_lock import DeviceExecutionLock
+
+
+@dataclass(frozen=True)
+class ExtraRow:
+    """A CLI-only diagnostic row that is not backed by an engine probe."""
+
+    key: str
+    title: str
+    status: str  # "pass" | "missing"
+    status_markup: str
+    summary: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class FixOutcome:
+    """Result of one ``--fix`` repair step."""
+
+    fix: str
+    success: bool
+    message: str
+
+
+# ---------------------------------------------------------------------------
+# Collection
+# ---------------------------------------------------------------------------
+
+
+async def _collect() -> list[ProbeResult]:
+    report, host = await collect_readiness()
+    return sort_by_fix_order([*report.probes, host])
+
+
+async def _apply_fixes(results: list[ProbeResult]) -> list[FixOutcome]:
+    """Repair corrupted ADB keys and sweep stale device locks left by dead runners."""
+    outcomes: list[FixOutcome] = []
+
+    if adb_keys_corrupted(results):
+        result = await readiness_engine.heal_adb_keys()
+        outcomes.append(
+            FixOutcome(
+                fix="heal_adb_keys",
+                success=bool(result.get("success")),
+                message=str(result.get("message") or "")
+                or ("Corrupted RSA keys regenerated." if result.get("success") else "Heal failed."),
+            )
+        )
+    else:
+        outcomes.append(
+            FixOutcome(
+                fix="heal_adb_keys",
+                success=True,
+                message="ADB authentication keys are healthy; nothing to repair.",
+            )
+        )
+
+    removed = await asyncio.to_thread(DeviceExecutionLock.cleanup_stale_locks)
+    outcomes.append(
+        FixOutcome(
+            fix="cleanup_stale_locks",
+            success=True,
+            message=(
+                f"Removed {removed} stale device lock(s)/queue ticket(s)."
+                if removed
+                else "No stale device locks or queue tickets found."
+            ),
+        )
+    )
+    return outcomes
+
+
+async def _diagnose(fix: bool) -> tuple[list[ProbeResult], list[FixOutcome]]:
+    results = await _collect()
+    fixes: list[FixOutcome] = []
+    if fix:
+        fixes = await _apply_fixes(results)
+        results = await _collect()
+    return results, fixes
+
+
+# ---------------------------------------------------------------------------
+# CLI-only extra rows (not engine probes)
+# ---------------------------------------------------------------------------
+
+
+def _npm_row() -> ExtraRow:
+    npm_path = shutil.which("npm")
+    if npm_path:
+        return ExtraRow(
+            key="nodejs_npm",
+            title="Node.js / npm",
+            status="pass",
+            status_markup="[bold green]✔ Installed[/bold green]",
+            summary="Installed",
+            detail=f"{npm_path} (Ready to build Showcase UI)",
+        )
+    hint = (
+        "winget install OpenJS.NodeJS.LTS"
+        if platform.os_type == OSType.WINDOWS
+        else "brew install node"
+        if platform.os_type == OSType.MACOS
+        else "sudo apt-get install -y nodejs npm"
+    )
+    return ExtraRow(
+        key="nodejs_npm",
+        title="Node.js / npm",
+        status="missing",
+        status_markup="[dim]⚪ Optional[/dim]",
+        summary="Not Found",
+        detail=f"Not found in PATH. ({hint})",
+    )
+
+
+def _showcase_row() -> ExtraRow:
+    from artemis.resources import get_bundled_showcase_dist
+
+    base_dist = ROOT_DIR / "apps" / "showcase_ui" / "dist"
+    candidates = [
+        base_dist / "frontend" / "browser" / "index.html",
+        base_dist / "browser" / "index.html",
+        base_dist / "frontend" / "index.html",
+        base_dist / "index.html",
+    ]
+    found_showcase = next((p for p in candidates if p.exists()), None)
+    if found_showcase is None:
+        bundled_showcase = get_bundled_showcase_dist()
+        if bundled_showcase is not None:
+            found_showcase = bundled_showcase / "index.html"
+    if found_showcase:
+        return ExtraRow(
+            key="showcase_ui",
+            title="Showcase UI",
+            status="pass",
+            status_markup="[bold green]✔ Compiled[/bold green]",
+            summary="Compiled",
+            detail=f"{found_showcase.parent} (Angular ready)",
+        )
+    return ExtraRow(
+        key="showcase_ui",
+        title="Showcase UI",
+        status="missing",
+        status_markup="[bold yellow]○ Not Compiled[/bold yellow]",
+        summary="Not Compiled",
+        detail="Run ./start.sh or artemis ui to auto-compile.",
+    )
+
+
+def _helper_row(results: list[ProbeResult]) -> ExtraRow | None:
+    """State of the Artemis accessibility helper on the one ready, idle device.
+
+    Tasks install the helper themselves when they take a device; this row lets a
+    person pre-install it so the first task does not pay the install delay, and
+    tells them the helper is a thing they can remove.
+    """
+    from artemis.clients.screen_client_factory import resolve_backend
+    from artemis.runtime.helper_manager import helper_manager
+
+    if resolve_backend().value == "uiautomator":
+        return None
+    adb = next((r for r in results if r.id == "android_adb"), None)
+    devices = (adb.metadata.get("devices") if adb else None) or []
+    ready = [str(d.get("serial")) for d in devices if d.get("state") == "device"]
+    if len(ready) != 1:
+        return None
+    serial = ready[0]
+    try:
+        status = helper_manager.status(serial)
+    except (OSError, ValueError, subprocess.SubprocessError) as exc:
+        return ExtraRow(
+            key="accessibility_helper",
+            title="Artemis Accessibility Helper",
+            status="missing",
+            status_markup="[dim]⚪ Unknown[/dim]",
+            summary="Could not read",
+            detail=f"{serial}: {exc}",
+        )
+    healthy = status["installed"] and status["enabled"] and not status["outdated"]
+    if healthy and status["reachable"]:
+        version = status.get("installed_version")
+        note = " (newer than the bundled build)" if status.get("newer_than_bundled") else ""
+        return ExtraRow(
+            key="accessibility_helper",
+            title="Artemis Accessibility Helper",
+            status="pass",
+            status_markup="[bold green]✔ Ready[/bold green]",
+            summary=f"v{version} on {serial}{note}",
+            detail=f"Remove any time with: artemis helper uninstall --serial {serial}",
+        )
+    if not status["installed"]:
+        summary, why = "Not installed", "the first task on this device will install it (about 3 s)"
+    elif status["outdated"]:
+        summary = f"Outdated (v{status['installed_version']} < v{status['bundled_version']})"
+        why = "the next task will upgrade it"
+    elif not status["enabled"]:
+        summary, why = "Service disabled", "the next task will try to enable it"
+    else:
+        summary, why = "Not answering", "unlock the phone or reinstall with --force"
+    return ExtraRow(
+        key="accessibility_helper",
+        title="Artemis Accessibility Helper",
+        status="missing",
+        status_markup="[bold yellow]○ Pending[/bold yellow]",
+        summary=summary,
+        detail=f"{why}; pre-install now: artemis helper install --serial {serial}",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+
+def _status_markup(result: ProbeResult) -> str:
+    status = result.status
+    if status is ProbeStatus.PASS:
+        return "[bold green]✔ OK[/bold green]"
+    if status is ProbeStatus.SKIPPED:
+        return "[dim]○ Skipped[/dim]"
+    summary = escape(result.summary)
+    if status is ProbeStatus.WARN:
+        # A warning keeps its summary whether or not it blocks (the host
+        # probe's warnings degrade the verdict without blocking it).
+        return f"[bold yellow]⚠ {summary}[/bold yellow]"
+    if not result.is_blocker:
+        return "[dim]⚪ Optional[/dim]"
+    return f"[bold red]✖ {summary}[/bold red]"
+
+
+def _action_lines(result: ProbeResult) -> list[str]:
+    """One plain-text line per remediation; ``&&`` chains split for PowerShell 5.1."""
+    lines: list[str] = []
+    for action in result.actions:
+        payload = action.payload.strip()
+        if not payload:
+            continue
+        if action.action_type == "command":
+            for part in payload.split("&&"):
+                if part.strip():
+                    lines.append(f"Run: {part.strip()}")
+        else:
+            lines.append(payload)
+    return lines
+
+
+def _details_markup(result: ProbeResult) -> str:
+    # Only summary/description/actions are ever rendered. Probe metadata can
+    # carry raw credentials (the console prefills its settings form from it)
+    # and must never reach a terminal or a log.
+    parts = [escape(result.description)]
+    if result.status is not ProbeStatus.PASS:
+        for line in _action_lines(result):
+            if line.startswith("Run: "):
+                parts.append(f"[bold cyan]Run:[/bold cyan] {escape(line[len('Run: ') :])}")
+            else:
+                parts.append(escape(line))
+    return "\n".join(parts)
+
+
+def _render_table(results: list[ProbeResult], extras: list[ExtraRow]) -> Table:
+    table = Table(show_header=True, header_style="bold magenta")
+    table.add_column("Component", style="dim", min_width=22, max_width=30)
+    table.add_column("Status", min_width=12, max_width=28)
+    table.add_column("Details & Recommendations", overflow="fold")
+    for result in results:
+        table.add_row(escape(result.title), _status_markup(result), _details_markup(result))
+    for extra in extras:
+        table.add_row(extra.title, extra.status_markup, escape(extra.detail))
+    return table
+
+
+def _render_fixes(console: Console, fixes: list[FixOutcome]) -> None:
+    lines = []
+    for outcome in fixes:
+        mark = "[bold green]✔[/bold green]" if outcome.success else "[bold red]✖[/bold red]"
+        lines.append(f"{mark} {escape(outcome.fix)}: {escape(outcome.message)}")
+    console.print(Panel("\n".join(lines), title="Repairs (--fix)", expand=False))
+    console.print()
+
+
+def _render_footer(console: Console, verdict: Verdict, results: list[ProbeResult]) -> None:
+    if verdict == "ready":
+        console.print(
+            Panel(
+                "[bold green]🎉 All system checks passed![/bold green]\n\n"
+                "Run your first automation task now:\n"
+                '  [bold cyan]artemis run "Open Settings and check Battery level"[/bold cyan]',
+                title="Status: Ready",
+                expand=False,
+            )
+        )
+        return
+
+    if verdict == "degraded":
+        console.print(
+            Panel(
+                "[bold green]Required checks passed.[/bold green] Optional components are "
+                "missing; tasks can run, but some features (video replay, OCR) are off.\n\n"
+                "Run your first automation task now:\n"
+                '  [bold cyan]artemis run "Open Settings and check Battery level"[/bold cyan]',
+                title="Status: Ready (optional gaps)",
+                expand=False,
+            )
+        )
+        return
+
+    failing = [r.title for r in results if r.is_blocker and r.status is not ProbeStatus.PASS]
+    tips = [
+        "[bold yellow]💡 Blocking issues:[/bold yellow] " + escape(", ".join(failing)),
+        "",
+        "• API keys & device setup: run [bold cyan]artemis init[/bold cyan].",
+        "• Follow the [bold cyan]Run:[/bold cyan] lines above, then re-run "
+        "[bold cyan]artemis doctor[/bold cyan].",
+        "• Using an IDE (Claude Code, Cursor, ...)? Ask it to call "
+        "[bold cyan]mobile_diagnose[/bold cyan] - it runs these same checks and can "
+        "apply safe fixes from the assistant.",
+    ]
+    if adb_keys_corrupted(results):
+        tips.append(
+            "• Corrupted ADB keys detected: run [bold cyan]artemis doctor --fix[/bold cyan]."
+        )
+    console.print(Panel("\n".join(tips), title="Action Required", expand=False))
+
+
+def _json_document(
+    results: list[ProbeResult],
+    extras: list[ExtraRow],
+    fixes: list[FixOutcome],
+    verdict: Verdict,
+) -> dict[str, Any]:
+    # Metadata is intentionally omitted: it may hold raw API keys.
+    checks = [
+        {
+            "id": r.id,
+            "title": r.title,
+            "status": r.status.value,
+            "required": r.is_blocker,
+            "summary": r.summary,
+            "detail": r.description,
+            "fix": []
+            if r.status is ProbeStatus.PASS
+            else [
+                {"type": a.action_type, "label": a.label, "payload": a.payload} for a in r.actions
+            ],
+        }
+        for r in results
+    ]
+    return {
+        "verdict": verdict,
+        "checks": checks,
+        "extras": {
+            e.key: {
+                "title": e.title,
+                "status": e.status,
+                "summary": e.summary,
+                "detail": e.detail,
+            }
+            for e in extras
+        },
+        "fixes": [{"fix": f.fix, "success": f.success, "message": f.message} for f in fixes],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+def doctor_command(
+    fix: bool = typer.Option(
+        False,
+        "--fix",
+        "-f",
+        help=(
+            "Automatically repair fixable environment issues (corrupted ADB authentication "
+            "keys, stale device locks left by crashed runners)."
+        ),
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the diagnosis as a JSON document instead of a table.",
+    ),
+) -> None:
+    """Run diagnostics to inspect system dependencies, device connectivity, and configuration."""
+    results, fixes = asyncio.run(_diagnose(fix))
+    extras = [_npm_row(), _showcase_row()]
+    helper_row = _helper_row(results)
+    if helper_row is not None:
+        extras.append(helper_row)
+    verdict = base_verdict(results)
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                _json_document(results, extras, fixes, verdict), indent=2, ensure_ascii=False
+            )
+        )
+    else:
+        console = Console()
+        console.print()
+        os_name = sys_platform.system()
+        arch_name = sys_platform.machine()
+        console.print(
+            Panel(
+                f"[bold cyan]☕ Artemis System & Environment Doctor[/bold cyan]\n"
+                f"[dim]Platform: {os_name} ({arch_name}) | PAL: {platform.os_type.value}[/dim]",
+                expand=False,
+            )
+        )
+        if fixes:
+            _render_fixes(console, fixes)
+        console.print(_render_table(results, extras))
+        console.print()
+        _render_footer(console, verdict, results)
+        console.print()
+
+    if verdict == "blocked":
+        raise typer.Exit(code=1)

package/artemis-main/artemis/interfaces/cli/commands/helper.py

@@ -0,0 +1,226 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""``artemis helper``: manage the Accessibility Helper APK on attached devices.
+
+Tasks provision the helper themselves when they take a device, so these
+commands exist for the cases the automatic path deliberately leaves alone:
+inspecting a device, forcing a reinstall, and removing the helper (which is
+never done automatically).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+from rich.console import Console
+from rich.table import Table
+import typer
+
+from artemis.runtime.device_pool import device_pool
+from artemis.runtime.helper_manager import helper_manager
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+helper_app = typer.Typer(help="Install, inspect, or remove the Artemis Accessibility Helper APK.")
+
+SerialOption = Annotated[
+    str | None,
+    typer.Option("--serial", "-s", help="Device serial. Defaults to the only ready device."),
+]
+
+
+def _resolve_serial(serial: str | None) -> str:
+    if serial:
+        return serial
+    ready = [d.serial for d in device_pool.get_ready_devices()]
+    if len(ready) == 1:
+        return ready[0]
+    if not ready:
+        typer.secho("No authorized device is attached.", fg=typer.colors.RED)
+    else:
+        typer.secho(
+            "Several devices are ready; pass --serial, or --all to target every idle one: "
+            + ", ".join(ready),
+            fg=typer.colors.RED,
+        )
+    raise typer.Exit(code=1)
+
+
+def _idle_ready_serials() -> list[str]:
+    """Every authorized device that no Artemis task currently holds."""
+    return [d.serial for d in device_pool.get_ready_devices() if not d.is_busy]
+
+
+def _bool(value: object) -> str:
+    return "[green]yes[/green]" if value else "[red]no[/red]"
+
+
+@helper_app.command("status")
+def helper_status(
+    serial: SerialOption = None,
+    as_json: Annotated[bool, typer.Option("--json", help="Print raw JSON.")] = False,
+) -> None:
+    """Show install, version, service and tunnel state of the helper on a device."""
+    target = _resolve_serial(serial)
+    status = helper_manager.status(target)
+    if as_json:
+        typer.echo(json.dumps(status, indent=2))
+        return
+    table = Table(title=f"Accessibility helper on {target}")
+    table.add_column("Field", style="cyan")
+    table.add_column("Value")
+    table.add_row("Installed", _bool(status["installed"]))
+    version = str(status["installed_version"])
+    if status.get("newer_than_bundled"):
+        version += f"  [yellow](newer than the bundled v{status['bundled_version']}; not downgraded)[/yellow]"
+    elif status.get("outdated"):
+        version += f"  [yellow](bundled is v{status['bundled_version']}; the next task upgrades it)[/yellow]"
+    table.add_row("Installed version", version)
+    table.add_row("Bundled version", str(status["bundled_version"]))
+    table.add_row("Service enabled", _bool(status["enabled"]))
+    tunnel = {
+        "session": f"this process, host port {status['forward_port']}",
+        "shared": f"another Artemis process, host port {status['forward_port']}",
+        "probe": "none (probed through a temporary forward)",
+        None: "none",
+    }[status.get("tunnel")]
+    table.add_row("Tunnel", tunnel)
+    table.add_row("Service answering", _bool(status["reachable"]))
+    if status.get("reachable"):
+        protocol = status.get("protocol_version")
+        proto_text = str(protocol)
+        if not status.get("protocol_supported"):
+            proto_text += "  [red](too old for this host; reinstall with --force)[/red]"
+        table.add_row("Protocol", proto_text)
+        table.add_row("Session token pushed", _bool(status.get("token_set")))
+    table.add_row("Auto-install by tasks", _bool(status.get("auto_install", True)))
+    table.add_row("Transport id", str(status["transport_id"]))
+    Console().print(table)
+
+
+def _install_one(target: str, force: bool) -> bool:
+    def on_event(event: str, details: dict) -> None:
+        if event == "installing":
+            typer.echo(f"{target}: installing v{details.get('version_name')}...")
+        elif event == "upgrading":
+            typer.echo(
+                f"{target}: upgrading v{details.get('from_version')} -> "
+                f"v{details.get('to_version')}..."
+            )
+
+    result = helper_manager.provision(target, force=force, on_event=on_event)
+    if result.ok:
+        typer.secho(
+            f"{target}: {result.action} (version {result.installed_version}, service enabled).",
+            fg=typer.colors.GREEN,
+        )
+        return True
+    typer.secho(f"{target}: {result.action}: {result.error}", fg=typer.colors.RED)
+    return False
+
+
+@helper_app.command("install")
+def helper_install(
+    serial: SerialOption = None,
+    force: Annotated[bool, typer.Option("--force", help="Reinstall even when up to date.")] = False,
+    all_devices: Annotated[
+        bool, typer.Option("--all", help="Every authorized device that no task is using.")
+    ] = False,
+) -> None:
+    """Install or upgrade the helper to the bundled version and enable its service."""
+    if all_devices:
+        targets = _idle_ready_serials()
+        if not targets:
+            typer.secho("No idle, authorized device is attached.", fg=typer.colors.RED)
+            raise typer.Exit(code=1)
+    else:
+        targets = [_resolve_serial(serial)]
+    outcomes = [_install_one(target, force) for target in targets]
+    if not all(outcomes):
+        raise typer.Exit(code=1)
+
+
+@helper_app.command("uninstall")
+def helper_uninstall(
+    serial: SerialOption = None,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Do not ask for confirmation.")] = False,
+) -> None:
+    """Disable the service and remove the helper package from a device."""
+    target = _resolve_serial(serial)
+    if not yes and not typer.confirm(f"Remove the Artemis accessibility helper from {target}?"):
+        raise typer.Exit(code=0)
+    if helper_manager.uninstall(target):
+        typer.secho(f"{target}: helper removed.", fg=typer.colors.GREEN)
+        return
+    typer.secho(f"{target}: uninstall failed (is the package installed?).", fg=typer.colors.RED)
+    raise typer.Exit(code=1)
+
+
+@helper_app.command("parity")
+def helper_parity(
+    serial: SerialOption = None,
+    rounds: Annotated[int, typer.Option("--rounds", help="Timed dumps per backend.")] = 3,
+    as_json: Annotated[bool, typer.Option("--json", help="Print raw JSON.")] = False,
+) -> None:
+    """Dump the current screen with the helper and with UIAutomator2 and compare them.
+
+    The two backends must describe the same visible screen: every labelled
+    UIAutomator element should have a helper element with the same label at
+    the same place, the helper must emit no off-screen or negative bounds, and
+    its dump should not be slower. Run it on a busy screen (a scrolled list, a
+    dialog over an app) to catch regressions the unit tests cannot see.
+    """
+    from artemis.core.diagnostics.hierarchy_parity import compare_backends
+
+    target = _resolve_serial(serial)
+    report = compare_backends(target, rounds=max(1, rounds))
+    if as_json:
+        typer.echo(json.dumps(report, indent=2, ensure_ascii=False))
+        raise typer.Exit(code=0 if report["ok"] else 1)
+
+    table = Table(title=f"Hierarchy parity on {target}")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Helper")
+    table.add_column("UIAutomator2")
+    h, u = report["helper"], report["uiautomator"]
+    table.add_row("Dump time, median", f"{h['median_ms']:.0f} ms", f"{u['median_ms']:.0f} ms")
+    table.add_row("Nodes", str(h["nodes"]), str(u["nodes"]))
+    table.add_row("Labelled nodes (text / desc)", str(h["labelled"]), str(u["labelled"]))
+    table.add_row("Negative bounds", str(h["negative_bounds"]), str(u["negative_bounds"]))
+    table.add_row("Off-screen bounds", str(h["offscreen_bounds"]), str(u["offscreen_bounds"]))
+    table.add_row("Foreground package", str(h["package"]), str(u["package"]))
+    Console().print(table)
+
+    m = report["match"]
+    typer.echo(
+        f"UIAutomator labels found in helper dump: {m['uiautomator_in_helper']}/{m['uiautomator_labelled']}"
+        f" ({m['recall']:.0%}); helper labels found in UIAutomator dump: "
+        f"{m['helper_in_uiautomator']}/{m['helper_labelled']} ({m['precision']:.0%})"
+    )
+    for label in m["missing_in_helper"][:10]:
+        typer.echo(f"  helper lacks: {label}")
+    for label in m["extra_in_helper"][:10]:
+        typer.echo(f"  helper adds:  {label}")
+    for problem in report["problems"]:
+        typer.secho(f"  ! {problem}", fg=typer.colors.RED)
+    typer.secho(
+        "PARITY OK" if report["ok"] else "PARITY FAILED",
+        fg=typer.colors.GREEN if report["ok"] else typer.colors.RED,
+    )
+    raise typer.Exit(code=0 if report["ok"] else 1)
+
+
+__all__ = ["helper_app"]