droidock 0.1.0__py3-none-any.whl

droidock/__init__.py

@@ -0,0 +1,50 @@
+"""Importable Android connection management. Importing this package performs no device I/O."""
+
+from .errors import DroidockError, IdentityError
+from .interfaces import Backend, Discovery
+from .manager import ConnectionManager
+from .models import (
+    AutoConnectReport,
+    ConnectionEvent,
+    DeviceRecord,
+    Identity,
+    PairResult,
+    Service,
+    ServiceGroup,
+    ServiceKind,
+    Settings,
+    Snapshot,
+    Transport,
+    group_services,
+)
+from .portscan import AdbPortScanner, PortScanProgress, PortScanStatus, preferred_adb_ports
+from .store import DeviceStore
+from .tailscale import TailscaleClient, TailscalePeer
+
+__version__ = "0.1.0"
+__all__ = [
+    "AdbPortScanner",
+    "DroidockError",
+    "AutoConnectReport",
+    "Backend",
+    "ConnectionEvent",
+    "ConnectionManager",
+    "DeviceRecord",
+    "DeviceStore",
+    "Discovery",
+    "Identity",
+    "IdentityError",
+    "PairResult",
+    "PortScanProgress",
+    "PortScanStatus",
+    "Service",
+    "ServiceGroup",
+    "ServiceKind",
+    "Settings",
+    "Snapshot",
+    "Transport",
+    "TailscaleClient",
+    "TailscalePeer",
+    "group_services",
+    "preferred_adb_ports",
+]

droidock/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

droidock/adb.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import importlib.resources
+import os
+import re
+import shutil
+import socket
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+from .errors import DroidockError
+from .models import (
+    ADB_SERVICE_KINDS,
+    Identity,
+    PairResult,
+    Service,
+    Settings,
+    Transport,
+    normalize_endpoint,
+    valid_serial,
+)
+
+
+def parse_services(text: str) -> list[Service]:
+    result: list[Service] = []
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        instance, service_type, address = parts[0], parts[-2].rstrip("."), parts[-1]
+        kind = ADB_SERVICE_KINDS.get(service_type)
+        if kind is None:
+            continue
+        try:
+            endpoint = normalize_endpoint(address)
+        except DroidockError:
+            continue
+        result.append(Service(instance, kind, endpoint, "adb"))
+    return result
+
+
+class AdbBackend:
+    """ADB adapter with bundled executable discovery and time-limited subprocesses.
+
+    Existing compatible servers are reused. No operation kills the shared ADB server.
+    Pairing secrets go through stdin and are removed from exception messages.
+    """
+
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or Settings()
+        self.settings.validate()
+        self._executable: Path | None = None
+        self._version = ""
+        self._protocol: int | None = None
+
+    @property
+    def executable(self) -> Path:
+        if self._executable:
+            return self._executable
+        override = self.settings.adb_path or os.environ.get("DROIDOCK_ADB_PATH", "")
+        if override:
+            candidate = Path(override).expanduser()
+            if not candidate.is_file():
+                raise DroidockError(
+                    f"The configured ADB executable does not exist: {candidate}", code="adb_missing"
+                )
+        else:
+            bundled = importlib.resources.files("adbutils.binaries").joinpath(
+                "adb.exe" if os.name == "nt" else "adb"
+            )
+            candidate = Path(str(bundled))
+            if not candidate.is_file():
+                found = shutil.which("adb")
+                if not found:
+                    raise DroidockError(
+                        "No bundled ADB is available for this OS. Set an ADB executable path in settings.",
+                        code="adb_missing",
+                    )
+                candidate = Path(found)
+        try:
+            result = subprocess.run(
+                [str(candidate), "version"],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=self.settings.command_timeout,
+                check=True,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise DroidockError(f"Cannot run the ADB executable: {candidate}", code="adb_missing") from exc
+        match = re.search(r"Android Debug Bridge version 1\.0\.(\d+)", result.stdout)
+        if not match:
+            raise DroidockError("Cannot read the ADB version response.", code="adb_missing")
+        self._protocol = int(match.group(1))
+        self._version = result.stdout.strip()
+        self._executable = candidate.resolve()
+        return self._executable
+
+    def _check_server(self) -> None:
+        try:
+            # Windows can take about a second to reject a closed localhost port.
+            # A shorter timeout would mistake an absent server for an unresponsive one.
+            connection = socket.create_connection(("127.0.0.1", self.settings.server_port), timeout=3)
+        except ConnectionRefusedError:
+            return
+        except OSError as exc:
+            raise DroidockError(f"Cannot reach the ADB server: {exc}", code="server_unavailable") from exc
+        try:
+            with connection:
+
+                def receive(count: int) -> bytes:
+                    data = b""
+                    while len(data) < count:
+                        chunk = connection.recv(count - len(data))
+                        if not chunk:
+                            raise ValueError("Incomplete server response")
+                        data += chunk
+                    return data
+
+                request = b"host:version"
+                connection.sendall(f"{len(request):04x}".encode() + request)
+                if receive(4) != b"OKAY":
+                    raise ValueError("The response is not from an ADB server")
+                length = int(receive(4), 16)
+                if length > 32:
+                    raise ValueError("Invalid server version response")
+                protocol = int(receive(length), 16)
+                if protocol != self._protocol:
+                    raise DroidockError(
+                        "The running ADB server uses a different protocol version. Select a compatible ADB executable "
+                        "or a separate server port. The shared server will not be stopped automatically.",
+                        code="server_conflict",
+                    )
+        except (OSError, ValueError) as exc:
+            raise DroidockError(
+                f"The ADB server on local port {self.settings.server_port} is not responding correctly.",
+                code="server_unavailable",
+            ) from exc
+
+    def _run(self, *arguments: str, input_text: str | None = None, timeout: float | None = None) -> str:
+        executable = self.executable
+        self._check_server()
+        environment = os.environ.copy()
+        # Explicitly select the checked local server, including when a parent app uses a remote server.
+        environment.pop("ADB_SERVER_SOCKET", None)
+        environment.pop("ANDROID_ADB_SERVER_ADDRESS", None)
+        environment.pop("ANDROID_ADB_SERVER_PORT", None)
+        # Even '-H 127.0.0.1' makes ADB refuse to start a missing server as a "remote host".
+        # Removing remote-server overrides and using -P selects localhost and permits startup.
+        command = [str(executable), "-P", str(self.settings.server_port), *arguments]
+        try:
+            result = subprocess.run(
+                command,
+                input=input_text,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=timeout or self.settings.command_timeout,
+                env=environment,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise DroidockError("The device did not respond within the timeout.", code="timeout") from exc
+        except OSError as exc:
+            raise DroidockError(f"Failed to run ADB: {exc}", code="adb_failed") from exc
+        output = "\n".join(x.strip() for x in (result.stdout, result.stderr) if x.strip())
+        if input_text:
+            output = output.replace(input_text.strip(), "[REDACTED]")
+        if result.returncode:
+            code = "unauthorized" if "unauthorized" in output.lower() else "adb_failed"
+            raise DroidockError(output[-2500:] or "The ADB command failed.", code=code)
+        return output
+
+    def inspect(self, address: str) -> Transport:
+        output = self._run("-s", address, "shell", "getprop")
+        properties = dict(re.findall(r"^\[([^\]]+)\]: \[(.*)\]$", output, flags=re.MULTILINE))
+        serial = properties.get("ro.serialno", "")
+        if not valid_serial(serial):
+            serial = properties.get("ro.boot.serialno", "")
+        if not valid_serial(serial):
+            return Transport(address, "device", detail="Cannot determine the device serial number.")
+        identity = Identity(
+            serial,
+            properties.get("ro.product.manufacturer", ""),
+            properties.get("ro.product.model", ""),
+            properties.get("persist.adb.wifi.guid", ""),
+        )
+        return Transport(address, "device", identity)
+
+    def transports(self) -> list[Transport]:
+        output = self._run("devices", "-l")
+        entries: list[tuple[str, str]] = []
+        for line in output.splitlines():
+            fields = line.split()
+            if len(fields) >= 2 and fields[1] in {
+                "device",
+                "offline",
+                "unauthorized",
+                "recovery",
+                "sideload",
+            }:
+                entries.append((fields[0], fields[1]))
+            elif len(fields) >= 3 and fields[1:3] == ["no", "permissions"]:
+                entries.append((fields[0], "no permissions"))
+
+        def inspect_entry(entry: tuple[str, str]) -> Transport:
+            address, state = entry
+            if state != "device":
+                return Transport(address, state)
+            try:
+                return self.inspect(address)
+            except DroidockError as exc:
+                return Transport(address, "unresponsive", detail=str(exc))
+
+        with ThreadPoolExecutor(max_workers=4) as executor:
+            return list(executor.map(inspect_entry, entries))
+
+    def services(self) -> list[Service]:
+        return parse_services(self._run("mdns", "services"))
+
+    def connect(self, endpoint: str) -> None:
+        endpoint = normalize_endpoint(endpoint)
+        output = self._run("connect", endpoint)
+        if not re.search(r"(?:already )?connected to ", output, re.IGNORECASE):
+            raise DroidockError(output or "The connection could not be established.", code="connect_failed")
+
+    def pair(self, endpoint: str, code: str) -> PairResult:
+        endpoint = normalize_endpoint(endpoint)
+        if not re.fullmatch(r"\d{6}", code):
+            raise DroidockError("Enter the six-digit pairing code shown on the device.", code="invalid_code")
+        output = self._run("pair", endpoint, input_text=code + "\n", timeout=30)
+        if "successfully paired" not in output.lower():
+            raise DroidockError(output or "Pairing failed.", code="pair_failed")
+        match = re.search(r"\[guid=([^\]]+)\]", output)
+        return PairResult(endpoint, match.group(1) if match else "")
+
+    def disconnect(self, endpoint: str) -> None:
+        if not re.fullmatch(r"adb-[A-Za-z0-9._-]+\._adb-tls-connect\._tcp\.?", endpoint):
+            endpoint = normalize_endpoint(endpoint)
+        self._run("disconnect", endpoint)
+
+    def reconnect(self, address: str) -> None:
+        self._run("-s", address, "reconnect")
+
+    def diagnostics(self) -> dict[str, str]:
+        result = {
+            "executable": str(self.executable),
+            "version": self._version,
+            "server_port": str(self.settings.server_port),
+        }
+        for key, args in {"server": ("server-status",), "mdns": ("mdns", "check")}.items():
+            try:
+                result[key] = self._run(*args)
+            except DroidockError as exc:
+                result[key] = str(exc)
+        return result

droidock/cli.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import functools
+import io
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import asdict
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from . import __version__
+from .display import (
+    show_auto_connect,
+    show_device,
+    show_diagnostics,
+    show_disconnected,
+    show_pairing,
+    show_settings,
+    show_snapshot,
+)
+from .errors import DroidockError
+from .interactive import InteractiveCli
+from .manager import ConnectionManager
+from .store import DeviceStore
+
+app = typer.Typer(
+    add_completion=False,
+    help="Save Android device profiles, discover devices, pair, and reconnect automatically.",
+)
+console = Console()
+JsonOutput = Annotated[bool, typer.Option("--json", help="Print structured JSON for scripts.")]
+
+
+def guarded(function: Callable[..., Any]) -> Callable[..., Any]:
+    @functools.wraps(function)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return function(*args, **kwargs)
+        except DroidockError as exc:
+            if kwargs.get("json_output"):
+                typer.echo(json.dumps({"error": {"code": exc.code, "message": str(exc)}}, ensure_ascii=False))
+            else:
+                Console(stderr=True).print(str(exc), style="red", markup=False)
+            raise typer.Exit(1) from exc
+
+    return wrapper
+
+
+def manager(ctx: typer.Context) -> ConnectionManager:
+    if ctx.obj is None:
+        ctx.obj = ConnectionManager(DeviceStore(ctx.find_root().params.get("data_dir")))
+    return ctx.obj
+
+
+def emit(value: object) -> None:
+    typer.echo(json.dumps(value, ensure_ascii=False, indent=2))
+
+
+def show_version(value: bool) -> None:
+    if value:
+        typer.echo(f"droidock {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+@guarded
+def root(
+    ctx: typer.Context,
+    data_dir: Annotated[
+        Path | None, typer.Option(help="Directory for saved device profiles.", envvar="DROIDOCK_HOME")
+    ] = None,
+    plain: Annotated[bool, typer.Option(help="Use numbered menus instead of arrow keys.")] = False,
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=show_version, is_eager=True, help="Show the version and exit."),
+    ] = False,
+) -> None:
+    if ctx.invoked_subcommand is None:
+        InteractiveCli(manager(ctx), plain=plain).run()
+
+
+@app.command()
+@guarded
+def devices(ctx: typer.Context, json_output: JsonOutput = False) -> None:
+    """List current connections and nearby wireless devices without requesting reconnection."""
+    current = manager(ctx)
+    snapshot = current.scan()
+    if json_output:
+        emit(asdict(snapshot))
+    else:
+        show_snapshot(console, snapshot, current.store.read().default_device)
+
+
+@app.command()
+@guarded
+def register(
+    ctx: typer.Context,
+    address: Annotated[
+        str, typer.Argument(help="USB serial or wireless address of an already connected device.")
+    ],
+    name: Annotated[str | None, typer.Option(help="Name for the saved device.")] = None,
+    json_output: JsonOutput = False,
+) -> None:
+    """Verify a connected device and save its identity on this PC."""
+    current = manager(ctx)
+    record = current.register(address, name=name)
+    if json_output:
+        emit(asdict(record))
+    else:
+        show_device(
+            console, record, title="Device registered", default_device=current.store.read().default_device
+        )
+
+
+@app.command()
+@guarded
+def connect(
+    ctx: typer.Context,
+    device: Annotated[
+        str | None, typer.Argument(help="Saved name, device ID, or serial. Omit to use the default device.")
+    ] = None,
+    endpoint: Annotated[
+        str | None, typer.Option(help="Current connection IP:port, separate from the pairing port.")
+    ] = None,
+    name: Annotated[str | None, typer.Option(help="Name to assign when registering a new device.")] = None,
+    json_output: JsonOutput = False,
+) -> None:
+    """Connect to the selected device and verify its identity."""
+    current = manager(ctx)
+    if endpoint:
+        expected = current.device(device) if device else None
+        record = current.connect_endpoint(endpoint, name=name, expected=expected)
+    else:
+        if name:
+            raise DroidockError("Use --name together with --endpoint to register a device at a new address.")
+        record = current.connect(device)
+    if json_output:
+        emit(asdict(record))
+    else:
+        show_device(
+            console, record, title="Connection verified", default_device=current.store.read().default_device
+        )
+
+
+@app.command()
+@guarded
+def pair(
+    ctx: typer.Context,
+    endpoint: Annotated[str | None, typer.Argument(help="IP:port shown on the pairing screen.")] = None,
+    code_stdin: Annotated[
+        bool, typer.Option(help="Read the six-digit code from standard input instead of a command argument.")
+    ] = False,
+    json_output: JsonOutput = False,
+) -> None:
+    """Pair wirelessly. Omit the address to open the pairing and registration wizard."""
+    if json_output and (not endpoint or not code_stdin):
+        raise DroidockError("Specify a pairing address and use --code-stdin with --json.")
+    if not endpoint:
+        if code_stdin:
+            raise DroidockError("Specify a pairing address when using --code-stdin.")
+        InteractiveCli(manager(ctx)).pair()
+        return
+    if code_stdin:
+        code = sys.stdin.readline().strip()
+    else:
+        code = typer.prompt("Six-digit pairing code shown on the device", hide_input=True)
+    result = manager(ctx).pair(endpoint, code)
+    if json_output:
+        emit(
+            {"status": "paired", **asdict(result), "next": "connect --endpoint <current-connection-IP:port>"}
+        )
+    else:
+        show_pairing(console, result)
+
+
+@app.command("auto-connect")
+@guarded
+def auto_connect(ctx: typer.Context, json_output: JsonOutput = False) -> None:
+    """Try connecting once to each saved device with automatic connection enabled."""
+    current = manager(ctx)
+    result = current.auto_connect()
+    if json_output:
+        emit(asdict(result))
+    else:
+        show_auto_connect(console, result, current.store.read().devices)
+    if result.errors:
+        raise typer.Exit(1)
+
+
+@app.command()
+@guarded
+def watch(
+    ctx: typer.Context,
+    interval: Annotated[float, typer.Option(min=1, help="Discovery interval in seconds.")] = 5,
+    once: Annotated[
+        bool, typer.Option(help="Run automatic connection once and show the resulting status.")
+    ] = False,
+) -> None:
+    """Discover and reconnect saved devices while running. Press Ctrl+C to stop."""
+    current = manager(ctx)
+    for snapshot in current.watch(interval=interval):
+        show_snapshot(console, snapshot, current.store.read().default_device)
+        if once:
+            break
+
+
+@app.command()
+@guarded
+def diagnose(ctx: typer.Context, json_output: JsonOutput = False) -> None:
+    """Show ADB, server, and device diagnostics with connection guidance."""
+    report = manager(ctx).diagnostics()
+    if json_output:
+        emit(report)
+    else:
+        show_diagnostics(console, report)
+
+
+@app.command()
+@guarded
+def settings(
+    ctx: typer.Context,
+    key: Annotated[str | None, typer.Argument(help="Setting name. Omit to show current settings.")] = None,
+    value: Annotated[str | None, typer.Argument(help="Value to save.")] = None,
+    json_output: JsonOutput = False,
+) -> None:
+    """View or update settings. Example: settings auto_connect_on_start false"""
+    current = manager(ctx)
+    if key is not None:
+        values = asdict(current.settings)
+        if key not in values or value is None:
+            raise DroidockError("Check the setting name and value. Available settings: " + ", ".join(values))
+        existing = values[key]
+        try:
+            if isinstance(existing, bool):
+                if value.lower() not in {"true", "false"}:
+                    raise ValueError
+                parsed: object = value.lower() == "true"
+            elif isinstance(existing, int):
+                parsed = int(value)
+            elif isinstance(existing, float):
+                parsed = float(value)
+            else:
+                parsed = "" if value == "auto" else value
+        except ValueError as exc:
+            raise DroidockError("Invalid value format. Use true or false for boolean settings.") from exc
+        current.configure(**{key: parsed})
+    if json_output:
+        emit({"store": str(current.store.path), **asdict(current.settings)})
+    else:
+        if key is not None:
+            console.print("Settings saved.", style="green")
+        show_settings(console, current.settings, current.store.path)
+
+
+@app.command()
+@guarded
+def profile(
+    ctx: typer.Context,
+    device: str,
+    name: str | None = None,
+    auto_connect: Annotated[bool | None, typer.Option("--auto-connect/--no-auto-connect")] = None,
+    default: bool = False,
+    json_output: JsonOutput = False,
+) -> None:
+    """Update a saved device name, automatic connection preference, or default selection."""
+    current = manager(ctx)
+    record = current.update_device(device, name=name, auto_connect=auto_connect, default=default)
+    if json_output:
+        emit(asdict(record))
+    else:
+        show_device(console, record, default_device=current.store.read().default_device)
+
+
+@app.command()
+@guarded
+def disconnect(ctx: typer.Context, device: str, json_output: JsonOutput = False) -> None:
+    """Disconnect verified wireless connections for this device and disable automatic connection."""
+    count = manager(ctx).disconnect(device)
+    if json_output:
+        emit({"disconnected": count})
+    else:
+        show_disconnected(console, count)
+
+
+@app.command()
+@guarded
+def forget(ctx: typer.Context, device: str, yes: bool = False) -> None:
+    """Delete the saved profile on this PC. Android pairing authorization is retained."""
+    if not yes and not typer.confirm("Delete this device profile from the PC?"):
+        raise typer.Abort()
+    manager(ctx).forget(device)
+    typer.echo("Device profile deleted.")
+
+
+def main() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper) and not stream.isatty():
+            stream.reconfigure(encoding="utf-8")
+    try:
+        app()
+    except (KeyboardInterrupt, EOFError):
+        return

droidock/discovery.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import threading
+import time
+
+from zeroconf import IPVersion, ServiceBrowser, ServiceStateChange, Zeroconf
+
+from .models import ADB_SERVICE_KINDS, Service, normalize_endpoint
+
+SERVICE_TYPES = {f"{service_type}.local.": kind for service_type, kind in ADB_SERVICE_KINDS.items()}
+
+
+class MdnsDiscovery:
+    """Independent multicast discovery, merged with ADB's results by ConnectionManager."""
+
+    def discover(self, seconds: float) -> tuple[list[Service], list[str]]:
+        if seconds <= 0:
+            return [], []
+        discovered: set[Service] = set()
+        lock = threading.Lock()
+        warnings: list[str] = []
+
+        def changed(
+            zeroconf: Zeroconf, service_type: str, name: str, state_change: ServiceStateChange
+        ) -> None:
+            if state_change is ServiceStateChange.Removed:
+                return
+            info = zeroconf.get_service_info(service_type, name, timeout=500)
+            if not info or not info.port:
+                return
+            for address in info.parsed_scoped_addresses(IPVersion.All):
+                host = f"[{address}]" if ":" in address else address
+                item = Service(
+                    name.removesuffix("." + service_type),
+                    SERVICE_TYPES[service_type],
+                    normalize_endpoint(f"{host}:{info.port}"),
+                    "zeroconf",
+                )
+                with lock:
+                    discovered.add(item)
+
+        try:
+            with Zeroconf(ip_version=IPVersion.All) as zeroconf:
+                browser = ServiceBrowser(zeroconf, list(SERVICE_TYPES), handlers=[changed])
+                try:
+                    time.sleep(seconds)
+                finally:
+                    browser.cancel()
+        except OSError as exc:
+            warnings.append(f"Wireless discovery is unavailable: {exc}")
+        return sorted(discovered, key=lambda item: (item.kind, item.instance, item.endpoint)), warnings