chaindiff 0.1.0__tar.gz

chaindiff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChainDiff contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chaindiff-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: chaindiff
+Version: 0.1.0
+Summary: Decide whether an Ethereum node client upgrade is safe.
+Author: ehsanhajian
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ehsanhajian/chaindiff
+Project-URL: Repository, https://github.com/ehsanhajian/chaindiff
+Project-URL: Issues, https://github.com/ehsanhajian/chaindiff/issues
+Project-URL: Changelog, https://github.com/ehsanhajian/chaindiff/releases
+Keywords: ethereum,blockchain,geth,node,upgrade,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ChainDiff
+
+Decide whether an Ethereum node client upgrade is safe.
+
+ChainDiff compares the client you run with the release you want. It answers **safe** only when every release in between has a sourced review and none of those reviews is breaking. Otherwise the answer is **review required** or **not safe**.
+
+It does not restart a node, edit config, or apply an upgrade.
+
+## Scope
+
+Supported clients:
+
+| Client | Role | Release source |
+| --- | --- | --- |
+| Geth | execution | ethereum/go-ethereum |
+| Nethermind | execution | NethermindEth/nethermind |
+| Erigon | execution | erigontech/erigon |
+| Besu | execution | besu-eth/besu |
+| Reth | execution | paradigmxyz/reth |
+| Lighthouse | consensus | sigp/lighthouse |
+| Prysm | consensus | OffchainLabs/prysm |
+| Teku | consensus | Consensys-Incorporated/teku |
+| Nimbus | consensus | status-im/nimbus-eth2 |
+
+Reth and Nimbus are in the catalog because operators run them. Besu and Teku are read from their current GitHub repositories.
+
+The shipping catalog is Ethereum mainnet. The tool also covers these networks, one task each. A check has to use the clients that network actually runs, and that chain's upgrade, not only the latest tag of an upstream Ethereum client.
+
+- Ethereum mainnet
+- Gnosis
+- BNB Smart Chain
+- Avalanche
+- OP Mainnet
+- Base
+- Arbitrum One
+- Polygon PoS
+- Linea
+- Scroll
+- zkSync Era
+- Starknet
+
+Not in this cut: Lodestar, Grandine, applying the upgrade, node metrics, peer or disk checks, and RPC benchmarks. Configuration scanning and execution/consensus pairing are tracked as later work. They need sourced rules, not guesses.
+
+Calendar-versioned clients (Besu, Teku, Nimbus) do not treat a new year in the version as a breaking change by itself. Semver clients do: an unreviewed major bump is **not safe**.
+
+## Install
+
+```bash
+pip install chaindiff
+```
+
+That package is published from a GitHub release. Until the first release is on PyPI:
+
+```bash
+pip install git+https://github.com/ehsanhajian/chaindiff.git
+```
+
+## Commands
+
+```bash
+chaindiff versions
+chaindiff check --client geth --from <installed>
+chaindiff check --client lighthouse --from <installed> --to v8.2.3
+chaindiff plan --client nethermind --from <installed>
+chaindiff refresh
+```
+
+`check` and `plan` use the local catalog. `refresh` is the only command that talks to GitHub. Set `GH_TOKEN` or `GITHUB_TOKEN` if you hit the unauthenticated rate limit.
+
+### Verdicts
+
+- **ALREADY CURRENT** (exit 0) — you are on the target release.
+- **SAFE** (exit 0) — every release in the range has a sourced review, and none is breaking.
+- **REVIEW REQUIRED** (exit 1) — ChainDiff will not call it safe. Releases are missing a review, something is deprecated, or the catalog is too old to trust "latest".
+- **NOT SAFE** (exit 2) — a reviewed breaking change, or an unreviewed semver major bump.
+- **PRERELEASE** (exit 2) — the target is a prerelease. Don't run it on a mainnet node.
+- **DOWNGRADE** (exit 2) — the target is older than what you run.
+
+A stale catalog (older than 5 days) cannot produce **safe** or **already current** for `latest`. Comparing two explicit versions still works; the report warns that the catalog is old.
+
+The checklist always includes the operator steps that are worth doing on any upgrade: read the notes, back up, keep the old binary, upgrade one client at a time, and roll back if the node fails. Client-specific steps appear only when an advisory says what to change.
+
+## Release catalog
+
+GitHub Actions refreshes the catalog twice a week, Monday and Thursday at 06:15 UTC, and commits it when the run succeeds. Run `chaindiff refresh` yourself any time.
+
+Erigon tags from the old date scheme, such as `v2022.10.01`, are left out. They are not comparable with the 2.x and 3.x line, and treating them as newer versions would hide the current release.
+
+The stored catalog is tags, dates, titles, and URLs. It does not copy release-note bodies. A release title that mentions a security fix is reported as a warning. That warning does not by itself make the upgrade safe or unsafe.
+
+## Advisories
+
+Safe and not-safe both require a review. Put reviews in `src/chaindiff/data/advisories/<client>.json`:
+
+```json
+{
+  "schema_version": 1,
+  "advisories": [
+    {
+      "version": "2.0.0",
+      "severity": "breaking",
+      "summary": "What breaks.",
+      "action": "What the operator changes.",
+      "source": "https://github.com/org/repo/releases/tag/2.0.0"
+    }
+  ]
+}
+```
+
+`severity` is `breaking`, `deprecated`, `note`, or `none`. `none` means the release was reviewed and there is nothing to do. `breaking` and `deprecated` need an `action`. Every advisory needs an `http` or `https` source. Do not mark a release reviewed without reading it.
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests that need a private catalog can set `CHAINDIFF_DATA` to a directory with the same `clients.json`, `releases/`, and `advisories/` layout.

chaindiff-0.1.0/README.md

@@ -0,0 +1,121 @@
+# ChainDiff
+
+Decide whether an Ethereum node client upgrade is safe.
+
+ChainDiff compares the client you run with the release you want. It answers **safe** only when every release in between has a sourced review and none of those reviews is breaking. Otherwise the answer is **review required** or **not safe**.
+
+It does not restart a node, edit config, or apply an upgrade.
+
+## Scope
+
+Supported clients:
+
+| Client | Role | Release source |
+| --- | --- | --- |
+| Geth | execution | ethereum/go-ethereum |
+| Nethermind | execution | NethermindEth/nethermind |
+| Erigon | execution | erigontech/erigon |
+| Besu | execution | besu-eth/besu |
+| Reth | execution | paradigmxyz/reth |
+| Lighthouse | consensus | sigp/lighthouse |
+| Prysm | consensus | OffchainLabs/prysm |
+| Teku | consensus | Consensys-Incorporated/teku |
+| Nimbus | consensus | status-im/nimbus-eth2 |
+
+Reth and Nimbus are in the catalog because operators run them. Besu and Teku are read from their current GitHub repositories.
+
+The shipping catalog is Ethereum mainnet. The tool also covers these networks, one task each. A check has to use the clients that network actually runs, and that chain's upgrade, not only the latest tag of an upstream Ethereum client.
+
+- Ethereum mainnet
+- Gnosis
+- BNB Smart Chain
+- Avalanche
+- OP Mainnet
+- Base
+- Arbitrum One
+- Polygon PoS
+- Linea
+- Scroll
+- zkSync Era
+- Starknet
+
+Not in this cut: Lodestar, Grandine, applying the upgrade, node metrics, peer or disk checks, and RPC benchmarks. Configuration scanning and execution/consensus pairing are tracked as later work. They need sourced rules, not guesses.
+
+Calendar-versioned clients (Besu, Teku, Nimbus) do not treat a new year in the version as a breaking change by itself. Semver clients do: an unreviewed major bump is **not safe**.
+
+## Install
+
+```bash
+pip install chaindiff
+```
+
+That package is published from a GitHub release. Until the first release is on PyPI:
+
+```bash
+pip install git+https://github.com/ehsanhajian/chaindiff.git
+```
+
+## Commands
+
+```bash
+chaindiff versions
+chaindiff check --client geth --from <installed>
+chaindiff check --client lighthouse --from <installed> --to v8.2.3
+chaindiff plan --client nethermind --from <installed>
+chaindiff refresh
+```
+
+`check` and `plan` use the local catalog. `refresh` is the only command that talks to GitHub. Set `GH_TOKEN` or `GITHUB_TOKEN` if you hit the unauthenticated rate limit.
+
+### Verdicts
+
+- **ALREADY CURRENT** (exit 0) — you are on the target release.
+- **SAFE** (exit 0) — every release in the range has a sourced review, and none is breaking.
+- **REVIEW REQUIRED** (exit 1) — ChainDiff will not call it safe. Releases are missing a review, something is deprecated, or the catalog is too old to trust "latest".
+- **NOT SAFE** (exit 2) — a reviewed breaking change, or an unreviewed semver major bump.
+- **PRERELEASE** (exit 2) — the target is a prerelease. Don't run it on a mainnet node.
+- **DOWNGRADE** (exit 2) — the target is older than what you run.
+
+A stale catalog (older than 5 days) cannot produce **safe** or **already current** for `latest`. Comparing two explicit versions still works; the report warns that the catalog is old.
+
+The checklist always includes the operator steps that are worth doing on any upgrade: read the notes, back up, keep the old binary, upgrade one client at a time, and roll back if the node fails. Client-specific steps appear only when an advisory says what to change.
+
+## Release catalog
+
+GitHub Actions refreshes the catalog twice a week, Monday and Thursday at 06:15 UTC, and commits it when the run succeeds. Run `chaindiff refresh` yourself any time.
+
+Erigon tags from the old date scheme, such as `v2022.10.01`, are left out. They are not comparable with the 2.x and 3.x line, and treating them as newer versions would hide the current release.
+
+The stored catalog is tags, dates, titles, and URLs. It does not copy release-note bodies. A release title that mentions a security fix is reported as a warning. That warning does not by itself make the upgrade safe or unsafe.
+
+## Advisories
+
+Safe and not-safe both require a review. Put reviews in `src/chaindiff/data/advisories/<client>.json`:
+
+```json
+{
+  "schema_version": 1,
+  "advisories": [
+    {
+      "version": "2.0.0",
+      "severity": "breaking",
+      "summary": "What breaks.",
+      "action": "What the operator changes.",
+      "source": "https://github.com/org/repo/releases/tag/2.0.0"
+    }
+  ]
+}
+```
+
+`severity` is `breaking`, `deprecated`, `note`, or `none`. `none` means the release was reviewed and there is nothing to do. `breaking` and `deprecated` need an `action`. Every advisory needs an `http` or `https` source. Do not mark a release reviewed without reading it.
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests that need a private catalog can set `CHAINDIFF_DATA` to a directory with the same `clients.json`, `releases/`, and `advisories/` layout.

chaindiff-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "chaindiff"
+version = "0.1.0"
+description = "Decide whether an Ethereum node client upgrade is safe."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["ethereum", "blockchain", "geth", "node", "upgrade", "cli"]
+authors = [{ name = "ehsanhajian" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/ehsanhajian/chaindiff"
+Repository = "https://github.com/ehsanhajian/chaindiff"
+Issues = "https://github.com/ehsanhajian/chaindiff/issues"
+Changelog = "https://github.com/ehsanhajian/chaindiff/releases"
+
+[project.scripts]
+chaindiff = "chaindiff.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+chaindiff = ["data/*.json", "data/releases/*.json", "data/advisories/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

chaindiff-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chaindiff-0.1.0/src/chaindiff/__init__.py

@@ -0,0 +1,3 @@
+"""Decide whether an Ethereum node client upgrade is safe."""
+
+__version__ = "0.1.0"

chaindiff-0.1.0/src/chaindiff/__main__.py

@@ -0,0 +1,4 @@
+from chaindiff.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chaindiff-0.1.0/src/chaindiff/catalog.py

@@ -0,0 +1,179 @@
+"""Load and store the client registry, release catalog, and advisories."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from chaindiff.models import SEVERITIES, Advisory, Client, Release
+from chaindiff.versions import parse_version
+
+SCHEMA_VERSION = 1
+
+
+def data_dir() -> Path:
+    override = os.environ.get("CHAINDIFF_DATA")
+    if override:
+        return Path(override)
+    return Path(__file__).resolve().parent / "data"
+
+
+def format_time(moment: datetime) -> str:
+    return moment.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_time(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        payload = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path} is not valid JSON") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    if payload.get("schema_version") != SCHEMA_VERSION:
+        raise ValueError(f"{path} has an unsupported schema_version")
+    return payload
+
+
+def load_clients() -> list[Client]:
+    path = data_dir() / "clients.json"
+    payload = _read_json(path)
+    clients: list[Client] = []
+    seen: set[str] = set()
+    for raw in payload.get("clients", []):
+        client_id = str(raw.get("id", "")).strip()
+        role = raw.get("role")
+        versioning = raw.get("versioning")
+        github = str(raw.get("github", "")).strip()
+        name = str(raw.get("name", "")).strip()
+        if not client_id or not name or not github:
+            raise ValueError(f"{path} has a client missing id, name, or github")
+        if role not in ("execution", "consensus"):
+            raise ValueError(f"{client_id} has an unknown role")
+        if versioning not in ("semver", "calver"):
+            raise ValueError(f"{client_id} has an unknown versioning scheme")
+        if client_id in seen:
+            raise ValueError(f"{client_id} is listed twice")
+        seen.add(client_id)
+        clients.append(
+            Client(
+                id=client_id,
+                name=name,
+                role=role,
+                github=github,
+                versioning=versioning,
+            )
+        )
+    if not clients:
+        raise ValueError(f"{path} does not list any clients")
+    return clients
+
+
+def client_by_id(clients: list[Client], client_id: str) -> Client | None:
+    key = client_id.strip().lower()
+    for client in clients:
+        if client.id == key:
+            return client
+    return None
+
+
+def releases_path(client_id: str) -> Path:
+    return data_dir() / "releases" / f"{client_id}.json"
+
+
+def load_releases(client_id: str) -> tuple[datetime, list[Release]] | None:
+    path = releases_path(client_id)
+    if not path.exists():
+        return None
+    payload = _read_json(path)
+    fetched_at = parse_time(str(payload["fetched_at"]))
+    releases: list[Release] = []
+    for raw in payload.get("releases", []):
+        tag = str(raw.get("tag", ""))
+        version = parse_version(tag)
+        if version is None:
+            continue
+        releases.append(
+            Release(
+                tag=tag,
+                name=str(raw.get("name") or tag),
+                published_at=str(raw.get("published_at") or ""),
+                prerelease=bool(raw.get("prerelease")),
+                url=str(raw.get("url") or ""),
+                version=version,
+            )
+        )
+    return fetched_at, releases
+
+
+def save_releases(
+    client: Client,
+    releases: list[Release],
+    ignored_tag_count: int,
+    fetched_at: datetime,
+) -> None:
+    path = releases_path(client.id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    ordered = sorted(releases, key=lambda item: (item.version, item.published_at, item.tag), reverse=True)
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "client": client.id,
+        "github": client.github,
+        "fetched_at": format_time(fetched_at),
+        "ignored_tag_count": ignored_tag_count,
+        "releases": [
+            {
+                "tag": item.tag,
+                "name": item.name,
+                "published_at": item.published_at,
+                "prerelease": item.prerelease,
+                "url": item.url,
+            }
+            for item in ordered
+        ],
+    }
+    text = json.dumps(payload, indent=2) + "\n"
+    temporary = path.with_suffix(".json.tmp")
+    temporary.write_text(text)
+    temporary.replace(path)
+
+
+def load_advisories(client_id: str) -> list[Advisory]:
+    path = data_dir() / "advisories" / f"{client_id}.json"
+    if not path.exists():
+        return []
+    payload = _read_json(path)
+    advisories: list[Advisory] = []
+    for index, raw in enumerate(payload.get("advisories", []), start=1):
+        version_text = str(raw.get("version", "")).strip()
+        version = parse_version(version_text)
+        severity = str(raw.get("severity", "")).strip()
+        summary = str(raw.get("summary", "")).strip()
+        action = str(raw.get("action", "")).strip()
+        source = str(raw.get("source", "")).strip()
+        where = f"{path} advisory {index} ({version_text or 'missing version'})"
+        if version is None:
+            raise ValueError(f"{where} has a version ChainDiff cannot parse")
+        if severity not in SEVERITIES:
+            raise ValueError(f"{where} has an unknown severity")
+        if not summary:
+            raise ValueError(f"{where} needs a summary")
+        if severity in ("breaking", "deprecated") and not action:
+            raise ValueError(f"{where} needs an action")
+        if not source.startswith(("https://", "http://")):
+            raise ValueError(f"{where} needs an http(s) source URL")
+        advisories.append(
+            Advisory(
+                version=version,
+                severity=severity,
+                summary=summary,
+                action=action,
+                source=source,
+            )
+        )
+    return advisories

chaindiff-0.1.0/src/chaindiff/cli.py

@@ -0,0 +1,156 @@
+"""Command line for ChainDiff."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+
+from chaindiff import __version__
+from chaindiff.catalog import client_by_id, load_advisories, load_clients, load_releases
+from chaindiff.evaluate import evaluate, latest_stable
+from chaindiff.models import CURRENT, DOWNGRADE, PRERELEASE, REVIEW, SAFE, UNSAFE
+from chaindiff.refresh import refresh_catalog
+from chaindiff.report import check_json, format_check, format_versions, versions_json
+from chaindiff.versions import explain_unparsed, parse_version
+
+_EXIT = {
+    CURRENT: 0,
+    SAFE: 0,
+    REVIEW: 1,
+    UNSAFE: 2,
+    DOWNGRADE: 2,
+    PRERELEASE: 2,
+}
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="chaindiff",
+        description="Decide whether an Ethereum node client upgrade is safe.",
+    )
+    parser.add_argument("--version", action="version", version=f"chaindiff {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    versions = commands.add_parser("versions", help="Show the latest stable release of each client")
+    versions.add_argument("--client", action="append", dest="clients", help="Limit to one client id")
+    versions.add_argument("--json", action="store_true")
+
+    check = commands.add_parser("check", help="Compare an installed version with a target release")
+    plan = commands.add_parser("plan", help="Checklist for the same comparison as check")
+    for command in (check, plan):
+        command.add_argument("--client", required=True, help="Client id, for example geth")
+        command.add_argument("--from", dest="current", required=True, help="Installed version")
+        command.add_argument("--to", dest="target", default="latest", help="Target version, or latest")
+        command.add_argument("--json", action="store_true")
+
+    refresh = commands.add_parser("refresh", help="Download the release catalog from GitHub")
+    refresh.add_argument("--client", action="append", dest="clients", help="Refresh one client id")
+    return parser
+
+
+def _selected_clients(raw_ids: list[str] | None):
+    try:
+        clients = load_clients()
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return None
+    if not raw_ids:
+        return clients
+    selected = []
+    for raw in raw_ids:
+        client = client_by_id(clients, raw)
+        if client is None:
+            known = ", ".join(item.id for item in clients)
+            print(f"Unknown client '{raw}'. Known clients: {known}", file=sys.stderr)
+            return None
+        selected.append(client)
+    return selected
+
+
+def _versions(args: argparse.Namespace) -> int:
+    clients = _selected_clients(args.clients)
+    if clients is None:
+        return 3
+    rows = []
+    missing = False
+    for client in clients:
+        try:
+            loaded = load_releases(client.id)
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 3
+        if loaded is None:
+            missing = True
+            rows.append((client, None, None))
+            continue
+        fetched_at, releases = loaded
+        rows.append((client, fetched_at, releases))
+    now = datetime.now(timezone.utc)
+    if args.json:
+        print(json.dumps(versions_json(rows, now=now), indent=2))
+    else:
+        print(format_versions(rows, now=now), end="")
+    if missing:
+        print("Run `chaindiff refresh` to fill a missing catalog.", file=sys.stderr)
+    return 0
+
+
+def _check(args: argparse.Namespace, *, plan_only: bool) -> int:
+    clients = _selected_clients([args.client])
+    if clients is None:
+        return 3
+    client = clients[0]
+    current = parse_version(args.current)
+    if current is None:
+        print(explain_unparsed(args.current), file=sys.stderr)
+        return 3
+    try:
+        loaded = load_releases(client.id)
+        advisories = load_advisories(client.id)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 3
+    if loaded is None:
+        print(f"No release catalog for {client.id}. Run: chaindiff refresh", file=sys.stderr)
+        return 3
+    fetched_at, releases = loaded
+    target_is_latest = args.target.lower() in ("latest", "stable")
+    if target_is_latest:
+        stable = latest_stable(releases)
+        if stable is None:
+            print(f"{client.id} has no stable release in the catalog.", file=sys.stderr)
+            return 3
+        target = stable.version
+    else:
+        target = parse_version(args.target)
+        if target is None:
+            print(explain_unparsed(args.target), file=sys.stderr)
+            return 3
+    result = evaluate(
+        client=client,
+        releases=releases,
+        advisories=advisories,
+        current=current,
+        target=target,
+        target_is_latest=target_is_latest,
+        fetched_at=fetched_at,
+        now=datetime.now(timezone.utc),
+    )
+    if args.json:
+        print(json.dumps(check_json(result), indent=2))
+    else:
+        print(format_check(result, plan_only=plan_only), end="")
+    return _EXIT[result.verdict]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "versions":
+        return _versions(args)
+    if args.command == "refresh":
+        return refresh_catalog(args.clients)
+    if args.command == "plan":
+        return _check(args, plan_only=True)
+    return _check(args, plan_only=False)