kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/doctor/__init__.py

@@ -0,0 +1,19 @@
+"""Health checks for ``kivyforge doctor`` (spec 05).
+
+Checks are pure functions over an injectable :class:`Probe`, so every
+PASS/WARN/FAIL/SKIP path is unit-testable without Xcode, a network, or a
+keychain. ``cli/doctor.py`` wires the real probe and renders the report.
+"""
+
+from __future__ import annotations
+
+from .probe import Probe, RealProbe
+from .result import CheckResult, Status, worst_status
+
+__all__ = [
+    "Probe",
+    "RealProbe",
+    "CheckResult",
+    "Status",
+    "worst_status",
+]

kivyforge/doctor/checks_common.py

@@ -0,0 +1,95 @@
+"""Platform-neutral doctor checks shared by every backend (spec 05).
+
+These checks are pure functions over an injectable :class:`Probe` and make no
+assumptions about the target platform, so iOS, macOS, and Linux all reuse them.
+Platform-specific checks live in ``platforms/<os>/doctor.py``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..config.model import Config
+from ..lock.resolver import MIN_PIP_VERSION, version_str
+from .probe import Probe
+from .result import CheckResult, Status
+
+SKIP_NOTE = "no pyproject.toml found in current directory"
+
+
+def lock_parse_fail(platform: str, exc: Exception) -> CheckResult:
+    """A FAIL result for an unreadable ``pylock.<platform>.toml``."""
+    return CheckResult(
+        f"pylock.{platform}.toml",
+        Status.FAIL,
+        f"failed to parse: {exc}",
+        hint=f"Regenerate it with `kivyforge lock -p {platform}`.",
+    )
+
+
+def _ver_tuple(v: str) -> tuple[int, ...]:
+    parts = []
+    for chunk in v.split("."):
+        digits = "".join(c for c in chunk if c.isdigit())
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)
+
+
+def check_pip_version(probe: Probe) -> CheckResult:
+    """pip >= 24.3 is required to match PEP 730 iOS platform tags at lock time."""
+    minimum = version_str(MIN_PIP_VERSION)
+    version = probe.pip_version()
+    if version is None:
+        return CheckResult(
+            "pip version",
+            Status.WARN,
+            "could not determine pip version",
+            hint="ensure pip is available: `python -m ensurepip --upgrade`.",
+        )
+    if _ver_tuple(version) < MIN_PIP_VERSION:
+        return CheckResult(
+            "pip version",
+            Status.FAIL,
+            f"{version} (need >= {minimum})",
+            hint=(
+                "pip < 24.3 cannot match iOS platform tags (PEP 730); "
+                "upgrade with `python -m pip install -U pip`."
+            ),
+        )
+    return CheckResult("pip version", Status.PASS, version)
+
+
+def check_kivyforge_version(
+    probe: Probe, current: str, *, offline: bool
+) -> CheckResult:
+    if offline:
+        return CheckResult("kivyforge version", Status.PASS, f"{current} (offline)")
+    latest = probe.latest_kivyforge_version()
+    if latest and _ver_tuple(latest) > _ver_tuple(current):
+        return CheckResult(
+            "kivyforge version",
+            Status.WARN,
+            f"{current} (latest {latest})",
+            hint="upgrade with `pip install -U kivyforge`.",
+        )
+    return CheckResult("kivyforge version", Status.PASS, current)
+
+
+def check_app_dir(config: Config, project_root: Path) -> CheckResult:
+    """``app_dir`` must resolve to an existing directory — it carries the app's
+    Python source into the bundle. Config validation only checks the *string*
+    (relative, non-empty, etc.), not that it exists on disk; a missing one would
+    otherwise build an app with no code (caught at build time, but reported here
+    first).
+    """
+    app_dir = config.kivy.app_dir
+    path = project_root / app_dir
+    if not path.is_dir():
+        return CheckResult(
+            "App source directory",
+            Status.FAIL,
+            f"app_dir {app_dir!r} not found",
+            hint="create the directory or fix [tool.kivy].app_dir; it must "
+            "point at your app's Python source.",
+        )
+    return CheckResult("App source directory", Status.PASS, app_dir)

kivyforge/doctor/probe.py

@@ -0,0 +1,357 @@
+"""Environment probes for doctor (the only place that touches the host).
+
+``Probe`` is the protocol the checks depend on; ``RealProbe`` is the macOS
+implementation (subprocess/socket/Mach-O parsing). Unit tests supply a fake
+object with the same methods, so the check logic never shells out.
+"""
+
+from __future__ import annotations
+
+import os
+import platform as _platform
+import shutil
+import socket
+import struct
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Protocol
+
+# How long to keep retrying to restore the build output after the lock probe
+# moved it aside. It was just renamed there on the same volume with no open
+# handles, so this normally succeeds on the first try; the retry only rides out
+# a transient antivirus touch.
+_RESTORE_TIMEOUT_S = 10.0
+
+# Mach-O platform constants (LC_BUILD_VERSION `platform`).
+PLATFORM_NAMES = {
+    1: "macos",
+    2: "ios",
+    3: "tvos",
+    4: "watchos",
+    7: "ios-simulator",
+    8: "tvos-simulator",
+    9: "watchos-simulator",
+}
+LC_BUILD_VERSION = 0x32
+_MACHO_MAGICS = {0xFEEDFACE, 0xFEEDFACF, 0xCEFAEDFE, 0xCFFAEDFE}
+
+
+class Probe(Protocol):
+    def xcode_version(self) -> str | None: ...
+    def pip_version(self) -> str | None: ...
+    def xcode_select_path(self) -> str | None: ...
+    def has_xcrun_clang(self) -> bool: ...
+    def has_swift_toolchain(self) -> bool: ...
+    def simulator_runtimes(self) -> list[str]: ...
+    def latest_kivyforge_version(self) -> str | None: ...
+    def keychain_identities(self) -> list[str]: ...
+    def login_keychain_identities(self) -> list[str]: ...
+    def tcp_reachable(self, host: str, port: int) -> bool: ...
+    def binary_platforms(self, path: Path) -> set[str]: ...
+    def host_system(self) -> str: ...
+    def has_codesign(self) -> bool: ...
+    def has_notarytool(self) -> bool: ...
+    def is_root(self) -> bool: ...
+    def linux_libc(self) -> str: ...
+    def shared_libraries(self) -> frozenset[str]: ...
+    def display_session(self) -> set[str]: ...
+    def has_desktop_file_validate(self) -> bool: ...
+    def desktop_file_errors(self, path: Path) -> str | None: ...
+    def long_paths_enabled(self) -> bool | None: ...
+    def has_signtool(self) -> bool: ...
+    def code_signing_thumbprints(self, store_scope: str) -> list[str]: ...
+    def build_output_locked(self, path: Path) -> bool | None: ...
+    def filesystem_type(self, path: Path) -> str | None: ...
+
+
+class RealProbe:
+    def host_system(self) -> str:
+        return _platform.system()
+
+    def has_codesign(self) -> bool:
+        return shutil.which("codesign") is not None
+
+    def has_notarytool(self) -> bool:
+        return bool(_capture(["xcrun", "--find", "notarytool"]))
+
+    def is_root(self) -> bool:
+        return hasattr(os, "geteuid") and os.geteuid() == 0
+
+    def xcode_version(self) -> str | None:
+        out = _capture(["xcodebuild", "-version"])
+        if not out:
+            return None
+        first = out.splitlines()[0]
+        return first.replace("Xcode", "").strip() or None
+
+    def pip_version(self) -> str | None:
+        # "pip 24.3.1 from /path/site-packages/pip (python 3.15)".
+        out = _capture([sys.executable, "-m", "pip", "--version"])
+        tokens = out.split()
+        if len(tokens) >= 2 and tokens[0] == "pip":
+            return tokens[1]
+        return None
+
+    def xcode_select_path(self) -> str | None:
+        return _capture(["xcode-select", "-p"]) or None
+
+    def has_xcrun_clang(self) -> bool:
+        return bool(_capture(["xcrun", "--find", "clang"]))
+
+    def has_swift_toolchain(self) -> bool:
+        return bool(_capture(["xcrun", "--find", "swift"]))
+
+    def simulator_runtimes(self) -> list[str]:
+        out = _capture(["xcrun", "simctl", "list", "runtimes", "iOS"])
+        versions = []
+        for line in out.splitlines():
+            # "iOS 18.0 (...) - com.apple.CoreSimulator.SimRuntime.iOS-18-0"
+            line = line.strip()
+            if line.startswith("iOS "):
+                parts = line.split()
+                if len(parts) >= 2:
+                    versions.append(parts[1])
+        return versions
+
+    def latest_kivyforge_version(self) -> str | None:
+        # Best-effort PyPI lookup; failures are non-fatal.
+        try:
+            import json
+            import urllib.request
+
+            url = "https://pypi.org/pypi/kivyforge/json"
+            with urllib.request.urlopen(url, timeout=3) as resp:  # noqa: S310
+                data = json.load(resp)
+            return data.get("info", {}).get("version")
+        except Exception:
+            return None
+
+    def keychain_identities(self) -> list[str]:
+        out = _capture(["security", "find-identity", "-v", "-p", "codesigning"])
+        return [line.strip() for line in out.splitlines() if line.strip()]
+
+    def login_keychain_identities(self) -> list[str]:
+        """Identities scoped to ``login.keychain-db`` (Apple recommends keeping
+        Developer ID identities out of it; see the ``Signing identity`` check).
+        """
+        login_keychain = str(
+            Path.home() / "Library" / "Keychains" / "login.keychain-db"
+        )
+        out = _capture(
+            ["security", "find-identity", "-v", "-p", "codesigning", login_keychain]
+        )
+        return [line.strip() for line in out.splitlines() if line.strip()]
+
+    def tcp_reachable(self, host: str, port: int) -> bool:
+        try:
+            with socket.create_connection((host, port), timeout=5):
+                return True
+        except OSError:
+            return False
+
+    def binary_platforms(self, path: Path) -> set[str]:
+        """Return the set of OS platforms a Mach-O (or fat) binary targets."""
+        try:
+            data = path.read_bytes()
+        except OSError:
+            return set()
+        return _macho_platforms(data)
+
+    def linux_libc(self) -> str:
+        """The host C library family: ``"glibc"``, ``"musl"``, or ``""``.
+
+        The bundled python-build-standalone runtime is a gnu/glibc ELF build,
+        so a musl host (Alpine) can't run it — doctor warns on that.
+        """
+        name = _platform.libc_ver()[0].lower()
+        if "glibc" in name or name == "libc":
+            return "glibc"
+        if any(Path("/lib").glob("ld-musl-*.so.1")):
+            return "musl"
+        return name
+
+    def shared_libraries(self) -> frozenset[str]:
+        """The sonames the dynamic linker's cache knows about (``ldconfig -p``)."""
+        out = _capture(["ldconfig", "-p"]) or _capture(["/sbin/ldconfig", "-p"])
+        libs: set[str] = set()
+        for line in out.splitlines():
+            token = line.strip().split(" ", 1)[0]
+            if token and token.startswith("lib"):
+                libs.add(token)
+        return frozenset(libs)
+
+    def display_session(self) -> set[str]:
+        """The display servers this session exposes via the environment."""
+        sessions: set[str] = set()
+        if os.environ.get("WAYLAND_DISPLAY"):
+            sessions.add("wayland")
+        if os.environ.get("DISPLAY"):
+            sessions.add("x11")
+        return sessions
+
+    def has_desktop_file_validate(self) -> bool:
+        return shutil.which("desktop-file-validate") is not None
+
+    def desktop_file_errors(self, path: Path) -> str | None:
+        try:
+            proc = subprocess.run(
+                ["desktop-file-validate", str(path)], capture_output=True, text=True
+            )
+        except (OSError, ValueError):
+            return None
+        if proc.returncode == 0:
+            return None
+        return (proc.stdout + proc.stderr).strip() or "validation failed"
+
+    def long_paths_enabled(self) -> bool | None:
+        """Whether ``LongPathsEnabled`` is on (``None`` when it can't be read).
+
+        Reads ``HKLM\\SYSTEM\\CurrentControlSet\\Control\\FileSystem`` — the
+        per-machine switch that lifts the legacy 260-char ``MAX_PATH`` limit that
+        deep bundle trees (a full PBS prefix under ``build/windows``) can hit.
+        """
+        try:
+            import winreg
+        except ImportError:
+            return None
+        try:
+            with winreg.OpenKey(
+                winreg.HKEY_LOCAL_MACHINE,
+                r"SYSTEM\CurrentControlSet\Control\FileSystem",
+            ) as key:
+                value, _ = winreg.QueryValueEx(key, "LongPathsEnabled")
+                return bool(value)
+        except OSError:
+            return None
+
+    def has_signtool(self) -> bool:
+        return shutil.which("signtool") is not None
+
+    def code_signing_thumbprints(self, store_scope: str) -> list[str]:
+        """Thumbprints of code-signing certs in the store *signtool* will use.
+
+        ``machine`` -> ``Cert:\\LocalMachine\\My`` (signtool's ``/sm``);
+        anything else -> ``Cert:\\CurrentUser\\My``. Thumbprints are normalized
+        to upper-case with no spaces to match the configured value.
+        """
+        store = "LocalMachine" if store_scope == "machine" else "CurrentUser"
+        script = (
+            f"Get-ChildItem Cert:\\{store}\\My -CodeSigningCert "
+            "| ForEach-Object { $_.Thumbprint }"
+        )
+        out = _capture(["powershell", "-NoProfile", "-Command", script])
+        return [
+            line.strip().replace(" ", "").upper()
+            for line in out.splitlines()
+            if line.strip()
+        ]
+
+    def build_output_locked(self, path: Path) -> bool | None:
+        """Whether a built onedir *path* is currently held open by a process.
+
+        ``None`` when *path* does not exist (nothing built). Otherwise performs
+        the exact metadata rename ``build``/``package`` will do — move the tree
+        aside — and immediately restores it, returning ``True`` when a sharing/
+        access lock blocks it (a running instance of the app, or an Explorer/
+        terminal window sitting in the folder), ``False`` when it is free.
+
+        A diagnostic must never lose the user's build: if the aside succeeds the
+        restore is retried and, in the vanishingly unlikely event it still fails,
+        raises ``OSError`` naming where the tree now sits — rather than silently
+        leaving the live build displaced under a hidden name.
+        """
+        if not path.exists():
+            return None
+        aside = path.with_name(f".{path.name}.doctorlock-{os.getpid()}")
+        try:
+            os.replace(path, aside)
+        except OSError:
+            return True
+        deadline = time.monotonic() + _RESTORE_TIMEOUT_S
+        delay = 0.1
+        while True:
+            try:
+                os.replace(aside, path)
+                return False
+            except OSError as exc:
+                if time.monotonic() >= deadline:
+                    raise OSError(
+                        f"doctor moved {path.name!r} aside to test its build "
+                        f"lock but could not restore it; the build output is now "
+                        f"at {aside}. Move it back to {path} manually."
+                    ) from exc
+                time.sleep(delay)
+                delay = min(delay * 1.5, 1.0)
+
+    def filesystem_type(self, path: Path) -> str | None:
+        """The filesystem of the volume holding *path* (e.g. ``"NTFS"`` /
+        ``"ReFS"``), or ``None`` when it can't be read. A trusted ReFS Dev Drive
+        is where Defender runs asynchronous 'performance mode' scans.
+        """
+        import ctypes
+
+        if not hasattr(ctypes, "windll"):
+            return None
+        drive = os.path.splitdrive(os.path.abspath(str(path)))[0]
+        if not drive:
+            return None
+        buf = ctypes.create_unicode_buffer(261)
+        try:
+            ok = ctypes.windll.kernel32.GetVolumeInformationW(  # type: ignore[attr-defined]
+                drive + "\\", None, 0, None, None, None, buf, len(buf)
+            )
+        except OSError:
+            return None
+        return buf.value if ok else None
+
+
+def _capture(argv: list[str]) -> str:
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True)
+    except (OSError, ValueError):
+        return ""
+    return proc.stdout if proc.returncode == 0 else ""
+
+
+def _macho_platforms(data: bytes) -> set[str]:
+    if len(data) < 4:
+        return set()
+    magic = struct.unpack(">I", data[:4])[0]
+    # Fat binary: parse each arch slice.
+    if magic in (0xCAFEBABE, 0xBEBAFECA):
+        platforms: set[str] = set()
+        nfat = struct.unpack(">I", data[4:8])[0]
+        for i in range(nfat):
+            off = 8 + i * 20
+            (offset,) = struct.unpack(">I", data[off + 8 : off + 12])
+            platforms |= _thin_platforms(data[offset:])
+        return platforms
+    return _thin_platforms(data)
+
+
+def _thin_platforms(data: bytes) -> set[str]:
+    if len(data) < 4:
+        return set()
+    magic = struct.unpack(">I", data[:4])[0]
+    if magic not in _MACHO_MAGICS:
+        return set()
+    little = magic in (0xCEFAEDFE, 0xCFFAEDFE)
+    is64 = magic in (0xFEEDFACF, 0xCFFAEDFE)
+    end = "<" if little else ">"
+    header = 32 if is64 else 28
+    ncmds = struct.unpack(end + "I", data[16:20])[0]
+    offset = header
+    platforms: set[str] = set()
+    for _ in range(ncmds):
+        if offset + 8 > len(data):
+            break
+        cmd, cmdsize = struct.unpack(end + "II", data[offset : offset + 8])
+        if cmd == LC_BUILD_VERSION and offset + 16 <= len(data):
+            (plat,) = struct.unpack(end + "I", data[offset + 8 : offset + 12])
+            platforms.add(PLATFORM_NAMES.get(plat, f"platform-{plat}"))
+        if cmdsize == 0:
+            break
+        offset += cmdsize
+    return platforms

kivyforge/doctor/result.py

@@ -0,0 +1,41 @@
+"""Check result types for doctor."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Status(Enum):
+    PASS = "PASS"
+    WARN = "WARN"
+    FAIL = "FAIL"
+    SKIP = "SKIP"
+
+
+# Severity ordering for computing the overall worst status.
+_ORDER = {Status.PASS: 0, Status.SKIP: 0, Status.WARN: 1, Status.FAIL: 2}
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    status: Status
+    detail: str = ""
+    hint: str = ""
+
+    def render(self) -> str:
+        line = f"[{self.status.value}] {self.name}"
+        if self.detail:
+            line += f": {self.detail}"
+        if self.hint and self.status in (Status.WARN, Status.FAIL):
+            line += f"\n       hint: {self.hint}"
+        return line
+
+
+def worst_status(results: list[CheckResult]) -> Status:
+    worst = Status.PASS
+    for r in results:
+        if _ORDER[r.status] > _ORDER[worst]:
+            worst = r.status
+    return worst

kivyforge/lock/__init__.py

@@ -0,0 +1,42 @@
+"""kivyforge shared lock core (spec 02).
+
+Platform-neutral lock building blocks shared by every backend: the PEP 751
+``[[packages]]`` model, the drift check, the neutral pip helpers, and the
+generic wheel+runtime engine (``kivyforge.lock.wheelruntime``). The iOS lock
+surface lives in ``kivyforge.platforms.ios.lock``; the macOS/Linux surfaces in
+``kivyforge.platforms.<os>.lock``.
+"""
+
+from __future__ import annotations
+
+from .model import (
+    LOCK_VERSION,
+    LockedPackage,
+    LockedWheel,
+    PackageDep,
+    canonical_name,
+)
+from .reader import LockError, compute_pyproject_sha256, is_in_sync
+from .resolver import (
+    MIN_PIP_VERSION,
+    abi_tags,
+    pip_python_version,
+    pip_version,
+    version_str,
+)
+
+__all__ = [
+    "LOCK_VERSION",
+    "LockedPackage",
+    "LockedWheel",
+    "PackageDep",
+    "canonical_name",
+    "LockError",
+    "compute_pyproject_sha256",
+    "is_in_sync",
+    "MIN_PIP_VERSION",
+    "abi_tags",
+    "pip_python_version",
+    "pip_version",
+    "version_str",
+]

kivyforge/lock/_pip_shim.py

@@ -0,0 +1,63 @@
+"""Run pip with the *target's* PEP 508 marker environment.
+
+kivyforge invokes this instead of ``-m pip`` when cross-resolving. It replaces
+``packaging.markers.default_environment`` — the single function every
+``Marker.evaluate()`` consults — with the target environment supplied as JSON in
+``KIVYFORGE_TARGET_MARKER_ENV``, then hands control to pip unchanged.
+
+pip still performs the whole resolution, including backtracking and platform
+wheel-tag expansion; only its answer to "what platform am I resolving for?"
+changes. kivyforge deliberately does not reimplement any of that.
+
+Platform-neutral by design: each backend describes its own target
+(``platforms/android/lock/markers.py``, ``platforms/ios/lock/markers.py``).
+
+This is a documented dependency on a pip internal, so it fails loudly rather
+than silently falling back to host markers: a quiet fallback would reintroduce
+exactly the host-dependent lock this exists to prevent.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+MARKER_ENV_VAR = "KIVYFORGE_TARGET_MARKER_ENV"
+
+
+def main(argv: list[str]) -> int:
+    raw = os.environ.get(MARKER_ENV_VAR)
+    if not raw:
+        sys.stderr.write(
+            f"{MARKER_ENV_VAR} is not set; refusing to resolve with the "
+            "host's marker environment.\n"
+        )
+        return 2
+    environment = json.loads(raw)
+
+    try:
+        from pip._vendor.packaging import markers
+    except ImportError:
+        sys.stderr.write(
+            "this pip does not vendor packaging.markers where kivyforge "
+            "expects it, so environment markers cannot be evaluated for the "
+            "target platform. Please report the pip version.\n"
+        )
+        return 3
+    if not hasattr(markers, "default_environment"):
+        sys.stderr.write(
+            "pip's vendored packaging has no default_environment(); kivyforge "
+            "cannot retarget marker evaluation. Please report the pip version.\n"
+        )
+        return 3
+
+    markers.default_environment = lambda: dict(environment)
+
+    from pip._internal.cli.main import main as pip_main
+
+    return pip_main(argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))