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 selection, archive identity and discovery-policy checks, tests, and
documentation.

Refs #4719; follows up #4712.

Assisted-by: OpenAI Codex (model: GPT-6, autonomous)
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)]