code-coordinator 0.5.46__py3-none-any.whl

coord/health/models.py

@@ -0,0 +1,250 @@
+"""Value types for the fleet-health check engine (#1628).
+
+The whole point of this module is :class:`CheckResult`.  A result carries
+**both** the raw values a probe measured **and** the already-rendered
+headroom string — because the moment a renderer starts re-deriving "is 86%
+used bad?" from ``values["used_pct"]``, the severity logic has forked and
+every new surface (the CLI here, the board projection in H-3, the TUI/web
+renderers in H-4) gets to disagree about what WARN means.
+
+So the contract is:
+
+* A **probe** owns thresholds.  It is the only thing allowed to turn raw
+  numbers into a :class:`Severity`.
+* A **renderer** owns layout.  It may reorder, truncate, colour, or drop
+  results; it may NOT look at ``values`` to decide severity, and it may not
+  reformat ``headroom`` from the raw numbers.
+* ``values`` exists for machine consumers (trend series, alert routing,
+  whoever comes next) — never as a second source of truth for "how bad".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class Severity(str, Enum):
+    """How much headroom is left, worst-first when sorted by :attr:`rank`.
+
+    ``UNKNOWN`` is deliberately not "fine": a probe that could not run tells
+    you nothing, and treating that as OK is how a silently-broken check
+    becomes indistinguishable from a healthy machine.  It ranks *above* OK
+    (so it surfaces) and *below* WARN (so it never pages).
+    """
+
+    OK = "ok"
+    UNKNOWN = "unknown"
+    WARN = "warn"
+    CRIT = "crit"
+
+    @property
+    def rank(self) -> int:
+        return _SEVERITY_RANK[self]
+
+    @property
+    def label(self) -> str:
+        """Fixed-width-ish display token: ``OK`` / ``WARN`` / ``CRIT`` / ``?``."""
+        return "?" if self is Severity.UNKNOWN else self.value.upper()
+
+    def __lt__(self, other: object) -> bool:  # type: ignore[override]
+        if isinstance(other, Severity):
+            return self.rank < other.rank
+        return NotImplemented
+
+
+_SEVERITY_RANK = {
+    Severity.OK: 0,
+    Severity.UNKNOWN: 1,
+    Severity.WARN: 2,
+    Severity.CRIT: 3,
+}
+
+# The three scopes a check can answer for.  ``fleet`` is defined here (so the
+# registry shape is settled — that is this child's whole job) but no seed
+# probe uses it; fleet-scope probes land in H-3.
+SCOPES = ("machine", "checkout", "fleet")
+
+
+def worst(severities: "list[Severity] | tuple[Severity, ...]") -> Severity:
+    """The most severe of *severities* (``OK`` when empty)."""
+    out = Severity.OK
+    for s in severities:
+        if s.rank > out.rank:
+            out = s
+    return out
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """One answer to "how much headroom is left?".
+
+    ``headroom`` is the load-bearing field for every renderer: a short,
+    already-formatted phrase such as ``"86% used (22G free)"`` or
+    ``"128.8h stale, hooks disabled -> will not self-heal"``.  It is produced
+    by the probe, which is also the thing that chose ``severity`` — the two
+    can never disagree because nothing downstream recomputes either.
+    """
+
+    check_id: str
+    scope: str
+    severity: Severity
+    headroom: str
+    # Display prefix, e.g. "disk" / "cargo targets" / "graph".  Defaults to
+    # ``check_id`` when a probe doesn't override it.
+    title: str = ""
+    # What this result is *about* within the check: "/home", "vimcode", ...
+    # ``None`` for whole-machine singletons like the claude-binary check.
+    subject: str | None = None
+    # Rendered threshold reminder, e.g. "crit at 93%".  Optional.
+    threshold: str = ""
+    # Extra rendered context shown under/after the headroom.  Optional.
+    detail: str = ""
+    # Rendered trend, where a probe can get one cheaply ("+4G since 6h ago").
+    trend: str | None = None
+    # Raw measurements, for machine consumers only.  NOT a severity source.
+    values: dict[str, Any] = field(default_factory=dict)
+    # Set iff the probe failed soft; ``severity`` is then UNKNOWN.
+    error: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.title:
+            object.__setattr__(self, "title", self.check_id)
+
+    @property
+    def key(self) -> str:
+        """Stable identity for this row: ``<check_id>`` or ``<check_id>:<subject>``."""
+        return f"{self.check_id}:{self.subject}" if self.subject else self.check_id
+
+    @property
+    def label(self) -> str:
+        """Human row label, e.g. ``"disk /home"`` or ``"claude binary"``."""
+        return f"{self.title} {self.subject}" if self.subject else self.title
+
+    def to_dict(self) -> dict[str, Any]:
+        """The JSON contract H-3/H-4 consume.  Keys here are load-bearing."""
+        return {
+            "key": self.key,
+            "check_id": self.check_id,
+            "scope": self.scope,
+            "subject": self.subject,
+            "title": self.title,
+            "label": self.label,
+            "severity": self.severity.value,
+            "headroom": self.headroom,
+            "threshold": self.threshold,
+            "detail": self.detail,
+            "trend": self.trend,
+            "values": dict(self.values),
+            "error": self.error,
+        }
+
+
+def unknown_result(
+    check_id: str,
+    *,
+    scope: str,
+    error: str,
+    title: str = "",
+    subject: str | None = None,
+) -> CheckResult:
+    """A fail-soft placeholder: the probe blew up, the run carries on.
+
+    Never raise out of a probe — a health engine that dies on its own
+    weakest check reports nothing at all, which is strictly worse than
+    reporting eight checks and one ``?``.
+    """
+    return CheckResult(
+        check_id=check_id,
+        scope=scope,
+        severity=Severity.UNKNOWN,
+        headroom=f"probe failed: {error}",
+        title=title or check_id,
+        subject=subject,
+        error=error,
+    )
+
+
+@dataclass(frozen=True)
+class Checkout:
+    """One local git checkout a ``checkout``-scoped probe can run against."""
+
+    name: str
+    path: Path
+    default_branch: str = "main"
+    # #934's opt-in develop branch.  A repo parked on *this* is not "parked
+    # on a non-default branch" — it's the configured integration branch.
+    develop_branch: str | None = None
+
+    @property
+    def home_branches(self) -> tuple[str, ...]:
+        out = [self.default_branch]
+        if self.develop_branch:
+            out.append(self.develop_branch)
+        return tuple(out)
+
+
+@dataclass
+class FleetSnapshot:
+    """What a ``fleet``-scope probe is allowed to know about the rest of the
+    fleet (#1630).
+
+    Only ever populated by the daemon (``coord.serve_app``'s health-poll
+    tick), from data it already collected polling every agent's ``/health``
+    plus a handful of facts that are genuinely local to the daemon process
+    itself (its own ``coord-serve`` venv).  ``coord health`` run by hand on a
+    single machine has no fleet view — ``HealthContext.fleet`` is ``None``
+    there, and ``fleet``-scope checks are simply not run (see
+    ``registry.run_all``'s ``scopes`` filter).
+
+    #1806: the CLI-venv version and the ``tui/`` binary-vs-source comparison
+    are NOT daemon-host facts, even though an earlier version of this
+    dataclass's ``daemon_host`` blob carried them — both are facts about
+    whichever machine the operator actually put them on, which is often not
+    the daemon host.  They ride ``machines`` instead (each machine's own
+    ``cli_venv``/``tui_binary`` checks, see
+    :mod:`coord.health.checks.deploy_lane_facts`) and are aggregated fleet-
+    wide from there, not read out of ``daemon_host``.
+    """
+
+    # machine_name -> {"state": "online"/"offline"/..., "reason": str,
+    # "latency_ms": float | None, "received_at": float,
+    # "checks": <agent's own H-1 report dict, or None if unreachable/old agent>}
+    machines: dict[str, dict] = field(default_factory=dict)
+    # Free-form daemon-host-local facts a fleet probe needs (its own
+    # coord-serve venv version, /board latency + payload size, phantom-
+    # running assignment ids, per-repo toolchain kinds + CI's pinned
+    # versions, ...).  Kept untyped/free-form (like ``values`` on
+    # CheckResult) so a new fleet fact doesn't require touching this
+    # dataclass.  See the class docstring's #1806 note for what does NOT
+    # belong here.
+    daemon_host: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HealthContext:
+    """Everything a probe is allowed to know about the machine it's on.
+
+    Passing this rather than letting probes reach for ``Path.home()`` /
+    ``coord.config.load()`` directly is what makes them unit-testable
+    without a real filesystem or a real ``coordinator.yml``.
+    """
+
+    thresholds: Any  # coord.config.HealthConfig — untyped to avoid an import cycle
+    home: Path
+    coord_dir: Path
+    now: float
+    checkouts: tuple[Checkout, ...] = ()
+    # The loaded coordinator.yml, when there is one.  Probes must tolerate
+    # ``None`` (``coord health`` on a machine with no config still works).
+    config: Any = None
+    # False on a timer/offline run: probes marked ``cost="network"`` are
+    # skipped entirely rather than left to time out.
+    allow_network: bool = True
+    # Set only by the daemon for a ``scopes=("fleet",)`` run (#1630).  ``None``
+    # everywhere else, including every ``machine``/``checkout`` probe — a
+    # fleet probe that forgets to guard against ``None`` fails soft via the
+    # registry's fail-soft ``run_check`` wrapper, not by crashing the run.
+    fleet: "FleetSnapshot | None" = None

coord/health/pypi.py

@@ -0,0 +1,231 @@
+"""Poll PyPI's **simple index** for a project's released versions (#1628).
+
+Why the simple index and not the JSON API (``/pypi/<name>/json``): they flip
+independently, in both directions.  The JSON API's ``info.version`` can lead
+the index (a release is visible there before the files are servable) *and*
+lag it (cached separately).  Only the simple index is what ``pip`` actually
+resolves against, so "am I behind?" answered from the JSON API can disagree
+with what an operator sees when they run ``pip install -U`` — which turns
+the check into a source of confusion instead of a signal.
+
+The index is HTML (PEP 503) whose anchors are distribution filenames::
+
+    <a href="...">code_coordinator-0.4.91-py3-none-any.whl</a>
+    <a href="...">code_coordinator-0.4.91.tar.gz</a>
+
+Parsing is filename-based and defensive: anything unrecognised is skipped
+rather than raising.  Yanked releases carry ``data-yanked`` on the anchor and
+are excluded — pip won't resolve to them, so counting one as "you're behind"
+would be a lie.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from coord.dist_name import CANDIDATE_NAMES
+
+# PEP 503 normalisation: runs of -_. collapse to a single "-", lowercased.
+_NORMALIZE_RE = re.compile(r"[-_.]+")
+
+# One anchor.  Non-greedy attribute soup, then the filename as anchor text.
+_ANCHOR_RE = re.compile(r"<a\s+([^>]*)>\s*([^<]+?)\s*</a>", re.IGNORECASE | re.DOTALL)
+
+_SDIST_SUFFIXES = (".tar.gz", ".zip", ".tar.bz2")
+
+
+def split_distribution_filename(filename: str) -> tuple[str, str] | None:
+    """``(project_name, version)`` from a distribution filename, or ``None``.
+
+    Wheels (PEP 427) are ``name-version(-build)?-pytag-abi-platform.whl`` with
+    every ``-`` inside the name escaped to ``_``, so splitting on ``-`` is
+    exact — no regex needed and no way to mis-split a hyphenated project.
+    Sdists are ``name-version.tar.gz`` where the name may legitimately keep
+    its hyphens, so those split from the right.
+    """
+    lower = filename.lower()
+    if lower.endswith(".whl"):
+        parts = filename[: -len(".whl")].split("-")
+        # 5 components without a build tag, 6 with one.
+        if len(parts) < 5 or not parts[0] or not parts[1]:
+            return None
+        return parts[0], parts[1]
+    for suffix in _SDIST_SUFFIXES:
+        if lower.endswith(suffix):
+            stem = filename[: -len(suffix)]
+            name, sep, version = stem.rpartition("-")
+            if not sep or not name or not version:
+                return None
+            return name, version
+    return None
+
+
+# Numeric-ish release segments plus an optional pre/post/dev suffix.  This is
+# a deliberate PEP 440 *subset*: enough to order 0.4.9 < 0.4.10 < 0.5.0 and to
+# recognise 1.0.0rc1 as a pre-release, without taking a `packaging` dependency
+# the package doesn't currently declare.
+_VERSION_RE = re.compile(
+    r"^(?P<release>\d+(?:\.\d+)*)"
+    r"(?:(?P<pre_kind>a|b|c|rc|alpha|beta|pre|preview)(?P<pre_num>\d*))?"
+    r"(?:\.?(?:post|rev|r)(?P<post>\d*))?"
+    r"(?:\.?dev(?P<dev>\d*))?$",
+    re.IGNORECASE,
+)
+
+
+def normalize_name(name: str) -> str:
+    """PEP 503 normalised project name (``code_coordinator`` → ``code-coordinator``)."""
+    return _NORMALIZE_RE.sub("-", name).lower()
+
+
+@dataclass(frozen=True, order=True)
+class Version:
+    """A comparable subset of PEP 440.  ``is_prerelease`` drives filtering.
+
+    Only ``sort_key`` participates in comparison: ``1.0`` and ``1.0.0`` are
+    the same release however they were spelled on the index, and the counting
+    of "how many releases am I behind" must not double-count a project that
+    changed its spelling.
+    """
+
+    sort_key: tuple
+    raw: str = field(default="", compare=False)
+    is_prerelease: bool = field(default=False, compare=False)
+
+    def __str__(self) -> str:  # pragma: no cover — trivial
+        return self.raw
+
+
+def parse_version(raw: str) -> Version | None:
+    """Parse *raw* into a comparable :class:`Version`, or ``None`` if it isn't
+    a shape we can order confidently.
+
+    Refusing to guess matters: mis-ordering versions would make the check
+    report "2 behind" on a machine that is current, and an alert that cries
+    wolf gets muted.
+    """
+    m = _VERSION_RE.match(raw.strip())
+    if not m:
+        return None
+    release = tuple(int(part) for part in m.group("release").split("."))
+    # Pad so 1.0 and 1.0.0 compare equal-ish (1.0 sorts just below 1.0.0 only
+    # if we don't pad; padding is what a human means by "same release").
+    release = release + (0,) * (4 - len(release)) if len(release) < 4 else release
+
+    pre_kind = m.group("pre_kind")
+    is_pre = pre_kind is not None or m.group("dev") is not None
+    # Ordering within a release: dev < pre < final < post.
+    if m.group("dev") is not None:
+        stage, stage_num = 0, int(m.group("dev") or 0)
+    elif pre_kind is not None:
+        stage, stage_num = 1, int(m.group("pre_num") or 0)
+    elif m.group("post") is not None:
+        stage, stage_num = 3, int(m.group("post") or 0)
+    else:
+        stage, stage_num = 2, 0
+    return Version(sort_key=(release, stage, stage_num), raw=raw.strip(), is_prerelease=is_pre)
+
+
+def parse_simple_index(html: str, project: str) -> list[Version]:
+    """Every non-yanked, parseable release version in a PEP 503 index page.
+
+    Sorted ascending.  Pre-releases are included here and filtered by the
+    caller — ``pip install -U`` won't pick one by default, so the "how far
+    behind am I" check excludes them, but a caller that wants them can.
+    """
+    wanted = normalize_name(project)
+    out: list[Version] = []
+    seen: set[str] = set()
+    for attrs, filename in _ANCHOR_RE.findall(html or ""):
+        if "data-yanked" in attrs.lower():
+            continue
+        parts = split_distribution_filename(filename)
+        if parts is None:
+            continue
+        name, raw_version = parts
+        if normalize_name(name) != wanted:
+            continue
+        version = parse_version(raw_version)
+        if version is None or version.raw in seen:
+            continue
+        seen.add(version.raw)
+        out.append(version)
+    return sorted(out)
+
+
+def fetch_simple_index(
+    project: str,
+    *,
+    index_url: str = "https://pypi.org/simple",
+    timeout: float = 3.0,
+) -> str:
+    """GET the simple-index page for *project*.  Raises on failure — the
+    caller (a probe) is the thing that has to fail soft."""
+    import httpx  # noqa: PLC0415 — keep import cost off the non-network path
+
+    url = f"{index_url.rstrip('/')}/{normalize_name(project)}/"
+    response = httpx.get(
+        url,
+        timeout=timeout,
+        follow_redirects=True,
+        headers={"Accept": "text/html"},
+    )
+    response.raise_for_status()
+    return response.text
+
+
+def latest_release(
+    project: str,
+    *,
+    index_url: str = "https://pypi.org/simple",
+    timeout: float = 3.0,
+) -> tuple[Version | None, list[Version]]:
+    """``(latest_final_release, all_final_releases_ascending)``."""
+    html = fetch_simple_index(project, index_url=index_url, timeout=timeout)
+    finals = [v for v in parse_simple_index(html, project) if not v.is_prerelease]
+    return (finals[-1] if finals else None), finals
+
+
+def latest_release_any(
+    names: tuple[str, ...] = CANDIDATE_NAMES,
+    *,
+    index_url: str = "https://pypi.org/simple",
+    timeout: float = 3.0,
+) -> tuple[str, Version | None, list[Version]]:
+    """:func:`latest_release`, tried against each of *names* in turn (#2103).
+
+    `claude-coordinator` and `code-coordinator` (#2096) are separate PyPI
+    projects — a caller resolving "what's the latest fleet-wide release"
+    must not hardcode whichever name happened to be current when the code
+    was written, or it silently stops seeing new releases the moment #2096
+    actually ships and starts publishing under the new name.
+
+    Returns ``(project_name_used, latest_final_release,
+    all_final_releases_ascending)`` for the first name in *names* that has
+    any final release on the index — ``code-coordinator`` wins once it has
+    releases, mirroring :func:`coord.dist_name.resolve_installed`'s
+    preference. A name with no releases yet (including a 404 for "this
+    project doesn't exist on the index at all", which is the *expected*
+    state for ``code-coordinator`` until #2096 ships) is treated as "try
+    the next name", not as an error.
+
+    Raises only when every name in *names* fails to even resolve (network
+    down, index unreachable, ...) — re-raising the last error, since at
+    that point there is no meaningful "no releases" to fall back to and the
+    caller needs to know the lookup itself failed.
+    """
+    last_exc: Exception | None = None
+    for project in names:
+        try:
+            latest, finals = latest_release(project, index_url=index_url, timeout=timeout)
+        except Exception as exc:  # noqa: BLE001 — try the next candidate name
+            last_exc = exc
+            continue
+        if finals:
+            return project, latest, finals
+    if last_exc is not None:
+        raise last_exc
+    # Every name resolved (no network/index error) but none has a single
+    # final release — an honest "nothing here", not a failure.
+    return names[-1], None, []