kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/cli/lock.py

@@ -0,0 +1,261 @@
+"""``kivyforge lock`` — resolve dependencies into pylock.<platform>.toml.
+
+The verb resolves the target platform (``-p`` / ``KIVYFORGE_PLATFORM`` / host)
+and dispatches to that backend's lock engine, writing ``pylock.<platform>.toml``.
+Each backend supplies its own build/serialize/compare callables; the drift check
+(``pyproject_sha256``) and atomic write are shared.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+from ..config import ConfigError, load_config
+from ..lock.reader import LockError, is_in_sync
+from ..platforms.base import HostCapabilityError
+from ..platforms.ios.lock import (
+    BuildError,
+    build_lockfile,
+    diff_summary,
+    dumps,
+    load,
+    semantic_equal,
+)
+from ._common import ToolchainError, lockfile_path_for
+from ._platform import platform_option, resolve_target
+
+
+@dataclass(frozen=True)
+class _LockOps:
+    """Per-platform lock callables (raise ``BuildError``/``LockError``)."""
+
+    build: Callable
+    dumps: Callable
+    load: Callable
+    semantic_equal: Callable
+    diff_summary: Callable
+    build_error: type[Exception]
+    require_ios: bool
+    require_macos: bool
+    require_linux: bool = False
+    require_windows: bool = False
+    require_android: bool = False
+    # Wheel+runtime backends (macOS/Linux) surface non-fatal lock warnings
+    # (e.g. accepting a vendored plain linux_* wheel) via an on_warning callback.
+    emits_warnings: bool = False
+    # Most backends resolve with pip alone, so `lock` runs anywhere and the
+    # result is committed. iOS is the exception: resolving declared Swift
+    # packages shells out to `swift package resolve`, which needs the Xcode
+    # toolchain, so the whole iOS workflow — lock included — is macOS-only.
+    requires_host_toolchain: bool = False
+
+
+def _lock_ops(platform: str) -> _LockOps:
+    if platform == "ios":
+        # Reference the module globals (not a local import) so tests can patch
+        # ``lock_cli.build_lockfile`` with a fake-injecting wrapper.
+        return _LockOps(
+            build=build_lockfile,
+            dumps=dumps,
+            load=load,
+            semantic_equal=semantic_equal,
+            diff_summary=diff_summary,
+            build_error=BuildError,
+            require_ios=True,
+            require_macos=False,
+            requires_host_toolchain=True,
+        )
+    if platform == "macos":
+        from ..platforms.macos import lock as macos_lock
+
+        return _LockOps(
+            build=macos_lock.build_macos_lockfile,
+            dumps=macos_lock.dumps,
+            load=macos_lock.load,
+            semantic_equal=macos_lock.semantic_equal,
+            diff_summary=macos_lock.diff_summary,
+            build_error=macos_lock.MacosBuildError,
+            require_ios=False,
+            require_macos=True,
+            emits_warnings=True,
+        )
+    if platform == "linux":
+        from ..platforms.linux import lock as linux_lock
+
+        return _LockOps(
+            build=linux_lock.build_linux_lockfile,
+            dumps=linux_lock.dumps,
+            load=linux_lock.load,
+            semantic_equal=linux_lock.semantic_equal,
+            diff_summary=linux_lock.diff_summary,
+            build_error=linux_lock.LinuxBuildError,
+            require_ios=False,
+            require_macos=False,
+            require_linux=True,
+            emits_warnings=True,
+        )
+    if platform == "windows":
+        from ..platforms.windows import lock as windows_lock
+
+        return _LockOps(
+            build=windows_lock.build_windows_lockfile,
+            dumps=windows_lock.dumps,
+            load=windows_lock.load,
+            semantic_equal=windows_lock.semantic_equal,
+            diff_summary=windows_lock.diff_summary,
+            build_error=windows_lock.WindowsBuildError,
+            require_ios=False,
+            require_macos=False,
+            require_windows=True,
+            emits_warnings=True,
+        )
+    if platform == "android":
+        from ..platforms.android.lock import builder as android_builder
+        from ..platforms.android.lock import reader as android_reader
+        from ..platforms.android.lock import writer as android_writer
+
+        return _LockOps(
+            build=android_builder.build_lockfile,
+            dumps=android_writer.dumps,
+            load=android_reader.load,
+            semantic_equal=android_builder.semantic_equal,
+            diff_summary=android_builder.diff_summary,
+            build_error=android_builder.BuildError,
+            require_ios=False,
+            require_macos=False,
+            require_android=True,
+        )
+    raise ToolchainError(
+        f"`kivyforge lock` does not support platform {platform!r} yet."
+    )
+
+
+def _require_host_toolchain(backend) -> None:
+    """Gate `lock` for backends whose resolution needs a host toolchain."""
+    try:
+        backend.check_host_capability()
+    except HostCapabilityError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+@click.command()
+@platform_option
+@click.option("--update", is_flag=True, help="Re-resolve even if the lock is in sync.")
+@click.option("--offline", is_flag=True, help="Use cached resolution results only.")
+@click.option(
+    "--check",
+    is_flag=True,
+    help="CI pre-flight: exit non-zero if the lock is stale; write nothing.",
+)
+def lock(cli_platform: str | None, update: bool, offline: bool, check: bool) -> None:
+    """Generate pylock.<platform>.toml from pyproject.toml."""
+    backend, project_root = resolve_target(cli_platform, verb="lock")
+    ops = _lock_ops(backend.name)
+    if ops.requires_host_toolchain:
+        _require_host_toolchain(backend)
+
+    pyproject = project_root / "pyproject.toml"
+    pyproject_text = pyproject.read_text(encoding="utf-8")
+    out_path = lockfile_path_for(backend.name, project_root)
+
+    try:
+        config = load_config(
+            pyproject,
+            require_ios=ops.require_ios,
+            require_macos=ops.require_macos,
+            require_linux=ops.require_linux,
+            require_windows=ops.require_windows,
+            require_android=ops.require_android,
+        )
+    except ConfigError as exc:
+        raise ToolchainError(exc.format()) from exc
+
+    if check:
+        _run_check(ops, config, pyproject_text, out_path, project_root, offline)
+        return
+
+    if out_path.is_file() and not update:
+        try:
+            existing = ops.load(out_path)
+        except LockError:
+            existing = None
+        if existing is not None and is_in_sync(existing, pyproject_text):
+            click.echo(f"{out_path.name} is already in sync with pyproject.toml.")
+            click.echo("  (use --update to force re-resolution)")
+            return
+
+    new_lock = _build(ops, config, pyproject_text, project_root, offline)
+    _atomic_write(out_path, ops.dumps(new_lock))
+    click.echo(f"Wrote {out_path.name} ({len(new_lock.packages)} packages pinned).")
+
+
+def _run_check(
+    ops: _LockOps,
+    config,
+    pyproject_text: str,
+    out_path: Path,
+    project_root: Path,
+    offline: bool,
+) -> None:
+    if not out_path.is_file():
+        raise ToolchainError(
+            f"{out_path.name} does not exist. Run `kivyforge lock` first."
+        )
+    try:
+        existing = ops.load(out_path)
+    except LockError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+    candidate = _build(ops, config, pyproject_text, project_root, offline)
+    if ops.semantic_equal(existing, candidate):
+        click.echo(f"{out_path.name} is up to date.")
+        return
+    click.echo(f"{out_path.name} is out of date:", err=True)
+    for line in ops.diff_summary(existing, candidate):
+        click.echo(line, err=True)
+    raise ToolchainError("lock is stale; run `kivyforge lock`.")
+
+
+def _build(
+    ops: _LockOps, config, pyproject_text: str, project_root: Path, offline: bool
+):
+    kwargs = {}
+    if ops.emits_warnings:
+        kwargs["on_warning"] = lambda msg: click.echo(msg, err=True)
+    try:
+        return ops.build(
+            config,
+            pyproject_text,
+            project_root=project_root,
+            offline=offline,
+            **kwargs,
+        )
+    except ops.build_error as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    """Write to a tempfile, fsync, then rename (spec 02 step 5).
+
+    Always LF: a lock file is committed and compared across machines, so
+    letting the host's default line ending through would make a re-lock on
+    another OS rewrite every line. The lock must depend on the target, never
+    on who ran it.
+    """
+    directory = path.parent
+    fd, tmp = tempfile.mkstemp(dir=directory, prefix=".pylock.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)

kivyforge/cli/open_cmd.py

@@ -0,0 +1,15 @@
+"""``kivyforge open`` — open the generated Xcode project (spec 05)."""
+
+from __future__ import annotations
+
+import click
+
+from ._platform import platform_option, resolve_target
+
+
+@click.command(name="open")
+@platform_option
+def open_(cli_platform: str | None) -> None:
+    """Open <app>-ios/<app>.xcodeproj in Xcode."""
+    backend, project_root = resolve_target(cli_platform, verb="open")
+    backend.open_project(project_root)

kivyforge/cli/package.py

@@ -0,0 +1,134 @@
+"""``kivyforge package`` — build the distributable, signed artifact (docs 02/06).
+
+``package`` produces the finished, signed runnable artifact for the resolved
+target (wrapping it into an installer/container is out of scope). For iOS this is
+the release archive + exported ``.ipa``; other platforms register their own
+shapes via ``Platform.package_formats`` and are wired in as they land.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ._common import ToolchainError
+from ._platform import platform_option, reject_android_only, resolve_target
+
+
+@click.command()
+@platform_option
+@click.option(
+    "-f",
+    "--format",
+    "fmt",
+    default=None,
+    help="Artifact format for the target (defaults to the platform's default).",
+)
+@click.option(
+    "--arch",
+    # x86_64 stays: it is the Linux arch and an Android ABI, not a macOS one.
+    type=click.Choice(["arm64", "x86_64"]),
+    default=None,
+    help="macOS: assemble a subset of the locked archs.",
+)
+@click.option(
+    "--team-id", default=None, help="Override [tool.kivy.ios.signing].team_id."
+)
+@click.option(
+    "--signing-identity",
+    default=None,
+    help="Override [tool.kivy.<platform>.signing].identity.",
+)
+@click.option(
+    "--export-method",
+    type=click.Choice(["app-store", "ad-hoc", "development"]),
+    default="app-store",
+    help="iOS export method.",
+)
+@click.option(
+    "--notarize/--no-notarize",
+    "notarize",
+    default=None,
+    help="macOS: notarize + staple the signed .app (default: when "
+    "[tool.kivy.macos.signing].notary_profile is configured).",
+)
+@click.option(
+    "--notary-profile",
+    default=None,
+    help="macOS: override [tool.kivy.macos.signing].notary_profile.",
+)
+@click.option(
+    "--no-verify-lock", is_flag=True, help="Skip the pyproject drift check (CI only)."
+)
+@click.option("--no-cache", is_flag=True, help="Force re-download of every artifact.")
+# --- Android-only ---
+@click.option(
+    "--abi",
+    type=click.Choice(["arm64_v8a", "x86_64"]),
+    default=None,
+    help="Android: restrict this package to one ABI.",
+)
+@click.option(
+    "--keystore",
+    default=None,
+    help="Android: override [tool.kivy.android.signing].keystore.",
+)
+@click.option(
+    "--key-alias",
+    default=None,
+    help="Android: override [tool.kivy.android.signing].key_alias.",
+)
+def package(
+    cli_platform: str | None,
+    fmt: str | None,
+    arch: str | None,
+    team_id: str | None,
+    signing_identity: str | None,
+    export_method: str,
+    notarize: bool | None,
+    notary_profile: str | None,
+    no_verify_lock: bool,
+    no_cache: bool,
+    abi: str | None,
+    keystore: str | None,
+    key_alias: str | None,
+) -> None:
+    """Build the signed, distributable artifact for the resolved platform."""
+    backend, project_root = resolve_target(cli_platform, verb="package")
+    reject_android_only(
+        backend,
+        {"--abi": abi, "--keystore": keystore, "--key-alias": key_alias},
+    )
+    fmt = _resolve_format(backend, fmt)
+
+    backend.package(
+        project_root,
+        fmt=fmt,
+        arch=arch,
+        team_id=team_id,
+        signing_identity=signing_identity,
+        export_method=export_method,
+        notarize=notarize,
+        notary_profile=notary_profile,
+        no_verify_lock=no_verify_lock,
+        no_cache=no_cache,
+        abi=abi,
+        keystore=keystore,
+        key_alias=key_alias,
+    )
+
+
+def _resolve_format(backend, fmt: str | None) -> str:
+    """Validate/resolve the ``-f`` format against the backend's advertised set."""
+    if fmt is None:
+        default = backend.default_package_format
+        if default is None:
+            raise ToolchainError(
+                f"{backend.name!r} does not define a package format yet."
+            )
+        return default
+    if fmt not in backend.package_formats:
+        allowed = ", ".join(backend.package_formats) or "none"
+        raise ToolchainError(
+            f"unknown package format {fmt!r} for {backend.name!r}; allowed: {allowed}."
+        )
+    return fmt

kivyforge/cli/run.py

@@ -0,0 +1,162 @@
+"""``kivyforge run`` — build, install, and launch on a simulator/device (spec 05)."""
+
+from __future__ import annotations
+
+import click
+from click.core import ParameterSource
+
+from ..platforms.ios.cli import ios_list_devices
+from ._common import ToolchainError
+from ._platform import platform_option, reject_android_only, resolve_target
+
+
+@click.command()
+@platform_option
+@click.option(
+    "--simulator",
+    "target",
+    flag_value="simulator",
+    default=True,
+    help="Target the iOS simulator (default).",
+)
+@click.option(
+    "--device",
+    "target",
+    flag_value="device",
+    help="Target a connected device (Android: a physical one, never an AVD).",
+)
+@click.option(
+    "--arch",
+    # x86_64 stays: it is the Linux arch and an Android ABI, not a macOS one.
+    type=click.Choice(["arm64", "x86_64", "arm64_v8a"]),
+    default=None,
+    help="macOS: a subset of locked archs; Android: restrict to one ABI.",
+)
+@click.option(
+    "--destination", default=None, help="Specific simulator/device by name or UDID."
+)
+@click.option(
+    "--list-devices",
+    is_flag=True,
+    help="Print available simulators and devices, then exit.",
+)
+@click.option(
+    "--no-build",
+    is_flag=True,
+    help="Skip the implicit build; install + launch the existing app.",
+)
+# --- Android-only ---
+@click.option(
+    "--emulator", is_flag=True, help="Android: boot/target an emulator (AVD)."
+)
+@click.option("--avd", default=None, help="Android: which AVD to boot (--emulator).")
+@click.option(
+    "--serial", default=None, help="Android: which adb device when several attach."
+)
+@click.option(
+    "--smoke",
+    is_flag=True,
+    help="Android: run the generated contract smoke test instead of launching.",
+)
+@click.option(
+    "--release",
+    is_flag=True,
+    help="Android (with --smoke): target the release variant.",
+)
+@click.option(
+    "--abi",
+    type=click.Choice(["arm64_v8a", "x86_64"]),
+    default=None,
+    help="Android: restrict the implicit build to one ABI.",
+)
+def run(
+    cli_platform: str | None,
+    target: str,
+    arch: str | None,
+    destination: str | None,
+    list_devices: bool,
+    no_build: bool,
+    emulator: bool,
+    avd: str | None,
+    serial: str | None,
+    smoke: bool,
+    release: bool,
+    abi: str | None,
+) -> None:
+    """Build (unless --no-build), install, and launch the app."""
+    backend, project_root = resolve_target(cli_platform, verb="run")
+
+    reject_android_only(
+        backend,
+        {
+            "--emulator": emulator,
+            "--avd": avd,
+            "--serial": serial,
+            "--smoke": smoke,
+            "--release": release,
+            "--abi": abi,
+        },
+    )
+    abi = abi or arch
+
+    if backend.name == "android":
+        from ..platforms.android.cli import android_run, android_smoke
+
+        # --simulator is the default flag value, so only an *explicit* one is a
+        # mistake worth reporting; the source is how click tells the two apart.
+        source = click.get_current_context().get_parameter_source("target")
+        explicit = target if source is ParameterSource.COMMANDLINE else None
+        if explicit == "simulator":
+            raise ToolchainError(
+                "--simulator is iOS-only; Android's equivalent is --emulator."
+            )
+        if explicit == "device" and emulator:
+            raise ToolchainError(
+                "--device and --emulator select opposite targets; pass one, or "
+                "neither to auto-select (a single attached device, else an AVD)."
+            )
+        if explicit == "device" and avd is not None:
+            raise ToolchainError(
+                "--avd names an emulator to boot, which --device rules out; pass one."
+            )
+        require_physical = explicit == "device"
+
+        if list_devices:
+            from ..platforms.android import adb as adb_mod
+
+            click.echo("Devices: " + (", ".join(adb_mod.connected_devices()) or "none"))
+            click.echo("AVDs: " + (", ".join(adb_mod.available_avds()) or "none"))
+            return
+        if smoke:
+            android_smoke(
+                project_root,
+                release=release,
+                abi=abi,
+                serial=serial,
+                avd=avd,
+                prefer_emulator=emulator or avd is not None,
+                require_physical=require_physical,
+            )
+        else:
+            android_run(
+                project_root,
+                no_build=no_build,
+                abi=abi,
+                serial=serial or destination,
+                avd=avd,
+                prefer_emulator=emulator or avd is not None,
+                require_physical=require_physical,
+            )
+        return
+
+    if list_devices:
+        ios_list_devices()
+        return
+
+    backend.run(
+        project_root,
+        target=target,
+        arch=arch,
+        destination=destination,
+        no_build=no_build,
+    )

kivyforge/cli/status.py

@@ -0,0 +1,20 @@
+"""``kivyforge status`` — read-only project state snapshot (spec 05).
+
+Platform-aware: resolves the target (``-p`` / ``KIVYFORGE_PLATFORM`` / host) and
+dispatches to that backend's ``status`` over its ``pyproject.toml`` +
+``pylock.<platform>.toml``.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ._platform import platform_option, resolve_target
+
+
+@click.command()
+@platform_option
+def status(cli_platform: str | None) -> None:
+    """Show app identity, Python version, lock sync, and build state."""
+    backend, project_root = resolve_target(cli_platform, verb="status")
+    backend.status(project_root)