kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/windows/naming.py

@@ -0,0 +1,52 @@
+"""Windows-safe artifact naming (windows-spec).
+
+The launcher ``<name>.exe`` and the packaged ``dist/windows`` folder name are
+derived from ``[tool.kivy].display_name`` through :func:`windows_safe_name`,
+which strips/replaces characters illegal in Windows filenames, avoids the
+reserved DOS device names, and drops trailing dots/spaces (which Windows
+silently removes). It is a pure helper so it is trivially unit-testable.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Characters that are illegal in a Windows filename component, plus control
+# characters (0x00–0x1F). Backslash and forward slash are path separators.
+_ILLEGAL = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+# Reserved DOS device names (case-insensitive). A component whose stem (the part
+# before the first dot) is one of these is illegal even with an extension
+# (``NUL.txt`` is still reserved).
+_RESERVED = frozenset(
+    {
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        *(f"COM{i}" for i in range(1, 10)),
+        *(f"LPT{i}" for i in range(1, 10)),
+    }
+)
+
+
+def windows_safe_name(display_name: str, *, fallback: str = "App") -> str:
+    """Return a Windows-filesystem-safe base name derived from ``display_name``.
+
+    Illegal characters become spaces (so ``"My|App"`` reads as ``"My App"``),
+    runs of whitespace collapse to a single space, and leading/trailing spaces
+    and trailing dots are removed. If the stem collides with a reserved device
+    name it is suffixed with ``_``. Returns ``fallback`` when nothing usable
+    remains (e.g. a name made entirely of illegal characters).
+    """
+    cleaned = _ILLEGAL.sub(" ", display_name)
+    # Collapse internal whitespace runs and strip the ends.
+    cleaned = " ".join(cleaned.split())
+    # Windows silently drops trailing dots and spaces from names.
+    cleaned = cleaned.rstrip(" .")
+    if not cleaned:
+        return fallback
+    stem = cleaned.split(".", 1)[0]
+    if stem.upper() in _RESERVED:
+        cleaned = f"{cleaned}_"
+    return cleaned

kivyforge/platforms/windows/native_stage.py

@@ -0,0 +1,66 @@
+"""Stage locked native binaries into the onedir ``bin\\`` (windows-spec).
+
+The ``[tool.kivy.windows.native.binaries]`` channel: each entry is fetched +
+SHA-256-verified from ``pylock.windows.toml`` (URL or vendored path) and staged
+into ``<bundle>\\bin`` — a single native file, or a ``.zip`` / ``.tar.gz`` /
+``.tgz`` of several extracted with a path-traversal guard. ``bin\\`` is created
+only when the lock actually pins binaries. The bootstrap registers ``<bundle>\\bin`` with
+``os.add_dll_directory`` and prepends it to ``PATH``.
+
+The staging mechanics live in the shared
+:mod:`kivyforge.artifacts.native_stage_util`; this is the Windows-facing wrapper
+that translates :class:`NativeStageError` into :class:`WindowsBundleError` and
+supplies the Windows-specific guards: case-insensitive collision keys, reserved
+DOS device name / alternate-data-stream rejection, and a PE machine-architecture
+check (:mod:`~kivyforge.platforms.windows.petools`) so a wrong-arch DLL is caught
+at assembly time rather than at load.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.native_stage_util import NativeStageError, stage_binaries
+
+from . import WindowsBundleError
+from .lock import WindowsLockfile
+from .petools import PeArchError, verify_pe_arch
+
+
+def stage_native_binaries(
+    lock: WindowsLockfile,
+    bundle: Path,
+    arch: str,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> None:
+    """Stage every pinned native binary for the lock into ``<bundle>\\bin``.
+
+    Each staged PE is checked against *arch* (a wrong-architecture DLL fails the
+    build with a clear message); non-PE members (data files, scripts) are
+    ignored by the check.
+    """
+
+    def _validate(path: Path) -> None:
+        try:
+            verify_pe_arch(path, arch)
+        except PeArchError as exc:
+            raise NativeStageError(str(exc)) from exc
+
+    try:
+        stage_binaries(
+            lock.native_binaries,
+            bundle,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+            bin_label="bin",
+            casefold=True,
+            reject_windows_names=True,
+            validate=_validate,
+        )
+    except NativeStageError as exc:
+        raise WindowsBundleError(str(exc)) from exc

kivyforge/platforms/windows/petools.py

@@ -0,0 +1,98 @@
+"""Minimal PE (Portable Executable) machine-type reader (windows-spec).
+
+The PE analog of Linux ``elftools`` / macOS ``machotools``: a tiny, pure-Python
+reader of the COFF header ``Machine`` field so a wrong-architecture DLL/EXE
+staged into an amd64 app is caught with a clear message instead of a cryptic
+load failure at runtime. Pure-Python (no ``ctypes``/OS APIs), so it runs on any
+host and in hermetic unit tests.
+
+Layout walked: ``MZ`` DOS signature at offset 0, the 4-byte PE-header offset at
+``0x3C``, the ``PE\\0\\0`` signature there, then the COFF header whose first
+field is the 2-byte little-endian ``Machine``.
+"""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+# IMAGE_FILE_MACHINE_* values (winnt.h).
+IMAGE_FILE_MACHINE_I386 = 0x014C
+IMAGE_FILE_MACHINE_AMD64 = 0x8664
+IMAGE_FILE_MACHINE_ARM64 = 0xAA64
+IMAGE_FILE_MACHINE_ARMNT = 0x01C4
+
+# kivyforge arch name -> expected PE machine.
+# arm64: already mapped — verify_pe_arch() validates arm64 native binaries today,
+# so this module needs no change when win_arm64 lands. See arm64-windows.md §4.
+_ARCH_MACHINE = {
+    "amd64": IMAGE_FILE_MACHINE_AMD64,
+    "arm64": IMAGE_FILE_MACHINE_ARM64,
+}
+
+_MACHINE_NAME = {
+    IMAGE_FILE_MACHINE_I386: "x86 (i386)",
+    IMAGE_FILE_MACHINE_AMD64: "x64 (amd64)",
+    IMAGE_FILE_MACHINE_ARM64: "arm64",
+    IMAGE_FILE_MACHINE_ARMNT: "arm (32-bit)",
+}
+
+
+def machine_name(machine: int) -> str:
+    """A human label for a PE ``Machine`` value (hex fallback if unknown)."""
+    return _MACHINE_NAME.get(machine, f"0x{machine:04x}")
+
+
+def machine_for_arch(arch: str) -> int | None:
+    """The expected PE ``Machine`` for a kivyforge *arch* (``None`` if unknown)."""
+    return _ARCH_MACHINE.get(arch)
+
+
+def read_pe_machine(path: Path) -> int | None:
+    """Return the PE ``Machine`` value of *path*, or ``None`` if it is not a PE.
+
+    Reads only the headers; never loads the file. Non-PE files (a ``.txt`` in a
+    zip, a truncated stub) return ``None`` so callers can skip them.
+    """
+    try:
+        with path.open("rb") as fh:
+            head = fh.read(0x40)
+            if len(head) < 0x40 or head[:2] != b"MZ":
+                return None
+            pe_offset = struct.unpack_from("<I", head, 0x3C)[0]
+            fh.seek(pe_offset)
+            sig = fh.read(6)  # "PE\0\0" + first 2 bytes of Machine
+            if len(sig) < 6 or sig[:4] != b"PE\x00\x00":
+                return None
+            return struct.unpack_from("<H", sig, 4)[0]
+    except OSError:
+        return None
+
+
+def is_pe(path: Path) -> bool:
+    """Whether *path* is a PE image (has a valid MZ + PE signature)."""
+    return read_pe_machine(path) is not None
+
+
+class PeArchError(Exception):
+    """A staged PE image does not match the target architecture."""
+
+
+def verify_pe_arch(path: Path, arch: str) -> None:
+    """Raise :class:`PeArchError` if *path* is a PE for a different *arch*.
+
+    Non-PE files are ignored (a native-binary channel may carry data files or
+    scripts). Unknown target archs are not enforced (forward-compat).
+    """
+    expected = machine_for_arch(arch)
+    if expected is None:
+        return
+    machine = read_pe_machine(path)
+    if machine is None or machine == expected:
+        return
+    raise PeArchError(
+        f"{path.name} is a {machine_name(machine)} PE image, but the app targets "
+        f"{arch} ({machine_name(expected)}).\n"
+        "  Ship the matching-architecture binary in "
+        "[tool.kivy.windows.native.binaries]."
+    )

kivyforge/platforms/windows/rcedit.py

@@ -0,0 +1,116 @@
+"""Per-app launcher resource patching via the vendored ``rcedit`` (windows-spec).
+
+The single vendored launcher is parameterized per app only by its *resources*
+(no recompilation): the icon (from ``[tool.kivy.windows.icons]``) and the
+version resource (product/file version, names, copyright — from ``[project]`` /
+``[tool.kivy]``). ``rcedit`` performs the edit without any toolchain.
+
+Command construction (:func:`build_rcedit_args`) is pure and host-agnostic so it
+is unit-tested directly; execution (:func:`patch_resources`) is Windows-only.
+Patching happens **before** signing — a resource edit invalidates any existing
+Authenticode signature (the signing pipeline guarantees the order).
+
+The numeric ``FILEVERSION``/``PRODUCTVERSION`` are four 16-bit integers; the
+PEP 440 → four-part mapping lives in signing (Phase 9) and is passed in here as
+an already-formatted ``a.b.c.d`` string.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import WindowsBundleError
+
+
+@dataclass(frozen=True)
+class ResourcePatch:
+    """The per-app resources to write into a launcher copy.
+
+    Every field is optional: only the ones set emit an ``rcedit`` flag, so a
+    minimal project (no icon, no metadata) still produces a valid launcher.
+    ``file_version``/``product_version`` are the numeric ``a.b.c.d`` forms;
+    ``product_version_string`` carries the human PEP 440 string.
+    """
+
+    icon: Path | None = None
+    product_name: str | None = None
+    file_description: str | None = None
+    product_version_string: str | None = None
+    legal_copyright: str | None = None
+    company_name: str | None = None
+    file_version: str | None = None  # numeric "a.b.c.d"
+    product_version: str | None = None  # numeric "a.b.c.d"
+
+    @property
+    def is_empty(self) -> bool:
+        return all(
+            getattr(self, f) is None
+            for f in (
+                "icon",
+                "product_name",
+                "file_description",
+                "product_version_string",
+                "legal_copyright",
+                "company_name",
+                "file_version",
+                "product_version",
+            )
+        )
+
+
+def build_rcedit_args(rcedit: Path, exe: Path, patch: ResourcePatch) -> list[str]:
+    """The full ``rcedit`` argv to patch *exe* in place (one invocation).
+
+    ``rcedit`` applies every ``--set-*`` operation given in a single call, so
+    the whole patch is one command. Returns ``[rcedit, exe]`` (no-op) when the
+    patch is empty — callers may skip execution in that case.
+    """
+    args: list[str] = [str(rcedit), str(exe)]
+    if patch.icon is not None:
+        args += ["--set-icon", str(patch.icon)]
+    # Numeric version fields first (dedicated flags), then string fields.
+    if patch.file_version is not None:
+        args += ["--set-file-version", patch.file_version]
+    if patch.product_version is not None:
+        args += ["--set-product-version", patch.product_version]
+    string_fields = [
+        ("ProductName", patch.product_name),
+        ("FileDescription", patch.file_description),
+        ("ProductVersion", patch.product_version_string),
+        ("LegalCopyright", patch.legal_copyright),
+        ("CompanyName", patch.company_name),
+    ]
+    for key, value in string_fields:
+        if value is not None:
+            args += ["--set-version-string", key, value]
+    return args
+
+
+def patch_resources(
+    exe: Path, patch: ResourcePatch, *, rcedit: Path | None = None
+) -> None:
+    """Patch *exe*'s icon/version resources in place with ``rcedit`` (Windows).
+
+    A no-op when *patch* is empty. Raises :class:`WindowsBundleError` on any
+    ``rcedit`` failure.
+    """
+    if patch.is_empty:
+        return
+    if rcedit is None:
+        from .assets import vendored_rcedit
+
+        rcedit = vendored_rcedit()
+    args = build_rcedit_args(rcedit, exe, patch)
+    try:
+        proc = subprocess.run(args, capture_output=True, text=True)
+    except OSError as exc:
+        raise WindowsBundleError(
+            f"failed to run rcedit ({rcedit}): {exc}. rcedit is Windows-only."
+        ) from exc
+    if proc.returncode != 0:
+        raise WindowsBundleError(
+            f"rcedit failed to patch {exe.name} (exit {proc.returncode}):\n"
+            f"{(proc.stderr or proc.stdout).strip()}"
+        )

kivyforge/platforms/windows/runtime_stage.py

@@ -0,0 +1,221 @@
+"""Stage the bundled CPython runtime into the onedir ``python\\`` prefix.
+
+Consumes the provider-agnostic runtime pin from ``pylock.windows.toml`` (a single
+``amd64`` artifact this phase), fetches + SHA-256-verifies its archive, extracts
+it, and materializes the **whole** python-build-standalone prefix at
+``<bundle>\\python`` — never flattened or pruned. The Windows PBS layout keeps
+``python.exe`` at the prefix root alongside ``python3xx.dll``, with ``DLLs\\``,
+``Lib\\``, ``Scripts\\`` etc. beneath it; the launcher points ``PYTHONHOME`` here.
+
+VC++ runtime (Phase 0 finding — resolved): the PBS ``install_only`` Windows
+archive ships ``vcruntime140.dll`` and ``vcruntime140_1.dll`` next to
+``python.exe`` but **not** ``msvcp140.dll`` (the C++ runtime some native deps
+need). :func:`ensure_vc_runtime` verifies the core CPython DLLs are present
+(a no-op for stock PBS, with an app-local fallback should a future PBS build
+drop them) and best-effort places ``msvcp140.dll`` app-local when the runtime
+itself omits it — never relying on a system-installed VCRedist, which is the
+classic clean-machine failure.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import struct
+import tarfile
+import tempfile
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.download import DownloadError, fetch_artifact
+from kivyforge.lock.wheelruntime.model import PythonRuntime
+from kivyforge.lock.wheelruntime.runtime import (
+    RuntimeProviderError,
+    normalized_runtime_root,
+)
+
+from . import WindowsBundleError
+from .petools import machine_for_arch, read_pe_machine
+
+# CPython itself links these; without them python.exe will not start. PBS ships
+# them, so the check is normally a no-op.
+CORE_VC_RUNTIME = ("vcruntime140.dll", "vcruntime140_1.dll")
+# The C++ runtime; PBS does NOT ship it. Native deps (SDL, codecs) may need it.
+# Placed app-local best-effort when neither the runtime nor a dep provides it.
+CXX_VC_RUNTIME = "msvcp140.dll"
+
+# The host location the redistributable VC++ runtime DLLs live in, used only as
+# a fallback source when the runtime archive omits one.
+DEFAULT_SYSTEM_DIR = Path(r"C:\Windows\System32")
+
+
+def stage_runtime(
+    runtime: PythonRuntime,
+    arch: str,
+    home: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+    system_dir: Path | None = None,
+) -> Path:
+    """Materialize the whole runtime prefix for *arch* at *home*; return *home*.
+
+    *home* is the final CPython prefix (``<bundle>\\python``). It is emptied and
+    recreated, then the conditional VC-runtime step runs.
+    """
+    cache = cache or ArtifactCache()
+    artifact = runtime.artifact_for(arch)
+    if artifact is None:
+        raise WindowsBundleError(
+            f"the lock has no {arch} runtime artifact; re-run "
+            f"`kivyforge lock -p windows` (locked archs: "
+            f"{', '.join(a.arch for a in runtime.artifacts)})."
+        )
+
+    tmp = Path(tempfile.mkdtemp(prefix="kivy-runtime-"))
+    try:
+        archive = _fetch(artifact, arch, project_root, cache, no_cache)
+        extracted = _extract(archive, tmp, runtime.provider)
+        if home.exists():
+            shutil.rmtree(home)
+        home.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(extracted, home, symlinks=True)
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    ensure_vc_runtime(home, arch=arch, system_dir=system_dir)
+    return home
+
+
+def ensure_vc_runtime(
+    home: Path, *, arch: str = "amd64", system_dir: Path | None = None
+) -> tuple[str, ...]:
+    """Guarantee the VC++ runtime DLLs the prefix needs sit next to python.exe.
+
+    Returns the DLLs this step placed app-local (empty when the runtime already
+    provides everything, the common PBS case). Raises if a *core* CPython DLL is
+    missing and cannot be sourced — python.exe could not start otherwise.
+
+    Any DLL taken from the host fallback is checked against *arch*: under a
+    32-bit Python process ``C:\\Windows\\System32`` is WOW64-redirected to the
+    x86 ``SysWOW64``, so a naive copy could put an x86 runtime into an amd64
+    bundle. Mismatched host DLLs are refused (core) or skipped (msvcp140).
+    """
+    source = system_dir if system_dir is not None else _default_system_dir()
+    placed: list[str] = []
+
+    for dll in CORE_VC_RUNTIME:
+        if (home / dll).is_file():
+            continue
+        if _copy_from(source, dll, home, arch):
+            placed.append(dll)
+        else:
+            raise WindowsBundleError(
+                f"the staged runtime is missing {dll} and no {arch} copy was "
+                f"found in {source}. python.exe cannot start without the VC++ "
+                "runtime; the runtime archive or a matching-architecture VC++ "
+                "redistributable is required."
+            )
+
+    # Best-effort: only place the C++ runtime app-local when the runtime omits
+    # it. A dep wheel may still ship it into site-packages; that is fine.
+    if not (home / CXX_VC_RUNTIME).is_file() and _copy_from(
+        source, CXX_VC_RUNTIME, home, arch
+    ):
+        placed.append(CXX_VC_RUNTIME)
+
+    return tuple(placed)
+
+
+def _copy_from(source: Path, name: str, home: Path, arch: str) -> bool:
+    """Copy *source*/*name* to *home* iff it matches *arch*; return if copied.
+
+    A host DLL whose PE machine type does not match the target architecture is
+    treated as absent — never copied — so a WOW64-redirected (x86) fallback or
+    any other wrong-arch source cannot poison the bundle.
+    """
+    candidate = source / name
+    if not candidate.is_file():
+        return False
+    expected = machine_for_arch(arch)
+    machine = read_pe_machine(candidate)
+    if expected is not None and machine is not None and machine != expected:
+        return False
+    shutil.copy2(candidate, home / name)
+    return True
+
+
+def _default_system_dir() -> Path:
+    """The host source for VC-runtime fallbacks, WOW64-redirection aware.
+
+    A 32-bit Python process has ``System32`` file-system-redirected to the x86
+    ``SysWOW64``; the ``Sysnative`` pseudo-directory reaches the real 64-bit
+    ``System32`` from such a process. On a 64-bit interpreter ``System32`` is
+    already correct.
+    """
+    # arm64: this WOW64 logic is x86/x64-specific and does not generalize to
+    # Arm64 Windows (the WOW layer there is Arm32 SysArm32, plus x64 emulation).
+    # The host-System32 fallback only ever works same-arch: cross-building an
+    # arm64 bundle on an x64 host cannot source an arm64 msvcp140.dll here (the
+    # _copy_from PE-machine guard correctly refuses the x64 one). The intended
+    # fix is NOT to teach this function about arm64 System32 — it is to pin
+    # msvcp140.dll as a per-arch, SHA-256-verified artifact and retire this
+    # host fallback, which is what makes cross-arch builds host-independent.
+    # See arm64-windows.md §6, §7.
+    if struct.calcsize("P") == 4:  # 32-bit interpreter
+        root = Path(os.environ.get("SystemRoot", r"C:\Windows"))
+        sysnative = root / "Sysnative"
+        if sysnative.is_dir():
+            return sysnative
+    return DEFAULT_SYSTEM_DIR
+
+
+def _fetch(artifact, arch, project_root, cache, no_cache) -> Path:
+    filename = artifact.url.rsplit("/", 1)[-1] or f"python-{arch}.tar.gz"
+    try:
+        return fetch_artifact(
+            name=f"python runtime ({arch})",
+            sha256=artifact.sha256,
+            filename=filename,
+            url=artifact.url,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+    except DownloadError as exc:
+        raise WindowsBundleError(str(exc)) from exc
+
+
+def _extract(archive: Path, into: Path, provider: str) -> Path:
+    into.mkdir(parents=True, exist_ok=True)
+    try:
+        with tarfile.open(archive, "r:*") as tf:
+            _safe_extractall(tf, into)
+    except (tarfile.TarError, OSError) as exc:
+        raise WindowsBundleError(f"failed to extract {archive.name}: {exc}") from exc
+    try:
+        return normalized_runtime_root(provider, into)
+    except RuntimeProviderError as exc:
+        raise WindowsBundleError(f"{archive.name}: {exc}") from exc
+
+
+def _safe_extractall(tf: tarfile.TarFile, into: Path) -> None:
+    """Extract, rejecting members that would escape *into*.
+
+    The explicit name check gives a clear message for the common ``../`` case;
+    ``filter="data"`` then provides the protection the name check cannot — it
+    validates symlink/hardlink *targets* (a safely named link pointing outside,
+    written through by a later member, would otherwise escape) and strips device
+    nodes and other special files. ``filter="fully_trusted"`` restored links
+    verbatim and did none of this.
+    """
+    base = into.resolve()
+    for member in tf.getmembers():
+        target = (into / member.name).resolve()
+        if not (target == base or base in target.parents):
+            raise WindowsBundleError(f"unsafe path in archive: {member.name!r}")
+    try:
+        tf.extractall(into, filter="data")  # noqa: S202 — hardened filter (validates links)
+    except tarfile.FilterError as exc:
+        raise WindowsBundleError(f"unsafe member in archive: {exc}") from exc