feat(extensions): select exact catalog releases

Keep current release metadata compatible with existing catalogs while allowing trusted catalogs to publish historical release URLs and digests. Add exact-version CLI selection, archive identity checks, tests, and documentation.

Refs #4719; follows up #4712.

Signed-off-by: 李永祺 <doribelove@gmail.com>

Author: Doribelove

docs/reference/extensions.md

@@ -26,11 +26,19 @@ specify extension add <name>
 | --------------- | -------------------------------------------------------- |
 | `--dev`         | Install from a local directory (for development)         |
 | `--from <url>`  | Install from a custom URL instead of the catalog         |
+| `--version <v>` | Install an exact version advertised by a catalog        |
 | `--force`       | Overwrite if the extension is already installed          |
 | `--priority <N>`| Resolution priority (default: 10; lower = higher precedence) |
 
 Installs an extension from the catalog, a URL, or a local directory. Extension commands are automatically registered with the currently installed AI coding agent integration.
 
+An unqualified catalog install still selects the advertised current version.
+`--version` uses only the winning catalog source for that extension ID; it does
+not fall back to a lower-priority source when the requested version is absent.
+Discovery-only catalogs remain non-installable. `--version` cannot be combined
+with `--dev` or the direct-URL `--from` option. The downloaded archive's extension
+ID and version are checked before installation.
+
 > **Note:** All extension commands require a project already initialized with `specify init`.
 
 ## Remove an Extension
@@ -79,9 +87,43 @@ including for help, the existing human-readable behavior is unchanged.
 
 ```bash
 specify extension info <name>
+specify extension info <name> --versions
 ```
 
 Shows detailed information about an installed or available extension, including its description, version, commands, and configuration.
+`--versions` lists the current and historical versions advertised by the
+winning catalog source; it labels discovery-only sources as non-installable.
+
+Catalogs may keep the current release in the existing top-level fields and add
+historical releases in a `releases` mapping. Older single-version catalogs
+continue to work unchanged. Each historical release needs its own download URL
+and SHA-256 digest; release-specific requirements or provided capabilities must
+be placed in that release's record rather than inherited from the current one.
+
+```json
+{
+  "extensions": {
+    "my-extension": {
+      "name": "My Extension",
+      "version": "0.5.1",
+      "download_url": "https://example.com/my-extension-0.5.1.zip",
+      "sha256": "<64-character SHA-256 for 0.5.1>",
+      "releases": {
+        "0.4.12": {
+          "download_url": "https://example.com/my-extension-0.4.12.zip",
+          "sha256": "<64-character SHA-256 for 0.4.12>"
+        }
+      }
+    }
+  }
+}
+```
+
+The example omits other catalog metadata for brevity. The current version must
+not be repeated in `releases`; malformed or duplicate release records are
+rejected. Bundle pins still use the current catalog resolution path until the
+separate bundle work described in [#4719](https://github.com/github/spec-kit/issues/4719)
+adds exact-version component lookup.
 
 ## Update Extensions
 

src/specify_cli/extensions/__init__.py

@@ -2722,6 +2722,8 @@ def install_from_archive(
         source_name: str | None = None,
         content_type: str | None = None,
         catalog_name: str | None = None,
+        expected_id: str | None = None,
+        expected_version: str | None = None,
     ) -> ExtensionManifest:
         """Install an extension from a supported archive.
 
@@ -2771,6 +2773,23 @@ def install_from_archive(
             if not manifest_path.exists():
                 raise ValidationError("No extension.yml found in archive")
 
+            if expected_id is not None or expected_version is not None:
+                archive_manifest = ExtensionManifest(manifest_path)
+                if expected_id is not None and archive_manifest.id != expected_id:
+                    raise ValidationError(
+                        f"Downloaded extension declares ID '{archive_manifest.id}', "
+                        f"expected '{expected_id}'."
+                    )
+                if (
+                    expected_version is not None
+                    and pkg_version.Version(archive_manifest.version)
+                    != pkg_version.Version(expected_version)
+                ):
+                    raise ValidationError(
+                        f"Downloaded extension '{archive_manifest.id}' declares version "
+                        f"{archive_manifest.version}, expected {expected_version}."
+                    )
+
             # Install from extracted directory
             return self.install_from_directory(
                 extension_dir,
@@ -2934,6 +2953,8 @@ def install_from_zip(
         source_name: str | None = None,
         content_type: str | None = None,
         catalog_name: str | None = None,
+        expected_id: str | None = None,
+        expected_version: str | None = None,
     ) -> ExtensionManifest:
         """Backward-compatible wrapper for archive installation."""
         return self.install_from_archive(
@@ -2945,6 +2966,8 @@ def install_from_zip(
             source_name=source_name,
             content_type=content_type,
             catalog_name=catalog_name,
+            expected_id=expected_id,
+            expected_version=expected_version,
         )
 
     def remove(self, extension_id: str, keep_config: bool = False) -> bool:
@@ -4336,13 +4359,16 @@ def search(
 
         return results
 
-    def get_extension_info(self, extension_id: str) -> Optional[Dict[str, Any]]:
+    def get_extension_info(
+        self, extension_id: str, version: str | None = None
+    ) -> Optional[Dict[str, Any]]:
         """Get detailed information about a specific extension.
 
         Searches all active catalogs in priority order.
 
         Args:
             extension_id: ID of the extension
+            version: Exact catalog version, or ``None`` for the advertised current release
 
         Returns:
             Extension metadata (annotated with ``_catalog_name`` and
@@ -4351,9 +4377,20 @@ def get_extension_info(self, extension_id: str) -> Optional[Dict[str, Any]]:
         all_extensions = self._get_merged_extensions()
         for ext_data in all_extensions:
             if ext_data["id"] == extension_id:
-                return ext_data
+                from ._catalog_versions import select_release
+
+                return select_release(ext_data, version)
         return None
 
+    def get_extension_versions(self, extension_id: str) -> list[str]:
+        """List versions advertised by the winning catalog source."""
+        from ._catalog_versions import available_versions
+
+        for ext_data in self._get_merged_extensions():
+            if ext_data["id"] == extension_id:
+                return available_versions(ext_data)
+        return []
+
     def download_extension(
         self, extension_id: str, target_dir: Optional[Path] = None
     ) -> Path:
@@ -4369,13 +4406,30 @@ def download_extension(
         Raises:
             ExtensionError: If extension not found or download fails
         """
-        import urllib.error
-
         # Get extension info from catalog
         ext_info = self.get_extension_info(extension_id)
         if not ext_info:
             raise ExtensionError(f"Extension '{extension_id}' not found in catalog")
 
+        return self.download_extension_info(ext_info, target_dir=target_dir)
+
+    def download_extension_info(
+        self, ext_info: Dict[str, Any], target_dir: Optional[Path] = None
+    ) -> Path:
+        """Download a selected release without looking up its ID again.
+
+        Exact-version callers pass the already-selected record so a catalog
+        change between lookup and download cannot substitute the current URL.
+        """
+        import urllib.error
+
+        extension_id = ext_info["id"]
+        if not ext_info.get("_install_allowed", True):
+            raise ExtensionError(
+                f"Extension '{extension_id}' is from a discovery-only catalog; "
+                "installation is not allowed."
+            )
+
         # Bundled extensions without a download URL must be installed locally
         if ext_info.get("bundled") and not ext_info.get("download_url"):
             raise ExtensionError(

src/specify_cli/extensions/_catalog_versions.py

@@ -0,0 +1,135 @@
+"""Exact-version selection for extension catalog entries.
+
+Legacy entries advertise one release at the top level. A versioned entry keeps
+that current release unchanged for older clients and adds historical releases
+under ``releases``. Historical records must carry their own URL and digest; a
+new current release must never supply either for an older version by accident.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from packaging.version import InvalidVersion, Version
+
+from . import ExtensionError
+
+_SHA256 = re.compile(r"^[0-9a-fA-F]{64}$")
+_CURRENT_ONLY = frozenset(
+    {
+        "version",
+        "download_url",
+        "sha256",
+        "requires",
+        "provides",
+        "bundled",
+        "verified",
+        "releases",
+    }
+)
+
+
+def _validated_releases(entry: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Return a checked history, or reject an ambiguous catalog entry."""
+    if "releases" not in entry:
+        return {}
+    releases = entry["releases"]
+    extension_id = entry.get("id", "<unknown>")
+    if not isinstance(releases, dict):
+        raise ExtensionError(
+            f"Extension '{extension_id}' has an invalid releases mapping."
+        )
+
+    current = entry.get("version")
+    if not isinstance(current, str) or not current.strip():
+        raise ExtensionError(
+            f"Extension '{extension_id}' has releases but no current version."
+        )
+    try:
+        normalized_current = Version(current)
+    except InvalidVersion:
+        raise ExtensionError(
+            f"Extension '{extension_id}' has an invalid current version '{current}'."
+        ) from None
+
+    seen = {normalized_current}
+    for release_version, record in releases.items():
+        if not isinstance(release_version, str) or not release_version.strip():
+            raise ExtensionError(
+                f"Extension '{extension_id}' has an invalid release version key."
+            )
+        try:
+            normalized = Version(release_version)
+        except InvalidVersion:
+            raise ExtensionError(
+                f"Extension '{extension_id}' has invalid release version '{release_version}'."
+            ) from None
+        if normalized in seen:
+            raise ExtensionError(
+                f"Extension '{extension_id}' repeats release version '{release_version}'."
+            )
+        seen.add(normalized)
+        if not isinstance(record, dict):
+            raise ExtensionError(
+                f"Extension '{extension_id}' release '{release_version}' must be an object."
+            )
+        if any(
+            key in record
+            for key in (
+                "id",
+                "version",
+                "releases",
+                "_catalog_name",
+                "_install_allowed",
+            )
+        ):
+            raise ExtensionError(
+                f"Extension '{extension_id}' release '{release_version}' contains reserved fields."
+            )
+        if (
+            not isinstance(record.get("download_url"), str)
+            or not record["download_url"].strip()
+        ):
+            raise ExtensionError(
+                f"Extension '{extension_id}' release '{release_version}' needs a download_url."
+            )
+        if not isinstance(record.get("sha256"), str) or not _SHA256.fullmatch(
+            record["sha256"]
+        ):
+            raise ExtensionError(
+                f"Extension '{extension_id}' release '{release_version}' needs a SHA-256 digest."
+            )
+        for field in ("requires", "provides"):
+            if field in record and not isinstance(record[field], dict):
+                raise ExtensionError(
+                    f"Extension '{extension_id}' release '{release_version}' has invalid {field}."
+                )
+
+    return releases
+
+
+def select_release(entry: dict[str, Any], version: str | None) -> dict[str, Any] | None:
+    """Select from the winning catalog entry without consulting lower sources.
+
+    ``None`` is returned when the requested version is absent. Callers can then
+    report a missing historical release without falling through to another
+    catalog or silently substituting the current release.
+    """
+    releases = _validated_releases(entry)
+    if version is None or version == entry.get("version"):
+        return entry
+    record = releases.get(version)
+    if record is None:
+        return None
+    common = {key: value for key, value in entry.items() if key not in _CURRENT_ONLY}
+    return {**common, **record, "version": version}
+
+
+def available_versions(entry: dict[str, Any]) -> list[str]:
+    """Current version first, then historical versions in descending order."""
+    releases = _validated_releases(entry)
+    current = entry.get("version")
+    if not isinstance(current, str) or not current:
+        return []
+    return [current, *sorted(releases, key=Version, reverse=True)]