model-mirror-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/.github/workflows/release.yml

@@ -23,6 +23,7 @@ jobs:
       - name: Validate release tag
         run: |
           python scripts/check_release.py "$GITHUB_REF_NAME"
+          python scripts/changelog.py "$GITHUB_REF_NAME" > "$RUNNER_TEMP/release-notes.md"
           if [ "$(git cat-file -t "$GITHUB_REF_NAME")" != "tag" ]; then
             echo "::error::release tag must be annotated"
             exit 1
@@ -45,3 +46,21 @@ jobs:
         run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py
       - name: Publish to PyPI
         run: uv publish
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v7
+      - name: Create GitHub release from changelog
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          python scripts/changelog.py "$GITHUB_REF_NAME" > "$RUNNER_TEMP/release-notes.md"
+          gh release create "$GITHUB_REF_NAME" \
+            --verify-tag \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file "$RUNNER_TEMP/release-notes.md"

model_mirror_cli-0.2.1/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+Notable user-facing changes are recorded here. The release workflow copies the
+matching version section into the corresponding GitHub Release.
+
+## [Unreleased]
+
+## [0.2.1] - 2026-07-28
+
+### Added
+
+- Added `model-mirror version` and `model-mirror version --json` to compare the
+  installed distribution with PyPI and show published release notes when an
+  update is available.
+
+### Changed
+
+- All repo-targeted commands now use the configured `repo_type` when
+  `--repo-type` is omitted. The initial configured default remains `model`.
+- Archive-wide `list` and `status` still include every repo type, while torrent
+  imports continue to use the type embedded in the publication descriptor.
+
+## [0.2.0] - 2026-07-28
+
+### Added
+
+- Initial public PyPI release of the `model-mirror-cli` distribution and
+  `model-mirror` command.
+- Commit-pinned Hugging Face mirroring, verification, repair, explicit upstream
+  updates, offline-only preservation, fast metadata status, and safe resumable
+  removal.
+- Experimental hybrid v1/v2 torrent publication, managed seeding, external
+  client handoff, torrent recovery/import, and reusable hash coverage.

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: model-mirror-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: Mirror and validate Hugging Face archives without leaving payloads in the default cache.
 Project-URL: Repository, https://github.com/xlr8harder/model-mirror
 Project-URL: Issues, https://github.com/xlr8harder/model-mirror/issues
+Project-URL: Changelog, https://github.com/xlr8harder/model-mirror/blob/main/CHANGELOG.md
+Project-URL: Releases, https://github.com/xlr8harder/model-mirror/releases
 Author: xlr8harder
 License-Expression: MIT
 License-File: LICENSE
@@ -19,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Archiving
 Requires-Python: >=3.11
 Requires-Dist: huggingface-hub>=1.0
+Requires-Dist: packaging>=24.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: torrent
 Requires-Dist: libtorrent<2.1,>=2.0.10; extra == 'torrent'
@@ -70,8 +73,17 @@ Update and inspect an installed release with:
 ```bash
 uv tool upgrade model-mirror-cli
 model-mirror --version
+model-mirror version
 ```
 
+`--version` reports the installed version without network access. The `version`
+command explicitly checks the latest PyPI release and, when the installation is
+out of date, prints the published changes and
+`uv tool upgrade model-mirror-cli`. Release notes come from the curated
+[`CHANGELOG.md`](https://github.com/xlr8harder/model-mirror/blob/main/CHANGELOG.md)
+through the corresponding GitHub Releases. The check does not run implicitly
+from `status` or other archive operations.
+
 For development, clone the
 [source repository](https://github.com/xlr8harder/model-mirror), run
 `uv sync --all-extras --dev`, and prefix commands with `uv run`. The rest of
@@ -412,14 +424,17 @@ model-mirror status org/model              # concise last-known repository state
 model-mirror status --verbose org/model    # full recorded metadata
 model-mirror status --check-upstream org/model  # advisory live upstream comparison
 model-mirror status --json                 # stable machine-readable status
+model-mirror version                       # compare installed version with PyPI
 model-mirror remove org/model              # inspect, confirm, and permanently remove one mirror
 model-mirror upgrade org/model             # fill missing torrent hash coverage
 model-mirror torrent publish org/model     # publish and request durable seeding
 model-mirror torrent join FILE_OR_MAGNET   # recover a normal local archive
 ```
 
-Datasets and Spaces are supported with `--repo-type dataset` or
-`--repo-type space`.
+Omitting `--repo-type` uses the configured default, initially `model`, for every
+repo-targeted command. Use `--repo-type dataset` or `--repo-type space` to
+override it. Archive-wide `list` and `status` include all repo types; torrent
+join/import operations read the repo type from the publication descriptor.
 
 ## Key Configuration
 

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/README.md

@@ -44,8 +44,17 @@ Update and inspect an installed release with:
 ```bash
 uv tool upgrade model-mirror-cli
 model-mirror --version
+model-mirror version
 ```
 
+`--version` reports the installed version without network access. The `version`
+command explicitly checks the latest PyPI release and, when the installation is
+out of date, prints the published changes and
+`uv tool upgrade model-mirror-cli`. Release notes come from the curated
+[`CHANGELOG.md`](https://github.com/xlr8harder/model-mirror/blob/main/CHANGELOG.md)
+through the corresponding GitHub Releases. The check does not run implicitly
+from `status` or other archive operations.
+
 For development, clone the
 [source repository](https://github.com/xlr8harder/model-mirror), run
 `uv sync --all-extras --dev`, and prefix commands with `uv run`. The rest of
@@ -386,14 +395,17 @@ model-mirror status org/model              # concise last-known repository state
 model-mirror status --verbose org/model    # full recorded metadata
 model-mirror status --check-upstream org/model  # advisory live upstream comparison
 model-mirror status --json                 # stable machine-readable status
+model-mirror version                       # compare installed version with PyPI
 model-mirror remove org/model              # inspect, confirm, and permanently remove one mirror
 model-mirror upgrade org/model             # fill missing torrent hash coverage
 model-mirror torrent publish org/model     # publish and request durable seeding
 model-mirror torrent join FILE_OR_MAGNET   # recover a normal local archive
 ```
 
-Datasets and Spaces are supported with `--repo-type dataset` or
-`--repo-type space`.
+Omitting `--repo-type` uses the configured default, initially `model`, for every
+repo-targeted command. Use `--repo-type dataset` or `--repo-type space` to
+override it. Archive-wide `list` and `status` include all repo types; torrent
+join/import operations read the repo type from the publication descriptor.
 
 ## Key Configuration
 

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/RELEASING.md

@@ -29,8 +29,12 @@ Select the next version according to the change:
 While the project is pre-1.0, substantial CLI or metadata compatibility changes
 normally warrant a minor release.
 
+Record user-facing work under `[Unreleased]` in `CHANGELOG.md`. Before release,
+move those entries into a dated section matching the new version. The release
+workflow rejects a tag with no matching, non-empty changelog section.
+
 ```bash
-RELEASE_VERSION=0.2.1
+RELEASE_VERSION=0.2.2  # example; choose the appropriate next version
 uv version "$RELEASE_VERSION"
 uv run coverage run -m pytest -q
 uv run coverage report -m
@@ -49,7 +53,8 @@ The tag must exactly equal `v` plus the version in `pyproject.toml`, must be
 annotated, and must point to a commit already on `main`. Release tags are
 protected from rewriting or deletion after publication. The GitHub workflow
 repeats the full test, build, and smoke-test sequence before publishing the
-wheel and source distribution through PyPI trusted publishing.
+wheel and source distribution through PyPI trusted publishing, then creates a
+GitHub Release from the matching `CHANGELOG.md` section.
 
 ## User installation and updates
 

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/model_mirror/cli.py

@@ -52,6 +52,7 @@ from .state import (
     write_verification_state,
 )
 from .verify import RemoteVerifyResult, merge_checksum_result, verify_remote
+from .version_check import RELEASE_URL_TEMPLATE, UPDATE_COMMAND, VersionCheck, check_version
 
 
 TORRENT_EXPERIMENTAL_NOTICE = (
@@ -185,7 +186,11 @@ def build_parser() -> argparse.ArgumentParser:
         epilog="Exit status: 0 when complete or downloaded cleanly; 1 when final verification is not clean.",
     )
     mirror_parser.add_argument("model", metavar="repo", help="Hugging Face repo id, e.g. org/model")
-    mirror_parser.add_argument("--repo-type", choices=["model", "dataset", "space"], help="repo kind to mirror")
+    mirror_parser.add_argument(
+        "--repo-type",
+        choices=["model", "dataset", "space"],
+        help="repo kind to mirror; defaults to configured repo_type",
+    )
     add_revision_options(mirror_parser)
     mirror_parser.add_argument("--force", action="store_true", help="download even if the local copy looks complete")
     mirror_parser.add_argument("--no-verify", action="store_true", help="skip verification after download")
@@ -210,7 +215,9 @@ def build_parser() -> argparse.ArgumentParser:
     )
     remove_parser.add_argument("model", metavar="repo", help="repo id to remove, e.g. org/model")
     remove_parser.add_argument(
-        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to remove"
+        "--repo-type",
+        choices=["model", "dataset", "space"],
+        help="repo kind to remove; defaults to configured repo_type",
     )
     remove_parser.add_argument(
         "-y",
@@ -233,7 +240,9 @@ def build_parser() -> argparse.ArgumentParser:
     verify_parser.add_argument("--cached", action="store_true", help="verify Hub hashes from cached .manifest rows")
     verify_parser.add_argument("--all", action="store_true", help="verify every mirrored model")
     verify_parser.add_argument(
-        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to verify"
+        "--repo-type",
+        choices=["model", "dataset", "space"],
+        help="repo kind to verify; defaults to configured repo_type",
     )
     add_revision_options(verify_parser)
     verify_parser.add_argument("--strict", action="store_true", help="fail on extra local files")
@@ -269,7 +278,9 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     repair_parser.add_argument(
-        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to repair"
+        "--repo-type",
+        choices=["model", "dataset", "space"],
+        help="repo kind to repair; defaults to configured repo_type",
     )
 
     upgrade_parser = add_command_parser(
@@ -286,7 +297,9 @@ def build_parser() -> argparse.ArgumentParser:
     upgrade_parser.add_argument("--all", action="store_true", help="upgrade every mirrored repository of this type")
     upgrade_parser.add_argument("--dry-run", action="store_true", help="report required reads without changing metadata")
     upgrade_parser.add_argument(
-        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to upgrade"
+        "--repo-type",
+        choices=["model", "dataset", "space"],
+        help="repo kind to upgrade; defaults to configured repo_type",
     )
 
     torrent_parser = add_command_parser(
@@ -309,8 +322,7 @@ def build_parser() -> argparse.ArgumentParser:
         command.add_argument(
             "--repo-type",
             choices=["model", "dataset", "space"],
-            default="model",
-            help="repo kind",
+            help="repo kind; defaults to configured repo_type",
         )
         return command
 
@@ -410,7 +422,9 @@ def build_parser() -> argparse.ArgumentParser:
     )
     offline_parser.add_argument("model", metavar="repo", help="repo id to mark offline-only")
     offline_parser.add_argument(
-        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to update"
+        "--repo-type",
+        choices=["model", "dataset", "space"],
+        help="repo kind to update; defaults to configured repo_type",
     )
 
     online_parser = add_command_parser(
@@ -421,7 +435,9 @@ def build_parser() -> argparse.ArgumentParser:
     )
     online_parser.add_argument("model", metavar="repo", help="repo id to mark online")
     online_parser.add_argument(
-        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to update"
+        "--repo-type",
+        choices=["model", "dataset", "space"],
+        help="repo kind to update; defaults to configured repo_type",
     )
 
     list_parser = add_command_parser(
@@ -475,6 +491,17 @@ def build_parser() -> argparse.ArgumentParser:
     )
     clean_cache_parser.add_argument("--force", action="store_true", help="delete cache and temporary files")
 
+    version_parser = add_command_parser(
+        "version",
+        help="compare the installed version with the latest PyPI release",
+        description=(
+            "Query PyPI for the latest model-mirror-cli release and compare it with "
+            "the installed version. Use --version for an offline installed-version check."
+        ),
+        epilog="Exit status: 0 when PyPI was checked successfully; 1 when the check was unavailable.",
+    )
+    version_parser.add_argument("--json", action="store_true", dest="json_output", help="emit structured JSON")
+
     config_parser = add_command_parser(
         "config",
         help="show or change configuration",
@@ -526,8 +553,11 @@ def main(argv: list[str] | None = None, *, hub=None) -> int:
         return 0
     if args.command == "help":
         return handle_help(parser, args.topic)
+    if args.command == "version":
+        return handle_version(json_output=args.json_output)
     config_path = Path(args.config).expanduser() if args.config else None
     config = load_config(config_path)
+    apply_configured_repo_type(args, config)
 
     if should_supervise_mirror(args, config, hub):
         return run_supervised_mirror(raw_argv, args, config)
@@ -583,6 +613,67 @@ def main(argv: list[str] | None = None, *, hub=None) -> int:
     return 2
 
 
+def apply_configured_repo_type(args, config: Config) -> None:
+    if args.command in {"list", "status"}:
+        return
+    if hasattr(args, "repo_type") and args.repo_type is None:
+        args.repo_type = config.repo_type
+
+
+def handle_version(*, json_output: bool) -> int:
+    result = check_version(__version__)
+    update_command = UPDATE_COMMAND if result.status == "out-of-date" else None
+    release_url = (
+        RELEASE_URL_TEMPLATE.format(version=result.latest_version)
+        if result.status == "out-of-date"
+        else None
+    )
+    if json_output:
+        print(
+            json.dumps(
+                {
+                    "schema": "model-mirror-version",
+                    "version": 1,
+                    "installed_version": result.installed_version,
+                    "latest_version": result.latest_version,
+                    "status": result.status,
+                    "update_command": update_command,
+                    "error": result.error,
+                    "release_url": release_url,
+                    "releases": [
+                        {
+                            "version": release.version,
+                            "url": release.url,
+                            "notes": release.notes,
+                        }
+                        for release in result.releases
+                    ],
+                    "release_notes_error": result.release_notes_error,
+                },
+                sort_keys=True,
+            )
+        )
+    else:
+        print(f"installed: {result.installed_version}")
+        print(f"latest: {result.latest_version or 'unavailable'}")
+        print(f"status: {result.status}")
+        if update_command:
+            print(f"update: {update_command}")
+        if result.releases:
+            print("changes:")
+            for release in result.releases:
+                print(f"\n{release.version}: {release.url}")
+                if release.notes:
+                    print(release.notes)
+        elif release_url:
+            print(f"changes: {release_url}")
+        if result.release_notes_error:
+            print(f"changes_error: {result.release_notes_error}")
+        if result.error:
+            print(f"error: {result.error}")
+    return 1 if result.status == "unavailable" else 0
+
+
 def should_supervise_mirror(args, config: Config, hub) -> bool:
     if args.command != "mirror":
         return False

model_mirror_cli-0.2.1/model_mirror/version_check.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from urllib.request import Request, urlopen
+
+from packaging.version import InvalidVersion, Version
+
+
+DISTRIBUTION_NAME = "model-mirror-cli"
+PYPI_JSON_URL = f"https://pypi.org/pypi/{DISTRIBUTION_NAME}/json"
+GITHUB_RELEASES_URL = "https://api.github.com/repos/xlr8harder/model-mirror/releases"
+RELEASE_URL_TEMPLATE = "https://github.com/xlr8harder/model-mirror/releases/tag/v{version}"
+UPDATE_COMMAND = f"uv tool upgrade {DISTRIBUTION_NAME}"
+
+
+class VersionCheckError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseNote:
+    version: str
+    url: str
+    notes: str
+
+
+@dataclass(frozen=True, slots=True)
+class VersionCheck:
+    installed_version: str
+    latest_version: str | None
+    status: str
+    error: str | None = None
+    releases: tuple[ReleaseNote, ...] = ()
+    release_notes_error: str | None = None
+
+
+def fetch_latest_version(*, timeout: float = 5.0) -> str:
+    document = _get_json(
+        PYPI_JSON_URL,
+        source="PyPI",
+        timeout=timeout,
+    )
+    try:
+        latest_version = document["info"]["version"]
+    except (KeyError, TypeError) as exc:
+        raise VersionCheckError("PyPI response did not contain info.version") from exc
+    _parse_version(latest_version, "PyPI")
+    return latest_version
+
+
+def fetch_release_notes(
+    installed_version: str,
+    latest_version: str,
+    *,
+    timeout: float = 5.0,
+) -> tuple[ReleaseNote, ...]:
+    installed = _parse_version(installed_version, "installed")
+    latest = _parse_version(latest_version, "PyPI")
+    releases: list[tuple[Version, ReleaseNote]] = []
+    page = 1
+    while True:
+        document = _get_json(
+            f"{GITHUB_RELEASES_URL}?per_page=100&page={page}",
+            source="GitHub releases",
+            timeout=timeout,
+        )
+        if not isinstance(document, list):
+            raise VersionCheckError("GitHub releases response was not a list")
+        for item in document:
+            if not isinstance(item, dict) or item.get("draft") or item.get("prerelease"):
+                continue
+            tag = item.get("tag_name")
+            if not isinstance(tag, str) or not tag.startswith("v"):
+                continue
+            try:
+                release_version = _parse_version(tag[1:], "GitHub release")
+            except VersionCheckError:
+                continue
+            if not installed < release_version <= latest:
+                continue
+            url = item.get("html_url")
+            if not isinstance(url, str) or not url:
+                url = RELEASE_URL_TEMPLATE.format(version=tag[1:])
+            notes = item.get("body")
+            releases.append(
+                (
+                    release_version,
+                    ReleaseNote(
+                        version=tag[1:],
+                        url=url,
+                        notes=notes.strip() if isinstance(notes, str) else "",
+                    ),
+                )
+            )
+        if len(document) < 100:
+            break
+        page += 1
+    releases.sort(key=lambda entry: entry[0])
+    return tuple(note for _, note in releases)
+
+
+def check_version(
+    installed_version: str,
+    *,
+    latest_version_provider=fetch_latest_version,
+    release_notes_provider=fetch_release_notes,
+) -> VersionCheck:
+    try:
+        installed = _parse_version(installed_version, "installed")
+        latest_version = latest_version_provider()
+        latest = _parse_version(latest_version, "PyPI")
+    except (OSError, ValueError, VersionCheckError) as exc:
+        return VersionCheck(
+            installed_version=installed_version,
+            latest_version=None,
+            status="unavailable",
+            error=str(exc),
+        )
+    if installed < latest:
+        status = "out-of-date"
+    elif installed > latest:
+        status = "ahead"
+    else:
+        status = "current"
+    releases: tuple[ReleaseNote, ...] = ()
+    release_notes_error = None
+    if status == "out-of-date":
+        try:
+            releases = release_notes_provider(installed_version, latest_version)
+        except (OSError, ValueError, VersionCheckError) as exc:
+            release_notes_error = str(exc)
+    return VersionCheck(
+        installed_version=installed_version,
+        latest_version=latest_version,
+        status=status,
+        releases=releases,
+        release_notes_error=release_notes_error,
+    )
+
+
+def _get_json(url: str, *, source: str, timeout: float):
+    request = Request(
+        url,
+        headers={
+            "Accept": "application/json",
+            "User-Agent": f"{DISTRIBUTION_NAME}-version-check",
+        },
+    )
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            return json.load(response)
+    except (OSError, ValueError) as exc:
+        raise VersionCheckError(f"{source} request failed: {exc}") from exc
+
+
+def _parse_version(value: object, source: str) -> Version:
+    if not isinstance(value, str) or not value:
+        raise VersionCheckError(f"{source} version is missing or invalid")
+    try:
+        return Version(value)
+    except InvalidVersion as exc:
+        raise VersionCheckError(f"{source} version is invalid: {value!r}") from exc

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "model-mirror-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "Mirror and validate Hugging Face archives without leaving payloads in the default cache."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -27,6 +27,7 @@ classifiers = [
 ]
 dependencies = [
   "huggingface_hub>=1.0",
+  "packaging>=24.0",
   "PyYAML>=6.0",
 ]
 
@@ -48,6 +49,8 @@ model-mirror = "model_mirror.cli:main"
 [project.urls]
 Repository = "https://github.com/xlr8harder/model-mirror"
 Issues = "https://github.com/xlr8harder/model-mirror/issues"
+Changelog = "https://github.com/xlr8harder/model-mirror/blob/main/CHANGELOG.md"
+Releases = "https://github.com/xlr8harder/model-mirror/releases"
 
 [tool.hatch.build.targets.wheel]
 packages = ["model_mirror"]

model_mirror_cli-0.2.1/scripts/changelog.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import re
+
+
+HEADING = re.compile(r"^## \[([^\]]+)\](?: - .+)?$", re.MULTILINE)
+
+
+def release_notes(document: str, version: str) -> str:
+    selected = version.removeprefix("v")
+    headings = list(HEADING.finditer(document))
+    for index, heading in enumerate(headings):
+        if heading.group(1) != selected:
+            continue
+        end = headings[index + 1].start() if index + 1 < len(headings) else len(document)
+        notes = document[heading.end() : end].strip()
+        if not notes:
+            raise ValueError(f"changelog section {selected!r} is empty")
+        return notes
+    raise ValueError(f"changelog section {selected!r} was not found")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Print release notes from CHANGELOG.md.")
+    parser.add_argument("version", help="package version or release tag, for example 0.2.1 or v0.2.1")
+    parser.add_argument("--changelog", type=Path, default=Path("CHANGELOG.md"))
+    args = parser.parse_args()
+    try:
+        notes = release_notes(args.changelog.read_text(encoding="utf-8"), args.version)
+    except (OSError, ValueError) as exc:
+        parser.error(str(exc))
+    print(notes)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

model_mirror_cli-0.2.1/tests/test_changelog.py

@@ -0,0 +1,39 @@
+import pytest
+
+from scripts.changelog import release_notes
+
+
+def test_release_notes_extracts_exact_version_section():
+    document = """# Changelog
+
+## [Unreleased]
+
+Pending.
+
+## [1.1.0] - 2026-07-28
+
+First line.
+
+Second line.
+
+## [1.0.0] - 2026-07-27
+
+Old.
+"""
+
+    assert release_notes(document, "v1.1.0") == "First line.\n\nSecond line."
+    assert release_notes(document, "1.0.0") == "Old."
+
+
+def test_release_notes_rejects_missing_or_empty_sections():
+    document = """## [Unreleased]
+
+## [1.0.0] - 2026-07-27
+
+Notes.
+"""
+
+    with pytest.raises(ValueError, match="section '1.1.0' was not found"):
+        release_notes(document, "1.1.0")
+    with pytest.raises(ValueError, match="section 'Unreleased' is empty"):
+        release_notes(document, "Unreleased")

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/tests/test_cli.py

@@ -29,6 +29,7 @@ from model_mirror.hub import HubFile, HubSnapshot, write_snapshot_plan
 from model_mirror.lock import ModelLock
 from model_mirror.progress import ProgressEntry, ProgressSnapshot, progress_path
 from model_mirror.state import VerificationState, read_verification_state, write_verification_state
+from model_mirror.version_check import ReleaseNote, VersionCheck
 
 
 @dataclass
@@ -371,7 +372,133 @@ def test_version_uses_package_metadata(capsys):
         main(["--version"])
 
     assert exc.value.code == 0
-    assert capsys.readouterr().out == "model-mirror 0.2.0\n"
+    assert capsys.readouterr().out == f"model-mirror {cli_module.__version__}\n"
+
+
+@pytest.mark.parametrize(
+    "result,expected_rc,expected",
+    [
+        (
+            VersionCheck("1.0.0", "1.0.0", "current"),
+            0,
+            ["installed: 1.0.0", "latest: 1.0.0", "status: current"],
+        ),
+        (
+            VersionCheck("1.0.0", "1.0.1", "out-of-date"),
+            0,
+            [
+                "status: out-of-date",
+                "update: uv tool upgrade model-mirror-cli",
+            ],
+        ),
+        (
+            VersionCheck("1.1.0", "1.0.1", "ahead"),
+            0,
+            ["status: ahead"],
+        ),
+        (
+            VersionCheck("1.0.0", None, "unavailable", "offline"),
+            1,
+            ["latest: unavailable", "status: unavailable", "error: offline"],
+        ),
+    ],
+)
+def test_version_command_reports_pypi_comparison(monkeypatch, capsys, result, expected_rc, expected):
+    monkeypatch.setattr(cli_module, "check_version", lambda installed: result)
+    monkeypatch.setattr(cli_module, "load_config", lambda path: pytest.fail("version must not load archive config"))
+
+    assert main(["version"]) == expected_rc
+
+    output = capsys.readouterr().out
+    assert all(item in output for item in expected)
+    assert ("update:" in output) == (result.status == "out-of-date")
+
+
+def test_version_command_supports_json(monkeypatch, capsys):
+    monkeypatch.setattr(
+        cli_module,
+        "check_version",
+        lambda installed: VersionCheck(
+            "1.0.0",
+            "1.0.2",
+            "out-of-date",
+            releases=(
+                ReleaseNote("1.0.1", "https://example/1.0.1", "first"),
+                ReleaseNote("1.0.2", "https://example/1.0.2", "second"),
+            ),
+        ),
+    )
+
+    assert main(["version", "--json"]) == 0
+
+    assert json.loads(capsys.readouterr().out) == {
+        "schema": "model-mirror-version",
+        "version": 1,
+        "installed_version": "1.0.0",
+        "latest_version": "1.0.2",
+        "status": "out-of-date",
+        "update_command": "uv tool upgrade model-mirror-cli",
+        "error": None,
+        "release_url": "https://github.com/xlr8harder/model-mirror/releases/tag/v1.0.2",
+        "releases": [
+            {"version": "1.0.1", "url": "https://example/1.0.1", "notes": "first"},
+            {"version": "1.0.2", "url": "https://example/1.0.2", "notes": "second"},
+        ],
+        "release_notes_error": None,
+    }
+
+
+def test_version_command_prints_all_pending_release_notes(monkeypatch, capsys):
+    monkeypatch.setattr(
+        cli_module,
+        "check_version",
+        lambda installed: VersionCheck(
+            "1.0.0",
+            "1.0.2",
+            "out-of-date",
+            releases=(
+                ReleaseNote("1.0.1", "https://example/1.0.1", "first"),
+                ReleaseNote("1.0.2", "https://example/1.0.2", ""),
+            ),
+            release_notes_error="one release had no notes",
+        ),
+    )
+
+    assert main(["version"]) == 0
+
+    output = capsys.readouterr().out
+    assert output.index("1.0.1:") < output.index("1.0.2:")
+    assert "first" in output
+    assert "changes_error: one release had no notes" in output
+
+
+def test_repo_commands_use_configured_repo_type_by_default():
+    parser = cli_module.build_parser()
+    config = Config(repo_type="dataset")
+    repo_commands = [
+        ["mirror", "org/data"],
+        ["remove", "org/data"],
+        ["verify", "org/data"],
+        ["repair", "org/data"],
+        ["upgrade", "org/data"],
+        ["torrent", "publish", "org/data"],
+        ["offline", "org/data"],
+        ["online", "org/data"],
+    ]
+
+    for command in repo_commands:
+        args = parser.parse_args(command)
+        assert args.repo_type is None
+        cli_module.apply_configured_repo_type(args, config)
+        assert args.repo_type == "dataset"
+
+    explicit = parser.parse_args(["verify", "--repo-type", "space", "org/app"])
+    cli_module.apply_configured_repo_type(explicit, config)
+    assert explicit.repo_type == "space"
+
+    archive_status = parser.parse_args(["status"])
+    cli_module.apply_configured_repo_type(archive_status, config)
+    assert archive_status.repo_type is None
 
 
 def test_help_command_prints_full_help(capsys):

model_mirror_cli-0.2.1/tests/test_version_check.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from io import BytesIO
+import json
+
+import pytest
+
+import model_mirror.version_check as version_module
+from model_mirror.version_check import (
+    ReleaseNote,
+    VersionCheckError,
+    check_version,
+    fetch_latest_version,
+    fetch_release_notes,
+)
+
+
+def test_fetch_latest_version_uses_pypi_json_api(monkeypatch):
+    captured = {}
+
+    def fake_urlopen(request, timeout):
+        captured["url"] = request.full_url
+        captured["accept"] = request.get_header("Accept")
+        captured["user_agent"] = request.get_header("User-agent")
+        captured["timeout"] = timeout
+        return BytesIO(json.dumps({"info": {"version": "1.2.3"}}).encode())
+
+    monkeypatch.setattr(version_module, "urlopen", fake_urlopen)
+
+    assert fetch_latest_version(timeout=2.5) == "1.2.3"
+    assert captured == {
+        "url": "https://pypi.org/pypi/model-mirror-cli/json",
+        "accept": "application/json",
+        "user_agent": "model-mirror-cli-version-check",
+        "timeout": 2.5,
+    }
+
+
+def test_fetch_latest_version_wraps_request_errors(monkeypatch):
+    def fail_urlopen(request, timeout):
+        raise OSError("offline")
+
+    monkeypatch.setattr(version_module, "urlopen", fail_urlopen)
+
+    with pytest.raises(VersionCheckError, match="PyPI request failed: offline"):
+        fetch_latest_version()
+
+
+@pytest.mark.parametrize(
+    "document,error",
+    [
+        ({}, "did not contain info.version"),
+        (None, "did not contain info.version"),
+        ({"info": {"version": ""}}, "version is missing or invalid"),
+        ({"info": {"version": "not a version"}}, "version is invalid"),
+    ],
+)
+def test_fetch_latest_version_rejects_invalid_responses(monkeypatch, document, error):
+    monkeypatch.setattr(
+        version_module,
+        "urlopen",
+        lambda request, timeout: BytesIO(json.dumps(document).encode()),
+    )
+
+    with pytest.raises(VersionCheckError, match=error):
+        fetch_latest_version()
+
+
+def test_fetch_release_notes_returns_every_published_version_in_range(monkeypatch):
+    document = [
+        {"tag_name": "v1.3.0", "html_url": "https://example/1.3.0", "body": " third "},
+        {"tag_name": "v1.1.0", "html_url": "https://example/1.1.0", "body": "first"},
+        {"tag_name": "v1.2.0", "html_url": "", "body": None},
+        {"tag_name": "v1.0.0", "body": "installed"},
+        {"tag_name": "v2.0.0", "body": "future"},
+        {"tag_name": "v1.2.1", "body": "draft", "draft": True},
+        {"tag_name": "v1.2.2", "body": "prerelease", "prerelease": True},
+        {"tag_name": "invalid", "body": "not a version"},
+        {"tag_name": "v-invalid", "body": "not a version"},
+        "not a release",
+    ]
+    captured = {}
+
+    def fake_urlopen(request, timeout):
+        captured["url"] = request.full_url
+        captured["timeout"] = timeout
+        return BytesIO(json.dumps(document).encode())
+
+    monkeypatch.setattr(version_module, "urlopen", fake_urlopen)
+
+    assert fetch_release_notes("1.0.0", "1.3.0", timeout=3.0) == (
+        ReleaseNote("1.1.0", "https://example/1.1.0", "first"),
+        ReleaseNote(
+            "1.2.0",
+            "https://github.com/xlr8harder/model-mirror/releases/tag/v1.2.0",
+            "",
+        ),
+        ReleaseNote("1.3.0", "https://example/1.3.0", "third"),
+    )
+    assert captured == {
+        "url": "https://api.github.com/repos/xlr8harder/model-mirror/releases?per_page=100&page=1",
+        "timeout": 3.0,
+    }
+
+
+def test_fetch_release_notes_paginates(monkeypatch):
+    pages = [
+        [{"tag_name": "not-a-release"}] * 100,
+        [{"tag_name": "v1.1.0", "html_url": "https://example/1.1.0", "body": "notes"}],
+    ]
+    urls = []
+
+    def fake_urlopen(request, timeout):
+        urls.append(request.full_url)
+        return BytesIO(json.dumps(pages.pop(0)).encode())
+
+    monkeypatch.setattr(version_module, "urlopen", fake_urlopen)
+
+    assert fetch_release_notes("1.0.0", "1.1.0") == (
+        ReleaseNote("1.1.0", "https://example/1.1.0", "notes"),
+    )
+    assert urls == [
+        "https://api.github.com/repos/xlr8harder/model-mirror/releases?per_page=100&page=1",
+        "https://api.github.com/repos/xlr8harder/model-mirror/releases?per_page=100&page=2",
+    ]
+
+
+def test_fetch_release_notes_rejects_non_list_response(monkeypatch):
+    monkeypatch.setattr(
+        version_module,
+        "urlopen",
+        lambda request, timeout: BytesIO(b"{}"),
+    )
+
+    with pytest.raises(VersionCheckError, match="response was not a list"):
+        fetch_release_notes("1.0.0", "1.1.0")
+
+
+@pytest.mark.parametrize(
+    "installed,latest,status",
+    [
+        ("1.0.0", "1.0.0", "current"),
+        ("1.0.0", "1.0.1", "out-of-date"),
+        ("1.1.0", "1.0.1", "ahead"),
+    ],
+)
+def test_check_version_compares_pep_440_versions(installed, latest, status):
+    result = check_version(
+        installed,
+        latest_version_provider=lambda: latest,
+        release_notes_provider=lambda installed, latest: (),
+    )
+
+    assert result.installed_version == installed
+    assert result.latest_version == latest
+    assert result.status == status
+    assert result.error is None
+    assert result.releases == ()
+    assert result.release_notes_error is None
+
+
+@pytest.mark.parametrize(
+    "installed,provider,error",
+    [
+        ("invalid", lambda: "1.0.0", "installed version is invalid"),
+        ("1.0.0", lambda: None, "PyPI version is missing or invalid"),
+        ("1.0.0", lambda: (_ for _ in ()).throw(OSError("offline")), "offline"),
+        ("1.0.0", lambda: (_ for _ in ()).throw(ValueError("bad response")), "bad response"),
+        ("1.0.0", lambda: (_ for _ in ()).throw(VersionCheckError("bad metadata")), "bad metadata"),
+    ],
+)
+def test_check_version_reports_unavailable(installed, provider, error):
+    result = check_version(installed, latest_version_provider=provider)
+
+    assert result.installed_version == installed
+    assert result.latest_version is None
+    assert result.status == "unavailable"
+    assert error in result.error
+
+
+def test_check_version_includes_release_notes_for_every_pending_release():
+    notes = (
+        ReleaseNote("1.1.0", "https://example/1.1.0", "first"),
+        ReleaseNote("1.2.0", "https://example/1.2.0", "second"),
+    )
+
+    result = check_version(
+        "1.0.0",
+        latest_version_provider=lambda: "1.2.0",
+        release_notes_provider=lambda installed, latest: notes,
+    )
+
+    assert result.releases == notes
+    assert result.release_notes_error is None
+
+
+@pytest.mark.parametrize(
+    "error",
+    [
+        OSError("offline"),
+        ValueError("bad response"),
+        VersionCheckError("bad metadata"),
+    ],
+)
+def test_check_version_keeps_update_status_when_release_notes_are_unavailable(error):
+    def fail_notes(installed, latest):
+        raise error
+
+    result = check_version(
+        "1.0.0",
+        latest_version_provider=lambda: "1.1.0",
+        release_notes_provider=fail_notes,
+    )
+
+    assert result.status == "out-of-date"
+    assert result.releases == ()
+    assert result.release_notes_error == str(error)

{model_mirror_cli-0.2.0 → model_mirror_cli-0.2.1}/uv.lock

@@ -321,10 +321,11 @@ wheels = [
 
 [[package]]
 name = "model-mirror-cli"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "huggingface-hub" },
+    { name = "packaging" },
     { name = "pyyaml" },
 ]
 
@@ -344,6 +345,7 @@ dev = [
 requires-dist = [
     { name = "huggingface-hub", specifier = ">=1.0" },
     { name = "libtorrent", marker = "extra == 'torrent'", specifier = ">=2.0.10,<2.1" },
+    { name = "packaging", specifier = ">=24.0" },
     { name = "pyyaml", specifier = ">=6.0" },
 ]
 provides-extras = ["torrent"]