sdkmgr 0.1.0__py3-none-any.whl

sdkmgr/__init__.py

@@ -0,0 +1,8 @@
+"""Discover and provision Node, Java, and Android development tools."""
+
+from .android import AndroidInstallation
+from .core import Installation, Manager
+from .errors import InstallationRequired, SDKError
+
+__all__ = ["AndroidInstallation", "Installation", "InstallationRequired", "Manager", "SDKError"]
+__version__ = "0.1.0"

sdkmgr/__main__.py

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

sdkmgr/android.py

@@ -0,0 +1,290 @@
+import hashlib
+import os
+import re
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from filelock import FileLock, Timeout
+
+from .download import fetch
+from .errors import InstallationRequired, SDKError
+from .providers import Platform
+from .system import display_command
+
+TOOLS_BUILD = "15859902"
+# SHA-256 values published at https://developer.android.com/studio.
+TOOLS_ARCHIVES = {
+    "linux-x64": ("linux", "4e4c464f145a7512b57d088ac6c278c03c9eea610886b35a5e0804e74eedf583"),
+    "macos-x64": ("mac_x86_64", "c5a6378ab5cf7e0d5701921405115befff13e9ff7417fb588389338f8bd050f3"),
+    "macos-arm64": ("mac_arm64", "835b62a26162b229b441d1f6d4680383815a270809eb33522c0d480fa5002c4e"),
+    "windows-x64": ("win", "90ae805d20434428bffcb699c290860f19bb5f66a67e6b330067e3de801fb04a"),
+}
+
+
+def sdk_root(host: Platform, explicit: str | Path | None = None) -> Path:
+    if explicit is not None:
+        return Path(explicit).expanduser().resolve()
+    home = os.environ.get("ANDROID_HOME")
+    legacy = os.environ.get("ANDROID_SDK_ROOT")
+    if home and legacy and Path(home).expanduser().resolve() != Path(legacy).expanduser().resolve():
+        raise SDKError("ANDROID_HOME and ANDROID_SDK_ROOT disagree; set one SDK root explicitly.")
+    if configured := home or legacy:
+        return Path(configured).expanduser().resolve()
+    if host.system == "windows":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+        return base / "Android" / "Sdk"
+    if host.system == "macos":
+        return Path.home() / "Library" / "Android" / "sdk"
+    return Path.home() / "Android" / "Sdk"
+
+
+def validate_packages(packages) -> tuple[str, ...]:
+    if isinstance(packages, str):
+        raise SDKError("Android packages must be a sequence, not a single string.")
+    result = []
+    for package in packages:
+        if not isinstance(package, str) or not re.fullmatch(
+            r"[A-Za-z0-9_][A-Za-z0-9_.-]*(/[A-Za-z0-9_][A-Za-z0-9_.-]*)*", package,
+        ) or any(part in {".", ".."} for part in package.split("/")):
+            raise SDKError(f"Invalid Android package identifier: {package!r}.")
+        if package not in result:
+            result.append(package)
+    return tuple(result)
+
+
+def command_tools(home: Path, host: Platform) -> Path | None:
+    suffix = ".exe" if host.system == "windows" else ""
+    directory = home / "cmdline-tools"
+    candidates = [directory / "latest", directory / f"sdkmgr-{TOOLS_BUILD}"]
+    if directory.is_dir():
+        versions = [p for p in directory.iterdir() if re.fullmatch(r"[0-9]+(\.[0-9]+)*", p.name)]
+        candidates.extend(sorted(versions, key=lambda p: tuple(map(int, p.name.split("."))), reverse=True))
+    for candidate in candidates:
+        if (candidate / "bin" / f"android{suffix}").is_file():
+            return candidate
+    return None
+
+
+def installed_packages(home: Path) -> dict[str, str]:
+    """Read Google's local package records without contacting the repository."""
+    try:
+        return _installed_packages(home)
+    except OSError as error:
+        raise SDKError(f"Cannot read Android package records: {error}") from error
+
+
+def _installed_packages(home: Path) -> dict[str, str]:
+    result = {}
+    if not home.exists():
+        return result
+    def unreadable(error):
+        raise error
+
+    for directory, subdirectories, files in os.walk(home, onerror=unreadable):
+        subdirectories[:] = [p for p in subdirectories if not p.startswith(".")]
+        if "package.xml" not in files:
+            continue
+        # Package contents (notably NDK toolchains) are not more SDK packages.
+        subdirectories.clear()
+        record = Path(directory) / "package.xml"
+        if record.stat().st_size > 1024 * 1024:
+            raise SDKError(f"Oversized Android package record: {record}.")
+        try:
+            root = ET.parse(record).getroot()
+            for package in root.iter():
+                if package.tag.rsplit("}", 1)[-1] != "localPackage":
+                    continue
+                # SDK records retain semicolons; the public CLI uses slashes.
+                name = package.attrib["path"].replace(";", "/")
+                validate_packages((name,))
+                if home.joinpath(*name.split("/")).resolve() != record.parent.resolve():
+                    continue
+                revision = next((p for p in package if p.tag.rsplit("}", 1)[-1] == "revision"), None)
+                parts = {} if revision is None else {
+                    p.tag.rsplit("}", 1)[-1]: p.text for p in revision
+                }
+                result[name] = ".".join(parts.get(p) or "0" for p in ("major", "minor", "micro"))
+        except (ET.ParseError, KeyError) as error:
+            raise SDKError(f"Invalid Android package record {record}: {error}") from error
+    return result
+
+
+@dataclass(frozen=True)
+class AndroidInstallation:
+    """An SDK root and its native Android CLI; no JVM is needed to provision it."""
+
+    home: Path
+    tools: Path
+    platform: Platform
+
+    def executable(self, name: str = "android") -> Path:
+        if name == "android":
+            suffix = ".exe" if self.platform.system == "windows" else ""
+            return self.tools / "bin" / (name + suffix)
+        if name in {"adb", "fastboot", "emulator"}:
+            suffix = ".exe" if self.platform.system == "windows" else ""
+            return self.home / ("emulator" if name == "emulator" else "platform-tools") / (name + suffix)
+        raise SDKError(f"Unknown Android executable: {name!r}.")
+
+    def environment(self, base: dict[str, str] | None = None) -> dict[str, str]:
+        result = dict(os.environ if base is None else base)
+        result["ANDROID_HOME"] = result["ANDROID_SDK_ROOT"] = str(self.home)
+        paths = (self.tools / "bin", self.home / "platform-tools", self.home / "emulator")
+        result["PATH"] = os.pathsep.join(map(str, paths)) + os.pathsep + result.get("PATH", "")
+        # Cross-OS download overrides must not silently provision unusable tools.
+        result.pop("REPO_OS_OVERRIDE", None)
+        return result
+
+    def installed(self) -> dict[str, str]:
+        return installed_packages(self.home)
+
+    def command(self, *arguments: str) -> tuple[str, ...]:
+        return (str(self.executable()), "--no-metrics", f"--sdk={self.home}", *arguments)
+
+
+def find(home: Path, host: Platform) -> AndroidInstallation | None:
+    try:
+        if tools := command_tools(home, host):
+            return AndroidInstallation(home, tools, host)
+        return None
+    except OSError as error:
+        raise SDKError(f"Cannot discover Android command-line tools: {error}") from error
+
+
+def _verify_packages(sdk: AndroidInstallation, packages):
+    suffix = ".exe" if sdk.platform.system == "windows" else ""
+    for package in packages:
+        directory = sdk.home.joinpath(*package.split("/"))
+        required = ()
+        if package == "platform-tools":
+            required = (f"adb{suffix}",)
+        elif package == "emulator":
+            required = (f"emulator{suffix}",)
+        elif package.startswith("platforms/"):
+            required = ("android.jar",)
+        elif package.startswith("build-tools/"):
+            required = (f"aapt2{suffix}", "d8.bat" if suffix else "d8")
+        for name in required:
+            if not (directory / name).is_file():
+                raise SDKError(
+                    f"Android package {package} is registered but missing {directory / name}. "
+                    "Repair it with Android Studio or Google's SDK manager, then retry; "
+                    "sdkmgr will not overwrite a partial installation."
+                )
+
+
+def _extract(archive: Path, destination: Path):
+    with zipfile.ZipFile(archive) as source:
+        entries = source.infolist()
+        if len(entries) > 20000 or sum(p.file_size for p in entries) > 1024 ** 3:
+            raise SDKError("Android tools archive exceeds extraction limits.")
+        for entry in entries:
+            path = PurePosixPath(entry.filename)
+            original = entry.orig_filename
+            mode = entry.external_attr >> 16
+            if (
+                path.is_absolute() or ".." in path.parts or not path.parts
+                or path.parts[0] != "cmdline-tools" or "\\" in original or "\x00" in original
+                or ":" in entry.filename or stat.S_ISLNK(mode)
+                or (stat.S_IFMT(mode) not in {0, stat.S_IFREG, stat.S_IFDIR})
+            ):
+                raise SDKError(f"Unsafe Android archive member: {entry.filename!r}.")
+            target = destination.joinpath(*path.parts)
+            if entry.is_dir():
+                target.mkdir(parents=True, exist_ok=True)
+            else:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with source.open(entry) as incoming, target.open("xb") as outgoing:
+                    shutil.copyfileobj(incoming, outgoing)
+                target.chmod(0o755 if mode & 0o111 or path.parent.name == "bin" else 0o644)
+
+
+def require_consent(*, accept_sdk_license: bool):
+    if not accept_sdk_license:
+        raise InstallationRequired((),
+            "Review Google's SDK terms and the licenses for the requested packages at "
+            "https://developer.android.com/studio#downloads before installing. "
+            "After accepting them, retry with --accept-sdk-license "
+            "(Python: accept_sdk_license=True), or install manually. "
+            "sdkmgr does not run Google's installer without this confirmation.")
+
+
+def bootstrap(home: Path, host: Platform, *, accept_sdk_license: bool) -> AndroidInstallation:
+    if existing := find(home, host):
+        return existing
+    if host.tag not in TOOLS_ARCHIVES:
+        raise SDKError(f"Android command-line tools bootstrap is not supported on {host.tag}.")
+    require_consent(accept_sdk_license=accept_sdk_license)
+    target = home / "cmdline-tools" / f"sdkmgr-{TOOLS_BUILD}"
+    if target.exists():
+        raise SDKError(f"Incomplete Android tools at {target}; move them aside and retry.")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    suffix, expected = TOOLS_ARCHIVES[host.tag]
+    url = f"https://dl.google.com/android/repository/commandlinetools-{suffix}-{TOOLS_BUILD}_latest.zip"
+    print(f"Installing Android command-line tools in {target}...", file=sys.stderr)
+    with tempfile.TemporaryDirectory(prefix=".sdkmgr-", dir=target.parent) as temporary:
+        stage = Path(temporary)
+        archive = stage / "tools.zip"
+        fetch(url, archive, limit=256 * 1024 ** 2)
+        with archive.open("rb") as stream:
+            if hashlib.file_digest(stream, "sha256").hexdigest() != expected:
+                raise SDKError("Android command-line tools SHA-256 mismatch.")
+        _extract(archive, stage)
+        extracted = stage / "cmdline-tools"
+        suffix = ".exe" if host.system == "windows" else ""
+        if not (extracted / "bin" / f"android{suffix}").is_file():
+            raise SDKError("Android tools archive is missing the Android CLI.")
+        os.replace(extracted, target)
+    return AndroidInstallation(home, target, host)
+
+
+def _run(sdk: AndroidInstallation, arguments, *, interactive: bool):
+    command = sdk.command(*arguments)
+    print(f"Running {display_command(command)}", file=sys.stderr)
+    return subprocess.run(
+        command, check=False, env=sdk.environment(),
+        stdin=None if interactive else subprocess.DEVNULL,
+        stdout=sys.stderr, stderr=sys.stderr, timeout=None if interactive else 1200,
+    )
+
+
+def ensure(home: Path, host: Platform, packages, *,
+           interactive: bool | None, accept_sdk_license: bool = False) -> AndroidInstallation:
+    packages = validate_packages(packages)
+    try:
+        existing = find(home, host)
+        installed = installed_packages(home)
+        if existing is None or any(p not in installed for p in packages):
+            require_consent(accept_sdk_license=accept_sdk_license)
+        home.mkdir(parents=True, exist_ok=True)
+        with FileLock(home / ".sdkmgr.lock", timeout=120):
+            sdk = bootstrap(home, host, accept_sdk_license=accept_sdk_license)
+            installed = sdk.installed()
+            _verify_packages(sdk, (p for p in packages if p in installed))
+            missing = tuple(p for p in packages if p not in installed)
+            if not missing:
+                return sdk
+            attached = interactive is not False and sys.stdin.isatty() and sys.stderr.isatty()
+            require_consent(accept_sdk_license=accept_sdk_license)
+            result = _run(sdk, ("sdk", "install", *missing), interactive=attached)
+            if result.returncode:
+                raise SDKError(f"Android installer exited with status {result.returncode}; retry after resolving its error.")
+            if remaining := tuple(p for p in packages if p not in sdk.installed()):
+                command = sdk.command("sdk", "install", *remaining)
+                raise InstallationRequired(command,
+                    f"Android packages still missing: {', '.join(remaining)}. "
+                    f"Inspect the installer output and retry {display_command(command)}. "
+                    "The installer may have reported unavailable packages or unmet prerequisites.")
+            _verify_packages(sdk, packages)
+            return sdk
+    except Timeout as error:
+        raise SDKError("Another sdkmgr Android install is active; retry later.") from error
+    except (OSError, subprocess.SubprocessError, zipfile.BadZipFile) as error:
+        raise SDKError(f"Android provisioning failed: {error}") from error

sdkmgr/bootstrap.py

@@ -0,0 +1,79 @@
+import hashlib
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from filelock import FileLock, Timeout
+
+from .download import fetch
+from .errors import SDKError
+from .providers import Platform
+
+MISE_VERSION = "2026.9.12"
+# Published in the pinned release's SHASUMS256.txt; no remote installer executes.
+MISE_BINARIES = {
+    "linux-x64": ("linux-x64-musl", "e59a38683c9d776e0ea6c7b35c9829de915bb7df15d16d0bf6890afa0278bd7c"),
+    "linux-arm64": ("linux-arm64-musl", "2d2982b12f7a13894aa88272e4cd360e68591fe105b43cff29b1ac4588c6fe83"),
+    "macos-x64": ("macos-x64", "fa1e35456f1e27a4555a1ccec82d5367d7037f3b4f46d48b83c4a3bceb4d78f2"),
+    "macos-arm64": ("macos-arm64", "f20d7cc555a5b0ee7b8a504acbc2583be1b0848d64115cfbe84119ceb705025b"),
+    "windows-x64": ("windows-x64.exe", "8bc3a2c46246bb00fc49f467c678cf9ff321f707c533ad707061d0f8c7b639b2"),
+    "windows-arm64": ("windows-arm64.exe", "6beeb61b829ba60ef3bb1fdda5717a41b8fb91bd400109de8b05b1700a107d8e"),
+}
+
+
+def _target(root: Path, host: Platform) -> Path:
+    return root / "managers" / f"mise-{MISE_VERSION}-{host.tag}" / (
+        "mise.exe" if host.system == "windows" else "mise"
+    )
+
+
+def _verify(path: Path, host: Platform):
+    with path.open("rb") as source:
+        digest = hashlib.file_digest(source, "sha256").hexdigest()
+    if digest != MISE_BINARIES[host.tag][1]:
+        raise SDKError(f"SHA-256 mismatch for {path}; move it aside and retry.")
+
+
+def find(root: Path, host: Platform) -> str | None:
+    target = _target(root, host)
+    try:
+        if target.exists():
+            _verify(target, host)
+            return str(target)
+        return None
+    except OSError as error:
+        raise SDKError(f"Cannot read sdkmgr's mise installation: {error}") from error
+
+
+def ensure(root: Path, host: Platform) -> str:
+    target = _target(root, host)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with FileLock(target.parent / ".install.lock", timeout=120):
+            if existing := find(root, host):
+                return existing
+            suffix = MISE_BINARIES[host.tag][0]
+            url = (
+                f"https://github.com/jdx/mise/releases/download/v{MISE_VERSION}/"
+                f"mise-v{MISE_VERSION}-{suffix}"
+            )
+            print(f"Installing mise {MISE_VERSION} in {target.parent}...", file=sys.stderr)
+            with tempfile.TemporaryDirectory(prefix=".install-", dir=target.parent) as temporary:
+                staged = Path(temporary) / target.name
+                fetch(url, staged, limit=128 * 1024 ** 2)
+                _verify(staged, host)
+                staged.chmod(0o755)
+                result = subprocess.run(
+                    [str(staged), "--version"], check=True, capture_output=True,
+                    text=True, timeout=10, stdin=subprocess.DEVNULL,
+                )
+                if MISE_VERSION not in result.stdout.split():
+                    raise SDKError("Downloaded mise did not report the pinned version.")
+                os.replace(staged, target)
+            return str(target)
+    except Timeout as error:
+        raise SDKError("Timed out waiting for mise bootstrap; retry later.") from error
+    except (OSError, subprocess.SubprocessError, UnicodeError) as error:
+        raise SDKError(f"Could not bootstrap mise: {error}") from error

sdkmgr/cli.py

@@ -0,0 +1,63 @@
+import argparse
+import sys
+
+from . import InstallationRequired, Manager, SDKError, __version__
+from .android import installed_packages, sdk_root
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description="Provision Node, Java 21/25, and Android SDK packages.")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--root", help="Private manager bootstrap directory")
+    parser.add_argument("--non-interactive", action="store_true", help="Never prompt; defer JDK installs")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("list", help="List selected-manager Node and discovered JDK installations")
+    android_parser = commands.add_parser("android", help="Manage Android SDK packages")
+    android_parser.add_argument("--sdk-root", help="Override ANDROID_HOME and the standard SDK location")
+    android_commands = android_parser.add_subparsers(dest="android_command", required=True)
+    android_commands.add_parser("list", help="Read installed packages without network access")
+    android_install = android_commands.add_parser("install", help="Install missing packages and their dependencies")
+    android_install.add_argument("packages", nargs="*", help="SDK IDs such as platforms/android-35")
+    android_install.add_argument("--accept-sdk-license", action="store_true",
+                                 help="Confirm acceptance of Google's SDK and requested package licenses")
+    for command in ("install", "which"):
+        subparser = commands.add_parser(command)
+        subparser.add_argument("sdk", help="node@X.Y.Z, java@21, or java@25")
+    args = parser.parse_args(argv)
+    try:
+        manager = Manager(args.root, interactive=False if args.non_interactive else None)
+        if args.command == "android":
+            if args.android_command == "install":
+                sdk = manager.ensure_android(args.packages, sdk_root=args.sdk_root,
+                                             accept_sdk_license=args.accept_sdk_license)
+                print(sdk.home)
+            else:
+                home = sdk_root(manager.platform, args.sdk_root)
+                for package, version in sorted(installed_packages(home).items()):
+                    print(f"{package}\t{version}")
+            return 0
+        if args.command == "list":
+            for installation in manager.installed():
+                print(f"{installation.tool}@{installation.version}\t{installation.home}")
+            return 0
+        tool, separator, version = args.sdk.partition("@")
+        if not separator or not tool or not version:
+            raise SDKError("Specify a tool and exact version, for example node@22.14.0.")
+        if args.command == "install":
+            print(f"Ensuring {tool}@{version}...", file=sys.stderr)
+            installation = manager.ensure(tool, version=version)
+        else:
+            installation = manager.find(tool, version=version)
+            if installation is None:
+                raise SDKError(f"{args.sdk} is not installed; run sdkmgr install {args.sdk}.")
+        print(installation.executable())
+        return 0
+    except InstallationRequired as error:
+        print(f"sdkmgr: {error}", file=sys.stderr)
+        return 2
+    except SDKError as error:
+        print(f"sdkmgr: {error}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("sdkmgr: interrupted", file=sys.stderr)
+        return 130

sdkmgr/core.py

@@ -0,0 +1,103 @@
+from pathlib import Path
+
+from platformdirs import user_data_path
+
+from . import android, bootstrap, java, mise, nvm
+from .errors import SDKError
+from .installation import Installation, validated_node
+from .providers import Platform, validate_node_version
+from .system import install_package
+
+
+class Manager:
+    """Provision Node through mise/nvm and Java 21/25 through OS packages.
+
+    Existing mise takes precedence over nvm; with neither installed, ensure()
+    bootstraps a pinned mise under root. find() and installed() never install.
+    Java package installation requires terminal confirmation; interactive=False
+    raises InstallationRequired instead. Authentication belongs to the OS.
+    """
+
+    def __init__(self, root: str | Path | None = None, *, interactive: bool | None = None):
+        self.root = Path(root) if root is not None else user_data_path("sdkmgr", appauthor=False)
+        self.root = self.root.expanduser().resolve()
+        self.interactive = interactive
+        self.platform = Platform.current()
+
+    def _node_provider(self, *, install: bool = False):
+        if executable := mise.executable() or bootstrap.find(self.root, self.platform):
+            return mise, executable
+        if existing := nvm.discover(self.platform):
+            return nvm, existing
+        if install:
+            return mise, bootstrap.ensure(self.root, self.platform)
+        return None
+
+    def _check_tool(self, tool: str, version: str):
+        if tool != "node":
+            raise SDKError(f"Unknown tool: {tool!r}; expected node or java.")
+        validate_node_version(version)
+
+    def ensure(self, tool: str, *, version: str) -> Installation:
+        """Return a matching installation, installing only when discovery fails."""
+        if tool == "java":
+            if existing := self.find(tool, version=version):
+                return existing
+            install_package(java.install_command(self.platform, version), interactive=self.interactive)
+            if installed := self.find(tool, version=version):
+                return installed
+            raise SDKError(
+                f"The installer completed, but JDK {version} was not found. "
+                "Set JAVA_HOME to its installation directory and retry."
+            )
+        self._check_tool(tool, version)
+        provider, context = self._node_provider(install=True)
+        if home := provider.node_installations(context, self.platform).get(version):
+            return validated_node(home, version, self.platform)
+        provider.install_node(context, version, self.platform)
+        if home := provider.node_installations(context, self.platform).get(version):
+            return validated_node(home, version, self.platform)
+        raise SDKError(f"{provider.__name__.rsplit('.', 1)[-1]} completed, but Node {version} was not found.")
+
+    def find(self, tool: str, *, version: str) -> Installation | None:
+        """Look up an installation without downloading anything."""
+        if tool == "java":
+            found = java.find(self.platform, version)
+            return Installation(tool, found[1], found[0], self.platform) if found else None
+        self._check_tool(tool, version)
+        if selection := self._node_provider():
+            provider, context = selection
+            if home := provider.node_installations(context, self.platform).get(version):
+                return validated_node(home, version, self.platform)
+        return None
+
+    def installed(self) -> list[Installation]:
+        """List the selected Node manager's installations and discovered Java 21/25."""
+        result = []
+        if selection := self._node_provider():
+            provider, context = selection
+            for version, home in provider.node_installations(context, self.platform).items():
+                result.append(validated_node(home, version, self.platform))
+        for version in ("21", "25"):
+            if installation := self.find("java", version=version):
+                result.append(installation)
+        return result
+
+    def find_android(self, *, sdk_root: str | Path | None = None) -> android.AndroidInstallation | None:
+        """Discover Android command-line tools without installing or running them."""
+        return android.find(android.sdk_root(self.platform, sdk_root), self.platform)
+
+    def ensure_android(self, packages=(), *, sdk_root: str | Path | None = None,
+                       accept_sdk_license: bool = False) -> android.AndroidInstallation:
+        """Ensure Android package IDs, delegating dependencies to Google's CLI.
+
+        Existing packages are not updated. accept_sdk_license confirms prior
+        acceptance of Google's SDK and requested package licenses. It is required
+        before any downloads or package installation, but not for existing SDKs.
+        IDs use slashes, for example platforms/android-35. No JDK is required;
+        no emulator is launched or virtual device created.
+        """
+        packages = android.validate_packages(packages)
+        home = android.sdk_root(self.platform, sdk_root)
+        return android.ensure(home, self.platform, packages,
+                              interactive=self.interactive, accept_sdk_license=accept_sdk_license)

sdkmgr/download.py

@@ -0,0 +1,59 @@
+import os
+import tempfile
+import time
+from pathlib import Path
+
+import httpx
+
+from .errors import SDKError
+
+MAX_DOWNLOAD = 1024 ** 3
+
+
+def fetch(url: str, destination: Path, *, limit: int = MAX_DOWNLOAD):
+    """Download over HTTPS, retrying transient failures without retaining partial data."""
+    if not url.startswith("https://"):
+        raise SDKError("Downloads require HTTPS.")
+    for attempt in range(3):
+        staged = None
+        try:
+            started = time.monotonic()
+            with httpx.Client(timeout=30, follow_redirects=False) as client:
+                current = url
+                for redirect in range(6):
+                    with client.stream("GET", current) as response:
+                        if response.is_redirect:
+                            location = response.headers.get("location")
+                            if not location:
+                                raise SDKError("Download redirect is missing its Location header.")
+                            target = response.url.join(location)
+                            if target.scheme != "https":
+                                raise SDKError("Refusing an insecure download redirect.")
+                            current = str(target)
+                            continue
+                        response.raise_for_status()
+                        size = 0
+                        with tempfile.NamedTemporaryFile(
+                            dir=destination.parent, prefix=".download-", delete=False,
+                        ) as output:
+                            staged = Path(output.name)
+                            for chunk in response.iter_bytes(128 * 1024):
+                                size += len(chunk)
+                                if size > limit or time.monotonic() - started > 600:
+                                    raise SDKError("Download exceeded its size or time limit.")
+                                output.write(chunk)
+                        os.replace(staged, destination)
+                        return
+                raise SDKError("Too many download redirects.")
+        except httpx.HTTPError as error:
+            retryable = not isinstance(error, httpx.HTTPStatusError) or (
+                error.response.status_code in {408, 429, 500, 502, 503, 504}
+            )
+            if attempt == 2 or not retryable:
+                raise SDKError(f"Could not download {url}: {error}") from error
+            time.sleep(0.5 * (attempt + 1))
+        except (OSError, httpx.InvalidURL) as error:
+            raise SDKError(f"Could not download {url}: {error}") from error
+        finally:
+            if staged is not None:
+                staged.unlink(missing_ok=True)

sdkmgr/errors.py

@@ -0,0 +1,10 @@
+class SDKError(Exception):
+    """A tool could not be resolved, downloaded, or installed safely."""
+
+
+class InstallationRequired(SDKError):
+    """Installation was deferred; run command and retry the original operation."""
+
+    def __init__(self, command: tuple[str, ...], message: str):
+        self.command = command
+        super().__init__(message)