inline-core 1.2.0__tar.gz → 1.2.1__tar.gz

{inline_core-1.2.0 → inline_core-1.2.1}/CLAUDE.md

@@ -6,9 +6,14 @@ models across macOS, Windows, and Linux - from CPU-only boxes and low-VRAM lapto
 machines that split a single image's sampling across GPUs (via xDiT). **It is the render backend that
 replaces ComfyUI for Inline.**
 
-> The UI client lives in the separate **Inline Studio / Storyline** repo (`inline-studio`, an Electron
-> app). It drives this engine over the `/v1` HTTP + websocket API. Inline Core is headless and knows
-> nothing about the UI.
+> The UI client lives in the separate **Inline Studio** repo
+> ([`inlineresearch/Inline-Studio`](https://github.com/inlineresearch/Inline-Studio)), which vendors
+> this engine under `core/` via `git subtree`. It drives the engine over the `/v1` HTTP + websocket
+> API; Inline Core is headless and knows nothing about the UI.
+
+> **GitHub org: `inlineresearch`** - never `inline-studio/` or any other org in a URL, manifest, or
+> doc. Sibling repos: `Inline-Studio` (UI + this engine), `Inline-Registry` (the published extension
+> index served to the Available tab), `Inline-Studio-Extension-Guide` (the reference extension).
 
 > Read this file before changing code. It defines the architecture and the non-negotiable rules.
 > `README.md` is the user/product-facing version of the same story; this is the engineering contract.
@@ -170,6 +175,12 @@ real codec that moves tensors lives with the model runner.
 
 - **Typed, strict.** `pyright` in strict mode (`[tool.pyright]`, `typeCheckingMode = "strict"`), all of
   `src` + `tests`. No silent `Any` leaks across component/graph boundaries.
+- **Comments are short.** One or two lines, and only for the **why** a reader can't infer from the
+  code - a non-obvious constraint, a rejected alternative, an ordering that matters. Module
+  docstrings: 1-3 sentences. Function docstrings: one line, or none when the signature says it.
+  Never narrate what the code does, never write an essay in a docstring, never leave a comment that
+  restates the line below it. If the reasoning genuinely needs paragraphs, it belongs in a doc, not
+  in the source.
 - **Lint.** `ruff` with `select = ["E", "F", "I", "UP", "B"]`, line length 100, target `py311`.
 - **Typed graph, validated before run.** Never execute an unvalidated graph. Edge type-checking
   (`graph/validate.py` + `port_satisfies`) rejects bad wiring at submit. New port kinds go in

{inline_core-1.2.0 → inline_core-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: inline-core
-Version: 1.2.0
+Version: 1.2.1
 Summary: The generation engine behind Inline Studio.
 Requires-Python: >=3.11
 Requires-Dist: numpy>=1.26

{inline_core-1.2.0 → inline_core-1.2.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # PyPI name; the import package is `inline_core` (src/inline_core).
 name = "inline-core"
-version = "1.2.0"
+version = "1.2.1"
 description = "The generation engine behind Inline Studio."
 readme = "README.md"
 requires-python = ">=3.11"

{inline_core-1.2.0 → inline_core-1.2.1}/src/inline_core/config.py

@@ -19,6 +19,23 @@ def data_dir() -> Path:
     return Path(env).expanduser() if env else Path(".inline")
 
 
+def extensions_dir() -> Path:
+    """Community extensions root. `INLINE_EXTENSIONS_DIR`, else `./extensions` (so a dev checkout
+    keeps it beside `./models` and `./.inline`). Holds `state.json`, the host constraint snapshot,
+    and one directory per installed extension."""
+    env = os.environ.get("INLINE_EXTENSIONS_DIR")
+    return Path(env).expanduser() if env else Path("extensions")
+
+
+def registry_url() -> str:
+    """Where the Available tab fetches its extension index. `INLINE_EXTENSION_REGISTRY`, else the
+    public registry. Point it at a fork or a file:// path to test a registry change."""
+    return os.environ.get(
+        "INLINE_EXTENSION_REGISTRY",
+        "https://raw.githubusercontent.com/inlineresearch/Inline-Registry/main/index.json",
+    )
+
+
 def server_host() -> str:
     """Address the /v1 server binds. `INLINE_HOST`, else loopback (`127.0.0.1`)."""
     return os.environ.get("INLINE_HOST", "127.0.0.1")

inline_core-1.2.1/src/inline_core/extensions/__init__.py

@@ -0,0 +1,10 @@
+"""Community extensions: installable node extensions from a git repo.
+
+A **extension** is one repo, installed at one pinned commit, holding N independently toggleable
+**modules**, each owning node types, optional model requirements, and optional UI.
+
+Authors import only ``inline_core.extensions.api``.
+
+Dependencies get private resolution with install-time conflict detection - not runtime isolation.
+See ``importer`` for why the distinction matters.
+"""

inline_core-1.2.1/src/inline_core/extensions/api.py

@@ -0,0 +1,214 @@
+"""The extension author's public surface. Everything an extension imports lives here.
+
+An extension ships one ``register(reg: ExtensionRegistrar)`` entry point that registers
+``@inline_node``-decorated ``NodeRunner`` classes.
+
+The decorator has no import-time side effect - it only attaches a descriptor. That is what lets the
+same code load into a scratch registry during install validation and the live one on activation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from ..device.policy import DevicePolicy
+from ..graph.descriptor import NodeDescriptor, ParamField, Port
+from ..graph.registry import Registry
+from ..graph.runners import NodeRunner
+from ..graph.schema import PortKind
+from ..media import MediaKind
+from ..models.requirements import RequirementsProvider, RequirementsRegistry
+from ..runtime.store import TakeStore
+
+#: Attribute the decorator attaches to a runner class.
+DESCRIPTOR_ATTR = "__inline_descriptor__"
+
+#: ``inline_node`` takes a keyword argument named ``type`` to mirror ``NodeDescriptor.type``, which
+#: shadows the builtin inside its body. Captured here so the runtime class check still works.
+_type = type
+
+
+class ExtensionError(RuntimeError):
+    """An extension broke the contract. Fails that extension, never the server."""
+
+
+def inline_node(
+    *,
+    type: str,  # noqa: A002 - mirrors NodeDescriptor.type
+    title: str,
+    category: str,
+    inputs: Sequence[Port] = (),
+    outputs: Sequence[Port] = (),
+    params: Sequence[ParamField] = (),
+    output_kind: MediaKind | None = None,
+    icon: str = "",
+    hidden: bool = False,
+) -> Callable[[type[NodeRunner]], type[NodeRunner]]:
+    """Attach a ``NodeDescriptor`` to a ``NodeRunner`` subclass. ``source`` is stamped by the
+    registrar, not settable here, so provenance can't be spoofed."""
+
+    def decorate(cls: type[NodeRunner]) -> type[NodeRunner]:
+        # Checked at runtime because the annotation is a promise an author can break.
+        if not (isinstance(cls, _type) and issubclass(cls, NodeRunner)):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise ExtensionError(f"@inline_node requires a NodeRunner subclass, got {cls!r}")
+        setattr(
+            cls,
+            DESCRIPTOR_ATTR,
+            NodeDescriptor(
+                type=type,
+                title=title,
+                category=category,
+                inputs=tuple(inputs),
+                outputs=tuple(outputs),
+                params=tuple(params),
+                output_kind=output_kind,
+                icon=icon,
+                hidden=hidden,
+            ),
+        )
+        return cls
+
+    return decorate
+
+
+def descriptor_of(cls: type[NodeRunner]) -> NodeDescriptor | None:
+    descriptor = getattr(cls, DESCRIPTOR_ATTR, None)
+    return descriptor if isinstance(descriptor, NodeDescriptor) else None
+
+
+class ExtensionRegistrar:
+    """Handed to an extension's ``register()``. The entire v1 capability surface.
+
+    Namespacing is enforced here, not by convention: channels carry the ``ext:<id>:`` prefix, node
+    types must be manifest-declared, and ``source`` is stamped."""
+
+    def __init__(
+        self,
+        registry: Registry,
+        extension_id: str,
+        *,
+        store: TakeStore,
+        policy: DevicePolicy,
+        requirements: RequirementsRegistry,
+        data_root: Path,
+        declared_nodes: Sequence[str] = (),
+        enabled_nodes: Sequence[str] | None = None,
+        rpc: Any = None,
+        events: Any = None,
+    ) -> None:
+        self._registry = registry
+        self._extension_id = extension_id
+        self._store = store
+        self._policy = policy
+        self._requirements = requirements
+        self._data_root = data_root
+        self._declared = frozenset(declared_nodes)
+        #: None means "register everything declared" (install-time validation).
+        self._enabled = frozenset(enabled_nodes) if enabled_nodes is not None else None
+        self._rpc = rpc
+        self._events = events
+        #: What actually landed in the registry, so disabling can be undone precisely.
+        self.registered_nodes: list[str] = []
+        self.registered_channels: list[str] = []
+        #: Declared and offered by the author but switched off by the user.
+        self.skipped_nodes: list[str] = []
+
+    # --- nodes -----------------------------------------------------------------------------------
+
+    def node(self, cls: type[NodeRunner], runner: NodeRunner | None = None) -> None:
+        """Register one ``@inline_node``-decorated runner class.
+
+        A node the user has switched off is validated and then skipped, so toggling it back on is
+        just another ``register()`` call - never a restart.
+        """
+        descriptor = descriptor_of(cls)
+        if descriptor is None:
+            raise ExtensionError(f"{cls.__name__} is missing the @inline_node decorator")
+        if self._declared and descriptor.type not in self._declared:
+            raise ExtensionError(
+                f"node type {descriptor.type!r} is not declared in the manifest's nodes[]"
+            )
+        _check_ports(descriptor)
+        if self._enabled is not None and descriptor.type not in self._enabled:
+            self.skipped_nodes.append(descriptor.type)
+            return
+        existing = self._registry.has(descriptor.type)
+        if existing and not self._registry.get(descriptor.type).source.startswith("ext:"):
+            raise ExtensionError(
+                f"node type {descriptor.type!r} is already provided by Core and cannot be replaced"
+            )
+        stamped = replace(descriptor, source=f"ext:{self._extension_id}")
+        self._registry.register(stamped, runner if runner is not None else cls())
+        self.registered_nodes.append(descriptor.type)
+
+    def nodes(self, *classes: type[NodeRunner]) -> None:
+        for cls in classes:
+            self.node(cls)
+
+    # --- model requirements -----------------------------------------------------------------------
+
+    def models(self, node_type: str, provider: RequirementsProvider) -> None:
+        """Declare what a node needs on disk, so it flows through the existing download popup."""
+        self._requirements.register(node_type, provider)
+
+    # --- backend channels ------------------------------------------------------------------------
+
+    def rpc_channel(self, method: str, fn: Callable[..., Any]) -> None:
+        """Register ``ext:<id>:<method>``. The prefix is forced, so an author cannot shadow a
+        core channel like ``project:open``."""
+        if self._rpc is None:
+            return
+        import inspect
+
+        channel = self.channel(method)
+
+        async def handler(args: list[Any]) -> Any:
+            result = fn(*args)
+            if inspect.isawaitable(result):
+                result = await result
+            return result
+
+        self._rpc.register(channel, handler)
+        self.registered_channels.append(channel)
+
+    def emit(self, event: str, payload: Any) -> None:
+        """Broadcast ``ext:<extension>:<event>`` to connected clients."""
+        if self._events is not None:
+            self._events.broadcast(self.channel(event), payload)
+
+    def channel(self, name: str) -> str:
+        if not name or ":" in name:
+            raise ExtensionError(f"channel name {name!r} must be a bare method name")
+        return f"ext:{self._extension_id}:{name}"
+
+    # --- engine handles --------------------------------------------------------------------------
+
+    @property
+    def takes(self) -> TakeStore:
+        return self._store
+
+    @property
+    def device(self) -> DevicePolicy:
+        """Placement policy. Never pick a device yourself - ask ``device.placement(role)``."""
+        return self._policy
+
+    @property
+    def data_dir(self) -> Path:
+        """This extension's private scratch dir. Writing elsewhere is a CRITICAL scanner finding."""
+        path = self._data_root / self._extension_id
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+
+def _check_ports(descriptor: NodeDescriptor) -> None:
+    """Reject custom port kinds: ``port_satisfies`` must stay total, or graph validation could no
+    longer decide edge legality without running extension code."""
+    for port in (*descriptor.inputs, *descriptor.outputs):
+        if not isinstance(port.kind, PortKind):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise ExtensionError(
+                f"port {port.id!r} on {descriptor.type!r} uses an unsupported kind "
+                f"{port.kind!r}; extensions must use the built-in PortKind values"
+            )

inline_core-1.2.1/src/inline_core/extensions/constraints.py

@@ -0,0 +1,179 @@
+"""Pins the host's packages so an extension can never replace them.
+
+An extension may depend on torch/diffusers/transformers but never install its own - two copies in
+one process is a corrupted CUDA context, not a version skew.
+
+The constraint file pins every installed distribution. A requirement needing a different version
+fails to resolve, and that failure *is* the host-override signal.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import write_atomic
+
+#: Packages an extension may never provide, even at the host's exact version. Anything here is
+#: pruned from an extension's private site/ after install, so the finder cannot route it.
+HOST_PROTECTED: frozenset[str] = frozenset(
+    {
+        "torch",
+        "torchvision",
+        "torchaudio",
+        "torchao",
+        "diffusers",
+        "transformers",
+        "accelerate",
+        "safetensors",
+        "tokenizers",
+        "huggingface-hub",
+        "numpy",
+        "scipy",
+        "fastapi",
+        "uvicorn",
+        "starlette",
+        "pydantic",
+        "pydantic-core",
+        "psutil",
+        "xfuser",
+        "nvidia-ml-py",
+        "inline-core",
+    }
+)
+
+_NAME_RE = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)")
+
+
+def canonical(name: str) -> str:
+    """PEP 503 normalization, so ``Huggingface_Hub`` and ``huggingface-hub`` compare equal."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+@dataclass(frozen=True)
+class Conflict:
+    """One dependency an extension wants that the host already owns at another version."""
+
+    name: str
+    host_version: str
+    wanted: str
+
+    @property
+    def protected(self) -> bool:
+        return canonical(self.name) in HOST_PROTECTED
+
+    def message(self) -> str:
+        if self.protected:
+            return (
+                f"{self.name} is part of the shared Inline runtime and cannot be replaced "
+                f"(installed: {self.host_version}, extension wants: {self.wanted})"
+            )
+        return (
+            f"{self.name} {self.wanted} conflicts with the installed {self.name} "
+            f"{self.host_version}"
+        )
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "hostVersion": self.host_version,
+            "wanted": self.wanted,
+            "protected": self.protected,
+            "message": self.message(),
+        }
+
+
+def host_distributions() -> dict[str, str]:
+    """Canonical name -> version for every distribution in the running interpreter."""
+    found: dict[str, str] = {}
+    for dist in importlib.metadata.distributions():
+        name = dist.metadata["Name"] if dist.metadata else None
+        if not name:
+            continue  # a malformed dist-info in site-packages must not break installs
+        version = dist.version
+        if version:
+            found[canonical(name)] = version
+    return found
+
+
+def fingerprint(host: dict[str, str] | None = None) -> str:
+    """Digest of the host's package set, so the constraint file is regenerated after an upgrade."""
+    dists = host if host is not None else host_distributions()
+    payload = ";".join(f"{name}=={version}" for name, version in sorted(dists.items()))
+    return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+
+def render(host: dict[str, str] | None = None) -> str:
+    dists = host if host is not None else host_distributions()
+    lines = [
+        "# Generated by Inline Core - do not edit.",
+        "# Every package installed in the host interpreter, pinned. An extension that needs a",
+        "# different version of any of these fails to resolve rather than silently replacing it.",
+        f"# host-fingerprint: {fingerprint(dists)}",
+    ]
+    lines.extend(f"{name}=={version}" for name, version in sorted(dists.items()))
+    return "\n".join(lines) + "\n"
+
+
+def write_constraints(path: Path, host: dict[str, str] | None = None) -> Path:
+    """Write the constraint file, refreshing it only when the host's packages changed."""
+    dists = host if host is not None else host_distributions()
+    wanted = fingerprint(dists)
+    try:
+        if f"# host-fingerprint: {wanted}" in path.read_text(encoding="utf-8"):
+            return path
+    except OSError:
+        pass
+    write_atomic(path, render(dists))
+    return path
+
+
+def requirement_name(requirement: str) -> str:
+    """The distribution name from a PEP 508 requirement string, canonicalized."""
+    head = requirement.split(";", 1)[0].split("@", 1)[0].strip()
+    match = _NAME_RE.match(head)
+    return canonical(match.group(1)) if match else ""
+
+
+def protected_requirements(requirements: tuple[str, ...]) -> list[str]:
+    """Requirements naming a host-protected package. Runs in the security scan, before any
+    resolution, so listing ``torch`` is blocked outright rather than diagnosed later."""
+    return [req for req in requirements if requirement_name(req) in HOST_PROTECTED]
+
+
+def parse_lock(lock_text: str) -> dict[str, str]:
+    """Canonical name -> version from a fully pinned ``uv pip compile`` lockfile."""
+    pinned: dict[str, str] = {}
+    for raw in lock_text.splitlines():
+        line = raw.split("#", 1)[0].strip()
+        if not line or line.startswith("-"):
+            continue
+        name, sep, version = line.partition("==")
+        if not sep:
+            continue
+        cleaned = version.split(";", 1)[0].split("--", 1)[0].strip()
+        if cleaned:
+            pinned[canonical(name.strip())] = cleaned
+    return pinned
+
+
+def conflicts(lock_text: str, host: dict[str, str] | None = None) -> list[Conflict]:
+    """Pinned packages in an unconstrained lock that disagree with the host. Run only after a
+    constrained resolve failed, to name the culprit instead of dumping a resolver trace."""
+    installed = host if host is not None else host_distributions()
+    found: list[Conflict] = []
+    for name, version in sorted(parse_lock(lock_text).items()):
+        current = installed.get(name)
+        if current is not None and current != version:
+            found.append(Conflict(name=name, host_version=current, wanted=f"=={version}"))
+    return found
+
+
+def prunable(site_dists: dict[str, str], host: dict[str, str] | None = None) -> list[str]:
+    """Private-site distributions that duplicate a host package. Constraints already pinned them to
+    the host version, so removing them guarantees the finder can't route e.g. numpy privately."""
+    installed = host if host is not None else host_distributions()
+    return sorted(name for name in site_dists if name in installed or name in HOST_PROTECTED)

inline_core-1.2.1/src/inline_core/extensions/fetch.py

@@ -0,0 +1,183 @@
+"""Fetching an extension repo at a pinned commit.
+
+A bare mirror under ``.cache/git`` is kept so re-fetching a tag is cheap. The working copy is
+extracted with ``git archive``, which produces no ``.git`` directory and no hooks - nothing in a
+fetched repo can execute before the scanner has seen it.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import subprocess
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .tools import FETCH_TIMEOUT, GIT
+
+#: https/ssh for real repos, file:// for the extension-author dev loop (install your own checkout).
+#: A bare path is still rejected, so nothing can be read as a git option.
+_URL_RE = re.compile(r"^(https://|git@|file:///)[A-Za-z0-9]")
+_REF_RE = re.compile(r"^[A-Za-z0-9._/-]{1,128}$")
+
+
+class FetchError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Fetched:
+    source: Path
+    sha: str
+    ref: str
+
+
+def fetch(url: str, ref: str, *, mirror: Path, dest: Path) -> Fetched:
+    """Clone/refresh ``url`` into ``mirror`` and extract ``ref`` into ``dest``."""
+    GIT.require()
+    _validate(url, ref)
+    _sync_mirror(url, mirror)
+    sha = _resolve(mirror, ref)
+    _extract(mirror, sha, dest)
+    return Fetched(source=dest, sha=sha, ref=ref)
+
+
+def remote_sha(url: str, ref: str) -> str | None:
+    """The commit ``ref`` currently points at upstream, without cloning. None when unreachable -
+    an update check must never fail the dialog."""
+    try:
+        _validate(url, ref)
+        done = _git("ls-remote", url, ref, check=False)
+    except (FetchError, OSError, subprocess.SubprocessError):
+        return None
+    if done.returncode != 0:
+        return None
+    line = done.stdout.strip().split("\n")[0]
+    sha = line.split()[0] if line else ""
+    return sha or None
+
+
+def _validate(url: str, ref: str) -> None:
+    if not _URL_RE.match(url):
+        raise FetchError(f"{url!r} is not an https or ssh git URL")
+    if not _REF_RE.match(ref):
+        raise FetchError(f"{ref!r} is not a valid tag, branch, or commit")
+
+
+def _sync_mirror(url: str, mirror: Path) -> None:
+    if (mirror / "HEAD").is_file():
+        # Re-point at the URL in case a registry entry moved the repo.
+        _git("remote", "set-url", "origin", url, cwd=mirror)
+        _git("fetch", "--prune", "--tags", "origin", "+refs/heads/*:refs/heads/*", cwd=mirror)
+        return
+    mirror.parent.mkdir(parents=True, exist_ok=True)
+    _git("clone", "--bare", "--quiet", url, str(mirror))
+
+
+def _resolve(mirror: Path, ref: str) -> str:
+    """The full commit sha for ``ref``. Pinning by sha is what makes a version reproducible even
+    if the tag is later moved."""
+    for candidate in (f"refs/tags/{ref}", f"refs/heads/{ref}", ref):
+        args = ("rev-parse", "--verify", "--quiet", f"{candidate}^{{commit}}")
+        done = _git(*args, cwd=mirror, check=False)
+        sha = done.stdout.strip()
+        if done.returncode == 0 and sha:
+            return sha
+    raise FetchError(f"{ref!r} was not found in the repository")
+
+
+def _extract(mirror: Path, sha: str, dest: Path) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    done = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        [GIT.require(), "archive", "--format=tar", sha],
+        cwd=mirror,
+        capture_output=True,
+        timeout=FETCH_TIMEOUT,
+        check=False,
+    )
+    if done.returncode != 0:
+        raise FetchError(f"could not read {sha[:7]} from the repository")
+    with tarfile.open(fileobj=io.BytesIO(done.stdout), mode="r|") as archive:
+        for member in archive:
+            if not _safe_member(member):
+                raise FetchError(f"the repository contains an unsafe path: {member.name!r}")
+            archive.extract(member, dest)
+
+
+def _safe_member(member: tarfile.TarInfo) -> bool:
+    """Belt and braces over git's own tree rules: no absolute paths, no traversal, no links."""
+    if member.issym() or member.islnk() or member.isdev():
+        return False
+    path = Path(member.name)
+    return not path.is_absolute() and ".." not in path.parts
+
+
+def _git(
+    *args: str, cwd: Path | None = None, check: bool = True
+) -> subprocess.CompletedProcess[str]:
+    done = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        [GIT.require(), *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        timeout=FETCH_TIMEOUT,
+        check=False,
+    )
+    if check and done.returncode != 0:
+        raise FetchError(_tail(done.stderr) or "git failed")
+    return done
+
+
+def _tail(text: str, lines: int = 4) -> str:
+    kept = [line for line in text.strip().splitlines() if line.strip()][-lines:]
+    return "\n".join(kept)
+
+
+#: `v1.2.3`, `1.2.3`, `v1.2.3-beta.1`. Anything else is not a release tag and is ignored.
+_SEMVER_RE = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$")
+
+
+def version_key(tag: str) -> tuple[int, int, int, int, str] | None:
+    """Sort key for a release tag, or None when the tag isn't one.
+
+    A prerelease sorts below the same release (`1.2.0-rc.1` < `1.2.0`), so floating to the newest
+    tag never picks a release candidate over the finished version.
+    """
+    match = _SEMVER_RE.match(tag.strip())
+    if match is None:
+        return None
+    major, minor, patch, pre = match.groups()
+    return (int(major), int(minor), int(patch), 0 if pre else 1, pre or "")
+
+
+def latest_tag(url: str, *, prereleases: bool = False) -> str | None:
+    """The newest stable release tag upstream, or None when there is none (or it's unreachable).
+
+    This is how a listing floats: the registry names the repository, and the newest tag is resolved
+    here, so an author publishes by tagging rather than by opening a registry PR.
+
+    Prereleases are skipped by default. ``v2.0.0-rc.1`` is semver-newer than ``v1.10.0``, but
+    floating a user onto a release candidate they never asked for is not; install one by naming
+    its tag explicitly.
+    """
+    try:
+        _validate(url, "HEAD")
+        done = _git("ls-remote", "--tags", "--refs", url, check=False)
+    except (FetchError, OSError, subprocess.SubprocessError):
+        return None
+    if done.returncode != 0:
+        return None
+
+    best: tuple[tuple[int, int, int, int, str], str] | None = None
+    for line in done.stdout.splitlines():
+        parts = line.split()
+        if len(parts) != 2:
+            continue
+        tag = parts[1].removeprefix("refs/tags/")
+        key = version_key(tag)
+        if key is None or (not prereleases and key[3] == 0):
+            continue
+        if best is None or key > best[0]:
+            best = (key, tag)
+    return best[1] if best else None